Il buon Emanuele Aina mi ha chiesto come fare a riversare in HTML la documentazione per i traduttori. Dopo qualche giorno ecco qui, per la gioia di tutti, come fare ad usare i fogli di stile ufficiali di GNOME per convertire i file XML-DocBook in HTML.

Premessa: in un sistema GNU/Linux ben configurato è possibile effettuare tale conversione semplicemente invocando il comando db2html nomefile.xml. Solo che in questo modo si perde un po' in formattazione.

Dunque, per procedere si ha necessità di tre ingredienti:

1. Il file XML DocBook del manuale da convertire. Ad Emanuele serviva il documento relativo all'introduzione ai PO (che ricordo essere ancora in stadio di bozza), ciò non toglio che ogni file XML DocBook che fa parte della documentazione di GNOME possa essere convertito
2. Il pacchetto docbook-xsl alla versione 1.45. Tale pacchetto non è più disponibile per il download su sourceforge.net (per lo meno non dalla pagina del progetto docbook, magari esporando in FTP si trova...). Usando GOOGLE l'ho trovato qui, ma potete cercarlo anche altrove.
3. I fogli di stile forniti dal GDP. Li trovate sul CVS, sotto gnome-docu/gdp/xsl (per cui dovete dare il comando cvs -z3 co -d :pserver:anonymous@anoncvs.gnome.org:/cvs/gnome gnome-docu/gdp/xsl)

Ora che avete tutti i componenti bisogna procedere a:

• installare docbook-xsl
• applicare qualche piccola modifica (per lo meno a me è stata necessaria) ai fogli di stile del GDP
• generare i file HTML

Per installare il pacchetto docbook-xsl (installare per tutti gli utenti, ovvio; dovrebbe essere possibile installarli anche solo per un utente senza privilegi, ma non so come creare il catalogo xml personalizzato), procedere come segue:

• spacchettare il file docbook-xsl-1.45.tar.gz
• entrare nella directory docbook-xsl-1.45
• creare una directory in cui installare i file. Sulla mia Ubuntu ho proceduto con il comando install -v -d -m755 /usr/share/xml/docbook/stylesheet/1.45/ Per altre distribuzioni controllare il percorso in cui sono è già installato il pacchetto docbook-xsl-1.6X e regolarsi di conseguenza
• installare i file necessari nella directory appena create. Sulla mia Ubuntu ho proceduto con il comando cp -v -af VERSION common/ extensions/ fo/ html htmlhelp/ images/ javahelp/ lib/ template/ xhtml/ /usr/share/xml/docbook/stylesheet/1.45/
• passare alla directory in cui si è appena copiato i file (/usr/share/xml/docbook/stylesheets/1.45 per me) e impostare a root il proprietario ed il gruppo dei file installati (chown -R root:root .)
• Aggiornare il catalogo XML (sulla mia Ubuntu è il /etc/xml/catalog) in modo da usare i fogli di stile appena installati xmlcatalog --noout --add "rewriteSystem" "http://docbook.sourceforge.net/release/xsl/1.45" "/usr/share/xml/docbook/stylesheet/1.45/" /etc/xml/catalog
• Completare l'aggiornamento (parte 2 di 2) del catalogo col lievemente diverso xmlcatalog --noout --add "rewriteURI" "http://docbook.sourceforge.net/release/xsl/1.45" "/usr/share/xml/docbook/stylesheet/1.45/" /etc/xml/catalog
  

A questo punto il sistema in uso sarà in grado di usare i docbook-xsl presenti in /usr/share/xml/docbook/stylesheet/1.45/ quando i fogli di stile del GDP chiederanno di usare cose da http://docbook.sourceforge.net/release/xsl/1.45. Nota: l'installazione è necessaria perché la versione 1.45 non è più disponibile via Internet :-(

Passiamo ora al secondo punto: la modifica dei fogli di stile del GDP. Questa modifica si è resa necessaria a causa di alcuni errori che si sono evidenziati nella conversione XML~HTML.

• nei file admonitions.xsl copyright.xsl e toc.xsl cambiare le varie stinghe doc:type="boolean" in type="boolean"
• nel file general-customization.xml rimuovere o commentare la riga numero 16 (quella con il tag xsl:include che ha come opzione href="titlepage.xsl"
  

Non so se è il modo corretto di procedere per togliere quegli errori che mi venivano evidenziati. Però, almeno sul mio sistema, funziona. :-)

A questo punto si è pronti per la conversione XML~HTML. Spostarsi nella directory dove è posizionato il file XML da convertire, e dare il comando

xsltproc -o outputdir/ percorso/gnome-docu/gdp/xsl/general-customization.xsl file-da-convertire.xml

Nella directory outputdir/ verrano creati i file HTML. Per completare il tutto, all'interno di outputdir/ andrebbe creata una directory stylesheets/ con i file PNG per le icone (caution.png - important.png - note.png - tip.png - warning.png - gnome-logo-icon.png). I file possono essere recuperati dalla propria distribuzione: gnome-logo-icon.png è in /usr/share/pixmaps, gli altri, sebbene con nomi un po' diversi sono installati da Yelp. Nei prossimi giorni li impacchetterò e li metterò a disposizione assieme alla documentazione sul mio spazio Web.

Ora devo scrivere ad Emanuale per comunicargli che le istruzioni le trova qui...

PS: quasi quasi converto in HTML la guida per l'ammistrazione e la guida per l'accessibilità dello GNOME Desktop e le metto in rete...

PPS: perdonate la pessima formattazione del testo :-|