[inizio] [indice generale] [precedente] [successivo] [indice analitico] [contributi]


148. ALtools

ALdoc è il DTD utilizzato per la realizzazione di questo documento, Appunti Linux, 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. *1*

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

ALtools e il DTD ALdoc continueranno a evolversi assieme all'opera Appunti Linux. Chi desidera utilizzarli deve tenere in considerazione questo fatto, e prima di passare a un eventuale aggiornamento, deve valutare l'opportunità di questo cambiamento.

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 148.1 riepiloga gli applicativi da cui dipende il buon funzionamento di ALtools.

Applicativo Compito
Perl I programmi più importanti di ALtools sono in Perl.
SP Verifica la validità SGML e genera una prima conversione.
SGMLSpm Converte il risultato post-SP in un altro formato.
LaTeX Compone in un formato finale per la stampa.
ImageMagick Converte i file delle immagini nei formati appropriati.
Lynx Converte un file HTML in testo puro.
PSUtils Riorganizza, ingrandisce e riduce un file PostScript.
Wget Controlla la validità degli URI di tipo HTTP.

Tabella 148.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.

148.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/

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

148.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 Mbyte. 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.

Naturalmente, se non si apprezza questa politica, nulla vieta di entrare nella directory `/opt/ALtools/lib/' per modificare il file `minimo.aff' nel modo che più è ritenuto corretto per i propri scopi. Come è già stato precisato, ogni volta che viene avviato il controllo del vocabolario, questi file vengono ricompilati.

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

148.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 Linux; 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. *2*

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 148.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'.

Macro SGML Contenuto
&OPERA; Il nome dell'opera.
&AUTORI; L'autore o l'elenco dei nomi degli autori.
&INDIRIZZO; l'indirizzo di riferimento per il copyright (ammesso che ci sia).
&OPERAEMAIL; L'indirizzo o gli indirizzi di posta elettronica di riferimento.
&PERIODO; L'anno o gli anni del copyright.
&EDIZIONE; Edizione, scritta possibilmente come data.

Tabella 148.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.

148.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:

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 148.3 dove viene descritto il loro significato nel caso siano attive (`INCLUDE').

Entità parametrica Significato se attiva
%HTML Composizione HTML normale.
%PLAINHTML Composizione HTML su una pagina unica.
%POSTSCRIPT Composizione PostScript o PDF normale.
%POSTSCRIPTLUNGO Composizione PostScript speciale per risparmiare spazio.
%ANNOTAZIONI Composizione con annotazioni per uso interno.
%SENZACONTROLLO Composizione completa di ciò che non viene controllato ortograficamente.
%OBSOLETO Composizione completa di informazioni ritenute obsolete o incomplete.

Tabella 148.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 148.4.

Macro Descrizione
&COPYING; Copyright e licenza da indicare all'inizio del documento.
&PRESENTAZIONEAUTORE; Presentazione dell'autore in poche righe.
&DEDICA; Dedica del libro.
&COPYTOMO; Copyright e licenza da collocare all'inizio di un tomo.
&COPYPARTE; Copyright e licenza da collocare all'inizio di una parte.
&COPY; Copyright da indicare alla fine di ogni capitolo normale.
&MIRROR; Descrizione del modo in cui è possibile ottenere una copia del documento.

Tabella 148.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.

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

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

148.2.1 Elaborazione SGML

Lo schema della figura 148.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

Figura 148.1: Fasi dell'elaborazione SGML.

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 0xb7, ovvero 183, viene sostituito con 0xa0, ovvero 160, corrispondente allo spazio non interrompibile;

    • il codice 0xf7, 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~'.

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

Figura 148.2: Fasi successive all'elaborazione SGML pura e semplice.

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

148.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 filesystem 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

Figura 148.3: Elaborazione per la generazione del formato HTML.

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:

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">

Vengono inseriti anche altri elementi `META' in base a informazioni che si possiedono già dal sorgente dell'opera.

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.

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

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

Figura 148.4: Elaborazione attraverso LaTeX.

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 148.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 148.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>/'.

Stile generale Stile personale Tipo di composizione
ALtools-stile-tex-ps stile-tex-ps PostScript normale.
ALtools-stile-tex-ps-lungo stile-tex-ps-lungo PostScript lungo.
ALtools-stile-tex-ps-bozza stile-tex-ps-bozza PostScript bozza.
ALtools-stile-tex-ps-continuo stile-tex-ps-continuo PostScript numerazione pagine continua.
ALtools-stile-tex-pdf stile-tex-pdf PDF normale.
ALtools-stile-tex-pdf-bozza stile-tex-pdf-bozza PDF bozza.

Tabella 148.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.

Osservando un po' come sono realizzati gli stili di ALtools, quelli che si trovano nella directory `/opt/ALtools/share/', si può tentare di personalizzare i propri, tenendo conto però che da un'edizione all'altra questi possono cambiare molto.

La figura 148.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 Linux, 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 127; in pratica, si tratta di determinare quale sia il comando giusto: `\language0', `\language1',... *3*

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.

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

Alle volte, forse per la stanchezza, ci si accorge di avere aggiunto una parola sbagliata nel vocabolario. Per eliminarla basta un programma per la modifica dei file di testo, togliendo la riga corrispondente nel file `ortografia/vocabolario'.

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

148.3 Comandi di ALtools

ALtools è realizzato con l'idea di avere un programma frontale tuttofare per ciò che serve a Appunti Linux. 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 147) 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.

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

---------------------------

Appunti Linux 2000.04.12 --- Copyright © 1997-2000 Daniele Giacomini --  daniele @ pluto.linux.it


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.


[inizio] [indice generale] [precedente] [successivo] [indice analitico] [contributi]