Il documento secondo Alml

Il DTD di Alml è organizzato per gestire documenti molto grandi, che possono essere suddivisi in volumi, parti e capitoli. Tuttavia, la suddivisione in volumi o in parti resta facoltativa, mentre la divisione in capitoli è obbligatoria.

Quando devono essere indicate delle dimensioni che prevedono la specificazione dell'unità di misura, si usano le sigle elencate nella tabella u93.1.

Tabella u93.1. Sigle delle unità di misura utilizzabili con Alml.

Sigla Unità di misura corrispondente
pt
Punti tipografici corrispondenti a 1/72,27 di pollice.
bp
Punti tipografici corrispondenti a 1/72 di pollice (big point).
pc
Pica corrispondenti a 1/6 di pollice.
in
Pollici.
cm
Centimetri.
mm
Millimetri.

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

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 volumi; 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.

Figura u93.2. Schema ad albero degli elementi principali di un documento Alml.

alml [lang="lingua"] [spacing="normal|french|uniform"]
  |--head
  |--[intro]
  |--body
  |--[appendix]
  `--[index]

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 (tabella 13.4), ma se le informazioni su un certo linguaggio non sono disponibili, si applicano comunque le convenzioni inglesi.

L'attributo spacing permette di definire il modo in cui vengono gestiti gli spazi alla fine dei periodi (dopo il punto fermo). Assegnando la parola chiave normal, si ottiene la spaziatura normale della convenzione inglese, in cui lo spazio dopo un punto ha una larghezza 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">

La figura u93.4 e la tabella u93.5 mostrano 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.

Figura u93.4. Schema ad albero degli elementi di un documento Alml, con il dettaglio dell'intestazione.

alml [lang="lingua"] [spacing="normal|french|uniform"]
  |--head
  |    |--[admin]
  |    |    |--[description]
  |    |    |--[keywords]
  |    |    |--[htmlmeta name="nome" lang="linguaggio"]...
  |    |    |--[printedfontsize type="contesto"]...
  |    |    |--[printedpagesize type="contesto"]...
  |    |    |--[chapterdefinition]
  |    |    |--[partdefinition]
  |    |    `--[tomedefinition]
  |    |--title
  |    |--[shorttitle]
  |    |--[subtitle]...
  |    |--author...
  |    |--date
  |    |--[edition]
  |    |--[version]
  |    |--[frontcovertop]
  |    |--[abstract]
  |    |--[frontcoverbottom]
  |    |--[backcover]
  |    |--[textbeforelegal]
  |    |--legal
  |    |--[dedications]
  |    |--[textafterdedications]
  |    `--[maincontents levels="n" nopages="true|false"]
  |--[intro]
  |--body
  |--[appendix]
  `--[index]

Tabella u93.5. Elementi SGML dalla copertina all'indice generale.

Elemento Descrizione
alml [lang="..."] [spacing="..."]
Contenitore del documento. L'attributo lang può contenere la sigla del linguaggio espressa secondo lo standard ISO 639. L'attributo spacing può contenere una parola chiave, a scelta tra: normal, french e uniform.
head
Intestazione del documento.
admin
Informazioni amministrative.
description
Descrizione in breve del documento.
keywords
Elenco di parole chiave.
htmlmeta name="..." lang="..."
Contenuto di un elemento HTML META. Gli attributi name e lang vanno usati nello stesso modo previsto per l'elemento META di HTML.
chapterdefinition
Definizione alternativa del capitolo.
partdefinition
Definizione alternativa della parte.
tomedefinition
Definizione alternativa del volume.
printedfontsize type="..."
Corpo del carattere in punti. Il carattere a cui si fa riferimento è quello indicato nell'attributo type.
printedpagesize type="..."
Dimensione di quanto indicato nell'attributo type, che in generale si riferisce alla definizione dei margini e della giustezza.
title
Titolo del documento.
shorttitle
Sigla o abbreviazione del titolo dell'opera; è utile nella composizione HTML.
subtitle
Sottotitolo.
author
Autore.
date
Data del lavoro.
edition
Edizione, da usare se questa è diversa dalla data.
version
Versione, se la si vuole indicare in modo diverso dalla data di edizione.
frontcovertop
Blocco che precede il titolo.
abstract
Descrizione del contenuto. Si osservi che attualmente questa informazione non viene utilizzata in fase di composizione.
frontcoverbottom
Testo aggiuntivo di copertina, da mostrare dopo il titolo e dopo le altre indicazioni standard.
backcover
Contenuto della copertina finale.
textbeforelegal
Testo prima delle informazioni legali.
legal
Informazioni legali (copyright, condizioni, ecc.).
dedications
Pagina delle dediche.
textafterdedications
Testo successivo alle dediche.
maincontents [levels="..."]
[nopages="..."]
Inserimento dell'indice generale, specificando il titolo da dare a tale indice. L'attributo levels specifica il livello di dettaglio dell'indice. L'attributo nopages specifica se si vogliano vedere i numeri di pagina come riferimento nella composizione stampata; può assumere i valori true o false.

Si può osservare che tutte le informazioni sono contenute 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 (sezione u0.5).

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

L'elemento printedpagesize consente di definire I margini e la giustezza per la composizione stampata, in base al contesto indicato dall'attributo type.

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. Tuttavia, questa informazione non viene usata in fase di composizione.

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

Gli elementi date, edition e version, servono per indicare una data, un'edizione e una versione del lavoro. In generale è sufficiente l'uso dell'elemento data.

L'elemento frontcovertop permette l'inserzione di blocchi prima del titolo; così, l'elemento frontcoverbottom consente di fare la stessa cosa dopo il titolo e le altre indicazioni standard. L'elemento backcover permette di definire il contenuto della 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 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. All'interno dell'elemento si inserisce il titolo da dare all'indice.

Esempio quasi completo per la compilazione dell'intestazione

Viene mostrato qui un esempio quasi completo dell'uso degli elementi che si inseriscono all'interno di head (il file in questione dovrebbe essere disponibile presso allegati/a2/alml-esempio-intestazione.sgml). Di proposito, il contenuto del documento è completamente mancante, nel senso che l'elemento body è vuoto.

<!DOCTYPE ALML PUBLIC "-//D.G.//DTD Alml//EN">
<alml lang="it" spacing="uniform">
<head>
    <admin>
        <description>Compilazione di un'intestazione con Alml</description>
        <keywords>Alml, SGML, composizione</keywords>
        <printedfontsize type="title">20mm</printedfontsize>
        <printedfontsize type="subtitle">8mm</printedfontsize>
        <printedfontsize type="author">8mm</printedfontsize>
        <printedfontsize type="edition">8mm</printedfontsize>
        <printedfontsize type="normal">7mm</printedfontsize>
    </admin>
    <title>Intestazione</title>
    <shorttitle>int</shorttitle>
    <subtitle>Come iniziare con Alml</subtitle>
    <author>Pinco Pallino</author>
    <date>1111.11.11</date>
    <edition>1212.12.12</edition>
    <version>1.1</version>
    <frontcovertop>
        <p>i libri di Alml</p>
    </frontcovertop>
    <abstract>
        <p>La compilazione delle informazioni di un documento
        è sempre complicato all'inizio dello studio di un sistema
        SGML o XML di composizione.</p>
        <p>Questo libro, attraverso un esempio pratico, spiega come
        utilizzare proprio gli elementi dell'intestazione.</p>
    </abstract>
    <frontcoverbottom>
        <p>!"£$%&amp;/()=?^*+°§</p>
        <p>!"£$%&amp;/()=?^*+°§</p>
        <p>!"£$%&amp;/()=?^*+°§</p>
        <p>!"£$%&amp;/()=?^*+°§</p>
    </frontcoverbottom>
    <backcover>
        <p>Questo libro privo di contenuti, attraverso un solo esempio
        pratico, dimostra come utilizzare gli elementi dell'intestazione
        di Alml.</p>
    </backcover>
    <textbeforelegal>
        <p>Pinco Pallino è laureato in scienza del vuoto mentale
        e insegna nullafacenza applicata.</p>
    </textbeforelegal>
    <legal>
        <p>Copyright &copy; Pinco Pallino, &lt;pinco.pallino@brot.dg&gt;</p>
        <p>Permission is granted to copy, distribute and/or modify this
        document under the terms of the GNU Free Documentation License,
        Version 1.1 or any later version published by the Free Software
        Foundation; with no Invariant Sections, with no Front-Cover
        Texts, and with no Back-Cover Texts. A copy of the license is
        included in the section entitled "GNU Free Documentation
        License".</p>
    </legal>
    <dedications>
        <p>Alla mia bella Gigia, con tanto amore.</p>
    </dedications>
    <textafterdedications>
        <p>Sette, sei, cinque, quattro, tre, due, uno,... via!</p>
    </textafterdedications>
    <maincontents levels="2">Indice generale</maincontents>
</head>
<body>
</body>
</alml>

Nelle figure successive viene mostrato il risultato della composizione in un formato PostScript o PDF, in modo indifferente. Si suppone che il file sorgente sia stato chiamato head.sgml e che sia stato usato uno dei due comandi seguenti:

alml --ps alml-esempio-intestazione.sgml[Invio]

alml --pdf alml-esempio-intestazione.sgml[Invio]

Il risultato che si dovrebbe ottenere, in formato PDF, può essere prelevato presso allegati/a2/alml-esempio-intestazione.pdf (viene distribuito assieme all'edizione HTML dell'opera).

Figura u93.9. La copertina e la pagina del colofone (che appare subito dopo la copertina). Nella pagina della copertina si può osservare che: in alto, prima del titolo, viene messo il contenuto di frontcovertop; disponendo della versione dell'edizione, appare il contenuto degli elementi version e edition; nella parte sottostante appare il contenuto dell'elemento frontcoverbottom. Nella pagina del colofone si vede in alto il contenuto di textbeforelegal e in basso il contenuto di legal.

alml head copertina alml head copyright

Figura u93.10. La pagina delle dediche, ovvero la pagina associata all'elemento dedications, assieme alla pagina successiva, corrispondente al contenuto dell'elemento textafterdedications.

alml head dedica alml head postdedica

Figura u93.11. La quarta di copertina (copertina posteriore), corrispondente all'elemento backcover.

alml head retrocopertina

Margini e giustezza nella composizione stampata

È possibile definire i margini e la giustezza (la larghezza del testo) della composizione stampata, senza dover intervenire modificando lo stile TeX. Si utilizza per questo l'elemento printedpagesize, all'interno dell'elemento admin, nell'intestazione del documento, specificando il contesto con l'attributo type. Si osservi l'esempio in cui si mostrano tutti i valori disponibili per l'attributo type:

<head>
    <admin>
        ...
        <printedpagesize type="topmargin">2.5cm</printedpagesize>
        <printedpagesize type="bottommargin">3.0cm</printedpagesize>
        <printedpagesize type="internalmargin">3.5cm</printedpagesize>
        <printedpagesize type="bodywidth">15cm</printedpagesize>
        ...
    </admin>
    ...
</head>

Il tipo topmargin è il margine superiore, fino alla base del testo normale (la riga di intestazione viene collocata automaticamente); il tipo bottommargin è il margine inferiore; il tipo internalmargin è il margine sinistro per le pagine destre e il margine destro per le pagine sinistre; il tipo bodywidth è la giustezza, ovvero la larghezza della colonna in cui scorre effettivamente il testo.

Tabella u93.13. Valori dell'attributo type dell'elemento printedpagesize.

Valore Contesto a cui si fa riferimento
topmargin
Margine superiore.
bottommargin
Margine inferiore.
internalmargin
Margine interno.
bodywidth
Giustezza.

Il margine esterno non viene indicato, perché si preferisce indicare la giustezza, essendo un valore che è meglio non vari automaticamente, dal momento che da questo dipendono anche le dimensioni che si assegnano ad altri componenti contenuti nel testo.

Figura u93.14. Valori dell'attributo type dell'elemento printedpagesize.

valori dell'attributo type dell'elemento printedpagesize

Il formato della carta viene definito al di fuori del sorgente SGML, attraverso le opzioni di Alml. Ciò permette di produrre composizioni differenti a seconda del tipo di carta disponibile. Tuttavia, è evidente che le dimensioni adottate per la carta devono essere compatibili con i margini e la giustezza richiesti nel sorgente SGML.

Corpo del carattere nella composizione stampata

È possibile definire il corpo 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">4mm</printedfontsize>
        <printedfontsize type="table">3.5mm</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.

Tabella u93.16. Valori dell'attributo type dell'elemento printedfontsize.

Valore Carattere a cui si fa riferimento
title
Titolo dell'opera che appare in copertina.
subtitle
Sottotitolo che appare in copertina.
author
Autori che appaiono in copertina.
edition
Data, edizione e versione che appaiono in copertina.
tomeheading
Titolo dei volumi nella loro pagina iniziale.
h0
Titolo delle parti nella loro pagina iniziale.
h1
Titolo dei capitoli.
h2
Titolo delle sezioni di primo livello.
h3
Titolo delle sottosezioni.
h4
Titolo delle sotto-sottosezioni.
normal
Testo normale.
table
Testo delle tabelle.
object
Testo interno agli elementi object.

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(1) 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 poi si ripete la verifica SGML.

Figura u93.17. Schema ad albero semplificato degli elementi di un documento Alml, dove di mostra la suddivisione dei contenuti.

alml [lang="lingua"] [spacing="normal|french|uniform"]
  |--head
  |--[intro]
  |    `--capitolo...
  |--body
  |    `--{volume...|parte...|capitolo...}
  |--[appendix]
  |    `--capitolo...
  `--[index]
       `--capitolo...

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.

Corpo

Il corpo vero e proprio del documento è contenuto nell'elemento body, il quale si può articolare in volumi, parti o capitoli. Sta all'autore scegliere quale livello di suddivisione superiore adottare. È evidente che se si usa una suddivisione in volumi, 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 volume può contenere solo capitoli, senza parti, quando per qualche ragione ciò è necessario.

Volumi, parti, capitoli e sezioni inferiori sono delimitate materialmente attraverso la dichiarazione del titolo relativo, come avviene in HTML. Le tabelle e gli schemi successivi descrivono gli elementi relativi.

Figura u93.18. Schema di un volume.

volume
  |--tomeheading [id="ancora"] [lang="lingua"] [bookmark="segnalibro"]
  |    `--testo_lineare
  |--[blocco_generico]...
  `--{parte...|capitolo...}

Tabella u93.19. Dichiarazione dei titoli dei volumi, con la possibilità di aggiungere un indice del contenuto.

Elemento Descrizione
tomeheading [id="ancora"] [lang="..."]
[bookmark="..."]
Titolo del volume. L'attributo id consente di specificare un'ancora di riferimento; l'attributo lang consente di specificare la lingua del volume; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF.
tomecontents [levels="livelli"]
[nopages="true|false"]
Elemento vuoto per ottenere l'inserimento dell'indice generale del volume. L'attributo levels specifica il livello di dettaglio dell'indice; l'attributo nopages consente di non mostrare i numeri di pagina nella composizione per la stampa.

Figura u93.20. Schema di una parte.

parte
  |--h0 [id="ancora"] [lang="lingua"] [bookmark="segnalibro"]
  |    `--testo_lineare
  |--[blocco_generico]...
  `--capitolo...

Tabella u93.21. Dichiarazione dei titoli delle parti, con la possibilità di aggiungere un indice del contenuto.

Elemento Descrizione
h0 [id="ancora"] [lang="..."] [bookmark="..."]
Titolo della parte. L'attributo id consente di specificare un'ancora di riferimento; l'attributo lang consente di specificare la lingua della parte; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF.
partcontents [levels="livelli"]
[nopages="true|false"]
Elemento vuoto per ottenere l'inserimento dell'indice generale della parte. L'attributo levels specifica il livello di dettaglio dell'indice; l'attributo nopages consente di non mostrare i numeri di pagina nella composizione per la stampa.

Figura u93.22. Schema di un capitolo e della sua suddivisione inferiore.

capitolo
  |--h1 [id="ancora"] [lang="lingua"] [bookmark="segnalibro"]
  |    `--testo_lineare
  |--[blocco_generico]...
  |--[sezione...]
  |    |--h2 [id="ancora"] [bookmark="segnalibro"]
  |    |    `--testo_lineare
  |    |--[blocco_generico]...
  |    `--[sottosezione...]
  |         |--h3 [id="ancora"] [bookmark="segnalibro"]
  |         |    `--testo_lineare
  |         |--[blocco_generico]...
  |         `--[sotto_sottosezione...]
  |              |--h4 [id="ancora"] [bookmark="segnalibro"]
  |              |    `--testo_lineare
  |              `--[blocco_generico]...
  `--[endofchapter]

Tabella u93.23. Elementi relativi alla definizione di un capitolo.

Elemento Descrizione
h1 [id="ancora"] [lang="..."] [bookmark="..."]
Titolo del capitolo. L'attributo id consente di specificare un'ancora di riferimento; l'attributo lang consente di specificare la lingua del capitolo; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF.
chaptercontents [levels="livelli"]
[nopages="true|false"]
Elemento vuoto per ottenere l'inserimento dell'indice generale del capitolo. L'attributo levels specifica il livello di dettaglio dell'indice; l'attributo nopages consente di non mostrare i numeri di pagina nella composizione per la stampa.
h2 [id="ancora"] [bookmark="..."]
Titolo della sezione. L'attributo id consente di specificare un'ancora di riferimento; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF.
h3 [id="ancora"] [bookmark="..."]
Titolo della sottosezione. L'attributo id consente di specificare un'ancora di riferimento; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF.
h4 [id="ancora"] [bookmark="..."]
Titolo della sotto-sottosezione. L'attributo id consente di specificare un'ancora di riferimento; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF.
extramaincontents [levels="livelli"]
[nopages="true|false"]
Elemento vuoto per ottenere l'inserimento di un indice generale complessivo. L'attributo levels specifica il livello di dettaglio dell'indice; l'attributo nopages consente di non mostrare i numeri di pagina nella composizione per la stampa.
endofchapter
Testo lineare da inserire, eventualmente, alla fine di un capitolo, con delle note particolari.

Nella parte iniziale delle classificazioni principali (volumi, 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.

L'elemento endofchapter avrebbe lo scopo di consentire l'inserimento di una riga di informazioni alla fine del capitolo; precisamente, nella composizione per la stampa, alla base dell'ultima pagina del capitolo. Purtroppo, però, in presenza di riquadri fluttuanti può succedere di vedere il contenuto dell'elemento endofchapter alla fine di una pagina, mentre nelle successive vengono collocati i riquadri fluttuanti rimasti in sospeso; inoltre, può capitare di avere una pagina completamente vuota, ma contenente soltanto quanto inserito nell'elemento endofchapter.

Appendici

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

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. Viene descritto meglio in seguito l'uso di questo elemento, perché Alml è in grado di gestire più indici analitici differenti.

Suddivisioni speciali

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

Figura u93.24. Schema di un capitolo speciale per diapositive.

capitolo
  |--slideh1 [id="ancora"] [lang="lingua"] [bookmark="segnalibro"]
  |    `--testo_lineare
  |--[blocco_generico]...
  `--[endofchapter]

Figura u93.25. Schema di un capitolo speciale per schede informative generiche.

capitolo
  |--sheeth1 [id="ancora"] [lang="lingua"] [bookmark="segnalibro"]
  |    `--testo_lineare
  |--[blocco_generico]...
  `--[endofchapter]

Figura u93.26. Schema di un capitolo contenente domande e risposte.

capitolo
  |--h1 [id="ancora"] [lang="lingua"] [bookmark="segnalibro"]
  |    `--testo_lineare
  |--[blocco_generico]...
  |--[sezione...]
  |    |--faqh2 [id="ancora"] [bookmark="segnalibro"]
  |    |    `--testo_lineare
  |    |--qh2 [id="ancora"] [bookmark="segnalibro"]
  |    |    `--testo_lineare
  |    |--[blocco_generico]...
  |    `--[sottosezione...]
  |         |--faqh3 [id="ancora"] [bookmark="segnalibro"]
  |         |    `--testo_lineare
  |         |--qh3 [id="ancora"] [bookmark="segnalibro"]
  |         |    `--testo_lineare
  |         `--[blocco_generico]...
  `--[endofchapter]

Figura u93.27. Schema parziale di un capitolo contenente un questionario.

capitolo
  |--testh1 [id="ancora"] [lang="lingua"] [bookmark="segnalibro"]
  |    |    [testtime="tempo"] [testtimepenalty="penalità"]
  |    |    [testwindow="0|0"] [testanswaretime="tempo"]
  |    |    [testmaxscore="punteggio_massimo"]
  |    |    [testcodehide="0|1|2|3"]
  |    `--testo_lineare
  |--dati_descrittivi...
  |    |--[blocco_generico]
  |    `--[testinfo]
  |--domanda...
  |    |--[domanda_risposta_singola]
  |    |    |--testlistquestion
  |    |    |--[blocco_generico]...
  |    |    `--testlist...
  |    |--[domanda_risposta_multipla]
  |    |    |--testmultiquestion
  |    |    |--[blocco_generico]...
  |    |    `--testmulti...
  |    `--[domanda_risposta_testuale]
  |         |--testtextquestion
  |         |--[blocco_generico]...
  |         `--testtext...
  |--testsend
  `--[endofchapter]

Tabella u93.28. Dichiarazione dei titoli di capitoli e di sezioni speciali.

Elemento Descrizione
slideh1 [id="ancora"] [lang="..."] [bookmark="..."]
Titolo della diapositiva. L'attributo id consente di specificare un'ancora di riferimento; l'attributo lang consente di specificare la lingua del capitolo; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF.
sheeth1 [id="ancora"] [lang="..."] [bookmark="..."]
Titolo della scheda sintetica. L'attributo id consente di specificare un'ancora di riferimento; l'attributo lang consente di specificare la lingua del capitolo; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF.
testh1 [id="ancora"] [lang="..."] [bookmark="..."]
       [testtime="..."] [testtimepenalty="..."]
       [testwindow="0|1"]
       [testanswaretime="tempo"]
       [testmaxscore="massimo"]       [testcodehide="n"]
Titolo del questionario. L'attributo id consente di specificare un'ancora di riferimento; l'attributo lang consente di specificare la lingua del capitolo; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF; l'attributo testtime consente di indicare il tempo massimo in secondi; testtimepenalty permette di specificare la penalità da sottrarre al punteggio per ogni secondo di ritardo; testwindow consente di far eseguire la verifica in una finestra priva di menù e di icone; testanswaretime consente di stabilire il tempo a disposizione per la stampa del risultato; testmaxscore serve a indicare ad Alml qual è il punteggio massimo che può produrre la verifica; testmaxscore serve a indicare ad Alml qual è il punteggio massimo che può produrre la verifica; testcodehide consente di rendere difficilmente interpretabile il codice HTML e JavaScript, attribuendo un valore intero maggiore di zero.
faqh2 [id="ancora"] [lang="..."]
Titolo del gruppo di domande e risposte. L'attributo id consente di specificare un'ancora di riferimento; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF.
faqh3 [id="ancora"] [lang="..."]
Domanda a cui segue una risposta. L'attributo id consente di specificare un'ancora di riferimento; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF.
qh2 [id="ancora"] [lang="..."]
Titolo di un gruppo di domande. L'attributo id consente di specificare un'ancora di riferimento; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF.
qh3 [id="ancora"] [lang="..."]
Domanda. L'attributo id consente di specificare un'ancora di riferimento; l'attributo bookmark consente di specificare un segnalibro alternativo per la composizione in formato PDF.

Gli elementi slideh1, sheeth1 e testh1 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. Si osservi che, pur non avendo modo di controllare la dimensione del contenuto, è bene che ogni diapositiva e ogni scheda occupi una sola pagina nella composizione per la stampa, mentre nel caso di un questionario di verifica, non esiste questo problema estetico.

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 qh2 è simile a faqh2 e va usato quando le domande che raggruppa non hanno propriamente il senso di una «faq».

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. L'elemento qh3 è simile a faqh3 e va usato quando la domanda non ha il senso di una «faq».

Nel capitolo u105 è descritto meglio come realizzare delle diapositive, mentre nel capitolo u101 è descritto come realizzare un questionario.

Documento multilingua

L'attributo lang viene indicato normalmente nell'elemento alml per definire il linguaggio complessivo del lavoro, ma il linguaggio può essere modificato nell'ambito dei volumi, delle parti o dei capitoli. Per questo, l'attributo lang può essere usato anche negli elementi tomeheading, h0 e h1, con lo scopo di fare riferimento al volume, alla parte o al capitolo a cui questi titoli si riferiscono. Pertanto, si osservi che l'attributo lang attribuisce il valore della scelta linguistica a tutto il volume, alla parte o al capitolo relativo, senza limitarsi all'ambito dell'elemento che ne delimita il titolo.

Un volume, una parte o un capitolo che non abbiano la definizione esplicita di un linguaggio, ereditano la definizione del livello gerarchicamente precedente.

La motivazione più importante per la quale è stato introdotto questo attributo nella dichiarazione dei volumi, 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 (tabella 13.4). 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 volume, della parte o del capitolo viene adattata alla lingua, solo se questa non è stata modificata attraverso gli elementi tomedefinition, partdefinition e chapterdefinition, descritti più avanti in questo capitolo.

Cambiamento temporaneo del linguaggio

Quando si inserisce un testo di un linguaggio che non appartiene all'Europa occidentale, può essere necessario selezionare il linguaggio per ottenere una composizione corretta. Pertanto, oltre alla selezione del linguaggio all'inizio dei volumi, delle parti e dei capitoli, è possibile modificare il linguaggio di un blocco di testo o di una porzione lineare, rispettivamente con gli elementi div e span. Gli esempi seguenti mostrano l'uso di entrambi per ottenere la composizione per la stampa di alcune lettere in cirillico:

<div lang="ru">

    <p>&acy; &Acy; &bcy; &Bcy; &vcy; &Vcy; &gcy; &Gcy; &dcy; &Dcy;
    &iecy; &IEcy; &iocy; &IOcy; &zhcy; &ZHcy; &zcy; &Zcy;...</p>

</div>

а А б Б в В г Г д Д е Е ё Ё ж Ж з З...

<p>Bla bla bla: <span lang="ru">&acy; &Acy; &bcy; &Bcy; &vcy; &Vcy;
&gcy; &Gcy; &dcy; &Dcy; &iecy; &IEcy; &iocy; &IOcy; &zhcy; &ZHcy; &zcy;
&Zcy;...</span> bla bla bla.</p>

Bla bla bla: а А б Б в В г Г д Д е Е ё Ё ж Ж з З... bla bla bla.

Può succedere che il cambiamento di linguaggio crei «confusione» a LaTeX, che viene usato per ottenere la composizione da stampare. Si possono osservare degli errori inspiegabili nel file .log generato durante il procedimento di composizione, in corrispondenza di vocali accentate:

! Missing \endcsname inserted.
<to be read again> 
                   \global 
l.16570 cui corrisponde l'entit\`a
                                     parametrica
The control sequence marked <to be read again> should
not appear between \csname and \endcsname.

Se questo avviene successivamente a un testo scritto con un linguaggio particolare (proprio come si verifica in questa spiegazione), si può tentare di dichiarare nuovamente il linguaggio con un elemento div, oppure span:

<p>Bla bla bla: <span lang="ru">&acy; &Acy; &bcy; &Bcy; &vcy; &Vcy;
&gcy; &Gcy; &dcy; &Dcy; &iecy; &IEcy; &iocy; &IOcy; &zhcy; &ZHcy; &zcy;
&Zcy;...</span> bla bla bla.</p>

<div lang="it">

    <p>Bla bla bla... perché, poiché, c'è,... bla bla bla.</p>

</div>

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 volumi. Queste suddivisioni prevedono una denominazione attribuita automaticamente, corrispondente a «capitolo», «parte» e «volume»; eventualmente, se tale struttura va definita invece attraverso termini differenti, si possono sostituire le definizioni delle suddivisioni 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 volumi, delle parti e dei capitoli è indipendente, per cui non ci si può aspettare che al cambio di un volume o di una parte, i capitoli riprendano la numerazione a partire da uno.


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

«a2» 2013.11.11 --- Copyright © Daniele Giacomini -- appunti2@gmail.com http://informaticalibera.net