8. Migration tools

Il secondo grande problema con DocBook è dato dagli sforzi necessari per convertire il vecchio presentation markup nel nuovo markup di DocBook. Un essere umano non avrebbe alcuna difficoltà a riconoscere in un documento le sue diverse strutture logiche, questo perché può capire dal contesto quando, ad esempio, il corsivo è utilizzato per evidenziare qualcosa e quando invece serve a riportare una citazione del tipo 'questa è la frase di qualcuno'.

In qualche modo, quando vogliamo convertire i documenti in DocBook, queste distinzioni devono essere rese esplicite. Qualche volta sono già prensenti nel vecchio markup, ma spesso non lo sono, e la mancanza di questa informazione strutturale deve essere quindi dedotta da algoritmi euristici o introdotta a mano dall'uomo.

Di seguito è riportato un riepilogo sullo stato dei vari strumenti di conversione utilizzati per i vari formati:

GNU Texinfo

La Free Software Foundation ha deciso di utilizzare DocBook come un formato di interscambio. Texinfo ha strutture a sufficienza per realizzare conversioni automatizzate di buona qualità, e la versione 4.x di makeinfo mette a disposizione l'opzione --docbook che genera direttamente documenti in DocBook. Per avere maggiori informazioni, consultate la pagina del progetto makeinfo.

POD

Esiste un modulo POD::DocBook che traduce i documenti scritti nel markup POD (Plain Old Documentation) in DocBook. Ufficialmente implementa tutti i tag POD eccetto il tag L<> italic. La pagina man dice anche "liste del tipo nested-over e nested-bask inserite nei documenti non sono gestite in Docbook", ma si noti che il modulo è stato ampiamente testato.

LaTeX

LaTeX è, principalmente, un insieme di macro in linguaggio structural markup costruito sul formatter TeX. Esiste un programma, chiamato TeX4ht, che riesce a generare DocBook a partire da documenti LaTeX (questo secondo l'autore di PassiveTeX).

Pagine man e altri markup tipo troff

Questo è generalemente considerato il più grosso e difficile problema di conversione. Infatti troff(1) è un markup di così basso livello di presentazione che è molto difficile ottenere da strumenti automatici una conversione dignitosa. Tuttavia, la visione così buia della cosa può essere schiarita pensando a sorgenti di documentazione scritti con le macro del pacchetto man(7). Questi infatti utilizzano caratteristiche di struttura sufficienti per ottenere conversioni in modo automatico.

Ho scritto un programma per fare proprio questo, anche perché non sono riuscito a trovare nient'altro che facesse un lavoro almeno decente (il problema è molto interessante). L'ho chiamato doclifter. Dovrà riuscire a produrre DocBook XML o SGML a partire da sorgenti scritti per man(7), mdoc(7), ms(7), o me(7). Leggete la documentazione per maggiori informazioni.