110. DebianDoc

<!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, e 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.

110.1.1 Organizzazione del catalogo, del DTD e delle entità

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/lib/sgml/catalog, che in pratica è un collegamento simbolico che punta al file /etc/sgml.catalog. Leggendo le dichiarazioni del catalogo si intende che il DTD DebianDoc sia costituito dal file dtd/debiandoc.dtd, ovvero /usr/lib/sgml/dtd/debiandoc.dtd, e che viene usato un solo file di entità generali: entities/general, ovvero /usr/lib/sgml/entities/general.

110.1.2 Utilizzo sommario

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 l'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 doppio trattino serve a separare le opzioni dal nome del file sorgente.

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 110.1: Elementi della struttura generale 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 110.2: Elementi che rappresentano la suddivisione gerarchica del contenuto di un documento DebianDoc.

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 110.3: Elementi che si utilizzano nel corpo del testo per modificare l'aspetto del loro contenuto in base al significato che rappresentano.

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 110.4: Riferimenti.

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.

Tabella 110.5: Elenchi.

110.3 Riferimenti

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