[successivo] [precedente] [inizio] [fine] [indice generale] [licenze] [indice analitico] [tomo] [parte]
Alml (1) è il sistema di composizione SGML di questo documento, Appunti di informatica libera. Si tratta di un programma Perl, alml, che controlla l'analizzatore SGML e altri programmi necessari per arrivare alla composizione finale del documento.(2)
Alml si avvale di altri programmi per l'analisi SGML e per la generazione di alcuni formati finali. In particolare, è necessario disporre di nsgmls che fa parte generalmente del pacchetto SP (anche se la propria distribuzione GNU/Linux potrebbe nominarlo in modo differente); inoltre è fondamentale la presenza di LaTeX per generare la composizione da stampa. La tabella 156.1 riepiloga gli applicativi da cui dipende il buon funzionamento di Alml.
Tabella 156.1. Applicativi da cui dipende Alml.
Alml viene fornito solo attraverso archivi tradizionali di tipo tar+gzip, in file con nomi del tipo:
alml- versione .tar.gz
Estraendo il contenuto dell'archivio, si dovrebbero ottenere in particolare i file e le sottodirectory elencati nella tabella 156.2, che rappresentano l'essenziale.
Tabella 156.2. Contenuto essenziale dell'archivio di distribuzione di Alml.
Gli eseguibili, alml e alml-sp2be, devono essere raggiungibili attraverso il percorso di ricerca del sistema, rappresentato dalla variabile di ambiente PATH. Pertanto vanno collocati opportunamente, oppure vanno predisposti dei collegamenti adeguati.
I file alml.cat, alml.dcl e alml.dtd vanno collocati nella directory /etc/alml/, oppure vanno realizzati dei collegamenti equivalenti. Inoltre, tutto il contenuto della directory entities/ va collocato all'interno di /etc/alml/entities/, oppure può bastare un altro collegamento simbolico alla directory intera.
Per completare l'installazione, sarebbe opportuno provvedere a trasferire le directory html/ e xml/, nella directory /etc/alml/, in modo da ottenere /etc/alml/html/ e /etc/alml/xml/. Tuttavia, ciò serve solo per abilitare la verifica formale di documenti in HTML e in XML.
I messaggi di Alml possono essere tradotti. Per installare i file PO già esistenti è necessario compilarli come nell'esempio seguente:
$ msgfmt -vvvv -o alml.mo it.po
In questo esempio, il file it.po viene compilato generando il file alml.mo. Questo file può essere collocato in /usr/share/locale/it/LC_MESSAGES/, o in un'altra posizione analoga in base agli standard del proprio sistema operativo.
Se non è disponibile il modulo Perl-gettext,(3) che serve a Alml per accedere alle traduzioni, è possibile eliminare il suo utilizzo e simulare la funzione di Gettext. In pratica si commentano le istruzioni seguenti all'inizi dei programmi alml e alml-sp2be:
# We *don't* want to use gettext.
#use POSIX;
#use Locale::gettext;
#setlocale (LC_MESSAGES, "");
#textdomain ("alml");
Inoltre, si tolgono i commenti dalla dichiarazione della funzione fittizia gettext(), come si vede qui:
sub gettext
{
return $_[0];
}
Un esempio iniziale può servire per comprendere il funzionamento generale di Alml.
<!DOCTYPE ALML PUBLIC "-//Daniele Giacomini//DTD Alml//EN">
<alml lang="it" spacing="uniform">
<head>
<admin>
<description>An example for Alml documentation system</description>
<keywords>SGML, XML, HTML, Alml</keywords>
</admin>
<title>Example to use Alml</title>
<author>Pinco Pallino <pinco.pallino@brot.dg></author>
<date>2011.11.11</date>
<legal>
<p>Copyright © Pinco Pallino, <pinco.pallino@brot.dg></p>
<p>Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover
Texts, and with no Back-Cover Texts. A copy of the license is
included in the section entitled "GNU Free Documentation
License".</p>
</legal>
<maincontents levels="2">Table of contents</maincontents>
</head>
<intro>
<h1>
Introduction to the document
</h1>
<p>This document is written for... bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla...</p>
<p>Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla...</p>
</intro>
<body>
<h1 id="first-chapter">
Working with bla bla bla...
<indexentry>working with bla bla</indexentry>
<indexentry>bla bla</indexentry>
</h1>
<p>Working with bla bla is very easy... bla bla bla bla bla bla bla bla
bla bla bla bla bla...</p>
<p>Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla...</p>
<h2>
Do it better
</h2>
<p>There is also a better way to... bla bla bla bla bla bla bla bla bla
bla bla bla bla...</p>
<p>Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla...</p>
<h1 id="second-chapter">
Don't work any more
<indexentry>relaxing</indexentry>
</h1>
<p>If you don't work, you can relax, but you can do it only if you
already have enough money... bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla...</p>
<p>Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla...</p>
</body>
<appendix>
<h1>
Some notes
</h1>
<p>Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla...</p>
<p>Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla...</p>
</appendix>
<index>
<h1>
Index
</h1>
<printindex index="main">
</index>
</alml>
Se tutto viene copiato correttamente nel file ipotetico esempio.sgml, con il comando
$ alml --ps esempio.sgml
si ottiene la composizione in PostScript, attraverso LaTeX e Dvips. Nello stesso modo, con il comando
$ alml --html esempio.sgml
Si ottiene la composizione in HTML, su più file distinti.
L'utilizzo di Alml può generare file differenti a seconda del tipo di operazione che viene richiesta. La tabella 156.3 riepiloga questi file.
Tabella 156.3. File generati dall'utilizzo di Alml.
È bene sottolineare che i file indicati come nome .sgml e nome .css devono essere già presenti perché si possa usare Alml; inoltre, il sorgente SGML principale potrebbe a sua volta incorporare altri file SGML.
Se il sorgente SGML fa riferimento a immagini esterne, servono diverse versioni dei file relativi a seconda del tipo di composizione: PNG per la composizione in PDF; PostScript o EPS per la composizione in PostScript; JPG per la composizione in HTML. In generale, conviene prevedere una directory apposita per questi file, in modo da non essere intralciati quando la composizione in HTML genera la copia delle immagini richieste nella directory corrente, utilizzano i nomi nella forma n .jpg.
Il programma frontale attraverso cui si gestisce il sistema di composizione Alml è alml:
alml opzioni sorgente_sgml alml --help alml --version
Come si vede dal modello sintattico, a parte i casi delle opzioni --help e --version, è sempre richiesta l'indicazione di un file sorgente SGML, a cui applicare un qualche tipo di elaborazione.
--help
Mostra la guida rapida interna e conclude il funzionamento.
--version
Mostra le informazioni sulla versione e conclude il funzionamento.
--draft
Quando il contesto lo permette, serve per ottenere una composizione particolare, con più informazioni utili alla correzione o alla revisione del testo.
--compact
Quando il contesto lo permette, serve per ottenere una composizione compatta, risparmiando spazio.
--long
Quando si usa in abbinamento all'opzione --ps, cioè quando si vuole ottenere un risultato in formato PostScript, permette di ottenere una composizione speciale, a due colonne con il testo ridotto della metà. Di solito si abbina a questa anche l'opzione --compact.
--clean
Rimuove alcuni file temporanei abbinati al file sorgente indicato. Si tratta per la precisione di nome .aux e di nome .log.
--verbose
Segnala il procedere dell'elaborazione con informazioni dettagliate. In generale tali informazioni sono ottenibili dal file nome .diag; tuttavia, in presenza di file sorgenti di grandi dimensioni, può servire per sapere a che punto è l'elaborazione.
--derivation= derivazione
Permette di richiedere il filtro di una derivazione particolare. Si tratta di un nome attraverso il quale si stabilisce una porzione particolare del sorgente da prendere in considerazione (verrà spiegato meglio in seguito di cosa si tratta).
--sgml-include= entità_parametrica
Attraverso questa opzione, che può essere usata anche più volte, è possibile «includere» delle entità parametriche. Per la precisione, è come se nel sorgente venisse dichiarata un'entità parametrica corrispondente, assegnandole la parola chiave INCLUDE. Ciò viene usato per controllare l'inclusione di porzioni di sorgente, secondo le convenzioni dell'SGML.
--replace-char= carattere , rimpiazzo
Attraverso questa opzione, che può essere usata anche più volte, è possibile definire la sostituzione di un carattere con una stringa corrispondente. Può servire se nel sorgente viene usato sistematicamente un simbolo speciale con un significato differente da quello che dovrebbe avere. A puro titolo di esempio, si potrebbe immaginare di volere utilizzare l'asterisco per rappresentare lo spazio non interrompibile, che in condizioni normali si indica con la macro . Per questo si potrebbe usare l'opzione --replace-char="*, ".
--page-numbering={plain|default}
Questa opzione permette di definire in che modo gestire la numerazione delle pagine nei formati di composizione cartacei. In condizioni normali, la numerazione è realizzata attraverso sequenze differenti: una per la parte iniziale fino alla fine dell'introduzione, una per il corpo (comprese le appendici) e una finale per gli indici analitici. Assegnando la parola chiave plain si fa in modo che la numerazione sia unica, cosa che potrebbe essere conveniente per il formato PDF.
--sgml-syntax | --sgml-check
Una qualunque di queste due opzioni permette di ottenere la verifica formale del sorgente, in base al DTD.
--sp
Con questa opzione si vuole raggiungere solo un formato intermedio per il controllo diagnostico del funzionamento di Alml.
--tex | --latex
Con questa opzione si vuole raggiungere solo un formato intermedio in LaTeX per il controllo diagnostico del funzionamento di Alml.
--dvi
Genera un risultato in formato DVI.
--ps | --postscript
Genera un risultato in formato PostScript.
Genera un risultato in formato PDF.
--html
Genera un risultato in formato HTML, articolato in più file, dove il primo è nome .html e gli altri sono nome n .html. Inoltre, viene fatta una copia dei file delle immagini, secondo il modello n .jpg.
--html-text
Genera un risultato in formato HTML speciale, in un file unico, senza riferimenti a immagini esterne e con tabelle testuali. Il file ottenuto può essere consultato con Lynx e con questo può essere convertito in un testo puro e semplice, attraverso il comando:
lynx -dump -nolist -dont_wrap_pre nome .html > nome .txt
---------
--html-check | --html401-check
Se sono stati installati i file relativi, consente la verifica formale di un file HTML secondo le specifiche della versione 4.01.
--html320-check
Se sono stati installati i file relativi, consente la verifica formale di un file HTML secondo le specifiche della versione 3.2.
--xml
Se sono stati installati i file relativi, consente la verifica formale di un file XML secondo le specifiche del DTD relativo (attualmente solo XHTML).
Un file-make opportuno può facilitare l'uso di Alml. Viene proposto un esempio elementare, riferito al file example.sgml, in cui si può vedere anche l'utilizzo proposto di alml.
# file name prefix.
DOC_PREFIX=example
# Notice that "text" generates an HTML file with the same name
# for the first HTML page. This is why it is before the standard
# HTML typesetting.
#
all: \
clean \
text \
html \
ps \
longps \
pdf
clean:
@echo "Cleaning..." ; \
find . -name core -exec rm -f \{\} \; ; \
rm -f $(DOC_PREFIX)*.html ; \
rm -f $(DOC_PREFIX)*.tex ; \
rm -f $(DOC_PREFIX)*.dvi ; \
rm -f $(DOC_PREFIX)*.sp ; \
rm -f $(DOC_PREFIX)*.ps ; \
rm -f $(DOC_PREFIX)*.pdf ; \
rm -f $(DOC_PREFIX)*.txt ; \
rm -f $(DOC_PREFIX)*.log ; \
rm -f $(DOC_PREFIX)*.aux ; \
rm -f $(DOC_PREFIX)*.tmp ; \
rm -f $(DOC_PREFIX)*.diag ; \
rm -f *.bak ; \
rm -f *.jpg ; \
rm -f *\~
check:
@alml --sgml-check \
--verbose \
$(DOC_PREFIX).sgml
dvi:
@alml --dvi \
--verbose \
$(DOC_PREFIX).sgml
ps:
@alml --ps \
--verbose \
$(DOC_PREFIX).sgml
longps:
@alml --ps \
--verbose \
--compact \
--long \
--page-numbering=plain \
$(DOC_PREFIX).sgml
pdf:
@alml --pdf \
--verbose \
--page-numbering=plain \
$(DOC_PREFIX).sgml
html:
@alml --html \
--verbose \
$(DOC_PREFIX).sgml
text:
@alml --html-text \
--verbose \
$(DOC_PREFIX).sgml ; \
lynx -dump \
-nolist \
-dont_wrap_pre \
$(DOC_PREFIX).html \
> $(DOC_PREFIX).txt
Si può osservare in particolare l'obiettivo clean che elimina tutti i file non indispensabili.
Se si realizza un documento contenente immagini, può essere conveniente organizzare la cosa in modo da non doversi preoccupare della conversione nei vari formati. In generale conviene predisporre una directory apposita, per esempio img/, realizzando una sola serie di immagini in formato PNG. Nella stessa directory si potrebbero predisporre due script per automatizzare la conversione nei formati PostScript e JPG:
#!/bin/bash
# PNG2PS: to convert images from PNG to PS
for IMAGE in *.png
do
IMAGE=`basename $IMAGE .png`
if [ -e $IMAGE.ps ]
then
echo -n ""
else
convert $IMAGE.png EPSI:$IMAGE.ps
echo "$IMAGE.ps"
fi
done
#!/bin/bash
# PNG2JPG: to convert images from PNG to JPG
for IMAGE in *.png
do
IMAGE=`basename $IMAGE .png`
if [ -e $IMAGE.jpg ]
then
echo -n ""
else
convert $IMAGE.png $IMAGE.jpg
echo "$IMAGE.jpg"
fi
done
Come si vede si fa uso del programma convert del pacchetto che compone ImageMagick.
In base a questa organizzazione, si può estendere il file-make in modo da generare automaticamente i file necessari, a seconda del tipo di composizione richiesto. Si possono aggiungere due obiettivi, come quelli seguenti:
imagesps:
@cd img ; \
PNG2PS
imagesjpg:
@cd img ; \
PNG2JPG
Successivamente si possono modificare gli obiettivi che richiedono questa conversione:
dvi: imagesps
@alml --dvi \
--verbose \
$(DOC_PREFIX).sgml
ps: imagesps
@alml --ps \
--verbose \
$(DOC_PREFIX).sgml
longps: imagesps
@alml --ps \
--verbose \
--compact \
--long \
--page-numbering=plain \
$(DOC_PREFIX).sgml
html: imagesjpg
@alml --html \
--verbose \
$(DOC_PREFIX).sgml
Inoltre, nell'obiettivo che serve a eliminare i file superflui, si può aggiungere l'eliminazione dei file img/*.jpg e img/*.ps:
clean:
@echo "Cleaning..." ; \
find . -name core -exec rm -f \{\} \; ; \
rm -f $(DOC_PREFIX)*.html ; \
rm -f $(DOC_PREFIX)*.tex ; \
rm -f $(DOC_PREFIX)*.dvi ; \
rm -f $(DOC_PREFIX)*.sp ; \
rm -f $(DOC_PREFIX)*.ps ; \
rm -f $(DOC_PREFIX)*.pdf ; \
rm -f $(DOC_PREFIX)*.txt ; \
rm -f $(DOC_PREFIX)*.log ; \
rm -f $(DOC_PREFIX)*.aux ; \
rm -f $(DOC_PREFIX)*.tmp ; \
rm -f $(DOC_PREFIX)*.diag ; \
rm -f *.bak ; \
rm -f *.jpg ; \
rm -f *\~ ; \
rm -f img/*.ps ; \
rm -f img/*.jpg
A parte le differenze che ci possono essere nell'organizzazione di un DTD rispetto a un altro, Alml ha delle particolarità specifiche che vanno considerate.
La prima di queste è la possibilità di definire delle derivazioni diverse dello stesso documento, delimitando le parti attraverso dei commenti SGML appositi, nella forma:
<!-- START derivazione --> ... ... <!-- STOP derivazione -->
Si può intuire il significato di queste istruzioni particolari, con le quali si delimita una porzione di sorgente appartenente alla derivazione indicata. Si osservi che la dichiarazione dell'inizio di una derivazione, non conclude implicitamente le altre. In questo senso è utile che tali istruzioni abbiano la forma di commenti SGML, in modo che alla fine non interferiscano con l'analizzatore SGML stesso.
Se non si vuole usare questa possibilità, non è necessario dichiarare una derivazione, che in modo predefinito corrisponde al nome MAIN. In altri termini, è come se fosse sempre dichiarata all'inizio del sorgente l'istruzione
<!-- START MAIN -->
Oltre a questa particolarità di Alml, va considerato l'elemento verbatimpre, il cui scopo è quello di contenere testo da riprodurre letteralmente. L'SGML consentirebbe l'utilizzo di sezioni marcate di tipo CDATA; tuttavia questa possibilità può essere valida se il sistema di composizione successivo è in grado di accettare l'informazione letterale. Alml gestisce simultaneamente due sistemi di composizione antagonisti: LaTeX e HTML; per questa ragione, si è preferita una soluzione differente, in cui l'elemento che si intende debba contenere testo letterale, viene in realtà preparato prima dell'analisi SGML. Per questa ragione, l'elemento verbatimpre va usato in un modo preciso:
<verbatimpre> ... ... ... </verbatimpre>
In pratica, occorre che i marcatori che delimitano l'elemento siano usati da soli in una riga, iniziando dalla prima colonna.
Textchk e Urichk, descritti rispettivamente nel capitolo 155 e nella sezione 145.4, possono essere usati facilmente con Alml. In generale, si passa per una composizione in formato HTML singolo, quindi si utilizzano questi programmi. Supponendo di avere generato il file mio_file.html:
$ textchk --input-type=html mio_file.html mio_file.tchk mio_file.tdiag
$ urichk --input-type=html mio_file.html mio_file.uri.html
Per usare Ispell, è conveniente generare prima una versione del documento in formato testo puro. Per questo si potrebbe usare Lynx, ma all'interno del pacchetto di Alml è disponibile uno script speciale, in grado di convertire opportunamente un file HTML per questo scopo. Si tratta di HTML2TXTSPELL:
HTML2TXTSPELL < file_html > file_testo_non_formattato
In particolare, per evitare problemi con Ispell, nel file che si ottiene sono eliminate la barre oblique inverse (\).
Naturalmente, usando poi Ispell nel file generato in questo modo, non ha senso fare delle correzioni, che invece vanno applicate al sorgente originale, in modo manuale.
Il file LaTeX generato da Alml tende a richiedere risorse impreviste a TeX. È molto probabile che per documenti di dimensioni medie, sia necessario espandere i limiti posti dalla configurazione di TeX.
In generale, si dovrebbe disporre di una distribuzione teTeX, per la quale si interviene nel file texmf/web2c/texmf.cnf (eventualmente potrebbe trattarsi meglio di /etc/texmf/texmf.cnf, o simile).
Qui vengono annotate le modifiche che si sono rese necessarie per riuscire a completare la composizione di Appunti di informatica libera, così da permettere al lettore di comprendere dove potrebbe essere necessario intervenire.
%... %main_memory = 263000 main_memory = 1000000 %... %hash_extra = 0 hash_extra = 100000 %... %pool_size = 125000 pool_size = 1000000 %... %string_vacancies = 25000 string_vacancies = 100000 %... %max_strings = 15000 max_strings = 100000 %... %pool_free = 5000 pool_free = 500000 %... %nest_size = 100 nest_size = 200 %... %save_size = 4000 save_size = 100000 %...
Al termine delle modifiche a questo file, occorre ricordare di lanciare il comando texconfig init, con i privilegi dell'utente root:
# texconfig init
Le distribuzioni normali di TeX potrebbero non essere in grado di gestire un gran numero di comandi \label, anche se si tenta di intervenire sulla configurazione. Questo si traduce in pratica in un limite insuperabile per ciò che nella configurazione viene mostrato come la variabile save_size. Se ci si trova in questa situazione, per esempio quando si ottiene un messaggio del tipo seguente,
! TeX capacity exceeded, sorry [save size=40000].
avendo magari impostato il file texmf.cnf con un limite superiore, occorre procurarsi i sorgenti di teTeX e intervenire nel file texk/web2c/tex.ch. Dovrebbe esserci una riga simile a quella seguente:
@!inf_save_size = 600; @!sup_save_size = 40000;
Evidentemente bisogna aumentare il valore assegnato a sup_save_size, per esempio come nel caso seguente:
@!inf_save_size = 600; @!sup_save_size = 100000;
Per queste cose conviene usare i sorgenti predisposti per la propria distribuzione GNU, in modo da ottenere alla fine l'eseguibile tex pronto per sostituire quello già installato in precedenza, attraverso pacchetti già pronti.
Appunti di informatica libera 2001.01.30 --- Copyright © 2000-2001 Daniele Giacomini -- daniele @ swlibero.org1) Alml GNU-GPL
2) Questo capitolo e i successivi descrivono il sistema di composizione Alml. 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.
3) Nelle distribuzioni Debian si tratta del pacchetto liblocale-gettext-perl.
Dovrebbe essere possibile fare riferimento a questa pagina anche con il nome alml_preparazione_e_visione_generale.html
[successivo] [precedente] [inizio] [fine] [indice generale] [licenze] [indice analitico] [tomo] [parte]