DocBook je jazyk založený na XML (definiční nástroje Relax NG, SGML a XML DTD a W3C XML Schema) vedeného technickým výborem DocBook z OASIS. Je vhodný pro tvorbu knih a článků. Byl vytvořen primárně pro texty zaměřené na počítačový hardware a software. Nicméně samozřejmě není problém jej použít na jakékoliv jiné téma.

Docbook je v aktuálně ve verzi DocBook5.1 (vydána 11/2016), jeho možnosti jsou velmi široké a proto je možné najít v něm shodu i pro lidi, kteří mají o knize či článku mírně odlišné představy. Zároveň má velkou komunitu a mnoho autorů, kteří jej aktivně využívají. DocBook je podporován i komerčními software (například OxygenXML Editor).

V rámci použití XSLT a XSL:FO není problém jej přetvořit v libovolný výstup pro webe nebo tištěné knihy a sborníky. V sérii článků se pokusím jeho charakteristiku a dám k dispozici ukázky, jak se jej naučit a používat pro tvorbu. V současné době (04/2017) v něm připravuji materiály na skripta pro několik předmětů na Provozně ekonomické fakultě ČZU v Praze.

 Cílem není historická studie na téma vývoj DocBooku, takže pouze stručně novinky a změny v majoritní revizi:

  • založen na RelaxNG,
  • striktní dodržování pravidel (využit i Schematron),
  • vyčištění kódu,
  • umožňuje flexibilitu a upravitelnost.

Vytváříme dokument

Stejně jako u jiných XML jazyků je vždy prvním řádkem deklarace:

<?xml version="1.0" encoding="utf-8"?>

Dalším řádkem, rovněž povinným, je deklarace jazyka:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN" "http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd">
Prima, teď se dostaneme k obsahu. U DocBooku je několik typů dokumentů, ty jsou určeny jejich rozsahem a máme tak k dispozici následující možnosti (logické rozdělení):

  • sets - sety, například knih, měl by obsahovat alespoň dvě knihy, jinak ztrácí smysl,
  • book - knihy, neolik součástí - dedication, ToC (navigace), logické části
  • divisions - oddíly knih
  • components - pododdíly knih (preface, chapter, appendix, glossary, bibliography, article)
  • sections - dílčí části textu (sect1 - sect5, simplesect, bridgehead, ...)
  • meta-information elements (poměrně hodně elementů)
  • block elements (poměrně hodně elementů)
  • inline elements (poměrně hodně elementů)

Pokud máme rozdělený dlouhý text a chceme například jej nechat upravovat několika autory, pak můžeme dokument rozdělit fyzicky:

<book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
  <title>My First Book</title>
    <xi:include href="/kapitola-1.xml"/>
    <xi:include href="/kapitola-2.xml"/>
    <xi:include href="/kapitola-3.xml"/>
</book>

Článek

Každý článek by měl obsahovat základní informace o autorovi (včetně kontaktu a adresy). Dále pak jednotlivé kapitoly s obsahem. Obdobně můžeme vytvořit jednoduchý článek:
<article xmlns=http://docbook.org/ns/docbook xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
  <info>
    <title>
      Něco o DocBook
    </title>
    <author>
      <orgname>KIT PEF ČZU v Praze</orgname>
      <address>
        <city>Praha</city>
        <street>Kamýcká 129</street>
        <postcode>16529</postcode>
        <country>Czech republic</country>
      </address>
      <email>This email address is being protected from spambots. You need JavaScript enabled to view it.</email>
    </author>
  </info>
  <sect1>
    <title>Úvod – co je to DocBook</title>
    <subtitle>Verze 5.1</subtitle>
    <para>DocBook má dvě v současnosti používané verze – 4 a 5. Obě se liší – nejsou vzájemně kompatibilní.</para>
  </sect1>
</article>

Kniha

Nejpoužívanější formát používaný při tvorbě dokumentů v DocBooku. Kniha obsahuje velké množství informací, které ji charakterizují:
  • metainformace o autor, adresa, organizace, ...
  • dedikace
  • tiráž
  • ToC – table of content - Seznamy, rejstříky, obsahy, ...
  • Části
  • Předmluva
  • Kapitoly
  • Přílohy
  • Reference a zdroje
Ukázka jednoduché knihy:
<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
  <info>
    <title>Book Template Title</title>
    <author>
      <orgname>KIT PEF ČZU v Praze</orgname>
      <address>
        <city>Praha</city>
        <street>Kamýcká 129</street>
        <postcode>16529</postcode>
        <country>Czech republic</country>
      </address>
      <email>This email address is being protected from spambots. You need JavaScript enabled to view it.</email>
    </author>
  </info>
  <part>
    <title>První kapitola</title>
    <subtitle>Úvod do DocBook dokumentace</subtitle>
    <chapter>
      <title>Úvod – co je to DocBook</title>
      <subtitle>Subtitle of Chapter</subtitle>
      <sect1>
        <title>Section1 Title</title>
        <subtitle>Verze5.1</subtitle>
        <para>DocBook má dvě v současnosti používané verze – 4 a 5. Obě se liší – nejsou vzájemně kompatibilní.</para>
      </sect1>
    </chapter>
  </part>
</book>

Další prvky dokumentu

Seznamy
Pokud je potřeba vložit do dokumentu seznamy, pak máme stejné možnosti jako v HTML. Tedy odrážky – neseřazený seznam, pak seřazený seznam – číslované či písmenkované položky. Případnou možností jsou kombinované seznamy.  Posledním typem seznamu je pak slovníček – glosslist. Upozornění V odborném textu je vhodné zdůraznit některé věty či bloky textu. V rámci upozornění je pak dobré je odlišit od dalšího textu a zvýraznění provést tak, aby odpovídalo dané situaci.  Proto je v DocBooku možné využít následující upozornění:
  • Caution – upozornění na vážný problém
  • Important – důležitý text
  • Note – poznámka – rozšíření vysvětlované problematiky
  • Tip – zajímavost
  • Warning – upozornění na důležitý fakt
Řádkování v dokumentu
Text je nutné ve vybraných případech nechat odřádkovaný tak, jak jej autor vložit. Většina prezentačních prostředků (HTML, DocBook, TeX) nerespektuje nové řádky vložené v kódu. I v případě DocBooku je nutné takovýto text uzavřít do speciálních značek:
  • Address – adresa – obsahuje běžně řádky s jednotlivými řádky
  • Literallayout – ponechává formátování dle autorova záměru
  • Programlisting – pro vložení programového kódu, také zachovává vložený text beze změn
  • Screen – výstup z obrazovky
  • Synopsis – popisu syntaxe příkazů.
Rovnice
Odborná literatura se běžně vyznačuje rovnicemi a vzorci. DocBook je umí vkládat a pracovat s nimi. A to interně pomocí značek:
  • Equation
  • Informalequation
  • Inlineequation
Dále pak je možné pro složitější vzorce použít externí jazyk mathML.
 
Obrázky
Grafiku můžeme vložit pomocí značek:
  • Graphics
  • Inlinegraphics
  • Mediaobject
  • Inlinemediaobject
K obrázku, či grafu je pak vhodné doplnit popisek – toto obstaráme vložením značky figure a následně pak obrázku a značky title.
 
Další blokové elementy
Některé texty je nunté zpracovat jako blok textu. Pak jsou k dispozici značky:
  • Blockquote – vloží delší text s citací
  • Epigraph – vloží kratší text ze začátku kapitoly
  • Highlight – umožňuje vyznačit důležité texty
  • Procedure – vloží výpis z programu či postupu
  • Sidebar – vloží postranní blok s textem
 
Inline elementy
Některé části dokumentu vkládáme jako řádkové elementy, ty se pak vkládají do běžného oddstavce a obohacují jej:
  • Anchor – vytvoří bod, na který se lze v dokumentu odkazovat
  • Citation – citace ze zdroje
  • Email – vloží emailovou adresu
  • Filename – vloží název souboru
  • Glossterm – vloží pojem ze slovníčku
  • Link – vloží odkaz
 
Entity
Entita je znak či text vložený pomocí speciálního zápisu, tak lze vložit i znaky či značky, které pomocí běžného zápisu nejsou možné (zápis entity se provádí uvozujícího znaku &a ukončujícího znaku ;):
  • &ndash; - krátká pomlčka
  • &mdash; - dlouhá pomlčka
  • &hellip; - ...
  • &copy; - copyright
  • &reg; - registrovaná značka
  • &plusmn; - +-
 
Tabulka
Vložení tabulky je možné obdobným postupem jako v případě HTML, ale v DocBooku jsou navíc definovány i sloupce. Viz následující příklad:
<table>
  <title>První tabulka</title>
  <tgroup cols="3">
    <colspec colwidth=„5cm"/>
    <colspec colwidth=„5cm"/>
    <colspec colwidth=„7,5cm"/>
    <thead>
      <row>
        <entry>Jazyk</entry>
        <entry>Založen na</entry>
        <entry>Stylování</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>HTML</entry>
        <entry>SGML a XML</entry>
        <entry>CSS</entry>
      </row>
    </tbody>
  </tgroup>
</table>
 
Bibliografie
Seznam zdrojů je vhodné připojit tam, kde jsme v textu použili text či jiné složky dokumentu od jiného autora, případně z jiné publikace.
<biblioentry>
  <abbrev>XML - IN</abbrev>
  <author>
    <firstname>Elliote Rusty</firstname>
    <surname>Harold</surname>
  </author>
  <title>XML in a nutshell</title>
  <publisher>
    <publishername>Grada Publishing</publishername>
  </publisher>
  <pubdate>2000</pubdate>
  <isbn>ISBN 80-7169-861-X</isbn>
  <pagenums>244</pagenums>
</biblioentry>
 
FAQ
Pro omezení uživatelských dotazů lze vložit seznam často kladených otázek a odpovědí na ně, i tato možnost je v DocBooku připravena:
<qandaset>
  <qandaentry>
    <question></question>
    <answer></answer>
  </qandaentry>
</qandaset>
 
Komentář
Stejně jako u kteréhokoliv jiného jazyka je v kódu vhodné využít komentáře, které upřesňují avysvětlují zápisy.
<!-- komentář -->
 
CDATA
<![CDATA[ kód ]]>
  Instrukce pro další programy
  <?identifikátor data?>
 
Formátujeme výstup
Pro formátování výstupního dokumentu máme možnost využít několika nástrojů. Jeden z nich je běžně používaný při tvorbě webových stránek:
  • XLS – silný nástroj umožňující tak výpočty, souhrny a další funkce
  • DSSSL – původní stylovací jazyk pro SGML, jeho zápis je komplikovaný a jazyk je velmi málo používaný
  • CSS – stejný nástroj jako pro webové stránky, výhodou je jeho velká rozšířenost, na druhou stranu umí pouze formátovat
Jak vytvořit dokumentaci
Každá dokumentace je základní text, který provází vybraný značkovací jazyk, který jde do běžného používání. Cílem dokumentace je umožnit uživatelům a zejména programátorům pochopit, co je cílem dokumentu a jak byl vytvořen.
Klíčovými složkami dokumentace jsou:
  • Popis uživatelských vlastností
  • Přesné specifikace jednotlivých součástí dokumentu
  • Designový návrh
  • Ideový návrh
Na základě dokumentace pak mohou další subjekty využívat nově definovaný jazyk a umožní se tak jeho šíření.