DocBook: XML pro technickou dokumentaci

Co je DocBook

DocBook je schéma, tedy pevně daný soubor elementů a pravidel pro jejich skládání, určené pro dokumentaci softwaru a hardwaru. Vzniklo v roce 1991 jako společný projekt firem HaL Computer Systems a O'Reilly & Associates, které potřebovaly vyměňovat unixovou dokumentaci psanou v troffu. Údržbu později převzala Davenport Group a v roce 1998 přešel vývoj pod konsorcium OASIS. Původně šlo o SGML DTD; od verze 4.1 vycházela i XML podoba a DocBook 5 je už jen XML.

Aktuálním standardem je DocBook 5.2, schválený jako standard OASIS 6. 2. 2024. Technická komise OASIS byla v září 2024 uzavřena a schéma dál udržuje projekt docbook.org; jeho nejnovější vydání je 5.2.1 z 19. 3. 2026. Na DocBooku stála dokumentace řady open source projektů i knih. Dnes ho často nahrazují lehčí formáty jako AsciiDoc nebo Markdown, ale u rozsáhlé dokumentace s mnoha výstupy se drží dál.

Proč DocBook místo HTML nebo Wordu

• Jeden zdroj, více výstupů. Ze stejného souboru vznikne web, PDF k tisku, e-kniha i manuálová stránka. Nekopíruješ text mezi formáty a opravu uděláš jen jednou.
• Obsah odděleně od vzhledu. V textu nepíšeš „tučně“ ani „Courier“, ale co věc znamená: <command>, <filename>, <warning>. Vzhled určí až stylesheet, takže změna grafiky nevyžaduje zásah do textu.
• Kontrolovatelná struktura. Schéma vynutí nadpis u každé kapitoly a nedovolí nesmyslné vnoření. Nad XML můžeš spouštět XPath, generovat rejstříky nebo vybírat části textu pro různé verze produktu (profilace podle atributů jako os či arch).
• Textový formát. Soubory se dobře verzují v Gitu, porovnávají a slučují.

Cenou je upovídanost a nutnost nástrojového řetězce. Na krátký web nebo README DocBook nepotřebuješ; vyplatí se tam, kde je text dlouhý, žije roky a vychází v několika podobách.

Stavba dokumentu

Nejmenší užitečný dokument je article s nadpisem a oddíly. Ukázka je platná podle schématu DocBook 5.2:

<?xml version="1.0" encoding="UTF-8"?>
<article xmlns="http://docbook.org/ns/docbook" version="5.2" xml:lang="cs">
  <title>Instalace nástroje</title>
  <section>
    <title>Požadavky</title>
    <para>Potřebuješ <application>Javu</application> 17 nebo novější.</para>
    <itemizedlist>
      <listitem><para>Linux, macOS nebo Windows</para></listitem>
      <listitem><para>500 MB volného místa</para></listitem>
    </itemizedlist>
  </section>
  <section>
    <title>Spuštění</title>
    <para>Spusť příkaz:</para>
    <programlisting language="bash">nastroj --verze</programlisting>
    <note><para>Na Windows použij <command>nastroj.exe</command>.</para></note>
  </section>
</article>

Kniha má navíc metadata v info, kapitoly, předmluvu a přílohy. Křížový odkaz xref ukazuje na xml:id a stylesheet za něj dosadí číslo a název kapitoly; odkaz na web používá atribut xlink:href z jmenného prostoru XLink:

<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink" version="5.2" xml:lang="cs">
  <info>
    <title>Příručka správce</title>
    <author><personname>
      <firstname>Jana</firstname><surname>Nováková</surname>
    </personname></author>
    <pubdate>2026</pubdate>
  </info>
  <preface>
    <title>Úvod</title>
    <para>Komu je příručka určena.</para>
  </preface>
  <chapter xml:id="instalace">
    <title>Instalace</title>
    <section>
      <title>Stažení</title>
      <para>Balíček stáhneš z <link xlink:href="https://example.com/">webu projektu</link>.</para>
    </section>
  </chapter>
  <chapter xml:id="konfigurace">
    <title>Konfigurace</title>
    <para>Postup navazuje na <xref linkend="instalace"/>.</para>
    <table>
      <title>Parametry</title>
      <tgroup cols="2">
        <thead><row><entry>Parametr</entry><entry>Význam</entry></row></thead>
        <tbody><row><entry><option>--port</option></entry><entry>Port serveru</entry></row></tbody>
      </tgroup>
    </table>
  </chapter>
  <appendix>
    <title>Licence</title>
    <para>MIT.</para>
  </appendix>
</book>

Nejpoužívanější elementy:

Schéma DocBook 5.2 definuje zhruba 390 elementů, ale pro běžnou příručku jich stačí pár desítek. Úplný popis každého elementu včetně povoleného obsahu je v referenci DocBook: The Definitive Guide.

Verze 4 a 5: jmenný prostor

Nejviditelnější rozdíl mezi generacemi je ve způsobu, jak dokument říká, čím je. DocBook 4 používá DTD a elementy bez jmenného prostoru; dokument se odkazuje na DTD deklarací DOCTYPE:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article lang="cs">
  <title>Instalace nástroje</title>
  <para>…</para>
</article>

DocBook 5 přesunul všechny elementy do jmenného prostoru http://docbook.org/ns/docbook, DOCTYPE nepotřebuje a verzi uvádí atributem version:

<?xml version="1.0" encoding="UTF-8"?>
<article xmlns="http://docbook.org/ns/docbook" version="5.2" xml:lang="cs">
  <title>Instalace nástroje</title>
  <para>…</para>
</article>

Normativním schématem DocBooku 5 je RELAX NG, doplněný pravidly ve Schematronu, která RELAX NG vyjádřit neumí. Starší dokumenty 4.x převede do verze 5 stylesheet db4-upgrade.xsl z distribuce DocBooku 5.0; výsledek vždy zvaliduj, protože některé konstrukce převod jen odhaduje.

Zpracování: HTML a PDF

DocBook sám o sobě nic nezobrazuje. Výstup vyrábějí XSLT stylesheety a existují dvě hlavní sady:

Klasická sada docbook-xsl běží v libovolném XSLT 1.0 procesoru, například v xsltproc z libxml2. Cesta k PDF má dva kroky: stylesheet vytvoří XSL-FO a formatter, třeba Apache FOP, z něj vysází stránky:

# HTML do jednoho souboru (XHTML5, UTF-8)
xsltproc --nonet -o clanek.html docbook-xsl/xhtml5/docbook.xsl clanek.xml

# PDF: nejdřív XSL-FO, potom formatter
xsltproc --nonet --stringparam paper.type A4 \
  -o kniha.fo docbook-xsl/fo/docbook.xsl kniha.xml
fop -fo kniha.fo -pdf kniha.pdf

Novější xslTNG je napsaný v XSLT 3.0 a potřebuje Saxon, který je součástí staženého archivu. Generuje sémantické HTML se styly v CSS a tiskovou podobu řeší přes CSS pro stránkovaná média místo XSL-FO:

# xslTNG: XSLT 3.0, Saxon je přibalený v archivu
java -jar docbook-xslTNG-2.7.1/libs/docbook-xslTNG-2.7.1.jar clanek.xml -o:clanek.html

Výchozí nastavení stylesheetů se mění parametry, a to buď na příkazové řádce (--stringparam), nebo ve vlastní vrstvě, která původní stylesheet importuje. Vrstva je lepší, protože se dá verzovat:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:import href="docbook-xsl/fo/docbook.xsl"/>
  <xsl:param name="paper.type">A4</xsl:param>
  <xsl:param name="body.font.family">DejaVu Serif</xsl:param>
  <xsl:param name="title.font.family">DejaVu Sans</xsl:param>
  <xsl:param name="monospace.font.family">DejaVu Sans Mono</xsl:param>
</xsl:stylesheet>

Nástroje a validace

DocBook můžeš psát v libovolném textovém editoru, pohodlnější jsou ale editory, které znají schéma a nabízejí povolené elementy: Oxygen XML Editor má pro DocBook hotovou šablonu i převody, XMLmind XML Editor nabízí vizuální úpravy. Pokud raději píšeš lehčí syntaxí, Asciidoctor umí převést AsciiDoc do DocBooku 5 a Pandoc DocBook čte i zapisuje.

Před převodem dokument zvaliduj proti schématu (docbook.rng). Referenčním validátorem RELAX NG je Jing, základní kontrolu zvládne i xmllint:

# RELAX NG (normativní schéma DocBooku 5)
java -jar jing.jar docbook.rng clanek.xml
xmllint --noout --relaxng docbook.rng clanek.xml

RELAX NG nepokryje všechno. Například vnořenou poznámku note uvnitř note schéma pustí a zakáže ji až Schematron docbook.sch (vyžaduje XSLT 2.0 procesor). Že je soubor well-formed, ověříš rychle v XML validátoru na tomto webu; validaci proti DocBook schématu ale nedělá.

Časté chyby

Chybějící nebo špatný jmenný prostor

Dokument DocBook 5 bez xmlns, s překlepem v URI nebo s koncovým lomítkem (…/ns/docbook/) obsahuje elementy, které schéma nezná. Jing to hlásí takto:

<article version="5.2">        <!-- chybí xmlns -->
  <title>Instalace nástroje</title>
  …

err-ns.xml:2:38: error: element "article" not allowed here; expected element
"abstract", "acknowledgements", … (with xmlns="http://docbook.org/ns/docbook")

Záludné je, že docbook-xsl 1.79.2 takový dokument nezastaví: vypíše jen Note: namesp. add : added namespace before processing a převod dokončí. Chybu tedy odhalí validace, ne převod. Oprava je jediný atribut xmlns="http://docbook.org/ns/docbook" na kořeni; podrobně o výchozím jmenném prostoru píše kapitola Jmenné prostory.

Chybějící title

Kniha, článek, kapitola i oddíl musejí mít nadpis jako první potomek (nebo uvnitř info). Validátor hlásí až první element, který přišel místo něj:

<section>
  <para>Potřebuješ Javu 17 nebo novější.</para>   <!-- title chybí -->
</section>

err-title.xml:5:11: error: element "para" not allowed yet;
expected element "info", "subtitle", "title" or "titleabbrev"

Neplatné vnoření

Odstavec nesmí obsahovat další odstavec a oddíl nesmí obsahovat volný text, jen bloky jako para. Text kolem seznamu proto rozděl do dvou odstavců, nebo dej seznam dovnitř jednoho para, což para na rozdíl od simpara dovoluje.

<para>Text <para>vnořený odstavec</para></para>
<section><title>A</title>Volný text bez para.</section>

err-nest.xml:4:20: error: element "para" not allowed here; …
err-nest.xml:5:50: error: text not allowed here; …

Rozsypaná čeština v PDF

Ve výchozím nastavení FO stylesheetu se použijí obecné fonty serif a sans-serif, které FOP mapuje na základní fonty PDF bez znaků ř, č nebo ů. FOP vypíše Glyph "ř" (0x159, rcaron) not available in font "Helvetica-Bold" a z „Příručky“ se v PDF stane „P#íru#ka“. Nastav ve vlastní vrstvě font s českými znaky (viz vlastni-fo.xsl výše) a řekni FOPu, kde fonty najde:

<fop version="1.0">
  <renderers>
    <renderer mime="application/pdf">
      <fonts><auto-detect/></fonts>
    </renderer>
  </renderers>
</fop>

Font musí být v systému nainstalovaný. Výchozí formát papíru je navíc US Letter, proto nastav paper.type na A4.

HTML v ISO-8859-1

Stylesheet html/docbook.xsl zapisuje výstup v kódování ISO-8859-1. Znaky mimo Latin-1 (č, ř, ž) převede na číselné odkazy, takže se stránka zobrazí správně, ale pokud ji server pošle s hlavičkou charset=utf-8, rozbijí se znaky á, é, í. Použij xhtml5/docbook.xsl, který zapisuje UTF-8, nebo ve vlastní vrstvě nastav <xsl:output encoding="UTF-8"/>. Víc o kódování v kapitole Špatné kódování.

Doporučené postupy

• Nové dokumenty piš v DocBooku 5 s jmenným prostorem a version="5.2".
• Validuj v každém sestavení, nejlépe v CI, ne až když převod selže.
• Úpravy vzhledu dělej ve vlastní vrstvě, nikdy přímo ve staženém stylesheetu.
• Velkou knihu rozděl do souborů po kapitolách a spoj je přes XInclude; schéma a stylesheety přesměruj na lokální kopie přes XML katalogy, aby sestavení nestahovalo soubory ze sítě.
• Pro nový projekt zvaž xslTNG; docbook-xsl má smysl tam, kde už je řetězec postavený.

Odkazy

• The DocBook Schema Version 5.2 — specifikace OASIS
• Schémata DocBook — všechny verze ke stažení
• DocBook: The Definitive Guide — reference elementů
• DocBook xslTNG Reference
• docbook-xsl (XSLT 1.0) na GitHubu