[successivo] [precedente] [inizio] [fine] [indice generale] [indice ridotto] [indice analitico] [home] [volume] [parte]


Capitolo 467.   Sistemi SGML basati su Qwertz

Il sistema standard utilizzato inizialmente per la documentazione di GNU/Linux si è basato sul DTD Qwertz, dal quale hanno avuto origine una serie di derivazioni e di strumenti di composizione SGML che hanno avuto una certa importanza.

In questo capitolo si intende mostrare solo il funzionamento essenziale di alcuni di questi strumenti di composizione; in particolare LinuxDoc e DebianDoc.

Tra tutte le derivazioni di strumenti di composizione SGML basati originariamente sul DTD Qwertz, DebianDoc sembra essere stato il sistema più coerente, con il quale si garantiva la composizione tipografica dal formato PostScript alla pagina di manuale pura e semplice.

467.1   Struttura di LinuxDoc

La struttura di un sorgente SGML secondo il DTD LinuxDoc è generalmente la seguente:

<!DOCTYPE linuxdoc SYSTEM>
<article>
<titlepag>
<title>Titolo del documento</title>
<author>
        <name>Pinco Pallino ppallino@dinkel.brot.dg</name>
</author>
<date>29/02/1999</date>
<abstract>
Breve introduzione al documento.
</abstract>
</titlepag>
<toc>
<sect>Prima sezione
<p>
Contenuto della prima sezione,
...
...
(eventuali altre sezioni)
</article>

Con l'istruzione <!DOCTYPE linuxdoc SYSTEM> si afferma di voler utilizzare il DTD linuxdoc. Il documento è delimitato dall'elemento article che rappresenta uno tra i diversi tipi di struttura possibile del documento. Il DTD LinuxDoc è derivato dal Qwertz che è strutturato in modo da imitare il comportamento di LaTeX. In questo modo, nel DTD originale sono previste diverse strutture, tutte riferite ad analoghi tipi di documento LaTeX. La tendenza generale è quella di utilizzare sempre solo la struttura article, soprattutto perché lo scopo di SGMLtools è stato quello di permettere la trasformazione del sorgente SGML in un grande numero di altri formati, non solo LaTeX.

Dopo l'inserimento dell'elemento title e di tutto ciò che deve contenere (titolo, autore, descrizione del documento), è possibile inserire il marcatore <toc>, con il quale si intende ottenere un indice generale.

Dopo l'indice generale inizia il testo del documento, suddiviso in sezioni, il cui inizio è evidenziato dai marcatori: <sect>, <sect1>, <sect2>.

467.1.1   Utilizzo sommario

Attraverso SGMLtools, si ottiene un documento finale a partire da un sorgente SGML. Per questo, si elabora il sorgente come si fa con un linguaggio di programmazione durante la compilazione. La prima fase è il controllo di validità.

sgmlcheck sorgente_sgml

Una volta verificata la correttezza formale dal punto di vista del DTD, si può richiedere la trasformazione in un altro formato. Nell'elenco seguente vengono mostrati solo alcuni tipi di trasformazione, i più importanti. In effetti non tutto funziona nello stesso modo e alcuni tipi di conversioni sono difettosi.

Quando si progetta di realizzare un documento attraverso SGMLtools/LinuxDoc, è importante decidere subito quali formati devono essere ottenuti necessariamente, in modo da poter controllare il loro funzionamento dall'inizio dell'opera. Per esempio, il fatto che si riesca a ottenere un formato PostScript corretto, non garantisce che gli altri formati generino un risultato altrettanto buono.(1)

La conversione in LaTeX si ottiene facilmente attraverso il comando seguente:

sgml2latex --output=tex sorgente_sgml

Viene generato un file con lo stesso nome del sorgente, terminante con l'estensione .tex. Questo file contiene riferimenti a stili addizionali che fanno parte del pacchetto SGMLtools. Questo fatto deve essere tenuto in considerazione se si vuole poi rielaborare questo file con LaTeX.

La composizione del documento in PostScript avviene attraverso l'elaborazione successiva da parte di LaTeX, richiamato automaticamente da SGMLtools.

sgml2latex --output=ps sorgente_sgml

Quello che si ottiene è un file con lo stesso nome del sorgente, terminante con l'estensione .ps.

La conversione in formato HTML viene gestita completamente all'interno di SGMLtools, attraverso il sistema di programmi in Perl che lo compongono.

sgml2html sorgente_sgml

Si ottengono una serie di file HTML collegati attraverso riferimenti ipertestuali.

467.1.2   Supporto per altri SGML

SGMLtools ha un supporto limitato per HTML. Precisamente, consente di verificare un file HTML attraverso il DTD HTML 3.2. Si può usare il comando seguente, che è lo stesso visto nel caso dei file SGML.

sgmlcheck sorgente_html

sgmlcheck determina da solo che si tratta di un file HTML. Comunque, un file HTML corretto dovrebbe iniziare con la dichiarazione seguente:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

Eventualmente, sono ammissibili anche altre forme,

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Draft//EN">

dove Draft si riferisce in particolare alla prima stesura della versione 3.2.

Si può osservare che un file HTML apparentemente corretto dato il risultato che si ottiene con il programma usato per visualizzarlo, può contenere un gran numero di errori formali secondo il suo DTD.

467.2   LinuxDoc più in dettaglio

Lo standard LinuxDoc, come suggerisce il nome, è quello che si è utilizzato originariamente per la documentazione di GNU/Linux. Del DTD relativo, linuxdoc.dtd, vengono sfruttate ufficialmente solo alcune delle caratteristiche. Per esempio, la definizione dell'incorporazione di immagini e le tabelle sono rimaste come eredità dallo standard Qwertz, ma il loro utilizzo va evitato, preferendo piuttosto l'uso di strumenti SGML basati su DocBook.

467.2.1   Preambolo e definizione dello stile

Come accennato all'inizio del capitolo, un documento LinuxDoc inizia con un preambolo che descrive il tipo di documento (linuxdoc appunto), lo stile (in questo caso article), il titolo, l'autore e altre informazioni eventuali.

<!DOCTYPE linuxdoc SYSTEM>

<article>

<titlepag>
<title>Il mio primo articolo</title>
<author>Pinco Pallino, pincop@dinkel.brot.dg</author>
<date>v0.01, 29 febbraio 1999</date>
<abstract>
Breve anticipazione del contenuto del documento.
</abstract>
</titlepag>

<toc>

<sect>Prima sezione
<p>
Contenuto della prima sezione.

</article>

Dopo il preambolo può essere collocato un indice generale che viene costruito automaticamente attraverso l'elemento toc. Quindi si può iniziare il corpo del documento suddiviso in sezioni. Al termine, la chiusura dello stile dichiarato nel preambolo definisce la fine del documento.

Lo stile article è quello standard per i documenti LinuxDoc ed è anche quello raccomandato. Consente la suddivisione del documento per sezioni e non per capitoli. Viene chiuso alla fine del documento.

467.2.2   Suddivisione del documento

A seconda dello stile di documento utilizzato, la suddivisione del contenuto può avvenire in modi differenti. In pratica, utilizzando lo stile article, la suddivisione avviene solo per sezioni, identificate dall'elemento sect.

  1. sect

  2. sect1

  3. sect2

Ciò significa che una sezione sect può scomporsi in sottosezioni sect1, che a loro volta si possono scomporre in altre sottosezioni di livello inferiore sect2, ecc. In generale, se possibile, è conveniente limitarsi soltanto a due livelli di suddivisione.

<!DOCTYPE linuxdoc SYSTEM>

<article>

<titlepag>
<title>Il mio primo articolo</title>
<author>Pinco Pallino, pincop@dinkel.brot.dg</author>
<date>v0.01, 29 febbraio 1999</date>
<abstract>
Breve anticipazione del contenuto del documento.
</abstract>
</titlepag>

<toc>

<sect>Prima sezione
<p>
Contenuto della prima sezione.
...

<sect1>Una sottosezione
<p>
Contenuto della sottosezione.
...

<sect>Seconda sezione
<p>
...
...

</article>

L'ambiente delimitato da una sezione di qualunque livello, non richiede l'indicazione esplicita della sua conclusione. È invece necessaria l'inserzione dell'indicazione dell'inizio di un paragrafo, subito dopo il titolo della sezione stessa. L'esempio mostrato sopra dovrebbe chiarirne il funzionamento.

467.2.3   Paragrafi

Il testo di un documento normale è suddiviso in paragrafi. L'indicazione dell'inizio o della conclusione di un paragrafo è facoltativa. È sufficiente staccare i paragrafi con almeno una riga bianca per dare questa informazione a LinuxDoc. Resta comunque possibile l'indicazione esplicita dei paragrafi attraverso l'elemento p. È obbligatoria l'indicazione dell'inizio del primo paragrafo di una sezione, perché non esiste altro modo per capire quando finisce il titolo (della sezione) e quando inizia il testo.

467.2.4   Elenchi

Si hanno a disposizione tre tipi di elenchi: descrittivo (descrip), puntato (itemize) e numerato (enum).

L'elenco descrittivo è definito dall'elemento descrip. Le parti descrittive di questo elenco sono costituite da elementi tag. Ciò che è contenuto all'interno della sequenza <tag>...</tag> appare evidenziato in un'unica riga e generalmente non può contenere simboli particolari (dipende dal tipo di trasformazione che si vuole ottenere). Per esempio:

<descrip>
<tag>primo</tag>primo elemento;
<tag>secondo</tag>secondo elemento;
<tag>terzo</tag>terzo elemento.
</descrip>

genera l'elenco seguente:

primo
    primo elemento;

secondo
    secondo elemento;

terzo
    terzo elemento.

L'elenco puntato è costituito dall'elemento itemize che si articola in elementi item, che in pratica costituiscono le varie voci dell'elenco. Per esempio:

<itemize>
<item>primo elemento;
<item>secondo elemento;
<item>terzo elemento.
</itemize>

genera l'elenco puntato seguente:

* primo elemento;
* secondo elemento;
* terzo elemento.

L'elenco numerato è costituito dall'elemento enum che si articola in elementi item, come nel caso dell'elenco puntato. Per esempio:

<enum>
<item>primo elemento;
<item>secondo elemento;
<item>terzo elemento.
</enum>

genera l'elenco numerato seguente:

1 primo elemento;
2 secondo elemento;
3 terzo elemento.

Generalmente, se il tipo di composizione finale lo consente, gli elenchi possono essere annidati e contenere anche testo normale che viene rappresentato allineato in modo opportuno.

<descrip>
<tag>primo</tag>
        Primo elemento descrittivo.

        Continuazione del primo elemento descrittivo.

<tag>secondo</tag>
        Secondo elemento descrittivo.

        <enum>
        <item>Prima suddivisione.

                <enum>
                <item>Ulteriore suddivisione.
                <item>Ancora un altro punto.
                </enum>

        <item>Seconda suddivisione.

                <itemize>
                <item>Ecco un sottoelenco puntato.
                <item>Un secondo elemento dell'elenco puntato.
                </itemize>

        <item>Terza suddivisione.
        </enum>

<tag>terzo</tag>
        Terzo elemento descrittivo.

</descrip>

L'esempio sopra riportato si traduce in qualcosa che è simile a ciò che segue:

primo
    Primo elemento descrittivo.

    Continuazione del primo elemento descrittivo.

secondo
    Secondo elemento descrittivo.

    1  Prima suddivisione.

        a  Ulteriore suddivisione.
        b  Ancora un altro punto.

    2  Seconda suddivisione.

        *  Ecco un sottoelenco puntato.
        *  Un secondo elemento dell'elenco puntato.

    3  Terza suddivisione.

terzo
    Terzo elemento descrittivo.

467.2.5   Inclusione di testo letterale

Si incontra spesso la necessità di includere in un documento del testo letterale. In generale si tratta di listati di programma o cose simili che possono contenere caratteri o simboli che di solito dovrebbero essere scritti utilizzando dei codici macro particolari. Per questo si utilizza l'elemento verb.

Al suo interno è consentito includere un testo che deve essere riprodotto esattamente com'è, spazi e caratteri strani inclusi, utilizzando, quando possibile, lo stesso carattere usato per il testo normale. Per quanto riguarda la libertà di inclusione di simboli, esiste comunque una piccola limitazione:

Di solito, il testo contenuto in questo elemento è preferibile che appaia in un carattere dattilografico. Per questo, generalmente, verb viene a sua volta inserito in un elemento tscreen.

<tscreen><verb>
Ecco un testo che contiene strani simboli # \ [ ].
</verb></tscreen>

467.2.6   Testo citato

Quando si cita del testo o si vuole fare risaltare una nota, si usano rientri e tipi di carattere diversi. Gli elementi utilizzati per questo scopo sono: quote e tscreen.

All'interno dell'elemento tscreen il testo viene riportato tutto con caratteri a larghezza fissa e rientrato leggermente. Di solito viene usato per incorporare l'elemento verb, in modo da poter inserire simboli particolari senza la necessità di doverli convertire.

<tscreen>
Ecco del testo riportato con carattere a larghezza fissa
o dattilografico.
</tscreen>

L'elemento quote fa in modo di rientrare leggermente il testo, per fare risaltare che si tratta di una citazione.

<quote>
Senza nessuna precisazione, i documenti Linux HOWTO hanno
il copyright dei loro rispettivi autori. I documenti Linux
HOWTO possono essere riprodotti e distribuiti, completi o in...
</quote>

467.2.7   Enfatizzazioni

All'interno di un testo normale è possibile intervenire per modificare l'aspetto del carattere. Generalmente, qualsiasi intervento verso la definizione dell'aspetto del risultato finale è inopportuno in un sorgente SGML. Infatti, SGML dovrebbe servire per definire gli oggetti che compongono il testo e il documento in generale; quindi, è compito dei programmi di conversione attribuire un aspetto particolare al risultato finale.

LinuxDoc consente ancora di intervenire sull'aspetto di alcune parti di testo, attraverso l'indicazione di testi in corsivo, neretto e dattilografico. Resta tuttavia da considerare che queste possibilità sono destinate a scomparire, in favore di una definizione più precisa delle componenti del testo.

L'elemento bf si utilizza per rendere in neretto il testo racchiuso.

Esempio di un testo in <bf>neretto o bold face</bf>.

L'elemento it si utilizza per rendere in corsivo il testo racchiuso.

Esempio di un testo <it>corsivo</it>.

L'elemento tt si utilizza per rendere in carattere dattilografico il testo racchiuso.

Esempio di un testo <tt>a larghezza fissa o dattilografico</tt>.

467.2.8   Riferimenti incrociati

Possono essere fatti dei riferimenti interni o esterni al documento. Generalmente, all'interno del documento si utilizza l'elemento label come segnaposto e l'elemento ref come puntatore. Per fare dei riferimenti all'esterno del documento, si fa uso dell'elemento url oppure di htmlurl.

Un'etichetta, definita attraverso l'elemento label, permette di marcare una posizione nel documento a cui si vuole poter fare riferimento. Si tratta di un elemento vuoto che contiene un attributo obbligatorio: ID. Questo attributo contiene il valore dell'etichetta che identifica quindi la posizione che si vuole marcare.

<sect>Note personali<label id="note1">
<p>
        bla bla bla bla...

L'esempio mostra un possibile uso di label per marcare l'inizio di una sezione. In linea di massima, un'etichetta di questo genere permette di fare riferimenti di due tipi: la pagina in cui si trova e il numero della sezione o dell'oggetto, in relazione al contesto in cui si trova. Un'etichetta può apparire nei contesti seguenti:

È importante che queste etichette-segnaposto non contengano caratteri strani, altrimenti il programma di composizione potrebbe non gestirle correttamente.

Un elemento ref si comporta come puntatore o riferimento a un'etichetta definita attraverso l'elemento label. All'interno di un documento stampato genera un riferimento numerico che dipende dal contesto in cui si trova l'etichetta (il numero della sezione, della figura o della tabella), mentre in un documento HTML genera un riferimento ipertestuale (link).

Si tratta di un elemento vuoto che contiene un attributo obbligatorio, ID, e uno opzionale, NAME. L'attributo ID contiene il nome dell'etichetta a cui si intende fare riferimento, l'attributo NAME viene inserito per dare un nome al riferimento che viene creato quando si genera un documento HTML.

Vedere la sezione <ref id="linuxdoc-xref-ref" name="riferimento">.

Un elemento pageref di comporta come puntatore o riferimento a un'etichetta. All'interno di un documento stampato genera un riferimento al numero della pagina che contiene l'etichetta.(2)

Si tratta di un elemento vuoto che contiene un attributo obbligatorio, ID, destinato a contenere il nome dell'etichetta a cui si intende fare riferimento.

Un elemento url si comporta come riferimento a un URI. All'interno di un documento stampato genera la rappresentazione di questo indirizzo URI, mentre in un documento HTML crea un riferimento ipertestuale vero e proprio. Un elemento htmlurl si comporta in maniera analoga, ma non riporta l'indirizzo URI nel documento stampato.(3)

Si tratta di elementi vuoti che contengono un attributo obbligatorio, URL, destinato a indicare l'indirizzo URI a cui si intende fare riferimento, e uno opzionale, NAME. Si osservi la differenza tra i due tipi di puntatori attraverso l'esempio seguente:

<url url="http://ildp.psy.unipd.it/" name="ILDP">
&egrave; il progetto di documentazione di Linux in italiano.

<htmlurl url="http://ildp.psy.unipd.it/" name="ILDP">
&egrave; il progetto di documentazione di Linux in italiano.

Nel primo caso, assieme al valore dell'attributo NAME viene visualizzato anche l'URI, mentre nel secondo viene mostrato solo il valore di NAME.

L'elemento footnote permette di inserire una nota che da stampare a piè di pagina (ma potrebbe non funzionare correttamente nella composizione in HTML).

LinuxDoc &egrave; una derivazione di
Qwertz<footnote>Il nome della tastiera tedesca.</footnote>.

467.2.9   Indici

Il sistema è in grado di generare automaticamente l'indice generale del documento e un indice analitico. Per ottenere l'indice generale è sufficiente inserire l'elemento toc (vuoto) subito dopo il preambolo. L'esempio seguente mostra in che modo si può inserire un indice di questo tipo.

<!DOCTYPE linuxdoc SYSTEM>

<article>

<titlepag>
<title>Il mio primo articolo</title>
<author>Pinco Pallino, pincop@dinkel.brot.dg</author>
<date>v0.01, 29 febbraio 1999</date>
<abstract>
Breve anticipazione del contenuto del documento.
</abstract>
</titlepag>

<toc>

<sect>Prima sezione
<p>
Contenuto della prima sezione.

</article>

Ogni tipo di conversione in un formato finale del documento SGML gestisce la generazione dell'indice generale a modo proprio. Di solito sono garantiti solo due livelli di titoli (sezioni).

L'indice analitico potrebbe essere disponibile solo per la conversione attraverso LaTeX. Si ottiene marcando alcune porzioni di testo attraverso l'elemento nidx, oppure ncdx, come nell'esempio seguente:

<sect>Pallini e sfere<nidx>pallino</nidx><ncdx>sfera</ncdx>
<p>
Questa sezione tratta di pallini e sfere in generale, fino a giungere
alla descrizione dei cuscinetti a sfera.<nidx>cuscinetto a sfera</nidx>

Quanto contenuto all'interno degli elementi nidx e ncdx non viene a fare parte del testo; tutte le conversioni che non possono farne uso lo trattano come un commento da ignorare. La conversione in LaTeX genera corrispondentemente il comando LaTeX \index{...}, ma nel caso particolare di ncdx, vengono aggiunti dei codici di composizione in modo tale che nell'indice la stringa corrispondente appaia evidenziata con un testo dattilografico.

Per usare in pratica l'indice analitico, occorrono diverse fasi:

La generazione del file indice avviene attraverso il comando seguente:

sgml2latex --makeindex sorgente_sgml

Si ottiene un file, il cui nome ha la stessa radice del sorgente SGML e l'aggiunta dell'estensione .idx. Questo file deve essere rielaborato da makeindex che è un programma abbinato alle distribuzioni comuni di LaTeX.

makeindex < indice_generato > indice_rielaborato

Il file dell'indice rielaborato potrebbe avere la fisionomia dell'esempio seguente:

\begin{theindex}

  \item cuscinetto a sfera, 1
  \item cuscino, 15

  \indexspace

  \item pallino, 87
  \item pallone, 82
  \item pallottola, 54, 55
  \item pallottoliere, 50

  \indexspace

  \item {\tt sfera}, 30, 43
  \item steroide, 23

\end{theindex}

Per giungere a un risultato finale, cartaceo, occorre aggiungergli qualcosa in modo che diventi un documento LaTeX vero e proprio. Come nell'esempio seguente:

\documentclass[a4paper]{article}

\usepackage[italian]{babel}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}

\begin{document}

\begin{theindex}

  \item cuscinetto a sfera, 1
  \item cuscino, 15

  \indexspace

  \item pallino, 87
  \item pallone, 82
  \item pallottola, 54, 55
  \item pallottoliere, 50

  \indexspace

  \item {\tt sfera}, 30, 43
  \item steroide, 23

\end{theindex}

\end{document}

In tal modo, attraverso LaTeX si può passare alla trasformazione in un documento finale DVI; successivamente, attraverso dvips, si può ottenere una trasformazione in PostScript.

latex documento_latex
dvips -o documento_ps documento_dvi

467.2.10   Inclusione di immagini

All'interno di un documento è possibile fare riferimento a immagini in formato EPS (Encapsulated PostScript), che vengono utilizzate nella trasformazione in PostScript attraverso LaTeX e dvips. Parallelamente è possibile fare anche riferimento a immagini (di solito equivalenti) in formati diversi, adatti alla trasformazione in HTML.

L'elemento figure racchiude le informazioni necessarie per l'inserzione di un'immagine. All'interno del marcatore di apertura è possibile specificare la posizione prescelta dell'immagine, per la trasformazione attraverso LaTeX, utilizzando l'attributo LOC (location). In pratica conviene quasi sempre utilizzare la stringa htbp che dice a LaTeX di collocare l'immagine nel posto più adatto, cominciando dalla posizione di partenza (here), quindi nella parte superiore della pagina (top), poi ancora nella parte inferiore (bottom) e infine, se ogni tentativo fallisce, in una pagina dedicata (page). Il valore predefinito di questo attributo è tbp con il significato che si può intuire.

<figure LOC=htbp>
        <eps file="esempio" height="5cm">
</figure>

L'esempio indica di visualizzare l'immagine esempio.ps collocata nella directory figure/ a partire dalla posizione corrente.

L'elemento eps serve all'interno di un elemento figure per definire il file da visualizzare utilizzando l'attributo FILE. Questo file viene poi utilizzato nella composizione in PostScript attraverso LaTeX. Il nome del file che viene fornito non deve contenere l'estensione .ps che è sottintesa e obbligatoria. Un altro attributo obbligatorio è HEIGHT, con cui si definisce l'altezza dell'immagine. L'esempio già mostrato in precedenza, specificava a questo proposito un'altezza di 5 cm. La larghezza viene regolata in proporzione.

L'elemento img serve invece a definire il file da visualizzare per la composizione in HTML. Anche in questo caso si utilizza l'attributo FILE. Al contrario del caso di eps, il nome del file che viene fornito deve essere indicato completo di estensione.

<figure LOC=tbp>
        <eps file="esempio" height="5cm">
        <img src="figure/esempio.jpg">
</figure>

L'esempio indica di includere l'immagine esempio.ps, per la composizione attraverso LaTeX, e esempio.jpg per quella in HTML.

L'elemento caption può essere usato all'interno della definizione di una figura per indicare la descrizione o il titolo della figura stessa. All'interno di questa descrizione si può inserire anche un'etichetta, l'elemento label, in modo da permettere un riferimento al numero della figura all'interno del testo.

<figure LOC=tbp>
        <eps file="esempio" height="5cm">
        <img src="figure/esempio.jpg">
        <caption>
                <label id="figura-esempio">
                Immagine di esempio
        </caption>
</figure>

L'esempio inserisce la figura rappresentata dal file esempio.ps, nel caso di trasformazione in LaTeX, oppure esempio.jpg in caso di trasformazione in HTML; inoltre appare una descrizione e un'etichetta per potervi fare riferimento.

467.2.11   Tabelle

All'interno di un documento è possibile inserire delle tabelle, ma questo solo se si intende trasformare il proprio documento in LaTeX. In HTML si riesce a ottenere qualcosa, ma decisamente scadente. Per questo motivo, l'uso delle tabelle deve essere riservato ai casi di effettiva necessità.

Le tabelle sono composte essenzialmente da righe separate da un separatore di riga, dove ogni riga è suddivisa a sua volta in colonne attraverso un separatore di colonna.

L'elemento table delimita la zona di descrizione di una tabella. All'interno del marcatore di apertura è possibile specificare la posizione prescelta della tabella, utilizzando l'attributo LOC (location), che si comporta nello stesso modo di quello utilizzato nell'elemento figure.

L'elemento tabular, interno a table, definisce le caratteristiche di una tabella. All'interno del marcatore di apertura è necessario specificare l'allineamento orizzontale del contenuto delle celle e la separazione di queste attraverso linee verticali. l'attributo utilizzato per questo è CA (Column alignment) e il suo valore consigliabile è una stringa composta da una serie di lettere l, una per ogni colonna esistente nella tabella.

Le righe della tabella sono concluse dall'elemento rowsep, mentre le colonne sono staccate l'una dall'altra attraverso l'elemento colsep. È possibile inserire una linea orizzontale di separazione utilizzando l'elemento hline. Tutti questi elementi di descrizione delle righe, sono vuoti.

Si osservi questo esempio. Si suppone di voler rappresentare una tabella di quattro righe, più una di intestazione, divisa in due sole colonne, secondo lo schema seguente:

-----------------------------------------
Parametro LOC   Posizione corrispondente
-----------------------------------------
h               posizione attuale
t               superiore
b               inferiore
p               pagina
-----------------------------------------
        Esempio di tabella.

Il codice necessario è quello mostrato di seguito.

<table LOC=tbp>
<tabular colonne="2">
        <hline>
        Parametro loc   <sepcol> Posizione corrispondente       <rowsep>
        <hline>
        h               <sepcol> posizione attuale              <rowsep>
        t               <sepcol> superiore                      <rowsep>
        b               <sepcol> inferiore                      <rowsep>
        p               <sepcol> pagina                         <rowsep>
        <hline>
</tabular>
<caption>
        <label id="tabella-esempio">
        Esempio di tabella.
</caption>
</table>

467.2.12   Mappa dei caratteri

Alcuni caratteri che all'interno di LinuxDoc hanno un significato speciale, oltre a quelli che sono al di fuori della codifica ASCII standard, possono essere inseriti nel testo finale utilizzando dei codici macro; precisamente si tratta delle entità standard.(4)

Questi codici macro sono preceduti dalla e-commerciale (&) e seguiti da un punto e virgola. Nel capitolo 456 appare una tabella riferita alle entità standard di uso comune nell'SGML. Si tratta precisamente della tabella 456.25.

467.3   Struttura di DebianDoc

La struttura di un sorgente SGML secondo il DTD DebianDoc ricalca quello che si può vedere dall'esempio seguente:

<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN">
<debiandoc>
    <book>
        <titlepag>
            <title>Titolo del documento</title>
            <author>
                <name>Pinco Pallino</name>
                <email>ppallino@dinkel.brot.dg</email>
            </author>
            <version>29/02/1999</version>
            <abstract>
                Breve introduzione al documento.
            </abstract>
            <copyright>
                <copyrightsummary>
                    Copyright &copy; 1999 Pinco Pallino
                </copyrightsummary>

                <p>This work is free; you can redistribute it and/or
                modify it under the terms of the GNU General Public
                License as published by the Free Software Foundation;
                either version 2 of the License, or (at your option) any
                later version.</p>

            </copyright>
        </titlepag>
                
        <toc detail="sect">
                
        <chapt id="primo-capitolo">
            <heading>Primo capitolo</heading>

            <p>Contenuto del primo capitolo,
            ...
            ...
            </p>

            <sect id="prima-sezione">
                <heading>Prima sezione del primo capitolo</heading>

                <p>Contenuto della prima sezione,
                ...
                ...
                </p>

            </sect>
            ...
            ...
        </chapt>
        ...
        ...
        <appendix id=prima-appendice>
                <heading>Prima appendice</heading>

                <p>...
                ...
                </p>

        </appendix>
        ...
        ...
    </book>
    
</debiandoc>

Si può osservare una grande affinità con il DTD LinuxDoc, dove spicca in particolare il fatto che le etichette per la realizzazione di riferimenti incrociati sono inserite come attributi ID degli elementi di suddivisione del testo: chapt, sect,...

DebianDoc presume quindi che si tratti di un libro suddiviso in capitoli, gli elementi chapt, quindi in sezioni a vari livelli: sect, sect1, sect2, sect3 e sect4.

È speciale anche l'elemento di dichiarazione dell'indice generale, toc, che prevede l'attributo DETAIL, al quale si deve assegnare il nome del livello di suddivisione che si ritiene indispensabile includere nell'indice generale: nell'esempio mostrato vengono inclusi solo i capitoli e le sezioni del livello iniziale.

467.3.1   Organizzazione del catalogo, del DTD e delle entità

Dal punto di vista dell'SGML, DebianDoc è organizzato con un catalogo unico, che contiene le indicazioni seguenti:

DOCTYPE debiandoc                               dtd/debiandoc.dtd
PUBLIC "-//DebianDoc//DTD DebianDoc//EN"        dtd/debiandoc.dtd
ENTITY %general-chars                           entities/general

Queste righe vengono aggiunte al catalogo del sistema, corrispondente a /usr/share/sgml/catalog, che in pratica è un collegamento simbolico al file /etc/sgml.catalog. Leggendo le dichiarazioni del catalogo si intende che il DTD DebianDoc è costituito dal file dtd/debiandoc.dtd, ovvero /usr/share/sgml/dtd/debiandoc.dtd; inoltre, si vede che viene usato un solo file di entità generali: entities/general, ovvero /usr/share/sgml/entities/general.

467.3.2   Utilizzo sommario

Attraverso gli strumenti di DebianDoc, si ottiene un documento finale a partire da un sorgente SGML. Per questo, si elabora il sorgente come si fa con un linguaggio di programmazione durante la compilazione.

debiandoc2dvi [-k] [-p formato_carta] file_sgml
debiandoc2dvips [-k] [-p formato_carta] file_sgml
debiandoc2html [-k] file_sgml
debiandoc2info [-k] file_sgml
debiandoc2latex2e [-k] [-O] [--] file_sgml
debiandoc2lout [-k] [-O] [--] file_sgml
debiandoc2ps [-k] [-O] [-1] [-p formato_carta] [--] file_sgml
debiandoc2texinfo [-k] [-O] [--] file_sgml
debiandoc2text [-k] [-O] [--] file_sgml
debiandoc2textov [-k] [-O] [--] file_sgml

Ognuno di questi comandi elencati rappresenta un modo differente di elaborare e convertire un sorgente SGML scritto secondo il DTD DebianDoc. Il significato dei nomi dovrebbe essere intuitivo: debiandoc2html significa evidentemente «DebianDoc to HTML», ovvero, «da DebianDoc a HTML». Lo stesso vale, più o meno, per gli altri comandi. In breve:

Opzione Descrizione
-k
Fa in modo che i file intermedi, creati durante il procedimento di conversione, vengano conservati.
-O
Fa in modo che il risultato finale della trasformazione venga emesso attraverso lo standard output, quando di solito si crea invece un file con la stessa radice dell'origine e un'estensione opportuna. Se il sorgente è fornito attraverso lo standard input, questa opzione è implicita.
-1
Questa opzione riguarda espressamente debiandoc2ps, che senza di questa, genera un file PostScript in cui ogni pagina ne contiene due ridotte e affiancate (per mezzo di PSUtils). Con questa opzione, si ottengono pagine normali (singole).
-p dimensione_pagina
Questa opzione permette di specificare la dimensione della pagina, nelle trasformazioni in cui ciò può avere senso, facendo riferimento alla configurazione del pacchetto Papersize della distribuzione Debian.
--
In caso di ambiguità, un trattino doppio serve a separare le opzioni dal nome del file sorgente.

467.4   Guida rapida di DebianDoc

Dal momento che DebianDoc è molto simile a LinuxDoc e che la sua documentazione è abbastanza chiara, non è il caso di ripetere le stesse informazioni anche in questo capitolo. Eventualmente si può rileggere quello precedente. Qui vengono mostrati solo i prospetti riassuntivi degli elementi SGML principali di DebianDoc, attraverso delle tabelle.

Tabella 467.37. Elementi della struttura generale di un documento DebianDoc.

Elemento Descrizione
debiandoc
Il contenitore di un documento DebianDoc.
book
Il sotto-contenitore di un documento DebianDoc.
titlepag
La definizione della pagina del titolo.
title
Il titolo del documento.
author
L'autore (scomposto ulteriormente).
name
Il nome dell'autore.
email
L'indirizzo di posta elettronica dell'autore.
version
La versione del documento.
abstract
Una descrizione breve del contenuto.
copyright
Informazioni sul copyright.
copyrightsummary
Il copyright, in breve.
p
La descrizione della licenza.
toc
L'indice generale.
chapt
Il contenitore di un capitolo.
appendix
Il contenitore di un'appendice.

Tabella 467.38. Elementi che rappresentano la suddivisione gerarchica del contenuto di un documento DebianDoc.

Elemento Descrizione
chapt
Il contenitore di un capitolo.
appendix
Il contenitore di un'appendice (si articola come il capitolo).
sect
Sezione di un capitolo o di un'appendice.
sect1
Sotto-sezione di primo livello.
sect2
Sotto-sezione di secondo livello.
sect3
Sotto-sezione di terzo livello.
sect4
Sotto-sezione di quarto livello.
heading
Il titolo di: capitolo, appendice, sezione o sotto-sezione.

Tabella 467.39. Elementi che si utilizzano nel corpo del testo per modificare l'aspetto del loro contenuto in base al significato che rappresentano.

Elemento Descrizione
em
Enfasi normale (idealmente un corsivo).
strong
Enfasi più forte (idealmente un neretto).
var
Rappresentazione di una metavariabile (di uno schema sintattico).
package
Il nome di un pacchetto GNU/Linux.
prgn
Il nome di un programma o di un file ben conosciuto.
file
Il percorso di un file o di una directory.
tt
Una stringa letterale dattilografica.

Tabella 467.40. Riferimenti.

Elemento Descrizione
ref id="etichetta"
Riferimento a un'etichetta dichiarata altrove.
manref name="nome" \
  \section="n_sezione"
Riferimento a una pagina di manuale.
email
Contenitore di un indirizzo di posta elettronica.
ftpsite
Il nome di dominio di un sito FTP.
ftppath
Il percorso riferito all'ultimo sito FTP indicato.
httpsite
Il nome di dominio di un sito HTTP.
httppath
Il percorso riferito all'ultimo sito HTTP indicato.
url id="uri" name="nome"
Indirizzo URI completo.
footnote
Nota a piè pagina.

Tabella 467.41. Elenchi.

Elemento Descrizione
list
Elenco puntato.
item
Voce di un elenco.
enumlist
Elenco numerato.
item
Voce di un elenco.
taglist
Elenco descrittivo.
tag
Elemento descrittivo.
item
Voce di un elemento.

467.5   Riferimenti


1) Per fare un esempio evidente, basta pensare all'inserzione di immagini e a ciò che si può ottenere in un formato finale puramente testuale: niente immagini.

2) Non ha senso nella traduzione HTML.

3) L'elemento htmlurl crea qualche problema quando si vogliono indicare caratteri speciali nell'URI, come nel caso della tilde. Sotto questo aspetto, per evitare problemi, è meglio limitarsi all'uso di url.

4) LinuxDoc cerca di privilegiare in qualche modo l'ambiente matematico di LaTeX. Per richiamarlo è sufficiente delimitarlo attraverso le parentesi quadre, che così non possono essere usate in modo letterale. Come nel caso di altri simboli speciali, anche le parentesi quadre vanno indicate con l'uso di macro.


Appunti di informatica libera 2008 --- Copyright © 2000-2008 Daniele Giacomini -- <appunti2 (ad) gmail·com>


Dovrebbe essere possibile fare riferimento a questa pagina anche con il nome sistemi_sgml_basati_su_qwertz.htm

[successivo] [precedente] [inizio] [fine] [indice generale] [indice ridotto] [indice analitico] [home]

Valid ISO-HTML!

CSS validator!

Gjlg Metamotore e Web Directory