Capitolo 275.   ALtools

ALdoc è il DTD utilizzato per la realizzazione di questo documento, Appunti di informatica libera, e ALtools è la raccolta di programmi (script di shell e programmi Perl) necessari a controllare la sua conversione nei formati finali. In pratica, ALdoc e ALtools si sono sviluppati in base alle esigenze particolari di questo documento.

⁽¹⁾

Anche se ALtools continua a essere uno strumento piuttosto rudimentale, è diventato abbastanza indipendente da Appunti di informatica libera, e potrebbe dimostrarsi utile anche per lo sviluppo di altra documentazione.

ALtools si avvale di altri programmi per l'analisi SGML e per la generazione di alcuni formati finali. In particolare, è necessario disporre di nsgmls e sgmlspl, che fanno parte generalmente dei pacchetti SP e SGMLSpm (anche se la propria distribuzione GNU/Linux potrebbe nominarli in modo differente); inoltre è fondamentale la presenza di LaTeX e di ImageMagick. La tabella 275.1 riepiloga gli applicativi da cui dipende il buon funzionamento di ALtools.

Tabella 275.1. Applicativi da cui dipende ALtools.

ALtools viene fornito solo attraverso pacchetti tradizionali di tipo tar+gzip, perché in generale non dovrebbe essere necessaria alcuna preparazione per la sua installazione e inoltre è obbligatoria la collocazione a partire dalla directory /opt/ALtools/. È anche da considerare il fatto che ALtools è completamente indipendente dalla gestione SGML che potrebbe essere già stata predisposta nel proprio sistema. L'installazione di ALtools è comunque molto semplice; supponendo di avere ottenuto l'archivio ALtools-2000.04.12, si procede nel modo seguente:

# cd /

# tar xzvf ALtools-2000.04.12.tar.gz

Si ottiene la directory /opt/ALtools/ che si articola ulteriormente. Perché le cose funzionino è necessario aggiungere /opt/ALtools/bin/ ai percorsi di avvio dei programmi (la variabile di ambiente PATH). In seguito si potrà disinstallare ALtools cancellando semplicemente questa directory, senza che ciò lasci conseguenze al sistema di tracciamento dei pacchetti della propria distribuzione GNU/Linux.

275.1   Struttura di un progetto di documentazione

Il documento «ideale» realizzato con il DTD ALdoc e composto con ALtools, è molto complesso, di conseguenza richiede la predisposizione di un ambiente adatto, piuttosto articolato. In generale conviene iniziare dall'esempio che accompagna ALtools stesso e si trova a partire dalla directory /opt/ALtools/doc/esempio/. Supponendo di volere preparare la directory ~/lavoro/ per un proprio progetto di documentazione, si può copiare l'esempio di partenza e successivamente si modificherà quello che si desidera.

$ cp -dpR /opt/ALtools/doc/esempio/* ~/lavoro/

275.1.1   File e directory

Il listato seguente mostra la struttura di directory che si deve articolare a partire da quella destinata al progetto di documentazione.

.
|-- citazioni/
|   `-- *.sgml
|
|-- contributi/
|   `-- *.sgml
|
|-- derivazioni/
|   |-- principale/
|   |   |-- formalita/
|   |   |   |-- COPY.sgml
|   |   |   |-- COPYPARTE.sgml
|   |   |   |-- COPYTOMO.sgml
|   |   |   |-- DEDICA.sgml
|   |   |   |-- LICENZA.sgml
|   |   |   |-- MIRROR.sgml
|   |   |   `-- PRESENTAZIONEAUTORE.sgml
|   |   |-- stile-html.sh
|   |   |-- stile-tex-pdf-bozza.sty
|   |   |-- stile-tex-pdf.sty
|   |   |-- stile-tex-ps-bozza.sty
|   |   |-- stile-tex-ps-continuo.sty
|   |   |-- stile-tex-ps-lungo.sty
|   |   `-- stile-tex-ps.sty
|   |-- <altra-derivazione>/
|   |   |
|   |   ...
|   |
|   ...
|
|-- figure/
|   `-- *.png
|
|-- formalita/ (vuota)
|
|-- inclusi/
|   `-- *.sgml
|
|-- ortografia/
|   |-- errorieccezioni
|   |-- minimo.hash
|   |-- particolari
|   `-- vocabolario
|
|-- Makefile
|
`-- xxx-00001.sgml

Vengono descritti brevemente i file e le directory.

• citazioni/

  Questa directory serve a contenere una serie di file SGML che costituiscono dei pezzi da considerare come citazioni, ovvero del testo che non deve essere alterato e per sicurezza viene separato dal sorgente principale. L'esempio tipico di una tale citazione è la riproduzione di una licenza, come nel caso della GNU-GPL che appare in molti testi come appendice.

• contributi/

  Se si tratta di un documento a cui contribuiscono in parte anche altre persone, in questa directory vanno collocati i file SGML che rappresentano i capitoli scritti da loro.

• figure/

  Questa directory serve a contenere i file delle illustrazioni, che devono essere in formato PNG. Se le figure di cui si dispone sono in altri formati, occorre convertirle in PNG.

• formalità/

  Si tratta di una directory vuota, che viene riempita dinamicamente dal programma di composizione, in base al tipo di derivazione che si intende compilare (verrà chiarito in occasione della descrizione della directory derivazioni/).

• inclusi/

  Questa directory è fatta per contenere delle parti del documento principale, in SGML, che per qualche motivo si è ritenuto di voler tenere a parte. Se si intende gestire un file SGML principale monolitico, non c'è bisogno di mettere alcunché in questa directory.

• derivazioni/

  Il sistema di composizione è organizzato per gestire diverse derivazioni della stessa opera, attraverso un meccanismo simile a quello del preprocessore del linguaggio C. A partire da questa directory si articolano le particolarità delle varie derivazioni, tenendo presente che, come minimo, ci deve essere quella denominata «principale».

  • derivazioni/derivazione/

    Ogni sottodirectory contiene le particolarità della derivazione nominata nello stesso modo (preferibilmente utilizzando solo lettere minuscole). Ciò che si trova a partire da questo punto viene copiato dal sistema di composizione, di volta in volta, nella directory principale del progetto di documentazione.

    • derivazioni/derivazione/formalita/

      I file che contiene questa directory servono a definire le solite cose formali, come il copyright, la licenza con cui viene rilasciato il documento, la dedica e altre informazioni. L'utilità di tenerli separati dal file principale sta nel fatto che questi possono essere inseriti in più punti dell'opera, senza rischiare di omettere qualcosa o di sbagliare in qualche modo.

      Come si intende, i file contenuti in questa directory vengono copiati nella directory formalità/, che come già indicato, inizialmente è vuota per questo motivo.

    I file che si vedono elencati nel listato riepilogativo che è stato mostrato, rappresentano in parte dei nomi prestabiliti; per il resto si tratta di convenzioni derivate dall'opera Appunti di informatica libera, che però conviene mantenere.

• ortografia/

  Questa directory serve a contenere la configurazione del sistema di controllo ortografico specifico per il documento che si scrive:

  • ortografia/errorieccezioni ---> ../.textchk.rules

    si tratta di un file contenente una serie di espressioni regolari che rappresentano errori di ortografia o di stile, utilizzato quando si richiede questo tipo di controllo;

  • ortografia/particolari ---> ../.textchk.special

    contiene delle stringhe particolari che sono da considerare valide anche se il sistema di controllo basato sulle espressioni regolari tenderebbe a segnalare un errore;

  • ortografia/vocabolario

    è il vocabolario specifico per l'opera, che serve a Ispell per questo tipo di verifica;

  • ortografia/minimo.hash

    è il file .hash per Ispell che viene rigenerato ogni volta che si avvia un controllo di questo tipo attraverso ALtools. Infatti, i file .aff e .sml utilizzati da ALtools sono realizzati in modo particolare e vengono ricompilati ogni volta da Ispell prima di fare l'analisi del vocabolario. Ciò serve a garantire il funzionamento di questo tipo di controllo anche quando si cambia piattaforma, o quando si aggiorna Ispell.

• Makefile

  Il file-make che facilita l'uso dei comandi di composizione.

• prefisso-nnnnn.sgml

  Questo rappresenta il file sorgente principale dell'opera che si vuole scrivere. Come si vede, il nome si compone di un prefisso seguito da un trattino, quindi da un numero sequenziale che dovrebbe avere una quantità di cifre uniforme. In coda si aggiunge il solito suffisso .sgml.

275.1.2   Logica dell'apparato

A parere dell'autore di ALtools, è preferibile gestire un file sorgente unico, piuttosto di spezzettare tutto in una miriade di file, anche a costo di lavorare con un file da 10 Mibyte. In questo modo, infatti, è più facile tenere sotto controllo tutto il testo, sapendo che non si perde nulla per la strada.

Questo atteggiamento estremo ha ovviamente degli svantaggi. Tanto per cominciare non si può configurare il proprio programma per la modifica dei file di testo in modo da fargli riconoscere la codifica (la sintassi SGML), perché ciò porterebbe via troppe risorse; inoltre, cosa più grave, diventa più delicato il rischio di perdita di dati (perdendo l'unico file, si perde tutto). Per il primo problema non c'è soluzione; si può solo fare a meno di richiedere funzionalità speciali di riconoscimento al proprio programma che si usa per scrivere. Per prevenire i rischi di perdita di dati si può decidere di salvare ogni volta usando un nome differente: se succede qualcosa si prende l'ultimo file salvato e lo si confronta con il penultimo, attraverso diff.

Ecco allora il senso del nome così strano: il prefisso serve a riconoscere il contenuto del file. Questo potrebbe essere qualunque cosa, come il nome prv usato nella struttura di esempio che viene fornita assieme a ALtools. Il numero che segue serve a distinguere ogni revisione che viene salvata, in modo sequenziale. In pratica, si vuole fare in modo che con un comando del tipo:

ls prefisso-*.sgml

si ottenga un elenco di nomi, dove l'ultimo è esattamente quello più recente (e di conseguenza anche più aggiornato). Sarà compito del redattore eliminare regolarmente le revisioni troppo vecchie.

Il file-make serve prevalentemente per questo: facilitare l'avvio dell'operazione richiesta selezionando automaticamente il file sorgente con il numero di serie maggiore. In pratica, all'interno del file-make si utilizza spesso il comando seguente proprio per determinare il nome di questo file:

ls prefisso-*.sgml | tail -n 1

Si può intuire che il file-make deve essere informato su quale sia il prefisso che permette di individuare questi file: in effetti è così. All'inizio del file-make si deve definire questa informazione, modificando opportunamente la direttiva PREFISSO:

PREFISSO=prefisso_del_sorgente

I file che si trovano nelle directory citazioni/, contributi/, formalità/ e inclusi/, possono essere inseriti nel sorgente principale attraverso le istruzioni SGML apposite. In particolare, ciò che si può trovare nella directory formalità/ proviene in realtà da derivazioni/derivazione/formalita/; in questo modo si consente di avere «formalità» differenti a seconda della derivazione che si intende compilare.

La directory derivazioni/derivazione/, oltre a contenere pezzi di file SGML, come si è visto, serve a distinguere tutto quello che riguarda una certa derivazione. In particolare, si vedono una serie di file di stile per LaTeX che permetterebbero di personalizzare in qualche modo l'aspetto della composizione con LaTeX, con la quale si arriva a un risultato PostScript, oppure PDF.

ALtools ha anche un'altra particolarità importante: al gestione di Ispell è indipendente. Questo serve a ridurre la quantità di errori nel vocabolario che non vengono rivelati. Infatti, se si utilizza un vocabolario troppo dettagliato, si rischia di non accorgersi di termini che possono non avere alcun senso nel tipo di documento che si sta scrivendo. L'ideale sarebbe quello di iniziare a scrivere un documento con un vocabolario completamente vuoto, aggiornandolo mano a mano che questo cresce. Il sistema di file .aff e .sml di ALtools è organizzato in modo da riconoscere come parole tutte le sequenze di lettere e numeri, dove le lettere possono avere qualunque tipo di accento. È un po' difficile spiegare il motivo, perché nasce da un problema che si avverte solo quando si scrivono documenti molto lunghi: prima di tutto non si può escludere di scrivere qualche parola in un'altra lingua che richiede un accento diverso dal solito, e non avrebbe senso inserirla nel vocabolario spezzata in due (o in tre), perché tali lettere accentate non sono considerate parte di una parola; inoltre, includendo anche i numeri si creano parole più lunghe, proprio quando si ha a che fare con stringhe che nulla hanno a che fare con le parole normali del testo.

In generale, è conveniente tenere l'informazione sull'edizione del documento in un file esterno. In base all'esempio fornito, si tratta del file EDIZIONE, che deve contenere una sola riga, con la stringa che definisce l'edizione (dovrebbe trattarsi preferibilmente di una data).

275.1.3   Scheletro di un sorgente SGML che utilizza questo apparato

Data la struttura così articolata che deve avere un progetto di documentazione realizzato con ALtools, anche il sorgente principale di un documento del genere deve essere un po' raffinato. Volendo usare questo sistema di composizione conviene partire sempre dal file fornito come esempio; comunque è il caso di descriverne alcuni punti salienti.

<!-- INIZIO DERIVAZIONE PRINCIPALE -->
<!DOCTYPE ALdoc PUBLIC "-//daniele giacomini//DTD ALdoc 2000.01.00//EN"
[
    ...
]>

<ALdoc>
    ...
<!-- FINE DERIVAZIONE PRINCIPALE -->

Anche se non si prevede di gestire più di una sola derivazione per il proprio documento, è necessario dichiarare l'inizio e la fine di quella denominata come «principale». Le istruzioni

<!-- INIZIO DERIVAZIONE PRINCIPALE -->

e

<!-- FINE DERIVAZIONE PRINCIPALE -->

scritte esattamente in questo modo, usando solo lettere maiuscole, sono precisamente dei commenti SGML che però vengono gestiti da ALtools per filtrare il sorgente prima di iniziare l'elaborazione normale. Senza questa delimitazione non ci sarebbe alcuna composizione.

Dopo la dichiarazione di inizio della derivazione si passa alla definizione del DTD che viene adoperato. Nel momento in cui si scrive questo capitolo, la versione che si vede nell'esempio è quella più recente. Si deve tenere presente che ALtools e ALdoc evolvono rapidamente assieme a Appunti di informatica libera; anche se vengono conservati i DTD delle versioni precedenti, la composizione potrebbe richiedere sempre l'utilizzo del DTD più recente a disposizione.

Si può osservare che nell'ambito della dichiarazione del DTD ci sono anche diverse dichiarazioni di entità interne, che verranno descritte meglio tra poco, quindi si passa alla dichiarazione dell'inizio del documento: il marcatore <ALdoc>. Quindi inizia finalmente il documento, che termina senza la necessità di un marcatore di chiusura esplicito (</ALdoc>).

Nel sorgente ALdoc sono molto importanti le dichiarazioni delle entità interne. Le prime che si trovano nel file di esempio, che accompagna ALtools, sono molto semplici da intendere e in parte sono anche facoltative (sono lì a titolo di esempio):

<!-- Separazione tra paragrafi -->
<!ENTITY SEPARA   "<p>---------</p>">

<!-- lettere evidenziate -->
<!ENTITY NUMN     "<enf>n</enf>"        -- n -- >
<!ENTITY NUMM     "<enf>m</enf>"        -- m -- >
<!ENTITY VARX     "<enf>x</enf>"        -- x -- >
<!ENTITY VARY     "<enf>y</enf>"        -- y -- >
<!ENTITY VARZ     "<enf>z</enf>"        -- z -- >

<!-- Sigle e nomi speciali -->
<!ENTITY LINUX    "Linux"               -- kernel -- >
<!ENTITY GNULINUX "GNU/Linux"           -- sistema operativo -- >
<!ENTITY GNUHURD  "GNU/Hurd"            -- sistema operativo -- >
<!ENTITY DOS      "Dos">
<!ENTITY POSIX    "POSIX"               -- standard -- >
<!ENTITY UNIX     "Unix">
<!ENTITY X        "X">

Come si vede, si tratta solo di un promemoria per rendere uniforme la scrittura di certi termini, come nel caso della macro &GNULINUX; che rappresenta «GNU/Linux» in modo sempre uniforme, oppure per dare una personalità a certi oggetti, come nel caso di &NUMN; che serve a indicare una lettera «n» che dovrebbe avere il significato di «numero» in forma abbreviata.

⁽²⁾

Successivamente si passa a entità interne più importanti, che sono praticamente obbligatorie. Queste servono a definire il nome dell'opera, il nome dell'autore o degli autori, e altre informazioni delicate, a cui fanno riferimento anche i file esterni delle formalità. Dal momento che il documento può essere organizzato in derivazioni differenti, è normale che queste informazioni siano distinte tra una derivazione e l'altra; pertanto, prima si chiude il flusso delle derivazioni e quindi si riapre selettivamente, come mostra l'esempio seguente:

...
<!-- FINE DERIVAZIONE PRINCIPALE -->
<!-- FINE DERIVAZIONE ALTERNATIVA -->

<!-- INIZIO DERIVAZIONE PRINCIPALE -->
<!ENTITY OPERA  "<nome>Esempio</nome>" >
<!ENTITY AUTORI  "Tizio Tizi, Caio Cai" >
<!ENTITY INDIRIZZO  "via Terreno principale, 0 -- I-99999 Terralandia" >
<!ENTITY OPERAEMAIL  " tizio.tizi @ tiziopoli.dg,  caio.cai @ caiopoli.dg" >
<!-- Periodo del copyright -->
<!ENTITY PERIODO  "2000-2010" >
<!-- FINE DERIVAZIONE PRINCIPALE -->

<!-- INIZIO DERIVAZIONE ALTERNATIVA -->
<!ENTITY OPERA  "Esempio alternativo" >
<!ENTITY AUTORI  "Tizio Tizi, Caio Cai" >
<!ENTITY INDIRIZZO  "via Terreno principale, 0 -- I-99999 Terralandia" >
<!ENTITY OPERAEMAIL  " tizio.tizi @ tiziopoli.dg,  caio.cai @ caiopoli.dg" >
<!-- Periodo del copyright -->
<!ENTITY PERIODO  "2000-2010" >
<!-- FINE DERIVAZIONE ALTERNATIVA -->

<!-- INIZIO DERIVAZIONE ALTERNATIVA -->
<!-- INIZIO DERIVAZIONE PRINCIPALE -->

<!-- Data di edizione -->
<!ENTITY EDIZIONE SYSTEM "EDIZIONE">
...

Si osservi che le varie entità che vengono definite hanno un significato speciale per le convenzioni di ALtools. La tabella 275.2 le elenca brevemente, e l'esempio dovrebbe chiarirne il significato. In particolare si può notare che nell'esempio l'entità EDIZIONE viene definita in base al contenuto del file EDIZIONE.

Tabella 275.2. Descrizione del senso delle macro SGML usate per definire i dati essenziali dell'opera.

La terza parte di entità interne è ancora più complessa e importante; per questo viene descritta in una sezione a parte. Nella quarta parte, che conclude il preambolo di dichiarazione del DTD, vengono anticipati i file esterni che verranno inclusi nel sorgente.

...
<!ENTITY        LicenzaGNUGPLEN         SYSTEM  "citazioni/GNU-GPL.en.sgml~">
<!ENTITY        LicenzaGNULGPLEN        SYSTEM  "citazioni/GNU-LGPL.en.sgml~">
...
<!ENTITY        CONTR-PP-esempio        SYSTEM "contributi/PP-esempio.sgml~">
...

L'estratto di esempio mostra la dichiarazione di alcune entità corrispondenti a file esterni, contenuti rispettivamente nella directory citazioni/ e nella directory contributi/. Quando le macro corrispondenti saranno inserite nel testo si otterrà l'inclusione dei file che contengono.

Si può osservare che l'estensione di questi file è .sgml~; in pratica, c'è una tilde di troppo rispetto a quello che sembrerebbe essere corretto. In effetti, i file che si trovano in queste directory hanno le estensioni normali (.sgml), solo che c'è bisogno di una pre-elaborazione prima di essere utilizzati; per questo ALtools crea dei file corrispondenti con l'aggiunta di questa tilde finale. Questo particolare verrà descritto meglio in seguito.

275.1.4   Componenti variabili in base al tipo di composizione

Vale la pena di descrivere separatamente il problema dei componenti che cambiano in funzione del tipo di composizione. Per comprendere il meccanismo occorre capire quali sono le differenze tra i vari risultati di composizione. Si distingue tra:

• PostScript «normale», o PDF, dove si intende ottenere un libro in formato A4;

• PostScript «lungo», dove si intende ottenere un formato A4 finale, ma composto da pagine separate in due colonne contenenti testo ridotto a un quarto della dimensione originale;

• HTML «normale», dove ogni capitolo ha una sua pagina;

• HTML «piatto», o testo puro, dove tutto il documento occupa una sola pagina lunghissima;

Può essere opportuno ripetere certe informazioni all'interno del formato finale, se la sua forma lo richiede o lo consente. Per esempio, può essere utile ripetere l'indicazione del copyright alla fine di ogni capitolo, ma questo potrebbe essere superfluo in una composizione che genera una pagina unica (HTML o testo che sia); inoltre, all'inizio di ogni tomo potrebbe essere utile ripetere anche la licenza e altre informazioni, ma questo non sarebbe sensato in una composizione in cui si risparmia tutto lo spazio possibile (il PostScript lungo) o dove non ci sia una separazione in pagine (come nella composizione HTML o testo a pagina singola).

Per gestire queste piccole varianti sono previsti alcuni file, che prima della composizione vengono collocati nella directory formalita/. Questi file vengono dichiarati all'interno del sorgente come entità, che poi vengono incorporate dove più opportuno attraverso le macro corrispondenti. Controllando il contenuto di queste macro, si gestisce tale meccanismo di composizione variabile.

L'incorporazione di questo o di quel file all'interno di un'entità dipende da altre entità parametriche, che vengono dichiarate all'esterno del sorgente SGML, da ALtools, in base al comando di composizione che gli viene impartito. Per la precisione sono previste le entità parametriche elencate nella tabella 275.3 dove viene descritto il loro significato nel caso siano attive (INCLUDE).

Tabella 275.3. Significato delle entità parametriche gestite da ALtools.

Le prime quattro entità parametriche, %HTML, %PLAINHTML, %POSTSCRIPT, e %POSTSCRIPTLUNGO, sono alternative, nel senso che soltanto una alla volta può essere attiva. Le altre entità sono indipendenti e servono a controllare l'inclusione o meno di parte del testo SGML.

Nel preambolo di dichiarazione delle entità interne conviene procedere come si vede nell'estratto seguente, in cui, prima si dichiarano le entità parametriche, disattivandole; poi si controllano. Infatti, secondo l'analizzatore SGML, vale solo la prima delle dichiarazioni: se le entità in questione sono già state dichiarate al momento della chiamata dell'analizzatore stesso, quelle successive vengono ignorate semplicemente.

<!--=================================================================-->
<!-- Qui vengono escluse le entità parametriche in modo predefinito. -->
<!-- Se dovessero risultare già definite, queste sarebbero ignorate  -->
<!-- semplicemente.                                                  -->
<!--=================================================================-->
<!ENTITY % HTML "IGNORE">
<!ENTITY % PLAINHTML "IGNORE">
<!ENTITY % POSTSCRIPT "IGNORE">
<!ENTITY % POSTSCRIPTLUNGO "IGNORE">
<!ENTITY % ANNOTAZIONI "IGNORE">
<!ENTITY % SENZACONTROLLO "IGNORE">
<!ENTITY % OBSOLETO "IGNORE">


<![ %POSTSCRIPT [
        <!ENTITY COPYTOMO  SYSTEM "formalita/COPYTOMO.sgml~">
        <!ENTITY COPYPARTE SYSTEM "formalita/COPYPARTE.sgml~">
        <!ENTITY COPY      SYSTEM "formalita/COPY.sgml~">
        <!ENTITY DEDICA    SYSTEM "formalita/DEDICA.sgml~">
]]>

<![ %POSTSCRIPTLUNGO [
        <!ENTITY COPYTOMO  "">
        <!ENTITY COPYPARTE "">
        <!ENTITY COPY      SYSTEM "formalita/COPY.sgml~">
        <!ENTITY DEDICA    SYSTEM "formalita/DEDICA.sgml~">
]]>

<![ %HTML [
        <!ENTITY COPYTOMO  SYSTEM "formalita/COPYTOMO.sgml~">
        <!ENTITY COPYPARTE SYSTEM "formalita/COPYPARTE.sgml~">
        <!ENTITY COPY      SYSTEM "formalita/COPY.sgml~">
        <!ENTITY DEDICA    "">
]]>

<![ %PLAINHTML [
        <!ENTITY COPYTOMO "">
        <!ENTITY COPYPARTE "">
        <!ENTITY COPY "">
        <!ENTITY DEDICA "">
]]>


<!--=================================================================-->
<!-- Quella che segue è l'impostazione predefinita, nel caso non sia -->
<!-- stato specificato il tipo di composizione.                      -->
<!--=================================================================-->
<!ENTITY COPYING             SYSTEM "formalita/LICENZA.sgml~">
<!ENTITY PRESENTAZIONEAUTORE SYSTEM "formalita/PRESENTAZIONEAUTORE.sgml~">
<!ENTITY DEDICA              SYSTEM "formalita/DEDICA.sgml~">
<!ENTITY COPYTOMO            SYSTEM "formalita/LICENZA.sgml~">
<!ENTITY COPYPARTE           SYSTEM "formalita/COPYPARTE.sgml~">
<!ENTITY COPY                SYSTEM "formalita/COPY.sgml~">
<!ENTITY MIRROR              SYSTEM "formalita/MIRROR.sgml~">

Si tratta evidentemente di uno schema piuttosto complicato: nella prima parte vengono stabiliti i valori predefiniti per le entità parametriche che sono state descritte, ammesso che il programma di composizione non le abbia già impostate; in base all'attivazione di queste entità parametriche vengono dichiarate delle entità normali, a cui viene attribuito o meno il contenuto di un certo file. Le macro corrispondenti possono essere usate nel testo, nelle collocazioni più opportune, secondo la logica che si vede nella tabella 275.4.

Tabella 275.4. Descrizione delle macro contenenti le formalità.

Si può osservare nell'esempio che nel caso di composizione in formato HTML a pagina singola, non si indicano le informazioni sul copyright all'inizio dei tomi, delle parti, e alla fine dei capitoli. Inoltre, trattandosi di una forma di composizione così particolare, non viene messa nemmeno la dedica (ma questo solo perché si confonderebbe con il testo normale, mentre la tradizione vuole che la dedica stia su una pagina apposita).

A parte il controllo che si fa all'interno del preambolo di dichiarazione del DTD, è chiaro che i file delle formalità, a cui si fa riferimento in questo modo, vanno modificati in base alle proprie esigenze. A questo proposito, è importante ricordare che la loro posizione originale non è formalita/, ma derivazioni/derivazione/formalita/, essendo il programma di composizione che provvede a copiarli opportunamente nell'altra directory.

275.1.5   Prova di composizione

Per concludere la descrizione di come si debba organizzare un progetto di documentazione, vale la pena di mostrare in che modo si può comporre l'esempio che accompagna ALtools. Supponendo di avere copiato il contenuto della directory /opt/ALtools/doc/esempio/ in ~/lavoro/, ci si potrà spostare in questa seconda directory e quindi eseguire il comando

$ make ps

con il quale si ottiene la composizione in PostScript. Sapendo che nell'ambito di quel tipo di esempio, il prefisso usato per i file è la sigla prv, ammesso che sia presente un file con un numero di serie pari a «00007», si ottiene il file prv-00007.sgml.ps.

Al termine, se gli altri file che sono serviti per arrivare al risultato non servono più, basta usare il comando seguente:

$ make ripulisci

275.2   Fasi attraverso cui viene elaborato il file SGML

Le fasi attraverso cui ALtools elabora un sorgente SGML ALdoc sono molte e tutto l'insieme è abbastanza complesso. In linea di massima si possono riconoscere tre passaggi iniziali prima di passare alla composizione finale: una pre-elaborazione SGML, l'analisi SGML, una post-elaborazione. L'elaborazione successiva dipende dal tipo di composizione che si vuole ottenere. In tutti i casi si passa per una trasformazione in un formato intermedio, che nelle situazioni più comuni può essere LaTeX o una sorta di HTML da rielaborare.

275.2.1   Elaborazione SGML

Lo schema della figura 275.1 mostra i passaggi che subisce un sorgente SGML ALdoc, sotto il controllo di ALtools.

Sorgente ALdoc ----> ALtxt2txt             ALtxt2txt <---- componenti ALdoc
principale               |                     |           esterni (*.sgml)
                         V                     V
                   ALpresgml2sgml        ALpresgml2sgml
                         |                     |
                         V                     V
                    ALsgml2sgml           ALsgml2sgml
                         |                     |
                         V                     |
  DTD ALdoc ---->   nsgmls (SP) <--------------' (*.sgml~)
                         |
                         V
                      ALsp2sp ----> Risultato post-SP

Il file sorgente viene filtrato da diversi programmi, generando a volte anche dei file intermedi per non appesantire il sistema con un insieme di processi simultanei troppo complesso.

Di seguito viene descritto il significato di questi passaggi che si rendono necessari perché un sorgente SGML ALdoc non rispetta perfettamente le specifiche dell'SGML, dato che utilizza il più possibile la codifica ISO 8859-1 con qualche estensione e dato che deve essere possibile la delimitazione di derivazioni differenti. Si noti che i nomi dei programmi che appaiono indicati servono solo per distinguere le funzioni, dal momento che ALtools li gestisce automaticamente a partire dall'unico eseguibile ALtools (che comunque è uno script di shell).

1. ALtxt2txt

   Questo programma si occupa di filtrare il sorgente e di sostituire alcuni codici con qualcosa di appropriato. Per la precisione:

   • il codice B7₁₆, ovvero 183₁₀, viene sostituito con A0₁₆, ovvero 160₁₀, corrispondente allo spazio non interrompibile;

   • il codice F7₁₆, ovvero 247₁₀, viene sostituito con la stringa <meno>, cioè con un marcatore SGML che si traduce poi in un trattino dattilografico.

   L'utilità di questo sta nel fatto che così non è più necessario usare da macro &nbsp; per indicare lo spazio non interrompibile; inoltre, anche il trattino dattilografico viene gestito in un modo quasi trasparente. Ovviamente, data questa scelta, i simboli utilizzati per questo scopo non possono più servire per il loro significato originale.

2. ALpresgml2sgml

   Questo programma filtra il sorgente SGML alla ricerca dei delimitatori

   <!-- INIZIO DERIVAZIONE derivazione -->
   

   e

   <!-- FINE DERIVAZIONE derivazione -->
   

   che, pur essendo commenti dal punto di vista dell'SGML, segnalano i blocchi di testo che appartengono a questa o a quella riduzione particolare del documento. Per non interferire con SP, che tra le altre cose informa sulla correttezza o meno del sorgente SGML attraverso l'indicazione delle righe in cui appaiono gli errori, il file generato da ALpresgml2sgml ha lo stesso numero di righe, dove ciò che non si vuole viene sostituito da righe vuote.

   Queste segnalazioni devono essere scritte esattamente come mostrato e devono occupare sa sole una riga, senza l'aggiunta di spazi superflui prima o dopo.

3. ALsgml2sgml

   Alcuni ambienti per il testo letterale vengono rielaborati in modo da sistemare le incompatibilità derivanti dall'SGML, in modo distinto se si deve arrivare a un risultato adatto a LaTeX, a HTML o ad altri tipi di file.

4. nsgmls

   Questo è l'eseguibile di SP, l'analizzatore SGML fondamentale scritto da James Clark. È lo stesso analizzatore che aggrega i vari file SGML; inoltre, è in questa fase che vengono definite le entità parametriche che servono a modificare il risultato dell'aggregazione del testo.

5. ALsp2sp

   Dopo l'elaborazione di SP (nsgmls), il risultato viene rielaborato per sostituire alcuni caratteri ISO 8859-1 (standard) con delle entità SDATA; subito dopo le entità vengono rimpiazzate con ciò che è più conveniente per il tipo di trasformazione a cui si vuole arrivare.

   L'SGML ha poche esigenze per ciò che riguarda i simboli speciali. Per questo linguaggio è sufficiente che non siano lasciati in giro <, > e &, ma per altri programmi che devono rielaborare il risultato di un analizzatore SGML, ci potrebbero essere altri caratteri che hanno significati speciali. Basti pensare a LaTeX per esempio. Per evitare problemi occorrerebbe utilizzare sempre le macro per tutto ciò che va oltre le lettere alfabetiche normali e le cifre numeriche.

   Per risolvere il problema, è necessario individuare nel risultato dell'elaborazione SP tali simboli speciali, sostituendoli con la notazione corrispondente che sarebbe stata usata se al loro posto fosse stata inserita la macro relativa.

Naturalmente, tutta l'elaborazione che c'è prima di arrivare a SP, riguarda anche tutti i file che devono essere aggregati al sorgente principale; quei file che quando vengono acquisiti hanno l'estensione .sgml~.

275.2.2   Elaborazione post-SP

Una volta ottenuto il risultato dell'elaborazione da parte di SP, dopo che gli sono state apportate le correzioni dovute al problema dei caratteri speciali, si passa a un'altra elaborazione che genera un risultato adatto al tipo di composizione che si intende ottenere. Questo lavoro è svolto da SGMLSpm, attraverso l'eseguibile sgmlspl, secondo le direttive contenute in un file specifico, che in pratica è un pezzo di programma Perl.

risultato post-SP ----> sgmlspl <---- latex.spec
                           |
                           `--> sorgente LaTeX


risultato post-SP ----> sgmlspl <---- prehtml.spec
                           |
                           `--> formato intermedio per la composizione HTML

La figura 275.2 mostra i due casi fondamentali, attraverso i quali si genera un sorgente LaTeX, oppure un file adatto alla composizione successiva in HTML.

275.2.3   Elaborazione HTML

L'elaborazione fatta da SGMLSpm, attraverso le indicazioni contenute nel file prehtml.spec (o anche prehtml.bozza.spec), genera una specie di file HTML, contenente una serie di simboli speciali che devono essere interpretati da un altro programma per arrivare a una composizione finale. Il programma in questione è ALprehtml2html, il quale può generare simultaneamente un formato HTML «normale», un altro con nomi compatibili con i file system Dos-FAT (8.3), un altro ancora composto da una sola pagina. Questa viene convertita anche in un formato testo normale, con l'aiuto di Lynx.

post-SGMLSpm ----> ALprehtml2html
normale                  |
                         |----> formato HTML normale
                         |
                         `----> formato HTML 8.3

post-SGMLSpm ----> ALprehtml2html
singolo                  |
                         `----> formato HTML singolo
                                        |
                                        |
                                       Lynx
                                        |
                                        V
                                    testo puro

Tuttavia, le cose non avvengono sempre in modo simultaneo, dal momento che il formato a pagina singola richiede una selezione diversa del sorgente SGML, per cui è necessaria un'altra elaborazione da parte di SP, utilizzando delle entità parametriche differenti.

Per la composizione in HTML occorre definire alcune informazioni che riguardano il file /derivazioni/derivazione/stile-html.sh e anche il file-make. Si tratta in particolare di due prefissi: uno da utilizzare per i nomi dei file della composizione «8.3» e l'altro per i file della composizione normale. Le direttive relative da inserire nel file stile-html.sh sono molto semplici:

SIGLA83=prefisso_nomi_corti
SIGLA=prefisso_normale

Tuttavia, queste non sono le sole. L'esempio seguente le mostra tutte:

# Titolo dell'opera nelle intestazioni dei file HTML
TITOLO="P.R.V."

# Sigla iniziale dei file HTML normali
SIGLA="PRV"

# Sigla iniziale dei file HTML 8.3 (nomi corti)
SIGLA83="prv"

# Lingua secondo lo standard ISO 639
LINGUA="it"

# Campi meta
META_HTTP_EQUIV="text/html; charset=ISO-8859-1"
META_DESCRIPTION="PRV e altre storie simili"
META_KEYWORDS="GNU/Linux, Unix, software libero, free software"

In questo modo, la composizione genera i risultati seguenti:

• con nomi corti (8.3) genera la directory htm-prv, contenente file prvn.htm e n.jpg (per le immagini);

• la composizione normale genera la directory html-PRV, contenente file PRV-*.html e la directory figure/ con le immagini;

• la composizione a pagina singola genera la directory html-singolo-PRV, contenente il file PRV.html, il file PRV.txt, e la directory figure/ con le immagini.

In tutti i casi, le pagine HTML hanno un titolo che inizia con la sigla P.R.V.; il linguaggio dell'elemento HTML è definito dalla stringa it; inoltre si utilizzano gli elementi META seguenti:

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
<META NAME="Description" CONTENT="PRV e altre storie simili">
<META NAME="Keywords" CONTENT="GNU/Linux, Unix, software libero, free software">

Nel caso della composizione con nomi corti, è opportuno che il prefisso scelto sia scritto in lettere minuscole, ed è importante che questo prefisso sia breve (in ogni caso, non può superare i cinque caratteri), altrimenti si rischia di superare gli otto caratteri per la parte del nome che precede l'estensione.

Tuttavia, non basta intervenire nel file /derivazioni/derivazione/stile-html.sh. Se si vuole che il file-make sia in grado di eliminare correttamente queste directory quando si fa la ripulitura dai file superflui, con un make ripulisci, occorre annotare questi prefissi anche al suo interno. All'inizio del file Makefile si trova questa definizione e l'esempio si riferisce a quanto già visto:

#-----------------------------------------------------------------------
# Prefisso del nome dei file.
#-----------------------------------------------------------------------
PREFISSO=prv
SIGLAHTML=PRV
SIGLAHTML83=prv

In precedenza era già stato mostrato l'uso della definizione PREFISSO, allo scopo si sapere quale sia il prefisso dei file sorgenti SGML.

275.2.3.1   Accorgimenti ulteriori per la composizione HTML

Nella directory /derivazioni/derivazione/ vanno collocati altri file che vengono copiati semplicemente nella destinazione dei file HTML. Si tratta dei file index.html e index.htm, che vanno realizzati opportunamente per presentare l'edizione normale e con nomi corti rispettivamente. Eventualmente si può fare a meno di questi file; tuttavia, occorre tenere presente che il sistema di composizione non li genera da solo. È utile anche un altro file, stile.css, che è il foglio di stile CSS a cui fanno riferimento tutte le pagine HTML generate.

275.2.4   Elaborazione LaTeX

La composizione in PostScript e PDF viene fatta attraverso LaTeX e pdfLaTeX, a partire da un solo tipo di file sorgente: la differenza nella composizione viene controllata attraverso una serie di stili specifici.

 post-SGMLSpm
      |
      V
sorgente LaTeX
      |
      | prima passata
      |                                   / formato
      |----------> LaTeX o pdfLaTeX <----<  stile
      |                 |   |             \ indice
      |                 |   |
      |                 |   `--> indice generale e analitico
      |                 |
      |                 `--> file DVI o PDF non valido a causa degli indici
      |                      e dei riferimenti incrociati
      |
      | seconda passata
      |                                   / formato
      |----------> LaTeX o pdfLaTeX <----<  stile
      |                 |   |             \ indice
      |                 |   |
      |                 |   `--> indice generale e analitico
      |                 |
      |                 `--> file DVI o PDF non valido a causa degli indici
      |                      e dei riferimenti incrociati
      |
      | terza passata
      |                                   / formato
      `----------> LaTeX o pdfLaTeX <----<  stile
                        |   |             \ indice
                        |   |
                        |   `--> indice generale e analitico
                        |
                        `--> file DVI o PDF valido

Nel sorgente LaTeX generato da SGMLSpm ci sono i comandi per importare dei file che vengono generati dinamicamente da ALtools; si tratta di quelli che si vedono nella figura 275.4.

Il file formato contiene i comandi necessari a definire il formato della carta. In generale si tratta di un formato A4, ma eccezionalmente le cose possono cambiare, per esempio nel caso del formato lungo. Il file stile viene creato di volta in volta per definire quali file di stile importare. In generale la scelta dipende dalla particolarità della composizione richiesta (la tabella 275.5 riepiloga i vari casi), tenendo conto che si fa sempre riferimento a una coppia di file: uno collocato nella directory /opt/ALtools/share/ e un altro, personalizzabile, nella directory derivazioni/derivazione/.

Tabella 275.5. Organizzazione degli stili LaTeX.

In generale, per evitare di riscrivere gli stessi file di stile, quando possibile si tende a richiamare quello più simile, aggiungendo i comandi necessari.

La figura 275.4 mostra le cose in modo un po' semplificato, ma la necessità di intervenire ripetendo la composizione con LaTeX più volte dipende dagli indici che devono essere inclusi e dai riferimenti incrociati; inoltre, è noto il fatto che l'indice analitico viene realizzato con l'aiuto di altri programmi che riordinano e selezionano le voci.

ALtools è organizzato anche per gestire altri tipi di indici specifici, realizzati per Appunti di informatica libera, ma questo verrà descritto in seguito.

La composizione attraverso LaTeX e pdfLaTeX risente della configurazione della sillabazione. Si tratta di un punto molto delicato, a causa del quale è probabile sia necessario intervenire nel file di stile necessario (derivazioni/derivazione/stile-tex-*). Bisogna stabilire quale sia il linguaggio del testo (italiano o altra lingua) dal punto di vista della propria distribuzione LaTeX; inoltre è necessario sapere quale sia il linguaggio nullo, ovvero senza sillabazione. Il problema è già stato descritto nel capitolo 129; in pratica, si tratta di determinare quale sia il comando giusto: \language0, \language1,...

⁽³⁾

Se la sillabazione per la lingua principale con cui si intende scrivere corrisponde al secondo linguaggio, il comando è \language1; se la sillabazione nulla corrisponde al terzo linguaggio, il comando per selezionarla è \language2. In base a questi esempi, occorrerebbe aggiungere nel proprio file di stile personalizzato le istruzioni seguenti:

\renewcommand{\sillabazione}{\language1}
\renewcommand{\nosillabazione}{\language2}

Se poi si preferisce annullare del tutto la sillabazione, basta dichiarare in entrambi i casi il comando corrispondente alla sillabazione nulla, per esempio:

\renewcommand{\sillabazione}{\language2}
\renewcommand{\nosillabazione}{\language2}

Per concludere si tenga presente che, per la composizione in PostScript, dopo la realizzazione del file DVI si utilizza dvips per convertirlo in PostScript; inoltre, nel caso del formato lungo, si passa anche per un'elaborazione con le PSUtils.

275.2.5   Elaborazione per l'analisi ortografica

Per eseguire l'analisi ortografica, attraverso Ispell e ALerrori (che comunque è incorporato all'interno di ALtools), si passa per la generazione di un formato intermedio, rappresentato da un file di testo senza formattazione di alcun tipo.

Quando si esegue il controllo del vocabolario, con Ispell, per sicurezza vengono conservate tre copie precedenti nella directory ortografia/. Precisamente si tratta di: vocabolario.bkp1, vocabolario.bkp2 e vocabolario.bkp3. In caso di «incidenti», si può sempre recuperare il vocabolario dalla copia più recente.

Il controllo sintattico e stilistico funziona nel modo che è già stato descritto nel capitolo 152.

275.3   Comandi di ALtools

ALtools è realizzato con l'idea di avere un programma frontale tuttofare per ciò che serve a Appunti di informatica libera. Per questo, oltre ai comandi normali per la composizione, sono disponibili delle funzioni particolari, che di solito mancano in un sistema di documentazione del genere.

Ci sono tre modi di usare ALtools: indicando il comando come primo argomento; utilizzando un collegamento simbolico che si compone anche del nome del comando; affidandosi al file-make.

ALtools comando file [derivazione]

ALtools-comando file [derivazione]

make comando

Nei primi due dei modelli sintattici mostrati si vede che è possibile specificare il nome della derivazione, o riduzione, a cui si vuole fare riferimento. In mancanza, si intende il nome principale. Nel caso dell'uso del file-make, si intende implicitamente l'ultimo dei sorgenti (lo si determina in base all'ordine che prende con un ls prefisso-*.sgml) e inoltre si considera esclusivamente la derivazione predefinita.

Comandi di controllo e di composizione

ALtools controllo-sgml file [derivazione]

ALtools-controllo-sgml file [derivazione]

make controllo-sgml

Controlla la validità SGML del file indicato, in base al DTD, dopo averlo preparato un po', con l'aiuto di ALtxt2txt, ALpresgml2sgml e ALsgml2sgml.

ALtools controllo-vocabolario file [derivazione]

ALtools-controllo-vocabolario file [derivazione]

make controllo-vocabolario

Utilizza Ispell per verificare le parole utilizzate nel documento attraverso il suo vocabolario specifico.

ALtools controllo-sintassi file [derivazione]

ALtools-controllo-sintassi file [derivazione]

make controllo-sintassi

Utilizza ALerrori (il sistema descritto nel capitolo 152) per verificare la coerenza sintattica e stilistica del sorgente.

ALtools html file [derivazione]

ALtools-html file [derivazione]

make html

Elabora il file indicato come argomento per ottenere un risultato HTML, in tutte le sue varianti, oltre a una conversione in formato testo.

ALtools pdf file [derivazione]

ALtools-pdf file [derivazione]

make pdf

Elabora il documento indicato come argomento per ottenere un risultato PDF, attraverso l'uso di pdfLaTeX.

ALtools ps file [derivazione]

ALtools-ps file [derivazione]

make ps

Elabora il documento indicato come argomento per ottenere un risultato PostScript, attraverso l'uso di LaTeX.

ALtools ps-continuo file [derivazione]

ALtools-ps-continuo file [derivazione]

make ps-continuo

Elabora il documento indicato come argomento per ottenere un risultato PostScript, attraverso l'uso di LaTeX, in cui la numerazione delle pagine sia continua, a partire dal numero uno.

ALtools ps-lungo file [derivazione]

ALtools-ps-lungo file [derivazione]

make ps-lungo

Elabora il documento indicato come argomento per ottenere un risultato PostScript, di tipo speciale, in cui si riduce al massimo e si risparmia tutta la carta che si può.

Comandi particolari

ALtools controllo-uri file

ALtools-controllo-uri file

make controllo-uri

Controlla la validità degli indirizzi URI, se è disponibile una connessione alla rete esterna. Il controllo avviene su tutto il sorgente, senza distinguere tra le derivazioni.

ALtools controllo-uri-html file

ALtools-controllo-uri-html file

Controlla la validità degli indirizzi URI, di un file HTML normale.

ALtools psX2 file_ps

ALtools-psX2 file_ps

Utilizza le PSUtils per generare una trasformazione di un file PostScript A4, in un altro file PostScript in cui le pagine sono ridotte in formato A5 e in coppia.

ALtools psX2-4 file_ps

ALtools-psX2-4 file_ps

Utilizza le PSUtils per generare una trasformazione di un file PostScript A4, in un altro file PostScript in cui le pagine sono ridotte in formato A5, da stampare fronte e retro e piegare a metà a segnature di un solo foglio.

ALtools psX2-40 file_ps

ALtools-psX2-40 file_ps

Utilizza le PSUtils per generare una trasformazione di un file PostScript A4, in un altro file PostScript in cui le pagine sono ridotte in formato A5, da stampare fronte e retro e piegare a metà a segnature di 10 fogli.

ALtools psX4 file_ps

ALtools-psX4 file_ps

Utilizza le PSUtils per generare una trasformazione di un file PostScript A4, in un altro file PostScript in cui le pagine sono ridotte in formato A6, raccolte a gruppetti di quattro.

275.3.1   Bozza per la correzione

Il controllo di un documento scritto secondo il modello ALdoc può essere fatto più facilmente se nel sorgente SGML si segnalano alcune informazioni, parole o frasi, che devono essere usate coerentemente nel testo. Nella composizione finale, questi elementi non devono essere segnalati, ma è possibile farli rimarcare nella composizione «bozza».

ALtools bozza-ps  file [derivazione]

ALtools-bozza-ps  file [derivazione]

make bozza-ps file

ALtools bozza-pdf  file [derivazione]

ALtools-bozza-pdf  file [derivazione]

make bozza-pdf file

ALtools bozza-html  file [derivazione]

ALtools-bozza-html  file [derivazione]

make bozza-html file

1) Questo capitolo e i successivi descrivono il sistema di composizione ALtools/ALdoc. Tuttavia, per poter comprendere quanto esposto, è necessario prima conoscere ciò che è stato descritto a proposito dell'SGML, di TeX, e dei sistemi comuni di composizione basati sull'SGML.

2) Data l'organizzazione dei file delle formalità, è necessaria la presenza della macro &SEPARA;, che serve letteralmente a separare leggermente un testo. Infatti, non c'è altro modo di ottenere una separazione più netta del normale tra due paragrafi.

3) Per scoprirlo, si può provare a cercare il file TeX texmf/web2c/latex.log. Al suo interno si possono trovare le corrispondenze attuali di questi comandi.