Capitolo 265. HTMLDOC
HTMLDOC (1) è un sistema di composizione basato su HTML. In pratica, si parte da uno o più file HTML e si ottiene una composizione in PostScript, PDF e HTML. I file HTML di partenza devono avere una struttura ragionevolmente semplice, dove il testo sia strutturato in capitoli, inizianti con un'intestazione H1, suddivisi nel modo consueto, attraverso le intestazione di livello inferiore (H2, H3,... H7). In questo modo, HTMLDOC è in grado di generare automaticamente un indice generale e diventa utile tutto il sistema anche quando l'obiettivo è la generazione di una composizione finale nello stesso formato HTML.
HTMLDOC è disponibile sia su piattaforme Unix, sia su sistemi MS-Windows. In particolare, può funzionare in modo interattivo, attraverso l'interfaccia grafica, oppure in modo non interattivo utilizzando semplicemente opzioni della riga di comando.
265.1 Sorgente HTML
Il sorgente di un documento HTMLDOC può essere contenuto in un file singolo, oppure in più file HTML distinti. La prima cosa che dovrebbe apparire nel corpo del file HTML è un'intestazione di tipo H1.
In questi file HTML non sono ammissibili le inserzioni di oggetti, a parte le immagini nel modo consueto, attraverso l'elemento IMG; non si possono usare le cornici (frame); vengono ignorati gli script e le applet. È possibile selezionare soltanto i tipi di carattere standard, corrispondenti a: Helvetica, Times e Courier. Dal momento che HTMLDOC è disponibile anche su piattaforma MS-Windows, il carattere Arial viene convertito automaticamente in Helvetica. Non sono gestiti i fogli di stile e le tabelle sono riconosciute solo al livello di HTML 3.2.
Come estensione dello standard HTML viene riconosciuto il marcatore <HR BREAK>, allo scopo di ottenere un salto pagina.
La documentazione di HTMLDOC è scritta in questo modo, per cui può essere osservata la tecnica utilizzata e il risultato che si ottiene. In generale, dopo l'elemento HEAD, all'interno dell'elemento BODY si comincia subito con un'intestazione H1. L'esempio seguente è un estratto del file intro.html, che è il primo del gruppo di file che compongono la documentazione di HTMLDOC:
<HTML> <HEAD> <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> <META NAME="author" CONTENT="Michael R. Sweet"> <META NAME="copyright" CONTENT="Copyright 1997-1999, See the GNU General Public License for Details."> <META NAME="Author" CONTENT="Michael R. Sweet, Easy Software Products"> <TITLE>HTMLDOC 1.7 User's Guide</TITLE> </HEAD> <BODY> <DIV ALIGN=right> <H1> Introduction</H1></DIV> <H2> About This Software</H2> This document describes how to use the <I>HTMLDOC</I> software, version 1.7. <I>HTMLDOC</I> is a HTML document processing program that generates indexed HTML, Adobe® PostScript<SUP>TM</SUP>, and Adobe Portable Document Format (PDF 1.2) files suitable for printing or online viewing. <P>No restrictions are placed upon the output produced by <I>HTMLDOC</I>. <H2>History</H2> Like many programs <I>HTMLDOC</I> was developed in response to a need my company had for generating high-quality documentation in printed and ... ... <H2>Why Just HTML?</H2> Some people have asked why this program only deals with HTML input files and is not able to read any Standard Generalized Markup Language (SGML) file. The reasons are numerous but basically boil down to: ... ... </BODY> </HTML>
Eventualmente è possibile convertire un file HTML singolo che non sia conforme a questa struttura, utilizzando un'opzione apposita, --webpage, con la quale non si ottiene più l'indice generale, ma soprattutto non è possibile aggregare più file HTML assieme in un documento finale unico.
265.2 Funzionamento
HTMLDOC si compone dell'eseguibile htmldoc, che può essere avviato senza argomenti, per ottenere un funzionamento interattivo:
htmldoc [opzioni file_html...]
È prevista la presenza di un file di configurazione personale, dei singoli utenti. Si tratta del file ~/.htmldocrc. Questo file viene creato la prima volta dall'eseguibile htmldoc e potrebbe essere utile modificare la direttiva di dichiarazione del programma usato per modificare i file HTML sorgenti:
#HTMLDOCRC 1.7 EDITOR=amaya %s
In questo caso, si fa in modo di utilizzare Amaya per la modifica del sorgente HTML, quando questo tipo di programma viene richiamato da HTMLDOC.
Purtroppo non è disponibile una documentazione sufficiente sulle direttive di questo file di configurazione.
Nel seguito viene mostrato il funzionamento interattivo di HTMLDOC, abbinando anche la descrizione delle opzioni che possono servire per ottenere lo stesso risultato senza interazione con il programma. Intanto, nella figura 265.1 si può osservare come appare inizialmente, dopo l'avvio con il comando seguente:
$ htmldoc[Invio]
|
Figura 265.1. Aspetto iniziale di HTMLDOC, quando viene avviato senza argomenti.
|
Nella parte bassa del pannellino grafico, appaiono alcuni pulsanti grafici, che fanno riferimento alla possibilità di creare e salvare un file contenente tutte le informazioni sulla composizione che si vuole generare. Questo file può essere inteso come la configurazione del libro che si vuole comporre.
-
Il pulsante <
New> serve a eliminare il lavoro in corso, per ricominciare con un altro nuovo. -
Il pulsante <
Open> permettere di accedere al file system per selezionare un file contenente le informazioni su una composizione già predisposta in precedenza. -
I pulsanti <
Save> e <Save As> consentono di salvare l'impostazione attuale, eventualmente dando un nome nuovo alla cosa. -
Il pulsante <
Generate> avvia la composizione in base alle informazioni indicate, generando uno o più file PostScript, PDF o HTML, a seconda di quanto specificato a questo proposito.
La parte centrale del pannello grafico di HTMLDOC cambia in funzione del lembo superiore selezionato.
265.2.1 Definizione dei file sorgenti
La prima fase per arrivare alla composizione è quella della selezione dei file HTML che compongono i sorgenti. Ciò si fa dalla finestra che si ottiene selezionando l'etichetta {Input}, che corrisponde alla situazione in cui si presenta HTMLDOC all'avvio.
In alto, si può osservare la presenza di due pulsanti di selezione, dove si può specificare il tipo di sorgente che si utilizza. La voce <Book> indica l'intenzione di utilizzare uno o più file HTML per generare un documento unico, in forma di libro, mentre la voce <Web Page>, corrispondente all'opzione --webpage, specifica che si tratta di un solo file HTML che non ha la struttura richiesta per realizzare un libro.
Il pulsante grafico laterale <Add File> consente di accedere al file system per selezionare i file HTML che compongono i sorgenti del documento che si vuole comporre. Nella figura 265.2 appaiono selezionati i file uno.html, due.html e tre.html.
|
Figura 265.2. Sono stati selezionati tre file.
|
Sul lato destro si possono osservare anche altri pulsanti grafici, che si abilitano solo quando si seleziona uno o più nomi nell'elenco di quelli che compongono l'insieme dei sorgenti del documento: <Edit File> permette di avviare automaticamente il programma per la modifica dei file HTML; <Delete File> elimina i nomi evidenziati dall'elenco, ma senza cancellarli dal file system; <Move Up> e <Move Down> consentono di spostare il nome selezionato in alto o in basso, cambiando l'ordine.
Per completare l'estetica della composizione, è possibile specificare un'immagine da usare come logo e un'altra immagine da utilizzare nella copertina (ammesso che sia stata ablitata la sua generazione). Nel primo caso si può usare l'opzione --logo file_immagine; nel secondo l'opzione --title file_immagine.
265.2.2 Composizione
L'etichetta {Output} consente di accedere alla definizione del file o dei file che si vogliono ottenere dalla composizione. Il risultato della composizione può essere un file oppure una directory, selezionando <File> oppure <Directory>, rispettivamente. Queste due voci corrispondono alle opzioni --outfile file e --outdir directory. Il file o la directory in questione si indicano sotto, mentre più giù si specifica esattamente il tipo di composizione che si vuole generare: <HTML>, <PS>, <PS2> e <PDF> (opzione --format {ps1|ps2|pdf|html}).
|
Figura 265.3. Definizione del risultato della composizione che si vuole ottenere.
|
Il senso delle opzioni che appaiono nel resto della maschera è abbastanza intuitivo. Si può osservare il fatto che sia possibile cambiare il colore dello sfondo e anche utilizzare un'immagine per questo.
Se si indica una directory, si intende generare un gruppo di file nella directory stessa. Ciò può essere utile nella composizione in HTML, ma funziona nello stesso modo anche per le altre forme di composizione.
265.2.3 Formato e aspetto delle pagine
L'etichetta {Page} consente di accedere alla definizione delle pagine, nel caso in cui la composizione richiesta serva a generare un formato PostScript o PDF. È possibile indicare il formato della pagina (corrispondente all'opzione --size formato), se la stampa avviene su entrambi i lati del foglio (la voce <Double-sided>, ovvero l'opzione --duplex), i margini (le opzioni --left n{in|cm|mm}, --right n{in|cm|mm}, --top n{in|cm|mm}, --bottom n{in|cm|mm}), l'intestazione e il piè pagina (opzioni --header xyz e --footer xyz).
|
Figura 265.4. Definizione della pagina nel caso di composizione per la stampa.
|
La selezione di intestazione e piè di pagina consente di definire ciò che deve apparire a sinistra, al centro e a destra di queste.
265.2.4 Indice generale
L'etichetta {TOC} consente di accedere alla definizione dell'indice generale, che in particolare prevede l'indicazione del livello di dettaglio che deve avere e consente la specificazione di intestazione e piè pagina differenti dal resto del documento.
|
Figura 265.5. Definizione dell'indice generale e della numerazione delle sezioni.
|
Il livello di dettaglio dell'indice si definisce anche con l'opzione --toclevels n, l'intestazione e il piè di pagina si possono definire con le opzioni --tocheader xyz e --tocfooter xyz. Infine, nella maschera si può vedere la voce <Numbered Headings>, corrispondente all'opzione --numbered, con cui si ottiene la numerazione delle sezioni (gli elementi Hn).
265.2.5 Carattere da stampa
Sempre nel caso di composizione per la stampa, l'etichetta {Fonts} consente di definire il tipo e la dimensione dei caratteri da usare per il corpo, le sezioni, l'intestazione e il piè pagina. Per la necessità di essere compatibili al massimo, sono disponibili solo i tipi Times, Helvetica e Courier. Si osservi che l'altezza delle righe viene espressa in rapporto rispetto all'altezza dei caratteri, dove per esempio 1.2 rappresenta il 120 %.
|
Figura 265.6. Definizione del carattere da stampa.
|
Le opzioni corrispondenti sono: --bodyfont carattere, --fontsize n e --fontspacing n per definire il carattere, la dimensione in punti e l'altezza delle righe nel testo normale; --headfootfont carattere e --headfootsize n, per indicare il tipo di carattere e la dimensione in punti dell'intestazione e del piè di pagina; --headingfont carattere per definire il tipo di carattere dei titoli delle sezioni.
265.2.6 Altre opzioni
L'ultima etichetta, {Options}, riguarda le opzioni rimanenti che non hanno trovato una collocazione migliore. In questo contesto viene definito in particolare il programma da utilizzare per la modifica dei file HTML del sorgente. Si può usare un programma per la modifica dei file di testo, oppure un applicativo più elaborato, specifico per i file HTML.
|
Figura 265.7. Definizione delle opzioni rimanenti.
|
265.3 Programmazione della composizione
HTMLDOC, quando funziona in modo interattivo, consente di conservare in un file l'impostazione, ovvero la configurazione di un documento, memorizzando tutte le opzioni selezionate. Quanto mostrato nelle figure di esempio, si tradurrebbe nel contenuto seguente:
#HTMLDOC 1.7 3 uno.html due.html tre.html -t ps1 -f prova.ps --toclevels 3 --size a4 --left 3cm --right 3cm (segue)
--top 3cm --bottom 3cm --header t.1 --footer h.. --tocheader .I. (segue)
--tocfooter h.i --no-compression --fontsize 11.0 --fontspacing 1.2 (segue)
--headingfont Courier --bodyfont Times --headfootsize 12.0 (segue)
--headfootfont Helvetica
Da htmldoc(1) si intuisce che l'autore suggerisca di usare l'estensione .book per questi file; tuttavia HTMLDOC non propone alcunché.
L'osservazione di questi file consente anche di capire meglio l'uso delle opzioni della riga di comando. In questo caso, volendo usare l'eseguibile htmldoc in modo non interattivo per fare la stessa cosa, il comando avrebbe potuto essere quello seguente:
$ htmldoc -t ps1 -f prova.ps --toclevels 3 --size a4 <-'
`->--left 3cm --right 3cm --top 3cm --bottom 3cm --header t.1 <-'
`->--footer h.. --tocheader .I. --tocfooter h.i <-'
`->--no-compression --fontsize 11.0 --fontspacing 1.2 <-'
`->--headingfont Courier --bodyfont Times --headfootsize 12.0 <-'
`->--headfootfont Helvetica uno.html due.html tre.html
Eccezionalmente, l'eseguibile htmldoc può ricevere come argomento il nome di uno di questi file .book, ottenendo un funzionamento interattivo, partendo dalla configurazione contenuta nel file stesso. Supponendo di avere salvato quella configurazione nel file prova.book, basterebbe riavviare nel modo seguente:
$ htmldoc prova.book
Tabella 265.1. Riepilogo delle opzioni più comuni.
| Opzione | Descrizione |
| --webpage | Il sorgente non è realizzato secondo la struttura di un libro. |
| --format {ps1|ps2|pdf|html} | Formato finale della composizione. |
| -t {ps1|ps2|pdf|html} | Come --format. |
| --outfile file | File da generare dalla composizione. |
| -f file | Come --outfile. |
| --outdir directory | Directory in cui inserire i file della composizione. |
| -d directory | Come --outdir. |
| --top n{in|cm|mm} | Margine superiore secondo l'unità di misura specificata. |
| --bottom n{in|cm|mm} | Margine inferiore secondo l'unità di misura specificata. |
| --left n{in|cm|mm} | Margine sinistro secondo l'unità di misura specificata. |
| --right n{in|cm|mm} | Margine destro secondo l'unità di misura specificata. |
| --size letter|a4|universal | Formato della carta in base a un nome. |
| --size larghezzaxaltezza{in|cm|mm} | Formato della carta espresso esattamente. |
| --duplex | Stampa su entrambi i lati del foglio. |
| --header xyz | Intestazione. |
| --footer xyz | Piè di pagina. |
| --tocheader xyz | Intestazione dell'indice generale. |
| --tocfooter xyz | Piè di pagina dell'indice generale. |
| --headfootfont carattere | Carattere da usare nell'intestazione e piè pagina. |
| --headfootsize n | Dimensione carattere di intestazione e piè pagina. |
| --headingfont carattere | Carattere dei titoli delle sezioni. |
| --bodyfont carattere | Carattere da usare nel corpo. |
| --fontsize n | Dimensione del carattere normale in punti. |
| --fontspacing n | Altezza riga rispetto alla dimensione del carattere. |
| --logo file | Definisce il file da usare come logo. |
| --bodyimage file | Definisce il file da usare come sfondo. |
| --title file | Immagine da usare nella copertina. |
| --no-toc | Non genera l'indice generale. |
| --no-title | Non genera la copertina. |
| --toclevels n | Definisce il numero di livelli dell'indice generale. |
La tabella 265.1 riassume le funzionalità delle opzioni principali di HTMLDOC quando viene usato in modo non interattivo. È importante tenere in considerazione alcune cose, che vengono descritte brevemente nel seguito.
È possibile gestire solo immagini in formato GIF, JPG e PNG; in particolare, quando si ottiene una conversione in HTML, si usano le stesse immagini di partenza.
La dimensione della carta può essere indicata per nome, oppure direttamente, fornendo larghezza e altezza, nella forma mxn, dove m rappresenta la larghezza e n l'altezza. Si osservi che questi due numeri vanno completati con l'indicazione finale dell'unità di misura (come si vede nella tabella), una volta sola per entrambi i valori. Il formato speciale denominato universal si riferisce a un compromesso tra il formato A4 e il formato lettera (8,5 in × 11 in), in modo che possa essere stampato con entrambi i tipi di carta; in pratica si utilizza la larghezza del formato A4 e l'altezza del formato lettera.
Le opzioni che definiscono il contenuto delle intestazioni e dei piè di pagina, utilizzano una simbologia speciale, in cui tre lettere indicano rispettivamente la parte sinistra, quella centrale e quella destra della riga. La tabella 265.2 riepiloga questi simboli.
Tabella 265.2. Simboli usati negli argomenti delle opzioni che definiscono il contenuto delle intestazioni e dei piè di pagina.
| Simbolo | Descrizione |
| . | Vuoto. |
| t | Titolo del documento |
| h | Sezione attuale. |
| c | Capitolo attuale. |
| l | Logo. |
| i | Pagina in numero romano minuscolo. |
| I | Pagina in numero romano maiuscolo. |
| 1 | Pagina in numero arabo normale. |
| a | Pagina in lettere minuscole. |
| A | Pagina in lettere maiuscole. |
daniele @ swlibero.org