Nome:     HTTX
Versione: 1.1b - 21 Gennaio 1997
Autore:   Gabriele Favrin
          (E-Mail:  gfavrin@mbox.vol.it / FidoNet:  2:333/726.8)



Indice:

  1.  Condizioni di utilizzo
  2.  Proprieta` di HTTX e condizioni di distribuzione
  3.  Introduzione
  4.  Richieste hardware e installazione
  5.  Utilizzo
  6.  Messaggi di errore e RC AmigaDOS
  7.  FAQ (consigli, interfacciamento ad altri programmi, etc).
  8.  Informazioni tecniche
  9.  Contattare l'autore (bug report, suggerimenti, etc)
 10.  Ringraziamenti
 11.  Storia del programma
 12.  Versioni future



-----------------------------------------------------------------------------

                              *** CHILDWARE ***

Questo  programma e` "CHILDWARE".  L'autore chiede espressamente che chiunque
utilizza  HTTX effettui una donazione ad un ente benefico che opera in favore
dei bambini, in qualunque forma o modo.

Se  non  ne  conoscete  rivolgetevi  all'ufficio  postale della vostra zona e
chiedete informazioni su come effettuare un versamento a favore dell'Unicef.

L'entita` della donazione e` libera, ma fatela!

-----------------------------------------------------------------------------



1.  Condizioni di utilizzo
--------------------------

Prima  di  utilizzare  HTTX  leggere  attentamente  quanto segue e proseguire
soltanto se ci si trova pienamente daccordo.

L'AUTORE  DI  HTTX  NON  SI  ASSUME NE` HA ALCUNA RESPONSABILITA` PER I DANNI
MORALI  E/O MATERIALI CHE L'UTILIZZO DEL SUO PROGRAMMA PUO` CAUSARE A PERSONE
E/O  COSE.   IL  PROGRAMMATORE SI E` IMPEGNATO A LIMITARE I PROBLEMI CHE HTTX
PUO`  CREARE  MA  NON  E`  IN  GRADO  DI  GARANTIRNE L'EFFICIENZA IN TUTTE LE
SITUAZIONI.   UTILIZZANDO  HTTX L'UTENTE SI ASSUME *TUTTE* LE RESPONSABILITA`
MORALI, MATERIALI E LEGALI DEL CASO.


ATTENZIONE:

Molti  documenti HTML sono Copyright e non liberamente distribuibili, nemmeno
se  convertiti  in  formato testo.  L'autore declina ogni responsabilita` per
l'utilizzo che verra` fatto dei files generati da HTTX.



2.  Proprieta` di HTTX e condizioni di distribuzione
----------------------------------------------------

L'eseguibile,  il  sorgente e le idee alla sua base sono PROPRIETA` ESCLUSIVA
di Gabriele Favrin.  Tutti i diritti sono riservati.

HTTX  e` freeware, NON pubblico dominio.  Puo` essere diffuso a patto che ne`
l'eseguibile,  ne`  la  documentazione  vengano  in  alcun modo alterati.  e`
consentita   l'archiviazione   con   programmi  diversi  da  LhA  ma  non  la
compressione dei singoli file con PowerPacker o tools simili.

L'inserimento di HTTX o di sue parti in cover-disk di riviste e` consentito a
patto che venga preventivamente chiesta esplicita autorizzazione all'autore.

L'utilizzo  commerciale  di  questo  pacchetto e` consentito esclusivamente a
AmiTrix ed Yvon Rozijn (AWeb).

Gli  staff  di  Aminet  e  Fred  Fish sono autorizzati ad inserire HTTX nelle
rispettive raccolte di software Pubblico Dominio.



3.  Introduzione
----------------

HTTX (HTml > TXt) e` un programma atto a convertire il formato HTML,
utilizzato per la visualizzazione di files nel World Wide Web, in ASCII puro.
Esistono prodotti analoghi ma poiche` nessuno soddisfaceva pienamente le mie
necessita` ho deciso di creare HTTX.

Non dico che sia il migliore o il piu` veloce (anzi...) ma certamente ha
qualche funzione finora inedita su Amiga.

Ps:  ...e anche HTTX e` un bel nome!  :-)



4.  Richieste hardware e installazione
--------------------------------------

Sistema richiesto:
Amiga, 512K, Kickstart 2.04 (37.175) o superiore.

Occupazione in memoria:
La dimensione del file da convertire e circa 10k di buffer.

Installazione:
Copiare HTTX nella directory C: o comunque nel path corrente.

Nota:  leggere AWeb/httxrx.readme(.html) per l'utilizzo con l'interfaccia
       ARexx di AWeb.



5.  Utilizzo
------------

HTTX va lanciato ESCLUSIVAMENTE da Shell.

Sintassi:

HTTX input [output] [opzioni]

I parametri fra parentesi quadre sono opzionali, e` richiesto esclusivamente
il nome del file da convertire ("input").

Qualora non venga indicato un nome per il salvataggio, sara` utilizzata la
convenzione "NomeFile.txt" (es.:  test.html verra` salvato come
test.html.txt).

Le altre opzioni disponibili sono:


LEN
   lunghezza massima delle linee nel file convertito.

   Default:  77  Minimo:  15  Massimo:  255


INDENT o IN
   Dimensione dell'indentazione (giustificazione a destra) per le liste <UL>
   e <DL>.  Il valore massimo deve consentire almeno due livelli di
   indentazione relativamente alla lunghezza (LEN) impostata.

   Default:  3   Minimo:  1


ANSI o AN
   Conversione in ANSI degli stili HTML e dei LINK (HREF e NAME).

   Default:  disattivo (gli stili non vengono convertiti)


7BIT
   Conversione in sequenze di caratteri ASCII minori di 128 delle entities
   HTML (lettere accentate, etc).  Fondamentale per il forward di testi in
   reti come FidoNet ove i caratteri ammessi vanno da 32 a 127.

   ATTENZIONE:  l'opzione ANSI comunque aggiunge i codici ESC (ASCII 27)
   proibiti in Fidonet!

   Default:  disattivo (i caratteri 8bit non vengono convertiti)


NOHR
   Disattivazione inserimento linee <HR>.  Utile per risparmiare caratteri.

   Default:  disattivo (le linee vengono inserite)


FILENOTE o FN
   Salvataggio del titolo (<TITLE>) del documento come commento al file.

   Default:  disattivo (il titolo viene inserito nel file)


SITE
   Aggiunta al file generato dell'URL specificato.  Utile soprattutto
   utilizzando lo script di conversione per AWeb.

   Esempio:
   HTTX ram:file.html SITE=http://www.uncicef.org

   All'inizio del file convertito comparira` la stringa
   "URL  : http://www.unicef.org"

   Nota:  l'opzione ha priorita` su GETNOTE, quindi specificando
   un sito questo verra` utilizzato anche se la suddetta e` attiva.

   Default:  omettendo l'opzione e relativo sito nulla viene aggiunto.


GETNOTE o GN
   Utilizzo del commento del file da convertire come URL.
   L'opzione sostituisce SITE ed e` utilizzabile con i file salvati
   dal browser AWeb e da tutti i programmi che memorizzano l'URL nel
   commento.

   Default:  attivo (l'URL viene preso dal commento del file, se presente)


NOHEADER o NOHEAD
   Soppressione inserimento titolo (<TITLE>) e URL nel file convertito.
   Qualora indicata l'opzione annulla SITE/GETNOTE, se presenti.

   Default:  disattivo (titolo e URL possono essere aggiunti)


HREF o LINK
   Inserimento nel file degli <HREF> (esclusi <A NAME> e LINK locali).

   Default:  disattivo (gli HREF non vengono aggiunti)


IMG
   Inserimento nel file dell'ALT-Text delle <IMG>.

   Default:  attivo (l'ALT-Text viene aggiunto)


BADHTML o BAD
   Supporto (parziale) per documenti realizzati al di fuori degli standard
   HTML.  Da utilizzare solo qualora la pagina convertita risulti mancante di
   parti di testo poiche` con documenti corretti si possono avere problemi.

   Default:  disattivo (HTTX utilizza le regole DTD standard)


FORCE
   Effettua la conversione del file di input senza controllare se si tratta
   di un documento HTML.
   L'UTILIZZO e` A PROPRIO RISCHIO:  la conversione di file di testo o binari
   puo` portare ad effetti imprevisti.

   Normalmente HTTX considera valido un file HTML quando si verifica una
   di queste condizioni:

   - estensione .html o .htm
   - tag iniziale <HTML>
   - tag iniziale <!DOCTYPE ...>

   L'opzione si rende necessaria se il file non risponde a queste
   caratteristiche pur essendo un documento HTML.

   Default:  disattivo (il controllo viene effettuato)


STDIO
   Visualizzazione del file convertito su video invece che su file.
   L'opzione attiva automaticamente QUIET.

   Default:  disattivo (il documento viene salvato su file)


QUIET
   Soppressione dei messaggi a video di HTTX.  L'opzione si rivela utile se
   il programma e` utilizzato all'interno di script.

   ATTENZIONE:  viene disabilitata anche la visualizzazione dei messaggi
   d'errore.  Restano pero` attivi i codici d'errore AmigaDOS.

   Default:  disattivo (l'output di HTTX viene visualizzato)


Se non specificati, sono utilizzati i settaggi di default.

Al termine della conversione vengono visualizzate:

- dimensione dei file di input e di output,
- eventuale presenza di caratteri a 8bit (e, se attiva, loro conversione)
- eventuale presenza di TAB o caratteri ASCII minori di 32 non convertiti in
  quanto inclusi in testo preformattato.



6.  Messaggi di errore e RC AmigaDOS
------------------------------------

Al termine dell'esecuzione HTTX genera l'appropriato codice d'errore (RC)
AmigaDOS, utilizzabile all'interno di script per determinare l'esito della
conversione.  Per la lista completa dei codici si rinvia al manuale AmigaDOS.

Nota:  nel caso di documenti non HTML viene utilizzato l'RC 212 (l'oggetto
non e` del tipo richiesto).

Inoltre, se l'opzione QUIET non e` utilizzata, in caso di errore vengono
visualizzati i seguenti messaggi:


Bad Args
   Gli argomenti inseriti sono errati.

Break, output deleted
   La conversione e` stata interrotta con la sequenza Control-C ed il file
   di output e` stato rimosso.

Not enough memory
   Non c'e` sufficiente memoria libera per allocare i buffer utilizzati da
   HTTX.

Input file not found
   Il file indicato non esiste o non e` accessibile.

Can't open output file
   Non e` possibile aprire il file di salvataggio.
   Possibile causa:  il device di destinazione e` protetto dalla scrittura.

Can't read from input
   Non e` possibile leggere dal file di input.
   Possibile causa:  file protetto dalla lettura o danneggiato.

Can't write to output
   Non e` possibile scrivere sul file di output.
   Possibile causa:  il device di destinazione e` protetto dalla scrittura,
   pieno oppure danneggiato.

Not a valid HTML file
   Il file che si vuole convertire non e` in formato HTML.
   Se si ritiene che lo sia utilizzare l'opzione FORCE.

The line length must be within 15 and 255 characters
   La dimensione di linea inserita e` maggiore di 255 o minore di 15
   caratteri.

Length of indent must be at least 1
   La dimensione dell'indentazione dev'essere almeno di un carattere.

With line length NN and indent size NN,
maximum indent level is less than 3.
   Il massimo livello di indentazione, relativamente alla lunghezza linea e
   all'indentazione impostata, e` minore di 3.



7.  FAQ (consigli, interfacciamento ad altri programmi, etc)
------------------------------------------------------------

Q. "HTTX mi sembra un po` lento..."
A. In questa versione sono stati fatti progressi.  E` comunque sempre
   possibile migliorare le prestazioni operando su file system con blocchi di
   1024 bytes, come ad esempio il Ram Disk.

Q. "La pagina XXX non viene convertita correttamente..."
A. Le ragioni possono essere diverse:  layout basato su tabelle (attualmente
   non supportate, si veda paragrafo 8), errori nel sorgente HTML (HTTX e`
   abbastanza tollerante, ma ci sono dei limiti) oppure errori nell'engine di
   HTTX stesso.  Se ritenete che la pagina sia corretta, segnalatemene l'URL.
   (E-Mail: gfavrin@mbox.vol.it, FidoNet: 2:333/726.8)

Q. "Posso utilizzare HTTX direttamente da AWeb o Directory Opus?"
A. Per quanto riguarda AWeb, gli utenti della versione 1.2b o superiore
   possono utilizzare lo script ARexx fornito.

   HTTX puo` essere utilizzato anche da Directory Opus creando un bottone
   configurato come segue (esempio relativo alla versione 4):

   Comando: C:HTTX {f}
   Flags:   CD source
            Do all files
            Output window
            Rescan source

   In questo modo si potranno convertire anche piu` files alla volta:
   bastera` selezionarli e invocare HTTX.

   Directory Opus e` un marchio registrato della Inovatronics.



8.  Informazioni tecniche
-------------------------

Questa sezione affronta alcune tematiche relative allo standard HTML ed alla
sua implementazione in HTTX.  La sua lettura comunque non e` fondamentale per
imparare ad utilizzare il programma.


Cosa e` supportato:

 - le entities descritte nel RFC 1866 piu` &copy; e &reg; (NHTML).
 - i separatori (<BR>, <P> e <HR>) e il cambio larghezza font (<H1...H6>).
 - gli stili fisici e logici.
 - liste numerate (<OL>) e non (<UL>) e liste di definizioni (<DL>)
   fino a un massimo di 255.
 - il titolo del documento (<TITLE>).
 - i link (<HREF>) e le inline-image (<IMG> con eventuale ALT-text).
 - il testo preformattato (<PRE>).
 - l'utilizzo non standard di "<" e ">" in un testo preformattato.
   (suscettibile di cambiamenti).

Cosa non e` supportato:

 - le tabelle (<TABLE>), dei cui testi e` comunque stata migliorata la
   leggibilita` in questa versione.
 - <CENTER>, <HR SIZE>, <UL/OL TYPE> e in generale le estensioni NHTML.

Queste TAG verranno probabilmente implementate nelle prossime versioni di
HTTX.

 - la conversione delle entities in stili gestibili da Spot, Mail Manager,
   etc.  Ci avevo pensato ma il numero di caratteri richiesto anche per una
   sola linea in Bold e` troppo alto (ogni parola andrebbe preceduta e
   seguita da "*").
 - <SCRIPT> e <APPLET>:  non potendoli gestire vengono skippati.

Implementazione dello standard:

 - TAG sconosciute vengono ignorate.
 - doppi spazi, spazi a inizio e fine riga vengono eliminati,
 - caratteri non ASCII (< 32) vengono convertiti in spazi.
 - EOL PC (CR+LF) e Mac (CR) vengono convertiti nel formato Amiga (LF).
 - per maggiore leggibilita` le TAG <CENTER> e <TR> vengono trasformate in
   EOL; la tag <TH> in spazio.
 - EOL consecutivi vengono ridotti ad uno (fatta eccezione per <BR>).



9.  Contattare l'autore
-----------------------

Oltre a consigli, segnalazioni di bug, problemi, e` gradito un messaggio di
commento da chiunque utilizzi HTTX, oltre che naturalmente segnalazioni di
azioni in favore di enti che si occupano di bambini (vedi "CHILDWARE").

E-Mail:   gfavrin@mbox.vol.it
FidoNet:  2:333/726.8

Per favore scrivete in italiano o in inglese.

Pagina di supporto per HTTX:
http://www.logicom.it/personal/poing/httx/



10.  Ringraziamenti
-------------------

Fabio Belli           zak@anturio.com
Documentazione in inglese

Claudio Mazzuco       kirk@maya.dei.unipd.it
Beta testing

Giuseppe Ammendolia   ryuga@freenet.hut.fi
Beta testing

Giuseppe Sacco        N/A
Beta testing

Paul Kolenbrander     paul@serena.IAEhv.nl
Beta testing

Andrea Modenese       bigmod@freenet.hut.fi
Che e` stato un grande boss negli ultimi tre anni.  Grazie di tutto, Andrea!

Yvon Rozijn           yrozijn@xs4all.nl
Per lo splendido AWeb, i commenti entustiastici su HTTX e per averlo voluto
nella versione commerciale di AWeb!

Dale Currie           dalec@zorro.amitrix.com
Per il piacevole e produttivo scambio di E-Mail e la sensazione di "far parte
del progetto" che mi ha saputo trasmettere!

William Parker        wparker@bill.amitrix.com
Beta testing a aiuto

Un ringraziamento speciale a chi mi ha scritto a proposito di HTTX e a chi lo
utilizza!



11.  Storia del programma
-------------------------

V1.0
   Prima versione pubblica.

V1.1  
  +migliorata la velocita`.
  +aggiunte le opzioni STDIO, QUIET, BADHTML, NOHEADER, GETNOTE.
  +aggiunto il supporto per i codici d'errore Amigados.
  +aggiunto il supporto per le tag <ADDRESS> e <LISTING>.
  +modificata la gestione di <BR> e <LI> in ottemperanza all'implementazione
   nello standard HTML 3.2.
  +riscritta la gestione delle entities:  ora vengono convertite anche se non
   chiuse da ";".
  +estesa la conversione a 7bit, ora piu` veloce, completa (vengono
   convertiti quasi tutte i caratteri) e accurata (non vengono lasciati
   accenti in mezzo alle parole, ad esempio "httx è bello" diventa
   "httx e` bello" mentre "Belphégor" diverra` "Belphegor".
  +a grande richiesta impostata come disattiva per default l'opzione 7BIT.
  +migliorato il supporto per commenti multilinea e sorgenti HTML non
   standard.
  +aggiunto il supporto per tag e alt-text contenenti LF o "<" e ">".
  -corretti diversi piccoli bug estetici nella conversione (doppi spazi in
   alcune circostanze, spurie all'uscita da <PRE> e <SCRIPT> e altro).
  -corretto un errore che poteva portare al lock del file da convertire.
  -corretto un errore in FILENOTE.

V1.1a
  -corretto uno stupido e raro bug nella gestione delle tag.
  -corretta la gestione degli EOL MAC.

V1.1b
  -corretta l'interpretazione di alcune entities.



12.  Versioni future
--------------------

HTTX  e`  un programma in continuo sviluppo, se non altro perche` lo utilizzo
quotidianamente e ne rilevo quindi mancanze o possibili migliorie.

Al momento sto alacremente lavorando su una nuova versione che conterra`
importanti innovazioni.



-----------------------------------------------------------------------------

                              *** CHILDWARE ***

Questo  programma e` "CHILDWARE".  L'autore chiede espressamente che chiunque
utilizza  HTTX effettui una donazione ad un ente benefico che opera in favore
dei bambini, in qualunque forma o modo.

Se  non  ne  conoscete  rivolgetevi  all'ufficio  postale della vostra zona e
chiedete informazioni su come effettuare un versamento a favore dell'Unicef.

L'entita` della donazione e` libera, ma fatela!

-----------------------------------------------------------------------------