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.
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>, ...
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/questo testo in grassetto/, ...
che racchiude il testo in grassetto all'interno delle barre (/).
(Ovviamente sarà necessario usare la forma estesa se il testo
racchiuso contiene barre, come nel caso dei nome dei file Unix).
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
).
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><pippo></tt>.
Generalmente, tutto quello che inizia con una &, e commerciale,
è un carattere speciale. Per esempio, c'è %
per produrre il carattere %, |
per produrre il
carattere | e così via. Ogni ``carattere speciale'' che
potrebbe confondere LinuxDoc-Tools se inserito direttamente ha una
``entità'' che inizia con & che lo rappresenta.
Le più comunemente usate sono:
&
per la e commeciale (&),<
per la parentesi sinistra (<),>
per la parentesi destra (>),&etago;
per la parentesi sinistra con barra
(</
),$
per il simbolo dollaro ($),#
per il cancelletto (#),%
per il simbolo percentuale (%),˜
per la tilde (~),``
e ''
per le virgolette, o usare
&dquot
per ".­
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.
frazione 1/2 verticale
frazione 1/2 tipografica
frazione 1/4 tipografica
frazione 3/4 tipografica
frazione 1/8 tipografica
frazione 3/8 tipografica
frazione 5/8 tipografica
frazione 7/8 tipografica
1 in esponente
2 in esponente
3 in esponente
segno più
segno più-o-meno
segno minore di
segno uguale
segno maggiore di
segno divisione
segno moltiplicazione
simbolo valuta
simbolo sterlina
segno dollaro
segno centesimi
segno yen
numero o segno cancelletto
segno percentuale
e commerciale
asterisco
segno a commerciale (chiocciola)
parentesi quadra sinistra
backslash
parentesi quadra destra
parentesi graffa sinistra
barra orizzontale
barra verticale
parentesi graffa destra
mu greca (prefisso micro)
omega greco maiuscolo (segno Ohm)
piccolo segno circolare in esponente (segno grado)
ordinale maschile
ordinale femminile
segno sezione
segno paragrafo
punto centrato
freccia sinistra
freccia destra
freccia su
freccia giù
copyright
segno r-in-cerchio
segno trademark
barra verticale interrotta
segno negazione logica
segno nota musicale
punto esclamativo
punto esclamativo invertito
doppie virgolette
apostrofo (singola virgoletta)
parentesi sinistra
parentesi destra
virgola
barra inferiore
trattino
punto
barra obliqua
due punti
punto e virgola
punto interrogativo
punto interrogativo invertito
virgolette caporali sinistre
virgolette caporali destre
singola virgoletta sinistra
singola virgoletta destra
doppie virgolette siniste
doppie virgolette destre
spazio indivisibile (non-breaking space)
trattino sillabazione invisibile
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
.
&ero;
per ottenere la e commerciale.&etago;
per ottenere <
/.\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.
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.
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
.
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.
Alla fine del documento, si deve usare il tag:
</article>
per comunicare all'analizzatore che è finito l'elemento
article
(che racchiude l'intero documento).
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">
È poi possibile riferirsi a quella sezione in qualsiasi punto 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 LinuxDoc-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 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.
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.
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.
Equivalente a:
Ecco un <tt/testo typewriter/ da includere nel documento.
Ricordare che è possibile usare la 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 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.
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ì:
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ì:
Piccola fastidiosa creatura che vola nella propria ventola di raffreddamento.
Piccola fastidiosa creatura che viaggia nella propria CPU.
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>.
Qualsiasi cosa tra questo tag <#if> e il seguente </#if>
è considerata condizionata e non verrà inclusa nel documento nel
caso in cui, o l'opzione di filtro ``output'' sia stata impostata a qualcosa
che non corrisponde a ``latex2e'' oppure se l'opzione di filtro ``version''
sia stata impostata a qualcosa che non corrisponde a ``drlinux''. La doppia
negazione è intenzionale; se nessuna opzione di filtro ``output'' o
``version'' è impostata, il testo condizionato sarà incluso.
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
o
% Linuxdoc -B latex pippo.sgml
includerebbe la parte ``condizionata'', ma né
% linuxdoc -B html -D version=drlinux pippo.sgml
né
% linuxdoc -B latex -D private=book pippo.sgml
la includerebbe.
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.
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>.
Al fine di ottenere l'appropriata giustificazione e il riempimento dei paragrafi nell'output per la stampa tipografica, LinuxDoc-Tools include l'entità ­. 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.