3. Scrittura di documenti con SGML-Tools

Per la maggior parte, la scrittura di documenti usando SGML-Tools è molto semplice e abbastanza simile alla scrittura dell'HTML. Comunque ci sono alcune cose a cui fare attenzione. In questa sezione viene fornita un'introduzione sulla scrittura di documenti SGML. Guardare il file esempio.sgml per un documento SGML di esempio (e di guida) che si può usare come modello nella scrittura dei propri documenti. Qui si discuterranno le varie caratteristiche di LinuxDoc-Tools, ma il sorgente non è molto leggibile come esempio. Piuttosto, stampare il sorgente (come anche l'output formattato) di esempio.sgml per avere un caso reale a cui riferirsi.

3.1 Concetti di base

Osservando il sorgente del documento di esempio, si nota subito che ci sono vari "tag" marcati all'interno di parentesi angolari (< e >). Un tag specifica semplicemente l'inizio o la fine di un elemento, dove un elemento può essere una sezione, un paragrafo, una frase in corsivo, una voce di una lista e così via. Usare un tag è come usare un tag in HTML o un comando di LaTeX, come per esempio \item o \section{...}.

Come semplice esempio, per produrre questo testo in grassetto, si dovrebbe scrivere:

Come semplice esempio, per produrre <bf>questo testo in grassetto</bf>, ...

Come semplice esempio, per produrre <bf/questo testo in grassetto/, ...

Ci sono altre cose a cui fare attenzione per ciò che riguarda i caratteri speciali (e questo è il motivo per cui si possono notare tutte queste espressioni con il simbolo &, apparentemente bizzarre, se si guarda il sorgente. Verranno spiegate tra breve).

In alcuni casi, il tag finale di un particolare elemento è opzionale. Per esempio, per iniziare una sezione, si usa il tag <sect>, comunque il tag finale per la sezione (che dovrebbe apparire alla fine del corpo della sezione stessa, non subito dopo il nome della sezione!) è opzionale e implicito quando si inizia un'altra sezione dello stesso livello. In generale non c'è da preoccuparsi per questi dettagli; basta seguire semplicemente il modello dell'esercitazione (esempio.sgml).

3.2 Caratteri speciali

Ovviamente, le parentesi angolari sono anch'esse caratteri speciali nel sorgente SGML. Ce ne sono altri a cui fare attenzione. Se per esempio si vuole scrivere un'espressione racchiusa tra parentesi angolari, come: <pippo>. Per ottenere la parentesi angolare sinistra, si deve usare l'elemento <, che è una macro che si espande nel corretto carattere di parentesi sinistra. Quindi, nel sorgente, si scriverà

un'espressione racchiusa tra parentesi angolari, come: 
<tt>&lt;pippo&gt;</tt>.

• usare & per la e commeciale (&),
• usare < per la parentesi sinistra (<),
• usare > per la parentesi destra (>),
• usare &etago; per la parentesi sinistra con barra (</),
• usare $ per il simbolo dollaro ($),
• usare # per il cancelletto (#),
• usare % per il simbolo percentuale (%),
• usare ˜ per la tilde (~),
• usare `` e '' per le virgolette, o usare &dquot per ".
• Usare ­ per un trattino invisibile (che è un'indicazione che questo è un buon punto per spezzare una parola per la giustificazione orizzontale).

Di seguito è fornita una lista completa delle "entità" riconosciute dalla versione 1.0.x di SGML-Tools. Si noti che non tutti i back-end saranno in grado di fare qualcosa di utile da ogni entità; se si vedono delle parentesi che non hanno niente al loro interno, questo significa che il back-end che ha generato il testo che si sta osservando non ha modo di sostituire l'entità. Le entità comuni elencate sopra sono piuttosto sicure.

&half (1/2)

frazione 1/2 verticale

&frac12 (1/2)

frazione 1/2 tipografica

&frac14 (1/4)

frazione 1/4 tipografica

&frac34 (3/4)

frazione 3/4 tipografica

&frac18 (1/8)

frazione 1/8 tipografica

&frac38 (3/8)

frazione 3/8 tipografica

&frac58 (5/8)

frazione 5/8 tipografica

&frac78 (7/8)

frazione 7/8 tipografica

&sup1 (^1)

1 in esponente

&sup2 (^2)

2 in esponente

&sup3 (^3)

3 in esponente

&plus (+)

segno più

&plusmn (±)

segno più-o-meno

&lt (<)

segno minore di

&equals (=)

segno uguale

&gt (>)

segno maggiore di

&divide (÷)

segno divisione

&times (×)

segno moltiplicazione

&curren (¤)

simbolo valuta

&pound (£)

simbolo sterlina

&dollar ($)

segno dollaro

&cent (¢)

segno centesimi

&yen (¥)

segno yen

&num (#)

numero o segno cancelletto

&percnt (%)

segno percentuale

&amp (&)

e commerciale

&ast (*)

asterisco

&commat (@)

segno a commerciale (chiocciola)

&lsqb ([)

parentesi quadra sinistra

&bsol (\)

backslash

&rsqb (])

parentesi quadra destra

&lcub ({)

parentesi graffa sinistra

&horbar (―)

barra orizzontale

&verbar (|)

barra verticale

&rcub (})

parentesi graffa destra

&micro (µ)

mu greca (prefisso micro)

&ohm (Ω)

omega greco maiuscolo (segno Ohm)

&deg (°)

piccolo segno circolare in esponente (segno grado)

&ordm (º)

ordinale maschile

&ordf (ª)

ordinale femminile

&sect (§)

segno sezione

&para (¶)

segno paragrafo

&middot (·)

punto centrato

&larr (<-)

freccia sinistra

&rarr (->)

freccia destra

&uarr (-^)

freccia su

&darr (-v)

freccia giù

&copy (©)

copyright

&reg (®)

segno r-in-cerchio

&trade ((TM))

segno trademark

&brvbar (¦)

barra verticale interrotta

&not (¬)

segno negazione logica

&sung (♪)

segno nota musicale

&excl (!)

punto esclamativo

&iexcl (¡)

punto esclamativo invertito

&quot (")

doppie virgolette

&apos (')

apostrofo (singola virgoletta)

&lpar (()

parentesi sinistra

&rpar ())

parentesi destra

&comma (,)

virgola

&lowbar (_)

barra inferiore

&hyphen (-)

trattino

&period (.)

punto

&sol (/)

barra obliqua

&colon (:)

due punti

&semi (;)

punto e virgola

&quest (?)

punto interrogativo

&iquest (¿)

punto interrogativo invertito

&laquo («)

virgolette caporali sinistre

&raquo (»)

virgolette caporali destre

&lsquo (‘)

singola virgoletta sinistra

&rsquo (’)

singola virgoletta destra

&ldquo (“)

doppie virgolette siniste

&rdquo (”)

doppie virgolette destre

&nbsp ( )

spazio indivisibile (non-breaking space)

&shy (­)

trattino sillabazione invisibile

3.3 Ambienti Verbatim e Code

Dato che siamo in argomento di caratteri speciali, tanto vale menzionare anche l'``ambiente'' verbatim, usato per includere testo letterale nell'output (preservando spazi, rientri e così via). L'elemento verb è usato per questo scopo; esso appare come segue:

<verb>
        Un po' di testo letterale da includere come output di esempio.
</verb>

L'ambiente verb non permette di usare tutto in esso letteralmente. In particolare, si deve fare quello che segue con l'ambiente verb.

• Usare &ero; per ottenere la e commerciale.
• Usare &etago; per ottenere </.
• Non usare \end{verbatim} dentro ad un ambiente verb, in quanto in LaTeX viene usato per chiudere l'ambiente verbatim. (In futuro, sarà possibile nascondere l'intera sottostante formattazione del testo, ma per adesso l'analizzatore non supporta ancora questa funzione).

L'ambiente code (codice) è molto simile all'ambiente verb, eccetto per l'aggiunta di due linee orizzontali intorno al testo, come in:

Un esempio di ambiente code.

Si dovrebbe usare l'ambiente tscreen attorno ogni ambiente verb, come in:

<tscreen><verb>
Un testo di esempio.
</verb></tscreen>

tscreen è un ambiente che semplicemente ha il testo rientrato e carattere predefinito tt. Questo rende gli esempi molto carini, sia nella versione LaTeX sia in testo semplice. È possibile usare tscreen senza verb, comunque se si usano caratteri speciali negli esempi è necessario usarli entrambi. tscreen non fa nulla sui caratteri speciali. Vedere esempio.sgml per un esempio.

L'ambiente quote è simile a tscreen, eccetto per il fatto che non imposta il carattere predefinito a tt. Così si può usare quote per citazioni che non riguardano l'interazione con il computer, come in:

<quote>
Un po' di testo rientrato, come nelle citazioni.
</quote>

che genererà:

Un po' di testo rientrato, come nelle citazioni.

3.4 Struttura generale del documento

Prima di andare troppo a fondo nei dettagli, verrà descritta la struttura generale di un documento di LinuxDoc-Tools. Vedere esempio.sgml per un buon esempio di come è impostato un documento.

Il preambolo

Nel "preambolo" del documento si impostano alcune cose, come informazioni sul titolo e lo stile del documento:

<!doctype linuxdoc system>

<article>

<title>Linux Pippo HOWTO
<author>Norbert Ebersol, <tt/norb@baz.com/
<date>v1.0, 9 Marzo 1994
<abstract>
Questo documento descrive come usare gli strumenti <tt/pippo/ per smanettare
le librerie pluto, usando il relinker <tt/xyzzy/.
</abstract>

<toc>

Gli elementi dovrebbero essere disposti più o meno in questo ordine. La prima riga comunica all'analizzatore SGML di usare il DTD linuxdoc. Questo verrà spiegato in una successiva sezione su Come funziona LinuxDoc-Tools; per ora basta trattarlo con un po' di magia necessaria. Il tag <article> forza il documento ad assumere lo stile ``article'' (articolo).

I tag title (titolo), author (autore), date (data) dovrebbero essere ovvi; il tag date include il numero di versione e la data dell'ultima modifica del documento.

Il tag abstract (compendio) imposta il testo che viene stampato nella parte superiore del documento, prima dell'indice. Se non si include un indice (il tag toc), probabilmente non sarà necessario un abstract.

Sezioni e Paragrafi

Dopo il preambolo, si è pronti per "tuffarsi" dentro il documento. Sono disponibili i seguenti comandi per creare sezioni:

• sect: per sezioni principali (cioè 1, 2 e così via).
• sect1: per sottosezioni di secondo livello (cioè 1.1, 1.2 e così via).
• sect2: per sottosottosezioni di terzo livello.
• sect3: per sottosottosottosezioni di quarto livello.
• sect4: per sottosottosottosottosezioni di quinto livello.

Questi sono approssimativamente equivalenti alle loro controparti LaTeX section, subsection e così via.

Dopo il tag sect (o sect1, sect2, ecc.) segue il nome della sezione. Per esempio, all'inizio di questo documento, dopo il preambolo, c'è il tag:

<sect>Introduzione

E, all'inizio di questa sezione (Sezioni e paragrafi), c'è il tag:

<sect2>Sezioni e paragrafi

Dopo il tag della sezione inizia il corpo della sezione. Comunque, si deve iniziare il corpo con un tag <p>, così:

<sect>Introduzione
<p>
Questa è la guida dell'utente al sistema di elaborazione documenti 
LinuxDoc-Tools...

Questo serve per comunicare all'analizzatore che il titolo della sezione è concluso e si è pronti ad iniziarne il corpo del testo. Da qui in poi i nuovi paragrafi iniziano con una linea vuota (come si farebbe in TeX). Per esempio:

Questa è la fine del primo paragrafo.

E qui inizia un nuovo paragrafo.

Non ci sono motivi per usare i tag <p> all'inizio di ogni paragrafo; è necessario solo all'inizio del primo paragrafo dopo il comando di sezione.

Chiusura del documento

Alla fine del documento, si deve usare il tag:

</article>

per comunicare all'analizzatore che è finito l'elemento article (che racchiude l'intero documento).

3.5 Riferimenti incrociati interni

Adesso vedremo altre caratteristiche del sistema. I riferimenti incrociati sono semplici. Per esempio, se si vuole creare un riferimento ad una certa sezione, è necessario fornire un'etichetta a quella sezione:

<sect1>Introduzione<label id="sez-intro">

Vedere la sezione <ref id="sez-intro" name="Introduzione"> per una
introduzione.

Per esempio, questa sezione è Riferimenti incrociati interni.

Alcuni back-end possono essere disturbati da caratteri speciali nelle etichette dei riferimenti. In particolare, latex2e si blocca alle linee di sottolineatura (anche se il back end di latex usato nelle vecchie versioni di questo pacchetto non lo faceva). L'uso dei trattini è sicuro.

3.6 Riferimenti web

C'è anche l'elemento url per Universal Resource Locator, o URL, usato nel World Wide Web. Questo elemento dovrebbe essere usato per riferirsi ad altri documenti, file disponibili attraverso FTP e così via. Per esempio,

Si possono prelevare i documenti Linux HOWTO da
<url url="http://sunsite.unc.edu/mdw/HOWTO/" name="The Linux HOWTO INDEX">.

L'argomento url specifica l'URL reale stesso. Un link all'URL in questione sarà automaticamente aggiunto al documento HTML. L'argomento opzionale name specifica il testo che dovrebbe essere ancorato all'URL (per la conversione HTML) o il nome per la descrizione dell'URL (per LaTeX e groff). Se manca l'argomento name, verrà usato l'URL stesso.

Un'utile variante di questo è htmlurl, che sopprime la visualizzazione della parte URL in ogni contesto eccetto HTML. Questo è utile per cose come gli indirizzi email; si può scrivere:

<htmlurl url="mailto:esr@snark.thyrsus.com" name="esr@snark.thyrsus.com">

e ottenere ``esr@snark.thyrsus.com'' nel testo di output invece del duplice ``esr@snark.thyrsus.com <mailto:esr@snark.thyrsus.com>'', ma avere ancora un corretto URL nei documenti HTML.

3.7 Tipi di carattere

Essenzialmente, gli stessi tipi di carattere supportati da LaTeX sono supportati da LinuxDoc-Tools. Si noti, comunque, che la conversione in testo semplice (tramite groff) ignora le informazioni sui caratteri. Così i tipi di carattere si dovrebbero usare soprattutto per i benefici della conversione in LaTeX, anche se non si dorebbe fare affidamento su di essi per veicolare informazioni nella versione in testo semplice.

In particolare, il tag tt descritto sopra può essere usato per ottenere il carattere a larghezza fissa ``typewriter'', che dovrebbe essere usato per indirizzi email, nomi di macchine, nomi di file e così via. Esempio:

Ecco un <tt>testo typewriter</tt> da includere nel documento.

Ecco un <tt/testo typewriter/ da includere nel documento.

Altri font possono essere selezionati con bf per il grassetto e em per il corsivo. Sono supportati diversi altri tipi di carattere, ma non si consiglia di usarli in quanto nella conversione in altri formati, come HTML, potrebbero non essere supportati. Grassetto, corsivo e typewriter dovrebbero essere tutto ciò di cui si ha bisogno.

3.8 Liste

Ci sono vari tipi di liste supportate. Essi sono:

• itemize per liste puntate come questa.
• enum per liste numerate.
• descrip per liste ``descrittive''.

Ogni voce in itemize o enum deve essere marcata con un tag item. Le voci di una lista descript sono marcate con tag. Per esempio,

<itemize>
<item>Questa è una voce.
<item>Questa è una seconda voce.
</itemize>

appare così:

• Questa è una voce.
• Questa è una seconda voce.

Oppure, per enum,

<enum>
<item>Questa è la prima voce.
<item>Questa è la seconda voce.
</enum>

Questa è l'idea generale. Le liste possono essere nidificate; si guardi il documento di esempio per ulteriori dettagli.

Una lista descrip è leggermente diversa e leggermente brutta, ma si potrebbe volerla usare in alcune situazioni:

<descrip>
<tag/Gnat./ Piccola fastidiosa creatura che vola nella propria ventola di
raffreddamento.
<tag/Gnu./ Piccola fastidiosa creatura che viaggia nella propria CPU.
</descrip>

finisce per apparire così:

Gnat.

Piccola fastidiosa creatura che vola nella propria ventola di raffreddamento.

Gnu.

Piccola fastidiosa creatura che viaggia nella propria CPU.

3.9 Uso di condizioni

L'obbiettivo principale di LinuxDoc-Tools è quello di essere capace di produrre da un insieme di file originali un output che sia semanticamente equivalente su tutti i back end. Tuttavia, qualche volta è utile essere capaci di produrre un documento in varianti lievemente differenti a seconda del back end e della versione. LinuxDoc-Tools supporta questo attraverso i tag <#if> e <#unless>.

Questi tag permettono di includere o non includere selettivamente porzioni di file originale SGML nel proprio output, a seconda delle opzioni di filtro impostate dal proprio driver. Ogni tag può includere un insieme di coppie attributo/valore. Le più comuni sono ``output'' e ``version'' (comunque non si è limitati a queste), così un tipico esempio potrebbe apparire come questo:

Parte di testo <#if output=latex2e 
version=drlinux>condizionato</#if>.

Le opzioni di filtro sono impostate in uno di due modi. Il proprio driver di formato imposta l'opzione ``output'' al nome del back end che usa; così, in particolare, ``linuxdoc -B latex'' imposta ``output=latex2e'', oppure si può impostare una coppia attributo-valore con l'opzione ``-D'' del proprio driver di formato. Così, se il tag precedente era parte di un file chiamato ``pippo.sgml'', allora formattare con uno tra i comandi:

% Linuxdoc -B latex -D version=drlinux pippo.sgml

% Linuxdoc -B latex pippo.sgml

% linuxdoc -B html -D version=drlinux pippo.sgml

% linuxdoc -B latex -D private=book pippo.sgml

Così si possono avere condizioni dipendenti dalla corrispondenza con uno o più valori diversi; i valori supportano una semplice sintassi per le alternative usando ``|''. Così si potrebbe scrivere:

Parte di testo <#if output="latex2e|html" 
version=drlinux>condizionata</#if>.

e formattando sia con ``-B latex'' che con ``-B html'' il testo ``condizionato'' sarà incluso (ma non lo sarà, per esempio, formattando con ``-B txt'').

Il tag <#unless> è l'esatto opposto di <#if>; esso include quando <#if>; escluderebbe e viceversa.

Si noti che questi tag sono implementati da un preprocessore che è eseguito prima ancora che l'analizzatore SGML veda il documento. Così questi tag sono completamente indipendenti dalla struttura del documento, non sono presenti nel DTD e gli errori d'uso non saranno colti dall'analizzatore. È possibile essere seriamente confusi dalle sezioni condizionate che contengono tag tra parentesi sbilanciati.

L'implementazione del preprocessore significa anche che analizzatori SGML autonomi si bloccheranno davanti a documenti LinuxDoc-Tools che contengono condizioni. Tuttavia, si può verificare la loro validità con ``linuxdoc -B check''.

Notare anche che, al fine di non confondere i numeri di riga del sorgente nei messaggi di errore dell'analizzatore, il preprocessore in realtà non getta via ogni cosa quando omette una sezione condizionata. Esso comunque passa ogni inizio di nuova riga. Questo porta ad un comportamento che può sorprendere se si usa <if> o <unless> all'interno di un ambiente <verb>, o ogni altra specie di parentesi che cambia il normale trattamento da parte di SGML degli spazi bianchi.

Questi tag sono chiamati ``#if'' e ``#unless'' (piuttosto che ``if'' e ``unless'') per ricordare che sono implementati da un preprocessore ed è necessario fare un po' di attenzione a come li si usa.

3.10 Generazione di indici

Per supportare la generazione automatica di indici per la pubblicazione di libri dagli originali SGML, LinuxDoc-Tools supporta i tag <idx> e <cdx>. Questi sono tag fra parentesi che fanno sì che il testo racchiuso tra di loro sia salvato come una voce dell'indice che punta al numero della pagina in cui appare nel documento formattato. Essi sono ignorati da tutti i backend eccetto LaTeX, che li usa per costruire un file .ind adatto per l'elaborazione con l'utilità makeindex di TeX.

I due tag si comportano in modo identico, eccetto che <idx> imposta la voce con un tipo di carattere normale e <cdx> in uno a spaziatura fissa.

Se si vuole aggiungere una voce d'indice che non dovrebbe apparire nel testo stesso, usare i tag <nidx> e <ncdx>.

3.11 Controllo della giustificazione

Al fine di ottenere l'appropriata giustificazione e il riempimento dei paragrafi nell'output per la stampa tipografica, LinuxDoc-Tools include l'entità &shy;. Questa diventa un trattino opzionale o `soft' nei back end come latex2e per i quali questo è significativo.

Il tag tra parentesi <file> può essere usato per racchiudere nomi di file nel corpo del testo. Esso inserisce in modo efficace trattini soft dopo ogni slash nel nome del file.

Uno dei vantaggi di usare i tag <url> e <htmlurl> è che essi fanno lo stesso per gli URL lunghi.