[PLUTO-ildp] Serve una mano?

[Hugh Hartmann]

Ciao Silvano,
e un saluto "crepuscolare" si propaga a tutti i partecipanti alla lista
... :-) 

On Thu, May 24, 2007 at 09:47:05PM +0200, Silvano wrote:
> Domanda: visto quanto "detto" da Hugh Hartmann, devo darmi una guardata
> al funzionamento di DocBook ? L'ho incontrato qualche volta, ma non l'ho
> mai usato. 

Cerchero' di essere breve (cosa alquanto difficile per il sottoscritto,
come avrai gia' potuto notare ... :-) 

Sostanzialmente, il docbook e' diventato il sostituto "piu' evoluto" di
LinuxDoc (o SGML-Tools), il quale, era nato con lo scopo di essere
utilizzato per la documentazione di Linux (ecco la provenienza del nome
LinuxDoc). 

In ogni caso non e' necessario conoscere il funzionamento del docbook,
che viene usato per trasformare un sorgente .sgml o .xml nei vari formati
consueti, cio' che conta e' conoscere un po' i vari tag che sono presenti
all'interno di un file sorgente .sgml. 

Per esempio, la prima riga di un file sorgente .sgml di linuxdoc e' (e
deve essere):

<!doctype linuxdoc system>
oppure:
<!DOCTYPE linuxdoc PUBLIC "-//LinuxDoc//DTD LinuxDoc 96//EN" >

La Prima linea di un sorgente .sgml di DocBook e':
<!DOCTYPE Book PUBLIC "-//Davenport//DTD DocBook V3.0//EN">

La prima linea di un sorgente .xml di DocBook e':  
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
     "http://docbook.org/xml/4.2/docbookx.dtd">

Subito dopo la prima riga c'e la "classe di Documento" che per testo di
documentazione, in Linuxdoc, e' rappresentata dal tag <article>, mentre
in DocBook e' rappresentata da <Book>. Normalmente esiete un tag iniziale
e un corrispondente tag finale. Prendendo l'esempio del tag <article>,
alla fine di tutto il testo "deve" esserci il tag finale </article>, cosi
in docbook, se all'inizio c'e' il tag <Book>, alla fine del testo ci deve
essere il tag </Book>. Tutto il testo deve essere racchiuso tra i tag
(iniziale e finale) "classe di documento".  

In maniera del tutto analoga si definiscono gli altri tag. Ergo se esiste
un tag <author>, ci sara' (ma non e' obbligatorio in Linuxdoc) un tag
</author>. All'interno di questi due tag ci dovrebbe essere il nome
dell'autore. Cosi il tag <date> e </date> dovrebbero racchiudere la data
del documento e la sua versione (in DocBook ci sono molti piu' tag ...
:-))

Ora, oltre al testo che stai traducendo (che si suppone essere un
sorgente sgml o xml di DocBook) potresti prelevare un sorgente .sgml 
di un'altro testo magari che utilizza il linuxdoc e farne un paragone.

Noterai subito che la quantita' di tag in docbook e' assolutamente piu'
grande rispetto a a quelli in linuxdoc. 

Tanto per farti un esempio i paragrafi in linuxdoc si indicano con <p>
(spesso non si mettono neanche, basta una riga vuota per stabilire
implicitamente un paragrafo) e alla fine del paragrafo si mette un </p>
anche se non necessario. In Docbook praticamente c'e' sempre la
necessita' di mettere il tag finale, il paragrafo si indica con <para> e
si chiude con </para>. 

Naturalmente tutto cio' che si trova all'interno delle parentesia
nagolari, salvo rare eccezioni (per esempio nei riferimenti incrociati)
non va assolutamente tradotto.

Oltre alla guida sul Docbook sul sito dell'ILDP dovresti trovare anche la
guida sul Linuxdoc e SGML-tools e anche altri testi utili come:

HOWTO HOWTO, Howtos-with-Linuxdoc, LinuxDoc+Emacs+Ispell-HOWTO,
LinuxDoc-Reference, ecc ..

Per ora penso possa bastare ... :-)

Au Revoir
Hugh Hartmann

-- 
 ... Linux, Windows Xp ed MS-DOS 
     (anche conosciuti come il Bello, il Brutto ed il Cattivo).   
     -- Matt Welsh