HTTX Convertitore da HTML a testo Creato da Gabriele Favrin (E-Mail: favrin@tin.it - FidoNet: 2:333/726.8) Versione 2.0b - Dicembre 1999 Indice: 1. Condizioni di utilizzo 2. Proprieta' di HTTX e condizioni di distribuzione 3. Introduzione 4. Richieste hardware e installazione 5. Utilizzo 5.1 Opzioni nella linea di comando 5.2 Configurazione esterna 6. Messaggi di errore e codici di ritorno AmigaDOS 7. FAQ (consigli, interfacciamento ad altri programmi, etc) 8. Informazioni tecniche 8.1 Cosa e' supportato, cosa non lo e' (ancora) e implementazione dello standard. 8.2 Note sulla conversione ANSI 8.3 Note sulla conversione dei contenuti di 
, , <LISTING> e      
         <SCRIPT>.
  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 file generati da HTTX.


Tutti  i  programmi citati in questo documento sono proprieta' dei rispettivi
autori e produttori.



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 in formati diversi da LhA ma non la compressione
dei singoli file con PowerPacker o tool simililari.

L'utilizzo commerciale di questo pacchetto e' consentito esclusivamente ad
AmiTrix che puo' offrirlo a terzi assieme ad edizioni complete o parziali del
browser WWW AWeb.

Gli staff di Aminet, Fred Fish, Meeting Pearls, Amy Resource e delle riviste
Amiga con CD o disco allegato sono esplicitamente 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 file nel World Wide Web e per la
documentazione di diversi programmi, 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, ma
certamente introduce diverse funzioni finora inedite nei programmi similari
per Amiga.



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

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

Occupazione in memoria:
La dimensione del file da convertire e circa 15k fra buffer e altro.

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

HTTX e' compatibile con AmigaOS 3.5 e l'emulatore U.A.E.



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

HTTX puo' essere utilizzato esclusivamente da Shell. Gli utenti di AWeb
possono comunque utilizzare lo speciale plugin ARexx incluso nell'archivio e
che consente il pieno controllo del programma dal browser. Si raccomanda
inoltre la lettura del paragrafo 7.

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). Se come output e' indicato un path il file convertito secondo
la convenzione sopra riportata verra' salvato in detta directory.

Alcuni esempi:

-> HTTX data:txt/html/abox.html

Il file "abox.html" viene convertito e salvato
come "data:txt/html/abox.txt"

-> HTTX data:txt/html/abox.html ram:abox.txt

Il file "abox.html" viene convertito e salvato
come "ram:abox.txt"

-> HTTX data:txt/html/abox.html data:txt/

Il file "abox.html" viene convertito e salvato
come "data:txt/abox.txt"



5.1 Opzioni nella linea di comando
----------------------------------

HTTX offre numrose opzioni per il controllo della conversione.


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>,
   <OL> e <DL>. Il valore massimo deve consentire almeno due livelli di
   indentazione relativamente alla lunghezza (LEN) impostata.

   Default: 3 - Minimo: 1 - Massimo: il valore di (LEN - 10) / 3


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

   Da non utilizzare se il testo convertito deve essere inserito in aree
   messaggi FidoNet o newsgroup Usenet.

   Leggere il paragrafo 8.2 (note sulla conversione ANSI) per informazioni
   importanti sui codici ANSI utilizzati ed i possibili problemi di
   compatibilita'.

   L'opzione supporta i seguenti valori:

   ANSIMODE=0
      I codici ANSI non vengono utilizzati. Equivale a non specificare
      l'opzione ne' in linea di comando ne' nella configurazione.

   ANSIMODE=1
      Vengono utilizzati esclusivamente codici ANSI standard. Questa
      modalita' di conversione ANSI e' l'unica disponibile in fase di stampa.

   ANSIMODE=2
      Vengono utilizzate le sequenze di posizionamento cursore VT100 che
      riducono la dimensione del file convertito comprimendo gli spazi ma
      possono risultare incompatibili con alcuni programmi (vedere il
      paragrafo 8.2).

   Default: ANSIMODE=0 (stili e link non vengono convertiti).


ANSICOL
   Colore utilizzato per visualizzare i link durante la conversione ANSI.
   I valori accettati vanno da 0 a 9. Il colore visualizzato puo' variare da
   terminale a terminale.

   Default: 3 (conversione e salvataggio) e 4 (stampa).


7BIT
   Conversione in sequenze di caratteri ASCII minori di 128 delle entita'
   HTML (lettere accentate, etc). Fondamentale per l'inserimento di testi in
   reti come FidoNet dove i caratteri ammessi vanno da 32 a 127.

   ATTENZIONE:  tenere presente che l'opzione ANSI aggiunge i codici ESC
   (ASCII 27) proibiti in FidoNet e fortemente sconsigliati per un uso non
   personale (diffusione) del testo convertito.

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


HRMODE o HR
   I documenti HTML spesso contengono l'elemento HTML <HR> che definisce una
   linea di separazione fra i paragrafi. HTTX consente di gestire queste
   linee in diversi modi:

   HRMODE=0
      Le linee non vengono tracciate.
      Equivale all'opzione NOHR delle versioni di HTTX precedenti alla 1.5.

   HRMODE=1
      Le linee vengono tracciate utilizzando il carattere "-".

   HRMODE=2
      Le linee vengono tracciate utilizzando spazi sottolineati (in ANSI).
      In questo modo si ottiene un tratto continuo molto piu' gradevole
      esteticamente.

      Di contro questa soluzione introduce nel documento codici ANSI da
      evitare assolutamente quando il testo e' destinato al forward su
      conferenze echo FidoNet o Newsgroup Usenet.

   Default: HRMODE=1 (le linee vengono tracciate utilizzando il
            carattere "-" ).


NOALIGN o NA
   HTTX supporta l'allineamento (a destra o centrale) di testi e separatori
   (<HR>).

   Esempi (riferiti a una linea a 77 colonne):

                               testo centrato
                                                     testo allineato a destra

   Con l'opzione NOALIGN attiva entrambe le linee sarebbero poste all'inizio,
   con evidente risparmio di caratteri.

   Default: disattivo (l'eventuale allineamento e' supportato).


TDEOL
   Inserimento di un fine linea fra le celle di una tabella HTML. L'uso di
   questa opzione puo' migliorare la leggibilita' di alcune tabelle.

   Default: disattivo (fra le celle viene inserito uno spazio).


SETNOTE o SN
   Salvataggio del titolo del documento (elemento HTML <TITLE>) o
   dell'indirizzo del documento originale come commento del file convertito.
   L'opzione e' ovviamente ignorata in caso di stampa (opzione PRINT) o
   visualizzazione su console (opzione STDIO).

   L'opzione supporta i seguenti valori:

   SETNOTE=0
      Nessun commento viene salvato.

   SETNOTE=1
      Il titolo del documento, se presente, viene memorizzato come commento
      del file salvato. Vengono inseriti solo i primi 64 caratteri, come da
      standard HTML.

   SETNOTE=2
      L'URL del documento, se disponibile, viene memorizzato come commento
      del file salvato.

   Default: disattivo (nessun commento viene impostato).


SITE
   Aggiunta all'header del file convertito dell'URL specificato. Utile per
   ricordare da quale documento e' stato ottenuto il file.

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

   All'inizio del file convertito comparira' il testo
   "URL  : http://www.unicef.org"

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

   Default: disattivo (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 dei
   file salvati.

   La dimensione massima di un commento su AmigaDOS e' di 80 caratteri.

   Default: disattivo.


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

   Default: disattivo (la versione di HTTX ed eventuali titolo e URL
            vengono aggiunti).


HREF o LINK
   Inserimento nel file degli indirizzi dei link (elemento HTML <A>).
   Particolarmente utile se il documento da convertire contiene link che si
   vogliono conservare.

   Default: disattivo (i link non vengono aggiunti).


IMG
   Inserimento nel file dell'ALT-Text delle immagini (elemento HTML <IMG>).
   Utile se il documento contiene immagini con descrizioni
   esplicative.

   Default: disattivo (l'ALT-Text non viene aggiunto).


SCRIPT o SCP
   Inserimento nel file del contenuto dell'elemento <SCRIPT>, ad esempio
   script JavaScript.

   Attenzione: questa opzione inserisce lo script stesso, non il risultato
   della sua esecuzione!

   Leggere il paragrafo 8.3 per informazioni importanti sulla conversione di
   questo tipo di testo.

   Default: disattivo (il contenuto dell'elemento <SCRIPT> non viene
            aggiunto).


BADHTML o BAD
   Parziale supporto 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
   Conversione del file specificato senza controllare se si tratta realmente
   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 se si verificano una o
   piu' delle seguenti condizioni:

   - l'estensione del file e' ".html" o ".htm"
   - il primo elemento HTML e' <HTML>
   - il primo elemento HTML e' <!DOCTYPE ...>

   L'uso di questa opzione si rende necessario se il file non risponde a
   queste caratteristiche pur essendo un documento HTML.

   Default: disattivo (il controllo viene effettuato).


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

   Default: disattivo (il documento viene salvato su file).


PRINT o PRT
   Invio del documento alla stampante invece che a video o su file.

   Il printer.device si occupa di convertire i codici ANSI standard ed il
   fine linea in quelli utilizzati dalla stampante impostata con il
   programma "Printer" presente nel cassetto Prefs.

   Questa opzione va SEMPRE utilizzata qualora si intenda stampare il
   documento convertito. Se l'opzione ANSIMODE e' attiva il relativo valore
   verra' automaticamente impostato a 1 per l'utilizzo di codici ANSI
   standard. Inoltre, qualora non specificato, il valore di ANSICOL verra'
   impostato a 4 (come da specifiche Commodore relative al printer.device).

   Da evitare quindi la soluzione adottata in precedenti versioni di
   HTTX: "HTTX abox.html prt:"

   L'opzione attiva automaticamente QUIET e disattiva SETNOTE e STDIO.

   Default: disattivo (il documento viene salvato a video o su file).


APPEND
   Normalmente HTTX sovrascrive il file destinazione indicato, se gia'
   presente.

   Utilizzando APPEND il testo convertito viene invece aggiunto in coda al
   file specificato.

   Default: disattivo (il file destinazione, se gia' esistente, viene
            sovrascritto).


NOCFG
   HTTX per default carica la configurazione ENV:httx.prefs (se non
   diversamente specificato dall'opzione CFG). Con questa opzione HTTX
   utilizza solo le impostazioni di default o quelle inserite nella linea di
   comando.

   Per informazioni sulla configurazione esterna vedere il paragrafo 5.2.

   Default: disattivo (HTTX cerca la configurazione di default o quella
            specificata con l'opzione CFG).


CFG
   Con questa opzione e' possibile specificare il nome della configurazione
   utilizzata da HTTX. Tale file deve trovarsi nella directory ENV:

   L'opzione disattiva NOCFG.
   Per informazioni sulla configurazione esterna vedere il paragrafo 5.2.

   Default: disattivo (HTTX cerca di caricare la configurazione httx.prefs).


INCLUDE
   Con questa opzione e' possibile far precedere da un altro file di testo
   il documento HTML da convertire.

   Il file incluso NON VIENE MODIFICATO IN ALCUN MODO, compresi eventuali
   caratteri 8 bit, formattazione del testo, codici ANSI e via dicendo. HTTX
   non segnalera' se sono presenti caratteri 8 bit.

   Tenerne conto se il testo convertito deve essere inserito in conferenze
   echo FidoNet o Newsgroup Usenet.

   Default: disattivo (nessun testo viene aggiunto).


QUIET
   Soppressione dei messaggi a video di HTTX. L'opzione si rivela utile se
   il programma e' usato all'interno di uno 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 specificato diversamente vengono utilizzate le impostazioni di
default.

Al termine della conversione, se l'opzione QUIET non e' attiva, vengono
fornite le seguenti informazioni:

- dimensione dei file di input e output.
- eventuale presenza di caratteri a 8 bit (e se attiva, loro conversione a
  7 bit).
- eventuale presenza di TAB o caratteri ASCII minori di 32 non convertiti in
  quanto inclusi in testo preformattato.
- eventuale presenza di commenti HTML non conformi agli standard. Un
  commento HTML mal scritto puo' rendere invisibili intere parti del
  documento. Se il file convertito appare incompleto, provare ad utilizzare
  l'opzione BADHTML.



5.2 Configurazione esterna
--------------------------

HTTX supporta una configurazione esterna, ovvero un file di testo in cui e'
possibile inserire le opzioni utilizzate piu' frequentemente per non doverle
riscrivere ad ogni esecuzione.

Di default (a meno che sia specificata l'opzione NOCFG o che CFG non indichi
un file diverso) HTTX cerca il file "ENV:httx.prefs".

E' possibile utilizzare piu' configurazioni, ad esempio una per la
conversione su file ed una per la stampa, creando file differenti ed
utilizzando l'opzione "CFG nome file" (non e' necessario indicare ENV:).

Esempio:

-> HTTX abox.html

Converte il file "abox.html" utilizzando la configurazione di default
(ENV:httx.prefs).

-> HTTX abox.html PRINT CFG=httxprt.prefs

Converte il file "abox.html" utilizzando la configurazione contenuta nel
file ENV:httxprt.prefs



Parametri utilizzabili
----------------------

La configurazione esterna supporta un sottoinsieme delle opzioni disponibili
in linea di comando. Ogni opzione DEVE essere specificata nella forma estesa
(ad esempio HRMODE e non HR, INDENT e non IN, etc).

Il file non deve contenere altro se non le opzioni e gli eventuali parametri
relativi ad esse. E' consentito andare a capo per maggiore chiarezza in fase
di stesura.

I comandi disponibili, per la cui descrizione si rimanda al paragrafo 5.1,
sono i seguenti:

LEN      - dimensione massima delle linee.
INDENT   - dimensione dell'indentazione (giustificazione a destra).
ANSIMODE - modalita' di utilizzo dei codici ANSI nella conversione.
ANSICOL  - colore dei link nella conversione ANSI.
7BIT     - conversione a 7 bit delle entita' HTML 8 bit.
HRMODE   - modalita' tracciamento linee di separazione.
NOALIGN  - disattivazione allineamento (centrale o a destra) del testo.
TDEOL    - inserimento di un fine linea tra le celle di una tabella HTML.
SETNOTE  - salvataggio di titolo o URL del documento HTML come commento del
           file convertito.
GETNOTE  - utilizzo del commento al file originale come URL del file da
           convertire.
NOHEADER - omissione dell'instestazione (versione di HTTX, URL e titolo
           del documento originale) nel file convertito.
HREF     - inserimento dei link (elemento HTML <A>) nel file convertito.
IMG      - inserimento dell'ALT-Text delle immagini nel file convertito.
SCRIPT   - inserimento del contenuto dell'elemento <SCRIPT>.
BADHTML  - parziale supporto per HTML non conforme agli standard.

Gli argomenti in linea di comando hanno priorita' rispetto a quelli inseriti
nella configurazione esterna e funzionano come interruttori. Alcuni esempi:

Posta una configurazione esterna contenente:

IMG GETNOTE LEN=70

inserendo il comando:

-> HTTX abox.html IMG

si ottiene che IMG e' presente sia nella configurazione che lo attiva che
nella linea di comando che lo disattiva.

-> HTTX abox.html LEN=74

LEN e' presente nella configurazione esterna, ma viene preso il valore
impostato in linea di comando ovvero 74.



Creazione e modifica della configurazione
-----------------------------------------

I file di configurazione in effetti sono vere e proprie variabili di sistema
e si trovano nelle directory ENVARC: (su disco) ed ENV: (generalmente in
ram). Questa distribuzione consente di modificare le configurazioni anche in
maniera non permanente in quanto il contenuto di ENV: vale solo per la
sessione in corso e viene riportato ai contenuti di ENVARC: ad ogni
accensione o reset della macchina.

Di contro per salvare una configurazione in maniera permanente sara'
necessario copiare lo stesso file sia in ENV: che in ENVARC:

Utilizzare il proprio editor di testi preferito (per esempio Ed, Cygnus
Editor, GoldEd, etc) per creare il file il cui nome di default e' httx.prefs.
Salvarlo in ENV: ed ENVARC: in modo che non venga perso al reset successivo.
Modifiche temporanee possono essere effettuate operando sul file in ENV:

La configurazione di HTTX puo' essere interamente gestita utilizzando il
plugin per il browser WWW AWeb.



6. Messaggi di errore e codici di ritorno 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.

In caso di errore, se l'opzione QUIET non e' attiva, viene visualizzato anche
il messaggio AmigaDOS relativo.

Segue un elenco degli errori piu' frequenti e del loro significato. Da notare
che se il sistema e' localizzato i messaggi sono visualizzati nella lingua
impostata. Fare riferimento al manuale AmigaDOS per informazioni piu'
dettagliate.

Argument line invalid or too long
   Gli argomenti inseriti sono errati.

*** Break
   La conversione e' stata interrotta con la sequenza Control-C od il comando
   break ed il file di output e' stato cancellato.

Not enough memory available
   Non c'e' sufficiente memoria libera per allocare i buffer utilizzati da
   HTTX.
   Questa condizione puo' verificarsi qualora il file da convertire o quello
   da includere siano troppo grandi o la memoria risulti troppo frammentata.
   Provare a resettare Amiga.

Object not found
   Il file indicato non esiste o non e' accessibile.
   Verificare l'esattezza di nome e percorso del file.

Object is not of the required type
   Il file indicato non risulta essere in formato HTML.
   Se si ritiene che lo sia utilizzare l'opzione FORCE.


HTTX inoltre puo' visualizzare altri errori, in inglese, relativi all'errato
utilizzo di comandi od opzioni.

The line length must be between 15 and 255 characters (current is NN)
   La dimensione di linea inserita e' maggiore di 255 o minore di 15
   caratteri.

Indentation size must be at least 1 (current is NN)
   La dimensione dell'indentazione dev'essere almeno di un carattere.

With line length XX, indentation size YY, max indent level is ZZ.
You must allow at least 3 indentations.
   Il massimo livello di indentazione, relativamente alla lunghezza linea e
   all'indentazione impostata, e' minore di 3.

HRMODE value must be 0, 1 or 2
   Il valore impostato per l'opzione HRMODE non e' valido.
   Deve essere 0, 1 o 2.


Infine possono essere visualizzati degli avvertimenti (Warning) che non
precludono la conversione del documento ma possono indicare situazioni che
alterano il risultato finale:


Error in env config. HTTX will use its defaults.
   La configurazione esterna contiene un errore che ne ha impedito
   l'interpretazione. HTTX utilizzera' le impostazioni di default e gli
   eventuali argomenti inclusi nella linea di comando.

   Fare riferimento al paragrafo 5.2 per informazioni sul formato da
   utilizzare.

ENV config 'NAME' not found.
   La configurazione specificata con l'opzione CFG non e' stata trovata.
   HTTX utilizzera' le impostazioni di default e gli eventuali argomenti
   inseriti nella linea di comando.

   Il file di configurazione deve trovarsi in ENV:
   Ricordarsi di copiarlo in ENVARC: quando lo si crea per la prima volta o
   lo si modifica.

Found non-ASCII chars in preformatted text!
   In una sezione di testo non formattato sono stati trovati caratteri a
   8 bit. Tenerne conto se il testo convertito deve essere inserito in
   conferenze echo FidoNet o Newsgroup Usenet.

This file contains non standard HTML comment(s)!
   Il file potrebbe non essere stato completamente convertito in quanto
   sono stati trovati commenti HTML non standard. Se il file convertito
   appare incompleto, provare ad utilizzare l'opzione BADHTML.

Include file could not be added.
   Il file specificato con l'opzione INCLUDE non puo' essere aggiunto
   perche' non esiste o non e' accessibile.
   Verificare l'esattezza di nome e percorso del file.



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

Q. Gli stili ANSI (grassetto, italico, sottolineato, blu) vengono
   interrotti dopo la prima linea.
A. Vedere il paragrafo 8.2.

Q. Il testo converito da HTTX non e' centrato mentre nella pagina
   originale lo e'.
A. Questo puo' avvenire se il testo nelle linee di una tabella (<TR>) o
   nelle sue celle (<TD>) e' definito come centrato. Per mantenere la
   compatibilita' con alcuni programmi utilizzati in congiunzione ad HTTX,
   questa versione non supporta l'allineamento definito in tali elementi.
   Verra' aggiunto in versioni future che avranno maggiore supporto per le
   tabelle. In alternativa puo' trattarsi di un problema di compatibilita'
   ANSI (vedere il paragrafo 8.2).

Q. In alcuni casi non funziona l'allineamento, la formattazione del testo e
   le liste non vengono formattate correttamente o addirittura compaiono
   elementi HTML.
A. Si tratta di testo preformattato contenuto nell'elemento HTML <PRE>.
   HTTX lo copia cosi' com'e', senza effettuare alcuna formattazione. Questa
   scelta deriva dal fatto che sovente i testi di questo tipo contengono
   sorgenti che l'autore del documento desidera presentare cosi' come sono.

   Negli elementi <LISTING> e <XMP> anche gli elementi HTML vengono inclusi
   nel documento, come da specifiche. Anche se le direttive dell'HTML 4.0
   sconsigliano <XMP>, esso e' tuttora utilizzato per esempi in molti
   documenti, come le specifiche JavaScript di Netscape.

Q. Determinate pagine non vengono convertite correttamente...
A. Le ragioni possono essere diverse: layout basato su tabelle (attualmente
   non supportate completamente, si veda paragrafo 8.1), errori nel sorgente
   HTML (HTTX e' abbastanza tollerante, ma ci sono dei limiti) oppure errori
   nel parser di HTTX stesso. Se ritenete che la pagina sia corretta,
   segnalatemene l'URL. (E-Mail: favrin@tin.it, FidoNet: 2:333/726.8)

Q. Posso utilizzare HTTX da altri programmi?
A. Nell'archivio e' presente un plugin ARexx per utilizzare HTTX dal browser
   AWeb.

   Per quanto riguarda i programmi esterni, e' possibile usare facilmente
   HTTX da Directory Opus. Segue esempio relativo alla versione 4 ma
   facilmente utilizzabile anche con le sucessive:

   New Entry/AmigaDOS:
     C:HTTX {f} {d}
     (sostituire a C: il path completo se HTTX non si trova li')

   In questo modo il file selezionato nella directory "source" verra'
   convertito in formato testo e salvato nella directory "destination".

   Attivando il flag "Do all files" diventa possibile convertire piu' files
   alla volta semplicemente selezionandoli e premendo il bottone cui e' stato
   assegnato HTTX.

Q. Esistono GUI per controllare HTTX?
A. Alfonso Ranieri (alfier@iol.it) ha realizzato uno script ARexx che
   fornisce un'interfaccia StormWizard per la configurazione di HTTX.

   Il plugin per AWeb comprende un'interfaccia Reaction per la
   configurazione. La versione separata da utilizzarsi da wb sara'
   disponibile a breve.

Q. Utilizzo un programma che si appoggia ad HTTX per la stampa dell'HTML.
   Installando una versione di HTTX superiore alla 1.1b la stampa non
   funziona piu'.
A. Diversi programmi che si appoggiano ad HTTX sono stati realizzati ai
   tempi della versione 1.1b. Essi usano comandi tipo "HTTX <nomefile> prt:".

   Questa sintassi non e' piu' utilizzabile, soprattutto se viene abilitata
   l'opzione ANSIMODE. A partire dalla versione 1.5, infatti, HTTX puo'
   utilizzare per la stampa alcuni codici ANSI non compatibili con "prt:".

   La soluzione e' chiedere agli autori di questi programmi la modifica della
   sintassi utilizzata per invocare HTTX, se essa non e' direttamente
   configurabile dall'utente.

Q. Posso migliorare le prestazioni di HTTX?
A. E' possibile velocizzare la conversione utilizzando un filesystem con
   blocchi da 1024 byte, ad esempio il ram disk. Nel caso la memoria sia
   poca o particolarmente frammentata il salvataggio in ram portera' pero' a
   rallentamenti.

Q. Posso rendere residente HTTX?
A. A partire dalla versione 2.0 HTTX "dovrebbe" poter essere reso residente,
   Tuttavia non e' stato ancora possibile verificare il corretto e totale
   funzionamento in tale stato, pertanto, allo scopo di evitare problemi per
   gli utenti, questa possibilita' non e' ufficialmente documentata.

   Chi vuole tentare puo' inserire in una shell il seguente comando:

   Resident C:HTTX FORCE
   (sostituire a C: il path completo se HTTX non si trova li')



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

Questo paragrafo affronta alcune tematiche relative allo standard HTML ed
alla sua implementazione in HTTX. Anche se la sua lettura non e' fondamentale
per imparare ad utilizzare il programma, sono presenti informazioni
importanti, da leggere se si intende diffondere i testi convertiti.



8.1 Cosa e' supportato, cosa non lo e' (ancora) e implementazione
    dello standard.
-----------------------------------------------------------------

HTML supportato:

 - Le entita' descritte nel RFC 1866, &copy; e &reg; (NHTML), le entita'
   numeriche (sia decimali che esadecimali), le entita' numeriche ed i
   caratteri speciali di Win'95.
 - I separatori (<CENTER>, <DIV>, <BR>, <P> e <HR>) e il cambio dimensione
   font (da <H1> ad <H6>).
 - L'allineamento (centrale e a destra) di testo (intestazioni e paragrafi) e
   separatori.
 - Gli stili fisici e logici.
 - Le liste numerate (<OL> con eventuale attributo START) di tipo
   alfabetico, numerico o misto, quelle non numerate (<UL>) e le liste di
   definizioni (<DL>); fino a un massimo di 255 livelli.
 - Il titolo del documento (<TITLE>).
 - I link (<A>), le mappe utente e le immagini (<IMG> con eventuale
   ALT-text).
 - Il testo preformattato (<PRE>, <XMP> e <LISTING>).
 - Gli script (il contenuto dell'elemento HTML <SCRIPT>).
 - L'utilizzo non standard di "<" e ">" in un testo preformattato
   (suscettibile di cambiamenti).

Cosa non e' (ancora completamente) supportato:

 - Le tabelle (<TABLE>). Attualmente ogni cella e' gestita come un documento
   a parte con un proprio allineamento, livello di indentazione liste, stili
   e via dicendo.
 - <APPLET>, <STYLE> e <SELECT>: il contenuto di questi elementi viene
   ignorato.

Implementazione dello standard:

 - Elementi HTML sconosciuti vengono ignorati.
 - Spazi consecutivi o posti a inizio e fine riga vengono eliminati,
 - Caratteri ASCII non visualizzabili (minori di 32) vengono convertiti in
   spazi.
 - Fine linea PC (CR+LF) e Mac (CR) vengono convertiti nel formato Amiga
   (LF).
 - Per facilitare la lettura del testo nelle tabelle, <TD> viene trasformato
   in uno spazio e <TR> in un EOL. Inoltre fra due <TR> (table row) viene
   inserito al massimo un separatore (<HR>).
 - EOL consecutivi vengono ridotti ad uno (fatta eccezione per <BR>).

Queste regole non vengono seguite durante la conversione degli elementi
<SCRIPT>, <PRE>, <LISTING> e <XMP>. Fare riferimento alla sezione 8.3 per
maggiori informazioni.



8.2 Note sulla conversione ANSI
-------------------------------

Se l'opzione ANSIMODE e' attiva (valori 1 o 2) HTTX utilizza le sequenze ANSI
per la gestione degli stili HTML (grassetto, italico, sottolineato etc), dei
link (visualizzati in un colore sottolineato, di base il blu), del centraggio
e dell'indentazione del testo.

I codici ANSI utilizzati sono stati tratti dalle specifiche dello standard e
dovrebbero essere supportati da qualsiasi programma (forse...).

Queste le sequenze (ESC e' sostituito da "\e").

Grassetto    \e[1m
Italico      \e[3m
Sottolineato \e[4m
Colore (blu) \e[33m (\e[34m se si utilizza l'opzione PRINT)

La definizione contemporanea di piu' stili viene effettuata con ";", ad
esempio per impostare grassetto e italico HTTX utilizza "\e[1;3m".

Se l'opzione ANSIMODE ha valore 2, per l'indentazione delle liste e
l'allineamento del testo viene utilizzata la sequenza di posizionamento
cursore "\e[nnC" dove nn e' il numero di spostamenti a destra da effettuare.
Questa sequenza non e' usata in fase di stampa.


Problematiche di compatibilita':

- Lo standard ANSI prevede che il fine linea non causi l'interruzione di uno
  stile, se quindi uno stile risulta interrotto dopo la prima linea il
  problema e' nei programmi utilizzati per visualizzare il testo. Sia la
  shell standard che MultiView, per citarne due, operano correttamente.

- Alcuni visualizzatori di testi (come MultiView) non supportano le
  sequenze VT100 per il posizionamento del cursore utilizzate quando viene
  attivata l'opzione ANSIMODE=2 (ANSI ottimizzato). Se con MultiView una
  pagina contenente liste o testo allineato appare mal convertita, provare a
  ripetere la conversione utilizzando l'opzione ANSIMODE=1 oppure cambiare
  visualizzatore.



8.3 Note sulla conversione dei contenuti di <PRE>, <XMP>,
    <LISTING> e <SCRIPT>.
---------------------------------------------------------

Le regole indicate nell'implementazione dello standard (paragrafo 8.1), la
formattazione del testo e la conversione a 7 bit dei caratteri 8 bit non sono
totalmente valide per alcuni elementi che in base alle specifiche HTML
vengono gestiti diversamente.

- Elemento <PRE> (testo preformattato).
  In questa modalita' la formattazione del testo non e' effettuata.
  L'interpretazione degli elementi HTML (ad eccezione di liste e
  allineamento) viene effettuata. Le entita' numeriche minori di 32 non
  vengono convertite per evitare problemi con file uuencodati presenti nelle
  pagine HTML.

- Elementi <XMP>, <LISTING> e <SCRIPT>.
  Il contenuto di questi elementi e' lasciato inalterato. Non vengono
  effettuate formattazione del testo, conversione delle entita' ed
  interpretazione degli elementi HTML. Se l'opzione 7BIT e' attiva i
  caratteri ASCII minori di 32 vengono convertiti in spazi. Quelli maggiori
  di 128 vengono lasciati come sono e le entita' di Win'95 non vengono
  convertite. Tenerne conto se il testo convertito deve essere inserito in
  conferenze echo FidoNet o Newsgroup Usenet.



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

Oltre a consigli, segnalazioni di bug e 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:  favrin@tin.it
FidoNet: 2:333/726.8

Per favore scrivete in italiano o in inglese.

Pagina di supporto per HTTX:
http://www.freeweb.org/varie/poing/soft/httx/indice.html



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

Per il betatesting:

William Parker        wparker@bill.amitrix.com
Giuseppe Pasanisi     amicus@net-service.net
Neil Bothwick         aweb@wirenet.co.uk
Marco L. Buschini     shido@mclink.it
Claudio Mazzuco       kirk@maya.dei.unipd.it
Giuseppe Ammendolia   ryuga@freenet.hut.fi

Per la documentazione inglese e la verifica dei testi:

Fabio Belli           zak@anturio.com
William Parker        wparker@bill.amitrix.com

Per il betatesting del Plugin per AWeb:

William Parker        wparker@bill.amitrix.com
Neil Bothwick         aweb@wirenet.co.uk
Dale Currie           dalec@zorro.amitrix.com

Ringraziamenti speciali:

A Yvon Rozijn per aver voluto HTTX nel pacchetto di AWeb II e per tutto
l'aiuto che mi ha fornito!

A Bill Parker per l'aiuto, i consigli e la sua amicizia.

A Wouter van Oortmerssen per lo splendido AmigaE ed a Tomasz Wiszkowski per
CreativE, la sua evoluzione.

A Enrico Altavilla per i suoi consigli di programmazione.

Ai Pooh (http://www.pooh.it) per le emozioni che da anni mi regalano con la
loro musica. HTTX, forse, e' nato un po' anche grazie a loro...

Infine grazie di cuore a chi mi ha scritto a proposito di HTTX e a chi lo
utilizza!



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

V2.0b (Dicembre 1999)
  -Corretto un bug che poteva causare l'inserimento di codici ANSI incompleti
   nella modalita' ANSI standard.
  +Reso il sorgente compatibile con il nuovo compilatore CreativE.

V2.0  (Settembre 1999)
  +Riorganizzato in maniera modulare il parser HTML, ora piu' espandibile
   e veloce.
  +Gli elementi HTML di stile vengono ora interpretati solo se la conversione
   ANSI e' attiva, velocizzando cosi' la conversione non ANSI.
  +Allargato il buffer di scrittura file. Cio' rende HTTX piu' veloce su
   device veloci (come HD SCSI o RAM) ma anche piu' lento su quelli lenti
   (come i drive ZIP).
  +Aggiunto il pieno supporto di liste alfabetiche e miste
   (numeriche/alfabetiche).
  +Aggiunte le opzioni ANSIMODE (scelta modalita' ANSI utilizzata), ANSICOL
   (colore dei link), TDEOL (inserimento fine linea fra le celle di una
   tabella) e SETNOTE (tipo del commento aggiunto al file salvato).
  +Riorganizzata la visualizzazione delle impostazioni correnti.
  +Il contenuto dell'elemento HTML <SELECT> viene ora ignorato.
  +Se la conversione ANSI e' attiva, il contenuto dell'elemento HTML <TH>
   viene ora mostrato in grassetto.
  +Aggiunto un bell'ovetto di Pasqua ;-)
  -Corretti (si spera) tutti i bug nella formattazione del testo ed i
   relativi effetti collaterali, come la duplicazione di parti del testo,
   l'errato conteggio della dimensione linea, etc.
  -Se l'opzione SCRIPT era attiva l'indicazione della lunghezza del file
   salvato poteva essere errata.
  -Dopo un reset dei codici ANSI, in presenza dell'elemento <U>, il testo
   poteva essere visualizzato in blu sottolineato.
  -Aumentata la compatibilita' ANSI in fase di stampa: ora gli spazi a inizio
   riga sono sempre preceduti da una sequenza di reset ANSI.
  -Le impostazioni visualizzate in assenza di argomenti erano errate.
  -L'errore "configurazione non trovata" poteva essere visualizzato anche in
   presenza delle opzioni QUIET o STDIO.
  -Ogni cella all'interno di una tabella HTML poteva contenere un solo <HR>.
  -L'uso dell'opzione FILENOTE disabilitava l'inserimento di url e titolo nel
   documento anche in assenza dell'opzione NOHEADER.
  -In fase di stampa i link ANSI venivano visualizzati in giallo.

V1.7a (Giugno 1998)
  +Aggiunto l'alias PRT per l'opzione PRINT.
  -Corretto un pericoloso bug che poteva portare al crash di HTTX 
   durante l'allineamento di linee molto lunghe.
  -Corretto un errore nel wordwrap che causava problemi di layout dopo certe
   linee.

V1.7  (Gennaio 1998)
  +Riscritte in maniera piu' lineare varie parti importanti del sorgente come
   la gestione ANSI ed il wordwrap.
  +Reso il parser HTML piu' fedele alle regole SGML.
  +Migliorato il supporto delle tabelle tramite la gestione di ogni cella
   come un documento a parte.
  +Aggiunto il supporto per le entita' numeriche esadecimali (&#xnn;)
   (fino a 255) e le entita' numeriche ed i caratteri speciali di Win'95 fra
   128 e 159.
  +Aggiunto il supporto per l'elemento HTML <SELECT>, <XMP> e migliorata la
   gestione di <LISTING>.
  +Il testo interno a <BLOCKQUOTE> (o <BQ>) ora viene indentato.
  +In modalita' <PRE> le entita' numeriche minori di 32 vengono lasciate
   inalterate.
  +Aggiunte le opzioni SCRIPT e INCLUDE.
  +Specificando l'opzione NOHEADER ora la versione di HTTX non viene
   inserita.
  +Migliorato il supporto per HTML non standard.
  +... e molte altre migliorie!
  -Corretti vari piccoli bug estetici o dovuti ad HTML non standard.
  -Risolti parecchi problemini del vecchio wordwrap (il piu' rilevante dei
   quali si manifestava quando una linea senza spazi terminava con una
   entita').
  -Entita' numeriche inferiori ad ASCII 32 non erano convertite in spazi.
  -In caso di argomenti errati potevano venire visualizzati errori
   inesistenti.
  -In alcuni casi l'ultimo carattere del file poteva essere ignorato.
  -Spazzati via diversi altri piccoli bug!

V1.5  (Maggio 1997)
  +Velocizzato di molto il programma grazie ad una completa riscrittura del
   parser HTML e all'ottimizzazione di parecchie funzioni.
  +Aggiunte le opzioni HRMODE, NOALIGN, PRINT, APPEND, NOCFG, CFG.
  +Aggiunto il supporto per l'allineamento (centrale e a destra) di testo e
   separatori.
  +Aggiunto il supporto per vari elementi e attributi HTML (ad esempio START
   nelle liste numerate).
  +Ottimizzato l'output ANSI.
  +Aggiunto il supporto per i separatori in ANSI.
  +Aggiunto il supporto per la configurazione esterna.
  +Migliorato il supporto delle entita' che ora vengono identificate
   qualunque sia il carattere che le chiude.
  +Resi piu' esplicativi i messaggi d'errore interni di HTTX e sostituiti
   quelli DOS con PrintFault() di AmigaDOS.
  +Aggiunto il supporto per "HTTX nome_sorgente path_destinazione".
  +Migliorata la gestione dei separatori nelle tabelle.
  -Ora HTTX segue piu' fedelmente i DTD HTML per parecchie TAG.
  -Corretti alcuni errori nel wordwrap.
  -Corretti tutti i bug segnalati per la 1.1b.
  +... e molte altre migliorie!

V1.1b (Gennaio 1997)
  -Corretta l'interpretazione di alcune entita'.

V1.1a (Gennaio 1997)
  -Corretto uno stupido e raro bug nella gestione delle TAG.
  -Corretta la gestione degli EOL MAC.

V1.1  (Novembre 1996)
  +Migliorata la velocita'.
  +Aggiunte le opzioni STDIO, QUIET, BADHTML, NOHEADER, GETNOTE.
  +Aggiunto il supporto per i codici d'errore AmigaDOS.
  +Aggiunto il supporto per gli elementi <ADDRESS> e <LISTING>.
  +Modificata la gestione di <BR> e <LI> in ottemperanza all'implementazione
   nello standard HTML 3.2.
  +Riscritta la gestione delle entita': ora vengono convertite anche se non
   chiuse da ";".
  +Estesa la conversione a 7 bit, ora piu' veloce, completa (vengono
   convertiti quasi tutti 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 elementi HTML e ALT-Text contenenti
   fine linea, "<" 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.0  (Luglio 1996)
   Prima versione pubblica.



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. Questa
versione ha posto le basi per una nuova, ancor migliore, che sara' presto
disponibile.



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

                              *** 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!

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