[successivo] [precedente] [inizio] [fine] [indice generale] [indice ridotto] [indice analitico] [volume] [parte]


Capitolo 514.   Texinfo: libro e ipertesto

Nel capitolo introduttivo è già stato affrontato il problema della gestione dei nodi in un documento Texinfo, ma alcuni aspetti sono stati solo sfiorati. Texinfo non può essere considerato pensando esclusivamente a uno dei risultati di composizione finale che possono essere generati, altrimenti si perde di vista la logica complessiva. In generale si sovrappongono due esigenze: il documento cartaceo da sfogliare e il documento elettronico da attraversare in modo ipertestuale.

Il documento cartaceo, ovvero il libro, ha una struttura ad albero che deriva dalla tradizione. Semplificando molto le cose si può rappresentare come nella figura 514.1, dove si vede che tutto viene suddiviso in capitoli, che possono eventualmente essere suddivisi ulteriormente in segmenti di livello inferiore (le sezioni).

Figura 514.1. Struttura ad albero di un libro.

libro

Un libro particolarmente corposo potrebbe anche raggruppare assieme i capitoli in parti; mentre un'opera potrebbe anche essere suddivisa in raggruppamenti ancora più grandi, che di solito corrispondono ai volumi, ovvero ai tomi.

La suddivisione ad albero mostrata nella figura, non basta a descrivere la struttura di un libro. Infatti, occorre considerare che i capitoli, se suddivisi in sezioni, non sono composti semplicemente dalla somma di queste sezioni, in quanto, prima di tali suddivisioni introducono il problema, che poi viene descritto in modo particolareggiato. In pratica, è come se ogni capitolo suddiviso in sezioni contenesse una sezione fantasma iniziale. Lo stesso ragionamento vale per le sezioni che si articolano in sottosezioni e così via con le classificazioni inferiori.

Lo stesso discorso può valere per la classificazione in parti e in tomi, anche se in questi casi, le informazioni che precedono i capitoli, o le parti, tendono a non avere la stessa valenza.

Il documento elettronico ipertestuale è composto da blocchi di informazioni che Texinfo definisce opportunamente come nodi. Generalmente questi nodi sono indivisibili, come avviene con Texinfo, ma tendono a essere raggruppati in sequenze ideali, oltre che prevedere la possibilità di saltare ad altri nodi (e quindi ad altre sequenze potenziali) attraverso riferimenti trasversali.

Figura 514.2. Sequenze di nodi e collegamenti trasversali.

sequenze

L'ipertesto puro è un documento in cui le informazioni sono raggiunte con un ordine che viene deciso durante la lettura, dove non c'è l'esigenza di leggere tutto e non ci si preoccupa se volontariamente o inavvertitamente si salta qualche nodo che compone l'ipertesto complessivo. In generale è proprio questo il problema: un ipertesto non dispone necessariamente di un percorso predefinito di lettura.

Nel momento in cui si intende realizzare un documento unico, simultaneamente libro e ipertesto, si deve giungere in qualche modo a un compromesso. Texinfo consente di realizzare un ipertesto estremamente complesso, oppure un libro tradizionale; se però si vogliono fare entrambe le cose, di solito conviene realizzare l'ipertesto secondo la struttura stessa del libro.

Texinfo propone una sequenza predefinita, che viene generata automaticamente quando i nodi vengono dichiarati subito prima delle suddivisioni tradizionali del documento (capitoli, sezioni, ecc.), senza specificare la sequenza a cui appartengono. In generale si formano delle sequenze gerarchiche di questi nodi, dove si può passare ai livelli inferiori solo attraverso dei salti aggiuntivi, come si vede nella figura 514.3.

Figura 514.3. Struttura dei nodi predefinita secondo Texinfo.

struttura dei nodi predefinita

I salti aggiuntivi che permettono di raggiungere una sequenza inferiore di nodi vengono raggruppati convenzionalmente in un menù finale di riferimenti.

514.1   Sequenza dei nodi secondo Texinfo

Secondo Texinfo, i nodi hanno tre riferimenti che servono a comporre le sequenze e a legare tali sequenze in una dipendenza gerarchica. Si tratta di:

Figura 514.4. Riferimenti standard che si diramano a partire da un nodo di Texinfo.

riferimenti standard

Il primo nodo di un documento Texinfo deve essere denominato Top, che corrisponde idealmente a tutto ciò che precede il contenuto vero e proprio di un libro (subito dopo la copertina fino alla prefazione esclusa).

Per riprodurre lo schema gerarchico predefinito a cui si accennava in precedenza, dove si distinguono delle sequenze di nodi distinte a livelli diversi, è necessario inserire alla fine del testo di questi nodi un menù di riferimenti ai nodi di una sequenza inferiore. In generale, il nodo Top prevede l'inserimento di un menù di riferimenti ai nodi della sequenza principale, corrispondente in pratica ai capitoli di un libro; se i capitoli si articolano in strutture inferiori, anche i nodi relativi devono disporre di un menù che faccia riferimento alle sezioni, continuando così fino all'ultimo livello che si deve raggiungere.

Tuttavia, resta il fatto che tutto questo non sia indispensabile, dal momento che le sequenze dei nodi potrebbero essere determinate in modo arbitrario, senza rispettare la struttura tipica di un libro; senza avere così la necessità di definire tutti questi menù.

È proprio questa idea legata alla presenza di sequenze di nodi separate gerarchicamente che impone la presenza dei menù e di conseguenza impone l'esistenza del nodo Top. A questo punto, è il caso di osservare che il nodo Top non può appartenere a una sequenza di altri nodi allo stesso suo livello; per questo, viene inserito normalmente nella stessa sequenza dei capitoli.

514.2   Definizione automatica della sequenza dei nodi e problemi relativi

Texinfo prevede una struttura predefinita dei nodi che lo compongono, compatibile con la struttura di un libro, nel modo che è già stato mostrato in precedenza (figura 514.3). Per raggiungere questo risultato, nel sorgente Texinfo si indicano i nodi specificando solo il nome (senza stabilire relazioni con il nodo precedente, quello successivo e quello superiore). Tuttavia, questo non basta, perché se dal nodo si deve articolare una sequenza inferiore gerarchicamente, è necessario predisporre anche il menù relativo. L'esempio seguente rappresenta un nodo corrispondente a un capitolo, estratto dallo stesso sorgente dalla documentazione di Texinfo:

@node Overview
@chapter Overview of Texinfo

@dfn{Texinfo} is a documentation system that uses a single source file
to produce both online information and printed output.  This means that
instead of writing two different documents, one for the online
information and the other for a printed work, you need write only one
document.  Therefore, when the work is revised, you need revise only
that one document.

@menu
* Reporting Bugs::                Submitting effective bug reports.
* Using Texinfo::                 Create printed or online output.
* Info Files::                    What is an Info file?
* Printed Books::                 Characteristics of a printed book or manual.
* Formatting Commands::           @@-commands are used for formatting.
* Conventions::                   General rules for writing a Texinfo file.
* Comments::                      Writing comments and ignored text in general.
* Minimum::                       What a Texinfo file must have.
* Six Parts::                     Usually, a Texinfo file has six parts.
* Short Sample::                  A short sample Texinfo file.
* Acknowledgements and History::  Contributors and genesis.
@end menu

Il capitolo si articola in diverse sezioni e tutte devono essere elencate nel menù che si vede. Questo fatto può essere sentito come una limitazione, che bene o male costringe l'autore a curarsi della realizzazione di questi riferimenti ipertestuali. Oltre a questo, è il caso di considerare il modo in cui si presenta il documento quando viene fatta la composizione in forma Info: quando si accede al nodo del capitolo, si vedono solo quelle poche righe iniziali, mentre per entrare nelle sezioni successive occorre passare per la selezione del menù.

Il problema della predisposizione di questi menù si può risolvere utilizzando Emacs, attraverso alcuni comandi specifici della modalità Texinfo. Tuttavia, questa non è la soluzione definitiva, dal momento che si costringe a utilizzare Emacs, mentre chi non vuole farlo resta costretto ad arrangiarsi a mano.

Il problema dei capitoli spezzati in nodi separati è più serio. In effetti la suddivisione fatta attraverso le sequenze gerarchiche di nodi è perfettamente logica; tuttavia, nel momento in cui ci si accinge a leggere un documento del genere, sarebbe forse più logico scorrere il capitolo verticalmente per raggiungere le sue classificazioni inferiori come se si trattasse di un'unica pagina. Purtroppo, il sistema Info non consente di avere dei sottonodi, ovvero dei riferimenti a posizioni intermedie di un nodo, come invece avviene con l'HTML. Per risolvere in pratica questa limitazione bisogna limitarsi ad attribuire i nodi ai capitoli, tenendo presente che in questo modo non è possibile indicare nel testo dei riferimenti diretti a classificazioni inferiori. Tuttavia, recentemente è stato introdotto il comando @anchor con cui si ottiene l'inserimento di un'etichetta raggiungibile come se si trattasse di un nodo, smussando così il problema dei nodi.

514.3   Limitazioni originali della struttura a nodi

Originariamente i nodi di Texinfo rappresentavano gli unici oggetti che potevano essere raggiunti attraverso riferimenti ipertestuali. In pratica, per fare riferimento a un capitolo o a una sezione, occorreva definire il nodo relativo per poi poter utilizzare comandi della serie @...ref.

È già stato visto che in generale conviene definire dei nodi in corrispondenza di tutti i capitoli, in modo da creare una sequenza definita a partire dal menù collocato nel nodo Top. Tuttavia, se c'è la necessità di fare riferimento a una sezione particolare di un certo capitolo, diventerebbe necessario dichiarare anche lì un nodo. Ma non basta definire un nodo in una sezione lasciando stare le altre sezioni, perché si creerebbe disordine nell'insieme; in pratica, se si definisce un nodo per una sezione di un certo capitolo, diventa indispensabile definire i nodi per le altre sezioni della stesso capitolo, avendo poi cura di predisporre il menù necessario.

A questo problema si è posto rimedio aggiungendo il comando @ancor{} che ha lo scopo di collocare un'ancora, ovvero un'etichetta raggiungibile attraverso riferimenti ipertestuali, senza dichiarare implicitamente l'inizio di un nodo in quella posizione.

@ancor{nome_ancora}

I nomi delle ancore appartengono allo stesso dominio dei nomi dei nodi, per cui non si devono creare dei conflitti nella scelta dei nomi. Inoltre, quando si fa riferimento a un'ancora, nella composizione Info si ottiene normalmente di raggiungere l'inizio del nodo in cui si trova.

Anche la gestione degli indici analitici è condizionata dalla struttura a nodi di Texinfo. In generale non è indispensabile che la voce da collocare in un indice analitico si trovi all'inizio di un nodo; quando però dall'indice analitico si vuole raggiungere il testo in cui questa è stata dichiarata, si arriva in realtà all'inizio del nodo in cui questa si trova. Se la voce si trova all'interno di una piccola sottosezione, mentre l'unico nodo disponibile è quello che fa capo al capitolo, si raggiunge l'inizio del capitolo. Naturalmente, questo vale per la navigazione di un documento che è stato composto in formato Info, mentre nelle altre forme di composizione il problema scompare o viene attenuato.

514.4   Riferimenti ipertestuali e limitazioni verbali

Texinfo nasce come un sistema di composizione per documentazione scritta in lingua inglese. Attualmente il lavoro attorno a Texinfo si rivolge anche verso le esigenze delle altre lingue, selezionabili attraverso il comando @documentlanguage, ma questo lavoro non è ancora completo nel momento in cui si scrivono queste note.

Texinfo dispone di quattro comandi diversi per i riferimenti ipertestuali, il cui scopo è quello di adattarsi alle esigenze del contesto. Ma in questo caso, il contesto è prevalentemente di tipo «verbale». Vale la pena di descrivere brevemente questi quattro comandi, mostrando le conseguenze pratiche del loro utilizzo. Qui non vengono mostrate tutte le varianti perché ciò richiederebbe un capitolo apposito, mentre la documentazione originale è molto chiara a questo proposito.(1)

Vengono considerati i comportamenti confrontando solo la composizione Info e quella stampata (DVI, PostScript e PDF), perché l'HTML non ha ancora una sistemazione definitiva.

Questi comandi ricevono più argomenti distinti in base all'uso di una virgola di separazione. Per questa ragione la virgola non può essere usata all'interno di un argomento. Si tratta evidentemente di una limitazione importante da tenere in considerazione.

@xref{nodo, titolo_per_info, titolo_o_argomento, file_info, titolo_del_documento_stampato}

Il comando @xref{} consente di ottenere dei riferimenti ipertestuali molto descrittivi. In generale è obbligatoria l'indicazione del nodo (il primo argomento), mentre il resto può essere omesso. Dopo l'indicazione del nodo, alcuni argomenti successivi riguardano esclusivamente la composizione Info, mentre gli altri solo la composizione stampata (e simili). Nella composizione Info viene indicato il nome del nodo; se fornito appare il titolo specifico per la composizione Info ed eventualmente anche il nome del file Info esterno in cui cercarlo. Nella composizione per la stampa si ha l'indicazione del titolo dell'argomento e se non viene fornita questa indicazione ci si limita a mostrare il nome del nodo stesso; se poi il riferimento è interno al documento viene aggiunta l'indicazione della pagina, altrimenti diventa necessario fornire il titolo del documento esterno che così appare al posto del numero della pagina.

L'uso più semplice di @xref{} è quello in cui si indica solo il nodo, come nell'esempio seguente:

Bla bla bla. @xref{Din don dan}. Bla bla bla...

Il risultato nell'ipertesto Info è:

Bla bla bla. *Note Din don dan::. Bla bla bla...

mentre con la composizione per la stampa l'aspetto è molto diverso:

Bla bla bla. See Chapter 3 [Din don dan], page 22. Bla bla bla...

Tanto per cominciare si può comprendere che si tratta di un riferimento che può essere collocato solo all'inizio di una frase (di un testo inglese), dal momento che la prima parola, See, ha l'iniziale maiuscola. Eventualmente non è detto che il riferimento debba concludersi con un punto fermo come avviene nell'esempio, ma la frase che continua è comunque condizionata dal modo in cui viene rappresentato tale riferimento.

@ref{nodo, titolo_per_info, titolo_o_argomento, file_info, titolo_del_documento_stampato}

Il comando @ref{} si comporta in modo analogo a @xref{} con la differenza che nella composizione per la stampa non viene generata la parola See iniziale. Ciò consente di collocare il riferimento alla fine di una frase, oppure, con l'accortezza necessaria, anche in mezzo.

@pxref{nodo, titolo_per_info, titolo_o_argomento, file_info, titolo_del_documento_stampato}

Il comando @pxref{} è il più strano per chi non scrive utilizzando la lingua inglese. La lettera «p» sta per «parentheses», cioè parentesi, quelle all'interno delle quali dovrebbe essere collocato. A differenza del comando @xref{}, la composizione per la stampa inizia con see (iniziale minuscola), mentre la composizione Info aggiunge un punto fermo.

@inforef{nodo, titolo, file_info}

Il comando @inforef{} serve a fare riferimento a un file Info esterno, per il quale non si vuole o non si può fare riferimento a un'analoga versione stampata. Mentre nella composizione Info il risultato è uguale a quanto è già stato visto per @xref{}, nella composizione stampata viene fatto esplicito riferimento a un file Info. Si può ottenere una cosa simile a quella seguente:

Bla bla bla. See Info file `miofile', node `Din don dan'. Bla bla bla...

Si intende che il riferimento sia fatto per essere collocato esattamente all'inizio di un periodo, dato il fatto che anche qui la parola See ha l'iniziale maiuscola.

Tabella 514.10. Comandi per i riferimenti incrociati.

Comando Descrizione o risultato
@anchor{etichetta}
Inserisce un ancora nel testo.
@xref
«See...»
@ref
Come @xref, ma senza «See».
@pxref
«see...»
@inforef
«See Info file...».

514.5   Altri tipi di riferimento

Texinfo dispone di altri tipi di riferimento che però risultano indolori dal punto di vista della lingua utilizzata per scrivere il proprio documento.

@uref{uri, descrizione, testo_sostitutivo_dell'indirizzo}

Il comando @uref{} consente di annotare un indirizzo URI secondo modalità differenti: se si indica solo il primo argomento, viene mostrato in ogni tipo di composizione; se appare anche il secondo argomento, vengono mostrate entrambe le cose, la descrizione e l'indirizzo, tranne nel caso della composizione HTML, in cui l'indirizzo non viene più mostrato; se si indica il terzo argomento (il secondo diventa superfluo), non si vuole mostrare l'indirizzo URI, mentre nella composizione HTML viene comunque attivato il riferimento. Si osservino gli esempi seguenti.

Bla bla bla @uref{http://www.dinkel.brot.dg/} bla bla bla...

Questo genera l'inserimento dell'indirizzo nel testo senza delimitazioni, in ogni tipo di composizione.

Bla bla bla @uref{http://www.dinkel.brot.dg/, Titolo} bla bla bla...

In questo modo, la composizione per la stampa e quella per Info generano un risultato del tipo:

Bla bla bla Titolo (http://www.dinkel.brot.dg/) bla bla bla...

Invece, nella composizione HTML l'indirizzo URI scompare dalla vista, nel modo seguente:

Bla bla bla <a href="http://www.dinkel.brot.dg/">Titolo</a> bla bla bla...

Infine, l'esempio seguente mostra l'uso del terzo argomento (si noti l'uso della coppia di virgole per segnalare l'assenza del secondo argomento):

Bla bla bla @uref{http://www.dinkel.brot.dg/,, Titolo} bla bla bla...

Nella composizione stampata e in quella Info si perde completamente l'informazione dell'indirizzo URI:

Bla bla bla Titolo bla bla bla...

Nella composizione HTML l'indirizzo URI rimane nascosto alla vista, come è già stato visto in precedenza:

Bla bla bla <a href="http://www.dinkel.brot.dg/">Titolo</a> bla bla bla...

A fianco di @uref{} si pone anche un comando specifico per l'annotazione di indirizzi di posta elettronica:

@email{indirizzo, descrizione}

Il comando @email{} si comporta in pratica come @uref{}, con la differenza che il terzo argomento non esiste, per cui si mostra sempre l'indirizzo, che eventualmente viene preceduto dalla sua descrizione. Nel caso della composizione in HTML, viene generato un riferimento ipertestuale del tipo mailto:.

Esiste un altro modo di indicare un riferimento a un indirizzo URI. Si tratta del comando @url{}, che serve solo a mostrare tale indirizzo, senza generare nel formato HTML alcun riferimento:

@url{uri}

L'indirizzo URI viene mostrato senza delimitazioni in ogni tipo di composizione. In generale può essere conveniente utilizzare questo comando al posto di uref{} quando si indica un indirizzo ipotetico o un indirizzo che non è più valido (al quale non sarebbe opportuno puntare con un riferimento ipertestuale).

514.6   Riepilogo dei comandi relativi a nodi, ancore e riferimenti

Appunti di informatica libera 2007.02 --- Copyright © 2000-2007 Daniele Giacomini -- <daniele (ad) swlibero·org>


1) È il caso di ricordare che le parentesi graffe fanno parte dei comandi di Texinfo.


Dovrebbe essere possibile fare riferimento a questa pagina anche con il nome texinfo_libro_e_ipertesto.htm

[successivo] [precedente] [inizio] [fine] [indice generale] [indice ridotto] [indice analitico]

Valid ISO-HTML!

CSS validator!