Kapitola 2. Systémy používateľskej dokumentácie softvéru

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:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ ]>
<book lang="sk">
<bookinfo>
	<date>2002-12-09</date>
	<title>Môj prvý DocBook dokument</title>
	<subtitle>s týmto podnadpisom</subtitle>
</bookinfo>

<chapter>
<title>Nadpis prvej kapitoly</title>

<para>Text prvej kapitoly.</para>

</chapter>
</book>

<chapter><title>Nadpis prvej kapitoly</title>
	<sect1><title>Prvá sekcia v prvej kapitole</title>>
		<sect2><title>Prvá podsekcia v prvej sekcii</title>
			<para>Text. Text. Text. Text.</para>
		</sect2>
		<sect2><title>Druhá podsekcia v prvej sekcii</title>
		</sect2>
	</sect1>
	<sect1 ...>
		<para> ... </para>
	</sect1>
</chapter>

<filename>/etc/passwd</filename>
<filename class=headerfile>stdio.h</filename>
<varname>$selected_user</varname>
<constant>BUFFER_SIZE</constant>
<function>proctable_init()</function>
<command>grep</command>
<application>jade</application>
<productname>DocBook</productname>
<email>platon@pobox.sk</email>
<ulink url="http://www.platon.sk/">Platon SDG</>