successivo precedente inizio fine indice generale aiuto indice analitico volume parte TXT HTML PDF pdf gdoc P₄

Riferimenti, note e altre informazioni

Alml ha una gestione abbastanza ricca delle informazioni che si ricollegano attraverso riferimenti incrociati. La caratteristica fondamentale di Alml è di far sì che tutto ciò che è fruibile in forma elettronica, rimanga accessibile anche in forma stampata su carta. Per esempio, non è prevista la possibilità di annotare un riferimento ipertestuale a una risorsa di cui non si possa vedere l'indirizzo nella forma stampata.

Riferimenti incrociati e ipertestuali

I riferimenti incrociati si realizzano attraverso l'indicazione di ancore (o etichette se si preferisce il termine) e di puntatori a tali ancore. Esistono diversi modi per definire un'ancora e un riferimento a questa: tutti gli elementi che dispongono di un attributo id, sono ancore oppure sono puntatori alle ancore.

Gli elementi usati per delimitare i titoli dei volumi, delle parti, dei capitoli, delle sezioni e dei riquadri (figure, tabelle, ecc.), sono ancore a cui si può puntare, ma per inserire un'ancora nel testo normale, è possibile usare l'elemento vuoto anchor, anche questo provvisto di attributo id. Tuttavia, l'elemento anchor è speciale, perché provvisto anche dell'attributo type, con cui è possibile stabilire se si voglia un'ancora invisibile oppure visibile. L'esempio seguente inserisce un'ancora visibile, mentre se si omette l'attributo type, l'ancora è invisibile in modo predefinito:

<p>Bla bla bla, questa <anchor id="oggetto" type="visible">pentola
è fatto di alluminio, bla bla bla...</p>

Un'ancora ^{a}visibile è qualcosa che viene mostrato in modo evidente nella composizione stampata; il suo scopo è quello di poter fare dei riferimenti a posizioni esatte nel testo. Per esempio, la parola «visibile» di questo paragrafo si trova nella posizione u0.1:a. Se l'ancora non fosse visibile, il riferimento che si otterrebbe riguarderebbe soltanto la sezione in cui questa è contenuta.

Esistono due elementi vuoti per fare riferimento alle ancore: sectionref, per ottenere un riferimento alla sezione in cui si trova l'ancora e objectref per fare riferimento a un riquadro. In particolare, l'elemento objectref può essere usato anche senza l'attributo id per fare riferimento all'ultima ancora di un riquadro, per semplificare la scrittura delle didascalie.

Quando si realizza un documento che può includere o meno una certa porzione a cui puntano alcuni riferimenti, per evitare che vengano mostrati questi collegamenti mancanti, si può usare l'elemento ifref, con il quale si delimita la parte da non comporre se manca il riferimento indicato nell'attributo id. D'altro canto, per ottenere l'effetto opposto, di mostrare qualcosa solo se manca un riferimento, si può usare l'elemento ifnotref.

Tabella u97.2. Elementi utili nella gestione dei riferimenti incrociati.

Elemento	Descrizione
tomeheading [id="`ancora`"] [lang="..."] [bookmark="..."]	Titolo del volume. L'attributo `id` consente di specificare un'ancora di riferimento.
h0 [id="`ancora`"] [lang="..."] [bookmark="..."]	Titolo della parte. L'attributo `id` consente di specificare un'ancora di riferimento.
h1 [id="`ancora`"] [lang="..."] [bookmark="..."]	Titolo del capitolo. L'attributo `id` consente di specificare un'ancora di riferimento.
h2 [id="..."] [bookmark="..."]	Titolo della sezione. L'attributo `id` consente di specificare un'ancora di riferimento.
h3 [id="`ancora`"] [bookmark="..."]	Titolo della sottosezione. L'attributo `id` consente di specificare un'ancora di riferimento.
h4 [id="`ancora`"] [bookmark="..."]	Titolo della sotto-sottosezione. L'attributo `id` consente di specificare un'ancora di riferimento.
object [id="`ancora`"] [pos="fixed\|float"] [sep="none\|rule\|border"] [split="0\|1"] [printedfontsize="`dimensione`"]	Involucro di un riquadro. L'attributo `id` consente di mette un'ancora di riferimento.
anchor id="`ancora`" [type="hidden\|visible"]	Elemento vuoto per l'inserimento di un'ancora in un contesto lineare. L'attributo `id` consente di specificare l'ancora di riferimento. L'attributo `type` consente rendere visibile l'ancora; il valore `invisible` è predefinito.
sectionref id="`riferimento`"	Elemento vuoto per l'inserimento di un riferimento a un'ancora, individuata dal valore assegnato all'attributo `id`. Il riferimento individua il numero di una sezione, indicando generalmente il capitolo e, se presenti, le suddivisioni inferiori, oppure la parte, oppure il volume, se il contesto è esterno al capitolo.
objectref id="`riferimento`"	Elemento vuoto per l'inserimento di un riferimento a un'ancora di un elemento `object`, individuata dal valore assegnato all'attributo `id`.
ifref id="`riferimento`"	Si tratta di un elemento che può essere inserito in un contesto lineare o tra i blocchi e può contenere sia un testo lineare, sia dei blocchi. Il contenuto dell'elemento viene reso nella composizione tipografica solo se l'ancora indicata con l'attributo `id` esiste.
ifnotref id="`riferimento`"	Si tratta di un elemento che può essere inserito in un contesto lineare o tra i blocchi e può contenere sia un testo lineare, sia dei blocchi. Il contenuto dell'elemento viene reso nella composizione tipografica solo se l'ancora indicata con l'attributo `id` non esiste.

Note e piè pagina

Alml prevede l'utilizzo di due tipi di annotazioni: avvertimenti che devono risaltare in un riquadro e note a piè pagina. Le note evidenziate sono indicate all'interno di un elemento frame, mentre quelle a piè pagina sono inserite nell'elemento footnote. Le note a piè pagina vengono inserite nell'elemento footnote, che si colloca all'interno delle righe; al contrario, l'elemento frame è un blocco che contiene blocchi.

<frame>
    <p>Attenzione! Si tratta di un'operazione rischiosa.</p>
</frame>

L'esempio precedente mostra l'utilizzo di un riquadro, mentre quello successivo mostra l'uso di un piè pagina.

<p>Bla bla bla<footnote>Questa parola si ripete.</footnote> bla bla...</p>

Tabella u97.5. Annotazioni a vario titolo.

Elemento	Descrizione
frame	Riquadro di avvertimento.
footnote	Nota a piè pagina.

Purtroppo, nella composizione stampata, le tabelle che si possono disporre su più pagine interferiscono con le note a piè di pagina. Si tratta di un difetto di LaTeX (precisamente del pacchetto longtable). Per risolvere il problema, si è reso necessario raggruppare le note alla fine dei capitoli.

Riferimenti esterni e citazioni

Alcuni elementi sono specializzati per fare riferimento a qualcosa di esterno. Il caso più comune riguarda l'elemento uri, con il quale si indica un indirizzo ipertestuale esterno al documento:

<p>Bla bla bla <uri><![CDATA[http://www.brot.dg]]></uri> bla bla...</p>

Per indicare il riferimento a una pagina di manuale, si può usare l'elemento man, in modo da ottenere una rappresentazione uguale a quella tradizionale, ma ciò non comporta alcun richiamo automatico alla visualizzazione di tale pagina di manuale:

<p>Bla bla bla <man>ls<mansect>1</mansect></man> bla bla...</p>

Figura u97.8. Sintassi per l'uso dell'elemento man.

man
 |--nome
 `--mansect
      `--n_sezione

La tabella u97.9 riepiloga questi e altri elementi affini.

Tabella u97.9. Riferimenti esterni.

Elemento	Descrizione
uri	Si tratta di un elemento che si inserisce in un contesto letterale e contiene il riferimento a un URI esterno, da indicare all'interno di una sezione marcata di tipo CDATA.
uristr	Si utilizza come l'elemento `uri`, con la differenza che il contenuto non viene inserito in una sezione marcata e non si crea alcun riferimento ipertestuale.
blockquote	Si tratta di un blocco che contiene una citazione, contenuta in altri blocchi. Alla fine, prima delle conclusione dell'elemento, può apparire l'elemento `quoteinfo`.
quoteinfo	So tratta di un blocco contenente componenti lineari, che serve a fornire informazioni sulla citazione.
bibref	Si inserisce in un contesto lineare e contiene componenti lineari. Precisamente si usa per delimitare il titolo di un documento.
man	Si inserisce in un contesto lineare e contiene componenti lineari, oltre che l'elemento `mansect`. Si usa indicare il nome di una pagina di manuale.
mansect	Si inserisce all'interno dell'elemento `man` e contiene un numero, che rappresenta il numero di una sezione della pagina di manuale.

L'elemento uristr è una variante di uri, con lo scopo di non generare un riferimento ipertestuale. Ciò può servire per rappresentare un indirizzo di fantasia, oppure un indirizzo reale che non è più valido. Si possono indicare in questo modo anche i nomi a dominio.

L'elemento blockquote è previsto per delimitare una citazione in uno o più blocchi. Alla fine dell'elemento blockquote è prevista la possibilità di usare un solo elemento quoteinfo, con lo scopo di contenere informazioni relative alla citazione:

<blockquote>
    blocchi
    ...
    [<quoteinfo>componenti_lineari...</quoteinfo>]
</blockquote>

Figura u97.10. Sintassi per l'uso dell'elemento blockquote.

blockquote
 |--blocco...
 `--[<quoteinfo>]
      `--componenti_lineari...

Indici analitici e termini speciali

Diversi tipi di elementi nella struttura di Alml sono predisposti per accumulare informazioni da restituire a richiesta. La situazione più semplice è data dalla gestione degli indici analitici, dove con l'elemento indexentry si inserisce una voce nell'indice analitico generale o in un altro individuato da un nome libero:

<h1>
I colori dell'arcobaleno
<indexentry>arcobaleno</indexentry>
<indexentry><code>color</code></indexentry>
</h1>

L'elemento indexentry appartiene al gruppo di quelli che possono essere inseriti all'interno di una riga; nell'esempio si vede la situazione tipica in cui lo si inserisce nel testo di un titolo. In questo caso, sono state indicate due voci dell'indice analitico generale: la parola «arcobaleno» viene inserita in modo normale, mentre la parola «color» viene inserita con un carattere dattilografico.

Ogni indice analitico ha un nome e quello generale, o predefinito, corrisponde a main. L'esempio mostrato sopra sarebbe perfettamente equivalente a quello seguente:

<h1>
I colori dell'arcobaleno
<indexentry index="main">arcobaleno</indexentry>
<indexentry index="main"><code>color</code></indexentry>
</h1>

Per recuperare l'elenco di un indice analitico si utilizza l'elemento printindex, in cui, lo stesso attributo index permette di stabilire quale indice estrapolare.

Figura u97.13. Sintassi per l'uso dell'elemento indexentry.

indexentry [index="nome_indice"]
  `--{testo|code|asciicode|kbd|vkbd|kp|strdfn}...

Tabella u97.14. Gestione degli indici analitici.

Elemento	Descrizione
indexentry [index="`nome_indice`"]	Dichiara una voce per l'indice analitico. L'attributo `index` consente di inserire la voce in un indice analitico particolare; se si omette, si fa riferimento all'indice `main`.
special special="`nome_indice`"	Delimita un termine speciale, che per qualche ragione si vuole seguire e controllare in un indice analitico specializzato. L'attributo `special` serve a specificare in quale indice analitico inserire la voce.
printindex [index="`nome_indice`"] [indexcontext="all\|tome\|part\ \`\|chapter"] [indexref="default\|section"]`	Si tratta di un elemento vuoto, da usare tra i blocchi, per inserire l'indice analitico accumulato alla voce specificata con l'attributo `index`. Se si omette l'attributo `index`, si fa riferimento all'indice `main`. L'attributo `indexcontext` specifica il contesto a cui si deve riferire l'indice analitico; è predefinito il contesto `all`, che richiede l'indice completo. L'attributo `indexref` serve a specificare in che modo devono apparire i riferimenti alle voci dell'indice; con la parola chiave `section`, si richiede espressamente che il riferimento sia solo al numero della sezione.

Esiste anche un altro elemento che inserisce voci negli indici analitici; si tratta di special, che inserisce una voce nell'indice corrispondente al nome indicato con l'attributo che ha lo stesso nome: special.

La differenza tra special e indexentry sta nella destinazione, in quanto il primo dovrebbe servire per tracciare l'uso di certi termini e, attraverso l'indice analitico relativo, verificare l'utilizzo uniforme degli stessi. Da un punto di vista puramente operativo, l'elemento special si distingue da indexentry perché mostra nella composizione finale il termine che contiene, mentre indexentry lo nasconde.

Esempio di indice analitico

Viene proposto qui un esempio completo di accumulo di voci in un indice analitico e di riproduzione dell'indice stesso. Vengono usati in particolare tutti gli elementi che possono essere inseriti nelle voci dell'indice, in modo da poterne osservare l'effetto nella riproduzione delle stesse. Si osservi che le voci vengono accumulate nell'indice predefinito main.

<p>Alcuni segnali possono essere inviati al programma con il quale si interagisce attraverso delle
combinazioni di tasti. Di solito si invia un segnale
<indexentry><code>SIGINT</code></indexentry><samp>SIGINT</samp> attraverso il carattere
<indexentry><asciicode>^c</asciicode></indexentry><asciicode>^c</asciicode>, ovvero
<indexentry><asciicode>ETX</asciicode></indexentry><asciicode>ETX</asciicode>, che si ottiene con
la combinazione virtuale <indexentry><vkbd>Control_c</vkbd></indexentry><vkbd>Control_c</vkbd>, a
cui spesso, fortunatamente, corrisponde la combinazione reale
<indexentry><kbd>Ctrl c</kbd></indexentry><kbd>Ctrl c</kbd>.</p>

<p>I pulsanti grafici <button>Next</button> e <button>Prev</button> permettono di passare alla
modalità grafica successiva (quella che si otterrebbe con la combinazione <indexentry>X:
<kbd>Ctrl Alt <kp>+</kp></kbd></indexentry><kbd>Ctrl Alt <kp>+</kp></kbd>) e
precedente (<indexentry>X:
<kbd>Ctrl Alt <kp>-</kp></kbd></indexentry><kbd>Ctrl Alt <kp>-</kp></kbd>).</p>

<printindex>

Nel riquadro successivo si vede come può risultare l'esempio nella composizione finale; si osservi che, nella composizione per la stampa, i riferimenti alle pagine potrebbero risultare sfasati, nel caso il riquadro dovesse passare nella pagina successiva:

Alcuni segnali possono essere inviati al programma con il quale si interagisce attraverso delle combinazioni di tasti. Di solito si invia un segnale SIGINT attraverso il carattere <^c>, ovvero <ETX>, che si ottiene con la combinazione virtuale <Control_c>, a cui spesso, fortunatamente, corrisponde la combinazione reale [Ctrl c].

I pulsanti grafici <Next> e <Prev> permettono di passare alla modalità grafica successiva (quella che si otterrebbe con la combinazione [Ctrl Alt ⁺]) e precedente ([Ctrl Alt ^-]).

<Control_c> i97.4.1
[Ctrl c] i97.4.1
<ETX> i97.4.1
SIGINT i97.4.1
X: [Ctrl Alt ⁺] i97.4.1
X: [Ctrl Alt ^-] i97.4.1
<^c> i97.4.1

Esempio di indice di termini speciali

Viene proposto un esempio completo per l'utilizzo di special, allo scopo di tenere traccia dell'uso di alcuni nomi.

<p>I formati più comuni per la stampa sono <special
special="nome-formato">DVI</special>, <special
special="nome-formato">PostScript</special>, <special
special="nome-formato">PDF</special>. Tra questi, quello che si presta
alle rielaborazioni, per esempio per favorire la rilegatura, è il
formato <special special="nome-formato">PostScript</special>. Per la
consultazione di un documento in modo interattivo, i formati comuni sono
<special special="nome-formato">HTML</special>, <special
special="nome-formato">XHTML</special> e ancora <special
special="nome-formato">PDF</special>.</p>

<p>In questo documento abbiamo parlato di:</p>

<printindex index="nome-formato">

Nel riquadro successivo si vede come può risultare l'esempio nella composizione finale; si osservi che, nella composizione per la stampa, i riferimenti alle pagine potrebbero risultare sfasati, a causa del passaggio del riquadro a una pagina successiva:

I formati più comuni per la stampa sono DVI, PostScript, PDF. Tra questi, quello che si presta alle rielaborazioni, per esempio per favorire la rilegatura, è il formato PostScript. Per la consultazione di un documento in modo interattivo, i formati comuni sono HTML, XHTML e ancora PDF.

In questo documento abbiamo parlato di:

DVI i97.4.2
HTML i97.4.2
PDF i97.4.2 i97.4.2
PostScript i97.4.2 i97.4.2
XHTML i97.4.2

Caratteristiche del software e di altri «lavori»

La struttura di Alml dispone di un elemento speciale che si può inserire nel testo lineare, il cui scopo è quello di annotare alcune informazioni sul software e su lavori simili. Si osservi l'esempio seguente:

<p>Stiamo parlando di Mpage,<workinfo>
<workname>Mpage</workname>
<worklicense>licenza speciale che non ammette le modifiche</worklicense>
<worklicensetext>

    <p>Permission is granted to anyone to make or distribute verbatim
    copies of this document as received, in any medium, provided that
    this copyright notice is preserved, and that the distributor grants
    the recipient permission for further redistribution as permitted by
    this notice.</p>

</worklicensetext>
</workinfo> un programma che si occupa di...</p>

Nel riquadro successivo si può vedere cosa succede nella composizione finale:

Stiamo parlando di Mpage,⁽¹⁾ un programma che si occupa di...

Solo gli elementi workname e worklicense sono obbligatori, dal momento che il loro contenuto appare in un piè pagina locale. L'elemento worklicensetext è facoltativo e può essere utile per annotare una licenza unica, per la quale non possa essere individuato un riferimento standard; inoltre, un altro elemento, worknotes, permette di annotare qualcosa al riguardo.

Figura u97.21. Sintassi per l'uso dell'elemento workinfo.

workinfo
  |--workname
  |    `--testo
  |--worklicense
  |    `--testo
  |--[worklicensetext]
  |    `--blocco...
  `--[worknotes]
       `--blocco...

Dove lo si ritiene più opportuno, si può collocare l'elemento printworkinfo, per ottenere l'elenco ordinato di queste informazioni accumulate.

Tabella u97.22. Tracciamento di informazioni sul software citato.

Elemento	Descrizione
workinfo	Contenitore delle informazioni, da inserire in un contesto lineare.
workname	Contiene il nome del software o di altro lavoro.
worklicense	Contiene la denominazione o la descrizione breve della licenza.
worklicensetext	Si usa per riportare il testo della licenza, organizzato in blocchi.
worknotes	Si usa per riportare delle annotazioni, organizzato in blocchi.
printworkinfo [workinforef="default\|section"]	Inserisce le informazioni accumulate in modo ordinato. L'attributo `workinforef`, se riceve il valore `section`, fa sì che i riferimenti ai lavori vengano fatti sempre solo utilizzando i numeri di sezione.

Nel riquadro successivo appare ciò che si potrebbe vedere nella composizione finale, quando si inserisce l'elemento printworkinfo:

Mpage, u0.5: Permission is granted to anyone to make or distribute verbatim copies of this document as received, in any medium, provided that this copyright notice is preserved, and that the distributor grants the recipient permission for further redistribution as permitted by this notice.

Informazioni su sezioni specifiche del documento

In situazioni particolari, potrebbe essere necessario, o anche solo utile, tenere traccia dell'origine di una sezione del documento, assieme a delle annotazioni a vario titolo. Per questo si può utilizzare l'elemento docinfo, che costituisce un blocco, contenente blocchi. Si osservi l'esempio seguente:

<docinfo docinfo="modifiche">
    <dl>
    <dt>2002.09.15</dt>
    <dd>
        <p>Il testo viene aggiornato nel contenuto, con l'inserimento
        della sezione «bla bla bla», da parte di Caio Cai
        (caio@brot.dg).</p>
    </dd>
    <dt>2002.09.08</dt>
    <dd>
        <p>Il testo viene modificato per adeguarlo alla nuova veste
        grafica dell'opera, per opera di Caio Cai (caio@brot.dg);
        il contenuto rimane invariato.</p>
    </dd>
    <dt>2002.02.02</dt>
    <dd>
        <p>Il testo originale è di Tizio Tizi e risale al 2002.02.02.
        Nello stesso giorno, il testo ha subito qualche aggiustamento
        per opera di Caio Cai (caio@brot.dg), con il consenso
        dell'autore.</p>
    </dd>
    </dl>
</docinfo>

L'esempio mostra in particolare l'uso dell'elemento docinfo per annotare lo storico delle modifiche fatte su quella porzione di documento; come si può vedere, vengono indicate prima le azioni più recenti, ma questo dipende solo da una scelta organizzativa.

Per ottenere l'elenco delle informazioni accumulate in questo modo, si utilizza l'elemento vuoto printdocinfo. Per inserire l'elenco dell'esempio precedente, va usato così:

...
<printdocinfo docinfo="modifiche">
...

Nel riquadro seguente si vede ciò che potrebbe apparire nella composizione finale:

sezione u0.6, Informazioni su sezioni specifiche del documento

2002.09.15

Il testo viene aggiornato nel contenuto, con l'inserimento della sezione «bla bla bla», da parte di Caio Cai (caio@brot.dg).

2002.09.08

Il testo viene modificato per adeguarlo alla nuova veste grafica dell'opera, per opera di Caio Cai (caio@brot.dg); il contenuto rimane invariato.

2002.02.02

Il testo originale è di Tizio Tizi e risale al 2002.02.02. Nello stesso giorno, il testo ha subito qualche aggiustamento per opera di Caio Cai (caio@brot.dg), con il consenso dell'autore.

Tabella u97.27. Tracciamento di informazioni su sezioni particolari del documento globale.

Elemento	Descrizione
docinfo [docinfo="`nome_gruppo`"]	Blocco contenente blocchi per l'annotazione di qualcosa sul documento. L'attributo `docinfo` consente di stabilire un raggruppamento a cui appartiene l'informazione accumulata; se non viene fornito, il valore predefinito per l'attributo è `default`.
printdocinfo [docinfo="`nome_gruppo`"]	Elemento vuoto che si inserisce tra i blocchi, per ottenere l'elenco delle annotazioni associate al nome che si assegna all'attributo `docinfo`. Se l'attributo non viene fornito, il valore predefinito per l'attributo è `default`.

Sezioni particolari

È disponibile l'elemento vuoto sectiongroup per inserire il numero della sezione in cui si trova in un elenco particolare, che successivamente può essere ottenuto con l'elemento vuoto printsectiongroup. Nell'esempio successivo, viene annotato che la sezione appartiene al gruppo non-modificabile:

...
<sectiongroup group="non-modificabile">
...

Nell'esempio successivo, si vuole ottenere l'elenco di tutte le sezioni associate al gruppo non-modificabile:

...
<p>Segue l'elenco delle sezioni dell'opera che non possono
essere modificate, per vari motivi:<p>
<printsectiongroup group="non-modificabile">
...

Nel riquadro successivo, si vede ciò che potrebbe apparire nell'elenco:

Segue l'elenco delle sezioni dell'opera che non possono essere modificate, per vari motivi:

Tabella u97.31. Sezioni particolari.

Elemento	Descrizione
sectiongroup [group="`gruppo`"]	Dichiara che la sezione appartiene al gruppo indicato nell'attributo. Se manca l'attributo, si intende che il gruppo in questione sia denominato `nomod`.
printsectiongroup [group="`gruppo`"]	Inserisce l'elenco delle sezioni che appartengono al gruppo indicato nell'attributo. Se manca l'attributo, si intende che il gruppo in questione sia denominato `nomod`.

1) Mpage licenza speciale che non ammette le modifiche