[inizio] [indice generale] [precedente] [successivo] [indice analitico] [contributi]


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

135.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', 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.

135.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/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'.

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

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

135.2 Guida rapida

Dal momento che DebianDoc è molto simile a LinuxDoc, e dato 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.

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 135.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 135.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 135.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 135.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 135.5: Elenchi.

135.3 Riferimenti

---------------------------

Appunti Linux 2000.04.12 --- Copyright © 1997-2000 Daniele Giacomini --  daniele @ pluto.linux.it


[inizio] [indice generale] [precedente] [successivo] [indice analitico] [contributi]