Precedente Successivo Indice

3. Scrittura di Documenti con Linuxdoc-SGML

Per la gran parte, la scrittura di dicumenti con il Linuxdoc-SGML DTD è molto semplice, e abbastanza simile a LaTeX. Comunque ci sono alcune cose da vedere. In questa sezione viene data un'introduzione sulla scrittura di documenti SGML. Guardate il file esempio.sgml per un documento SGML di esempio (ed esercitazione) che potete usare come modello nella scrittura dei vostri documenti. Qui discuterò le varie caratteristiche di SGML, ma il sorgente non è molto leggibile come esempio. Invece, stampatevi il sorgente (come anche il testo formattato) di esempio.sgml per avere un caso reale a cui fare riferimento.

3.1 Concetti Base

Guardando il sorgente del documento di esempio, potete notare che ci sono varie ``etichette'' segnate con parentesi angolari (< e >). Una etichetta specifica semplicemente l'inizio o la fine di un elemento, dove un elemento è spesso una sezione, un paragrafo, una frase in italico (corsivetto), una voce di una lista e così via. L'uso delle etichette è simile all'uso dei comandi LaTeX come \item o \section{...}.

Come semplice esempio, per produrre un testo in grassetto, si scrive

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 potete usare la forma abbreviata

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

che racchiude il testo da evidenziare senza barre. (Ovviamente è necessario usare la forma estesa se il testo racchiuso contiene barre, come nel caso dei filename Unix.)

Ci sono altre cose da vedere sui caratteri speciali (questo perché si possono notare questi caratteri speciali se si guarda il sorgente; ne parlerò tra breve).

In alcuni casi, l'etichetta di fine di un particolare elemento è opzionale. Per esempio, per iniziare una sezione, usare l'etichetta <sect>, comunque, l'etichetta di fine 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; semplicemente seguire il modello dell'esercitazione (esempio.sgml).

3.2 Caratteri Speciali

Ovviamente, le parentesi angolari sono anch'essi caratteri speciali nel sorgente SGML. Ce ne sono altri da guardare. Per esempio, diciamo di voler scrivere un'espressione con 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. Quindi, nel sorgente, io scrivo

un'espressione con 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. Ogni ``carattere speciale'' è rappresentabile tramite queste macro.

Generalmente non è necessario usare queste macro per ottenere un carattere speciale, comunque, in molti casi si è obbligati. Le più comunemente usate sono:

Per una lista completa di caratteri speciali, guardate uno dei file di sostituzione. Generalmente LaTeX soffre molto di caratteri speciali, quindi dare un'occhiata a $LINUXDOCLIB/rep/latex/general è un buon posto per iniziare. $LINUXDOCLIB è definita all'inizio degli script di conversione SGML.

3.3 Ambienti Testuali e Codice

Visto che siamo in argomento di caratteri speciali, voglio parlare anche di ``ambienti'' testuali, usati per includere testo letterale (preservando spazi, indentazione e così via). L'elemento verb è usato per questo; esso appare come il seguente:

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

L'ambiente verb non permette di usare tutto in esso letterariamente. Nel caso specifico, dovete fare quello che segue con l'ambiente verb.

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

Un esempio di ambiente codice.

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

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

tscreen è un ambiente che ha il testo semplicemente indentato e carattere di default tt. Questo rende gli esempi molto carini, sia nella versione LaTeX sia in testo semplice. Potete usare tscreen senza verb, comunque se usate 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 che non imposta il carattere a tt. Così potete 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 andare troppo in dettagli, descrivo la struttura generale di un documento come definita dal Linuxdoc-SGML DTD. Vedere esempio.sgml per un buon esempio di come è impostato un documento.

I Preliminari

Nei ``preliminari'' del documento si impostano alcune cose, come informazioni sul titolo e stile del documento. Per un documento Linux HOWTO questo dovrebbe essere:

<!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 frobnicate
le librerie bar, usando il relinker <tt/xyzzy/.
</abstract>

<toc>

Gli argomenti dovrebbero essere più o meno in questo ordine. La prima linea dice all'analizzatore SGML di usare il Linuxdoc-SGML DTD. L'etichetta <article> forza il documento ad assumere lo stile ``articolo''. (L'originale QWERTZ DTD definisce anche ``report'' e ``book''; non ho incluso questi per l'uso con Linuxdoc-SGML).

Le etichette title (titolo), author (autore), date (data) dovrebbero essere ovvie; l'etichetta date include il numero di versione e la data dell'ultima modifica del documento.

L'etichetta abstract imposta il testo che viene stampato in testa al documento, prima dell'indice. Se non volete includere l'indice (l'etichetta toc), probabilmente non avete bisogno di un abstract. Suggerisco che tutti i Linux HOWTO usino questo formato comune per i preliminari, in modo che titolo, riassunto e indice appaiano tutti allo stesso modo.

Sezioni e Paragrafi

Dopo i preliminari, siete pronti per tuffarvi nel documento. Sono disponibili i seguenti comandi di sezione:

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

Dopo l'etichetta sect (o sect1, sect2, ecc.) viene il come della sezione. Per esempio, all'inizio di questo documento, dopo i preliminari, c'è l'etichetta:

<sect>Introduzione

All'inizio di questa sezione (Sezioni e Paragrafi), c'è l'etichetta:

<sect2>Sezioni e Paragrafi

Dopo l'etichetta della sezione inizia il corpo della sezione. Si deve iniziare il corpo con un'etichetta <p>, come in:

<sect>Introduzione
<p>
Questa &egrave; la guida dell'utente al sistema Linuxdoc-SGML...

Questo per comunicare all'analizzatore che il titolo della sezione è concluso e siete pronti ad iniziare il corpo. Indi i nuovi paragrafi iniziano con una linea vuota (come si fa in TeX). Per esempio,

Questa &egrave; la fine del primo paragrafo.

E qui inizia un nuovo paragrafo.

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

Chiusura del Documento

Alla fine del documento, si deve usare l'etichetta:

</article>

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

3.5 Riferimenti Incrociati

Adesso vediamo un'altra caratteristica del sistema. I riferimenti incrociati sono semplici. Per esempio, se volete creare un riferimento ad una certa sezione, è necessario etichettare quella sezione:

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

Potete riferirvi a quella sezione in qualsiasi posto del testo usando l'espressione:

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

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

Per esempio, questa sezione è la Riferimenti Incrociati.

Ci sono anche elementi url (per Universal Resource Locators, o URL), usati nel World Wide Web. Questi elementi dovrebbero essere usati per riferirsi ad altri documenti, file disponibili via 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 url specifica l'attuale URL stesso. Un link all'URL in questione sarà automaticamente aggiunto al documento HTML. L'argomento opzionale name specifica il testo che deve 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.

Per esempio, potete prelevare il pacchetto Linuxdoc-SGML da
ftp://sunsite.unc.edu/pub/Linux/utils/text/linuxdoc-sgml-1.5.tar.gz.

Un'utile variante di questo è htmlurl, che sopprime la visualizzazione della parte URL in ogni contesto eccetto HTML. Questo è utile per gli indirizze email; potete scrivere:

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

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

3.6 Caratteri

Essenzialmente, gli stessi caratteri supportati da LaTeX sono supportati da Linuxdoc-SGML. Notare comunque che la conversione in testo semplice (tramite groff) ignora le informazioni sui caratteri. Così dovreste usare i caratteri più possibile, per i benefici della conversione in LaTeX, anche se non sono utilizzati nella versione testo semplice.

In particolare, l'etichetta tt descritta sopra può essere usata per ottenere il carattere a larghezza costante ``typewriter'', che dovrebbe essere usato per indirizzi email, nomi di macchine, filename e così via. Esempi:

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

equivalente a

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

Ricordatevi che potete usare la forma abbreviata solo se il testo racchiuso non contiene barre.

Altri caratteri possono essere selezionati con bf per il grassetto e em per l'italico. Sono supportati diversi altri caratteri, ma non suggerisco di usarli in quanto nella conversione in altri formati, come HTML, potrebbero non essere supportati. Grassetto, italico e typewriter dovrebbero essere i più necessari.

3.7 Liste

Ci sono vari tipi di liste supportate. Esse sono:

Ogni voce in itemize ed enum deve essere marcata con un'etichetta item. Le voci di una lista descript sono marcate con 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 avete un'idea. Le liste possono essere nidificate; guardate il documento di esempio per dettagli.

Una lista descrip è leggermente diversa, e leggermete complicata, 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

Precedente Successivo Indice