Capitolo 253. DebianDoc

DebianDoc è un'altra variazione sul tema dell'ormai famoso DTD Qwertz. In altri termini, è una derivazione di SGMLtools/LinuxDoc, riorganizzato in modo da gestire solo quello che può essere rappresentato in tutte le forme di composizione che sono state pianificate.

Sotto questo aspetto, DebianDoc è superiore a LinuxDoc quando l'obiettivo è la documentazione compatibile con lo spettro che va da una composizione in PostScript alla pagina di manuale pura e semplice.

Come si può intuire, DebianDoc è un applicativo nato per la distribuzione GNU/Linux Debian. Tuttavia, con un po' di prudenza, può essere convertito e installato anche in sistemi basati su altre distribuzioni. Eventualmente, si dovrà fare attenzione alle dipendenze: DebianDoc richiede la presenza di una serie di pacchetti che la distribuzione Debian organizza in funzione della gestione degli strumenti SGML. Un particolare interessante di DebianDoc è il fatto che utilizza Lout per la composizione in PostScript ed eventualmente anche PSUtils per generare dei libretti di dimensioni più comode rispetto al solito A4.

253.1 Struttura

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

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

253.1.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:

debiandoc2latex2e produce un file LaTeX;
debiandoc2dvi produce un file DVI attraverso l'elaborazione con il sistema di composizione LaTeX;
debiandoc2dvips produce un file PostScript attraverso l'elaborazione con il sistema di composizione LaTeX;
debiandoc2html produce una trasformazione in HTML, distribuita su più file, collocati in una directory il cui nome corrisponde alla radice del file sorgente, e l'estensione .html;
debiandoc2texinfo produce un file in formato Texinfo;
debiandoc2info produce un file di documentazione Info, attraverso il sistema di composizione Texinfo;
debiandoc2lout produce un file adatto per il sistema di composizione Lout;
debiandoc2ps produce un file PostScript, attraverso l'elaborazione del sistema di composizione Lout, in cui le pagine sono ridotte e raddoppiate (ogni pagina A4 ne contiene due A5, a meno che venga utilizzata l'opzione -1);
debiandoc2text produce un file di testo puro e semplice, con un'ampiezza di 79 colonne;
debiandoc2textov produce un file di testo con i codici di arretramento per ottenere gli effetti di evidenziamento e sottolineatura per la visualizzazione su schermo.

Alcune opzioni

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

253.2 Guida rapida

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 253.1. 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 253.2. 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 253.3. 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 253.4. 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 253.5. 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.

253.3 Riferimenti

Ian Jackson, Arno van Rangelrooij, Debiandoc-SGML Markup Manual

Dovrebbe essere possibile fare riferimento a questa pagina anche con il nome debiandoc.html