[zdl-devel] sistema di documentazione per ZDL (primo punto)

[Gianluca Zoni]

ciao,
è praticamente completo il sistema per la documentazione di ZDL,
(al primo punto del programma)
che prevede:

- l'ipertesto HTML all'indirizzo http://nongnu.org/zdl
- (quasi) lo stesso ipertesto per "info" (o "pinfo" o via
  Emacs...): info zdl
- la "man page": man zdl
- un help più semplificato: zdl --help

L'aggiornamento di tutta questa documentazione avviene da un
unico sorgente in formato texinfo, che è il "GNU documentation
system", potenziato da una serie di comandi compatibili con
makeinfo, che permettono a "texi2man" (un mio nuovo progetto in
attesa di approvazione su savannah-gnu) di estrarre parti di
testo dal sorgente texi/texinfo, di riordinarle, ricomporle e
"transcodificarle" in formato groff (formato delle man pages), per
creare una pagina di manuale in stile Unix, diversa
dall'ipertesto in info/html. 
Restano da modificare ancora i contenuti (e l'aspetto del sito),
ma questa è una faccenda che richiede tempo e che non ha mai fine.

In generale, tutto questo nasce da una duplice necessità:
1) spostare l'intero sistema della documentazione ecc. su una
   struttura "pubblica" (la stessa del progetto di sviluppo, di
   cui sto cercando di usare meglio gli strumenti che fornisce)
2) unificare l'aggiornamento di tutte le forme di comunicazione
   in una sola azione, a partire da un solo testo in un solo
   sorgente (in passato, ogni volta dovevo aggiornare 
   separatamente troppe cose... poi ZDL è cresciuto e stava
   diventando un'immane rottura di scatole)


C'è un'altra cosa (che rientra nell'idea di usare gli strumenti
di savannah): il sito web (utilizzando, per ora, uno script
esterno) pubblica le "Ultime notizie" del progetto di
sviluppo (il feed RSS
https://savannah.nongnu.org/news/atom.php?group=zdl). In questo 
modo, possiamo aggiornare le news (novità tecniche di vario tipo)
direttamente dal sistema di savannah-gnu, 
senza rigenerare subito l'intera documentazione.

La politica di savannah è molto restrittiva rispetto a un sacco
di cose: non si possono realizzare siti dinamici (per questo ho
optato per un dinamismo in locale: generando il sito statico con
makeinfo --html) e l'unico strumento consentito per l'upload
delle pagine html è cvs (!)

Per semplificare la rigenerazione della documentazione e l'upload
delle pagine html si può comunque ricorrere ad un piccolo script
(a dire il vero, mi sono creato uno script zdl-update che sta
diventando sempre più imponente: rigenera la documentazione,
carica il sito, si occupa dei sorgenti su git e carica i file sui
mirror).

Last but not least, l'aspetto del sito http://nongnu.org/zdl è in
via di elaborazione. La testata (forse un po' troppo psichedelica)
rappresenta la curva di Peano: lo zigzag che attraversa tutte le
dimensioni (la linea che diventa un piano, che diventa uno spazio
a 3 dimensioni, che...). Abbiamo lasciato anche in sospeso
l'invenzione del logo (l'anno scorso abbiamo fatto dei tentativi
interessanti). Si potrebbe discutere e ridiscutere  di tutte
queste cose, senza impegno, quando ci viene in mente un'idea...

-- 
Z O N I N O Z
Gianluca Zoni

address@hidden
http://inventati.org/zoninoz
http://savannah.gnu.org/users/zoninoz