Se avete letto la prima parte della mia serie di articoli sulla riprogettazione di gentoo.org, sapete che sono il Chief Architect di Gentoo Linux, autonominatomi responsabile del sito web di Gentoo Linux. Allo stato attuale, il sito lascia un po' a desiderare. Si, per certi versi, sembra attraente ma, se guardate dietro la grafica, vedrete che in realtà non risponde alle necessità dei suoi primari destinatari: gli sviluppatori di Gentoo Linux, gli utenti, potenziali e no.

L'ultima volta, ho usato la progettazione orientata all'utente (User-Centered Design) per creare un set di priorità per il sito e usare queste per creare un piano d'azione per migliorare gentoo.org. Due sono in cima alla lista: una nuova documentazione per gli sviluppatori e una nuova mailing list per comunicare agli sviluppatori i cambiamenti fatti nella nostra repository CVS. Mentre aggiungere la nuova mailing list per CVS era relativamente facile (ma più difficile di quanto pensassi, come vedremo), la nuova documentazione per sviluppatori richiedeva molta pianificazione e lavoro.

Inoltre, non solo era necessario creare della documentazione aggiornata (un obiettivo che avevo ignorato per troppo tempo), ma dovevo scegliere una sintassi XML ufficiale che il nostro nuovo modello di documento doveva usare. Vedete, fino a poche settimane fa, la documentazione era scritta solo con HTML. Usare solo HTML è una cosa superata perché i contenuti (le informazioni) sono mischiate con la presentazione (i tag per la grafica HTML). E che cosa avevo ottenuto? Un grande disordine. Era difficile aggiornare la documentazione attuale ed estremamente difficile migliorare il sito scritto in HTML.

In questo articolo, mostrerò con orgoglio la soluzione per la nuova e flessibile documentazione XML del sito, ma prima, descriverò come abbiamo aggiunto una mailing list per CVS al nostro sito.

L'obiettivo della mailing list per i cambiamenti nel CVS è informare gli sviluppatori dei cambiamenti fatti nella nostra repository CVS. Poiché avevo già il mailman mailing list manager (vedere Risorse) installato, pensavo che creare una nuova mailing list fosse facile. Prima avrei semplicemente creato la mailing list, poi aggiunto l'appropriato "aggancio" alla repository CVS, cosi che le email sarebbero state automaticamente generate e spedite, descrivendo i cambiamenti fatti ai nostri sorgenti.

Innanzitutto, ho iniziato cercando un file speciale nella mia CVSROOT della repository chiamato "loginfo". In teoria, modificando questo file potevo istruire CVS ad eseguire uno script quando una modifica era aggiunta alla repository ed effettivamente delle email venivano spedite alla nuova mailing list "gentoo-cvs" ogni volta che delle modifiche erano fatte ai nostri sorgenti.

Sfortunatamente questa soluzione non era come speravo che fosse. Prima di tutto generavo molti messaggi email (uno per ogni modifica) e secondariamente i messaggi erano criptici e qualche volta vuoti! Velocemente rimossi il mio script loginfo e bloccai temporaneamente il progetto mailing list gentoo-cvs. Chiaramente l'aggancio al file loginfo di CVS non era appropriato per i miei scopi e ho dovuto lavorare molto per rintracciare tutta la documentazione relativa al loginfo che poteva aiutarmi a risolvere il problema.

Parecchie settimane dopo ho cominciato a cercato una alternativa al loginfo. Questa volta ho astutamente cercato in http://freshmeat.net dove ho trovato proprio quello che cercavo: il meraviglioso script Perl cvs2cl.pl disponibile in http://red-bean.com (vedere Risorse). Invece di usare un aggancio al loginfo, cvs2cl.pl usa il comando cvslog per collegarsi direttamente alla repository ed estrarre le appropriate informazioni dal log. Inoltre, non utilizza i messaggi relativamente criptici del log CVS, ma fa un grande lavoro di riformattazione in un formato leggibile di ChangeLog:

2001-04-09 20:58  drobbins
      * app-doc/gentoo-web/files/xml/dev.xml: new fixes
2001-04-09 20:47  drobbins
      * app-doc/gentoo-web/: gentoo-web-1.0.ebuild,
      files/pyhtml/index.pyhtml, files/xml/gentoo-howto.xml: new gentoo-howto
      fixes
2001-04-09 20:03  drobbins
      * app-doc/gentoo-web/files/xml/dev.xml: typo fix
2001-04-09 20:02  drobbins
      * app-doc/gentoo-web/files/pyhtml/index.pyhtml: little update

cvs2cl.pl può anche essere istruito per generare un output in formato XML e nel mio prossimo articolo mostrerò i vantaggi di questa cosa per generare un aggiornamento del ChangeLog nella nuova sezione del nostro sito.

Di seguito c'è lo script che io uso per generare le email con il ChangeLog giornaliero. Prima cambia la directory di lavoro mettendosi nella repository del CVS da controllare. Poi crea le variabili d'ambiente $yesterday e $today che contengono le date nel formato RFC822. Notate che entrambe le date hanno l'ora fissata alle 00:00. Queste variabili sono, a turno, usate per creare la variabile $cvsdate che sono passate a cvs2cl.pl per specificare il range di tempo che interessa (l'arco di tempo tra la mezzanotte di ieri e di oggi).

Ho anche creato la variabile $nicedate (usata nell'oggetto della email) ed usato mutt, in modo mailx compatibile (vedere Risorse), per spedire le email alla mailing list gentoo-cvs.

#!/bin/bash
cd /usr/portage
cvs -q update -dP
yesterday=`date -d "1 day ago 00:00" -R`
today=`date -d "00:00" -R`
cvsdate=-d\'${yesterday}\<${today}\'
nicedate=`date -d yesterday +"%d %b %Y %Z (%z)"`
/home/drobbins/gentoo/cvs2cl.pl -f /home/drobbins/gentoo/cvslog.txt -l "${cvsdate}"
mutt -x gentoo-cvs -s "cvs log for $nicedate" <\
/home/drobbins/gentoo/cvslog.txt

Usando cron, eseguo questo script ogni notte a mezzanotte. Grazie a cvs2cl.pl, ora i miei sviluppatori hanno un accurato e leggibile aggiornamento giornaliero dei cambiamenti in CVS.

Ora il progetto per la documentazione di Gentoo Linux. Oggi il nostro sistema di documentazione coinvolge due gruppi di persone o destinatari: i redattori della documentazione e i lettori. I redattori hanno bisogno di una sintassi XML ben progettata; i lettori, che possono non preoccuparsi dell'XML, vogliono una documentazione in HTML che sia funzionale e attraente. La sfida è realizzare un sistema completo che risolva le necessità di entrambi i destinatari. Oh, supponiamo che ci sia un terzo tipo di persone: le persone che progettano il nuovo sistema, il webmaster ed io. Poiché dobbiamo interagire con il nuovo sistema di documentazione ogni volta che il sito venga aggiornato, abbiamo bisogno che sia sicuro e flessibile.

Prima parliamo dell'HTML web-ready che sarà generato dal mio modello XML. Per essere una grande documentazione leggibile sarà necessario avere il supporto di adeguati tag XML. Per esempio, deve esserci la possibilità di inserire note, messaggi importanti e avvertimenti nel corpo del testo (ed avere la loro prominente grafica sul restante HTML). Inoltre, si deve essere in grado di inserire blocchi di codice e potrebbe essere bello se l'input potesse essere in qualche modo evidenziato in modo automatico. Si potrebbe perfino aggiungere dei tag che evidenzino il codice sorgente in un colore diverso cosi che i blocchi di codice siano più leggibili.

I documenti dovrebbero avere un indice (con collegamenti ai capitoli), una sinossi, una data di revisione, una versione e una lista degli autori. Certamente ogni documento deve contenere anche un header in cima alla pagina contenente un piccolo logo di Gentoo Linux. Cliccando su questo logo si dovrebbe tornare alla pagina principale di Gentoo Linux. Ultimo ma non meno importante, ogni documento dovrebbe avere un footer che contenga le informazioni di copyright con un indirizzo email per i contatti.

Quella era una pesante lista di richieste e ho deciso di concentrarmi inanzitutto sulla parte più importante: il nuovo logo di Gentoo Linux che appare nell'angolo superiore sinistro della documentazione di Gentoo Linux. Ho usato la "g" grafica di "gentoo" (creata usando l'eccellente e libero programma Blender 3D) della nostra pagina principale come base per il nuovo piccolo logo. Ho manipolato il logo un poco e aggiunto una colorazione cromata, posizionato al meglio le luci e la prospettiva: il nuovo logo era completo. Importato in Xara X (vedere Risorse) e aggiunto il testo, ecco il risultato:

Dopo molto lavoro e commenti favorevoli da parte di alcuni degli sviluppatori, il nuovo sistema di documentazione era pronto per l'uso. Ho iniziato a lavorare immediatamente a lavorare sulla nostra prima nuova guida per lo sviluppo, "The Gentoo Linux Documentation Guide", "Guida alla documentazione di Gentoo Linux", (xml-guide.html), che contiene una completa descrizione del nuovo formato XML. Non solo questa permetteva agli altri sviluppatori di iniziare a lavorare con il nuovo stile della documentazione, ma serviva come un eccellente esempio del nuovo sistema in azione. Assicuratevi di leggere questa guida per comprendere interamente la nostra sintassi XML.

Se state lavorando con la vostra documentazione, potreste anche voler considerare i formati DocBook XML e SGML (vedere Risorse). DocBook è molto adatta per grandi raccolte di documentazione tecnica e per libri, molto flessibile, con molte (forse troppe) opzioni. Inoltre ci sono un grande numero di pacchetti esistenti che possono essere usati per convertire DocBook XML/SGML in pagine di man, file di testo, Postscript, PDF, e naturalmente formato HTML.

Io non ho scelto DocBook perché una sintassi XML leggera era migliore per le necessità di Gentoo. Il numero limitato di tag facilitano la trasformazione delle guide XML in un altro formato come HTML, e anche assicurano un certo livello di consistenza dell'intera documentazione, proprio perché il formato è semplice. Poiché ho il mio formato XML, sarà semplice estendere il formato con nuovi tag se necessario. Amo mantenere il controllo. Io intendo XML come una tecnologia che dovrebbe essere usata dalle persone per strutturare i loro dati nel modo che loro trovano più utile. In altre parole, l'abilità di definire i propri elementi e attributi è una cosa preziosa e io dovrei ottenere tutti i vantaggi da esse. Dopo tutto, è la caratteristica per definizione di XML.

Certamente, creare la propria sintassi XML non è sempre la soluzione migliore, specialmente quando lo scambio di dati è importante per voi. Tra tutto il gran parlare di XML, una cosa spesso trascurata è che la conversione tra differenti formati XML può essere estremamente difficoltosa. In molti casi, i due formati non saranno compatibili al 100% e dovrete spiacevolmente scegliere di eliminare dati o metadati, intenzionalmente evitando l'uso di certi elementi, oppure di creare un superformato che accomoderà i dati e i metadati da entrambi i formati. Con la documentazione mondiale, DocBook è una discreta scelta come "superformato" poiché è molto flessibile e può facilmente accomodare documenti importati da diverse fonti.

Tuttavia, la ricchezza e la flessibilità di DocBook può anche creare problemi. Per esempio, ci potrebbero essere centinaia di tag dei quali potreste non avere mai bisogno, e supportare tutti questi tag nel vostro XSLT può rendere la conversione in altri formati più difficile. Cosi, mentre DocBook è un grande contenitore per documenti da convertire in altri formati, la nostra minima sintassi XML sarà quasi sempre più facilmente convertibile in altri formati.

La cosa più importante è valutare con attenzione ogni possibile soluzione quando le necessità dei vostri destinatari vi saranno note.

Con il nuovo sistema di documenti pronto, sono stati convertiti tutti i nostri documenti nel nuovo formato e messi nel sito esistente. Inoltre è stato creato un collegamento alla nuova pagina per la sottoscrizione alla mailing list gentoo-cvs. Qui il punto è che ho integrato queste caratteristiche nel sito esistente cosi che gli utenti potessero beneficiare di questi miglioramenti fin da subito.

• Leggete gli altri articoli in questa serie di developerWorks sulla riprogettazione del sito web www.gentoo.org usando tecnologie come XML, XSLT e Python:
  • Nella Parte 1, l'autore crea un piano d'azione orientato all'utente e introduce pytext, un interprete Python integrato (Marzo 2001).
  • Nella Parte 3, crea un nuovo look per il sito (Luglio 2001).
  • Nella Parte 4, Daniel completa la conversione XML/XSLT, fissa un bug di compatibilità del browser Netscape 4.x e aggiunge un autogenerato XML Changelog al sito (Agosto 2001).
• Se non avete ancora usato python, potete farvi del male da soli. Lo trovate al http://www.python.org.
• Controllate Xara.com, la home page di Xara X, un eccellente programma per il disegno vettoriale per Windows. Non troppo grosso e velocissimo, ha la mia personale raccomandazione.
• Impara di più su XSLT
• Quando ti svegli, controlla Sablotron, un veloce processore XSLT disponibile su Gingerall
• Puoi trovare il magnifico cvs2cl.pl lo script da CVS a ChangeLog in Red-Bean
• Impara di più su DocBook in http://www.docbook.org
• Se stai cercando un ottimo mailing list manager, date sicuramente un'occhiata a Mailman
• Controllate www.mutt.org per la più recente versione del programma per email Mutt.