LinuxDoc è molto più facile da imparare rispetto a DocBook. Molto di ciò che si impara riguardo LinuxDoc, tuttavia, sarà utile anche per DocBook. Così, se eventualmente si decidesse di usare DocBook, la maggior parte dello sforzo speso per l'apprendimento di LinuxDoc non sarà sprecato.
Un modo per imparare LinuxDoc è attraverso degli esempi. Ho scritto tre file d'esempio di difficoltà che va da facile a intermedia. Il contenuto di questi file è stato copiato in questo HOWTO. Per trasformarli in file individuali si può tagliarli dal testo (partendo dal primo tag) e scriverli in un file. Poi si può tentare di trasformarne uno in un testo semplice usando ad esempio "sgml2txt --pass="-P-cbou" un-esempio.sgml" per vedere come appare. Assicurarsi che i nomi dei file finiscano in .sgml.
Se si desidera vedere alcuni esempi reali si può andare su un sito mirror di LDP, trovare gli HOWTO e selezionare LinuxDoc SGML. Oppure si può andare direttamente al sito principale: Indice degli Howto (LinuxDoc).
Ora il primo semplice esempio.
<!doctype linuxdoc system>
<article>
<title>Primo esempio (esempio1)
<author>David S.Lawyer
<sect>Introduzione
<p>Questo rappresenta un esempio molto semplice di "sorgente" per il
sistema di formattazione testi LinuxDoc. Questo paragrafo inizia con
un tag di paragrafo (una "p" racchiusa tra due parentesi angolari).
Notare che ci sono altri tag, anch'essi racchiusi tra parentesi
angolari. Se non si vede nessun tag, allora si sta leggendo un file
convertito, si cerchi invece il file sorgente: esempio1.sgml
(che contiene i tag).
Questo è il paragrafo successivo. Si noti che solo una riga
vuota lo separa dal paragrafo precedente.
Pertanto non è necessario mettere un tag "p" al suo inizio.
Il tag "p" è necessario solamente per il primo paragrafo di
una sezione (appena dopo il tag di sezione). Il suffisso sgml del
file significa Standard Generalized Markup Language. Quella che si
sta leggendo è la variante LinuxDoc di sgml, come specificato
nella primissima riga di questo file.
<sect>I tag
<p>I tag sono parole all'interno di parentesi angolari. Il tag "sect"
qui sopra marca l'inizio di una nuova sezione di questo documento di
esempio. La prima sezione era "Introduzione" e ora si sta leggendo la
seconda sezione intitolata "I tag". Se questo fosse un documento
lungo (come ad esempio un libro), una sezione corrisponderebbe ad un
capitolo.
Si noti che, all'inizio di questo articolo, ci sono i tag "article"
(articolo), "title" (titolo) e "author" (autore). Alla fine di questo
articolo un tag "/article" ne segna la fine.
C'è dunque una coppia di tag "article", il primo
è il tag d'apertura e il secondo il tag di chiusura. Una coppia di
tag "article" racchiude dunque l'intero articolo.
Negli esempi successivi, si vedranno altri tag che
vanno in coppia come questi. Essi hanno effetto su tutto quello
che si trova tra la coppia (il tag iniziale e il tag finale). Ogni
tag il cui nome sia immediatamente preceduto dal simbolo "/" è
un tag di chiusura.
Quando questo codice sorgente viene convertito in un altro formato
(come in formato testo semplice usando il programma sgml2txt) i tag
vengono rimossi. I tag aiutano solamente il programma sgml2txt a fare
la conversione. Ci sono molti altri tag da imparare; quando questo
primo esempio è stato compreso, si passi dunque all'esempio
successivo, l'esempio 2. Non si devono realmente
memorizzare i tag, dato che saranno ripetuti (ma con
poca o nessuna spiegazione) negli esempi successivi.
</article>
<!-- Questo è un commento. Viene ignorato quando questo file
sorgente viene convertito in altri formati. -->
<!-- Il tag sotto a questo indica il formato di questo file:
LinuxDoc -->
<!doctype linuxdoc system>
<article>
<title>Secondo esempio (esempio2)
<author>David S. Lawyer
<date>v1.0, July 2000
<abstract>
Questo paragrafo rappresenta il sommario. Questo documento è il secondo
esempio sull'utilizzo della variante LinuxDoc-SGML di sgml. È
più complesso rispetto al primo esempio (esempio1.sgml), ma
più semplice del terzo esempio (esempio3.sgml). Dopo averlo
assimilato, si sarà in grado di scrivere un semplice HOWTO
usando LinuxDoc. Fine del sommario.
</abstract>
<!-- "toc" = l'indice. Sarà creato in questo punto. -->
<toc>
<!-- La parte principale dell'articolo (o del documento) inizia qui. La
parte soprastante rappresenta una specie di lunga intestazione. -->
<sect>Questo secondo esempio (esempio2.sgml)
<p>A meno che non si abbia confidenza con i linguaggi a marcatori, si
dovrebbe leggere prima l'esempio 1. Potrebbe essere utile dare in pasto
questi file di esempio ad un "traduttore" come sgml2txt, per
convertirli in testo e notare come il risultato appaia differente
ripetto a questo documento "sorgente" con tutti i suoi tag.
<sect>Impaginazione dell'articolo
<sect1>Corpo del documento
<p>Dopo l'intestazione viene il corpo del documento, che consiste
in sezioni annidate marcate dai tag di sezione ("sect"). Le
sottosezioni sono marcate con i tag "sect1". Dato che questa
è la prima sottosezione all'interno della seconda sezione
principale, essa è la sezione 2.1. All'interno di una
sottosezione marcata da "sect1" ci possono essere sotto-sottosezioni
come "sect2". Ci sono persino tag come "sect3", "sect4", ecc., ma
è improbabile che sia necessario usarli. Notare che i tag
nell'uso reale vanno racchiusi tra parentesi angolari, < e >.
<sect2>Questa è una sotto-sottosezione
<p>
Si tratta della sezione 2.1.1. Si noti che il tag "p" può essere
su una riga da solo. Questo non cambia nulla nel documento
risultante.
<sect1>Intestazione del documento
<p>Un modo per creare una parte di intestazione consiste nel copiarla da
un altro file .sgml. Basta poi sostituire ogni cosa, eccetto i tag,
con le informazioni corrette per il proprio documento. È come
usare un modello.
<sect>Ulteriori caratteristiche nell'esempio 3
<p>Con i tag in questo esempio 2 si può scrivere un semplice
breve documento lungo qualche pagina. Ma per documenti più
lunghi o per altre importanti caratteristiche, come l'inserimento di
collegamenti all'interno del documento, si deve studiare
l'esempio successivo, l'esempio 3. Esso mostra anche come
creare elenchi e usare tipi di carattere.
</article>
<!doctype linuxdoc system>
<!-- Notare il "mailto:" dopo il mio nome. Esso permette al
lettore del formato HTML di cliccare sul mio indirizzo di posta
elettronica per inviarmi un messaggio. -->
<article>
<title>Terzo esempio (esempio3)
<author>David S. Lawyer <url url="mailto:dave@lafn.org">
<date>v1.0, July 2000
<abstract>
Questo documento rappresenta il terzo esempio sull'uso della variante
LinuxDoc di sgml. È più complesso rispetto al secondo
esempio.
</abstract>
<!-- Commento: toc = Indice -->
<toc>
<sect>I tipi di carattere
<p>Sebbene non compaiano nell'output in testo semplice, funzionano per
altre conversioni.
<bf>carattere grassetto</bf> <em>carattere enfatizzato</em>
<sf>sans serif</sf> <sl>carattere inclinato</sl>
<tt>carattere a spaziatura fissa</tt> <it>carattere corsivo</it>
Un altro modo per ottenere questi stessi tipi di carattere consiste nel
racchiudere il testo con il simbolo "/", in questo modo:
<bf/carattere grassetto/ <em/carattere enfatizzato/
<sf/sans serif/ <sl/carattere inclinato/
<tt/carattere a spaziatura fissa/ <it/carattere corsivo/
Si noti che DocBook non ha tag per i tipi di carattere dunque
sarebbe meglio non usarli se si ha in progetto di fare la conversione
in DocBook.
<sect>I collegamenti <label id="links_">
<p>Si possono creare collegamenti (qualcosa su cui si può
cliccare all'interno di un navigatore html per andare da qualche
altra parte). Possono indirizzare semplicemente in un'altra parte di
questo documento (riferimenti incrociati), tipo l'etichetta ("label")
qui sopra, oppure possono indirizzare ad un sito web in Internet.
<sect1>Riferimenti incrociati
<p>Se si clicca su <ref id="links_" name="Collegamenti"> si
viene spostati all'inizio della sezione precedente "I
collegamenti" (che è etichettata come "links_"). L'etichetta
può essere una qualsiasi parola liberamente scelta, ma
è buona norma evitare parole comuni, in modo da poter
cercare etichette univoche usando il proprio editor. Per questa
ragione è stato usato links_ (con il simbolo di
sottolineatura). Il nome di questo collegamento viene mostrato
(nel formato html) come il nome su cui fare clic. Questo nome
(Collegamenti) è presente anche nella versione in puro
testo.
<sect1>Collegamenti con URL
<p>Se si clicca su <url url="http://www.tldp.org"> si viene spostati
sul sito web del Linux Documentation Project. Il successivo
collegamento aggiunge un nome su cui gli utenti cliccano:
<url url="http://www.tldp.org" name="Linux Documentation Project">.
Usando questo secondo metodo, non si deve nemmeno
spiegare dove porta il collegamento, in quanto è ovvio dal
nome.
<sect>Caratteri proibiti
<p>Ogni parola scritta tra parentesi angolari viene
interpretata come un tag. Come fare allora per mostrare un tag in un
documento? Per questo scopo si usa una parola in codice per i
caratteri delle parentesi angolari.
Si può usare < per il simbolo < e > per il simbolo
>. lt = "less than" (minore di), gt = "greater than" (maggiore di).
Per esempio, questo è un tag p: <p>.
Naturalmente di fatto non inizia alcun paragrafo, ma appare
nei documenti convertiti come <p>. Tutti questi codici iniziano con
un carattere "&". Il carattere ";" posto dopo lt serve per
separarlo. Non è necessario se c'è uno spazio dopo di
esso. Ad esempio: 3 < 4. Di fatto, se si sapesse che va bene
usare un > disaccoppiato si potrebbe scrivere <p> come <p>.
Questo non sarebbe riconosciuto erroneamente come tag, dato che
non c'è l'apertura <. A dire il vero anche 3 < 4 funziona
bene.
Ci sono altri caratteri che non si possono mettere direttamente nel
testo del documento. Per il carattere "&" in un comando AT del modem
usare: AT&. Se altri caratteri danno dei problemi (lo fanno
raramente) si veda
<ref id="ch_codes" name="Codici dei caratteri (macro)"> o la "guida"
che viene fornita con linuxdoc-tools o sgml-tools.
<sect>Verbatim, codice e a capo
<sect1>Verbatim
<p>Se si vuole essere sicuri che il testo appaia esattamente come lo si
è digitato, anche dopo la conversione in altri formati, usare
il tag verbatim "verb". È utile per creare tabelle, e simili.
Tuttavia alcune cose vengono comunque riconosciute come marcatori anche se
si trovano tra tag verbatim. Tra queste sono incluse le macro che
iniziano con il carattere "&" e i tag finali con il carattere "/".
<tscreen><verb>
% sgml2txt --pass="-P-cbou" esempio.sgml
</verb></tscreen>
Il tag "tscreen" imposta il carattere a spaziatura fissa e imposta il
rientro in modo bello da vedersi.
<sect1>Codice
<p>Questo racchiude del codice del
computer tra due righe tratteggiate.
<tscreen><code>
Mettere il codice sorgente qui.
</code></tscreen>
<sect1>A capo
<p>Per andare a capo in modo forzato usare <newline>
Questa frase inizia sempre al margine sinistro.
<sect>Elenchi
<p>Questo mette elementi dentro ad un elenco puntato con un segno grafico
all'inizio di ogni elemento. Gli elenchi iniziano con il tag
"itemize".
<itemize>
<item>Questo è il primo elemento di un elenco.
<item>Questo è il secondo elemento.
<itemize>
<item>Sono supportati livelli multipli (annidati).
<item>Il secondo elemento in questo sottoelenco.
</itemize>
<enum>
<item>Funzionano anche elenchi numerati usando <tt/enum/.
<item>Questo è l'elemento numero 2.
</enum>
<item>Questo è l'ultimo elemento nell'elenco principale.
</itemize>
</article>
<!doctype linuxdoc system>
<article>
<title>Guida di consultazione rapida
<author>David S. Lawyer
<date>v1.0, July 2000
<abstract>Qui va messo il sommario </abstract>
<toc> <!-- Commento: toc = Indice -->
<sect>Capitolo 1 Nota: si metta un <p> sulla prima riga di
<sect1>Sottosezione 1.1 ogni sezione (o sottosezione, ecc.)
<sect1>Sottosezione 1.2
<sect>Capitolo 2 Si scelgano nomi di titoli da sostituire a
<sect1>Sottosezione 2.1 "Capitolo", "Sottosezione", ecc.
<sect2>Sotto-sottosezione 2.1.1
<sect2>Sotto-sottosezione 2.1.2
<sect1>Sottosezione 2.2
</article>
Ci sono due modi per ottenerli:
<bf>carattere grassetto</bf> <em>carattere enfatizzato</em> <sf>carattere sans serif</sf> <sl>carattere inclinato</sl> <tt>carattere a spaziatura fissa</tt> <it>carattere corsivo</it> oppure: <bf/grassetto/ <em/enfatizzato/ <sf/sans serif/ <sl/inclinato/ <tt/spaziatura fissa/ <it/corsivo/
Normali elenchi non numerati: Elenchi numerati:
<itemize> <enum>
<item>Primo elemento <item>Primo elemento
<item>Secondo elemento <item>Secondo elemento
<item>eccetera <item>eccetera
</itemize> </enum>
Riferimenti incrociati: Un collegamento email:
<ref id="links_" name="Collegamenti"> <url url="mailto:bob@tldp.org">
Per andare a capo forzatamente: <newline>
<tscreen><verb>
<url url="http://www.tldp.org">
<url url="http://www.tldp.org" name="Linux Documentation Project">.
</verb></tscreen>
Non è sempre necessario usarli.
& per la e commerciale (&).< per una parentesi angolare sinistra (<).> per una parentesi angolare destra (>).&etago; per una parentesi angolare sinistra con
una sbarra (</).L'uso di questi è opzionale e io li uso raramente.
`` e '' per aprire e chiudere apici
doppi.­ per un soft-hyphen (trattino debole),
per indicare cioè che questo è un buon punto per
spezzare una parola molto lunga e inserire un trattino per la
giustificazione orizzontale della riga.Usare i seguenti solo se si hanno problemi in LinuxDoc con essi o se non si riesce ad ottenerli nel documento formattato. Io ho dovuto usarli raramente.
$ per il simbolo del dollaro
($).# per il simbolo cancelletto (#).% per il simbolo di percentuale
(%).˜ per la tilde (~).&dquot; per ".