DocBook a jeho využití Tomáš Pitner, Jan Pavlovič, FI MU

DocBook a jeho využití Tomáš Pitner, Jan Pavloviˇ c, FI MU

Ukažme si, jak v DocBooku oznaˇ ckujeme jednoduchou knihu se dvˇ ema kapitolami (pˇ riˇ cemž si odpouštíme napˇ r. informace o autorovi, datum vzniku, copyrightu, atd.):

XML znaˇ ckování DocBook 1 , p˚ uvodnˇ e urˇ cené k poˇ rizování programové dokumentace, se stává v souˇ casnosti velice populárním formátem platformovˇ e pˇ renositelných dokument˚ u “o ˇ cemkoli". Nejlepším d˚ ukazem jeho kvalit je široké uplatnˇ ení v open-source komunitách, akademické sféˇ re i v pr˚ umyslu – využívají ho spoleˇ cnosti Novell a SUN, vydavatelství O’Reilly stejnˇ e jako komunity kolem projekt˚ u PHP, Gnome, KDE, BSD, Linux aj.

<para>První odstavec první kapitoly. <para>Druhý odstavec první kapitoly. <para>Odstavec 1. se <emphasis>zd˚ uraznˇ eným textem <para>Odstavec 2.

DocBook je formátem zavedeným; v SGML podobˇ e, dnes již témˇ eˇ r neznámé, existuje nˇ ekdy od roku 1991. Od ustavení XML jako standardu v roce 1998 je DocBook rozvíjen již pˇ revážnˇ e v XML podobˇ e. Hlavní výhodou je kromˇ e totální platformové nezávislosti také “ˇ cistota" v nˇ em poˇ rízeného textu. Dokument oznaˇ ckovaný podle standardu DocBook nenese témˇ eˇ r žádné explicitní pokyny k formátování – je tedy stejnˇ e dobˇ re následnˇ e prezentovatelný na monitoru poˇ cítaˇ ce, na displeji PDA nebo ve vysoce kvalitní tiskové podobˇ e. Nejsme v nˇ em schopni – a tudíž ani nem˚ užeme – zabývat se tím, jak velké písmo a jaký font se použije na nadpis, kde bude zalomena stránka . . . .

Celkovˇ e DocBook nabízí pˇ res 400 druh˚ u element˚ u (znaˇ cek), v praxi vˇ etšinou vystaˇ címe se znalostí nˇ ekolika málo desítek z nich. Široký repertoár je nabízen pro ty, kdo vyžadují jemné sémantické vyznaˇ cení takových prvk˚ u dokumentu, jako jsou názvy tˇ ríd, metod, tlaˇ cítek v uživatelském rozhraní program˚ u, pˇ ríkaz˚ u systému, atd. Prvotní úˇ cel – prostˇ redek k poˇ rizování dokumentace – se zde jednoznaˇ cnˇ e odráží.

Pˇ revážná vˇ etšina znaˇ cek nese informace o sémantice toho, co je znaˇ ckou ohraniˇ ceno. Napˇ r. znaˇ cka signalizuje, že její vnitˇ rek pˇ redstavuje jednu kapitolu knihy nebo ˇ clánku, Slides Norman <surname>Walsh Tuesday, 25 June 2002 3.1.0 2002 Norman Walsh

<para>Groups can now have introductory text as well. ...

Na obr.1 je vidˇ et výsledná HTML podoba zobrazená v prohlížeˇ ci. V praxi se ukázalo, že hlavní pˇ redností poˇ rizování slid˚ u k pˇ rednáškám i jednorázovým prezentacím v DocBooku je snadná produkce výstup˚ uk prohlížení na obrazovce, promítání z projektoru a pro tisk – vše z jednoho zdrojového souboru. 1.2 Tvorba odborných ˇ clánk˚ u a publikací

<para>This is the introductory slide. <para>If you use foil groups (previously called sections), you can have introductory slides before the first group. 3

http://www.oasis-open.org/docbook/xml/ simple 4 XSL:FO, http://www.w3.org/TR/xsl 5 http://fop.apache.org

2

Velmi užiteˇ cný nástroj je DocBook pˇ ri tvorbˇ e ˇ clánk˚ u do konferencí a jiných odborných publikací. Vˇ etšinou se po autorech žádá, aby sv˚ uj pˇ ríspˇ evek formátovali do pˇ redem dané TEXové šablony. Jestliže své pˇ ríspˇ evky hodláme poˇ rizovat v DocBooku, lze pro pˇ ríslušnou konferenci napsat krátký XSLT styl, který nám zdrojový text v DocBooku pˇ revede do požadovaného formátu.

Fakulty informatiky. Rovnˇ ež tak lze zdarma použít i javový editor jEdit7 , “klasiku" Emacs, vim a ˇ radu dalších.

Výchozí zdroje z˚ ustávají v jednotné podobˇ e nezávislé na požadavcích editora daného sborníku, ˇ casopisu apod. Díky tomu, že zdrojový soubor ve znaˇ ckování DocBook nenese (témˇ eˇ r) žádné pokyny pro formátovací a sémantika znaˇ cek je dána pomˇ ernˇ e pevnˇ e, není rovnˇ ež problém kombinovat zdroje r˚ uzných autor˚ u – napˇ r. v situaci, kdy pracují na spoleˇ cném ˇ clánku, knize... 1.3

2.2 Modul xslt2 Aby mohl uživatel plnˇ e využít pˇ redností automatizovaného zpracování dokument˚ u v DocBooku, byl na Fakultˇ e informatiky vytvoˇ ren sys8 tém xslt2 . Celý systém je napsán v jazyce Perl a je tudíž pˇ renositelný na všechny operaˇ cní systémy s podporou Perlu.

Tvorba závˇ ereˇ cných prací

Jedním z požadavk˚ u na závˇ ereˇ cné práce je pˇ rimˇ eˇ rená typografická úroveˇ n. Na Fakultˇ e informatiky tradiˇ cnˇ e existuje LATEXový styl, které závˇ ereˇ cným pracím dává jednotnou podobu. V dnešní dobˇ e však TEXová gramotnost mezi studenty velmi klesá a napsat typograficky kvalitní práci ve WYSIWYG editoru není snadné. Práce v DocBooku nám velmi zjednoduší jak samotné poˇ rízení textu práce, tak pˇ redevším pˇ rípravu její výstupní podoby – obvykle ve formátech PDF a XHTML.

Na UNIXových strojích FI je systém dostupný pomocí modulu xslt2, který zavedeme bˇ ežným zp˚ usobem: module add xslt2

Po pˇ ridání modulu m˚ užeme transformovat XML dokument pomocí XSL šablony. Lze taktéž i specifikovat XSLT procesor. Systém plnˇ e podporuje i XML Catalogs 9 , tudíž se nemusíme starat ani o lokální umístˇ ení DTD definic odkazovaných ve zdrojových souborech. Napˇ ríklad: xslt -c -l -s fi -t pdf dp.xml xslt -c -s xhtml dp.xml

Tvorba práce v DocBooku je nˇ ekolikafázový automatizovaný proces, viz. obr 2

nám transformuje diplomovou práci (dp.xml) do PDF a XHTML.

V pr˚ ubˇ ehu celého procesu k transformaci zdrojového dokumentu v DocBooku do LATEXového kódu. LATEXový procesor nám ve výstupu dává dokument v požadované kvalitˇ e. Jelikož je celý proces automatizovaný, nemusí uživatel znát prakticky nic o LATEXu.

2.3 Struktura a možné modifikace xslt2 Samotný DocBook poskytuje dostateˇ cnˇ e široký repertoár element˚ u pro napsání vˇ ecného obsahu závˇ ereˇ cné práce, bylo však nutné jej rozšíˇ rit o elementy umožˇ nující specifikovat informace náležící k závˇ ereˇ cné práci – zejména k jejímu autorství, pˇ ríslušnosti k fakultˇ e atd. Architektura gramatiky DocBooku je naštˇ estí konstruována jako modulární a tudíž bylo rozšíˇ rení pro úˇ cely studentských závˇ ereˇ cných prací relativnˇ e pˇ rímoˇ caré, psané jako DTD modul fithesis.mod10 . Analogicky jako gramatika byly rozšíˇ reny i XSLT styly, byt’ samozˇ rejmˇ e jinou technikou.

2 Nástroje 2.1

Editory

Bez kvalitních autorských nástroj˚ u by samotné znaˇ ckování nebylo pˇ ríliš užiteˇ cné. Naštˇ estí je DocBook dnes koncipován a rozvíjet pˇ redevším jako XML znaˇ ckování a tudíž lze k editování dokument˚ u použít jakýkoli XML editor, pˇ rípadnˇ ei editor ˇ cistého textu. Nejkvalitnˇ ejší pˇ rímou podporu DocBook nabízejí komerˇ cní prostˇ redí jako je Epic, XMLSpy nebo Corel XMetal. Bez velkých omezení je ale použitelný i XMLMind XML Editor6 , jehož základní verze je dostupná zdarma a je k dispozici i jako modul (xmlmind) na strojích 6

Chování DocBook XSLT styl˚ u docbook-xsl11 a 12 db2latex , které systém xslt2 používá, lze 7

http://jedit.org http://www.fi.muni.cz/~xpavlov/xml 9 http://www.oasis-open.org/committees/ entity/spec-2001-08-06.html 10 http://www.fi.muni.cz/~xpavlov/fithesis.mod 11 http://sf.net/projects/docbook 12 http://sf.net/projects/db2latex 8

http://www.xmlmind.com/xmleditor

3

Obrázek 2: Transformace DocBooku

3 Matematika a DocBook

ovlivˇ novat nastavením parametr˚ u. Pro rozsáhlejší modifikace, nepokryté parametry, nabízejí XSLT styly mnohem silnˇ ejší techniku. Tou je pˇ rekrývání (nahrazování) již existujících šablon novými. Velkou výhodou je, že nemusíme zasahovat do originálních styl˚ u. Veškeré úpravy uvedeme ve vlastním stylovém souboru, kde v jeho zaˇ cátku importujeme pomocí xsl:import originální hlavní XSLT soubor.

Jelikož podpora MathML není zatím na pˇ rijatelné úrovni, je lepší v souˇ casné dobˇ e matematické vzorce v DocBooku zapisovat pomocí LATEXové syntaxe. Do výsledného LATEXového kódu se zápis matematiky vloží pˇ rímo a do HTML se vloží odkaz (uvedený v elementu imagedata) na obrázek, který vznikl konverzí z EPS souboru vyprodukovaného LATEXem. K zápisu matematických kód˚ u slouží v DocBooku tˇ ri elementy: inlineequation, který se používá k vložení matematiky pˇ rímo do textu, informalequation, který matematiku zobrazí v samostatném odstavci a equation zobrazující matematiku v odstavci s uvozovacím titulkem. Pˇ ríklad:

Jako pˇ ríklad vezmˇ eme db2latex styly, které originálnˇ e sestavují uvozovky kolem slova pomocí jednotlivých znakových entit daného jazyka. Vˇ ceštinˇ e se spíše používá pro uvozovky makro \uv{}. Proto vytvoˇ ríme vlastní definici šablony pro element quote, která v procesu transformace nahradí originální definici. Pˇ ríklad: <xsl:stylesheet xmlns:xsl= "http://www.w3.org/1999/XSL/Transform" version=’1.0’>

<equation> <mediaobject> e=mc^2

<xsl:import href="..docbook.xsl"/> <xsl:template match="quote"> <xsl:text>\uv{ <xsl:call-template name="inline.charseq"/> <xsl:text>}

4

4 Kam dál? DocBook je široce použitelné znaˇ ckování, k nˇ emuž existuje celá ˇ rada kvalitních nástroj˚ u a informaˇ cních zdroj˚ u. Zájemce m˚ užeme odkázat na v úvodu zmínˇ enou základní stránku standardu DocBook pˇ ri konsorciu OASIS, stránku ke knize N. Walshe DocBook: The Definitive Guide13 , stránky wiki k DocBooku dostupné tamtéž nebo pˇ ríslušnou mailovou skupinu pˇ ri OASIS14 . Kromˇ e toho se v polovinˇ e dubna 2004 na Fakultˇ e informatiky konala úvodní pˇ rednáška k DocBooku ve15 dená Jiˇ rím Koskem , ˇ clenem OASIS TC DocBook. Videozáznam pˇ rednášky je dostupný na http: //video.fi.muni.cz/ostatni.shtml. 

13

http://docbook.org http://lists.oasis-open.org/archives/ docbook 15 http://www.kosek.cz 14

5