DocBook je docela zajímavá věc pro psaní dokumentace k čemukoliv, umožňuje vám napsat jeden dokument v XML a z něj poté vygenerovat html variantu, pdf, ps, rtf a podobně. Pár lidí se mě už ptalo jak píšu své textíky, tak jsem si řekl, že udělám howto na to jak psát howto 🙂 Starší variantu tohoto dokumentu najdete na AbcLinuxu.cz v mém blogu. aktualizováno
Nemá cenu abych tu fušoval panu Koskovi do řemesla, proto u mě nehledejte návod na DocBook jako takový, ten je na jeho webu.
Instalace DocBooku je docela dobře popsaná u pana Koska. Pokud máte nějakou slušnější distribuci Linuxu, tak si můžete celkem pohodlně nainstalovat DocBook z jejich balíčků, v Debianu jsou to balíčky
-
docbook
-
docbook-defguide
-
docbook-doc
-
docbook-dsssl
-
docbook-dsssl-doc
-
docbook-html-forms
-
docbook-mathml
-
docbook-simple
-
docbook-to-man
-
docbook-utils
-
docbook-website
-
docbook-xml
-
docbook-xml-simple
-
docbook-xsl
-
docbook-xsl-stylesheets-ko
-
docbook2x
-
xsltproc, openjade, jade, jadetex
Pro každý dokument, který píšu si dělám samostatný adresář, ve kterém jsou potřebné soubory. V adresáři najdeme soubory Makefile, xhtml-chunk.xsl, xhtml-onechunk.xsl, xhtml-common.xsl a adresář html/, v něm je CSS styl (docbook.css) pro budoucí html variantu dokumentu. Samozřejmě je v adresáři i zdrojový dokument.xml případně další potřebné soubory (obrázky a podobně).
Na make jsem zvyklý, je to jednodužší než si psát pokaždé shellový skriptík. Obsah mého Makefile je následující:
#$Id: docbook.xml,v 1.2 2006/01/30 00:25:11 tsunami Exp $
all: single
book: clean dokument.xml xhtml-chunk.xsl xhtml-common.xsl
xsltproc -o html/ xhtml-chunk.xsl dokument.xml
single: clean dokument.xml xhtml-onechunk.xsl xhtml-common.xsl
xsltproc -o html/ xhtml-onechunk.xsl dokument.xml
rtf: dokument.xml
docbook2rtf dokument.xml
pdf: dokument.xml
docbook2pdf dokument.xml
ps: dokument.xml
docbook2ps dokument.xml
clean:
@rm -f html/*.html
@rm -f dokument.aux dokument.dvi dokument.log dokument.out
@rm -f dokument.rtf dokument.tex dokument.ps dokument.pdf
Pozor na odsazení v Makefile, je děláno pomocí tabulátorů a ne mezerama. Docela dobře to je vidět pokud Makefile děláte v mceditu, pak to odsazení bude červené (stačí dát dva tabulátory).
Jak vidíte, tento Makefile mi umožňuje vyrobit pomocí jednoduchého příkazu make CIL dokument v požadovaném formátu. Cíle jsou pdf, ps, rtf, single, book, clean, all. Cíle pdf, ps a rtf asi nemá cenu vysvětlovat. Cíl clean smaže všechny generované soubory, cíl all je výchozí cíl, uplatní se, když spustíte make bez parametrů. Book je html dokument dělený na jednotlivé stránky odpovídající kapitolám a single je html dokument ve formě jedné veliké stránky.
Tento soubor je společným pro book i single html, obsahuje základní definici parametrů pro generování html. Všechny své dokumenty píšu v ISO8859-2 kódování, ale samozřejmě si to můžete přehodit na UTF-8.
<?xml version="1.0" encoding="iso-8859-2"?>
<!-- $Id: docbook.xml,v 1.2 2006/01/30 00:25:11 tsunami Exp $ -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<!-- Úpravy parametru -->
<xsl:param name="chunker.output.encoding" select="'UTF-8'"/>
<!-- Mají se pouzívat rozsírení -->
<xsl:param name="use.extensions" select="1"/>
<!-- Vypneme podporu pro rozsireni tabulek -->
<xsl:param name="tablecolumns.extension" select="0"/>
<!-- Mají se sekce automaticky ??íslovat -->
<xsl:param name="section.autolabel" select="1"/>
<!-- Mají císla sekcí obsahovat i císla kapitol -->
<xsl:param name="section.label.includes.component.label" select="1"/>
<!-- Mají se císlovat kapitoly -->
<xsl:param name="chapter.autolabel" select="1"/>
<!-- Pouzijeme námi definovaný CSS-->
<xsl:param name="html.stylesheet">docbook.css</xsl:param>
<xsl:param name="html.stylesheet.type">text/css</xsl:param>
<xsl:param name="generate.id.attributes" select="1"></xsl:param>
<xsl:param name="make.valid.html" select="1"></xsl:param>
<xsl:param name="generate.meta.abstract" select="1"></xsl:param>
<xsl:param name="autotoc.label.separator" select="'. '"></xsl:param>
<xsl:param name="generate.toc">
book toc,title
</xsl:param>
</xsl:stylesheet>
Tento soubor dělá jen jednu věc, definuje výstup do html rozděleného na více stránek podle kapitol.
<?xml version="1.0" encoding="iso-8859-2"?>
<!-- $Id: docbook.xml,v 1.2 2006/01/30 00:25:11 tsunami Exp $ -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/>
<xsl:include href="xhtml-common.xsl"/>
</xsl:stylesheet>
<?xml version="1.0" encoding="iso-8859-2"?> <!-- $Id: docbook.xml,v 1.2 2006/01/30 00:25:11 tsunami Exp $ --> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/onechunk.xsl"/> <xsl:include href="xhtml-common.xsl"/> </xsl:stylesheet>
Pro html je definice vlastního vzhledu relativně snadná, stačí nám k tomu jeden CSS soubor.
/* $Id: docbook.xml,v 1.2 2006/01/30 00:25:11 tsunami Exp $ */
body { font-family: Verdana, Helvetica CE, Arial CE, Arial, Helvetica, sans-serif;
font-size: 12pt;
line-height: 1.3;
background-color: #dddddd;
color: black;
margin: 0px;}
table { font-size: 10pt
border: solid black 1px;
border-collapse: collapse; }
.title, .subtitle { color: navy }
.programlisting,
.programlistingco,
.screen { background-color: #f0f0fe;
border: 1px solid #999999;
margin: 0.3em;
padding: 0.3em; }
a:hover { color: red;
text-decoration: underline; }
a { text-decoration: none;
color: blue; }
.navfooter, .navheader { background-color: #bbbbbb; }
.section, .appendix,
.chapter, .refentry,
.book, .reference,
.preface, .colophon { margin-left: 10pt;
margin-right: 10pt; }
p { text-align: justify; }
li p { display: inline}
Na psaní skoro všeho používám VIM. Pokud vám na XML nevyhovuje, tak zkuste pro DocBook třeba Emacs nebo spíš XMLmind. Emacs má narozdíl VIMu špičkovou podporu pro psaní XML, jako berličku pro rychlejší psaní xml a html ve vimu používám makro na zavírání tagů. Editor XMLmind je špičkový editor napsaný v javě, který vám umožní docela efektivně pracovat s čímkoliv v xml, takže i s DocBookem. Kolega ho používá a je s ním docela spokojen.
Pro kontrolu správnosti XML dokumentu používám xmllint:
$ alias xmlvalid='xmllint --noout --valid' $ xmlvalid dokument.xml
DocBook umožňuje vložit obrázek ve více formátech, při generování výsledného dokumentu použije ten vhodnější (pro html png, pro pdf eps).
<figure float="0" id="net">
<title>Název obrázku</title>
<mediaobject>
<imageobject>
<imagedata fileref="img/net.eps" format="EPS" scale="50" />
</imageobject>
<imageobject>
<imagedata fileref="img/net.png" format="PNG" />
</imageobject>
</mediaobject>
</figure>
U větších dokumentů se hodí rozdělit zdrohový soubor do více logických celků.
V hlavním souboru (dokument.xml) je třeba definovat kde se mají hledat další části (v mém případě to jsou rfc.xml, ldif.xml, slovnicek.xml a odkazy.xml), to se dělá na začátku dokumentu.
<?xml version="1.0" encoding="ISO-8859-2"?> <!-- $Id: docbook.xml,v 1.2 2006/01/30 00:25:11 tsunami Exp $ --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ <!ENTITY rfc SYSTEM "rfc.xml"> <!ENTITY ldif SYSTEM "ldif.xml"> <!ENTITY slovnicek SYSTEM "slovnicek.xml"> <!ENTITY odkazy SYSTEM "odkazy.xml"> ]>
Pokud potom někam do dokumentu vložíte nově definovanou entitu (&rfc;, &ldif;, &slovnicek; nebo &odkazy;) tak se při překladu místo ní vloží zdrojový soubor, pro který je definována.
Formát tohot zdrojového souboru je trochu jednodužší, je třeba aby začínal jedním povinným řádkem a zbytek si už můžete psát co chcete (samozřejmě xml/DocBook a ne třeba xhtml).
<?xml version="1.0" encoding="ISO-8859-2"?>
Určitě jste si všimli, že generovaný html kód není pro normálního smrtelníka moc čitelný. Pokud chcete pěkný čitelný kód, nainstalujte si program tidy.
Přeformátování html:
tidy -i -wrap 0 -c -q -utf8 -o vystupni.html vstupni.html
Snad každý moderní browser umí zobrazit XML soubor. Pro zobrazení, které se velmi podobá výslednému vygenerovanému html souboru, je potřeba přidat CCS styl.
Do hlavičky XML souboru přidáme odkaz na CSS.
<?xml version="1.0" encoding="ISO-8859-2"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <?xml-stylesheet href="docbook-css-0.4/driver.css" type="text/css"?> </article> ...
Do adresáře vedle našeho docbook souboru rozbalte balíček s CSS (v příloze u článku, trochu jsem ho upravoval pro češtinu a měnil jsem barvy).
