[successivo] [precedente] [inizio] [fine] [indice generale] [violazione GPL] [licenze] [indice analitico] [tomo] [parte]


Capitolo 170.   Il documento secondo Alml

Il DTD di Alml è organizzato per gestire documenti molto grandi, che possono essere suddivisi in tomi (intesi come volumi che raccolgono un gruppo di parti), parti e capitoli. Tuttavia, la suddivisione in tomi o in parti resta facoltativa, mentre la divisione in capitoli è obbligatoria.

Alml non ha ancora raggiunto una sistemazione «definitiva» e si evolverà ancora assieme a Appunti di informatica libera. In questo capitolo non sono descritti tutti i dettagli sull'impostazione attuale del DTD di Alml; eventualmente si può sempre studiare il DTD stesso. Tuttavia, il DTD non rappresenta in modo perfetto i vincoli che si pongono poi nella composizione.

170.1   Organizzazione generale

Secondo il DTD di Alml, il documento ha una struttura generale ben definita:

<!DOCTYPE ALML PUBLIC "-//D.G.//DTD Alml//EN">
<alml>
<head>
...
</head>
[<intro>
...
</intro>]
<body>
...
</body>
[<appendix>
...
</appendix>]
[<index>
...
</index>]
</alml>

In questa struttura, gli elementi head e body sono obbligatori, mentre gli altri possono essere omessi, se non sono richiesti.

Si può intuire il senso della cosa: l'elemento head serve a contenere informazioni amministrative, oltre a ciò che deve apparire nelle primissime pagine (il titolo dell'opera, il copyright ecc.); l'elemento intro permette di inserire dei capitoli speciali da trattare come introduzioni o prefazioni, che come tali non risultano numerate; l'elemento body permette di inserire capitoli, oppure parti, o tomi; l'elemento appendix permette di inserire capitoli da trattare come appendici, numerate convenzionalmente in modo letterale; infine, l'elemento index permette di inserire capitoli speciali per l'inclusione degli indici analitici.

170.2   Dalla copertina all'indice generale

L'elemento che delimita il documento nella sua interezza, alml, può contenere due attributi facoltativi: lang e spacing. L'attributo lang permette di definire il linguaggio generale con cui è stato scritto il documento, attraverso una sigla secondo lo standard ISO 639 (appendice C).(1)

L'attributo spacing permette di definire il modo in cui vengono gestiti gli spazi alla fine dei periodi. Assegnando la parola chiave normal, si ottiene la spaziatura normale della convenzione inglese, in cui lo spazio dopo un punto ha una lunghezza maggiore degli altri; in alternativa, assegnando la parola chiave uniform, oppure french, si ottiene una spaziatura uniforme, come richiede la tradizione tipografica italiana e anche di altri paesi.

In generale, un documento scritto in lingua italiana dovrebbe utilizzare l'elemento alml in questo modo:

<alml lang="it" spacing="uniform">
Elemento o attributo Apertura Chiusura Contenuto Descrizione
alml Contenitore del documento.
   lang -- -- Attributo Sigla ISO 639 del linguaggio.
   spacing -- -- Attributo normal, french e uniform.
head Intestazione del documento.
   admin Informazioni amministrative.
      description Descrizione in breve del documento.
      keywords Elenco di parole chiave.
      htmlmeta Contenuto di un elemento HTML META.
         name -- -- Attributo Equivalente all'HTML.
         lang -- -- Attributo Equivalente all'HTML.
         content -- -- Attributo Equivalente all'HTML.
      chapterdefinition Definizione alternativa del capitolo.
      partdefinition Definizione alternativa della parte.
      tomedefinition Definizione alternativa del tomo.
      printedfontsize Corpo del carattere in punti.
         type -- -- Attributo Definisce il contesto a cui si fa riferimento.
   title %inline; Titolo del documento.
   subtitle %inline; Sottotitolo.
   abstract %block; Descrizione del contenuto.
   author %inline; Autore.
   date #PCDATA Data.
   edition %inline; Edizione, se diversa dalla data.
   frontcoverpicture Vuoto Immagine di copertina.
      imgfile -- -- Attributo File dell'immagine senza estensione.
      height -- -- Attributo Altezza dell'immagine.
      width -- -- Attributo Larghezza dell'immagine.
   frontcovertext %block; Testo aggiuntivo di copertina.
   backcoverpicture Vuoto Immagine di copertina finale.
      imgfile -- -- Attributo File dell'immagine senza estensione.
      height -- -- Attributo Altezza dell'immagine.
      width -- -- Attributo Larghezza dell'immagine.
   backcovertext %block; Testo aggiuntivo della copertina finale.
   textbeforelegal %block; Testo prima delle informazioni legali.
   legal %block; Informazioni legali.
   dedications %block; Pagina della dedica.
   textafterdedications %block; Testo successivo alla dedica.
   maincontents Vuoto Inserimento dell'indice generale.
      levels -- -- Attributo Livelli di dettaglio dell'indice.
      nopages -- -- Attributo true, false.

Tabella 170.1. Elementi SGML dalla copertina all'indice generale.

La tabella 170.1 mostra in breve l'elenco degli elementi che riguardano l'intestazione del documento; cosa che contiene tutte le informazioni per realizzare la copertina, fino ad arrivare all'indice generale.

Si può osservare che tutto è contenuto nell'elemento head, all'inizio del quale prende posto un altro «contenitore» denominato admin. Al suo interno sono previsti elementi relativi a informazioni amministrative, in particolare description e keywords, il cui scopo è quello di generare degli elementi META corrispondenti nella composizione HTML:

<HEAD>
    ...
    <META NAME="Description" CONTENT="An example for Alml documentation system">
    <META NAME="Keywords" CONTENT="SGML, XML, HTML, Alml">
    ...
</HEAD>

Inoltre, si possono aggiungere anche altri elementi META di HTML, attraverso l'elemento HTMLMETA, come si vede nell'esempio seguente:

<head>
    <admin>
        <description>GNU/Linux e altro software libero</description>
                
        <keywords>Linux, GNU/Linux, Unix, software, software libero,
        free software</keywords>
    
        <htmlmeta name="Resource-type" lang="en">Document</htmlmeta>
        <htmlmeta name="Revisit-after" lang="en">15 days</htmlmeta>
        <htmlmeta name="Robots">ALL</htmlmeta>
    </admin>
    ...
    ...
</HEAD>

Gli elementi chapterdefinition, partdefinition e tomedefinition vengono descritti più avanti in questo capitolo (170.8).

L'elemento printedfontsize consente di definire l'altezza del carattere indicato attraverso l'attributo type, per la composizione stampata.

L'elemento title serve a indicare il titolo del documento; gli elementi eventuali subtitle permettono di inserire dei sottotitoli successivi.

L'elemento abstract, facoltativo, permette l'inserimento di una descrizione, più o meno articolata, composta da blocchi di testo (ciò che nella tabella viene rappresentato schematicamente dalla macro %block;).

Successivamente è possibile inserire uno o più elementi author, uno per il nominativo di ogni coautore, eventualmente.

Gli elementi date e edition servono per indicare una data o una sigla differente che rappresenti in qualche modo l'edizione. In generale dovrebbe essere sufficiente l'indicazione di uno solo di questi due elementi.

L'elemento frontcoverpicture permette l'inserzione di un'immagine da collocare sopra il titolo dell'opera. Data la circostanza, non è previsto l'inserimento di una didascalia, anche perché rimane la possibilità di inserire un'immagine differente nel blocco contenuto all'interno dell'elemento frontcovertext.

Nello spazio rimanente della copertina è possibile inserire altri blocchi di testo all'interno dell'elemento facoltativo frontcovertext.

L'elemento backcoverpicture permette l'inserzione di un'immagine da collocare all'inizio della copertina finale. Anche in questo caso non è previsto l'inserimento di una didascalia, dato che rimane la possibilità di inserire un'immagine differente nel blocco contenuto all'interno dell'elemento backcovertext. Con l'elemento backcovertext è possibile aggiungere dei blocchi di testo nella copertina finale.

Gli elementi successivi riguardano la seconda pagina assoluta e quelle successive.

Nella seconda pagina appaiono di solito le informazioni sul copyright, nella parte bassa, mentre nella parte superiore potrebbero esserci altre informazioni, come una breve descrizione degli autori. L'elemento textbeforelegal permette di inserire blocchi di testo da collocare nella prima parte della seconda pagina, mentre l'elemento legal è fatto per le informazioni legali, a partire dal copyright.

Dopo le informazioni legali è possibile inserire una pagina di dediche, attraverso l'elemento dedications. Eventualmente, se necessario, è possibile aggiungere altre notizie all'interno dell'elemento textafterdedications che segue le dediche.

Infine, è possibile collocare l'elemento vuoto maincontents per ottenere l'inserimento dell'indice generale. L'attributo levels permette di definire il livello di dettaglio desiderato dell'indice: il numero zero rappresenta il minimo e fa in modo di ottenere informazioni fino alle parti, mentre valori superiori aumentano il dettaglio. Assegnando all'attributo nopages il valore true, si richiedere espressamente l'eliminazione dei riferimenti ai numeri di pagina; cosa che può essere utile soltanto nella composizione per la stampa.

170.2.1   Carattere nella composizione stampata

È possibile definire la dimensione del carattere, nella composizione stampata, in alcune situazioni importanti, senza dover intervenire modificando lo stile TeX. Si utilizza per questo l'elemento printedfontsize, all'interno dell'elemento admin, nell'intestazione del documento, specificando il contesto con l'attributo type. Si osservi l'esempio:

<head>
    <admin>
        ...
        ...
        <printedfontsize type="normal">11</printedfontsize>
        <printedfontsize type="table">9</printedfontsize>
    </admin>
...
</head>

Il tipo normal è il carattere normale del testo; il tipo table è il carattere utilizzato nelle tabelle di Alml. La distanza tra le righe viene impostata automaticamente al 120 % della dimensione del carattere utilizzato.

La dimensione del carattere deve essere armoniosa rispetto al resto del documento. Bisogna provare per rendersi conto se il risultato che si ottiene è accettabile oppure no.

170.3   Contenuto

Il contenuto del documento si articola in tre blocchi fondamentali: intro, body e appendix. In coda, possono apparire degli indici analitici, racchiusi nel blocco dell'elemento index.

Questa classificazione in blocchi va a compensare la mancanza di elementi atti a circoscrivere l'estensione delle sezioni in cui si articola il testo. La mancanza di una strutturazione dettagliata delle sezioni(2) fa sì che in presenza di errori di sintassi SGML, l'analizzatore tenda a segnalare in seguito una quantità di errori inesistenti che non vanno considerati. In tali situazioni, si correggono i primi errori evidenti e si ripete la verifica SGML.

170.3.1   Introduzione

Dopo l'elemento head è prevista la possibilità di inserire l'elemento intro, il cui scopo è quello di delimitare uno o più capitoli speciali, da intendere come prefazioni o introduzioni a vario titolo.

Per la definizione del capitolo, si veda quanto descritto a proposito dell'elemento body.

170.3.2   Corpo

Il corpo vero e proprio del documento è contenuto nell'elemento body, il quale si può articolare in tomi, parti o capitoli. Sta all'autore scegliere quale livello di suddivisione superiore adottare. È evidente che se si usa una suddivisione in tomi, si prevede una sottoclassificazione in parti, che poi si dividono in capitoli; se si usa una suddivisione in parti, è obbligatoria una sottoclassificazione in capitoli.

Eccezionalmente, un tomo può contenere solo capitoli, senza parti, quando per qualche ragione ciò è necessario.

Tomi, parti, capitoli e sezioni inferiori sono delimitate materialmente attraverso la dichiarazione del titolo relativo, come avviene in HTML. La tabella 170.2 elenca gli elementi relativi, assieme agli attributi eventuali.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
tomeheading %inline; Titolo del tomo.
     id -- -- Attributo Ancora di riferimento.
     lang -- -- Attributo Linguaggio del tomo.
   tomecontents Vuoto Indice generale del tomo.
       levels -- -- Attributo Livello di dettaglio dell'indice.
       nopages -- -- Attributo true, false.
h0 %inline; Titolo della parte.
     id -- -- Attributo Ancora di riferimento.
     lang -- -- Attributo Linguaggio della parte.
   partcontents Vuoto Indice generale della parte.
       levels -- -- Attributo Livello di dettaglio dell'indice.
       nopages -- -- Attributo true, false.
h1 %inline; Titolo del capitolo.
     id -- -- Attributo Ancora di riferimento.
     lang -- -- Attributo Linguaggio del capitolo.
   chaptercontents Vuoto Indice generale del capitolo.
       levels -- -- Attributo Livello di dettaglio dell'indice.
       nopages -- -- Attributo true, false.
h2 %inline; Titolo della sezione.
   id -- -- Attributo Ancora di riferimento.
h3 %inline; Titolo della sottosezione.
   id -- -- Attributo Ancora di riferimento.
h4 %inline; Titolo della sotto-sottosezione.
   id -- -- Attributo Ancora di riferimento.
segment Segmento di testo finale.
   segmenthead %inline; Titolo di un segmento.
extramaincontents Vuoto Indice generale dell'opera, piazzabile ovunque.
   levels -- -- Attributo Livello di dettaglio dell'indice.
   nopages -- -- Attributo true, false.
endofchapter %inline; Riga finale del capitolo.

Tabella 170.2. Dichiarazione dei titoli di tomi, parti, capitoli e sezioni inferiori, oltre ad altri elementi essenziali nella definizione della scomposizione del testo.

Nella parte iniziale delle classificazioni principali (tomi, parti e capitoli), è possibile collocare la richiesta di inserimento di un indice generale specifico. Si ottiene questo con gli elementi: tomecontents, partcontents e chaptercontents (è disponibile anche l'elemento extramaincontents che riguarda l'opera intera e può essere collocato ovunque). Ognuno di questi elementi prevede l'attributo levels, con il quale è possibile stabilire il livello di dettaglio di tali indici, tenendo presente che con il numero zero si ottengono voci fino alle parti, con uno si ottengono anche i capitoli, mentre con valori superiori si accede alle sezioni di livello inferiore. Anche in questo caso è possibile inibire la segnalazione delle pagine (nel caso di composizione per la stampa), utilizzando l'attributo nopages.

Alla fine del testo di ognuna di queste classificazioni, prima dell'inizio di una sottoclassificazione eventuale, è possibile collocare un «segmento» di testo, con un titolo che assomiglia a una voce di un elenco descrittivo. Si tratta dell'elemento segment, i cui titoli si indicano nell'elemento segmenthead. Questo gruppo rappresenta un'anomalia nell'organizzazione generale, introdotta solo per mantenere la compatibilità con le convenzioni usate in passato nella redazione di questa opera.

Infine, sempre per mantenere la compatibilità con il passato, esiste l'elemento endofchapter, il cui scopo è quello di consentire l'inserimento di una riga di informazioni alla fine del capitolo.

170.3.3   Appendici

Dopo il corpo è possibile inserire l'elemento appendix, il cui scopo è quello di delimitare uno o più capitoli speciali, da intendere come appendici.

170.3.4   Indici analitici

Alml consente la definizione di diversi tipi di indici analitici. Per questi è previsto uno spazio speciale collocato dopo le appendici, se ci sono, o in caso contrario subito dopo il corpo. Si tratta dell'elemento index, che prevede l'inserimento di capitoli, come nel caso delle appendici.

L'inserimento di un elenco riferito a un indice analitico particolare si ottiene con l'elemento vuoto printindex. Verrà descritto meglio in seguito l'uso di questo elemento, perché Alml è in grado di gestire più indici analitici differenti.

170.3.5   Suddivisioni speciali

Oltre alle suddivisioni standard nella forma hn, sono disponibili altre suddivisioni per scopi particolari. Sono previsti due capitoli speciali per le presentazioni (diapositive o lucidi per lavagna luminosa) e per i prospetti schematici riassuntivi (tavole sintetiche e simili), oltre a due tipi di sezioni per domande e risposte.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
slideh1 %inline; Titolo della diapositiva o del lucido.
     id -- -- Attributo Ancora di riferimento.
     lang -- -- Attributo Linguaggio della diapositiva o del lucido.
sheeth1 %inline; Titolo della scheda sintetica riassuntiva.
     id -- -- Attributo Ancora di riferimento.
     lang -- -- Attributo Linguaggio della scheda sintetica.
faqh2 %inline; Titolo del gruppo di domande e risposte.
     id -- -- Attributo Ancora di riferimento.
faqh3 %inline; Domanda a cui segue una risposta.
     id -- -- Attributo Ancora di riferimento.

Tabella 170.3. Dichiarazione dei titoli di capitoli e sezioni speciali.

Osservando la tabella 170.3, si può intuire che gli elementi slideh1 e sheeth1 si usano al posto di un capitolo normale. La differenze più importante rispetto all'elemento h1, sta nel fatto che non possono contenere altre suddivisioni in sezioni; inoltre, nella composizione per la stampa non appare il numero della pagina. Anche se non c'è modo di controllare la dimensione del contenuto, è bene che ogni diapositiva e ogni scheda occupi una sola pagina nella composizione per la stampa.

L'elemento faqh2 va usato al posto di h2, all'interno di un capitolo normale. Permette di introdurre un gruppo di domande e risposte, precedendole eventualmente da qualche blocco di testo introduttivo.

L'elemento faqh3 serve a contenere il testo di una domanda, anche se potrebbe essere più lungo di un titolo normale. Il testo viene rappresentato in modo evidenziato, ma non tanto quanto un elemento h3 normale. Dopo l'elemento faqh3 ci si aspetta di trovare la risposta alla domanda.

Eventualmente, la struttura composta da faqh2 e faqh3 può essere utilizzata anche per realizzare dei questionari o dei test valutativi.

170.4   Documento multilingua

Oltre a indicare il linguaggio nell'elemento alml, attraverso l'attributo lang, lo stesso attributo è disponibile all'inizio dei tomi, delle parti e dei capitoli. In pratica, si può usare l'attributo lang anche negli elementi tomeheading, h0 e h1.

Contrariamente alla logica comune, in questo caso l'attributo lang attribuisce il valore della scelta linguistica a tutto il tomo, alla parte o al capitolo relativo. Un tomo, una parte o un capitolo che non abbiano la definizione esplicita di un linguaggio, ereditano la definizione del livello precedente.

La motivazione più importante per la quale è stato introdotto questo attributo nella dichiarazione dei tomi, delle parti e dei capitoli, sta nel fatto che così la composizione in HTML genera file con intestazioni adeguate, anche per l'indicizzazione delle informazioni.

La sigla della lingua va attribuita secondo lo standard ISO 639 (appendice C). Se non è stata prevista la traduzione dei termini relativi alla composizione nella lingua richiesta, questi si ottengono in inglese.

L'esempio seguente mostra la dichiarazione esplicita di un capitolo che è da considerare in lingua inglese:

<h1 lang="en">Here I am</h1>

La definizione del tomo, della parte o del capitolo non viene adattata alla lingua, per permetterne il controllo attraverso gli elementi tomedefinition, partdefinition e chapterdefinition, descritti più avanti in questo capitolo.

170.5   Blocchi di testo ed elementi inseriti all'interno delle righe

A parte gli elementi strutturali del documento, il DTD di Alml organizza il testo in due gruppi fondamentali: i blocchi di testo, a cui corrisponde l'entità parametrica %block;, e gli elementi collocabili all'interno delle righe, corrispondente all'entità %inline;. Il caso tipico di elemento che costituisce un blocco di testo è il paragrafo, p, mentre il caso tipico di elemento che costituisce un'inserzione nella riga è l'enfatizzazione, em. La tabella 170.4 riepiloga gli elementi comuni che riguardano inserzioni all'interno della riga, mentre quelli che rappresentano un blocco e altri elementi speciali sono descritti separatamente in sezioni apposite.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
em %inline; Enfasi normale.
strong %inline; Enfasi rafforzata.
big %inline; Testo relativamente più grande.
small %inline; Testo relativamente più piccolo.
acronym %inline; Acronimo.
dacronym %inline; Descrizione di un acronimo.
kbd %inline; Tasto.
button %inline; Bottone o tasto grafico.
menuitem %inline; Voce di un menù.
asciicode %inline; Codice ASCII.
code %inline; Codice (come in HTML).
samp %inline; Stringa (come in HTML).
kerneloption %inline; Opzione del kernel.
file var|em|#PCDATA File o directory.
dfn #PCDATA|special Definizione.
strdfn %inline; Definizione in lingua straniera.
special #PCDATA Termine speciale per qualche ragione.
   special -- -- Attributo Nome attribuito al genere del termine.
sup var|em|strong|#PCDATA Apice.
sub var|em|strong|#PCDATA Pedice.
pwr var|em|strong|#PCDATA Potenza (esponente).
navlink #PCDATA Riferimento per la navigazione HTML.

Tabella 170.4. Elementi inseriti all'interno delle righe.

170.5.1   Numeri

La rappresentazione uniforme di valori numerici, specie quando si opera spesso con basi di numerazione insolite, diventa un aspetto delicato. Alml prevede alcuni elementi da utilizzare all'interno delle righe per delimitare valori numerici, eventualmente con basi di numerazioni particolari, come si vede nella tabella 170.5.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
num [+-]?[0-9]+[.,]?[0-9]* Numero decimale comune.
exa var|em|strong|#PCDATA Numero in base 16.
dec var|em|strong|#PCDATA Numero in base 10.
oct var|em|strong|#PCDATA Numero in base 8.
bin var|em|strong|#PCDATA Numero in base 2.

Tabella 170.5. Elementi inseriti all'interno delle righe per la rappresentazione uniforme di valori numerici.

Il caso dell'elemento num è speciale. In particolare, si fa riferimento a un numero in base 10, in cui non si mostra la base di numerazione, ma si usa una modalità di rappresentazione standard. Per questa ragione, il numero in questione deve essere inserito come previsto, utilizzando la virgola o il punto come separatore della parte decimale,(3) aggiungendo il segno all'inizio, se necessario, senza usare altri spazi o altri caratteri. Il numero viene elaborato separando le cifre a terne.

Per quanto riguarda gli altri elementi, a seconda del tipo di composizione si utilizza un modo diverso per mostrare la base di numerazione. Tuttavia, in questi casi il contenuto degli elementi non è strettamente letterale, come si vede dalla tabella.

170.5.2   Elenchi e simili

Gli elenchi di Alml sono molto semplici. Si tratta dei soliti elenchi puntati, numerati e descrittivi. Questi si comportano in modo molto simile all'HTML; la differenza sostanziale sta nel fatto che il contenuto delle voci è composto da uno o più blocchi di testo, mentre in HTML è consentita anche la presenza di righe pure e semplici.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
dl Elenco descrittivo.
   dt %inline; Termine descrittivo.
   dd %block; Descrizione relativa.
ol Elenco numerato.
   li %block; Elemento dell'elenco.
ul Elenco puntato.
   li %block; Elemento dell'elenco.

Tabella 170.6. Elenchi.

170.5.3   Testo letterale o quasi

L'inclusione di testo letterale in un sorgente SGML è sempre un problema. Alml prevede due ambienti diversi: verbatimpre e pre. Nel primo caso si può scrivere senza alcuna preoccupazione, tranne per il fatto che non può essere inclusa una stringa equivalente a <verbatimpre> o a </verbatimpre>; nel secondo caso invece, è necessario comportarsi come nel testo normale, utilizzando le entità standard quando servono, potendo includere anche gran parte degli elementi che rappresentano un'inserzione all'interno di una riga. In entrambi i casi vengono rispettate le interruzioni di riga.

<verbatimpre>
uno
   &
    due
</verbatimpre>
<pre>
uno
   &amp;
    due
</pre>

I due esempi portano allo stesso risultato:

uno
   &
    due

In generale si sceglierà il primo modo, mentre il secondo lo si riserva ai casi in cui si devono inserire le cose che il primo non può contenere.

In un documento a carattere tecnico-informatico, è essenziale la possibilità di indicare dei modelli sintattici. Alml prevede l'uso di un elemento simile a pre, dedicato precisamente a questo scopo: syntax.

<syntax>
man <synsqb><var>n_sezione</var></synsqb> <var>nome</var>
</syntax>

All'interno di questo elemento si possono inserire altri elementi specifici per rappresentare i componenti della sintassi. Infatti, è necessario distinguere tra parole chiave, metavariabili e altre indicazioni. In generale, quello che si scrive normalmente deve essere inteso come un dato fisso, ovvero delle parole chiave o delle stringhe fisse. Per indicare un contenuto variabile si utilizza l'elemento var per delimitare la denominazione di un qualcosa di variabile (un'opzione o qualcosa del genere).

Altri elementi speciali servono a guidare la lettura della sintassi: synsqb delimita una parte della sintassi che va intesa come facoltativa e si traduce generalmente con delle parentesi quadre che, se possibile, si distinguono dal testo normale; syncub delimita una parte della sintassi che va intesa come un corpo unico e si traduce generalmente con delle parentesi graffe speciali; synverbar (elemento vuoto) indica un'alternativa e si rappresenta con una barra verticale. Nell'uso di questi elementi occorre sempre un po' di prudenza, tenendo conto dei tipi di composizione in cui non è possibile mostrare questi simboli in forme diverse dal normale.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
pre %inline; Testo preformattato.
     width -- -- Attributo Ampiezza massima in caratteri del testo.
   pnewline Vuoto Continuazione nella riga successiva.
verbatimpre testo letterale Testo letterale preformattato.
     width -- -- Attributo Ampiezza massima in caratteri del testo.
syntax %inline; Modello sintattico preformattato.
     width -- -- Attributo Ampiezza massima in caratteri del testo.
   synsqb %inline; Parentesi quadre di un modello sintattico.
   syncub %inline; Parentesi graffe di un modello sintattico.
   synverbar %inline; Barra verticale di un modello sintattico.
   var %inline; Metavariabile sintattica.
   synellipsis Vuoto Ellissi nei modelli sintattici.
   snewline Vuoto Continuazione nella riga successiva.

Tabella 170.7. Elementi SGML che riguardano la rappresentazione di testo preformattato.

Si tenga in considerazione il fatto che gli elementi synsqb, syncub, synverbar e var, possono essere utilizzati anche al di fuori dell'elemento syntax, in qualità di inserzioni normali nelle righe.

La riga di un modello sintattico che si estende troppo in orizzontale, può essere spezzata e ripresa inserendo l'elemento vuoto snewline, in modo da ottenere una segnalazione evidente nella composizione finale, senza lasciare ambiguità. La stessa cosa, eventualmente, si può fare nell'elemento pre, usando l'elemento vuoto pnewline.

Gli elementi pre, verbatimpre e syntax, sono predisposti inizialmente per poter rappresentare 80 colonne di testo letterale, in una larghezza di 15 cm (quella normale del corpo). In situazioni particolari può essere necessario ampliare o ridurre la dimensione dei caratteri nella composizione stampata, per consentire la rappresentazione di un testo più ampio orizzontalmente. In questi casi, si può utilizzare l'attributo width, assegnando la quantità di colonne che si desiderano. Si fa sempre riferimento a una larghezza del testo di 15 cm e in base alla quantità di colonne richiesta, la dimensione del carattere viene adattata.

Viene lasciata la facoltà di ridefinire la larghezza del testo anche nell'elemento syntax, benché sia possibile interrompere e riprendere le righe troppo lunghe, come già descritto, con l'elemento snewline.

<pre width="90">
1234567890
          1234567890
                    1234567890
                              1234567890
                                        1234567890
                                                  1234567890
                                                            1234567890
                                                                      1234567890
                                                                                1234567890
</pre>

L'esempio mostra l'utilizzo di un elemento pre per rappresentare un testo che si estende su 90 colonne.

170.5.4   Comandi

I comandi che si impartiscono attraverso una riga di comando, possono essere rappresentati con l'elemento command. Si osservi l'esempio seguente:

<command><prompt>$ </prompt><type>ls</type><kbd>Invio</kbd></command>

Nell'ambito dell'elemento command è quasi tutto facoltativo; tuttavia, l'invito, rappresentato dall'elemento prompt, va messo per primo. Dopo l'elemento type, che serve a delimitare il testo che viene inserito sulla riga di comando, è possibile anche specificare il tasto che serve a concludere la digitazione, come in questo caso, oppure se ne può fare a meno, lasciandolo sottinteso.

Il testo che viene restituito da un comando si rappresenta normalmente con l'elemento verbatimpre.

A volte, si ha la necessità di rappresentare dei comandi piuttosto lunghi, che nella composizione stampata potrebbero risultare spezzati in modo imprevedibile e indesiderabile. È possibile indicare esplicitamente dove spezzare il comando, facendo in modo che nella composizione si intenda chiaramente questo fatto. Per questo si usa l'elemento vuoto cnewline, che si inserisce all'interno di type.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
command Comando da digitare.
   prompt %inline; Stringa dell'invito.
   type %inline; Digitazione del comando.
      cnewline Vuoto Continua il comando a riga nuova.
   kbd %inline; Tasto o combinazione di tasti.
   button %inline; Bottone o tasto grafico.

Tabella 170.8. Elementi SGML che servono a rappresentare un comando.

170.5.5   Figure

Alml permette di gestire le figure in diversi modi. In generale può trattarsi di file di immagine, oppure di altre cose, come dei disegni ASCII racchiusi nell'elemento verbatimpre.

L'ambiente normale in cui si inserisce una figura è quello dato dall'elemento figure, che in particolare può essere definito come flottante oppure fisso nel punto in cui si trova. All'interno di questo elemento può essere collocata una figura costituita da un'immagine esterna, da un'immagine incorporata, oppure un blocco di testo normale, come un elemento verbatimpre per realizzare un disegno ASCII.

<figure id="f-esempio-1">
<fcaption>
    Figura <figureref>. Ecco il mio primo esempio.
</fcaption>
<image imgfile="esempio-1" height="4cm">
</figure>

L'esempio mostra la situazione più comune. Si tratta dell'incorporazione del file esempio-1.png, dove viene stabilita l'altezza di quattro centimetri, lasciando che la larghezza si adatti di conseguenza, in modo relativo. Si può osservare che l'elemento figure contiene un attributo id, che serve evidentemente per poter fare riferimento alla figura.

L'elemento fcaption serve a delimitare il testo che si vuole fare apparire come didascalia. Al suo interno si nota la presenza di un elemento vuoto, figureref, che in questo caso rappresenta un riferimento all'ultima figura, cioè a se stessa.

Una figura ASCII potrebbe essere realizzata, per esempio, nel modo seguente, come in tanti altri modi possibili che fanno uso di blocchi di testo:

<figure id="f-esempio-1">
<fcaption>
    Figura <figureref>. Ecco il mio primo esempio.
</fcaption>
<pre>
    pinco &amp; pallino
          |
          `--&gt; e-commerciale
</pre>
</figure>

Oltre all'elemento figure, ci sono altre situazioni in cui si possono collocare delle figure: l'elemento img per le immagini inserite nel testo, l'elemento frontcoverpicture per l'immagine sulla copertina iniziale e l'elemento backcoverpicture per l'immagine sulla copertina finale.

<p>Bla bla bla <img imgfile="f-esempio-1" alt="Esempio" height="4mm"> bla
bla bla.</p>
<head>
    <admin>
        <description>An example for Alml documentation system</description>
        <keywords>SGML, XML, HTML, Alml</keywords>
    </admin>
    <title>Example to use Alml</title>
    <author>Pinco Pallino &lt;pinco.pallino@brot.dg&gt;</author>
    <date>2011.11.11</date>
    <frontcoverpicture imgfile="f-esempio-1" height="5cm">
    <legal>
        <p>Copyright &copy; Pinco Pallino, &lt;pinco.pallino@brot.dg&gt;</p>
    </legal>
    <maincontents levels="2">Table of contents</maincontents>
</head>
Elemento o attributo Apertura Chiusura Contenuto Descrizione
figure Involucro di una figura normale.
     id -- -- Attributo Ancora di riferimento per la figura.
     pos -- -- Attributo fixed, float.
     sep -- -- Attributo none, rule.
   fcaption %inline; Didascalia.
   image Vuoto Riferimento a un'immagine esterna.
     imgfile -- -- Attributo File contenente l'immagine, senza estensione.
     height -- -- Attributo Altezza dell'immagine.
     width -- -- Attributo Larghezza dell'immagine.
   embimage #PCDATA Immagine incorporata; algoritmo Base64.
     alt -- -- Attributo Descrizione alternativa alla visualizzazione.
     height -- -- Attributo Altezza dell'immagine.
     width -- -- Attributo Larghezza dell'immagine.
   epsimage #PCDATA Codice EPS letterale.
     alt -- -- Attributo Descrizione alternativa alla visualizzazione.
     width -- -- Attributo Larghezza.
     height -- -- Attributo Altezza.
img Vuoto Immagine inserita in una riga.
   alt -- -- Attributo Descrizione alternativa alla visualizzazione.
   imgfile -- -- Attributo File contenente l'immagine, senza estensione.
   height -- -- Attributo Altezza dell'immagine.
   width -- -- Attributo Larghezza dell'immagine.
embimg #PCDATA Immagine incorporata; algoritmo Base64.
   alt -- -- Attributo Descrizione alternativa alla visualizzazione.
   height -- -- Attributo Altezza dell'immagine.
   width -- -- Attributo Larghezza dell'immagine.
epsimg #PCDATA Codice EPS letterale.
   alt -- -- Attributo Descrizione alternativa alla visualizzazione.
   width -- -- Attributo Larghezza.
   height -- -- Attributo Altezza.
frontcoverpicture Vuoto Immagine di copertina.
   imgfile -- -- Attributo File contenente l'immagine, senza estensione.
   height -- -- Attributo Altezza dell'immagine.
   width -- -- Attributo Larghezza dell'immagine.
backcoverpicture Vuoto Immagine della copertina finale.
   imgfile -- -- Attributo File contenente l'immagine, senza estensione.
   height -- -- Attributo Altezza dell'immagine.
   width -- -- Attributo Larghezza dell'immagine.

Tabella 170.9. Elementi SGML che servono a rappresentare delle figure di qualche tipo.

I nomi dei file indicati nell'attributo imgfile devono essere privi di estensione, intendendo implicitamente che questa sia .png.

Quando si inserisce il file di un'immagine, l'elemento relativo consente l'utilizzo degli attributi height e width. Evidentemente il primo permette di specificare l'altezza della figura e il secondo riguarda la larghezza. In linea di principio, i file di immagini hanno delle dimensioni, anche se queste sono espresse in pixel, ovvero in punti grafici. In generale conviene specificare l'altezza, oppure la larghezza, tenendo in considerazione il risultato per la composizione stampata, sapendo che l'informazione mancante viene determinata in modo relativo. Evidentemente, fissando entrambe le dimensioni, si ottiene un adattamento dell'immagine che non è necessariamente relativo.

Le dimensioni, ovvero le stringhe che si assegnano agli attributi citati, hanno una forma prestabilita:

nunità_di_misura

Le unità di misura sono sigle di due lettere equivalenti a quelle di LaTeX, escludendo le unità relative (si veda la tabella 170.10).

Sigla Unità di misura corrispondente
pt Punti tipografici corrispondenti a 1/72 di pollice.
pc Pica corrispondenti a 1/6 di pollice.
in Pollici.
cm Centimetri.
mm Millimetri.

Tabella 170.10. Sigle delle unità di misura utilizzabili nell'adattamento delle dimensioni delle figure.

La composizione in HTML implica l'adattamento delle figure, in modo tale che la dimensione in punti grafici corrisponda al 200 % dei punti tipografici.(4) In pratica, nell'ambito di questa conversione, un punto grafico equivale a circa 0,027 8 pollici, ovvero a 0,705 5 mm. Questo tipo di rapporto è quello che ha dimostrato produrre la composizione HTML più vicina al risultato stampato.

Gli elementi per l'inserimento di immagini nel testo, come si vede dalla tabella 170.9, hanno un attributo denominato alt. Si tratta di un'informazione facoltativa, con la quale si descrive brevemente l'immagine. Questa informazione serve nella composizione HTML, per mostrare una descrizione minima in caso di problemi nella visualizzazione dell'immagine.

Oltre a immagini esterne, è possibile incorporare nel sorgente SGML due tipi di immagini: file trasformati secondo l'algoritmo Base64, che come tali possono inserirsi in un file di testo normale, oppure codice EPS che viene estrapolato nel momento della composizione.

Per incorporare un'immagine codificata con l'algoritmo Base64 si può usare il programma Uuencode, oppure Mpack, descritti nel capitolo 114. Supponendo di utilizzare Uuencode e di volere inserire l'immagine contenuta nel file prova.jpg, basta procedere come segue:

uuencode -m prova.jpg ciao > prova.uuencode

Quello che si ottiene in questo caso è il file prova.uuencode, che può apparire simile al testo seguente, che è stato ridotto per comodità:

begin-base64 664 ciao
JSFQUy1BZG9iZS0yLjAKJSVDcmVhdG9yOiAiYmFyY29kZSIsIGxpYmJhcmNv
ZGUgc2FtcGxlIGZyb250ZW5kCiUgJSVEb2N1bWVudFBhcGVyU2l6ZXM6IGE0
...
...
b3cKMTA0LjAwIDEwLjAwIG1vdmV0byAoOSkgc2hvdwoKJSBFbmQgYmFyY29k
ZSBmb3IgIjk5MTIzNDU2Nzg5MCIKCiUlRW5kUGFnZQoKc2hvd3BhZ2UKJSVU
cmFpbGVyCiUlRU9GCgo=
====

Da questo file, ottenuto con Uuencode, va tolta la prima e l'ultima riga; il resto si può inserire in un elemento EMBIMG, oppure EMBIMAGE. Vengono mostrati entrambi i casi.

<p>Bla bla bla
<embimg alt="Esempio" height="4mm">
<![CDATA[
JSFQUy1BZG9iZS0yLjAKJSVDcmVhdG9yOiAiYmFyY29kZSIsIGxpYmJhcmNv
ZGUgc2FtcGxlIGZyb250ZW5kCiUgJSVEb2N1bWVudFBhcGVyU2l6ZXM6IGE0
...
...
b3cKMTA0LjAwIDEwLjAwIG1vdmV0byAoOSkgc2hvdwoKJSBFbmQgYmFyY29k
ZSBmb3IgIjk5MTIzNDU2Nzg5MCIKCiUlRW5kUGFnZQoKc2hvd3BhZ2UKJSVU
cmFpbGVyCiUlRU9GCgo=
]]>
</embimg> bla bla bla.</p>
<figure id="f-esempio-1">
<fcaption>
    Figura <figureref>. Ecco il mio primo esempio.
</fcaption>
<embimage alt="Esempio" height="4cm">
<![CDATA[
JSFQUy1BZG9iZS0yLjAKJSVDcmVhdG9yOiAiYmFyY29kZSIsIGxpYmJhcmNv
ZGUgc2FtcGxlIGZyb250ZW5kCiUgJSVEb2N1bWVudFBhcGVyU2l6ZXM6IGE0
...
...
b3cKMTA0LjAwIDEwLjAwIG1vdmV0byAoOSkgc2hvdwoKJSBFbmQgYmFyY29k
ZSBmb3IgIjk5MTIzNDU2Nzg5MCIKCiUlRW5kUGFnZQoKc2hvd3BhZ2UKJSVU
cmFpbGVyCiUlRU9GCgo=
]]>
</embimage>
</figure>

Dal momento che si vuole evitare qualunque interpretazione SGML, può essere conveniente racchiudere il contenuto di questi elementi in una sezione marcata di tipo CDATA, così come si può vedere.

In modo analogo funzionano gli elementi EPSIMG e EPSIMAGE per quanto riguarda il codice EPS inserito direttamente nel sorgente. Vengono mostrati due esempi.

<p>Bla bla bla
<epsimg alt="Esempio" height="4mm">
<![CDATA[
%!PS-Adobe-2.0 EPSF-1.2
%%Creator: Pinco Pallino
%%BoundingBox: 0 0 500 500
%%Title: Un bel disegno
%%EndComments
...
...
showpage
%%Trailer
%%EOF
]]>
</epsimg> bla bla bla.</p>
<figure id="f-esempio-1">
<fcaption>
    Figura <figureref>. Ecco il mio primo esempio.
</fcaption>
<epsimage alt="Esempio" height="4cm">
<![CDATA[
%!PS-Adobe-2.0 EPSF-1.2
%%Creator: Pinco Pallino
%%BoundingBox: 0 0 500 500
%%Title: Un bel disegno
%%EndComments
...
...
showpage
%%Trailer
%%EOF
]]>
</epsimage>
</figure>

170.5.6   Tabelle

Come nel caso delle figure, le tabelle sono organizzate in modo da poter essere rappresentate da qualunque cosa: una tabella come si è abituati di solito, oppure dei blocchi di testo, anche preformattato, come pre e verbatimpre.

L'involucro di una tabella funziona in modo simile a quello di una figura:

<table id="t-esempio-1">
<tcaption>
    Tabella <tableref>. Ecco il mio primo esempio.
</tcaption>
...
...
</table>

Anche l'elemento table possiede gli attributi id e pos, con lo stesso significato che hanno nell'elemento figure. Nello stesso modo funziona la didascalia, che in questo caso è delimitata dall'elemento tcaption, mentre il riferimento all'ultima tabella avviene con l'elemento tableref.

A parte la possibilità di disegnare la tabella usando blocchi di testo normali, la tabella tipica incorpora l'elemento tabular:

<table id="t-esempio-1">
<tcaption>
    Tabella <tableref>. Ecco il mio primo esempio.
</tcaption>
<tabular col="2">
<thead>
<trow>  Dispositivo     <colsep> Descrizione                    </trow>
</thead>
<tbody>
<trow> /dev/fd0         <colsep> Prima unità a dischetti.       </trow>
<trow> /dev/hda         <colsep> Primo disco fisso IDE/EIDE.    </trow>
<trow> /dev/hdb         <colsep> Secondo disco fisso IDE/EIDE.  </trow>
<trow> /dev/sda         <colsep> Primo disco SCSI.              </trow>
<trow> /dev/lp0         <colsep> Prima porta parallela.         </trow>
<trow> /dev/ttyS0       <colsep> Prima porta seriale.           </trow>
</tbody>
</tabular>
</table>

L'esempio mostrato è sufficientemente completo: l'elemento tabular ha un attributo obbligatorio, col, con il quale è necessario dichiarare subito la quantità di colonne che compone la tabella. Le righe della tabella sono raggruppate in due gruppi: l'intestazione, delimitata dall'elemento thead, e il corpo, delimitato dall'elemento tbody. Le righe sono definite dall'elemento trow e la separazione tra una colonna e l'altra avviene con l'elemento vuoto colsep.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
table Involucro di una tabella.
     id -- -- Attributo Ancora di riferimento per la tabella.
     pos -- -- Attributo fixed, float.
   tcaption %inline; Didascalia.
   tabular Descrizione del reticolo di righe e colonne.
       col -- -- Attributo Quantità di colonne presenti.
     thead trow Righe di intestazione.
       trow Riga.
       colsep Separazione tra le colonne.
     tbody trow Righe del corpo.
       trow Riga.
       colsep Separazione tra le colonne.

Tabella 170.11. Elementi SGML che servono a rappresentare le tabelle.

La gestione delle tabelle di Alml è molto limitata; in particolare le celle non possono contenere più di una riga, per cui le informazioni che si possono inserire devono essere molto sintetiche. In situazioni eccezionali, si può valutare la possibilità di realizzare tabelle HTML utilizzando l'elemento html, come si vede nell'esempio di tabella 170.20. Tuttavia, si deve ricordare che si tratta di codice esterno, per cui non si possono inserire elementi tipici di Alml, ma solo codice HTML; inoltre, la trasformazione in forma di testo puro di una tabella HTML non avviene nel modo corretto.

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

Fino a questo punto sono stati descritti gli elementi che delimitano i titoli dei tomi, delle parti, dei capitoli e delle sezioni; inoltre sono stati visti gli elementi che avvolgono le figure e le tabelle. Tutti questi sono ancore a cui si può puntare. Inoltre, per inserire un'ancora nel testo normale, è possibile usare l'elemento vuoto anchor, anche questo provvisto di attributo id.

Esistono tre elementi vuoti per fare riferimento alle ancore: sectionref, per ottenere un riferimento alla sezione in cui si trova l'ancora; figureref per fare riferimento a una figura; tableref per fare riferimento a una tabella.

In particolare, gli elementi figureref e tableref possono essere usati anche senza l'attributo id per fare riferimento all'ultima ancora di una figura o di una tabella, come è già stato mostrato nell'uso delle didascalie.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
tomeheading Titolo di un tomo.
     id -- -- Attributo Ancora di riferimento per il titolo del tomo.
h0 Titolo di una parte.
     id -- -- Attributo Ancora di riferimento per il titolo della parte.
h1 Titolo di un capitolo.
     id -- -- Attributo Ancora di riferimento per il titolo di un capitolo.
h2 Titolo di una sezione.
     id -- -- Attributo Ancora di riferimento per il titolo di una sezione.
h3 Titolo di una sottosezione.
     id -- -- Attributo Ancora di riferimento per il titolo di una sottosezione.
h4 Titolo di una sotto-sottosezione.
     id -- -- Attributo Ancora per il titolo di una sotto-sottosezione.
anchor Vuoto Ancora inserita nel testo.
     id -- -- Attributo Stringa di identificazione dell'ancora.
sectionref Vuoto Riferimento a un'ancora del testo.
     id -- -- Attributo Stringa a cui si fa riferimento.
figure Involucro di una figura.
     id -- -- Attributo Ancora di riferimento per la figura.
figureref Vuoto Riferimento a un'ancora di una figura.
     id -- -- Attributo Stringa a cui si fa riferimento.
table Involucro di una tabella.
     id -- -- Attributo Ancora di riferimento per la tabella.
tableref Vuoto Riferimento a un'ancora di una tabella.
     id -- -- Attributo Stringa a cui si fa riferimento.

Tabella 170.12. Gestione dei riferimenti incrociati.

170.5.8   Note e piè pagina

Alml prevede l'utilizzo di tre tipi di annotazioni: avvertimenti che devono risaltare in un riquadro e due tipi di 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, oppure blockfootnote.

Le note a piè pagina normali sono quelle dell'elemento footnote, che si colloca all'interno delle righe; al contrario, blockfootnote rappresenta un blocco di testo, che rimane solo per compatibilità con il passato.

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

<p>Bla bla bla<footnote>Questa parola si ripete.</footnote> bla bla...</p>
Elemento o attributo Apertura Chiusura Contenuto Descrizione
frame %block; Riquadro.
blockfootnote %inline; Piè pagina tra i blocchi di testo.
footnote %inline; Piè pagina all'interno di una riga di testo.

Tabella 170.13. Annotazioni a vario titolo.

170.5.9   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 URI:

<p>Bla bla bla <uri>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:

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

La tabella 170.14 riepiloga questi e altri elementi affini.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
uri #PCDATA Riferimento a un URI esterno.
uristr #PCDATA Riferimento a un URI che non funziona.
blockquote %block;, quoteinfo Citazione.
   quoteinfo %inline; Informazioni sulla citazione.
bibref %inline; Titolo di un documento.
man #PCDATA, mansect Pagina di manuale.
   mansect #PCDATA Numero della sezione.

Tabella 170.14. Riferimenti esterni.

È importante osservare un particolare importante: la filosofia elementare di Alml fa sì che tutti gli attributi degli elementi siano trattati in modo letterale. Un URI potrebbe essere molto articolato, contenendo anche caratteri particolari che potrebbero creare problemi al sistema di composizione successivo. Per questo motivo, l'elemento uri racchiude l'informazione all'interno dell'elemento e non in un attributo; in questo modo si potranno usare le entità standard se necessario.

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 di 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>
    %block;
    ...
    [<quoteinfo>%inline;...</quoteinfo>]
</blockquote>

170.5.10   Altre inserzioni particolari

Sono disponibili altri elementi di importanza minore. Si tratta di br, hr, newpage, bottompage e navlink. I primi due emulano gli elementi corrispondenti dell'HTML, interrompendo una riga e inserendo una linea orizzontale rispettivamente.

L'elemento newpage richiede un salto pagina, se il tipo di composizione lo consente.

L'elemento bottompage serve per definire un gruppo di blocchi di testo da rappresentare nella parte bassa della pagina, nella composizione per la stampa. In pratica, si usa bottompage per delimitare informazioni legali nella seconda pagina relativa dei tomi:

<tomeheading>Bla bla bla</tomeheading>

<bottompage>
    <p>Copyright &copy; Pinco Pallino...</p>
    
    <p>Bla bla bla...</p>
</bottompage>
Elemento o attributo Apertura Chiusura Contenuto Descrizione
br Vuoto Interruzione della riga.
hr Vuoto Riga orizzontale di separazione.
newpage Vuoto Salto pagina se ammissibile.
bottompage %block; Testo da rappresentare nella parte bassa della pagina.
navlink #PCDATA Riferimento ipertestuale per la navigazione HTML.

Tabella 170.15. Inserzioni varie.

L'elemento navlink consente di aggiungere nella composizione HTML un riferimento ipertestuale fisso, in tutte le pagine, allo scopo di raggiungere facilmente la posizione in cui l'elemento stesso viene inserito. Si osservi l'esempio seguente:

<h1>
Indice analitico
</h1>

<navlink>indice analitico</navlink>

<printindex index="main">

</index>

Si tratta dell'inserimento dell'indice analitico, con l'aggiunta di un riferimento ipertestuale fisso nelle pagine della composizione HTML.

170.6   Tracciamento di informazioni particolari

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.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
indexentry #PCDATA|code Dichiarazione di una voce per l'indice analitico.
   index -- -- Attributo Nome dell'indice analitico in cui inserire la voce.
   emph -- -- Attributo Enfatizzazione: normal o code (obsoleto).
special #PCDATA Termine speciale.
   special -- -- Attributo Nome dell'indice analitico in cui inserire la voce.
printindex Vuoto Inserisce l'elenco dell'indice analitico richiesto.
   index -- -- Attributo Nome dell'indice analitico richiesto.

Tabella 170.16. Gestione degli indici analitici.

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.

170.6.1   Caratteristiche del software e di altri «lavori»

La struttura di Alml dispone di un elemento %inline; speciale, 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>

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.

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

Elemento o attributo Apertura Chiusura Contenuto Descrizione
workinfo Dichiarazione del blocco di informazioni.
   workname #PCDATA Nome del software o di altro lavoro.
   worklicense #PCDATA Denominazione o descrizione breve della licenza.
   worklicensetext %block; Testo della licenza specifica.
   worknotes %block; Annotazioni.
printworkinfo Vuoto Inserisce le informazioni accumulate in modo ordinato.

Tabella 170.17. Tracciamento di informazioni sul software citato.

170.6.2   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 questa volta costituisce un blocco.

<docinfo>
<docoriginnote>di Tizio Tizi</docoriginnote>
<docnotes>

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

</docnotes>
</docinfo>

L'esempio mostra l'utilizzo più semplice di questo elemento. In particolare si vede l'indicazione dell'autore originale nell'elemento docoriginnote, assieme a una breve nota nell'elemento docnote.

La cosa può essere anche più articolata, includendo informazioni sull'ultima revisione, con l'elemento docrevisionnote (soprattutto sugli ultimi revisori), oltre alla possibilità di indicare qualunque altra informazione, più o meno dettagliata nell'elemento docnotes.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
docinfo Dichiarazione del blocco di informazioni.
   docauthor #PCDATA Nome di un autore del documento.
   docoriginnote #PCDATA Note sull'origine del documento.
   docrevisionnote #PCDATA Note sull'ultima revisione del testo.
   docnotes %block; Annotazioni varie.
printdocinfo Vuoto Inserisce nel testo le informazioni accumulate.

Tabella 170.18. Tracciamento di informazioni su sezioni particolari del documento globale.

Si osservi che quanto inserito negli elementi docoriginnote e docrevisionnote, se forniti, appare nel testo.

Per ottenere l'elenco delle informazioni accumulate in questo modo, si utilizza l'elemento vuoto printdocinfo.

Oltre agli elementi docoriginnote e docrevisionnote, si può usare uno o più elementi docauthor per elencare gli autori. La differenza sta nel fatto che i primi due elementi vengono mostrati nella composizione, mentre gli elementi docauthor sono solo accumulati per essere inseriti nell'elenco che si ottiene con l'elemento vuoto printdocinfo.

<docinfo>
    <docoriginnote>di Tizio Tizi &lt;tizio@brot.dg&gt;,
      Caio Cai &lt;caio@brot.dg&gt; e altri</docoriginnote>
    <docrevisionnote>ultimo aggiornamento di Pinco Pallino
      &lt;pinco@brot.dg&gt;</docoriginnote>
    <docauthor>Tizio Tizi tizio@brot.dg</docauthor>
    <docauthor>Caio Cai caio@brot.dg</docauthor>
    <docauthor>Sempronio Semproni sempronio@brot.dg</docauthor>
    <docauthor>Pinco Pallino pinco@brot.dg</docauthor>
</docinfo>

In questo esempio, si vogliono annotare gli autori nell'elenco generato da printdocinfo, senza la necessità di altri commenti, facendo anche in modo che i loro nomi appaiano nel documento relativo, attraverso l'elemento docoriginnote (il cui contenuto non appare nell'elenco finale), mostrando anche chi è responsabile nell'ultimo aggiornamento del testo, attraverso l'elemento docrevisionnote.

170.6.3   Condizioni particolari per il contenuto di una sezione

È previsto un contenitore speciale per indicare le condizioni particolari che riguardano una certa sezione (anche un tomo intero). Si tratta dell'elemento specialcondition, all'interno del quale può eventualmente apparire l'elemento vuoto nomod:

<specialcondition><nomod>non è consentita la modifica di questa
sezione</specialcondition>

L'esempio dovrebbe rendere l'idea della cosa. Il testo contenuto nell'elemento specialcondition viene mostrato effettivamente, utilizzando un carattere un po' diverso da quello normale, in modo da risaltare.

L'elemento vuoto nomod serve per tenere traccia in particolare di quelle sezioni che non possono essere modificate. Evidentemente, può essere utile solo se il documento, nella sua globalità, è inteso come modificabile, in base alle condizioni della licenza. In generale non dovrebbe essere necessario;(5) tuttavia, in questo modo, è possibile poi ottenere un elenco dettagliato di tutte le sezioni che non possono essere modificate, con l'elemento vuoto printnomod.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
specialcondition #PCDATA|nomod Dichiarazione di condizioni particolari.
   nomod Vuoto Annotazione di sezione non modificabile.
printnomod Vuoto Elenco delle sezioni non modificabili.

Tabella 170.19. Annotazione delle condizioni particolari di una sezione.

170.7   Inserimento letterale di codice TeX e HTML, con eventuale inserimento condizionato

In situazioni eccezionali, può essere conveniente l'inserimento di codice scritto secondo il linguaggio di composizione che si trova al di sotto della struttura SGML di Alml. Lo scopo di Alml non è quello di mantenere un legame sicuro con TeX e HTML, tuttavia vale la pena di lasciare aperta questa possibilità.

Si pensi all'eventuale necessità di inserire qualcosa di particolare nella composizione HTML, per esempio per inserire un contatore di accesso, o altri tipi di inserzioni ritenuti utili per qualche ragione.

Per risolvere questo problema si possono usare due elementi speciali: tex e html. Come si può intuire, il primo elemento è fatto per racchiudere codice TeX o LaTeX; il secondo serve per includere codice HTML.

Dal momento che si vuole evitare qualunque interpretazione SGML, conviene racchiudere il contenuto di questi elementi in una sezione marcata di tipo CDATA. Si osservi l'esempio seguente:

<html><![CDATA[
    <hr>
    <p><a href="http://www.digits.com/">Web-Counter: </a><a
    href="http://www.digits.com/"><img
    src="http://counter.digits.com/wc/tizio345"
    alt="counter"></a></p>
]]></html>

In questo caso si tratta di un'inclusione di codice HTML, dove per poter scrivere i marcatori in modo letterale è stato necessario includere tutto all'interno della sezione marcata CDATA. Quello che segue è invece l'esempio dell'inclusione di codice TeX, dove capita che non ci siano problemi per l'SGML:

<tex>
$$ \chi^2 = \sum_{i=1}^N
          \left (y_i - (a + b x_i)
          \over \sigma_i\right)^2 $$
</tex>

A fianco di questo problema, sta poi la possibilità di delimitare facilmente dei blocchi di sorgente che debbano essere presi in considerazione solo se la composizione avviene attraverso una trasformazione in TeX o in HTML. In pratica, si utilizzano rispettivamente gli elementi iftex e ifhtml. Questi elementi non sono indispensabili, perché l'SGML offre già un meccanismo di controllo dell'elaborazione del sorgente, attraverso le sezioni marcate; tuttavia, servono per completare e concludere il problema degli elementi contenenti codice speciale TeX o HTML.

Il codice HTML può essere rappresentato in parte anche quando la composizione avviene attraverso TeX, per mezzo di HTML2ps. In pratica, con il codice HTML si ottiene un'immagine che viene poi incorporata nel sorgente TeX. Questa estensione serve specialmente per consentire la realizzazione di tabelle più complesse di quanto consenta Alml con il suo elemento tabular. Si osservi l'esempio seguente, che viene poi rappresentato nella tabella 170.20:

<table id="t-alml-incorporazione-tabella-html">
<tcaption>
    Tabella <tableref>. Incorporazione di codice HTML per rappresentare
    una tabella complessa.
</tcaption>
<html width=6in>
<![CDATA[
<table border="1">
  <thead>
    <tr>
      <td rowspan="2"><p>Denominazione della porta seriale su i386 nei sistemi
        Dos</p>
      </td>
      <td colspan="2"><p>Risorse</p>
      </td>
      <td rowspan="2"><p>File di dispositivo nei sistemi GNU/Linux</p>
      </td>
      <td rowspan="2"><p>Annotazioni</p>
      </td>
    </tr>
    <tr>
      <td><p>IRQ</p>
      </td>
      <td><p>I/O</p>
      </td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><p>COM1</p>
      </td>
      <td rowspan="2"><p align="center">4</p>
      </td>
      <td><p>3F8<sub>16</sub></p>
      </td>
      <td><p>/dev/ttyS0</p>
      </td>
      <td rowspan="2"><p>La prima e la terza porta seriale condividono lo
        stesso IRQ.</p>
      </td>
    </tr>
    <tr>
      <td><p>COM3</p>
      </td>
      <td><p>3E8<sub>16</sub></p>
      </td>
      <td><p>/dev/ttyS2</p>
      </td>
    </tr>
    <tr>
      <td><p>COM2</p>
      </td>
      <td rowspan="2"><p align="center">3</p>
      </td>
      <td><p align="right">2F8<sub>16</sub></p>
      </td>
      <td><p>/dev/ttyS0</p>
      </td>
      <td rowspan="2"><p>La seconda e la quarta porta seriale condividono lo
        stesso IRQ.</p>
      </td>
    </tr>
    <tr>
      <td><p>COM4</p>
      </td>
      <td><p align="right">2E8<sub>16</sub></p>
      </td>
      <td><p>/dev/ttyS2</p>
      </td>
    </tr>
  </tbody>
</table>
]]>
</html>
</table>

Denominazione della porta seriale su i386 nei sistemi Dos

Risorse

File di dispositivo nei sistemi GNU/Linux

Annotazioni

IRQ

I/O

COM1

4

3F816

/dev/ttyS0

La prima e la terza porta seriale condividono lo stesso IRQ.

COM3

3E816

/dev/ttyS2

COM2

3

2F816

/dev/ttyS0

La seconda e la quarta porta seriale condividono lo stesso IRQ.

COM4

2E816

/dev/ttyS2

Tabella 170.20. Incorporazione di codice HTML per rappresentare una tabella complessa.

Si osservi nell'esempio l'uso dell'attributo width. Precisamente, l'elemento html consente l'uso degli attributi width e height per stabilire le dimensioni dell'oggetto HTML importato nella composizione stampata. In questo caso, è stata specificata la larghezza, corrispondente allo spazio orizzontale a disposizione, in modo che l'altezza venga adattata in modo relativo, automaticamente.

Elemento o attributo Apertura Chiusura Contenuto Descrizione
html #PCDATA Codice HTML letterale.
     width -- -- Attributo Larghezza nella composizione stampata.
     height -- -- Attributo Altezza nella composizione stampata.
tex #PCDATA Codice TeX o LaTeX letterale.
ifhtml %block; Blocco condizionato alla composizione in HTML.
iftex %block; Blocco condizionato alla composizione in TeX.

Tabella 170.21. Inserimento letterale di codice TeX e HTML; inserimento condizionato in base al tipo di composizione.

Si rammenti che mentre quanto contenuto nell'elemento html appare sia nella composizione per la stampa, sia nella composizione HTML, l'elemento tex genera un risultato utile solo nella composizione per la stampa. Se si devono rappresentare formule matematiche non troppo complesse, si può valutare la possibilità di rappresentarle in HTML, in modo da garantire la compatibilità nei due formati, anche se rimane il problema della trasformazione in testo che non può avvenire nel modo corretto.

170.8   Definizione alternativa della suddivisione del documento

Alml è pensato per la realizzazione di documenti di grandi dimensioni. In questo senso, la sua struttura normale è quella di un libro, articolato in capitoli che si possono raggruppare in parti e tomi. Eventualmente, se questa struttura va definita attraverso termini differenti, si possono sostituire le parole «capitolo», «parte» e «tomo», con altre più appropriate.

Per questo si usano gli elementi chapterdefinition, partdefinition e tomedefinition, all'interno delle informazioni amministrative. L'esempio seguente dovrebbe permettere di comprendere il problema; per la precisione si tratta di una rivista telematica ipotetica:

<head>
    <admin>
        <description>Rivista di informatica libera</description>
        <keywords>informatica libera, software libero</keywords>
        <chapterdefinition>articolo</chapterdefinition>
        <partdefinition>numero</partdefinition>
        <tomedefinition>anno</tomedefinition>
    </admin>
    <title>RIL, rivista di informatica libera</title>
    <author>Pinco Pallino &lt;pinco.pallino@brot.dg&gt;</author>
    <date>2011.11.11</date>
    <legal>
        <p>Copyright &copy; Pinco Pallino, &lt;pinco.pallino@brot.dg&gt;</p>
    </legal>
    <maincontents levels="2">Table of contents</maincontents>
</head>

Si può osservare che le parole «articolo», «numero» e «anno», sono state inserite usando lettere minuscole e in forma singolare. Ciò è necessario, perché l'iniziale maiuscola viene ottenuta automaticamente quando opportuno; inoltre, questi termini vengono usati sempre quando si fa riferimento a un solo oggetto.

La numerazione dei tomi, delle parti e dei capitoli è indipendente, per cui non ci si può aspettare che al cambio di un tomo o di una parte, i capitoli riprendano la numerazione a partire da uno.

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

1) Attualmente viene individuato solo il codice it, mentre in tutti gli altri casi il testo viene trattato come se fosse in lingua inglese, tuttavia se saranno fornite le indicazioni necessarie, si potrà aggiungere la gestione per altre lingue.

2) Qui si intendono sezioni a qualsiasi livello, compresi i capitoli, le parti e i tomi.

3) Il segno meno, va indicato con il trattino normale.

4) Un punto tipografico corrisponde a 1/72 di pollice.

5) Se nella sezione che non si può modificare è scritto chiaramente come stanno le cose al riguardo, non serve alcun elenco di tali sezioni.


Dovrebbe essere possibile fare riferimento a questa pagina anche con il nome il_documento_secondo_alml.html

[successivo] [precedente] [inizio] [fine] [indice generale] [violazione GPL] [licenze] [indice analitico]