Archivio > Standards, Linux e Open Source > Singolo: DocBook, critica ad un sistema di documentazione

DocBook, critica ad un sistema di documentazione

DocBook is an XML/SGML vocabulary particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications).

DocBook è un vocabolario XML/SGML particolarmente adatto a descrivere libri e manuali incentrati su hardware e software (sebbene non sia limitato esclusivamente a quest'uso).

In altre parole, DB non è nient'altro che una grammatica DTD di tipo SGML/XML che si propone come strumento per la scrittura di documentazione specialmente in ambito Linux.

Negli ultimi giorni, grazie al progetto Archlinux Handbook, ho avuto modo di studiarne approfonditamente la sintassi, leggendo le specifiche per ogni elemento, e le relazioni che vi sono fra ognuno di essi.

Nonostante tutta la fiducia che nutro nei confronti di questo progetto, DocBook mi lascia titubante sotto molti aspetti: vediamo quali.

Cifre

DocBook vanta oltre 350 tags disponibili. Nel mio precedente articolo ho parlato di modularità, sottolineando quanto, personalmente, ritenessi importante suddividere le specifiche di un documento XML in più moduli tra loro separati ed eventualmente combinati assieme per realizzare sottoinsiemi di natura più complessa, utili soprattutto a livello individuale.

Questo concetto può essere applicato anche nel contesto attuale. Un unico DOCTYPE, specialmente con cifre come queste, può risultare scomodo e sembrare quasi trascurato per uno sviluppatore, rispetto ad una famiglia di document types composta da più moduli. Il vantaggio di questo secondo metodo è che possiamo gestire con più facilità set di elementi DocBook, potendo decidere quali usare, dove, e naturalmente come combinarli assieme anche nello stesso documento. Inoltre, questo non ci vieta affatto di creare schemi XML diversificati da più namespace, in modo tale da aggirare ogni tipo di problema derivante da conflitti fra tag omonimi.

Consideriamo ad esempio di voler separare la bibliografia da ogni altra cosa. Perchè caricare l'intera specifica? Basterebbe individuare il modulo correlato, impostare il namespace corretto (se necessario), e iniziare a scrivere l'albero XML.

Insomma, la scelta di sfornare quasi trecento tag senza un minimo di organizzazione è abbastanza criticabile. Da ammirare per le scelte in ambito semantico, ma questo è un discorso che tratterò in maniera più approfondita.

Nomenclatura

Vi invito a considerare il nome attribuito ad alcuni elementi DocBook:

  1. ArtPageNums, ovvero Il numero di pagina di un articolo quand'è pubblicato
  2. AuthorBlurb, ovvero Una breve descrizione/nota sull'autore
  3. BridgeHead, ovvero Intestazioni svincolate dalla gerarchia a sezioni
  4. QandASet, ovvero Un contenitore di domande/risposte
  5. ShortAffil, ovvero Una breve descrizione di un'affiliazione

Questi sono solo alcuni degli esempi che potrei presentare come prova della mia riluttanza. Quello che ho notato io, in particolare, è che:

  • Alcuni elementi hanno nomi incomprensibili. Merito di una specifica dovrebbe essere quello di presentare in maniera più immediata possibile lo scopo di ogni singolo componente. DocBook purtroppo in alcuni casi non sembra esserne all'altezza.
  • Alcuni elementi sono ridondanti e hanno nomi banali. Ne esistono almeno 4 terminanti con *Div. Perchè non usarne uno solo, flessibile, riutilizzabile in più contesti?
  • Alcuni elementi sono, come conseguenza del punto precedente, inutili e confusionari. Non ha senso inventarsi nomi incomprensibili semplicemente perchè si ignora la possibile portabilità di ogni componente.

Semantica

Questo è l'argomento che mi sta più a cuore. Se c'è un merito da dare a DocBook, allora quello consiste nella capacità di aver sintetizzato in differenti elementi differenti contenuti semantici. Prendo l'esempio di ToC o Callout, che rispettivamente marcano una tabella riassuntiva dei contenuti, e una lista di chiamate esterne (potremmo definirle come note immediatamente consequenziali ad una porzione di testo, per esempio alla sinossi di un comando).

La scelta insomma di arricchire le specifiche con una gerarchia semantica ben studiata è da tenere in considerazione per future reinterpretazioni anche in altri sottolinguaggi di marcamento derivati da XML. Come sempre, però, c'è un ma.

Infatti, più volte si rischia con DocBook di dover scegliere fra due o più elementi semanticamente talmente simili da diventare spesso ambigui, quasi superflui. E' il caso di Synopsis e CmdSynopsis, di Epigraph e BlockQuote, di Para e FormalPara.

A questo punto sorge spontanea la domanda: Quali sono i vantaggi di questa scelta?. Mi spiego meglio: fino a quando è conveniente scegliere quale elemento utilizzare, se la differenza risiede solo in qualche lieve, spesso impercettibile, sfumatura di significato semantico?

Per questo motivo non mi trovo completamente d'accordo con le specifiche DocBook. La semantica ha senso solo in quei contesti dove il contenuto non è arricchito, ovvero dove c'è poca profondità d'informazione. Il rischio è quello di non fermarsi mai, di cogliere ogni minima differenza cercando di evidenziarla nella maniera meno banale possibile. Questa eccessiva accuratezza tuttavia può scatenare effetti indesiderati. Immaginiamo, per assurdo, di utilizzare parser precostruiti per dare una formattazione predefinita al codice. Il problema può nascere laddove l'utente si trovi di fronte a presentazioni differenti di contenuti apparentemente uguali per tipo: la macchina percepisce il cambiamento, lo sviluppatore pure - suo malgrado; e il lettore?

La proposta

Sulla base di quanto ho già detto precedentemente, quindi, la proposta sarebbe quella di sfruttare - in futuro - le specifiche XHTML 1.1/2.0 assieme alle potenzialità di un sistema modulare, per poter usufruire dei componenti ideati dal team W3C. Optare per una scelta di questo tipo avrebbe effetti benefici sui tempi di realizzazione di una specifica: il compito si ridurrebbe alla creazione di estensioni XHTML da aggiungere all'inizio del documento per poter creare sottoinsiemi e combinazioni più complesse di un sistema iniziale, da ripubblicare eventualmente anche sotto altro nome.

Le possibilità a questo punto sono infinite. Aggiungo, rimuovo, modifico moduli in base alle mie esigenze. Il codice assume un evidente rigore, una certa schematicità, offrendo a chi lo consulta maggiori chanches di comprensione e riutilizzo.

E' necessario, insomma, sfruttare specifiche già esistenti, garantendo una certa flessibilità nella sintassi, una maggior fruibilità dei componenti (qualcuno potrebbe volerli includerli nel proprio sistema locale), e di conseguenza più chiarezza nell'organizzazione e distribuzione degli elementi dichiarati. Cose che, a mio parere, trovano poco spazio in DocBook.

Approfondimenti

L'articolo è stato di tuo gradimento? Puoi controllare che vi sia altro di tuo interesse nelle categorie e , oppure iscriverti al notiziario RSS e seguirmi su per restare sempre aggiornato sulle ultime pubblicazioni.

Pubblicato lunedì 28 maggio 2007.

Discuti

Il blog è in sola lettura.

Paginatura: