Di per sé, Alml nasce proprio per far fronte alle esigenze di un grande progetto di documentazione, pur essendo adatto anche a cose molto brevi. Il problema di un «grande progetto» non sta necessariamente nelle dimensioni di questo, quanto sulla gestibilità da parte di un singolo. È a questo proposito che Alml diventa veramente utile, in quanto consente di mettere tutte le proprie cose in un solo documento.
Solo mettendo assieme tutto, si ha la certezza di non perdere qualcosa. Forse non ci sarà la convenienza di pubblicare una raccolta che contiene ricette di cucina assieme a poesie e ad altri appunti, ma il singolo, ha sicuramente dei vantaggi a raccogliere tutto in un solo file SGML.
Si può obbiettare che il rischio di perdere i dati, se questi risiedono in un solo file, sia troppo alto. Ma se il problema è solo questo, basta avere l'accortezza di salvare usando un nome che contiene anche la data e un numero di serie (per esempio mio-20120131001.sgml, mio-20120131002.sgml, ecc.), controllando periodicamente le differenze tra il primo e l'ultimo file, prima di cancellare le copie obsolete (diff -u mio-20120131001.sgml mio-20120131045.sgml | less). Un'altra obiezione simile sta nella difficoltà di gestire un solo file enorme in un sistema CVS o simile, ma qui si parte dal presupposto che si tratti del lavoro di un singolo, il quale non ha alcuna convenienza a gestirselo tramite un sistema come quello.
Il vero problema, semmai, sta nel poter estrapolare delle porzioni del documento principale, per stampare o pubblicare solo ciò che serve (per esempio solo le ricette, solo le poesie, ecc.). In questo capitolo si vuole mostrare come si può organizzare il proprio lavoro in modo da mettere tutto assieme, con la possibilità di fare la composizione tipografica di una sola porzione che può servire per uno scopo preciso.
Alml include un programma realizzato in modo particolare per lo sviluppo di a2, con lo scopo di eseguire alcune operazioni di routine. Attraverso l'opzione --sgml-extract è possibile estrapolare una porzione di file SGML, delimitata con dei segni appropriati. Per esempio, si osservi il comando seguente:
$ a2engine --sgml-extract=sub-music.sgml example.sgml[Invio]
In questo modo, viene letto il file example.sgml, collocato nella directory corrente, generando il file sub-music.sgml, contenente le porzioni del file di partenza, delimitate tra i commenti speciali seguenti:
<!-- COPY TO "sub-music.sgml" START --> ... ... <!-- COPY TO "sub-music.sgml" STOP -->
Naturalmente, le porzioni che generano un file, possono essere più di una, ripetendo le inserzioni appena mostrate.
Il file che contiene inserzioni di questo tipo, può indicare più blocchi con nomi diversi, che possono tranquillamente accavallarsi (a differenza delle sezioni marcate che possono solo annidarsi).
Una volta estratte le copie che servono del contenuto del file SGML principale, queste potrebbero essere aggregate assieme (anche attraverso comandi come cat) in un altro file SGML temporaneo. In pratica, con qualche script si può organizzare il prelievo sistematico e la composizione tipografica di porzioni dedicate del lavoro complessivo.
Nella documentazione che accompagna Alml c'è un esempio di un progetto di documentazione che prevede l'estrapolazione di porzioni più piccole: doc/example-project/. L'esempio è ridotto al minimo, ma serve a far comprendere il meccanismo.
Il documento complessivo è contenuto nel file example.sgml che ha la struttura seguente:
|
Inizialmente appare un'entità parametrica, da usare per isolare delle sezioni all'interno del documento, quindi inizia il contenuto del documento.
Si suppone di voler estrapolare due argomenti per poterne ottenere una composizione indipendente: vengono individuati i due blocchi per generare i file sub-music.sgml e sub-listings.sgml. Pertanto, nel sorgente principale vengono inseriti dei commenti di questo tipo:
|
|
Viene preparato un altro file, che inizia in modo simile a example.sgml, ma che è privo di contenuti, in quanto è fatto per incorporare un file esterno, denominato sub-example-content.sgml. Inoltre, in questo file manca il titolo dell'opera, che viene letto da un file esterno, denominato TITLE. Si suppone che questo file che si affianca a example.sgml, si chiami example-head.sgml:
|
Vanno osservate le righe 4 e 5, dove sono state aggiunte le dichiarazioni delle entità interne sub-example-content e WORKNAME. Nella riga 13 si vede l'utilizzo dell'entità WORKNAME; nella riga 31 si vede l'utilizzo di sub-example-content.
A questo punto si prepara una struttura di sottodirectory, per generare la composizione selettiva delle porzioni del documento principale. Si predispone precisamente projects/music/ e project/listings/. In ognuna di queste due directory si predispongono dei collegamenti simbolici a tutto ciò che serve dalla directory principale, dove risiede il file SGML complessivo. Per esempio così:
|
Si osservi che in questo caso c'è un collegamento al file example-head.sgml, che però è stato nominato convenientemente example.sgml. Infatti, si intende riutilizzare il file-make principale.
Nelle directory servono anche altri due file: TITLE, che viene modificato in base al titolo che si vuole dare alla riduzione da comporre; inoltre serve uno script per attivare l'estrapolazione delle porzioni volute dal sorgente principale. Questo script potrebbe avere il contenuto seguente, che si riferisce precisamente all'estrazione di sub-music.sgml:
|
Come si comprende, è facile estrapolare anche porzioni più articolate dal sorgente principale, modificando in modo appropriato tale script; in pratica, alla fine occorre disporre di un solo file denominato sub-example-content.sgml.
Così come è possibile estrapolare qualcosa da un documento più complesso, è possibile anche aggregare in un documento già grande, delle porzioni di altri lavori (ammesso di averne ricevuto il permesso). Il meccanismo da usare è simile, in quanto si inseriscono dei commenti per l'estrapolazione delle porzioni desiderate nei file sorgenti esterni, quindi, nel sorgente che li deve accogliere, si dichiarano delle entità interne associate ai file di tali porzioni. Infine, si deve predisporre uno script appropriato, che, prima della composizione, esegua automaticamente l'estrazione di ciò che serve dagli altri documenti.
Questo meccanismo di aggregazione viene usato per a2, allo scopo di includere alcune opere di altri autori.
«a2» 2013.11.11 --- Copyright © Daniele Giacomini -- appunti2@gmail.com http://informaticalibera.net