Celou tvorbu dokumentace v DocBooku můžeme rozdělit na tři části:
- napsání dokumentace
- parametrizace a nastavení
- 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/~xpavlov/xml/tutorial.html
Samozřejmě si musíme stáhnout XSL styly pro transformace:
sourceforge.net/projects/docbook/
A DTD gramatiku:
www.oasis-open.org/docbook/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 :).
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"/>
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.
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/libxml/
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.org/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?
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/~xpavlov/xml, umí nejenom používat catalogy, ale i xinclude, mnoho transformací a lze jej jednoduše nastavovat.
ČLÁNKY DO MAILU