Dříve než se pustíme do popisu struktury DocBookového dokumentu a jeho hlavních elementů, ukážeme si, jak můžeme vstupní soubor generovat do souborů výstupních. Je důležité to umět již na počátku, abychom mohli zkoušet dále popsané konstrukce.
Abychom mohli cokoliv generovat, musíme mít nainstalované XSL styly a XML procesory. Předpokládáme že to jsme již zvládli.
DocBook dokáže díky XSL stylům Normana Walshe generovat výstup do prakticky všech základních formátů. My si ukážeme jak generovat ty nejpoužívanější, generování těch speciálnějších (manuálové stránky, html help aj.) probíhá obdobně.
Styly pro generování HTML stránek jsou připraveny v adresáři xsl/html/
.
Zpravidla chceme generovat dva typy HTML:
chunk.xsl
- sada strukturovaných HTML stránek. Každá kapitola a sekce jsou v samostatných stránkách.
onechunk.xsl
- vygeneruje jednu dlouhou HTML stránku, která není dále strukturovaná
Jaký typ HTML chceme, záleží jen na nás.
Jak ale vlastně zvolit tuto XSL šablonu? Je to snadné - máme vesměs dvě možnosti. Buď předáme příslušnou XSL šablonu přímo XSLT procesoru jako parametr. V případě Saxonu by tento spouštěcí příkaz vypadal takto:
java -cp ... index.xml file:///c:/docbook/xsl/html/chunk.xsl
Místo tří teček se nachází kompletní parametry pro samotné spuštění
Saxonu (s podporou XML katalogů) na vstupní soubor
index.xml
. Ty zde z důvodu úspory místa neuvádíme, naleznete je však v
příslušných dávkových souborech. Použitá šablona je posledním
parametrem. Jelikož je umístěna na lokálním disku, je před ní uvedeno file:///
, pokud
máme aktivní internetové přípojení, mohli bychom ji specifikovat i přímo pomocí URL adresy.
Druhá možnost jak použít tuto šablonu je využití vlastních modifikovaných XSL stylů do kterých původní styl naimportujeme příkazem.
<xsl:import href="file:///c:/docbook/xsl/html/chunk.xsl" />
Pokud máme zprovozněné XML katalogy, naimportujeme jeho skutečnou URL adresu:
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl" />
Tento druhý způsob je mnohem výhodnější, neboť můžeme rovnou pomocí parametrů měnit strukturu výstupního HTML souboru. Seznam použitelných parametrů nalezneme v dokumentaci [Wal-02].
Programu Saxon pak jako parametr předáme přímo naši modifikovanou šablonu.
java -cp ... index.xml file:///c:/docbook/xsl/my_xsl/html.xsl
Např. tento parametr umožňuje vypnout generování sekcí jako samostatných
HTML stránek. Jeho přepnutí na hodnotu 0
tedy vytvoří méně strukturovaný HTML soubor.
<xsl:param name="chunk.section.depth" select="1"/>
Postup generování XHTML je naprosto stejný jako u generování HTML, pouze použijeme XSL styl z
adresáře xsl/xhtml
.
Ovšem pozor! Při generování XHTML nelze použít XSLT procesory Saxon ani Xalan, neboť ty si s tímto formátem nedokáží korektně poradit. Jedinou možností jak generovat dokumenty v tomto formátu je použití procesoru xsltproc. XHTML tedy pak generujeme např. tímto postupem:
set SGML_CATALOG_FILES=C:\docbook\my_dtd\catalog.xml c:\docbook\libxml\bin\xsltproc --catalogs --xinclude c:\docbook\xsl\xhtml\chunk.xsl index.xml
Uvedený příkaz spouští procesor xsltproc na vstupní soubor
index.xml
s použitím XHTML šablony chunk.xsl
.
Generování PDF je opět variací na dané téma. Jen si musíme uvědomit, že musíme využít FO styly a nějaký FO procesor. V kapitole o instalaci jsme si popsali způsob, jak FO procesor zprovoznit. Naším FO procesorem bude XEP.
Při generování PDF tedy provádíme dva kroky (viz obrázek 9.2 – „Průběh generování formátu PDF“).
generování FO souboru (např. fo.xml
pomocí Saxonu a stylu xsl/fo/docbook.xsl
převod tohoto FO souboru do PDF procesorem XEP
První krok je nám již známý z postupu generování HTML, jen použijeme jiný XSL styl.
Druhý krok spočívá ve spuštění procesoru XEP příkazem:
xep.bat c:\docbook\podpora\fo.xml
Soubor xep.bat
přichází s procesorem XEP a zapouzdřuje jeho volání.
Nejjednodušším způsobem pro nás, jak provést generování je samozřejmě použití našich připravených dávkových souborů.
Pro generování HTML parserem Saxon pak prostě spustíme
html_saxon.bat soubor.xml
XHTML generujeme zase zase pomocí
xhtml_xsltproc.bat soubor.xml
Pro generování PDF musíme provést kroky dva, tak jak již víme z předchozích kapitol.
fo_saxon.bat soubor.xml pdf_xep.pdf fo.xml
Proč tomu tak je viz obrázek 9.2 – „Průběh generování formátu PDF“. Jen podotkněme, že pokud
nemáme k dispozici parser XEP, stačí spustit dávku pdf_fop.pdf
místo
pdf_xep.pdf
.