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


129. Introduzione a Texinfo

Texinfo è un sistema di composizione ideato per la documentazione di GNU, allo scopo di permettere la produzione di documenti ipertestuali in formato Info e di documenti stampati, attraverso il sistema di composizione TeX, a partire da un sorgente unico. Attualmente è disponibile anche la possibilità di comporre in HTML, cosa che completa il sistema Texinfo e lo rende uno strumento essenziale, ma anche molto valido.

A seconda di come è organizzata la propria distribuzione GNU/Linux, gli script che compongono il sistema Texinfo potrebbero far parte di un pacchetto indipendente, oppure essere inseriti direttamente all'interno della distribuzione teTeX (LaTeX).

Emacs permette di gestire in modo automatico molte particolarità del sorgente Texinfo, facilitando così il lavoro dell'utilizzatore. In questo capitolo si vuole mostrare solo l'essenziale di Texinfo, pertanto, tutta la parte che riguarderebbe la gestione di Emacs viene ignorata. Questo e altri particolari possono essere approfonditi nella documentazione originale di Texinfo.

129.1 Esempio introduttivo

Di solito, il modo migliore per cominciare a comprendere il funzionamento di un sistema di composizione, è quello di partire da un esempio, per avere modo di vedere subito come comporlo in pratica.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename esempio.info
@settitle Introduzione a Texinfo
@c %**end of header

@setchapternewpage odd

@ifinfo
Questo è un esempio molto breve di un documento scritto
utilizzando il sistema Texinfo.

Copyright @copyright{} 1999 Tizio Tizi
@end ifinfo

@titlepage
@sp 10
@comment Per il titolo viene utilizzato un corpo molto grande.
@center @titlefont{Titolo di esempio}

@c I due comandi seguenti iniziano la pagina del copyright.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1999 Tizio Tizi
@end titlepage

@node    Top, Suddivisione del documento, , (dir)
@comment nodo-attuale, nodo-successivo, nodo-precedente, nodo-superiore

@menu
* Suddivisione del documento::      Il primo capitolo di questo esempio
				    molto breve.
* Paragrafi::                       Il secondo capitolo.
* Indice analitico::                L'indice analitico.
@end menu

@node    Suddivisione del documento, Paragrafi, Top, Top
@comment nodo-attuale, nodo-successivo, nodo-precedente, nodo-superiore
@chapter Suddivisione del documento con Texinfo
@cindex suddivisione
@cindex capitolo
@cindex sezione
@cindex sottosezione

Un documento scritto in Texinfo è organizzato in capitoli, che possono
essere suddivisi in sezioni, sottosezioni e sotto-sottosezioni:

@enumerate
@item
capitolo -- @code{@@chapter};
@item
sezione -- @code{@@section};
@item
sottosezione -- @code{@@subsection};
@item
sotto-sottosezione -- @code{@@subsubsection};
@end enumerate

@node    Paragrafi, Indice analitico, Suddivisione del documento, Top
@comment nodo-attuale, nodo-successivo, nodo-precedente, nodo-superiore
@chapter Paragrafi in un sorgente Texinfo
@cindex paragrafo
@cindex testo

Il testo normale di un documento scritto in Texinfo è suddiviso in
paragrafi senza l'indicazione esplicita di alcun comando speciale.
Di conseguenza, basta inserire una riga vuota nel sorgente, per
produrre la separazione tra un paragrafo e il successivo.

@node    Indice analitico, , Paragrafi, Top
@comment nodo-attuale, nodo-successivo, nodo-precedente, nodo-superiore
@unnumbered Indice analitico

@printindex cp

@contents
@bye

Si suppone di avere nominato il file di questo sorgente `esempio.texinfo'. Di seguito vengono mostrati i comandi necessari alla composizione per generare un file Info, un file PostScript e un risultato in HTML.

makeinfo esempio.texinfo

texi2dvi esempio.texinfo ; dvips -t a4 -o esempio.ps esempio.dvi

texi2html esempio.texinfo

Nel primo caso viene generato il file Info `esempio.info'; nel secondo si ottiene prima il file `esempio.dvi', quindi, con l'aiuto di `dvips' si ottiene il file `esempio.ps'; nel terzo caso si ottiene il file `esempio.html', affiancato da `esempio_toc.html', che contiene l'indice generale.

129.2 Logica fondamentale di Texinfo

Texinfo è TeX a cui è stato applicato uno stile speciale, per cui il simbolo `@' sostituisce la barra obliqua inversa (`\'). Questo si ottiene attraverso l'inclusione di uno stile contenuto nel file `texinfo.tex', che viene incluso opportunamente con il comando TeX iniziale:

\input texinfo

Da quel punto in poi, la barra obliqua inversa ha valore letterale. Sempre allo scopo di ridurre al minimo i simboli che hanno significati speciali, i commenti si indicano attraverso un comando apposito: `@c', oppure `@comment'. A questo proposito, si può osservare che la prima riga mostrata nell'esempio introduttivo, contiene proprio un commento, subito dopo la dichiarazione dell'inclusione dello stile per Texinfo:

\input texinfo    @c -*-texinfo-*-

Si tratta di una stringa convenzionale, che è bene utilizzare anche se non è strettamente necessaria alla composizione di un sorgente Texinfo, perché riguarda Emacs, e gli permette di identificare il file e di qualificarlo per quello che è.

Una volta chiarita la natura TeX di un sorgente Texinfo, si può comprendere il comportamento generale del sistema, nel momento in cui la composizione viene fatta per arrivare alla stampa. In particolare, si può intendere il modo in cui vengono considerati gli spazi, che vengono eliminati quando sembrano superflui, e così si intende il motivo per cui basta separare i blocchi di testo con una o più righe vuote (o bianche), per ottenere la separazione in paragrafi. Tuttavia, le cose cambiano quando la composizione avviene in modo da generare un file Info: in questo caso gli spazi aggiuntivi contano, e anche le righe vuote superflue possono essere prese in considerazione.

Nonostante la sua natura TeX, Texinfo è vocato alla generazione di un ipertesto consultabile attraverso un terminale a caratteri, e su questo punto si fondano le sue caratteristiche e le limitazioni.

129.2.1 Scomposizione del documento

Un documento Texinfo è articolato in due modi distinti, che devono avvenire simultaneamente. Da una parte si trova l'articolazione del testo nel modo più adatto a un libro, con i suoi capitoli, e le sezioni a livelli diversi (come fa LaTeX), dall'altra parte c'è un ipertesto organizzato a grafo (un reticolo di collegamenti uniti assieme da dei nodi), dove i nodi sono i vari blocchi di informazioni.

Texinfo non pone limitazioni particolari all'uso dei nodi, tuttavia il buon senso richiede che siano usati in modo compatibile con la struttura «cartacea» del documento. In generale, ogni capitolo deve avere un nodo corrispondente, mentre le sezioni potrebbero averlo se ciò è opportuno, e lo stesso vale per le sottosezioni. Nell'esempio introduttivo, prima della dichiarazione del primo capitolo, si vede l'indicazione del nodo relativo:

@node    Suddivisione del documento, Paragrafi, Top, Top
@comment nodo-attuale, nodo-successivo, nodo-precedente, nodo-superiore
@chapter Suddivisione del documento con Texinfo

Dal momento che la composizione in formati finali diversi genera risultati differenti, c'è poi l'esigenza di poter distinguere il testo che deve essere usato per una o l'altra composizione. Per questo si possono circoscrivere delle porzioni di testo tra i comandi `@ifinfo' `@end info', `@iftex' `@end tex', e `@ifhtml' `@end html'. Nell'esempio introduttivo si vede proprio l'uso di questi comandi per inserire del testo che viene utilizzato solo nella composizione in formato Info:

@ifinfo
Questo è un esempio molto breve di un documento scritto
utilizzando il sistema Texinfo.

Copyright @copyright{} 1999 Tizio Tizi
@end ifinfo

129.2.2 Inserimento di simboli speciali

Il linguaggio di composizione utilizzato da Texinfo, attribuisce un significato speciale al simbolo `@', e alle parentesi graffe. Per indicare questi caratteri in modo letterale, basta farli precedere da un altro `@'. In questo senso, la sequenza `@<carattere>' rappresenta spesso la richiesta esplicita di fare riferimento al carattere in modo letterale. La tabella 129.1 elenca alcune di queste sequenze di escape.

Comando Descrizione
@@ Un solo simbolo `@'.
@{ Una parentesi graffa aperta.
@} Una parentesi graffa chiusa.
@<SP> Uno spazio non interrompibile.

Tabella 129.1: Comandi per rappresentare alcuni simboli speciali.

In modo simile si possono definire delle lettere speciali, se queste non sono disponibili attraverso la tastiera. La tabella 129.2 mostra i comandi utili per rappresentare le vocali accentate italiane.

Comando Risultato Comando Risultato
@`a à @`A À
@`e è @`E È
@'e é @'E É
@`i ì @`I Ì
@`o ò @`O Ò
@`u ù @`U Ù

Tabella 129.2: Comandi per la rappresentazione delle vocali accentate italiane.

129.3 Struttura di un documento Info

In un sorgente Texinfo, prima di arrivare alla scomposizione del testo in capitoli e nodi, c'è una parte iniziale che merita un po' di attenzione. La prima dichiarazione in assoluto è quella dell'inserimento dello stile `texinfo.tex', come è già stato mostrato, quindi si incontrano le dichiarazioni `@setfilename' e `@settitle' che costituiscono l'intestazione del sorgente:

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename esempio.info
@settitle Introduzione a Texinfo
@c %**end of header

La prima di queste due dichiarazioni serve a definire il nome del file Info finale, che in caso di necessità potrebbe anche essere scomposto in più file, e in tal caso quello che viene indicato sarebbe quello di partenza; la seconda dichiara il titolo del documento. Texinfo richiede che le dichiarazioni dell'intestazione siano racchiuse tra due commenti ben definiti, come si vede dall'esempio. È importante che siano riprodotti nello stesso modo che è stato mostrato:

@c %**start of header
...
@c %**end of header

La parte successiva all'intestazione, viene usata per utilizzare dei comandi specifici per la composizione TeX, come nel caso di `@setchapternewpage' che permette di definire se i capitoli debbano iniziare in una pagina nuova, e se questa debba essere una pagina dispari, oppure se ciò sia indifferente:

Dopo questo genere di definizioni, si passa generalmente alla presentazione formale del documento, annotando le informazioni legali, e nel caso particolare della composizione in TeX, specificando anche l'aspetto della prima pagina, quella del titolo. Nel caso di un documento Info non ha molta importanza la preparazione di una facciata introduttiva, e in effetti, questa non esiste (come si vedrà in seguito a proposito del nodo iniziale). In questo senso, non c'è nemmeno il posto per le informazioni sul copyright, che vengono comunque inserite, delimitandole tra i comandi `@iftex' e `@end tex', allo scopo che queste siano effettivamente annotate all'inizio nel file Info, anche se in una zona che poi non viene consultata attraverso la navigazione ipertestuale.

@ifinfo
Questo è un esempio molto breve di un documento scritto
utilizzando il sistema Texinfo.

Copyright @copyright{} 1999 Tizio Tizi
@end ifinfo

Alla fine di questa parte introduttiva del sorgente Texinfo, appare generalmente un blocco delimitato dai comandi `@titlepage' e `@end titlepage', che riguardano esclusivamente la composizione con TeX, e permette di definire la pagina iniziale del titolo, comprendendo anche le informazioni sul copyright.

@titlepage
@sp 10
@comment Per il titolo viene utilizzato un corpo molto grande.
@center @titlefont{Titolo di esempio}

@c I due comandi seguenti iniziano la pagina del copyright.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1999 Tizio Tizi
@end titlepage

I comandi che si vedono nell'esempio dovrebbero essere abbastanza intuitivi, dal momento che si tratta praticamente di TeX:

Il manuale di Texinfo propone anche un'altra forma, in cui si utilizzano i comandi `@title', `@subtitle' e `@author'. Il loro significato è intuitivo, e l'esempio seguente dovrebbe chiarirne l'uso: si osservi in particolare la presenza di due sottotitoli e di due autori.

@titlepage
@title Titolo di esempio
@subtitle Primo sottotitolo
@subtitle Secondo sottotitolo
@author Tizio Tizi
@author Caio Cai
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1999 Tizio Tizi, Caio Cai
@end titlepage

Nell'esempio introduttivo che è stato mostrato, non è stato circoscritto alcun pezzo riservato alla composizione in HTML. In effetti, `texi2html' ignora l'inizio del sorgente Texinfo, a parte l'intestazione, dalla quale ottiene il titolo del documento e il nome del file HTML principale che deve generare.

Al termine di un documento Texinfo, deve essere usato il comando `@bye' per concludere esplicitamente la composizione.

129.3.1 Capitoli e sezioni

Prima di affrontare il problema che riguarda la scomposizione del documento in nodi, vale la pena di vedere come avviene la scomposizione in capitoli e sezioni, dal momento che è qualcosa di più semplice, e si tratta di un concetto comune a molti altri sistemi di composizione. Semplificando le cose, si può affermare che un documento Texinfo è suddiviso in capitoli, che possono essere suddivisi a loro volta in sezioni, sottosezioni e sotto-sottosezioni. Tuttavia, esistono diversi tipi di «capitoli» e di «sezioni»; la tabella 129.3 riepiloga questi comandi.

Comando Descrizione
@chapter Capitolo normale con numerazione.
@section Sezione normale con numerazione.
@subsection Sottosezione normale con numerazione.
@subsubsection Sotto-sottosezione normale con numerazione.
@unnumbered Capitolo senza numerazione.
@unnumberedsec Sezione senza numerazione.
@unnumberedsubsec Sottosezione senza numerazione.
@unnumberedsubsubsec Sotto-sottosezione senza numerazione.
@appendix Capitolo numerato in modo letterale -- appendice.
@appendixsec Sezione di un'appendice.
@appendixsubsec Sottosezione di un'appendice.
@appendixsubsubsec Sotto-sottosezione di un'appendice.
@majorheading Titolo importante senza numerazione e senza salto pagina.
@chapterheading Capitolo senza numerazione e senza salto pagina.
@heading Sezione senza numerazione.
@subheading Sottosezione senza numerazione.
@subsubheading Sotto-sottosezione senza numerazione.

Tabella 129.3: Comandi per la suddivisione del testo in base al risultato stampato.

In particolare, la suddivisione che fa capo al capitolo di tipo `@unnumbered', riguarda generalmente gli indici, o le introduzioni, mentre la suddivisione `@...heading', permette di realizzare dei documenti in forma di relazione.

L'esempio introduttivo mostra in che modo si definisce l'inizio di un capitolo, utilizzando il comando `@chapter' seguito dal titolo, senza bisogno che questo sia delimitato in qualche modo. La stessa cosa varrebbe per le sezioni e per le altre classificazioni inferiori.

@chapter Suddivisione del documento con Texinfo

129.3.2 Nodi

I nodi di Texinfo sono le unità di informazioni raggiungibili attraverso una navigazione ipertestuale. A differenza della struttura di capitoli e sezioni, i nodi sono unità non divisibili, quindi non esistono dei sotto-nodi. Questo fatto crea una sovrapposizione imperfetta tra la struttura a nodi e la struttura di capitoli e sezioni.

Il nodo viene dichiarato attraverso il comando `@node', e la sua estensione va da quel punto fino alla dichiarazione del nodo successivo. Convenzionalmente, si dichiarano i nodi subito prima di un capitolo, o di una sezione (o anche di una sottosezione, ecc.); in questo modo, la struttura a nodi ha una qualche corrispondenza con la struttura cartacea del documento. A questo proposito, è importante stabilire l'estensione dei nodi: per cominciare potrebbe essere conveniente avere nodi contenenti un capitolo intero, e in questo caso si dichiarerebbero solo in corrispondenza di questi.

Ci sono dei pro e dei contro rispetto alla scelta di avere nodi grandi corrispondenti ai capitoli, o avere dei nodi più piccoli che arrivano al livello di sezione o anche a livelli inferiori. I nodi di Texinfo, oltre che essere i punti di arrivo dei riferimenti ipertestuali utilizzati nel documento Info, sono anche le «etichette» a cui puntano i riferimenti nel testo normale. In altri termini, se si decide per una struttura di nodi corrispondenti ai capitoli, senza altre suddivisioni, i riferimenti all'interno del testo possono essere fatti solo a livello di capitolo.

La struttura ipertestuale prevede un nodo di partenza obbligatorio, denominato `Top', all'interno del quale si trova normalmente un elenco di riferimenti, paragonabile a un indice generale, e una serie di altri nodi definiti dall'autore, con nomi liberi.

@node    Top, Suddivisione del documento, , (dir)

L'ipertesto Info, prevede l'aggregazione dei vari documenti scritti per questo sistema, attraverso un nodo precedente a quello `Top': si tratta del nodo `(dir)', corrispondente al file contenente l'indice iniziale di tutti i documenti Info installati effettivamente nel proprio sistema.

La dichiarazione di un nodo implica l'indicazione del suo nome, seguito da tre riferimenti ad altrettanti nodi: il nodo successivo, secondo un ordine ideale stabilito dall'autore, il nodo precedente, e il nodo superiore.

@node <nome-del-nodo>, <nodo-successivo>, <nodo-precedente>, <nodo-superiore>

In pratica, questa struttura prevede una sequenza di nodi, stabilita in qualche modo, e la presenza di un nodo di livello superiore. Il primo nodo in assoluto è `(dir)', mentre il primo nodo del documento è `Top'. Volendo utilizzare una struttura di nodi corrispondenti ai capitoli, senza suddivisioni ulteriori, si avrebbe una sola sequenza di nodi dal primo all'ultimo capitolo, e per tutti, il nodo superiore sarebbe `Top'; se invece si volesse realizzare una suddivisione maggiore, è ragionevole che i nodi contenuti in un capitolo formino una sequenza, e per questi il nodo superiore potrebbe essere quello iniziale del capitolo stesso.

Osservando la dichiarazione del nodo `Top' dell'esempio, si può vedere che il nodo precedente non è stato indicato, mentre il nodo superiore è `(dir)'. Infatti, non esiste un nodo precedente a `Top', mentre al di sopra di quello c'è solo l'indice generale, corrispondente al nome convenzionale `(dir)'.

Se non si hanno esigenze particolari nella definizione della sequenza dei nodi, si può lasciare fare a `makeinfo' (che è il programma che si occupa di generare la composizione in formato Info); quello che conta è indicare i nomi dei nodi, senza specificare i riferimenti. Per quanto riguarda i tipi di composizione differenti dal formato Info, non c'è il problema di definire una sequenza nei nodi. Perché `makeinfo' possa riuscire a creare da solo la sua sequenza di nodi, è necessario che questi siano dichiarati immediatamente prima di un capitolo, di una sezione, o di un altro tipo di suddivisione. È fondamentale però che non ci siano altre righe tra le due dichiarazioni. Dal momento che in questo modo il nodo `Top' verrebbe escluso, si può indicare sotto la sua dichiarazione, il comando `@top', che non serve ad altro che a questo: farsi riconoscere da `makeinfo'. L'esempio introduttivo, andrebbe modificato nel modo seguente, per fare in modo che possa essere gestito automaticamente da `makeinfo'. In particolare, vengono mostrate solo le parti significative:

    ...
@node Top
@top
    ...
@node    Suddivisione del documento
@chapter Suddivisione del documento con Texinfo
    ...
@node    Paragrafi
@chapter Paragrafi in un sorgente Texinfo
    ...
@node       Indice analitico
@unnumbered Indice analitico
    ...

La composizione in formato Info può generare automaticamente l'indice analitico, ma non l'indice generale. Per ottenere una sorta di indice generale, occorre indicare manualmente i riferimenti da qualche parte, di solito nel nodo `Top'. Nel caso dell'esempio introduttivo, sono stati indicati i riferimenti ai capitoli e all'indice analitico:

@menu
* Suddivisione del documento::      Il primo capitolo di questo esempio
				    molto breve.
* Paragrafi::                       Il secondo capitolo.
* Indice analitico::                L'indice analitico.
@end menu

Come si vede, tra i comandi `@menu' e `@end menu', sono stati indicati i nomi dei nodi da raggiungere, seguiti da una descrizione. Le voci di questi menù possono essere più articolate, ma in generale, se possibile, conviene mantenere questa forma elementare:

* <nome-nodo-da-raggiungere>:: <descrizione>

Chi scrive un documento in Texinfo, può anche fare a meno di preoccuparsi di questo menù iniziale, ma dovrebbe inserire almeno le voci che fanno riferimento ai nodi dell'indice analitico. Chi utilizza Emacs può anche ottenere la preparazione di questo menù in modo automatico; e per apprenderne il modo può consultare la documentazione originale su Texinfo.

129.4 Indici e riferimenti

Gli indici e i riferimenti di qualunque tipo siano, si ottengono attraverso l'indicazione di un'etichetta, da una parte, e dall'altra con l'utilizzo di un riferimento che punta all'etichetta. Gli indici in particolare, sono una raccolta di riferimenti, realizzata in modo automatico.

129.4.1 Indice generale e indici analitici

L'indice generale viene realizzato solo nella composizione che si avvale di TeX, e in quella per il formato HTML. Ciò avviene in modo automatico, indicando semplicemente il punto in cui questo deve apparire: l'inizio dei capitoli e delle classificazioni inferiori, sia di tipo numerato, sia di tipo non numerato, comprese le appendici, viene annotato nell'indice generale. Come accennato in precedenza, questo meccanismo non riguarda la composizione nel formato Info, per cui si utilizza un menù di riferimenti che fa le funzioni di indice generale.

Secondo la logica di Texinfo, l'indice generale va posto alla fine del documento, dopo gli indici analitici eventuali. Con il comando `@contents' si richiede la sua realizzazione in corrispondenza del comando stesso (che di solito precede solo il comando finale `@end'). È importante osservare che questo comando crea anche il titolo necessario, al contrario di ciò che avviene con l'indice analitico, come viene descritto nel seguito.

Per quanto riguarda l'indice analitico, per ottenerlo è necessario indicare nel testo delle etichette apposite, con le quali si ottiene l'inserimento delle voci relative. Questo viene fatto più o meno come avviene in altri sistemi di composizione, ma con Texinfo occorre tenere conto di alcune particolarità che derivano dalla sua specializzazione ipertestuale. Prima di tutto, si deve considerare che secondo la politica di Texinfo, le etichette riferite a voci da inserire nell'indice analitico devono essere uniche. In questo modo si semplificano una serie di problemi nella navigazione di un documento Info, che non può essere ambigua. A questo proposito, la documentazione originale di Texinfo suggerisce di utilizzare voci descrittive piuttosto dettagliate. Nel momento in cui si devono usare voci descrittive, si può porre anche il problema del modo in cui il lettore andrà a cercarle nell'indice, per cui, se ci sono più modi per indicare lo stesso concetto, è meglio inserire più etichette alternative per l'indice analitico. Texinfo è in grado di gestire diversi indici analitici specifici:

I primi due tipi di indici dovrebbero avere un significato evidente; per gli altri, si fa riferimento a ciò che riguarda i linguaggi di programmazione.

Si intuisce che non è tecnicamente necessario utilizzare tutti questi indici. In generale, ci si potrebbe limitare all'inserimento delle voci nell'indice analitico normale. Tuttavia, se si vuole realizzare un documento in Texinfo, seguendo le convenzioni, è bene fare uso dell'indice giusto per ogni cosa. Questo permette in seguito l'aggregazione con altri documenti che hanno seguito le stesse convenzioni.

La sintassi per la dichiarazione di una voce nei vari indici analitici di Texinfo, può essere fatta secondo uno degli schemi seguenti, che rappresentano nell'ordine i tipi di indice descritti sopra:

@cindex <voce-da-inserire-nell'indice-analitico-normale>

@kindex <voce-da-inserire-nell'indice-analitico-dei-comandi-da-tastiera>

@pindex <voce-da-inserire-nell'indice-analitico-dei-programmi>

@findex <voce-da-inserire-nell'indice-analitico-delle-funzioni>

@vindex <voce-da-inserire-nell'indice-analitico-delle-variabili>

@tindex <voce-da-inserire-nell'indice-analitico-dei-tipi-di-dati>

A ogni tipo di indice è abbinata una sigla, il cui utilizzo verrà descritto tra poco. La tabella 129.4 elenca queste sigle.

Sigla Indice
cp Indice analitico normale.
ky Indice analitico dei comandi da tastiera.
pg Indice analitico dei programmi.
fn Indice analitico delle funzioni.
vr Indice analitico delle variabili.
tp Indice analitico dei tipi di dati.

Tabella 129.4: Sigle dei vari tipi di indice analitico di Texinfo.

Nell'esempio introduttivo è stato mostrato l'uso del comando `@cindex' per inserire alcune voci nell'indice analitico normale:

@chapter Suddivisione del documento con Texinfo
@cindex suddivisione
@cindex capitolo
@cindex sezione
@cindex sottosezione

La voce che si inserisce nell'indice analitico, può essere anche composta da più parole, separate normalmente da uno spazio, senza bisogno di utilizzare dei delimitatori di alcun tipo: l'interpretazione corretta del comando è garantita dal fatto che questo deve stare da solo in una riga.

L'inserimento nel documento finale di un indice analitico, viene richiesto in modo esplicito, attraverso il comando `@printindex', seguito dalla sigla corrispondente all'indice desiderato. In generale, questo viene fatto all'interno di un capitolo non numerato, come è stato mostrato nell'esempio introduttivo, dove si vede la richiesta di creazione di un indice generale normale.

@unnumbered Indice analitico

@printindex cp

È il caso di segnalare che si possono fondere assieme più indici analitici specifici in modo da generare un solo indice analitico completo; inoltre si possono creare altri indici analitici specifici per scopi diversi da quelli previsti espressamente. Naturalmente, tutto questo può essere studiato nella documentazione originale.

129.4.2 Riferimenti incrociati

I riferimenti incrociati di Texinfo si basano sui nodi; in pratica, i nodi sono le etichette a cui puntano questi riferimenti. Si può avvertire questo fatto come una limitazione, tuttavia occorre ricordare che se si facesse diversamente, si porrebbero poi dei problemi nella composizione in formato Info. Texinfo prevede diversi tipi di riferimenti incrociati che vanno scelti accuratamente prima dell'uso (sono elencati brevemente nella tabella 129.5).

Comando Risultato
@xref «See...»
@ref Come `@xref', ma senza «See».
@pxref «see...»
@inforef Valido solo nella composizione Info.

Tabella 129.5: Comandi per i riferimenti incrociati.

Probabilmente, nella documentazione scritta in italiano, converrà l'utilizzo del solo comando `@ref'. La sua sintassi è molto articolata; si osservi in particolare che le parentesi graffe vanno considerate in modo letterale:

@ref{<nodo>, <titolo-per-info>, <titolo-o-argomento>, <nome-file-info>, <titolo-del-manuale-stampato>}

Gli argomenti finali che non servono, possono essere omessi, senza nemmeno indicare le virgole di separazione; se si vuole omettere qualche elemento centrale, lo si lascia vuoto, mantenendo la virgola che ne segna il posto. In condizioni normali, si utilizza solo il primo argomento, corrispondente al nome del nodo; in tutti gli altri casi, si ottiene un riferimento molto descrittivo, più di quanto sia necessario di solito. L'esempio seguente mostra una variante del secondo capitolo dell'esempio introduttivo:

@node    Paragrafi
@chapter Paragrafi in un sorgente Texinfo
@cindex paragrafo
@cindex testo

Il testo normale di un documento scritto in Texinfo è suddiviso in
paragrafi senza l'indicazione esplicita di alcun comando speciale.
Di conseguenza, basta inserire una riga vuota nel sorgente, per
produrre la separazione tra un paragrafo e il successivo.

Ecco un riferimento normale al capitolo in corso: @ref{Paragrafi}.

Quello che si ottiene con la composizione nel formato Info è il testo seguente:

Paragrafi in un sorgente Texinfo
********************************

   Il testo normale di un documento scritto in Texinfo è suddiviso in
paragrafi senza l'indicazione esplicita di alcun comando speciale.  Di
conseguenza, basta inserire una riga vuota nel sorgente, per produrre
la separazione tra un paragrafo e il successivo.

   Ecco un riferimento normale al capitolo in corso: *Note Paragrafi::.

Mentre, nel caso di composizione attraverso TeX, la frase contenente il riferimento viene formata più o meno nel modo seguente:

   Ecco un riferimento normale al capitolo in corso: Chapter 2
[Paragrafi], page 5.

Questo esempio serve per capire che, purtroppo, vengono generate delle parole aggiuntive, e per tradurle occorrerebbe intervenire nello stile TeX di Texinfo.

129.5 Aspetto del testo e ambienti speciali

Texinfo prevede una serie di comandi per delimitare parti di testo riferite a oggetti particolari; nello stesso modo, ci sono altri comandi per definire delle forme di enfatizzazione, senza stabilire le caratteristiche di ciò che si indica. Le tabelle 129.6 e 129.7 elencano questi comandi, quando sono riferiti a parole e frasi inserite nel corpo normale.

Comando Descrizione
@code{<testo>} Esempio letterale di un pezzo di programma.
@kbd{<testo>} Digitazione dalla tastiera.
@key{<testo>} Nome convenzionale di un tasto.
@samp{<testo>} Esempio letterale di una sequenza di caratteri.
@var{<testo>} Variabile metasintattica.
@url{<testo>} Indirizzo URI.
@file{<testo>} Nome di un file.
@email{<testo>} Indirizzo di posta elettronica.
@dfn{<testo>} Una definizione introdotta per la prima volta.
@cite{<testo>} Riferimento bibliografico (titolo di un libro).

Tabella 129.6: Comandi per delimitare oggetti particolari nel testo.

Comando Descrizione
@emph{<testo>} Enfatizzazione normale.
@strong{<testo>} Enfatizzazione più evidente.
@sc{<testo>} Maiuscoletto.
@r{<testo>} Carattere tondo normale.

Tabella 129.7: Comandi per l'enfatizzazione generica.

La tabella 129.8 mostra l'elenco dei comandi riferiti ad ambienti particolari, usati per mostrare esempi, per le citazioni, e per altre forme di evidenziamento del testo. I comandi in questione hanno un'apertura e una chiusura; per esempio,

@quotation
Questa è una citazione.
@end quotation

delimita il testo di una citazione da mettere in evidenza.

Comando Descrizione
@quotation Testo citato.
@example Codice, comandi e simili.
@lisp Codice LISP.
@smallexample Come `@example', ma più piccolo.
@smalllisp Come `@lisp', ma più piccolo.
@display Testo illustrativo senza uno scopo specifico.
@format Testo illustrativo, rispettando le interruzioni di riga.

Tabella 129.8: Comandi per delimitare blocchi di testo con funzioni specifiche.

Anche se ciò non riguarda precisamente l'argomento di questa sezione, vale la pena di mostrare brevemente come si dichiara una nota a piè pagina:

@footnote{<testo>}

129.6 Elenchi e tabelle

Gli elenchi vengono realizzati in Texinfo, più o meno come avviene con altri linguaggi di composizione. Dal momento che si deve poter arrivare al formato Info, le tabelle che vengono gestite sono molto simili a degli elenchi, e in questo senso è corretto trattare i due argomenti assieme.

Per la descrizione di come si realizza una tabella secondo Texinfo, è necessario leggere la documentazione originale, e qui non viene mostrato alcun esempio a questo proposito.

129.6.1 Elenco puntato e numerato

L'elenco puntato viene delimitato dai comandi `@itemize' e `@end itemize'. Gli elementi dell'elenco vengono introdotti dal comando `@item'. Il simbolo usato per segnalare l'inizio dei vari elementi dell'elenco, viene dichiarato esplicitamente, attraverso i comandi `@bullet' o `@minus', che si riferiscono rispettivamente a un pallino (o un asterisco), e a un trattino. L'esempio seguente mostra un elenco con due voci principali, dove la prima si scompone in altre due voci inferiori; le voci principali sono introdotte da un pallino, mentre quelle inferiori sono evidenziate da un trattino.

@itemize @bullet
@item
primo elemento principale;

@itemize @minus
@item
primo sottoelemento;

@item
secondo sottoelemento;
@end itemize

@item
secondo elemento principale.
@end itemize

Gli spazi tra le voci sono opportuni, per ottenere un buon risultato nella composizione in formato Info, mentre per la composizione attraverso TeX, la cosa è indifferente.

L'elenco numerato è simile a quello puntato, e si distingue solo perché è racchiuso tra i comandi `@enumerate' e `@end enumerate'. In particolare, in questo caso, al posto di definire il tipo di pallino da utilizzare, è possibile specificare il primo valore da utilizzare nell'elenco: se si tratta di un numero, quello sarà il primo valore di un elenco numerato vero e proprio; se si tratta di una lettera, si tratta di un elenco numerato in modo letterale, a partire da quella lettera. L'esempio seguente mostra un elenco numerato che parte dal numero zero (quando di solito partirebbe da uno).

@enumerate 0
@item
primo elemento;

@item
secondo elemento;

@item
terzo elemento.
@end enumerate

129.6.2 Elenco descrittivo

L'elenco descrittivo è quello che per ogni punto mostra una parola, o una frase, e quindi vi associa una descrizione. Per Texinfo, gli elenchi descrittivi sono delle tabelle a due colonne. L'ambiente viene delimitato dai comandi `@table' e `@end table', dove in particolare, il primo riceve un argomento che specifica il tipo di formattazione da dare alla prima colonna di questa specie di tabella. Per esempio,

@table @file
@item /etc/passwd
il file degli utenti;

@item /etc/group
il file dei gruppi.
@end @table

fa in modo che «/etc/passwd» e «/etc/group» vengano delimitati automaticamente con il comando `@file', mentre il resto, cioè la loro descrizione, viene lasciata con il carattere normale del testo.

129.7 Modifica dello stile TeX

Lo stile standard predisposto per la composizione attraverso TeX richiede una modifica per la produzione di documentazione in italiano. Infatti, se non si interviene, si ottiene l'inserimento di parole come «chapter», «section», «table of contents», ecc.

In generale, non è il caso di modificare il file che rappresenta lo stile standard, dal momento che è sufficiente farsene una copia da tenere assieme al sorgente Texinfo: quando si procede alla composizione, il file di stile `texinfo.tex' che si trova nella directory corrente, ha la precedenza.

Nell'estratto seguente vengono mostrate le righe utili che possono essere modificate per ottenere una traduzione dei termini che vengono inseriti automaticamente:

% Definizioni in italiano.
\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendice}\fi
\ifx\putwordChapter\undefined  \gdef\putwordChapter{Capitolo}\fi
\ifx\putwordfile\undefined     \gdef\putwordfile{file}\fi
\ifx\putwordInfo\undefined     \gdef\putwordInfo{Info}\fi
\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi
\ifx\putwordon\undefined       \gdef\putwordon{on}\fi
\ifx\putwordpage\undefined     \gdef\putwordpage{pagina}\fi
\ifx\putwordsection\undefined  \gdef\putwordsection{sezione}\fi
\ifx\putwordSection\undefined  \gdef\putwordSection{Sezione}\fi
\ifx\putwordsee\undefined      \gdef\putwordsee{vedere}\fi
\ifx\putwordSee\undefined      \gdef\putwordSee{Vedere}\fi
\ifx\putwordShortContents\undefined  \gdef\putwordShortContents{Indice breve}\fi
\ifx\putwordTableofContents\undefined\gdef\putwordTableofContents{Indice generale}\fi

129.8 Riferimenti

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

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


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