Avanti Indietro Indice

4. Imparare il LinuxDoc

4.1 Introduzione

LinuxDoc è un pò più facile da imparare rispetto al DocBook. Ma molto di ciò che si impara riguardo il LinuxDoc sarà utile anche per il DocBook. Così, se eventualmente si decidesse di usare il DocBook, la maggior parte dello sforzo speso per l'apprendimento di LinuxDoc, non sarà sprecato.

Un modo per imparare il LinuxDoc è attraverso gli esempi. Ho scritto tre file d'esempio che spaziano dal facile all'intermedio. Si inizia con l'esempio 1. 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 semplice usando ad esempio "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), trovare 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 primo semplice esempio.

4.2 Esempio 1

<!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 iniziale e il secondo stabilisce il tag finale. Quindi l'intero 
articolo è racchiuso nei tag "article". Negli esempi successivi, si 
vedrà che ci sono altri tag che vanno in coppia come questi. Essi 
hanno effetto su tutto ciò che si trova tra la coppia (tag iniziale
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 semplice 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, poiché 
saranno ripetuti (ma con poca spiegazione oppure senza spiegazione)
negli esempi successivi.
</article>

4.3 Esempio 2

<!-- Questo ?un commento. E' 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 è il sommario. 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 del sommario.
</abstract>

<!-- Il "toc" = Table of Contents (tavola dei contenuti). Esso
sarà creato qui. -->
<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>Impaginazione dell'articolo
<sect1>Intestazione del Documento
<p>Un modo per creare una parte di intestazione è di
copiarla da un altro file sgml. Poi basta sostituire ogni cosa con le 
informazioni corrette per il proprio documento eccetto i tag.
Questo è 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-sotto-sezione 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>

4.4 Terzo Esempio

<!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, Luglio 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 semplice 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'etichetta dell'id può essere
qualsiasi parola che si desidera, ma è una buona idea evitare
parole comuni, così che si possano 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 fare clic. Questo nome 
(Links) sarà anche presente nella trasformazione del testo.

<sect1>Link URL
<p> Se si clicca su <url url="http://www.tldp.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.tldp.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 &lt per il simbolo < e &gt per il simbolo >.
lt = Less Than (Minore), gt = Greater Than (Maggiore). Per esempio,
questo è un tag p: &lt;p&gt;. Certamente esso
non inizia alcun paragrafo, ma apparirà nei documenti convertiti
come un <p>. Tutti questi codici iniziano con un carrattere &. Il
carattere ; posto dopo di esso serve per separarlo. Non è necessario
se c'è uno spazio dopo di esso. Per esempio: 3 &lt 4.
Effettivamente, se si sapesse che va bene usare dei > disaccoppiati si
potrebbe scrivere <p> come &lt;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 carattere & in un comando AT del modem usare:
AT&amp;. Se altri caratteri provocano delle difficoltà 
vedere l'esempio 3 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 in modo carino.

<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 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>

4.5 Guida di consultazione rapida di Linuxdoc

Intestazione

<!doctype linuxdoc system>
<article>
<title>Guida di consultazione rapida
<author>David S. Lawyer
<date>v1.0, July 2000
<abstract> Qui c'è il sommario </abstract>
<toc> <!-- Commento: toc = Indice  -->

Impaginazione del Corpo

<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>

Font

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/  

Elenchi (va bene l'annidamento)

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>

Link

(Riferimenti incrociati):               Un Link di Email:
<ref id="links_" name="Link">           <url url="mailto:bob@linuxdoc.org">

Newline, Verbatim, URL

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>

Codici di Caratteri (macro).


Avanti Indietro Indice