<- Guida per il revisore di ILDP - Indice Generale - Copertina - Come funziona e come si traduce una man page ->

L'angolo del PLUTO

A cosa servono e come si traducono i documenti in SGML e XML

di Giulio Daprelà

Cos'è SGML

SGML è l' acronimo di "Standard Generalized Markup Language", ossia "linguaggio standard generalizzato a marcatori". Si tratta di un metalinguaggio, ovvero un linguaggio che serve per definirne un altro e che viene usato principalmente per determinare il modo in cui il testo deve essere scritto.

Cos'è un linguaggio a marcatori

Un linguaggio a marcatori combina testo e informazioni extra sul testo. Le informazioni extra, per esempio riguardanti la struttura del testo, sono espresse utilizzando dei marcatori intercalati nel testo principale.
Il linguaggio a marcatori, più noto nell'uso moderno come HTML, acronimo di HyperText Markup Language, è uno dei fondamenti del World Wide Web.
In origine i marcatori erano usati nell'industria editoriale per comunicare il lavoro di stampa tra autori, editori e stampatori.

I marcatori utilizzati nell' SGML e nell' HTML, detti comunemente anche tag, sono dei codici speciali racchiusi tra parentesi angolari (< e >). Il testo da formattare è delimitato da due marcatori tag: uno di apertura, posto all'inizio prima del corpo del testo e uno di chiusura, posto alla fine del corpo del testo.
La figura seguente riporta come esempio la struttura dei marcatori che permette la visualizzazione dei primi paragrafi di questo articolo.

Figura 1: una parte del sorgente HTML di questa pagina

Il tag <b>, ad esempio, facilmente identificabile nella figura, indica che il testo racchiuso tra i tag dovrà essere rappresentato in grassetto.

Origine di SGML

SGML è un discendente del linguaggio GML, Generalized Markup Language della IBM, sviluppato negli anni 60 da Charles Goldfarb, Edward Mosher e Raymond Lorie.
In origine fu pensato per permettere la condivisione di documenti elettronici in grandi progetti nell'industria governativa, legale e aerospaziale, documenti che avrebbero dovuto avere la caratteristica di rimanere leggibili per molti decenni (un tempo lunghissimo nell'industria informatica). Il suddetto linguaggio è stato usato anche nel settore della stampa e della pubblicistica, ma la sua complessità ne ha impedito la diffusione anche nell'uso su piccola scala.

Differenza tra SGML e HTML

L'esempio seguente mostra due tipi di sorgenti, il primo in SGML, il secondo in HTML, utilizzati nel libro LFS.

<para>Avviare un programma di partizionamento come
<command>cfdisk</command> o <command>fdisk</command> con un'opzione a
linea di comando che nomini il disco su cui dovrà essere creata la nuova partizione.
Per esempio <filename class="devicefile">/dev/hda</filename> per
il disco IDE (Integrated Drive Electronics) primario.
Creare quindi una partizione nativa Linux e, se necessaria, una partizione di
<systemitem class="filesystem">swap</systemitem>.
Se non si sa come usare questi programmi si può fare riferimento a
<filename>cfdisk(8)</filename> o <filename>fdisk(8)</filename>.</para>

<p>
Avviare un programma di partizionamento come <span><strong class=
"command">cfdisk</strong></span> o <span><strong class=
"command">fdisk</strong></span> con un'opzione a linea di comando che
nomini il disco su cui dovrà essere creata la nuova partizione. Per
esempio <tt class="filename">/dev/hda</tt> per il disco IDE
(Integrated Drive Electronics) primario. Creare quindi una partizione
nativa Linux e, se necessaria, una partizione di <tt class=
"systemitem">swap</tt>. Se non si sa come usare questi programmi si
può fare riferimento a <tt class="filename">cfdisk(8)</tt> o
<tt class="filename">fdisk(8)</tt>.
</p>

Il sorgente del primo esempio è un'applicazione di SGML pensata per la scrittura di documentazione tecnica chiamata DocBook.
In particolare il formato è un SGML semplificato che si chiama XML.

Apparentemente i due sorgenti sono molto simili, l'unica differenza consiste nel fatto che i tag usati hanno nomi diversi.
Nella pratica però è tutto completamente diverso. Il codice HTML, infatti, può essere caricato in un browser ed essere letto a video, mentre il sorgente XML, essendo scritto in un metalinguaggio, non può essere direttamente visualizzato ma deve essere trasformato nel formato definitivo con appositi tool.
Lo svantaggio della necessità di un ulteriore passaggio per poter usufruire del documento è ampiamente compensato da altre caratteristiche. Il documento, infatti, viene scritto una sola volta, il suo formato è neutrale e il suo scopo è di catturare la struttura logica del contenuto e non come esso viene rappresentato. Tale contenuto può successivamente essere pubblicato in una varietà di formati, tra cui l' HTML come nell'esempio, ottenuto proprio dal sorgente XML, o il formato PDF, Postscript (pensato per stampe ad alta qualità), o testo, utilizzando i tool di trasformazione di DocBook.

I sorgenti, come nel primo esempio, sono proprio quelli che si trovano nella documentazione prodotta da TLDP, ed è perciò importante che il traduttore capisca come definire o cambiare tale sorgente per poterlo tradurre. In effetti il significato dei tag è abbastanza intuitivo: i tag <para> e </para> indicano l'inizio e il termine di un paragrafo, <command> e </command> racchiudono un comando, <filename class="devicefile"> e </filename> un nome di file, con la specificazione del tipo di file (class="devicefile"). Ciò che bisogna tradurre, quindi, non è il testo dentro ai tag, ma quello che sta tra i tag. Esiste però qualche eccezione. Si prenda come esempio il seguente sorgente tradotto:

Può essere trovato anche tramite <htmlurl
url="http://metalab.unc.edu/LDP/" name="Linux Documentation
Project">
<htmlurl url="http://metalab.unc.edu/LDP/HOWTO/" name="HOWTO repository">

I due tag indicano chiaramente quello che nel documento sarà un link in un formato elettronico, ma il risultato finale di tale traduzione sarà:

Può essere trovato anche tramite Linux Documentation
Project HOWTO repository

Ciò che bisogna tenere presente è che il traduttore dovrebbe sapere in questo caso che il parametro name= all'interno del tag indica quale sarà il nome con il quale il link verrà rappresentato. Con questa nuova informazione possiamo vedere con occhio diverso il sorgente precedente, e tradurlo più consapevolmente in questo modo:

Può essere trovato anche tramite il
<htmlurl url="http://metalab.unc.edu/LDP/HOWTO/" name="repository degli HOWTO">
del <htmlurl url="http://metalab.unc.edu/LDP/" name="Linux Documentation Project">.

che nel formato definitivo diventerà:

Può essere trovato anche tramite il repository degli HOWTO del Linux Documentation
Project.

Esiste dunque un'eccezione alla regola che consiste nel non tradurre ciò che è all'interno dei tag. Poiché è impossibile sviscerare tutte le eccezioni alla regola, data la complessità di DocBook, solo il tempo e l'esperienza daranno al traduttore la sensibilità necessaria per capire di volta in volta come comportarsi.

I formati della documentazione di ILDP

Poiché ILDP traduce principalmente documentazione pubblicata da TLDP, acronimo di The Linux Documentation Project, ne adotta anche i formati. Anni fa TLDP propose un'applicazione di SGML per la documentazione, applicazione che tentava di semplificarne notevolmente la struttura e di rendere questo linguaggio accessibile al maggior numero possibile di utenti. Fu così che nacque Linuxdoc. Il formato fu inizialmente adottato per la scrittura di HOWTO e guide, ma col passare del tempo il progressivo affermarsi di DocBook quale standard per la scrittura di documentazione tecnica fece sì che Linuxdoc venisse abbandonato a favore di quest'ultimo. Oggi esistono ancora numerosi HOWTO scritti in Linuxdoc (più o meno la metà del totale), tuttavia questo formato è chiaramente in declino.

Differenze tra Linuxdoc e DocBook

Ciò che differenzia enormemente Linuxdoc da DocBook è la semplicità. Linuxdoc è stato pensato come una semplificazione di SGML, mentre DocBook è nato per sfruttare tutte le potenzialità di questo linguaggio.

E' possibile verificare la differenza dei due formati consultando il sito web all'indirizzo http://www.tldp.org e scaricando due HOWTO nei diversi formati. Fondamentalmente DocBook è molto più prolisso e richiede molti più tag, mentre Linuxdoc, semplificando notevolmente la struttura, permette di omettere alcune cose. Si veda questo esempio.

Per enfatizzare la parola "release" in DocBook si userà:

<emphasis>release</emphasis> release

Mentre in Linuxdoc:

<em>release</em>

Per iniziare una sezione in DocBook:

<sect>
<title>Introduzione<title>

Mentre in Linuxdoc:

<sect>Introduzione

Utilizzando DocBook il lavoro di scrittura diventa eccessivo, mentre in Linuxdoc anche i meno esperti possono imparare e scrivere documenti.
Tuttavia l'affermazione di DocBook ha fatto sì che Linuxdoc sia via via non più consultato e utilizzato da molti. Per facilitare il passaggio a coloro che ancora usano Linuxdoc esistono alcuni tool, che pur non eliminando la necessità di un controllo manuale del file la riducono notevolmente.

Nel caso in cui non si è pienamente sicuri che il documento che si possiede sia in DocBook o Linuxdoc è sufficiente guardare il tag di dichiarazione, all'inizio del documento.
Nel caso di Linuxdoc si troverà:

<!doctype linuxdoc system>

Mentre nel DocBook si troverà:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
     "http://docbook.org/xml/4.2/docbookx.dtd">

Tradurre un documento

Il vantaggio del traduttore è che la complessità di DocBook riguarda quasi esclusivamente l'autore del documento. Chi traduce trova già i tag e la struttura, e quindi deve solo tradurre il testo tra i tag. È importante, comunque, come regola generale, ricordarsi di avvisare della traduzione l'autore del documento. Questo fa parte della netiquette che permette all'autore di sapere che il suo lavoro è stato condiviso e apprezzato.
È importante anche che sia il traduttore che il revisore mettano il proprio nome nel documento. Questo solitamente lo si fa nel sommario o abstract. Il tag utilizzato è lo stesso per entrambi i formati.

L'esempio seguente è stato tratto da "Howtos with Linuxdoc HOWTO"

<abstract>
Questo testo tratta di come scrivere gli HOWTO usando il marcatore
(markup) semplice di LinuxDoc. È rivolto principalmente agli
autori di LDP (Linux Documentation project) (e autori futuri che
vorranno iniziare rapidamente). Se si vuole usare DocBook, il marcatore
più avanzato, (che include XML) vedere la Guida Autorevole di LDP.
Traduzione ed adattamenti in italiano a cura di Hugh Hartmann
<tt/hhartmann@libero.it/, revisione a cura di Giulio Daprelà
<tt/giulio@pluto.it/
</abstract>

Esso verrà rappresentato a video in questo modo:

Figura 2: sommario, o "abstract" di "Howtos with Linuxdoc HOWTO"

Alcuni marcatori di DocBook

Di seguito vengono elencati alcuni marcatori significativi di DocBook.
È molto importante, per chi conosce l' HTML, uscire dalla logica del linguaggio di presentazione e entrare in quella del linguaggio strutturale. Il linguaggio di presentazione, o presentation markup (si veda la bibliografia), si occupa dell'aspetto del documento, mentre il linguaggio strutturale o structural markup si preoccupa solo di definire il tipo di elemento, disinteressandosi di come verrà rappresentato. Non esistono quindi tag come <br> per andare a capo.
In SMGL si delimitano i paragrafi, i titoli, ma non si danno, ad esempio, le dimensioni dei caratteri o il tipo di font da usare. Quello è compito della traduzione nel formato definitivo.

• <article> - </article> = viene posto all'inizio e alla fine del documento, e ne identifica la tipologia. Invece di article potrebbe essere, ad esempio, <book> - </book>

• <para> - </para> = delimitatori di paragrafo

• <sect1> - </sect1> = delimita una sezione. Possono essere nidificati, nel qual caso le sezioni ulteriori hanno numeri crescenti. Di solito è seguito dal tag

• <title> - </title> = racchiude il titolo della sezione

• <itemize> - </itemize> = racchiude una lista

• <item> - </item> = elemento di una lista non numerata

• <enum> - </enum> = elemento di una lista numerata

• <abstract> - </abstract> = racchiude il sommario del documento

• <author> - </author> = tag che racchiude le informazioni sull'autore del documento. I tag "author" racchiudono spesso i tag di informazioni personali come:

• <firstname> - </firstname> = nome dell'autore

• <surname> - </surname> = cognome dell'autore

• e così via

Il copyright

Nei documenti SGML il copyright si trova in una sezione dedicata.
Il copyright non va mai tradotto, perché ovviamente è un lavoro inutile e in casi necessità bisogna sempre ricordarsi e tener presente che fa fede il testo in lingua originale, poiché la traduzione potrebbe non rispecchiarne fedelmente il significato.

Riferimenti bibliografici

[1] Il sito di DocBook:
http://www.docbook.org/

[2]Appunti di informatica libera - di Daniele Giacomini

Introduzione a SGML

[3] DocBook su Wikipedia:
http://en.wikipedia.org/wiki/Docbook

[4] La voce SGML su Wikipedia:
http://en.wikipedia.org/wiki/SGML

[5] La voce XML su Wikipedia:
http://en.wikipedia.org/wiki/XML

[6] Differenza tra presentation markup e structural markup:
Structural markup: a primer

[7] Howtos with Linuxdoc HOWTO
http://www.pluto.it/files/ildp/HOWTO/Howtos-with-LinuxDoc/Howtos-with-LinuxDoc.html

[8] DocBook demistification HOWTO
http://www.pluto.it/files/ildp/HOWTO/DocBook-Demystification-HOWTO/index.html

[9] DocBook install mini HOWTO
http://www.pluto.it/files/ildp/HOWTO/DocBook-Install/index.html

[10] DocBook XML/SGML Processing Using OpenJade
http://www.pluto.it/files/ildp/HOWTO/DocBook-OpenJade-SGML-XML-HOWTO/index.html

<- Guida per il revisore di ILDP - Indice Generale - Copertina - Come funziona e come si traduce una man page ->