[>a2182.html>] [<a2180.html<] [^a2.html^]

Capitolo 141.   Sgmltexi: struttura

Sgmltexi impone uno schema preciso al documento, in base alle consuetudini dei documenti stampati. Questo capitolo descrive brevemente tale struttura.

141.1   Struttura generale per un sorgente Sgmltexi

Il sorgente Sgmltexi tipico inizia così:

<!DOCTYPE Sgmltexi PUBLIC "-//GNU//DTD Sgmltexi//EN">

Naturalmente, potrebbe essere conveniente la definizione iniziale di alcune entità interne, come si vede nell'esempio seguente:

<!DOCTYPE Sgmltexi PUBLIC "-//GNU//DTD Sgmltexi//EN">
[
<!ENTITY EDITION   "2000.05.20">
...
...
]>

Tutto il documento viene racchiuso all'interno dell'elemento sgmltexi, rispettando una certa struttura: deve esserci un elemento head, ci può essere un elemento intro, ci deve essere un elemento body, infine ci può essere un elemento appendix. Lo spazio successivo all'elemento appendix può essere occupato da alcuni indici analitici (cosa che verrà descritta meglio in seguito).

<sgmltexi>
<head>
...
</head>
<intro>
...
</intro>
<body>
...
</body>
<appendix>
...
</appendix>
</sgmltexi>

In particolare, si può definire il linguaggio del documento attraverso l'attributo lang dell'elemento sgmltexi. Si tratta di assegnare una sigla corrispondente allo standard ISO 639 (appendice B), come si vede nell'esempio seguente:

<sgmltexi lang="it">

141.1.1   Intestazione

L'elemento head è il più complicato. È necessario per definire molte informazioni che riguardano il documento. Segue un esempio abbastanza completo, che si riferisce alla documentazione ipotetica dello stesso Sgmltexi.

<head>
    <admin>
        <setfilename content="sgmltexi.info">
        <settitle content="Sgmltexi">
        <setchapternewpage content="odd">
        <defindex name="sg">
        <syncodeindex from="sg" to="cp">
        <infodir cat="Texinfo documentation system">
    </admin>
    <titlepage>
        <title>Sgmltexi</title>
        <subtitle>An alternative way to write Texinfo
        documentation</subtitle>
        <subtitle>This edition is for Sgmltexi
        &EDITION; (alpha) for Texinfo 4.0</subtitle>
        <abstract>
            <p>Sgmltexi is an SGML system (DTD and tools) to
            make Texinfo documentation using SGML...</p>
            ...
        </abstract>
        <author>Daniele Giacomini &lt;daniele@pluto.linux.it&gt;</author>
        <legal>
            <copyright>Copyright &copy; 2000 Free Software
            Foundation, Inc.</copyright>
            <publishnote>
                <p>Published by...</p>
            </publishnote>
            <license>
                <p>Permission is granted to make and distribute
                verbatim copies of this manual...</p>
                ...
            </license>
            <coverart>
                <p>Cover art by ...</p>
            </coverart>
        </legal>
    </titlepage>
    <shortcontents>
    <contents>
</head>

Guardando l'esempio, si possono riconoscere alcuni elementi importanti: admin, usato per alcune informazioni amministrative, e titlepage.

141.1.1.1   Informazioni amministrative

L'elemento admin viene usato per indicare al suo interno alcune informazioni che vanno prevalentemente nell'intestazione del documento Texinfo finale, oppure subito dopo. I componenti di questo ambiente non hanno un ordine preciso, nel sorgente SGML, in quanto poi vengono riordinati prima della composizione in Texinfo.

Nel seguito vengono elencati e descritti gli elementi che possono apparire all'interno di admin.

141.1.1.2   Pagine iniziali

L'elemento titlepage viene utilizzato per circoscrivere le informazioni che appaiono nelle primissime pagine del documento. L'ordine degli elementi contenuti è importante e gli errori vengono segnalati dal sistema di analisi SGML.

141.1.1.3   Indice generale

Dopo l'elemento titlepage è possibile collocare uno o più indici generali, più o meno dettagliati.

141.1.1.4   Nodo e menù Info iniziale

In mancanza di indicazioni, Sgmltexi gestisce da solo i collegamenti riferiti al nodo Top, oltre a un menù unico per Info, collocato nello stesso nodo iniziale.

Volendo è possibile dichiarare espressamente il nodo Top, attraverso l'elemento topnode, che si usa vuoto con tre eventuali attributi: next, previous e up. L'elemento topnode si colloca, eventualmente, subito dopo gli indici generali.

<topnode next="intro" prev="Top" up="(dir)">

Dopo l'elemento topnode, è possibile specificare il menù iniziale in modo dettagliato, attraverso l'elemento menu. L'esempio seguente mostra un caso abbastanza articolato, anche se abbreviato, in cui si vede anche l'inclusione dell'elemento detailmenu:

<menu>
* Copying::                     Your rights.
* Overview::                    Texinfo in brief.
...
* Structuring::                 How to create chapters, sections, subsections,
                                  appendices, and other parts.
* Nodes::                       How to write nodes.
...

<detailmenu>

 --- The Detailed Node Listing ---

Overview of Texinfo

* Reporting Bugs::              Submitting effective bug reports.
* Using Texinfo::               Create printed or online output.
* Info Files::                  What is an Info file?
...
</detailmenu>
</menu>

Naturalmente, non si tratta di elementi indispensabili, ma solo utili se si desidera avere il controllo della gestione dei nodi del documento che si ottiene.

141.1.2   Introduzione

Dopo l'elemento head ci può essere l'elemento intro, il cui scopo è quello di definire uno spazio in cui i capitoli assumono il ruolo di sezioni introduttive, non numerate. Nell'ambito di questo spazio, i «capitoli» sono delimitati nello stesso modo utilizzato nel corpo del documento (l'elemento body) e nelle appendici (l'elemento appendix).

<intro>
<h1>Introduction to Sgmltexi</h1>

<p>Sgmltexi is a DTD with tools to get Texinfo...</p>

<p>Sgmltexi manage Texinfo nodes automatically,...</p>

</intro>

141.1.3   Corpo

Il corpo del documento è contenuto nell'elemento body, che si colloca dopo l'elemento head e dopo l'elemento intro eventuale.

Il corpo può essere suddiviso in capitoli, oppure in parti, o anche in tomi, a seconda della dimensione del progetto di documentazione che si intende avviare. Lo spazio del tomo, della parte, del capitolo, o di una classificazione inferiore, non è delimitato esplicitamente, in quanto appare soltanto la dichiarazione del titolo, all'interno di un elemento che cambia a seconda del livello gerarchico. In pratica, il titolo di un tomo è racchiuso nell'elemento tomeheading, mentre quello di una parte è inserito nell'elemento partheading.

I capitoli e le classificazioni inferiori hanno titoli delimitati da elementi analoghi a quelli dell'HTML: h1, h2, h3 e h4. Questa classificazione, a partire da h1 in giù, riguarda nello stesso modo l'introduzione e l'appendice.

<body>
<partheader>Networking</partheader>

<h1>IP protocol history</h1>

<p>Bla bla bla...</p>

<p>Bla bla bla...</p>

<h2>ISO/OSI model</h2>

<p>Bla bla bla...</p>

<p>Bla bla bla...</p>

<h1>IPv4 and IPv6</h1>

<p>Bla bla bla...</p>

<p>...</p>

</body>

Ogni elemento che racchiude un titolo consente l'inserimento dell'attributo id, il cui scopo è quello di definire una stringa di identificazione, da usare come obiettivo per i riferimenti incrociati.

<h1 id="ip history">IP protocol history</h1>

È importante rammentare che, a causa di una limitazione progettuale di Texinfo, queste etichette per i riferimenti ipertestuali non possono contenere la virgola.

Ogni elemento che racchiude un titolo consente l'inserimento degli attributi node e menu, con i quali è possibile stabilire il nome del nodo relativo e la descrizione che deve apparire nel menù (purché questo sia generato automaticamente). In mancanza di queste indicazioni, vengono generati dei nomi in modo automatico, mentre si usa il titolo come descrizione del nodo.

<h1 node="IPv4" menu="La storia del protocollo IP">Storia di IPv4</h1>

Ogni elemento che racchiude un titolo consente l'inserimento dell'attributo numbered, a cui si possono assegnare esclusivamente le parole chiave on oppure off. In condizioni normali, l'attributo contiene la parola chiave on, che implica la numerazione dei titoli, salvo il caso dell'introduzione. Assegnando esplicitamente la parola chiave off si ottiene un titolo non numerato in un contesto che non lo prevederebbe.

<h1 numbered="off">Riconoscimenti</h1>

141.1.4   Appendice

Dopo il corpo del documento, delimitato dall'elemento body, può apparire l'appendice, contenuta nell'elemento appendix. Al suo interno si possono inserire dei «capitoli», introdotti da un titolo contenuto in un elemento h1, che vengono trattati correttamente come appendici. Dopo i titoli delimitati da h1, sono ammissibili naturalmente anche segmenti di livello inferiore.

<appendix>
<h1>GNU Free Documentation License</h1>

<p indent="off"><strong>GNU Free Documentation License</strong></p>

<p indent="off">Version 1.1, March 2000</p>

<format>
Copyright &copy; 2000  Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
</format>
...
...
</appendix>

141.1.5   Indici analitici

Dopo il corpo e dopo il blocco delle appendici, è possibile inserire uno o più indici analitici. Questi si dichiarano con un titolo, attraverso l'elemento indexheading e con il riferimento al tipo di indice che si vuole esattamente, con l'elemento vuoto printindex. Si osservi l'esempio seguente in cui si inseriscono due indici: quello delle funzioni (la sigla fn) e quello standard (la sigla cp).

<indexheading>Index of functions</indexheading>
<printindex name="fn">
<indexheading>Concept index</indexheading>
<printindex name="cp">

Come si vede dall'esempio, l'elemento printindex ha l'attributo name, a cui si assegna la sigla corrispondente all'indice che si vuole inserire.

141.2   Scomposizione del documento, nodi e menù Info

Per scrivere della documentazione di qualità, secondo i canoni di Texinfo, è necessario gestire direttamente i nodi e i menù. Con Sgmltexi si possono dimenticare i nodi e i menù, ma il risultato in formato Info potrebbe soffrirne. Tuttavia, come in parte è già stato mostrato, è possibile scegliere diversi livelli di automatismo in questa gestione.

Gli elementi usati per delimitare le intestazioni, da h1 a h4, possono incorporare gli attributi node e menu. Ciò prende il sopravvento sulla determinazione automatica relativa. Si osservi l'esempio:

<h1 id="ip history" node="history" menu="History of IP protocol">
IP protocol history</h1>

In questo caso, si ottiene l'inserimento della riga seguente nel menù relativo:

* history::         History of IP protocol

I due attributi, node e menu, possono essere usati in modo indipendente: l'attributo che non viene usato, viene sostituito in modo automatico.

Avendo accesso ai nodi, è possibile farvi riferimento per dei riferimenti incrociati, senza bisogno di usare l'attributo id.

Come già descritto in precedenza, Sgmltexi crea automaticamente il nodo Top iniziale. Il menù relativo può essere definito esplicitamente e in tal caso tutti i nodi e tutte le descrizioni relative devono essere inseriti manualmente.

Inserendo l'elemento menu alla fine del testo di un capitolo, o di una sezione inferiore, si ottiene l'aggiunta di un menù Info in corrispondenza di quel punto. Si osservi l'esempio:

<h1>IP protocol history</h1>

<p>Bla bla bla...</p>

<p>Bla bla bla...</p>

<menu>

<h2>ISO/OSI model</h2>

<p>Bla bla bla...</p>

<p>Bla bla bla...</p>

<h2>More information</h2>

<p>Bla bla bla...</p>

<p>...</p>

In questo caso, si ottiene l'inserzione di un menù, gestito automaticamente, prima delle sezioni di livello h2. Volendo, si può indicare il menù in modo preciso, come si vede di seguito:

<menu>
* IP layer::        IP ISO/OSI layer model
* more on IP::      More details on IP
</menu>

Quando un menù viene descritto in questo modo, i nomi dei nodi devono essere identici a quelli dichiarati negli elementi delle intestazioni. In pratica, scrivendo un menù in modo manuale, anche i nodi devono essere dichiarati esattamente, come si vede qui:

<h1>IP protocol history</h1>

<p>Bla bla bla...</p>

<p>Bla bla bla...</p>

<menu>
* IP layer::        IP ISO/OSI layer model
* more on IP::      More details on IP
</menu>

<h2 node="IP layer">ISO/OSI model</h2>

<p>Bla bla bla...</p>

<p>Bla bla bla...</p>

<h2 node="more on IP">More information</h2>

<p>Bla bla bla...</p>

<p>...</p>

È evidente, in questa situazione, che l'attributo menu, il cui scopo sarebbe quello di controllare la descrizione del nodo nel menù, non può essere preso in considerazione in questo caso.

141.2.1   Numerazione o meno dei titoli

Texinfo consente di inserire dei titoli riferiti a capitoli o sezioni inferiori, con o senza numerazione. Inoltre, consente anche di dichiarare dei titoli che non devono apparire nell'indice generale. Per controllare questa possibilità con Sgmltexi, si può utilizzare l'attributo type che riguarda tutti gli elementi hn:

<hn type="{numbered|unnumbered|heading}">titolo</hn>

In mancanza dell'indicazione dell'attributo, è come se gli fosse stata assegnata la parola chiave numbered, con la quale i titolo del corpo e delle appendici sono numerati (con numeri o leggere rispettivamente). Utilizzando la parola chiave numbered si ottiene l'inserimento di un titolo non numerato (nel caso dell'introduzione è sempre senza numerazione); con la parola chiave heading si ottiene un titolo non numerato e anche non segnalato nell'indice generale (in questo senso può essere utile anche nell'introduzione).

141.3   Gestire più derivazioni di uno stesso progetto di documentazione

Attraverso Sgmltexi è possibile gestire più derivazioni distinte di un progetto di documentazione unico. Per ottenere questo risultato, Prima di passare all'analisi SGML, il sorgente viene filtrato in base a dei comandi particolari che delimitano lo spazio di queste derivazioni. L'esempio seguente mostra i comandi che delimitano uno spazio relativo alla derivazione PIPPO:

<!-- START PIPPO -->
...
...
...
<!-- STOP PIPPO -->

Si può osservare che si tratta di un commento SGML speciale, che viene preso in considerazione da Sgmltexi prima dell'analisi SGML vera e propria.

Questi comandi devono apparire da soli in una riga; in pratica, non è ammissibile circoscrivere uno spazio interno a una riga in questo modo.

Il principio di funzionamento è molto semplice: vengono incluse le parti di sorgente delimitate in questo modo per la derivazione a cui si fa riferimento. Quindi, se si vuole un pezzo qui e uno lì, occorre ripetere l'inserimento di questi comandi.

La derivazione predefinita è quella denominata MAIN, per cui è come se, in mancanza di altre indicazioni contrarie, il sorgente fosse racchiuso tra <!-- START MAIN --> e <!-- STOP MAIN -->:

<!-- START MAIN -->
<!DOCTYPE Sgmltexi PUBLIC "-//GNU//DTD Sgmltexi//EN">
<sgmltexi>
...
...
...
</sgmltexi>
<!-- STOP MAIN -->

Naturalmente, nulla vieta di usare esplicitamente queste dichiarazioni per la derivazione principale.

Per selezionare la composizione di una derivazione diversa da quella principale (predefinita), si usa l'opzione --deriv=derivazione. Supponendo di voler eseguire la composizione in PostScript della derivazione PIPPO del file prova.sgml, basta usare il comando seguente:

$ sgmltexi --deriv=PIPPO --ps prova.sgml

Questa forma di selezione può essere gestita anche all'interno di file secondari. Sgmltexi è organizzato a questo proposito per gestire solo file interni al sistema, che nel sorgente principale vengono gestiti come nell'esempio seguente:

<!DOCTYPE Sgmltexi PUBLIC "-//GNU//DTD Sgmltexi//EN"
[
    -- ... --
<!ENTITY INTRO      SYSTEM "formalita/introduzione.sgml">
<!ENTITY COPY       SYSTEM "formalita/copyright.sgml">
    -- ... --
]>

Come si vede, si tratta di dichiarazioni che si fanno nel preambolo SGML. Sgmltexi deve identificarle preventivamente, per poter attuare il filtro anche in tali file. Per questo motivo, è necessario che non ci sia più di un'istruzione del genere su una sola riga.

È importante sottolineare che questi comandi speciali riguardano il file in cui si trovano. Pertanto, se ci si trova in una situazione simile a quella che si vede nell'esempio sottostante,

<!-- START PIPPO -->

&INTRO;

<!-- STOP PIPPO -->

i comandi indicano semplicemente di includere l'istruzione SGML &INTRO;. Se poi si vuole includere effettivamente tutto o anche solo parte del file corrispondente (formalita/introduzione.sgml), bisognerà che al suo interno ci siano altre istruzioni del genere; diversamente sarebbe come includere un file completamente vuoto.

Appunti di informatica libera 2000.07.31 --- Copyright © 2000 Daniele Giacomini --  daniele @ swlibero.org

[>a2182.html>] [<a2180.html<] [^a2.html^]