Pro práci s DocBookem budeme potřebovat tyto nástroje:

DocBook DTD získáme z adresy http://www.docbook.org/. V sekci „DocBook Schemas“ zvolíme položku „XML“ a vybereme verzi.

XSL styly od Normana Walshe získáme z http://docbook.sourceforge.net/. Obsahují vše potřebné pro transformaci do různých výstupních formátů. Pokud nebudeme s těmito styly v budoucnu spokojeni, můžeme je sami modifikovat.

XSLT Procesory

Xalan je vyvíjen a spravován organizací Apache. Aktuální verzí je v2.6.0. Existuje ve verzi napsané v Javě a v C++. Doporučujeme preferovat Java verzi, která je lepší. Součástí XSL stylů Normana Walshe je i knihovna s rozšířeními pro Xalan. Pro generování dokumentů v DocBooku je použitelný, avšak obsahuje několik nepříjemných chyb. Zjištěn byl např. problém s generováním rejstříků.

Každopádně distribuci Xalann tak či tak potřebujeme, neboť z ní využijeme parser Xerces pro práci se Saxonem.

Saxon je asi nejpoužívanější XSLT procesor použitelný s DocBookem. Poslední použitelná verze je 6.5.3, novější nebudou fungovat. Je to způsobeno tím, že verze 6 ještě implementuje XSLT 1.0, kterou používá DocBook. Novější verze Saxonu implementují XSLT 2.0.

I pro Saxon existuje rozšiřující knihovna v distribuci XSL stylů Normana Walshe (extensions/saxon653.jar). Tato rozšíření však běžný uživatel nevyužije.

Saxon je třeba používat spolu s XML parserem Xerces, jenž je např. součástí distribuce Xalanu, neboť vestavěný parser v Saxonu obsahuje několik chyb. Naštěstí to není žádný problém a v kapitole 9.2 – „Instalace a zprovoznění“ si ukážeme jak na to.

Posledním použitelným parserem je xsltproc. Ten je vyvíjen jako součást projektu Gnome a postaven nad knihovnou libxslt. V Linuxu jej najdeme standardně, existuje však i port pro Windows, který můžeme získat z adresy http://www.zlatkovic.com/libxml.en.html.

Xsltproc jej také jediný nástroj z výše uvedených, kterým můžeme generovat XHTML. Saxon ani Xalan to nezvládají korektně. Tento nástroj také narozdíl od předchozích zvládá validaci XML dokumentů a podporuje XInclude.

Dalším užitečným nástrojem pro nás ještě může být Xmllint, jenž je také součástí knihovny libxml. Chová se stejně jako xsltproc, avšak nedokáže provádět XSL transformace. Je použitelný pro validaci dokumentů a pro jejich zpracování technologií XInclude.

Všechny uvedené procesory mají zabudovanou částečnou podporu pro EXSLT. Do Xalanu i Saxonu je ještě možno přidat rozšiřující knihovny.

Pro generování PDF či PS budeme potřebovat nějaký FO procesor. Zde doporučujeme vybrat multiplatformní XEP, který je sice komerční, ale pro školní instituce je zdarma.

Starší programy FOP a PassiveTex se již nevyvíjí a nemají tudíž do budoucna perspektivu. Navíc nepodporují standard FO příliš dobře. FOP ještě dále zmíníme, jako alternativa ke XEPu lze použít, ovšem nelze od něj očekávat převratné výsledky.

Existují samozřejmě i další FO procesory, bohužel však komerční (např. Antenna House XSL Formater). Vzhledem k jejich ceně jsou však pro nás nedostupné.

Textový editor můžeme použít libovolný. Některé zajímavé uvedeme v dalším textu.

Zprovoznění všech nástrojů tak aby spolu správně spolupracovaly je poměrně složitá problematika a vyžaduje pevné nervy a hodně experimentování.

Pro zjednodušení a úsporu času jsme připravili předinstalovaný balík pro systém Windows, který obsahuje potřebné nástroje a nastavení, stačí jej jen rozbalit a můžeme pracovat. Bohužel balík vyžaduje pevné umístění v systému a to konkrétně C:\DocBook\. Funguje v systému Windows XP, jinde nebyl testován.

V balíku se nacházejí procesory Saxon, Xalan, xsltproc i xmllint spolu s dávkovými soubory pro jejich spuštění. Taktéž balík obsahuje přednastavené katalogové soubory a ukázkové příklady.

Struktura tohoto adresáře je následující:

V této připravené distribuci jsou již zprovozněny XML katalogy a okamžitě lze generovat HTML výstup. Pro generování PDF musíme ještě doinstalovat procesor XEP do příslušného podadresáře.

Podadresář C:\DocBook\xep\ je prázdný. Je do něj třeba dodatečně doinstalovat procesor XEP pokud budeme chtít generovat PDF. Z licenčních důvodů nemůže být bohužel přiložen. Pokud jej budete doinstalovávat, nezapomeňte provést jeho počeštění, tak jak je popsáno v návodu na instalaci.

Ne každému však předpřipravená instalace vyhovuje. Pokud chcete zprovoznit nástroje sami, uvádíme návod jak na to. Budeme popisovat instalaci pro systém Windows XP do adresáře C:\DocBook. Instalaci pro systém Linux popisuje práce Michala Dudy [Dud-05].

1. DocBook DTD

Archiv s DocBook DTD v4.3 stáhneme z http://www.docbook.org/xml/4.3/index.html a jeho obsah rozbalíme do podadresáře C:\DocBook\dtd\.

2. DocBook XSL styly

Archív s XSL styly Normana Walshe stáhneme z http://docbook.sourceforge.net/projects/xsl/index.html. Aktuální verze je v době psané této podpory 1.68.1 - archiv docbook-xsl-1.68.1.zip.

Tento archív rozbalte do podadresáře C:\DocBook\xsl\. Ovšem pozor! Veškeré soubory jsou v tomto balíku obsažené v adresáři docbook-xsl-1.68.1. Proto to udělejte třeba tak, že balík rozbalíte jinam a pak obsah tohoto adresáře přesuňte do C:\DocBook\xsl\.

Pro kontrolu uvádíme, že vám tímto postupem vznikne mimo jiné C:\DocBook\xsl\html/chunk-html.xsl.

3. Xalan

Ať již chceme parser Xalan používat nebo ne, musíme jej mít nainstalovaný. Respektive jeho jednu součást - parser Xerces, tedy soubor xercesImpl.jar, který budeme potřebovat pro práci s parserem Saxon.

Xalan stáhneme z adresy http://xml.apache.org/xerces2-j/, jedná se o archiv xalan-j-current-bin.zip (v2.6.0) a obsah tohoto archivu rozbalíme do podadresáře C:\DocBook\xalan\. Pozor! Tento archiv opět obsahuje v sobě podadresář xalan-j_2_6_0. Proto na příslušné místo rozbalte pouze obsah tohoto podadresáře.

Pro kontrolu uvádíme, že tímto postupem vznikne mimo jiné C:\DocBook\xalan\bin\xalan.jar.

4. Saxon

Saxon pro nás bude preferovaným procesorem. Stáhneme jej z adresy http://saxon.sourceforge.net/. Avšak musíme použít verzi 6.5.3. Jedná se o archiv saxon6_5_3.zip.

Tento archiv rozbalíme do C:\DocBook\saxon\.

Pro kontrolu uvádíme, že tímto postupem vznikne mimo jiné C:\DocBook\saxon\saxon.jar.

5. xsltproc

Vše potřebné pro Windows se nachází na adrese ftp://ftp.zlatkovic.com/libxml/. Zde si stáhneme poslední verze zde umístěných knihoven. Všechny archivy v sobě opět obsahují adresář se jménem knihovny. Proto archivy rozbalíme do C:\DocBook\libxml tak, že tam umístíme pouze obsahy těchto adresářů.

Zároveň s procesorem xsltproc budeme mít ve stejném adresáři k dispozici i program Xmllint.

Pro kontrolu uvádíme, že tímto postupem vznikne mimo jiné C:\DocBook\libxml\bin\xsltproc.exe.

6a. XEP

Použití parseru XEP je volitelné. Pokud nebudeme chtít generovat soubory PDF, nemusíme jej vůbec instalovat. Bohužel jeho funkčnost je podmíněna vlastnictvím licence. Bez ní je funkčnost XEPu velmi omezená.

XEP získáme z adresy http://www.renderx.com. Jedná se o program napsaný v Javě s vlastním instalátorem a jeho instalace je tedy triviální. Program nainstalujte do adresáře C:\DocBook\xep\.

XEP standardně neobsahuje instalaci češtiny. Michal Duda v rámci [Dud-05] připravil balík xep-czech.zip. Tento balík obsahuje české vzory dělení slov, postscriptové fonty Nimbus spolu s upraveným konfiguračním souborem. Dále obsahuje podporu katalogů pro SVG obrázky, vkládané do PDF.

6b. FOP

Pokud nemáme k dispozici XEP, ale chceme přesto generovat PDF soubory, můžeme využít open- source FO procesor FOP. Ten bohužel nepodporuje FO standard a plno věcí neumí nebo si je dělá po svém, avšak i tak je použitelný. Navíc již není FOP aktivně vyvíjen.

Pokud tedy máte XEP, přeskočte přímo na část 7. XML katalogy.

FOP stáhneme z adresy http://www.apache.org/dyn/closer.cgi/xml/fop. Jedná se o archiv fop-current-bin.zip, který opět obsahuje jeden podadresář s dalšími soubory. Obsah tohoto podadresáře rozbalíme do C:\DocBook\fop.

Dále je nutno do programu přidat podporu češtiny. Postup zveřejnil Jiří Kosek. My jsme již příslušné modifikace provedli a výsledkem je balík určený přímo pro naši instalaci.

7. XML katalogy

XML katalogy je způsob, jakým lze mapovat URL adresy na soubory v našem lokálním systému. Abychom mohli totiž XML dokumenty zpracovávat, musíme nástrojům které to provádějí specifikovat kde naleznou příslušné DTD a XSL soubory. Pokud jsme neustále připojeni k Internetu, prostě v DTD uvedeme jejich URL adresy. Pokud ale připojení nemáme, můžeme třeba místo URL adresy v DTD uvést plnou cestu umístění tohoto souboru v našem systému. Tím však ztrácíme přenositelnost XML dokumentu. XML katalog nám umožní použití URL v DTD s tím, že se díky němu provede přemapování na příslušný lokální soubor v našem systému.

Pro práci s katalogy budeme potřebovat knihovnu Resolver. Z tohoto archivu nám stačí pouze soubor resolver.jar, který nakopírujeme do adresáře C:\DocBook\resolver\.

Tato knihovna automaticky načítá soubor CatalogManager.properties, ve kterém jsou definovány cesty ke XML katalogům. Tento soubor bude mít v našem případě následující obsah:

#CatalogManager.properties

verbosity=1

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

prefer=public

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

Do adresáře C:\DocBook\my_xsl\ umístíme samotný XML katalog, který v sobě bude obsahovat všechny ostatní katalogové soubory.

<?xml version='1.0'?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public">
 <nextCatalog catalog="../dtd/catalog.xml" />
 <nextCatalog catalog="../xsl/catalog.xml" />
</catalog>

Jak vidíme, tento soubor do sebe vkládá katalog DTD DocBooku, který je standardně obsažen v jeho distribuci. V distribučním archivu XSL stylů však katalog obsažen není, proto vytvoříme v C:\DocBook\xsl soubor catalog.xml s tímto obsahem:

Výpis kódu 9.1: Katalog pro XSL styly
<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
   "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/" rewritePrefix="file:///c:/docbook/xsl/"/>
  <rewriteSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/current/" rewritePrefix="file:///c:/docbook/xsl/"/>
  <delegateURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/" catalog="file:///c:/docbook/xsl/catalog.xml"/>
  <delegateSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/current/" catalog="file:///c:/docbook/xsl/catalog.xml"/>
</catalog>

8. Uživatelské XSL styly

Do adresáře C:\DocBook\my_xsl umístíme naše vlastní modifikované XSL styly, které budeme používat pro generování výstupních dokumentů. Jedná se o soubory html.xsl, xhtml.xsl, fo.xsl, slides_html.xsl, slides_fo.xsl.

9. Dávkové soubory

Obsah dávkových soubory pro spuštění transformace dokumentů v jednotlivých programech zde nebudeme z důvodu jejich obsáhlosti uvádět.

Vždy stačí spustit příslušnou dávku v adresáři s naším dokumentem. Dávkové soubory očekávají jeden parametr, kterým je název kořenového souboru našeho dokumentu.

 > html_saxon.bat index.xml

XSL šablony se jako parametr nepředávají, jsou načítány z našeho modifikovaného XSL souboru. Dávkový soubor však můžete snadno upravit dle svých představ.