Najznámejším a najpoužívanejším systémom pre tvorbu používateľskej dokumentácie je DocBook. Tento otvorený nástroj postavený nad otvorenými technológiami ponúka systém písania štruktúrových dokumentov použitím SGML alebo XML. Špeciálne je predurčený na písanie kníh zaoberajúcich sa počítačovým hardvérom a softvérom, ale rozhodne nie je limitovaný len na túto oblasť. DocBook je SGML definícia typu dokumentu (Document Type Definition - DTD). Mnoho známych firiem ako napr. TcX (tvorcovia databázového systému MySQL) alebo TrollTech (tvorcovia grafickej knižnice QT2) používa pre dokumentovanie svojich produktov vlastné nástroje. Odhliadnuc od ostatných faktorov môže byť výsledkom použitia vlastného dokumentačného systému pomerne ťažké a komplikované zlepšovanie a rozširovanie dokumentácie od rôznych prispievateľov. Preto sa používanie otvorených technológií v procese vytvárania dokumentácie považuje za vysoko žiadúce a silne produktívne. DocBook dokument je písaný použitím tzv. značkovacích jazykov (markup languages) ako je SGML a XML. DocBook existuje v oboch týchto verziách. Podobne ako pri HTML dokumentoch sa špecálnymi značkami (tagmi) označujú jednotlivé miesta alebo elementy. V prípade HTML dokumentu sa však pomocou značiek definuje dizajn a výzor výsledného dokumentu (zmena farby, zmena písma, zvýraznenie a pod.). V DocBook dokumente neexistuje žiadna značka manipulujúca priamo s dizajnom. Dokument je štruktúrovaný logicky, čiže označované sú časti s rovnakým významom (napr. mená súborov, premenných, produktov, ľudí, atď.). Výsledný dizajn je komponovaný pomocou jazyka DSSSL (Document Style Semantics and Specification Language), ten však nie je pre bežného používateľa podstatný. Rozdiely medzi XML verziou a SGML verziou DocBook sú minimálne. Okrem odlišnej hlavičky dokumentu a rôznej implementácii asi dvoch tagov sú obe verzie úplne identické. Podstatný rozdiel je v samotnom spracovaní dokumentu. Pri SGML verzii sa používa Jade Wrapper (jw) a pri XML verzii nástroje postavené nad knižnicou libxml2. My vo svojich príkladoch budeme používať SGML verziu. Základný dokument vyzerá nasledovne: 2002-12-09 s týmto podnadpisom Text prvej kapitoly. ]]> DocBook dokument (book) sa delí na kapitoly (chapter), sekcie v kapitolách (sect1) a podsekcie (sect2). Podsekcie možu mať ďalšie podsekcie (sect3, sect4). Kapitoly je možné združovať pomocou tagu part. Podobne viac kníh je možné spojiť do kompaktného celku pomocou tagu set. > Text. Text. Text. Text. ... ]]> Ako už bolo spomenuté, DocBook dokument má logickú štruktúru podľa významu. Značky sa používajú na označovanie výrazov alebo slov rovnakého typu. Označujú sa teda napríklad mená súborov, premenných, konštánt, funkcií, príkazov, produktov. Ďalej tiež e-mailové adresy alebo odkazy na webstránky. Je možné tiež vytvárať zoznamy alebo tabuľky, vkladať obrázky, atď. /etc/passwd stdio.h $selected_user BUFFER_SIZE proctable_init() grep jade DocBook platon@pobox.sk Platon SDG ]]> Na poslednom príklade je vidieť možnosť skracovania jednoduchých SGML tagov pomocou ukončovacej značky </>. Medzi najvýznamnejšie výhody DocBook dokumentácie patrí aj veľký počet možných formátov výstupných dokumentov. Sú to najmä HTML, RTF, PDF, PS, TeX, čistý text a manuálové stránky. Generovanie prebieha pomocou programu jade (predpokladáme vygenerovanie súboru myfile.html zo súboru myfile.sgml). $ jade -d /usr/lib/sgml/stylesheets/dbtohtml.dsl -t sgml myfile.sgml > myfile.html Nie je nutné používať priamo analyzátor jade. Existujú už predpripravené shell skripty pre generovanie konkrétnych typov výstupných súborov. Sú to napr. db2html, db2pdf, ale aj docbook2tex či docbook2txt. Takže pre vygenerovanie HTML dokumentácie stačí použiť nasledovný príkaz. $ db2html myfile.sgml Vzhľad výsledného HTML dokumentu sa jednoducho prispôsobuje použitím CSS (Cascading Style Sheets).