Hlavní navigace

DocBook a jeho použití

Jan Pavlovič

Psaní dokumentace v DocBoku se stává v současnosti velice populárním způsobem, jak napsat dokumentaci. O jeho výhodách svědčí použití u takových projektů jako PHP, Gnome, KDE, Linux aj. Co to DocBook je, se pokusí objasnit následující článek.

Na začátku bylo XML

XML (eXtensible Markup Language) bezesporu patří k často skloňovaným pojmům dneška. O XML jako o značkovacím jazyku není třeba psát dlouhé pojednání. Kam se dnes podíváme, narážíme na XML. XML není jen prostředek pro výměnu dat, dají se pomocí něho psát i dokumenty, Právě k tomu byla vytvořena značkovací množina DocBook.

DocBook versus HTML

Ať se to nemusí zdát na první pohled zřejmé, DocBook a HTML (HyperText Markup Language) jsou vlastně dvě sestřičky. Obě to jsou podmnožiny XML. K popisu toho, jak má jejich struktura vypadat, slouží gramatika. Mezi nejznámější formy gramatiky patří DTD (Document Type Definition). XML samo o sobě slouží hlavně k logickému označkování textu. Takže obecně nemusí být známo, jak má být třeba takový text označený elementem <p> zobrazen. V případě HTML mají prohlížeče tuto informaci integrovanou v sobě, ale v případě DocBooku nic takového neexistuje. Pokud chceme zobrazit dokument označkovaný pomocí DocBooku, musíme dodat další informace o výsledném vzhledu. Jedním ze způsobů je transformace do nějaké zobrazitelné podoby, jakou je například HTML, PDF či RTF.

Transformace

Jak je možné zkonvertovat dokument v DocBooku do HTML? Tuto prozatím magickou operaci umožňují (mimo jiné) XSL transformační styly. Jedná se opět o XML soubory, které umožňují každému elementu v XML (v našem případě v DocBooku) zadefinovat, na co se má převést, např.:

DocBook: <para>Hello World</para>

změní XSL styly pro transformaci DocBooku do HTML na:

<p>Hello World</p>

a tak dále.

Následující obrázek ukazuje, jak celá transformace zhruba probíhá.

schéma transformace

1. Nejprve se zkontroluje, zdali daný dokument odpovídá gramatice (validita). K tomu slouží nástroj zvaný parser.

2. Dále se provede transformace do formátu, který XSL styly umožňují, k tomu slouží procesor. Ten, stejně jako parser, může být buď binární program, nebo, jak je v poslední době velice moderní, napsaný pod Javou (existují i implementace v Perlu, Pythonu atd.)

Tak a máme dokument v požadované formě, v případě HTML je celý proces u konce. Jak je patrné z obrázku, existují i styly, které nám umožňují dokument v DocBooku převést do LaTexového zdrojáku. Ten můžeme následně přeložit kvalitním typografickým nástrojem pdftex a získat dokument v PDF. Existují i jiné možnosti, jak získat PDF, přes FO (Formatting Objects), což je poněkud „XMLčtější“ :), ale o něm někdy jindy.

A proč vlastně DocBook?

Podíváme se na případ, kdy chceme napsat nějakou technickou dokumentaci. Ideální je, aby byla lehce napsatelná, upravitelná a každý si ji mohl jednoduše prohlédnout. Ideálním se může zdát HTML. Ale proč se zbytečně tolik namáhat, když existuje DocBook? Oproti HTML je DocBook jednodušší, protože obsahuje pouze logické elementy. Tím do dokumentu zadáme jen čistě logické informace a zjednodušíme si tím práci, jelikož nemusíme myslet na výslednou podobu a můžeme se plně soustředit na obsah. Vizuální podobu pak můžeme snadno zvládnout pomocí CSS stylů, které k výslednému transformovanému HTML přiřadíme. Snadno tak získáme standardizovaný vzhled všech našich dokumentů. Zcela ideální je použití DocBooku pro psaní dokumentace v týmu, zajistíme tak standardní vzhled dokumentace všech členů týmu, aniž bychom je zatěžovali s požadovanou výslednou vizuální podobou. Nemá smysl zbytečně DocBook přechvalovat, nejlepší je ho vyzkoušet a udělat si svůj názor. I když použití DocBooku pro dokumentace v projektech jako PHP, KDE aj. také třeba o něčem svědčí :).

Bakalářská a diplomová práce v DocBooku?

Ano, DocBook lze bez problému použít i pro vytvoření bc. nebo dipl. práce. Jednak získáme typograficky kvalitní PDF (klidně standardizované do podoby dané fakultou) pomocí pdftexu, a to bez větších znalostí LaTeXu, jednak i HTML, jehož podobu můžeme opět standardizovat (CSS styly). Lze získat i RTF dokument, ale o tom, stejně jako o generování slajdů, třeba příště.

Pokud se chcete sami přesvědčit, jak taková věc funguje, stačí se podívat http://www.fi­.muni.cz/~xpa­vlov/xml na fakultu informatiky MU, kde je možnost své bc. a dipl. práce tvořit v DocBooku.

Našli jste v článku chybu?
20. 5. 2016 7:36
ufik (neregistrovaný)

Toto je oficialni zneni prohlaseni o puvodnosti dila, ktere je predepsano a musi byt soucasti vsech zaverecnych praci na FI MU.