Il LinuxDoc è un pò più facile da imparare rispetto al DocBook. Ma la maggior parte delle informazioni che si impareranno riguardo a linuxDoc dovrebbero essere utili anche per il DocBook. Così se eventualmente si decidesse di usare DocBook, la maggior parte dello sforzo speso per l'apprendimento linuxDoc, non sarà sprecato.
Un modo per imparare il LinuxDoc è attraverso gli esempi. In questo testo ci sono tre file d'esempio che spaziano tra il facile e l'intermedio. Si inizia con il primo esempio. Questi file sono inclusi qui come sezioni. Per trasformarli in file individuali si può tagliarli dal testo e scriverli ciascuno in un file. Poi si può tentare di trasformarne uno in un testo usando "sgml2txt -f example2.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 di un sito mirror di LDP (Linux Documentation Project), e cercare gli HOWTO e selezionare LinuxDoc SGML. Oppure si può andare direttamente al sito principale: http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/sgml
Ora è il momento di iniziare il primo semplice esempio.
<!doctype linuxdoc system>
<article>
<title>Primo Esempio (esempio1)
<author>David S.Lawyer
<sect> Introduzione
<p>Questo è un esempio molto facile di "sorgente" per il sistema
di formattazione testi LinuxDoc. Il paragrafo inizia con tag del
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, perciò si cerchi il file sorgente: example1.sgml
(che contiene i tag).
Questo è il paragrafo successivo. Notare che esso è
separato dal paragrafo precedente solo da una linea vuota.
Pertanto non è necessario mettere un tag "p" all'inizio di
esso. Il tag "p" è necessario solamente per il primo paragrafo
di una sezione (appena dopo il tag di sezione <sect>). Il suffisso
sgml significa Standard Generalized Markup Language.
Ora si sta leggendo la variante LinuxDoc di sgml come
specificato nella primissima linea di questo file.
<sect> I Tag
<p>I tag sono qualsiasi cosa all'interno delle parentesi angolari.
Il tag "sect" sopra marca l'inizio di una nuova sezione di questo
documento di esempio. "Introduzione" era la prima sezione e ora si sta
leggendo la seconda sezione intitolata "I Tag". Se questo fosse un
documento lungo (come ad esempio un libro), una sezione dovrebbe
corrispondere a un capitolo.
Notare che, all'inizio di questo articolo, ci sono i tag "article",
"title" (titolo) e "author"(autore). Alla fine dei questo articolo
c'è un tag "/article", che segna la fine di questo articolo.
Così c'è una coppia di tag "article", il primo stabilisce
il tag di partenza e il secondo stabilisce il tag finale. Quindi
l'intero articolo è racchiuso nei tag "article".
Negli esempi successivi, si vedrà (noterà) che
ci sono altri tag che vanno in coppia come questi. Essi hanno effetto
su tutto ciò che si trova tra le coppie (tag di inizio e
tag finale). Ogni nome di tag che ha il simbolo "/" appena prima di
esso è un tag di chiusura.
Quando questo codice sorgente è convertito in un altro formato
(come un testo piano usando il programma sgml2txt) i tag sono rimossi.
I tag aiutano solamente il programma sgml2txt a fare la conversione.
Ci sono molti altri tag da imparare. Così, quando si ha compreso
questo esempio1, si può passare all'esempio successivo: esempio2.
In questo momento non è necessario memorizzare i tag, saranno
ripetuti (ma con una piccola spiegazione oppure senza spiegazione)
negli esempi successivi.
</article>
<!-- Questo è un commento. È ignorato quando questo file sorgente
viene convertito in altri formati. -->
<!-- Il tag successivo richiesto implica che questo file è nel
formato LinuxDoc -->
<!doctype linuxdoc system>
<article>
<title>Secondo Esempio (esempio2)
<author>David S. Lawyer
<date>v1.0, Luglio 2000
<abstract>
Questo è l'astratto. Questo documento è il secondo esempio
sull'uso della variante Linuxdoc-SGML di sgml. Esso è più
complesso rispetto al primo esempio (esempio1.sgml), ma più
semplice del terzo esempio (esempio3.sgml).
Dopo che si ha assimilato questo si sarà in grado di
scrivere un semplice HOWTO usando il LinuxDoc. Fine dell'astratto.
</abstract>
<!-- Il "toc" = Table of Contents (tavola dei contenuti). Esso
sarà creato quì. -->
<toc>
<!-- Qui inizia la parte principale dell'articolo (o documento). La
parte precedente è una specie di lunga intestazione. -->
<sect>Questo è il Secondo Esempio (esempio2.sgml)
<p>A meno che non si abbia preso confidenza con i linguaggi a
marcatori, si dovrebbe leggere prima l'esempio1. Si potrebbe volere
eseguire questi file di esempio attraverso 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>Article Layout (Impaginazione di Article)
<sect1>Intestazione del Documento
<p>Un modo per creare una parte di intestazione è quello di
copiarla da un altro file sgml. Poi basta sostituire ogni cosa con le
informazioni corrette per il proprio documento eccetto i tag .
Questo modo è come usare un modello.
<sect1> Corpo del Documento
<p>Dopo l'intestazione si arriva al corpo del documento, che consiste
di sezioni annidate marcate dai tag di sezione ("sect"). Le
sottosezioni sono marcate con i tag "sect1". Poiché questa è
la prima sottosezione all'interno della seconda sezione principale, essa
è la sezione 2.1. All'interno di una sottosezione ci
può essere una sotto-sottosezione marcata con un tag "sect2", ecc.
Per una sotto-sotto-sotto-sezione usare il tag "sect3". Ci sono anche tag
come "sect4" e "sect5", ma è improbabile che sia necessario usarli.
<sect2> Questa è una sotto-sotto-sezione
<p>
È la sezione 2.2.1. Notare che il tag "p" può essere su
di una linea da solo. Questo non cambia nulla nel risultato del documento.
<sect>Ulteriori caratteristiche nell'esempio3
<p>Con i tag di questo esempio2, si può scrivere un
semplice breve documento lungo qualche pagina. Ma per documenti
più lunghi o per altre importanti caratteristiche come
l'inserimento di link all'interno del documento, è necessario
studiare l'esempio successivo: esempio3. In questo esempio si
mostrerà come creare elenchi e font.
</article>
<!doctype linuxdoc system>
<!-- Notare il mailto: dopo il mio nome. Questo permette al lettore
di cliccare su di esso per inviarmi una email -->
<article>
<title>Terzo Esempio (esempio3)
<author>David S. Lawyer <url url="mailto:dave@lafn.org">
<date>v1.0, July 2000
<abstract>
Questo documento è il terzo esempio sull'uso della variante
LinuxDoc di sgml. Esso è più complesso rispetto al
secondo esempio.
</abstract>
<!-- Commento: toc = Tavola dei Contenuti -->
<toc>
<sect> I Font
<p>
Mentre nella conversione in un testo piano i font non appariranno,
essi funzioneranno per altre conversioni.
<bf>boldface font</bf> <em>emphasis font</em>
<sf>sans serif</sf> <sl>slanted font</sl>
<tt>typewriter font</tt> <it>italics font</it>
C'è un altro modo per ottenere alcuni di questi font
racchiudendo il testo con il simbolo "/" (slash) come questi:
<bf/boldface font/ <em/emphasis font/ <sf/sans serif/
<sl/slanted font/ <tt/typewriter font/ <it/italics font/
<sect> I Link <label id="links_">
<p>Si possono creare link (qualcosa su cui si può cliccare con un
navigatore html per andare in qualche altra parte).
I link possono mandare in un'altra parte di questo documento
(riferimenti-incrociati), o potrebbero mandare a un sito web in Internet.
<sect1> Riferimenti incrociati
<p> Se si clicca su <ref id="links_" name="Links"> ci si
sposterà all'inizio della sezione precedente "I Link" (che è
ettichettata con links_). L'ettichetta dell'id può essere
qualsiasi parola che si desidera, ma è una buona idea evitare
parole comuni, così che si possono cercare etichette uniche
usando il proprio editor. Questa è la ragione per cui uso
links_ (con il simbolo di sottolineatura ). Il nome di
questo link sarà mostrato (nel formato html) come il nome su cui
cliccare. Questo nome (Links) sarà anche presente nella
trasformazione del testo.
<sect1> Link URL
<p> Se si clicca su <url url="http://www.linuxdoc.org"> si
otterrà il sito web del Linux Documentation Project.
Il successivo link aggiunge un nome su cui gli utenti potranno cliccare:
<url url="http://www.linuxdoc.org" name="Linux Documentation Project">.
Usando questo secondo metodo, non è necessario spiegare dove
porta il link, in quanto è ovvio dal nome.
<sect> Caratteri Proibiti
<p>Ogni cosa che si scriverà tra le parentesi angolari
sarà interpretata come un tag. Ma se si vuole mostrare un tag in
un documento? Per questo si deve usare un carattere codificato tra
le parentesi angolari.
Si può usare < per il simbolo < e > per il simbolo >.
lt = Less Than (Minore), gt = Greater Than (Maggiore). Per esempio,
questo è un tag p: <p>. Certamente esso
non inizia alcun paragrafo, ma apparirà nei documenti convertiti
come un <p>. Tutti questi codici iniziano con un carrattere &. Il ;
dopo di esso serve per separarlo. Non è necessario
se c'è uno spazio dopo di esso. Per esempio: 3 < 4.
Effettivamente, se si sapesse che va bene usare dei > disaccoppiati si
potrebbe scrivere <p> come <p>. Questo non sarebbe riconosciuto
erroneamente come tag, poiché non c'è l'apertura <.
Ci sono altri caratteri che non si possono mettere direttamente nel testo
del documento. Per il carrattere & in un comando AT del modem usare:
AT&. Se altri caratteri provocano delle difficoltà
vedere l'esempio3 o la "guida" che viene fornita nel pacchetto
linuxdoc-tools o sgml-tools.
<sect> Verbatim, Code & Newline
<sect1> Verbatim
<p> Se si vuole essere sicuri che le linee non siano congiunte insieme
durante la conversione ad altri formati, usare il verbatim (tag verb).
Alcune cose vengono riconosciute anche se si trovano tra tag verbatim.
Questo include le macro che iniziano con un carattere & e i tag finali
con il carattere /.
<tscreen><verb>
% sgml2txt -f example.sgml
</verb></tscreen>
Il tag "tscreen" imposta il font a typewriter e lo indenta piacevolmente.
<sect1> Code
<p> Questo racchiude codice del computer tra due linee -.
<tscreen><code>
Mettere qui il codice sorgente del computer
</code></tscreen>
<sect1> Newline (A capo)
<p> Per forzare una nuova linea (a capo) usare il tag <newline>
Questa frase inizierà sempre al margine sinistro.
<sect>Elenchi
<p>
Questo mette degli elementi dentro un elenco con un marcatore
all'inizio di ogni elemento.
Le liste iniziano con un tag "itemize".
<itemize>
<item> Questo è il primo elemento in un elenco.
<item> Questo è il secondo elemento
<itemize>
<item> Sono supportati livelli multipli (nidificazione).
<item> Il secondo elemento in questo sottoelenco
</itemize>
<enum>
<item> Si possono avere anche elenchi numerati usando <tt/enum/.
<item> Questo è l'elemento numero 2
</enum>
<item> Questo \ l'elemento finale nell'elenco principale
</itemize>
</article>
<!doctype linuxdoc system>
<article>
<title>Guida di consultazione rapida
<author>David S. Lawyer
<date>v1.0, July 2000
<abstract> abstract here </abstract>
<toc> <!-- Commento: toc = Tavola dei Contenuti -->
<sect> Capitolo 1 Nota: Mettere un <p> sulla prima linea di
<sect1> Sottosezione 1.1 ogni sezione (o sottosezione, etc.)
<sect1> Sottosezione 1.2
<sect> Capitolo 2 Scegliere i nomi dei 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>
Per ottenere i font ci sono due modi:
<bf>boldface font</bf> <em>emphasis font</em> <sf>sans serif font</sf> <sl>slanted font</sl> <tt>typewriter font</tt> <it>italics font</it> <bf/boldface/ <em/emphasis/ <sf/sans serif/ <sl/slanted/ <tt/typewriter/ <it/italics/
Liste ordinarie non numerate: Liste numerate:
<itemize> <enum>
<item> Primo elemento <item> Primo elemento
<item> Secondo elemento <item> Secondo elemento
<item> ecc. <item> ecc.
</itemize> </enum>
(Riferimenti incrociati): Un Link di Email:
<ref id="links_" name="Links"> <url url="mailto:bob@linuxdoc.org">
Per forzare una nuova linea <newline>
<tscreen><verb>
<url url="http://www.linuxdoc.org">
<url url="http://www.linuxdoc.org" name="Linux Documentation Project">.
</verb></tscreen>
& per la e commerciale (&),< per un simbolo di minore (<),> per un simbolo di maggiore (>),&etago; per un simbolo di minore con una barra
(</)$ per il simbolo del dollaro ($),# per un cancelletto (#),% per il sibolo percentuale (%),˜ per il simbolo tilde (~),`` and '' per le virgolette singole, o usare
&dquot; per ".­ per un trattino (ovvero, un'indicazione
che questo è un buon punto per spezzare una parola per una
giustificazione orizzontale).