Avanti Indietro Indice

3. Scrittura di documenti con SGML-Tools

Per la maggior parte la scrittura di documenti con l'SGML-Tools DTD è molto semplice, e abbastanza simile a LaTeX. Tuttavia ci sono alcuni particolari a cui fare attenzione. In questa sezione viene fornita un'introduzione sulla scrittura di documenti SGML. Vedere il file esempio.sgml per un documento SGML di esempio (ed esercitazione) che si può usare come modello nella scrittura dei propri documenti. In questa sezione discuterò solamente le varie caratteristiche di SGML, ma il sorgente non è molto leggibile come esempio. Invece sarebbe meglio stampare il sorgente (come anche il testo formattato) dell'esempio.sgml per avere un caso reale a cui fare riferimento.

3.1 Concetti base

Osservando il sorgente del documento di esempio si nota subito la presenza di vari "tag" racchiusi tra parentesi angolari (< e >). Un tag specifica semplicemente l'inizio o la fine di un elemento, dove per elemento si intende una sezione, un paragrafo, una parte di testo di una frase in corsivo, una voce di una lista e così via. Usare un tag è simile ad usare un comando di LaTeX come \item o \section{...}.

Come semplice esempio, per produrre un testo in grassetto, ho scritto:

Come semplice esempio, per produrre <bf>un testo in grassetto</bf>, ...
nel sorgente. <bf> inizia una regione di testo evidenziato in grassetto e </bf> la conclude. In alternativa si può usare la forma abbreviata:

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

che racchiude il testo da evidenziare all'interno delle barre (/). (Naturalmente sarà necessario usare la forma estesa se il testo racchiuso contiene barre, come nel caso dei nomi di file Unix.)

Ci sono altre cose a cui fare attenzione riguardo ai caratteri speciali (questo perché, se si guarda il sorgente, si possono notare tutte queste espressioni della & (e commerciale) dall'aspetto bizzarro; che verranno spiegate fra poco).

In alcuni casi il tag finale di un particolare elemento è opzionale. Per esempio, per iniziare una sezione, usare il tag <sect>, tuttavia il tag finale per la sezione (che dovrebbe apparire alla fine del corpo della sezione stessa, non solo 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 il modello usato nell'esercitazione (esempio.sgml).

3.2 Caratteri speciali

Ovviamente le parentesi angolari sono anch'essi caratteri speciali nel sorgente SGML. Ce ne sono altri a cui prestare attenzione. Per esempio si supponga di voler scrivere un'espressione racchiusa tra parentesi angolari, come: <foo>. Per ottenere le parentesi angolari, si deve usare l'elemento &lt;, che è una macro che si espande nel corretto carattere di parentesi sinistra. Perciò nel sorgente, ho scritto 

un'espressione racchiusa tra parentesi angolari, come: <tt>&lt;foo></tt>.
Generalmente, tutto quello che inizia con una & (e commerciale) è una macro speciale. Per esempio, c'è &percnt; per produrre %, &verbar; per produrre |, e così via. Per tutti i "caratteri speciali" esistono queste entità-e_commerciale per rappresentarli.

Normalmente non è necessario usare la macro "e commerciale" per ottenere un carattere speciale, tuttavia in alcuni casi è necessaria. Le più comunemente usate sono:

Per una lista completa di caratteri speciali guardare uno dei file di sostituzione. Generalmente LaTeX si lamenta molto dei caratteri speciali, quindi $LINUXDOCLIB/rep/latex/general dovrebbe essere una buona locazione per iniziare. $LINUXDOCLIB \ definita all'inizio degli script di conversione SGML.

3.3 Ambienti Verbatim e Code

Mentre si sta trattando l'argomento dei caratteri speciali, vorrei menzionare anche l'"ambiente" verbatim, usato per includere testo letterale in uscita (che preserva spazi, indentazione e così via). L'elemento verb è usato per questo scopo; esso appare come il seguente:

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

L'ambiente verb non permette di usare ogni cosa al suo interno letteralmente. Nel caso specifico si devono fare le seguenti cose all'interno dell'ambiente verb.

L'ambiente code è molto simile all'ambiente verb, tranne per l'aggiunta di due linee orizzontali che racchiudono il testo, come:

Un esempio di ambiente code.

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

<tscreen><verb>
Qui c'è un po' di testo d'esempio.
</verb></tscreen>

tscreen è un ambiente che semplicemente indenta il testo e imposta i font predefiniti a tt. Questo rende l'aspetto degli esempi più piacevole, sia nella versione LaTeX che in quella di testo semplice. È possibile usare tscreen senza verb, tuttavia se si usano caratteri speciali negli esempi è necessario usarli entrambi. tscreen non fa nulla sui caratteri speciali. Vedere esempio.sgml per degli esempi.

L'ambiente quote è simile a tscreen, tranne per il fatto che non imposta i font predefiniti 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 globale del documento

Prima di entrare troppo nei dettagli, descriverò la struttura complessiva di un documento come definita dal Linuxdoc-SGML DTD. 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 Foo HOWTO
<author>Norbert Ebersol, <tt/norb@baz.com/
<date>v1.0, 9 Marzo 1994
<abstract>
Questo documento descrive come usare gli strumenti <tt/foo/ per frobnicare
le librerie bar, usando il relinker <tt/xyzzy/.
</abstract>

<toc>

Gli elementi dovrebbero essere disposti praticamente in questo ordine. La prima linea comunica all'analizzatore SGML di usare il Linuxdoc DTD. Il tag <article> forza il documento ad usare lo stile "article" (articolo). (L'originale QWERTZ DTD definisce anche gli stili "report" e "book"; che non sono stati inclusi per l'uso con SGML-Tools).

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 imposta il testo che viene stampato all'inizio del documento, prima dell'indice. Se non si vuole includere l'indice (il tag toc), probabilmente non sarà necessario un abstract.

Sezioni e paragrafi

Dopo il preambolo, è giunto il momento per "tuffarsi" nel documento. Sono disponibili i seguenti comandi di sezione:

Questi sono approssimativamente equivalenti ai corrispondenti comandi di LaTeX section, subsection e così via.

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

<sect>Introduzione

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>, come in:

<sect>Introduzione
<p>
Questa &egrave; la guida dell'utente al sistema di eleborazione 
documenti SGML-Tools ...

Questo serve per comunicare all'analizzatore che il titolo della sezione è concluso e si può iniziare il corpo della sezione. Quindi i nuovi paragrafi iniziano con una linea vuota (proprio come si dovrebbe fare in TeX). Per esempio,

Questa &egrave; la fine del primo paragrafo.

E qui inizia un nuovo paragrafo.

Non c'è alcun motivo per usare il tag <p> all'inizio di ogni paragrafo; è necessario solo all'inizio del primo paragrafo dopo il comando di sezione.

Fine del documento

Alla fine del documento, si deve usare il tag:

</article>

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

3.5 Riferimenti incrociati

Adesso andremo a esplorare altre caratteristiche del sistema. I riferimenti incrociati sono semplici da usare. Per esempio se si vuole creare un riferimento ad una certa sezione è necessario "etichettare" quella sezione:

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

Poi, è possibile riferisi a quella sezione in qualsiasi parte del testo usando l'espressione:

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

Questo sostituirà il tag ref con il numero della sezione etichettata come sez-intro. L'argomento name di ref è necessario per la conversione in groff e HTML. Attualmente Il set di macro per groff usate da SGML-Tools non supporta i riferimenti incrociati, e spesso è più carino riferirsi ad una sezione per nome invece che per numero.

Per esempio, questa sezione è Riferimenti Incrociati.

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

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

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

Per esempio, è possibile prelevare il pacchetto SGML-Tools da
ftp://sunsite.unc.edu/pub/Linux/utils/text/sgml-tools-0.99.0.tar.gz.

Un'utile variante di questo elemento è htmlurl, che sopprime la visualizzazione della parte URL in ogni contesto eccetto HTML. Questo è utile per 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 prodotto in uscita invece del duplicato "esr@snark.thyrsus.com <mailto:esr@snark.thyrsus.com>", ma avere ancora un appropriato URL nei documenti HTML.

3.6 Font

Essenzialmente, gli stessi font supportati da LaTeX sono supportati anche da SGML-Tools. Notare, comunque, che la conversione in testo semplice (tramite groff) ignora le informazioni dei font. Perciò si dovrebbero usare i font più possibile, a beneficio della conversione in LaTeX. Ma, nella conversione al testo semplice, non c'è alcun vantaggio ad usare i font.

In particolare, il tag tt descritto precedentemente può essere usato per ottenere font a larghezza costante "typewriter", che dovrebbe essere usato per indirizzi email, nomi di macchine, nome di file e così via. Esempio:

Qui c'&egrave; un po' di <tt>testo typewriter</tt> da includere 
nel documento.

che è equivalente a:

Qui c'&egrave; un po' di <tt/testo typewriter/ da includere nel documento.

Ricordare che è possibile usare questa forma abbreviata solo se il testo racchiuso non contiene barre.

Altri font possono essere selezionati con bf per il grassetto e em per il corsivo. Sono supportati diversi altri font, ma non consiglio di usarli, perché convertendo questi documenti in altri formati, come HTML, potrebbero non essere supportati. Grassetto, corsivo e typewriter dovrebbero essere tutti quelli necessari.

3.7 Elenchi

Ci sono vari tipi di elenchi supportati. Essi sono:

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

<itemize>
<item>Questa &egrave; una voce.
<item>Questa &egrave; una seconda voce.
</itemize>

appare come questa

O, per una enum,

<enum>
<item>Questa &egrave; la prima voce.
<item>Questa &egrave; la seconda voce.
</enum>

Adesso si ha un'idea. Gli elenchi possono essere nidificati; guardare il documento di esempio per dettagli.

Un elenco descrip è leggermente diverso, e leggermete complicato, ma si dovrebbe usare per alcune situazioni:

<descrip>
<tag/Gnats./ Piccolo fastidioso insetto che vola nella ventola di
raffreddamento.
<tag/Gnus./ Piccolo fastidioso insetto che viaggia nella CPU.
</descrip>

3.8 Ulteriori informazioni

Avanti Indietro Indice