Hlavní navigace

DocBook a jeho použití (2)

Jan Pavlovič 10. 4. 2003

Ukážeme si, jak napsat konkrétní dokumentaci v DocBooku a transformovat ji do XHTML. Plus několik pokročilejších rad pro použití catalogů a jednotlivých XSLT procesorů.

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í &#x002D; 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.

Našli jste v článku chybu?

4. 1. 2006 11:38

Ten odkaz nefunguje. Máš to čistě vycucaný z prstu (bez ironie), nebo se opíráš o něco již existujícího? Docela by mě to zajímalo.

16. 4. 2003 8:35

Tomáš Kulhánek (neregistrovaný)

Píšu veškerou dokumentaci v Docbooku a pro ty, kdo se neradi hrabou přímo v XML dokumentech, mohu doporučit editor xmlmind na http://www.xmlmind.com/xmleditor/

Standardní edice je k dispozici zdarma a podporuje DocBook i Simple DocBook, psaní je skoro wysiwyg, ale vyžaduje od uživatele základní znalost struktury DocBooku. Možný je i trochu omezený přístup do XML zdrojáků. Navíc obsahuje už vlastní styly okamžitě použitelné pro konverzi do HTML, i když používám vlastní. Editor běží v Javě a v…

Vitalia.cz: Jak koupit Mikuláše a nenaletět

Jak koupit Mikuláše a nenaletět

Vitalia.cz: I církev dnes vyrábí potraviny

I církev dnes vyrábí potraviny

Lupa.cz: E-shopy: jen sleva už nestačí

E-shopy: jen sleva už nestačí

Podnikatel.cz: Dárky v podnikání. Jak je uplatnit v daních?

Dárky v podnikání. Jak je uplatnit v daních?

Podnikatel.cz: Přehledná titulka, průvodci, responzivita

Přehledná titulka, průvodci, responzivita

Měšec.cz: Zdravotní a sociální pojištění 2017: Připlatíte

Zdravotní a sociální pojištění 2017: Připlatíte

Měšec.cz: Finančním poradcům hrozí vracení provizí

Finančním poradcům hrozí vracení provizí

Lupa.cz: Proč firmy málo chrání data? Chovají se logicky

Proč firmy málo chrání data? Chovají se logicky

Vitalia.cz: Tesco: Chudá rodina si koupí levné polské kuře

Tesco: Chudá rodina si koupí levné polské kuře

Měšec.cz: Kdy vám stát dá na stěhování 50 000 Kč?

Kdy vám stát dá na stěhování 50 000 Kč?

Podnikatel.cz: EET: Totálně nezvládli metodologii projektu

EET: Totálně nezvládli metodologii projektu

120na80.cz: Rakovina oka. Jak ji poznáte?

Rakovina oka. Jak ji poznáte?

DigiZone.cz: NG natáčí v Praze seriál o Einsteinovi

NG natáčí v Praze seriál o Einsteinovi

Měšec.cz: U levneELEKTRO.cz už reklamaci nevyřídíte

U levneELEKTRO.cz už reklamaci nevyřídíte

Root.cz: Vypadl Google a rozbilo se toho hodně

Vypadl Google a rozbilo se toho hodně

Podnikatel.cz: 1. den EET? Problémy s pokladnami

1. den EET? Problémy s pokladnami

Podnikatel.cz: Prodává přes internet. Kdy platí zdravotko?

Prodává přes internet. Kdy platí zdravotko?

DigiZone.cz: Další dva kanály nabídnou HbbTV

Další dva kanály nabídnou HbbTV

Podnikatel.cz: K EET. Štamgast už peníze na stole nenechá

K EET. Štamgast už peníze na stole nenechá

120na80.cz: Pánové, pečujte o svoje přirození a prostatu

Pánové, pečujte o svoje přirození a prostatu