Kapitola 9. Instalace

Obsah

9.1. DocBook DTD
9.2. DSSSL styly a Jade
9.3. XSL styly, XSLT a FO procesor
9.3.1. XSLT procesor
9.3.2. FO procesor

V následujících odstavcích se podíváme na základní instalaci DocBooku – na instalaci DTD a DSSSL a XSL stylů pro formátování, včetně příslušných DSSSL a XSLT procesorů.

9.1. DocBook DTD

DocBook sám o sobě není skutečně nic jiného než DTD pro XML (případně pro SGML). Aktuální verzi DTD lze stáhnout ze stránek OASIS – http://www.oasis-open.org/docbook/. Pro případ výpadku serveru, je DTD zrcadleno i na stránkách http://www.docbook.org. DTD je rozděleno do několika souborů a proto je nejlepší si stáhnout celý ZIP archiv. Následující postup předpokládá práci s XML verzí DTD 4.5.

Získaný archiv můžeme rozbalit na libovolné místo na disku. V dalším budeme předpokládat, že jsme DTD rozbalili do adresáře c:\docbook\dtd.

Pokud chcete pro zpracování DocBooku používat i nástroje určené pro SGML – např. Jade nebo PSGML mód v Emacsu, je ještě potřeba nastavit katalogové soubory.

Součástí DTD je i katalogový soubor docbook.cat, který zařadíme mezi načítané katalogy uložené v proměnné SGML_CATALOG_FILES.

SGML_CATALOG_FILES=c:\docbook\dtd\docbook.cat

Konkrétní provedení nastavení proměnné závisí na použité platformě. Ve Windows 95/98 musíme upravit soubor autoexec.bat a restartovat počítač, ve Windows NT/2000 se nastavení provádí pomocí Ovládací panelSystemPokročiléProměnné prostředí. V Unixu nejspíše nastavení proměnné provedeme v nějakém startovacím skriptu jako .profile nebo .bash.rc.

Jelikož některé aplikace dávají přednost systémovým identifikátorům před veřejnými, je užitečné do katalogového souboru docbook.cat přidat řádku

SYSTEM "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" "docbookx.dtd"

Správnou instalaci DTD můžeme otestovat například tak, že pomocí parseru provedeme validaci již existujícího docbookového dokumentu.

9.2. DSSSL styly a Jade

DSSSL styly původně vytvořil Norman Walsh. Nyní styly vyvíjí skupina vývojářů pod jeho vedením. Styly je možné získat na adrese http://docbook.sourceforge.net. Styly jsou distribuovány jako ZIP archiv, který můžeme rozbalit například do adresáře c:\docbook\dsssl. Na stejné stránce jako styly můžeme získat i jejich dokumentaci.

Pro zpracování stylů budeme potřebovat nějaký DSSSL procesor. V současné době je možné používat dva – Jade (http://www.jclark.com/jade/) a jeho dále vyvíjeného následníka OpenJade (http://openjade.sourceforge.net/). Dále budeme předpokládat, že jsme si Jade stáhli a nainstalovali jej do adresáře c:\docbook\jade. Je vhodné tento adresář přidat do cesty, aby se nám Jade snadno spouštěl.

Pro bezproblémovou práci DSSSL stylů s XML dokumenty budeme ještě potřebovat soubor http://www.oasis-open.org/cover/ISOEnts.zip. Ten obsahuje deklarace standardních ISO entit v SGML formátu. Soubor rozbalíme například do adresáře c:\docbook\isoent. Ve stejném adresáři vytvoříme soubor isoent.cat, který slouží jako katalog.

PUBLIC "ISO 8879:1986//ENTITIES Diacritical Marks//EN" "isodia"
PUBLIC "ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN" "isonum"
PUBLIC "ISO 8879:1986//ENTITIES Publishing//EN" "isopub"
PUBLIC "ISO 8879:1986//ENTITIES General Technical//EN" "isotech"
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN" "isolat1"
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 2//EN" "isolat2"
PUBLIC "ISO 8879:1986//ENTITIES Greek Letters//EN" "isogrk1"
PUBLIC "ISO 8879:1986//ENTITIES Monotoniko Greek//EN" "isogrk2"
PUBLIC "ISO 8879:1986//ENTITIES Greek Symbols//EN" "isogrk3"
PUBLIC "ISO 8879:1986//ENTITIES Alternative Greek Symbols//EN" "isogrk4"
PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN" "isoamsa"
PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Binary Operators//EN" "isoamsb"
PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Delimiters//EN" "isoamsc"
PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Negated Relations//EN" "isoamsn"
PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Ordinary//EN" "isoamso"
PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Relations//EN" "isoamsr"
PUBLIC "ISO 8879:1986//ENTITIES Box and Line Drawing//EN" "isobox"
PUBLIC "ISO 8879:1986//ENTITIES Russian Cyrillic//EN" "isocyr1"
PUBLIC "ISO 8879:1986//ENTITIES Non-Russian Cyrillic//EN" "isocyr2"

DSSSL styly jsou ve skutečnosti SGML dokumenty, pro jejich správné zpracování potřebujeme použít další katalogové soubory. Do SGML_CATALOG_FILES musíme ještě před katalog pro DocBook přidat katalog pro DSSSL styly (ten se distribuuje s Jade) a pro ISO entity.

SGML_CATALOG_FILES=c:\docbook\jade\catalog;c:\docbook\isoent\isoent.cat;c:\docbook\dtd\docbook.cat

Pro bezproblémový provoz je potřeba zavést katalogové soubory v tomto pořadí.

Jade je program původně určený pro SGML. Výběr správného kódování pro dokument nemusí být vždy úplně automatický. Kódování, které bude Jade na vstupu očekávat, se získává z proměnné prostředí SP_ENCODING. Pokud máme dokumenty v XML a používáme různá kódování, je vhodné nastavit proměnnou na hodnotu XML. Jade pak pro výběr kódování používá pravidla definovaná ve specifikaci XML. Jediný problém je v tom, že Jade pro kódování windows-1250 používá nestandardní identifikátor windows. Pokud máme dokumenty v tomto kódování, musíme proměnnou SP_ENCODING nastavit na hodnotu windows a všechny dokumenty pak musíme mít v kódování windows-1250. Kódování iso-8859-n jsou rozpoznávána správně, takže si můžeme vybrat mezi nastavením proměnné na hodnotu XML nebo ISO-8859-2.

9.3. XSL styly, XSLT a FO procesor

XSL styly opět vytvořil Norman Walsh a nyní se o jejich další vývoj stará širší komunita vývojářů. Je možné je stáhnout z adresy http://docbook.sourceforge.net. Styly jsou distribuovány jako ZIP archiv, který můžeme rozbalit například do adresáře c:\docbook\xsl. Dokumentace je ke stylům he šířena jako samostatný archiv.

Pro zpracování stylů budeme potřebovat nějaký XSLT a případně i FO procesor.

9.3.1. XSLT procesor

Mezi nejlepší dnešní XSLT procesory patří Saxon. Pro pohodlnou práci se Saxonem je velice vhodné v něm aktivovat podporu katalogů a XInclude.

Saxon s podporou XML katalogů a XInclude

Všechny komponenty Saxonu a podpora katalogových souborů jsou dostupné jako javové archivy. Pro lepší orientaci můžeme všechny potřebné soubory nahrát do společného adresáře, např. c:\docbook\batch. Jedná se přitom o následující soubory:

saxon.jar

Samotný XSLT procesor Saxon. Tento javový archiv je obsažen přímo v jeho distribuci – http://saxon.sourceforge.net. Je potřeba použít Saxon z řady 6.x (např. 6.5.5).

resolver.jar

Samotná podpora katalogových souborů. Je součástí balíku XML Commons dostupného na adrese http://mirror.styx.cz/apache/xml/commons/, konkrétně v souboru xml-commons-resolver-1.x.zip.

xercesImpl.jar

Parser Xerces. Umožňuje spolupráci Saxonu s katalogovými soubory a přidává implementaci XInclude. Je dostupný na adrese http://xml.apache.org/dist/xerces-j/. Novější verze Javy (od verze 1.4 výše) obsahují již Xerces přímo v sobě, takže jej není nutné instalovat.

saxon643.jar

Rozšiřující funkce pro lepší zpracování DocBooku. Soubor je přímo součástí standardní distribuce XSL stylů (v podadresáři extensions).

Pro snadné spouštění Saxonu si můžeme vytvořit dávkový soubor saxon.bat.

@java -cp c:\docbook\batch\;c:\docbook\batch\resolver.jar;c:\docbook\batch\xercesImpl.jar;c:\docbook\batch\saxon.jar;c:\docbook\batch\saxon65.jar -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration -Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.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 %*

Javová cesta ke třídám je nastavena i přímo do adresáře c:\docbook\batch, protože zde je potřeba umístit soubor CatalogManager.properties. Pokud chceme, aby se použil katalogový soubor pro DocBook, můžeme do souboru uložit následující:

#CatalogManager.properties

verbosity=1

# Always use semicolons in this list
catalogs=file:///c:/docbook/dtd/catalog.xml

prefer=public

static-catalog=yes

allow-oasis-xml-catalog-pi=yes

catalog-class-name=org.apache.xml.resolver.Resolver

Od verze 4.2 je součástí distribuce DTD (c:\docbook\dtd) i odpovídající soubor catalog.xml s XML katalogovým souborem, který používáme. Jen pro ilustraci se můžeme podívat na to, jak zhruba vypadá.

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"
         prefer="public">

    <public publicId="-//OASIS//DTD DocBook XML V4.2//EN"
            uri="docbookx.dtd"/>
    <public publicId="-//OASIS//ENTITIES DocBook XML Notations V4.2//EN"
            uri="dbnotnx.mod"/>
    <public publicId="-//OASIS//ENTITIES DocBook XML Character Entities V4.2//EN"
            uri="dbcentx.mod"/>
    <public publicId="-//OASIS//ELEMENTS DocBook XML Information Pool V4.2//EN"
            uri="dbpoolx.mod"/>
    <public publicId="-//OASIS//ELEMENTS DocBook XML Document Hierarchy V4.2//EN"
            uri="dbhierx.mod"/>
    <public publicId="-//OASIS//ENTITIES DocBook XML Additional General Entities V4.2//EN"
            uri="dbgenent.mod"/>
    <public publicId="-//OASIS//DTD DocBook XML CALS Table Model V4.2//EN"
            uri="calstblx.dtd"/>

</catalog>

V souboru CatalogManager.properties můžete do vlastnosti catalogs zadat i více souborů, stačí je oddělit středníkem.

Saxon s XML katalogy je schopný mapovat i URL adresy stylů tak, aby byly načítány z lokálního disku a ne ze sítě. Pro aktivování této funkce stačí do katalogového souboru přidat instrukci:

<rewriteURI
  uriStartString="http://docbook.sourceforge.net/release/xsl/current/" 
  rewritePrefix="file:///c:/docbook/xsl/"/>

Saxon s podporou SGML catalogů

Katalogové soubory původně vznikly pro jazyk SGML a jsou definovány v Technickém prohlášení OASIS TR9401. Této syntaxi katalogových souborů rozumí i Jade a proto můžeme používat jeden katalog pro různé programy.

Poznámka

Doporučuji vám používat Saxon s podporou XML katalogů, protože nabízí více funkcí, např. mapování stylů na jejich lokální kopie. Následující postup je zde zachován spíše z historických důvodů.

Všechny komponenty Saxonu a podpora katalogových souborů jsou dostupné jako javové archivy. Pro lepší orientaci můžeme všechny potřebné soubory nahrát do společného adresáře, např. c:\docbook\batch. Jedná se přitom o následující soubory:

saxon.jar

Samotný XSLT procesor Saxon. Tento javový archiv je obsažen přímo v jeho distribuci – http://saxon.sourceforge.net.

crimson.jar

Parser, který podporuje mnoho kódování včetně iso-8859-2 a windows-1250. Parser můžeme získat například na adrese http://xml.apache.org/dist/crimson/.

saxoncatalog.jar

Soubor s podporou katalogových souborů pro Crimson. Lze stáhnout z http://www.kosek.cz/xml/saxon/saxoncatalog.jar.

saxon65.jar

Rozšiřující funkce. Soubor je přímo součástí standardní distribuce XSL stylů.

Pro snadné spouštění Saxonu si můžeme vytvořit dávkový soubor saxon.bat.

@java -cp c:\docbook\batch\crimson.jar;c:\docbook\batch\saxoncatalog.jar;c:\docbook\batch\saxon.jar;c:\docbook\batch\saxon65.jar -Dxml.catalog.files=%SGML_CATALOG_FILES% com.icl.saxon.StyleSheet -w0 -x cz.kosek.CatalogXMLReader -y cz.kosek.CatalogXMLReader %1 %2 %3 %4 %5 %6 %7 %8 %9

xsltproc

Místo Saxonu můžete použít libovolný jiný XSLT procesor, i když těžko najdete nějaký jiný, který nabízí srovnatelný výkon a funkčnost. V některých případech je ještě rychlejší než Saxon xsltproc. Zatím pro něj však nejsou hotová všechna rozšíření potřebná pro některé pokročilé funkce stylů a občas se v xsltproc objeví nějaká chyba.

Windows verzi xsltproc můžete získat na adrese http://www.zlatkovic.com/projects/libxml/binaries.html. Stáhněte si binární distribuci knihoven libxml, libxslt, iconv a zlib. Ze stažených archivů stačí nakopírovat následující soubory do nějakého adresáře, která je v cestě (např. c:\docbook\batch).

libxml2.dll libexslt.dll xsltproc.exe
iconv.dll zlib1.dll  
libxslt.dll xmllint.exe  

Aby xsltproc našel katalogový soubor (použije se stejný XML katalog jako v předchozí sekci pro Saxon), musíme jeho URI adresu nastavit v proměnné prostředí XML_CATALOG_FILES. V našem případě bychom ji nastavili na hodnotu file:///c:/docbook/dtd/catalog.xml.

9.3.2. FO procesor

Instalace FO procesoru závisí na konkrétním FO procesoru, který používáte.

XEP

FO procesor od firmy RenderX. Kromě komeční placené verze lze pro osobní použití zdarma získat verzi „personal“, která na každou stránku dolů vloží malé logo. Počeštění XEPu (české vzory dělení slov a podpora českých znaků), je dostupné na adrese http://www.kosek.cz/sw/xep/.

XEP je schopný před samotným formátováním provést rovnou i transformaci. V tom případě je dobré si dávku pro spouštění XEPu upravit tak, aby XEP rovnou podporoval XML katalogy a XInclude, tak jak je popsáno v „Saxon s podporou XML katalogů a XInclude“. Dávka xep.bat pak může vypadat například takto:

@echo off
rem   This batch file encapsulates a standard XEP call. 

set CP=%~dp0\xercesImpl.jar;%~dp0\;%~dp0\resolver.jar;%~dp0\saxon65.jar;%~dp0\..\XEP\lib\xep.jar;%~dp0\..\XEP\lib\saxon.jar;%~dp0\..\XEP\lib\xt.jar

java -Xmx512M -classpath "%CP%" -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration -Dcom.renderx.sax.entityresolver=org.apache.xml.resolver.tools.CatalogResolver -Dcom.renderx.jaxp.uriresolver=org.apache.xml.resolver.tools.CatalogResolver com.renderx.xep.XSLDriver "-DCONFIG=%~dp0\..\XEP\xep.xml" %*

set CP=

XFC

XFC je komerční procesor FO, který je však dostupný zdarma (ve verzi „standard“). Umí formátovací objekty převádět do formátů RTF, WordML (formát dokumentů podporovaný v MS Word 2003 a vyšší) a ODF (podporovaný např. v OpenOffice).

FOP

FOP je open-source procesor od sdružení Apache – http://xml.apache.org/dist/fop/. Standardní verze neobsahuje podporu českých znaků a dělení slov, je však k dispozici samostatně na adrese http://www.kosek.cz/sw/fop/index.html.

Antenna House

Opět komerční FO procesor, který ve své zkušební verzi doplní na každou stránku reklamní odkaz. Umožňuje prohlížení výsledného dokumentu přímo na obrazovce. Podporuje češtinu. K dispozici je na adrese http://www.antennahouse.com/. České vzory pro dělení jsou k dispozici na adrese http://www.kosek.cz/sw/axf/index.html.

© Jiří Kosek 2007
Tento dokument je určen výhradně pro osobní potřebu seznámení se systémem DocBook. Jakékoliv jiné použití, včetně dalšího šíření, pořizování kopií apod. je výslovně zakázáno a bude považováno za porušení autorských práv.