Capitolo 263.   HTML2ps

HTML2ps ⁽¹⁾ è un programma in grado di comporre uno o più file HTML, generando un risultato in PostScript. Questo si ottiene attraverso l'aiuto di altri programmi che devono essere installati, come per esempio TeX.

Teoricamente, HTML2ps è in grado di ricomporre assieme un documento suddiviso su più file HTML, ma questa possibilità dipende molto dall'organizzazione di questi file, all'interno dei quali, i riferimenti ipertestuali devono essere molto semplici. In generale, è possibile l'acquisizione diretta dalla rete; tuttavia, sarebbe consigliabile prima la riproduzione locale, con l'ausilio di Wget (170.6), attraverso il quale si possono modificare automaticamente i riferimenti ipertestuali, rendendo omogeneo il tutto.

HTML2ps si compone semplicemente dell'eseguibile html2ps (un programma scritto in Perl) e di uno o più file di configurazione. È indispensabile almeno il file di configurazione generale, /etc/html2psrc, che dovrebbe essere già predisposto in modo sufficientemente buono dal sistema di installazione. Eventualmente, gli utenti possono preparare una configurazione personalizzata nel file ~/.html2psrc e altri file specifici da richiamare con l'opzione -f, oltre all'aggiunta di stili ulteriori (opzione -s).

263.1   Configurazione di HTML2ps

Come accennato, la configurazione di HTML2ps è indispensabile. Di solito si predispone almeno il file di configurazione generale, /etc/html2psrc, mentre gli utenti hanno la possibilità di modificare o aggiungere qualcosa attraverso il file ~/.html2psrc. La sintassi per la scrittura di questi file è la stessa dei fogli di stile CSS (capitolo 262), con l'aggiunta di un selettore specifico, @html2ps, che serve a indicare gli aspetti particolari che riguardano HTML2ps e non possono appartenere ai fogli di stile CSS.

Bisogna tenere presente che HTML2ps è in grado di riconoscere solo una parte limitata delle dichiarazioni CSS.

HTML2ps riconosce anche i commenti CSS e le inclusioni di file di configurazione aggiuntivi, secondo la forma:

@include file

Per cominciare, è opportuno vedere un esempio abbastanza semplice di ciò che potrebbe contenere un file di configurazione, quando questo viene generato automaticamente dalla procedura di installazione.

/* Configurazione globale per html2ps */

@html2ps {
  package {
    ImageMagick: 1;
    PerlMagick: 1;
    TeX: 1;
    Ghostscript: 1;
    check: weblint;
    libwww-perl: 1;
    path: "/usr/X11R6/bin:/usr/bin";
  }
  paper {
    type: A4;
  }
  option {
    hyphenate: 0;
  }
}

Si può osservare che in questo esempio è stata dichiarata solo la regola corrispondente al selettore @html2ps, all'interno della quale si trovano altre sottoregole. Generalmente, le regole tipiche di uno stile CSS si aggiungono sotto. La configurazione predefinita dello stile CSS è indicata nella pagina di manuale html2psrc(5) e da questa si intende quali siano le possibilità effettive di HTML2ps nel riconoscere le dichiarazioni CSS:

BODY {
    font-family: Times;
    font-size: 11pt;
    text-align: left;
    background: white;
}

H1, H2, H3, H4, H5, H6 {
    font-weight: bold;
    margin-top: 0.8em;
    margin-bottom: 0.5em;
}

H1 { font-size: 19pt }
H2 { font-size: 17pt }
H3 { font-size: 15pt }
H4 { font-size: 13pt }
H5 { font-size: 12pt }
H6 { font-size: 11pt }

P, OL, UL, DL, BLOCKQUOTE, PRE {
    margin-top: 1em;
    margin-bottom: 1em;
}

P {
    line-height: 1.2em;
    text-indent: 0;
}

OL, UL, DD { margin-left: 2em }

TT, KBD, PRE { font-family: Courier }

PRE { font-size: 9pt }

BLOCKQUOTE {
    margin-left: 1em;
    margin-right: 1em;
}

ADDRESS {
    margin-top: 0.5em;
    margin-bottom: 0.5em;
}

TABLE {
    margin-top: 1.3em;
    margin-bottom: 1em;
}

DEL { text-decoration: line-through }

A:link, HR { color: black }

263.1.1   Configurazione della regola corrispondente al selettore speciale @html2ps

La regola corrispondente al selettore @html2ps si compone di dichiarazioni e di altre sottoregole per la configurazione di HTML2ps. Nelle sezioni seguenti vengono descritti i selettori specifici di queste sottoregole.

Alcune proprietà hanno un significato booleano. A loro si assegna il valore zero per indicare Falso e il valore uno per indicare Vero.

I valori che fanno riferimento a un'unità di misura, vanno indicati come avviene nei fogli di stile CSS: il numero seguito immediatamente dall'unità di misura. La tabella 263.1 elenca le unità di misura e le sigle corrispondenti che si possono utilizzare in questa circostanza. È importante osservare che l'unica dimensione relativa riconosciuta da HTML2ps è il quadratone e non sono previste misure percentuali come invece si può fare secondo le specifiche di W3C per i fogli di stile CSS.

Tabella 263.1. Unità di misura secondo HTML2ps.

Sigla	Unità di misura
cm	Centimetri.
mm	Millimetri.
pt	Punti tipografici.
pc	Pica.
em	Quadratoni, corrispondente alla dimensione della lettera «M» maiuscola.

• numberstyle: 0|1

  Permette di stabilire la numerazione delle pagine: zero richiede l'uso dei numeri arabi; uno corrisponde a numeri romani. Il valore predefinito per questa proprietà è il valore zero.

• showurl: 0|1

  Attivando questa proprietà booleana, si ottiene l'inserimento nella composizione dell'indirizzo URI corrispondente ai riferimenti ipertestuali. In situazioni normali questo non avviene.

• seq-number: 0|1

  Permette di abilitare la numerazione dei titoli H1, H2,... H6. In condizioni normali, questo non avviene.

263.1.1.1   Sottoregola package

La sottoregola package serve a definire la disponibilità o meno di altri programmi di cui HTML2ps potrebbe avere bisogno. Di conseguenza si tratta di assegnamenti di valori booleani, dove zero rappresenta l'assenza del programma in questione e in generale è anche il valore predefinito.

• PerlMagick: 0|1

  Indica la mancanza o la disponibilità di PerlMagick.

• ImageMagick: 0|1

  Indica la mancanza o la disponibilità di ImageMagick.

• Ghostscript: 0|1

  Indica la mancanza o la disponibilità di Ghostscript.

• TeX: 0|1

  Indica la mancanza o la disponibilità di TeX.

• dvips: 0|1

  Indica la mancanza o la disponibilità di dvips.

• libwww-perl: 0|1

  Indica la mancanza o la disponibilità del modulo Perl Libwww-Perl.

• path: percorsi_aggiuntivi

  Si tratta dell'indicazione di percorsi aggiuntivi per la ricerca degli eseguibili. Serve a garantire che i programmi utilizzati da HTML2ps siano raggiungibili per tutti gli utenti. In generale, in presenza di un sistema configurato bene, non dovrebbe essere necessaria l'indicazione di questa dichiarazione.

263.1.1.2   Sottoregola paper

La sottoregola paper serve a definire le caratteristiche della carta. In generale si tratta solo delle dimensioni.

• type: tipo_di_carta

  La direttiva serve a definire le dimensioni della carta, attraverso l'indicazione di un nome standard; per esempio: A0, A1, ... A10, B0, B1, ... B10, letter, legal, ecc. In alternativa, si possono indicare le dimensioni precise attraverso le proprietà height e width.

• height: dimensione_assoluta

  Permette di definire l'altezza del foglio.

• width: dimensione_assoluta

  Permette di definire la larghezza del foglio.

263.1.1.3   Sottoregola option

La sottoregola option serve a definire l'utilizzo di alcune opzioni, a cui si può accedere anche attraverso la riga di comando. Vengono descritte prima le dichiarazioni da indicare nel file di configurazione e poi le opzioni corrispondenti della riga di comando.

• twoup: 0|1

  -2 | --twoup

  Se attivato, fa in modo di ottenere un testo organizzato su due colonne verticali.

• toc: {f|h|t}[b]

  -C {f|h|t}[b]

  Fa in modo che venga generato un indice generale, in base alle opzioni specificate da una o più lettere:

  • b   l'indice generale deve essere collocato all'inizio;

  • f   l'indice generale deve essere generato a partire dai riferimenti contenuti nel documento;

  • h   l'indice generale deve essere generato a partire dai titoli definiti dagli elementi HTML da H1 a H6;

  • t   l'indice generale deve essere generato a partire da elementi LINK contenenti l'attributo REV=TOC.

• DSC: 0|1

  -D | --DSC

  Se attivato, fa in modo di generare un file PostScript aderente alle specifiche DSC. In generale, per ottenere un file PostScript completo, è necessario attivare questa opzione.

• encoding: codifica

  -e codifica | --encoding codifica

  Permette di definire la codifica in cui è realizzato il file HTML. Il valore predefinito è ISO-8859-1, ma sono poche altre le possibilità (si deve consultare la pagina di manuale).

• hyphenate: 0|1

  -H | --hyphenate

  Se attivato, fa in modo che il testo possa essere separato in sillabe, per facilitare l'impaginazione.

• language: linguaggio

  -l linguaggio | --language linguaggio

  Permette di indicare un linguaggio diverso da quello che può essere stato dichiarato nell'elemento BODY con l'attributo LANG di un documento HTML. La stringa che definisce il linguaggio va scelta in base a quanto già consentito dall'HTML (sezione 543).

• landscape: 0|1

  -L | --landscape

  Se attivato, genera pagine orientate in modo orizzontale.

• number: 0|1

  -n | --number

  Se attivato, fa in modo di aggiungere i numeri di pagina.

• startno: n

  -N n | --startno n

  Specifica il numero iniziale delle pagine. Il valore predefinito è uno.

• xref: 0|1

  -R | --xref

  Se attivato, fa in modo di aggiungere dei riferimenti visivi nel testo, in corrispondenza di quelli ipertestuali contenuti nel documento HTML.

• scaledoc: scala_percentuale

  -s scala_percentuale | --scaledoc scala_percentuale

  Riduce o amplia la scala del documento: il valore unitario rappresenta la situazione normale, di una scala pari al 100 %; valori superiori indicano un ingrandimento, mentre valori inferiori indicano una riduzione (si usa il punto per separare la parte intera dalle cifre decimali).

• web: {a|b|l|r|s}[p|L|n]

  -W {a|b|l|r|s}[p|L|n]

  -web {a|b|l|r|s}[p|L|n]

  Fa in modo che vengano utilizzati più file HTML che si ritiene facciano parte dello stesso documento. Il modo in cui vengono presi in considerazione questi file dipende dalla stringa composta nel modo mostrato dallo schema sintattico.

  • a   segue tutti i riferimenti ipertestuali;

  • b   segue soltanto i riferimenti ipertestuali che riguardano la stessa directory del file iniziale;

  • l   segue soltanto i riferimenti ipertestuali che contengono l'attributo REL=NEXT all'interno dell'elemento LINK;

  • r   segue soltanto i riferimenti ipertestuali relativi;

  • s   segue solo i riferimenti allo stesso nodo del documento di partenza;

  • p   chiede conferma per ogni file HTML da aggiungere (ciò avviene in ogni caso quando si superano i 50 file);

  • L   riordina i documenti in base alla struttura gerarchica;

  • n   un numero indica il livello massimo di ricorsione, tenendo conto che il valore predefinito è di quattro livelli.

263.1.1.4   Sottoregola margin

La sottoregola margin permette di definire esplicitamente i margini della pagina.

Questa sottoregola è diventata obsoleta e viene sostituita dalla configurazione nel file di stile CSS, utilizzando la regola @page, introdotta dalle specifiche CSS2.

• left margine_sinistro

  right margine_destro

  Indicano i margini sinistro e destro rispettivamente. Il valore predefinito è 2.5cm, pari a 2,5 cm.

• top margine_superiore

  bottom margine_inferiore

  Indicano i margini superiore e inferiore rispettivamente. Il valore predefinito è 3cm, pari a 3 cm.

• middle distanza_tra_colonne

  Indica la distanza orizzontale tra le colonne, quando si stampano due colonne per pagina. Il valore predefinito è 2cm, pari a 2 cm.

263.1.1.5   Sottoregola xref

La sottoregola xref permette di definire esplicitamente il modo in cui vengono indicati i riferimenti nel testo, quando questa funzionalità è stata abilitata.

• text: modello

  Permette di definire il modello da utilizzare, tenendo conto che il simbolo $N viene rimpiazzato con il numero della pagina. Il modello predefinito è [p $N].

• passes: n

  Permette di definire il numero di passaggi necessario per determinare in modo corretto i riferimenti incrociati. Il valore predefinito è il valore uno, ma l'inserzione del testo corrispondente al modello potrebbe cambiare la sequenza delle pagine, per cui si potrebbe rendere necessario un numero maggiore di passaggi.

263.1.1.6   Sottoregola quote

La sottoregola quote permette di definire esplicitamente l'uso delle virgolette più appropriate in base al linguaggio. Queste virgolette vengono inserite nel testo in corrispondenza degli elementi Q. In generale, i valori predefiniti per la lingua italiana sono già corretti. Viene mostrato solo un esempio per comprendere intuitivamente come si potrebbe adoperare questa sottoregola:

quote {
  it {
    open: "«";
    close: "»";
    open2: "``";
    close2: "''";
  }
}

Si intende dall'esempio che sono disponibili solo due livelli di virgolette.

263.1.1.7   Sottoregola toc

La sottoregola toc permette di definire alcune caratteristiche relative all'indice generale, quando la sua realizzazione è stata richiesta espressamente. In particolare si può utilizzare la proprietà level alla quale si assegna un numero, che sta a indicare i livelli da prendere in considerazione. Il valore predefinito è sei, che produce una voce per ogni tipo di titolo Hn (da H1 a H6).

263.1.1.8   Sottoregola hyphenation

La sottoregola hyphenation permette di definire la collocazione del file TeX contenente i modelli per la separazione in sillabe. La cosa si fa distinguendo tra diversi linguaggi. L'esempio seguente dovrebbe essere sufficiente a intendere intuitivamente la cosa:

hyphenation {
  it {
    file: "/usr/share/texmf/tex/generic/hyphen/ithyph.tex";
  }
  en {
    file: "/usr/share/texmf/tex/generic/hyphen/ushyph1.tex";
  }
}

263.1.1.9   Sottoregole header e footer

Le sottoregole header e footer permettono di definire l'intestazione e il fondo pagina, dove di solito si collocano alcune informazioni ricorrenti assieme al numero della pagina. Le proprietà di queste sottoregole sono praticamente le stesse; qui vengono elencate solo alcune di queste proprietà nella tabella 263.3. La tabella 263.2 elenca alcuni simboli che possono essere utilizzati per definire i modelli delle intestazioni e dei fondo pagina.

Tabella 263.2. Simboli utilizzabili nelle intestazioni e nei fondo pagina.

Simbolo	Corrispondenza
$T	Titolo del documento.
$A	Autore, come specificato in <META NAME="Author" CONTENT="...">.
$U	URI del documento.
$N	Numero di pagina.
$H	Titolo attuale (H1...H3).
$D	Data e orario attuale.
\$	Dollaro.

Tabella 263.3. Alcune proprietà utilizzabili nell'intestazione e nel fondo delle pagine.

proprietà	Contenuto
left	Intestazione allineata a sinistra.
center	Intestazione al centro.
right	Intestazione allineata a destra.
odd-left	Intestazione delle pagine dispari allineata a sinistra.
odd-center	Intestazione delle pagine dispari al centro.
odd-right	Intestazione delle pagine dispari allineata a destra.
even-left	Intestazione delle pagine pari allineata a sinistra.
even-center	Intestazione delle pagine pari al centro.
even-right	Intestazione delle pagine pari allineata a destra.
font-family	Tipo di carattere da usare (predefinito Helvetica).
font-size	Dimensione del carattere (predefinito 8 punti).
font-style	Forma del carattere (predefinita la forma normale).
font-weight	Spessore del carattere (predefinito lo spessore normale).

263.1.2   Configurazione in cascata

La configurazione di HTML2ps segue la logica dei fogli di stile CSS, anche per ciò che riguarda la sua definizione in cascata. In generale: il file /etc/html2psrc contiene le indicazioni essenziali; il file ~/.html2psrc contiene la configurazione personalizzata; l'opzione -f consente di aggiungere altra configurazione specifica; l'opzione -S consente di aggiungere una stringa ulteriore allo stile.

Quando si utilizza l'opzione -f, se si vuole evitare di eliminare la configurazione standard dei file /etc/html2psrc e ~/.html2psrc, si deve iniziare con i due punti (:), come si vede nell'esempio seguente:

$ html2ps -f :locale manuale.html > manuale.ps

Si possono anche sommare assieme più configurazioni o stili CSS locali, come si vede nell'esempio seguente, dove si utilizzano i file locale, A4 e numerato:

$ html2ps -f :locale:A4:numerato manuale.html > manuale.ps

L'opzione -S serve solo per aggiungere una regola al volo, indicandola direttamente nella riga di comando, come si vede nell'esempio seguente:

$ html2ps -f :locale -S "H1 { color: blue }" manuale.html > manuale.ps

263.2   Avvio di HTML2ps

HTML2ps si utilizza attraverso l'eseguibile html2ps, con la sintassi seguente:

html2ps opzioni [file_html]

Il file da convertire può essere indicato nella riga di comando, dove in tal caso può trattarsi anche di un URI, oppure può essere fornito attraverso lo standard input.

Quasi tutte le opzioni di questo programma sono richiamabili anche tramite una proprietà corrispondente nella sottoregola option, come è già stato descritto. Qui vengono riepilogate le opzioni più importanti nella tabella 263.4. In particolare, si può osservare che si può indicare il nome del file da generare attraverso l'opzione -o, oppure --output, altrimenti il risultato della conversione viene emesso attraverso lo standard output.

Tabella 263.4. Riepilogo delle opzioni più comuni.

Opzione	Descrizione
-2, --twoup	Due colonne verticali.
-D, --DSC	Genera un file PostScript DSC (standard).
-e, --encoding	Stabilisce la codifica originale.
-H, --hyphenate	Abilita la separazione in sillabe.
-L, --landscape	Orientamento orizzontale.
-n, --number	Aggiunge i numeri alle pagine.
-o, --output	Specifica il file PostScript da generare.
-R, --xref	Mostra gli URI dei riferimenti ipertestuali.
-s, --scaledoc	Cambia la scala del documento.
-W, --web	Definisce come gestire più file HTML assieme.
-f, --rcfile	Specifica i file di configurazione aggiuntivi o alternativi.
-S, --style	Specifica una regola aggiuntiva al volo.

Esempi

$ html2ps -o documento.ps documento.html

Converte il file documento.html nel file documento.ps.

$ html2ps -2 -o documento.ps documento.html

Converte il file documento.html nel file documento.ps, che risulterà organizzato in due colonne verticali.

$ html2ps -R -o documento.ps documento.html

Converte il file documento.html nel file documento.ps, che conterrà dei riferimenti incrociati visibili.

$ html2ps -2 -s 0.5 -o documento.ps documento.html

Converte il file documento.html nel file documento.ps, che risulterà organizzato in due colonne verticali, con la dimensione del carattere ridotta alla metà.

$ html2ps -W b -o XFree86.ps XFree86-Video-Timings-HOWTO.html

Converte i file HTML che iniziano da XFree86-Video-Timings-HOWTO.html in un solo file PostScript, denominato XFree86.ps. In particolare viene richiesto di seguire solo i riferimenti ipertestuali rivolti alla stessa directory di partenza.

263.3   Particolarità nell'HTML

HTML2ps interpreta alcuni «comandi» speciali all'interno del file HTML. Si tratta di:

• salto pagina incondizionato, che si ottiene con uno dei comandi seguenti:

  <HR class=PAGE-BREAK>

  <?page-break>

  <!--NewPage-->

• esclusione di parte del testo dalla composizione stampata, attraverso un elemento DIV speciale:

  <DIV class=NOPRINT>
      ...
      <!-- Testo che viene ignorato da HTML2ps -->
      ...
  </DIV>

263.4   Programma frontale per semplificare l'utilizzo di HTML2ps

Assieme a HTML2ps si dovrebbe trovare un programma aggiuntivo che facilita il suo utilizzo attraverso un pannello grafico. Si tratta dell'eseguibile xhtml2ps, che si vede in particolare nella figura 263.1. Il suo utilizzo dovrebbe essere intuitivo, dal momento che si rifà alle opzioni delle riga di comando.

Figura 263.1. Programma frontale per il controllo di HTML2ps.

La figura mostra una versione imperfetta, in cui i bottoni non sono allineati con le descrizioni. Probabilmente questo problema sarà corretto nelle prossime versioni.

263.5   Riferimenti

• Jan Kärrman, Using html2ps

Appunti di informatica libera 2003.01.01 --- Copyright © 2000-2003 Daniele Giacomini -- daniele @ swlibero.org

---

1) HTML2ps   GNU GPL