Obsah
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ů.
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í → → → . 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.
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
.
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.
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.
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/"/>
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.
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
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
.
Instalace FO procesoru závisí na konkrétním FO procesoru, který používáte.
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 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 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.
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.