DocBook a jeho použití (2)

Celou tvorbu dokumentace v DocBooku můžeme rozdělit na tři části:

1. napsání dokumentace
2. parametrizace a nastavení
3. transformace

Fáze 1.

Pokud ještě nejsme zběhlí v psaní DocBookových dokumentů, není na škodu si přečíst nějaký ten návod.

referenční příručka: DocBook: The Definitive Guide
užitečné informace: www.kosek.cz/xml/db
menší tutoriál: www.fi.muni.cz/~xpa­vlov/xml/tuto­rial.html

Samozřejmě si musíme stáhnout XSL styly pro transformace:

sourceforge.net/pro­jects/docbook/

A DTD gramatiku:

www.oasis-open.org/docbo­ok/xml/4.2

Hodit se nám bude i editor, který umí zvýrazňovat syntaxi, ať už (g)vim, emacs, či jiný oblíbený editor.

Tak a teď se již můžeme pustit do psaní naší první dokumentace. Na ukázku jsem použil takovou menší dokumentačku k lokálnímu používání PHP :).

php.xml

Fáze 2.

DocBookové XSL styly se dají do značné míry různě parametrizovat, viz DocBook: The Definitive Guide.

Pro začátek není třeba se s obsahem příliš zatěžovat, XSL soubor s parametry bude nyní sloužit jako styl, který spouští transformaci, musíme v něm tedy naimportovat hlavní originální transformační soubor docbook.xsl:

<xsl:import href="/path_to_docbook-xsl/xhtml/docbook.xsl"/>

php.xsl

DTD, které jsme uvedli v hlavičce XML souboru:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

neslouží jen pro kontrolu validity dokumentu, ale i pro substituce entit, např. entita &hyphen (HYPHEN-MINUS) se podle odkazu entit v DTD nahradí - atd. Nicméně chceme používat transformace i off-line a nestahovat pokaždé DTD z netu a na druhou stranu nechceme uvádět odkaz na lokálně uložené DTD, protože takový dokument pak jinde není bez manuálního zásahu plně transformovatelný.

Rafinovaně tuto situaci řeší catalogy. Ve zvláštním XML souboru jsou uvedeny ekvivalentní odkazy DTD, které v dokumentu používáme, na DTD lokálně uložené. Bohužel většina XML parserů a XSLT procesorů podporujících catalogy má vlastní formu, jak mapovat lokální DTD. Naštěstí množiny řešení nejsou úplně disjunktní.

Ukážeme si catalog soubor (řešení je pro win, pro UNIX je obdobné), ve kterém je uvedeno, kde se má lokálně hledat  PUBLIC DTD DocBook V4.2.

catalog.xml


<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <public publicId="-//OASIS//DTD DocBook XML V4.2//EN"
  uri="file:///c:/xml-dev/docbook/4.2/docbookx.dtd"/>
</catalog>

XSLT procesorům musíme sdělit, že hodláme používat catalogy a kde je mají hledat (trochu předběhneme, více o XSLT procesorech ve fázi 3.).

xmllint, xsltproc

nastavíme:

export SGML_CATALOG_FILES=/path/catalog.xml

při transformaci použijeme parametr:

--catalogs

Saxon

U procesorů napsaných pod Javou se catalogy používají tak, že procesoru řekneme jména externích tříd, které mají mapování URL a entit provést za ně. Stáhneme si nějaký nástroj pro používání catalogů a jeho třídy dáme jako parametr.

catalog resolver od Apache

tento catalog resolver má vlastní konfigurační soubor CatalogManager­.properties, ve kterém lze nastavovat krom cesty ke catalogům i několik jiných užitečných voleb.

CatalogManager.properties

verbosity=1
relative-catalogs=yes
catalogs=/path/catalog.xml
prefer=public
static-catalog=yes
allow-oasis-xml-catalog-pi=yes
catalog-class-name=org.apache.xml.resolver.Resolver

do CLASSPATH přidáme cestu k souboru CatalogManager­.properties a resolveru resolver-1.0.jar

export CLASSPATH=/path_to_saxon:/path_to_CatalogManager. properties:/path/resolver-1.0.jar

při transformaci použijeme parametry:

-x org.apache.xml.resolver.tools.ResolvingXMLReader
-y org.apache.xml.resolver.tools.ResolvingXMLReader
-r org.apache.xml.resolver.tools.CatalogResolver

Bohužel parser Saxonu Alfred to s catalogy moc neumí, je třeba použít nějaký jiný parser, třeba Crimson nebo Xerces, přidáme jej do CLASSPATH a použijeme parametry:

-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.crimson. jaxp.DocumentBuilderFactoryImpl
-Djavax.xml.parsers.SAXParserFactory=org.apache.crimson.jaxp. SAXParserFactoryImpl

Xalan

Soubor CatalogManager­.properties je samozřejně stejný a obdobně nastavíme parametry jako výše.

export CLASSPATH=/path_to_xalan:/path_to_CatalogManager.properties: /path/resolver-1.0.jar

při transformaci použijeme parametry:

-ENTITYRESOLVER org.apache.xml.resolver.tools.CatalogResolver
-URIRESOLVER org.apache.xml.resolver.tools.CatalogResolver

Nicméně nám SUN připravil menší překvapení v tom, že integroval (dnes hodně historickou) verzi Xalan přímo do JDK. Což samozřejmě nechceme, a proto musíme Javě říci, že má Xalan hledat nejprve někde jinde. Pro zjištění použité verze Xalanu stačí uvést parametr  -V.

-Xbootclasspath/p:/path_to_xalan/bin/xalan.jar:/ path_to_xalan/bin/xerces Impl.jar:/path_to_xalan/bin/xml-apis.jar:/path/resolver-1.0.jar: /path_to_CatalogManager.properties

Fáze 3.

Abychom mohli dokument správně transformovat, je potřeba zajistit, aby odpovídal gramatice (validita). Nejjednodušší je použít xmllint z libxml2.

xmllint --catalogs --valid --noout php.xml

Pokud se objeví nějaké nesrovnalosti, je potřeba dokument opravit. Poté můžeme s klidem přistoupit k transformaci. Mezi nejznámější XSLT procesory patří:

xsltproc

xmlsoft.org k dispozici i v binární formě pro Windows: www.zlatkovic­.com/projects/lib­xml/

transformaci spustíme:

xsltproc --catalogs -o php.html php.xsl php.xml

Saxon

saxon.sf.net/ existuje i přepracovaná verze Saxon7.

transformaci spustíme:

java \
-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.crimson. jaxp.DocumentBuilderFactoryImpl \
-Djavax.xml.parsers.SAXParserFactory=org.apache.crimson.jaxp. SAXParserFactoryImpl \
com.icl.saxon.StyleSheet \
-x org.apache.xml.resolver.tools.ResolvingXMLReader \
-y org.apache.xml.resolver.tools.ResolvingXMLReader \
-r org.apache.xml.resolver.tools.CatalogResolver \
-o php.html \
php.xml \
php.xsl

Xalan

xml.apache.or­g/xalan-j XSLT procesor z dílny Apache.

transformaci spustíme:

java \
-Djava.endorsed.dirs=/path_to_xalan/bin \
org.apache.xalan.xslt.Process \
-ENTITYRESOLVER org.apache.xml.resolver.tools.CatalogResolver \
-URIRESOLVER org.apache.xml.resolver.tools.CatalogResolver \
-V \
-IN php.xml \
-XSL php.xsl \
-OUT php.html

K výsledku je vhodné dodat nějaký pěkný CSS styl, který naše snažení patřičně prezentuje. A výsledek?

php.html

Automatizace

Samozřejmě pokaždé procházet celou touto procedurou je poněkud nepraktické a je dobré si vytvořit nějaký script, kterému jen předáme pár parametrů. Jedno takové řešení lze nalézt na www.fi.muni.cz/~xpa­vlov/xml, umí nejenom používat catalogy, ale i xinclude, mnoho transformací a lze jej jednoduše nastavovat.