Questa è la guida dell'utente al sistema di processo di documenti Linuxdoc-SGML, per l'uso con i documenti di Linux. Linuxdoc-SGML è un SGML DTD (Definizione Tipo Documento) e un gruppo di ``programmi di conversione'' che traducono il sorgente SGML in groff, LaTeX, HTML, GNU info, LyX e RTF.
Linuxdoc-SGML è basato sul QWERTZ DTD di Tom Gordon,
thomas.gordon@gmd.de. È stato semplicemente rivisto il suo DTD e
sostituito i file per l'uso con la documentazione di Linux.
Linuxdoc-SGML non è stato pensato per essere un sistema di formattazione generale. Anche se può essere usato per vari tipi di documenti, è stato confezionato per i documentatori di Linux e la creazione di HOWTO, FAQ e (successivamente) i manuali del Linux Documentation Project. Quindi sono state inserite le caratteristiche necessarie a questo uso. Se notate la mancanza di qualcosa di generale nel sistema, c'è la sua ragione. Non c'è niente che lega Linuxdoc-SGML alla documentazione Linux, ma tutti i documenti prodotti da questo sistema assumono lo stesso aspetto. Se volete produrre qualcosa di diverso, vi suggerisco di usare un sistema più generalizzato, tipo il normale QWERTZ DTD in combinazione con gli strumenti Linuxdoc-SGML.
Uno dei vantaggi di questo sistema è di creare facilmente documenti da produrre in vari formati. Finora molta documentazione di Linux è stata prodotta in testo semplice attraverso editor manuali. Un sistema tipo groff può occuparsi della formattazione in testo semplice, ma non produce l'HTML (per l'uso nel World Wide Web), LaTeX (per documenti stampati carini) o altri diversi formati. Comunque, se ci sono caratteristiche mancanti nel sistema che ritenete utili, ditemelo! L'idea è non dover faticare per produrre documenti di buon aspetto in formati multipli. L'autore dovrebbe fare meno lavoro possibile.
Questo documento è stato scritto con il Linuxdoc-SGML DTD. Esso contiene più
o meno tutto quello che è necessario sapere per scrivere documenti SGML con
questo DTD. Guardate esempio.sgml per un esempio di documento SGML, che
potete usare come modello per i vostri documenti.
Ho scelto SGML per questo sistema perché SGML è fatto specificatamente per la conversione in altri formati. SGML, che sta per Standard Generalized Markup Language, permette di specificare la struttura di un documento---cioè come si vuole impostare il documento. Si specifica la struttura di un documento tramite un DTD. Linuxdoc-SGML è un DTD che specifica la struttura per i Linux HOWTO e altri documenti. QWERTZ è un altro DTD. Lo standard SGML fornisce DTD per libri, articoli e altri tipi di documenti generici.
Il DTD specifica il nome di ``elementi'' con il documento. Un elemento è una parte di una struttura---come una sezione, una sottosezione, un paragrafo o qualcosa di più piccolo come un testo enfantizzato. Diversamente da LaTeX, comunque, questi elementi non sono intrinseci a SGML stesso. Il Linuxdoc-SGML DTD definisce elementi molto simili ai corrispondenti LaTeX---ci sono sezioni, sottosezioni, ``ambienti'' testuali e così via. Comunque, usando SGML si può definire ogni tipo di struttura per il documento che si preferisce. In ogni modo, SGML è simile a TeX a basso livello, mentre il Linuxdoc-SGML DTD è simile a LaTeX.
Non confondersi con questa analogia. SGML non è un sistema di formattazione di testi. Non ci sono ``formattatori SGML''. Il sorgente SGML è solo convertito in altri formati per il processo. Inoltre, SGML stesso è usato per specificare la struttura del documento. Non ci sono facilitazioni o ``macro'' intrinseche a SGML stesso. Tutto questo è definito nel DTD. Non si può usare SGML senza un DTD---un DTD definisce cosa fare con SGML.
Qui vediamo come viene processato un documento con SGML e il Linuxdoc-SGML DTD. Prima è necessario un DTD. Io uso il QWERTZ DTD che fu prodotto, originariamente, da un gruppo di persone che necessitavano di un DTD simile a LaTeX. Ho modificato il QWERTZ DTD per produrre il Linuxdoc-SGML DTD per i nostri scopi. Il DTD semplicemente imposta la struttura del documento. Una piccola porzione di esso è simile alla seguente:
<!element article - -
(titlepag, header?,
toc?, lof?, lot?, p*, sect*,
(appendix, sect+)?, biblio?) +(footnote)>
Questa parte imposta la struttura globale per un ``articolo'', che è simile
a un ``documentstyle'' con LaTeX. L'articolo consiste in un titolo pagina
(titlepag), un'eventuale intestazione (header), un'eventuale
indice (toc), un'eventuale lista di figure (lof) e tabelle
(lot), un numero qualsiasi di paragrafi (p), un numero qualsiasi
di sezioni principali (sect), eventuali appendici (appendix),
un'eventuale bibliografia (biblio) e note in fondo pagina
(footnote).
Come si può vedere, il DTD non dice niente su come il documento deve
essere formattato o come dovrebbe apparire. Esso definisce appena quali
parti compongono il documento. La struttura di titlepag, header,
sect e altri elementi sono definiti altrove.
Non è necessario sapere niente sulla sintassi del DTD per scrivere documenti. Viene solo prensentato in modo da sapere come appare e come funziona. È necessario prendere familiarità con la struttura del documento definita dal DTD. Altrimenti si potrebbe violare la struttura quando si prova a scrivere un documento e confondersi con i successivi messaggi d'errore. Verrà descritta in dettaglio la struttura di documenti Linuxdoc-SGML più avanti.
Il passo successivo è di scrivere un documento usando la struttura definita dal DTD. Di nuovo, il Linuxdoc-SGML DTD fa apparire il documento molto simile a LaTeX---è molto semplice da seguire. Nel gergo di SGML, un singolo documento scritto con un particolare DTD è conosciuto come una ``istanza'' di quel DTD.
Per trasformare il sorgente SGML in altri formati (come LaTeX o groff) per
la trasformazione, il sorgente SGML (il documento scritto) è analizzato
attraverso il DTD con l'analizzatore SGML. Io uso l'analizzatore
sgml di James Clark, jjc@jclark.com, che è anche l'autore di
groff. Siamo in buone mani. L'analizzatore (sgml) semplicemente
scorre il documento e verifica che sia utilizzata correttamente la struttura
richiesta dal DTD. Esso crea anche una versione più esplicita del documento,
con ``macro'' ed elementi espansi, che sono compresi da sgmlsasp, la
fase successiva del processo.
sgmlsasp è responsabile della conversione dell'output di sgmls in
altri formati (tipo LaTeX). Ciò viene fatto attraverso file di
sostituzione che descrivono come convertire gli elementi nel file originale
SGML nel formato ``destinazione'' (come LaTeX o groff).
Per esempio, una parte del file relativa a LaTeX assomiglia a:
<itemize> + "\\begin{itemize} +
</itemize> + "\\end{itemize} +
che comunica che ogni volta si inizia un elemento itemize nel
sorgente SGML, esso venga sostituito con:
\begin{itemize}
nel sorgente LaTeX. (Come avevo detto, gli elementi del Linuxdoc-SGML DTD sono molto simili ai corrispondenti LaTeX.)
Così, per convertire SGML in altri formati, tutto quello che c'è da fare è scrivere un file di traduzione per quel formato con le appropriate analogie tra l'SGML e il nuovo formato. In pratica, non è tutto semplice---per esempio, se si sta tentando di convertire in un formato che non è strutturato esattamente come il DTD si avranno dei problemi. In qualsiasi caso, è molto più semplice rispetto a fare un analizzatore e un converitore per ogni tipo di formato di uscita; SGML provvede un sistema generalizzato per convertire un sorgente in diversi formati.
Una volta che sgmlsasp ha completato il suo lavoro, avete un sorgente
LaTeX con il corrispondente documento originale SGML, che potete formattare
con LaTeX come al solito. Più avanti in questo documento ci sono esempi e i
comandi da usare per convertire e formattare. Si può fare tutto in una linea
di comando.
Ma prima devo descrivere come installare e configurare il software.