DocBook

DocBook je formát založený na SGML/XML pro zápis textových dokumentů, které obvykle slouží jako dokumentace k softwaru. Není však omezen jen na dokumentaci, lze v něm zapisovat téměř libovolný druh textových dokumentů, tento článek byl konec konců, stejně jako všechny mé ostatní články, připraven právě v DocBooku.

Co to znamená, že je DocBook založený na SGML/XML? SGML i XML jsou obecné značkovací jazyky, s jejichž pomocí je možné definovat další již specializované jazyky. Příkladem takto odvozeného jazyka je například HTML, které se používá pro tvorbu webových stránek. Z SGML HTML zdědilo základní syntaktická pravidla – jak se zapisují jednotlivé tagy apod. Zároveň je definováno, jaké značky lze vlastně v HTML použít. DocBook si můžete představit stejně jako HTML – jediný rozdíl je v tom, že DocBook obsahuje speciální značky pro tvorbu dokumentace, kdežto HTML má značky určené pro tvorbu webových stránek. Pokud chceme vytvářet vlastní dokumenty v DocBooku, musíme se naučit značky a to, k čemu se používají. Díky založení na SGML/XML není DocBook svázán s žádnou konkrétní platformou, a můžeme ho proto používat ve Windows, v unixu a na jakémkoliv jiném systému.

Ještě než se podíváme na detaily syntaxe DocBooku, povíme si něco málo o historii a současném využití DocBooku. Uvidíte, že DocBook není jen můj oblíbenec, ale technologie, která se používá již velmi dlouho a v mnoha důležitých projektech.

DocBook vznikl v roce 1991 jako formát založený na SGML, určený pro výměnu unixové dokumentace (především manuálových stránek). U jeho zrodu stály firma HaL Computers a nakladatelství O'Reilly. O vývoj a údržbu formátu se staralo sdružení Davenport. V 90. letech DocBook používalo mnoho velkých firem, které se podílely i na jeho vývoji (např. Novell, Digital, Hewlett-Packard, SCO, Fujitsu).

V roce 1999 se péče o DocBook přesunula pod hlavičku sdružení OASIS. Aktuální verze DocBooku nese číslo 4.2 a existuje ve dvou verzích – pro SGML a pro XML. My se budeme v článku zabývat především XML verzí DocBooku, protože je XML přece jen perspektivnější než SGML. Většina informací o XML verzi DocBooku však platí i pro SGML verzi.

Kde se DocBook dnes používá? Bezpochyby největší skupinou uživatelů jsou open source projekty. V DocBooku je například napsána dokumentace k operačním systémům Linux a FreeBSD, ke grafickým prostředím KDE a Gnome, ke skriptovacímu jazyku PHP a mnoha dalším. Z komerčních firem jej používají velká počítačová nakladatelství jako O'Reilly nebo velké softwarové firmy (např. Sun pro tvorbu dokumentace používá podmnožinu DocBooku pojmenovanou SolBook).

Když se podíváte na ukázku 1 – „Ukázka dokumentu v DocBooku“, zjistíte, že zápis dokumentu v DocBooku je velmi podobný HTML stránce. Dokument začíná deklarací typu dokumentu, která určuje použitou verzi DocBooku. Za ní pak následuje samotný dokument, který se pomocí elementů člení na základní bloky jako jsou kapitoly, podkapitoly a přílohy. DocBook umožňuje vytvářet knihy, sady knih, články, referenční příručky. Existují i upravené verze DocBooku, které se hodí pro vytváření slidů nebo celých webů.

<?xml version='1.0' encoding='windows-1250'?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN' 
          'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'>
<book lang="cs">
  <bookinfo>
    <title>První pokusná kniha</title>
    <author>
      <firstname>Jiří</firstname>
      <surname>Kosek</surname>
    </author>
  </bookinfo>
  <preface>
    <title>Úvod</title>
    <para>Odstavec textu.</para>
    <para>Druhý odstavec</para>
  </preface>
  <chapter>
    <title>První kapitola</title>
    <para>Text první kapitoly</para>
    <para>Další odstavec</para>
  </chapter>
  <chapter>
    <title>Druhá kapitola</title>
    <para>Text druhé kapitoly</para>
    <para>Další odstavec</para>
  </chapter>
  <appendix>
    <title>První příloha</title>
    <para>Text přílohy</para>
    <para>Další odstavec</para>
  </appendix>
</book>

DocBook obsahuje skoro 400 elementů. Kromě elementů pro základní členění dokumentů v něm samozřejmě najdeme elementy pro vytváření běžných struktur používaných v dokumentech, jako jsou seznamy, odkazy a tabulky. Problémem samozřejmě není ani vkládání obrázků. Obrázky se vkládají tak, že se vloží odkaz na soubor s obrázkem v nějakém grafickém formátu. K jednomu obrázku můžeme mít několik variant – např. bitmapovou a vektorovou. Použije se pak formát vhodný pro dané výstupní médium – při tisku se použije vektorový obrázek, při konverzi do HTML se použije bitmapa.

Největší síla DocBooku však spočívá v inline elementech. Ty umožňují označit jednotlivé části podle toho jaký mají význam – název funkce, jméno souboru, parametr metody, emailová adresa, klávesová zkratka, položka menu atd. Na základě těchto informací lze velmi snadno automaticky generovat rejstříky funkcí, přehledy klávesových zkratek apod. Následující odstavec v DocBooku obsahuje ukázku několika elementů označujících význam textu.

<para>Pro správný chod programu je potřeba nastavit proměnnou
prostředí <envar>APPHOME</envar>. Na unixu proměnnou nastavíme
příkazem <command>APPHOME=/usr/local/app; export APPHOME</command>, ve
Windows pak v <application>Ovládacích Panelech</application> tak, že
v položce <guimenuitem>Systém</guimenuitem> vybereme volbu
<guibutton>Prostředí</guibutton>. Uživatelská jména se ukládají do
souboru <filename>/etc/passwd</filename>, moje emailová adresa je
<email>jirka@kosek.cz</email> a na standardní výstup můžeme zapisovat
funkcí <function>printf</function>. Počítač se vypíná stiskem
<keycombo action="simul"><keycap>Ctrl</keycap><keycap>Alt</keycap>
<keycap>Del</keycap></keycombo>.</para>

Nebojte se však toho, že byste se nazpaměť museli učit několik set elementů. Ve většině dokumentů si vystačíte s pár desítkami elementů, které si časem postupně zapamatujete. Navíc dobrý XML editor vám s vkládáním elementů pomůže. Použití jednotlivých elementů, včetně ukázek, je velmi důkladně popsáno v referenční příručce DocBooku, knize DocBook – The Definitive Guide, která je zdarma dostupná i v elektronické podobě na adrese http://www.docbook.org.

Dokumenty v DocBooku nejsou nic jiného než XML dokumenty, které opět nejsou ničím jiným než obyčejnými textovými soubory. Pro přípravu dokumentů tedy můžete použít libovolný textový editor, klidně Poznámkový blok. Samozřejmě, že pro serióznější práci využijete pohodlné prostředí XML editoru.

Do nejkomfortnější kategorie editorů patří WYSIWYG XML editory, které jsou schopné dokument během editace zobrazovat i naformátovaný. Navíc jsou obvykle přizpůsobené pro DocBook tak, že nejběžnější prvky dokumentu, jako seznamy, tabulky a obrázky, lze vkládat stejně jednoduše a uživatelsky příjemně jako ve Wordu nebo obdobném textovém procesoru. XML editor se přitom sám stará o vložení správných XML značek. Tyto editory jsou vhodné zejména pro uživatele, kteří jsou schopni vytvářet strukturované dokumenty, ale nepřejí si pracovat přímo se zdrojovým kódem dokumentu v XML. Mezi nejznámější zástupce této kategorie patří editory Epic, XMetaL a epcEdit, podobný komfort by měl nabídnout i nově ohlášený FrameMaker 7.0.

Obrázek 1. Komerční XML editory nabízejí velmi pohodlné a příjemné prostředí i pro vytváření hodně strukturovaných dokumentů v DocBooku

Ti kdo mají hluboko do kapsy a nechtějí si pořizovat komerční vizuální editory, jejichž ceny začínají někde okolo 500 dolarů, mohou sáhnout po nevizuálních XML editorech, kde autor pracuje přímo se zdrojovým kódem v XML. Pro některé uživatele je tento způsob práce nepohodlný, na druhou stranu po určitém zacvičení je i tak velmi produktivní. Asi nejpoužívanějším editorem této kategorie je Emacs s nadstavbou PSGML. Editor je schopný načíst k dokumentu DTD (definici elementů použitelných v dokumentu) a autorovi pak ke vložení nabízí jen elementy, které jsou na daném místě přípustné. Zejména pro DocBook s velkým množstvím elementů je tato pomoc nedocenitelná.

V poslední době s „podporou“ DocBooku přišly i textové procesory jako LyX a AbiWord. Ty se však pro seriózní práci s DocBookem vůbec nehodí, protože neumožňují ovlivnit vkládané elementy a nedovolí tak správně označkovat informace v dokumentu. Pouze jedním, přesně definovaný způsobem mapují vizuální styly editoru na vybrané elementy DocBooku.

Možná se ptáte, proč připravovat dokumentaci pracně v DocBooku, zdržovat se vkládáním značek, když jde dokument pohodlněji napsat ve Wordu, párkrát kliknout myší a vytisknout. Ano, pokud dokument chcete jen vytisknout, a nic s ním dál nedělat, klidně ho připravte tímto způsobem. Síla DocBooku (a XML obecně) je ve snadné konverzi do dalších formátů. Primární vytvoření označkovaného dokumentu je obvykle o něco málo pracnější než u klasických textových dokumentů, ale tato práce se rychle vrátí v případech, kdy potřebujeme dokument publikovat v několika odlišných formátech.

Viděli jsme, že dokumenty v DocBooku vůbec nepostihují jejich vizuální vzhled, ale samotnou podstatu informace. Když potřebujeme dokument vytisknout nebo třeba zobrazit v prohlížeči, musíme ho nejprve zformátovat. V XML se k tomu používá mechanismus tzv. stylových jazyků. Ty umožňují velmi jednoduše popsat, jak se mají jednotlivé elementy zformátovat. Na základě tohoto popisu, kterému se říká styl, pak může stylový procesor naše dokumenty zformátovat. Pokud si stylů uděláme více, můžeme z jednoho dokumentu dostat několik výstupních podob – ty se mohou lišit svým vzhledem nebo výstupním formátem (RTF, PDF, HTML, HTML Help apod.).

Největší výhodou DocBooku je právě existence již hotových stylů, které jsou k dispozici zdarma a umožňují zcela automatický převod dokumentů do následujících formátů:

Při převodu do HTML si navíc můžeme vybrat převod do jednoho velkého HTML souboru, nebo převod do několika menších HTML stránek, kdy je dokument po kapitolách nebo podkapitolách „rozsekán“ do menších souborů. Existují i další konverzní programy, které jsou schopné DocBook převést do manuálových stránek, či formátů LaTeX a Texinfo.

Pro formátování DocBooku dnes existují dvě standardní sady stylů – DSSSL a XSL. Obě jsou ke stažení na adrese http://docbook.sourceforge.net, navíc většina linuxových distribucí styly již přímo obsahuje v podobě instalačních balíčků. Do stylů jsou přitom neustále přidávány nové funkce, a přibližně jednou za měsíc je k dispozici nová verze.

DSSSL styly jsou historicky starší a k jejich zpracování se používá program Jade, případně OpenJade. Styly existují ve dvou verzích – pro výstup do HTML a pro tištěný výstup. Jade přitom jako výstupní formáty pro tisk podporuje RTF, FrameMaker a TeX (z TeXu pak můžeme generovat PDF a PostScript). DSSSL styly jsou v současné době ještě hodně používané, zejména ze setrvačnosti, protože jsou k dispozici o několik let déle než XSL styly. Bohužel roky jazyka DSSSL jsou pomalu sečteny, protože kromě programů Jade/OpenJade neexistují žádné další implementace. Vývoj Jade je již ukončen, a práce na jeho pokračovateli OpenJade stagnují. Většina vývojářů je dnes zaměřena na novější jazyk XSL, který nabízí i větší možnosti než DSSSL.

Obrázek 2. Některé z cest, jak z DocBooku dostat výstupní formát

XSL styly, podobně jako ty DSSSL, nabízejí dvě základní skupiny stylů – pro výstup do HTML a pro tisk (ten se realizuje přes formátovací objekty XSL FO). Ze stylů pro výstup do HTML jsou pak odvozeny další styly – pro XHTML, JavaHelp a HTML Help. Pro práci s XSL styly potřebujeme nějaký XSLT procesor, nejlépe se osvědčily Saxon a xsltproc. Pokud chceme používat i výstup pro tisk, musíme mít ještě procesor formátovacích objektů – např. FOP, XEP nebo PassiveTeX. Budoucnost zcela jednoznačně patří XSL stylům a to zejména kvůli jejich širokému přijetí v celém IT odvětví – již dnes existuje několik XSLT i FO procesorů. XSLT styly pro generování HTML jsou již dnes lepší než ty DSSSL, u tištěného výstupu je zatím postup přes formátovací objekty slabší, protože všechny FO procesory jsou mladé programy, které ještě nestačily vyzrát a implementovat všechny možnosti formátovacích objektů.

Obrázek 3. Výstup do RTF je samozřejmostí

Kdyby se vám výstupy generované standardními styly nelíbily, můžete je ovlivňovat pomocí velkého množství parametrů. Ty určují, způsob číslování kapitol a podkapitol, jestli se má automaticky generovat obsah, jaká se použijí písma, jak budou velké okraje a mnoho dalších. V situacích, kdy už parametry nestačí, lze požadované změny dosáhnout přepsáním celých šablon, které obsluhují jednotlivé elementy.

Obrázek 4. Vygenerované HTML stránky mezi sebou mají samozřejmě navigační odkazy

Výstupům do HTML a do on-line formátů se v podstatě nedá nic vytknout. O něco slabší je už tištěný výstup. Pomocí standardních stylů a volně dostupných nástrojů sice získáme výstup, který nikoho neurazí, ale pokud jsou naše požadavky na design tištěného výstupu velké, musíme sáhnout po jiném řešení. Jelikož jsou situace, kdy nejde kvalitní sazbu plně automatizovat, je často používán jiný způsob vytváření tištěné verze dokumentu. Dokument se před finální sazbou nejprve převede do RTF nebo podobného formátu standardními styly. Takto nahrubo zformátovaný dokument se pak načte do DTP programu, kde sazeč provede finální zlom a grafickou úpravu stránek. Je to samozřejmě dražší a pomalejší proces než zcela automatická sazba, ale vyšší kvalita výsledku je znát.

Obrázek 5. Formát HTML Help je výhodný zejména pro uživatele – obsahuje přehledný hierarchický obsah, rejstřík a navíc fulltextové vyhledávání

Pro mnoho lidí je již samotná možnost automatického generování několika výstupních formátů z jedné předlohy dostatečnou výhodou pro přechod od proprietárních systémů k DocBooku. Kromě toho nabízí DocBook i další poměrně unikátní vlastnosti, které oceníte zejména při psaní dokumentace k větším a složitějším systémům.

Pokud vytváříte dokumentaci k modulárním systémům, je potřeba dokumentaci stejně tak jako celý program přizpůsobit přání zákazníka. Tím, že dokumenty v DocBooku jsou XML dokumenty, můžeme je rozdělit na několik menších souborů, které se pak skládají dohromady. Jednotlivé soubory přitom můžeme použít v několika dokumentech – do samostatných souborů tak můžeme uložit části dokumentace, které se používají opakovaně – různé typografické konvence, dokumentace k často používaným modulům apod. Při aktualizaci daného textu pak stačí opravy provést na jednom místě a automaticky se promítnou na všech místech, kde se fragment dokumentu používá.

V mnoha dalších případech naopak potřebujeme z jedné předlohy generovat několik obsahově drobně odlišných verzí dokumentů. Například uživatelská příručka k programu, který je k dispozici ve verzích pro Windows a pro Linux, se bude patrně lišit jen v pár bodech týkajících se instalace a konfigurace. Je kvůli tomu zbytečné vytvářet a udržovat sladěné dva samostatné dokumenty. Stejně tak můžeme mít kromě standardní dokumentace, také příručku doplňovanou o aktuální postřehy z pracoviště technické podpory. Opět je asi vhodnější tyto dokumenty uchovávat v jednom, aby byly naprosto synchronizované.

Většinou je tedy jednodušší vytvářet dokument jen jeden a v něm označit části určené pro konkrétní platformu nebo skupinu uživatelů. Při generování výsledné podoby dokumentu pak provedeme profilaci, či chcete-li přizpůsobení cílově skupině. Z dokumentu se vyberou pouze jeho odpovídající části. DocBook k těmto účelům nabízí speciální atributy pro označení cílové skupiny. Stylům pak v parametru můžeme při generování výstupního formátu předat identifikaci cílové skupiny a styly se postarají o správné odfiltrování nepotřebných částí vstupního dokumentu.

DocBook lze použít i pro vytváření programátorské dokumentace, ne jen té uživatelské. Obsahuje speciální elementy pro popis prototypů funkcí a tříd, a můžeme tedy ručně celou dokumentaci napsat. Mnoho projektů však dnes dokumentaci zapisuje přímo do strukturovaných komentářů ve zdrojových textech, ze kterých se pak dokumentace automaticky generuje. Např. v Javě k tomuto účelu slouží program JavaDoc. Existují programy, které jsou schopné ze zdrojových textů generovat přímo DocBook. Popisnou část dokumentace tak můžeme napsat ručně a pak k ní připojit automaticky vygenerovaný popis knihoven. To vše pak můžeme standardními nástroji konvertovat do mnoha výstupních formátů.

V omezeném prostoru vyhrazeném pro článek jsem vás samozřejmě nemohl naučit vytvářet a zpracovávat dokumenty v DocBooku, ostatně to ani nebylo záměrem článku. Ve vloženém rámečku „Jak se naučit DocBook?“ najdete odkazy na podrobnější informace o DocBooku. Doufám však, že již nyní máte alespoň představu o tom, jaké výhody přináší tvorba dokumentů v XML, obzvláště pak v DocBooku, pro který existuje velké množství již hotových stylů a aplikací.

Pro první seznámení s DocBookem je asi nejlepší začít přečtením asi jediného ucelenějšího návodu v češtině DocBook – Stručný úvod do tvorby a zpracování dokumentů. Kromě popisu principu DocBooku zde najdete i popis nejpoužívanějších elementů a parametrů XSL a DSSSL stylů. Nechybí ani ukázky konverze dokumentů do nejběžnějších formátů, popis instalace nástrojů nezbytných pro práci s DocBookem a odkazy na další zdroje informací (ty jsou již převážně jen v angličtině). (Abychom byli korektní, musíme čtenáře informovat o tom, že autorem tohoto dokumentu je autor článku.)

V případě nějakých problémů je nejlepší spojit se s ostatními uživateli DocBooku a požádat je o radu a jejich zkušenosti. Slouží k tomu mailové diskusní fórum <docbook@linux.cz>, pro přihlášení do něj stačí poslat e-mail na adresu <docbook-subscribe@linux.cz>. List je dostupný rovněž jako diskusní skupina news cz.comp.text.docbook.