Jak na DocBook na Windows

21.5.2012 21:52 | Přečteno: 1522× | Různé

Tento zápisek je tady v prvé řadě proto, abych dokázal rychle nainstalovat vše nutné k DocBooku, až se zase ocitnu na počítači s Windows a budu potřebovat něco psát. Proč tady článek vlastně je? Zejména proto, že ne všichni se uživí Linuxem a hodně Linuxáků má v práci Windows.

Pro kolegy s Linuxem může mít článek taky jistý přínos, i když na Linuxu plno věcí řešit nemusí, protože v distribuci mají odladěné balíčky.

Pokud chcete postupovat podle tohoto návodu, potřebujete počítač s Windows a v něm nainstalované něco, co má utilitu make (nejspíš cygwin).

Úvod

Tak tedy začněme s tím DocBookem. Nejdřív si ujasněme, co to vlastně znamená psát v DocBooku. DocBook není aplikace, je to datový formát. V jeho psaní nám můžou pomoci různé nástroje, které splňují určité požadavky. Je to podobné jako psaní prostého textu, existuje mnoho textových editorů, které se dají použít, přičemž po uložení je výsledek vždy stejný s kterýmkoliv z nich.

Formát DocBook je obyčejné XML. Ve specifikaci je popsáno, jak takové konkrétní XML vypadá, jaké obsahuje elementy, jak můžou být elementy zanořeny apod. Technicky je struktura popsána pomocí DTD (DocBook do verze 4.*), nověji se však používá XML Schema (DocBook 5.*), které umí omezení popsat přesněji, než DTD, zejména tedy jsou věci, které pomocí DTD nejde omezit (nebo to je příliš pracné) a pomocí XML schema to jde. Je třeba upozornit, že zejména omezení pomocí DTD není tak striktní, jako samotná specifikace, může tedy vzniknout XML, které je validní podle DTD, ale nevyhoví specifikaci.

Psaní v DocBooku

Pro nedočkavé uveďme, jak se vlastně píše takový DocBookový dokument. Pokud jste v oblasti nováčci, sáhnete po nějakém grafickém XML editoru, který už v základu podporuje formát DocBook (nebudu tady rozebírat, co přesně znamená podporovat DocBook, to bych se moc zamotal).

Mně se osvedčil editor XML mind [1]. Pokud vím, tak má placenou a neplacenou verzi, která je ovšem omezená na nekomerční použití. Na hraní to stačí. Pokud si oblíbíte jiný editor, který umí DocBook 5, není s tím problém, na výsledek to nemá vliv.

Od takového editoru se očekává, že vede člověka tak, aby napsal validní dokument a nějakou rozumnou grafickou formou mu dokument zobrazí. Tady ale musím zdůraznit, že zobrazení v editoru se pravděpodobně bude velmi lišit od výsledku převedeného do HTML nebo PDF.

Psaní dokumentu je pak velice jednoduché, asi jako v textovém procesoru (tady trošku přeháním, neplacené editory nejsou žádná sláva). Rozdíl je v tom, že text neoznačujeme podle vzhledu, ale podle významu. Takže nenajdete možnost napsat text tučně, kurzívou nebo jakkoliv jinak. Místo toho najdete prvky pro označení textu například jako parametr, příkaz systému apod. DocBook definuje poměrně hodně elementů, nejlepší přehled je asi v knize [2].

Zpracování DocBooku -- nástroje

Když máme dokument napsaný, je třeba s ním dál pracovat, zejména asi konvertovat do různých formátů. Řekněme, že jako výstupní formát chceme (X)HTML a PDF. Navíc budeme chtít použít možností nastavení, které mají standardní XSLT šablony, případně i šablony lehce upravit.

Pokud člověk umí anglicky, tak nejlepší je čerpat informace přímo od zdroje, v knize DocBook XSL: The Complete Guide [3]. Člověk je ale tvor líný, takže to tady přežvýkám a zestručním.

Konverze DocBooku může být vícekroková, přičemž v každém kroku potřebujeme jiný program. Pro každý takový krok najdete více programů napsaných k témuž účelu. Naštěstí je v této oblasti skoro všechno standardizováno, takže se dají programy zaměňovat za jiné a všechno by mělo fungovat, pokud nepoužijeme nějakou specialitku.

Nejdřív potřebujeme něco, co nám umí přechroustat text, který vypadne z XML editoru. Nejjednodušší je asi převod do (X)HTML. Tam nám stačí XML processor, který provede konverzi jedním příkazem. Převod do PDF je dvoukrokový a kromě XML procesoru potřebuje ještě FO processor (FO = formatting objects).

Po vyzkoušení XML procesorů jmenovaných v [3] jsem skončil u XML procesoru Xalan [4]. Je napsaný v Javě, což sice znamená větší nároky na HW, ale je multiplatformní, což ocení všichni, kteří pendlují mezi více systémy. Zkoušel jsem i Saxon, ale něco mi u něj chybělo, už nevím co.

Dále potřebujeme něco, čemu se říká XML Resolver, asi to není úplně nutné, ale bude se hodit velice brzo. Já jsem nainstaloval Apache XML Commons Resolver [5]. Vysvětlení významu je v [6].

Pokud jde o FO procesor, používám FOP [7], opět to je program napsaný v Javě, což mi připomíná, že si musíte nainstalovat i tu Javu. Pokud chcete psát v češtině, stáhněte si balíček s úpravami pro češtinu (viz [8]).

Teď je čas na XSLT šablony. Naštěstí si už pár lidí dalo tu práci a napsali stylesheety pro převod z DocBooku do jiných formátů, takže nám ušetřili plno práce. Pod poslední revizí je podpsaný Norman Walsh. XSLT stylesheety si stáhnete ze stránek [9]. Na mém počítači mám nainstalován balíček docbook-xsl-ns-1.75.2.tar.gz, to ns v názvu je důležité, je to potřeba pro DocBook verze 5 (vysvětlení je v souboru README uvnitř balíčku). Těmto šablonám budu dále říkat standardní šablony.

Teď si to všechno nainstalujte podle příslušných návodů (většinu stačí někam rozbalit, já k tomu používám adresář C:/Local). Když máme všechno nainstalované, je čas přejít k nastavení a vlastnímu psaní.

Zpracování DocBooku -- postup

Na začátku jsem psal, že budeme chtít konfigurovat a upravovat standardní šablony. Není dobrý nápad upravovat přímo originály, to se raději naučíme jiný postup. Nevím, jak to vysvětlit jednoduše a v malých krocích, tak raději popíši svou konfiguraci, kterou si později upravíte podle svých potřeb. Konfigurační soubory mám adresáři, kde píšu i text, takže neovlivňuje ostatní uživatele, ani jiné projekty.

Vytvoříme si adresář, kam později uložíme náš napsaný text, budeme mu říkat třeba $WORK.

V adresáři $WORK vytvoříme soubor CatalogManager.properties s tímto obsahem

catalogs=catalog.xml;
relative-catalogs=false
static-catalog=yes
catalog-class-name=org.apache.xml.resolver.Resolver
verbosity=1

Význam položek si asi musíte nastudovat jinde, třeba tady [6].

Potom vytvoříme soubor $WORK/catalog.xml (viz první řádek souboru výše) s následujícím obsahem.

<?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">
    <group  xml:base="file:///c:/Local/docbook-xsl/1.75.2/">
        <uri
            name="fo-docbook.xsl"
            uri="fo/docbook.xsl"/>
        <uri
            name="html-docbook.xsl"
            uri="html/docbook.xsl"/>

        <uri
            name="xhtml-docbook.xsl"
            uri="xhtml/docbook.xsl"/>

        <uri
            name="html-chunk-common.xsl"
            uri="html/chunk-common.xsl"/>

        <uri
            name="xhtml-chunk-common.xsl"
            uri="xhtml/c.xsl"/>

     <uri
            name="html-changebars.xsl"
            uri="html/changebars.xsl"/>

     <uri
            name="xhtml-changebars.xsl"
            uri="xhtml/changebars.xsl"/>

    </group>
</catalog>

Na 7. řádku si upravte cestu ke standardním šablonám.

Dále si v adresář $WORK vytvoříme podadresář s název custom_xsl a v něm pro začátek podadresář html. V tomto adresáři vytvoříme soubor docbook.xsl s tímto obsahem

<?xml version='1.0'?>
<xsl:stylesheet
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    xmlns:d="http://docbook.org/ns/docbook"
    exclude-result-prefixes="d"
version="1.0">

<!-- <xsl:import href="html-docbook.xsl"/> -->
<xsl:import href="html-changebars.xsl"/>
<xsl:param name="paper.type" select="'A4'"/>
<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="pixels.per.inch" select="150"/>

</xsl:stylesheet>

No a nakonec si vytvořte Makefile (nejlépe v adresáři $WORK), abyste nemuseli příkazy psát pořád dokola. Můj má tento obsah.

#user settings
RM=rm -f
XALAN_HOME=c:\Local\xalan\2_7_1
DOCBOOK_HOME=c:\Local\docbook-xsl\1.75.2
FO_PROCESSOR=c:/Local/fop/fop.bat
FO_PROCESSOR_CONFIG=-c c:/Local/fop/conf/myfop.xconf
XML_RESOLVER=C:\Local\xml-commons-resolver\1.2\resolver.jar

#don't touch the rest
CLASSPATH:= "${CLASSPATH};$(XALAN_HOME)\xalan.jar;$(XALAN_HOME)\xml-apis.jar;$(XALAN_HOME)\xercesImpl.jar;$(DOCBOOK_HOME)\extensions\xalan27.jar;$(XML_RESOLVER)"

XSLT_PROCESSOR=java org.apache.xalan.xslt.Process \
   -ENTITYRESOLVER  org.apache.xml.resolver.tools.CatalogResolver \
  -URIRESOLVER  org.apache.xml.resolver.tools.CatalogResolver

XSLT_FO_STYLESHEET=custom_xsl/fo/docbook.xsl
XSLT_HTML_STYLESHEET=custom_xsl/html/docbook.xsl
XSLT_XHTML_STYLESHEET=custom_xsl/xhtml/docbook.xsl

DOCUMENT=userManual

XML_EXT=xml
HTML_EXT=html
XHTML_EXT=x.html
FO_EXT=fo
PDF_EXT=pdf

#auxiliary targets
#formatting objects
$(DOCUMENT).$(FO_EXT): $(DOCUMENT).$(XML_EXT)
	$(XSLT_PROCESSOR) -xml -in $(DOCUMENT).$(XML_EXT) -out $(DOCUMENT).$(FO_EXT) -xsl $(XSLT_FO_STYLESHEET)

#==============================================================================
#targets for user
html: $(DOCUMENT).$(XML_EXT)
	$(XSLT_PROCESSOR) -xml -in $(DOCUMENT).$(XML_EXT) -out $(DOCUMENT).$(HTML_EXT) -xsl $(XSLT_HTML_STYLESHEET)

xhtml: $(DOCUMENT).$(XML_EXT)
	$(XSLT_PROCESSOR) -xml -in $(DOCUMENT).$(XML_EXT) -out $(DOCUMENT).$(XHTML_EXT) -xsl $(XSLT_XHTML_STYLESHEET)

pdf: $(DOCUMENT).$(FO_EXT)
	$(FO_PROCESSOR) -fo $(DOCUMENT).$(FO_EXT) -pdf $(DOCUMENT).$(PDF_EXT)  $(FO_PROCESSOR_CONFIG)
	$(RM)  $(DOCUMENT).$(FO_EXT)

all: pdf html xhtml

clean:
	$(RM) $(DOCUMENT).$(FO_EXT) $(DOCUMENT).$(PDF_EXT) $(DOCUMENT).$(HTML_EXT) $(DOCUMENT).$(XHTML_EXT)

Je potřeba upravit cesty na začátku souboru.

A teď si v adresáři $WORK vytvořte nějaký minimalistický dokument v DocBooku a uložte ho pod jménem userManual.xml (nebo nějaký jiný, ale pak si upravte i Makefile).

Teď zkuste napsat příkaz

make html

Po kratším chroustání by se měl objevit soubor userManual.html.

Teď co jste vlastně spáchali:

Soubor $WORK/custom_xsl/html/docbook.xsl je vaše přizpůsobená XSLT šablona (custom XSLT template). Na začátku načítá šablonu html-changebars.xsl, tento název se pak najde v souboru catalog.xml a zjistí se, že odpovídá souboru html/changebars.xsl v adresáři c:/Local/docbook-xsl/1.75.2/, což má za následek, že ve výsledku budou po stranách čáry tam, kde jsou některé elementy označené jako změněné. Všimněte si, že je tam zakomentovaný import souboru html-docbook.xsl (dřív jsem ho asi používal a pak jenom zakomentoval), můžete si najít, kterému souboru to ve skutečnosti odpovídá. Dále jsou v souboru nastavení, která ovllivňují chování standardních šablon. O nastavení šablon se dozvíte v [10].

Obdobným způsobem si můžete připravit svoje vlastní šablony pro XHTML a PDF výstup. Příslušné příkazy pak budou make xhtml a make pdf.

Moje soubory vypadají takto: Soubor $WORK/custom_xsl/xhtml/docbook.xsl

<?xml version='1.0'?>
<xsl:stylesheet
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    xmlns:d="http://docbook.org/ns/docbook"
    exclude-result-prefixes="d"
version="1.0">

<!-- <xsl:import href="xhtml-docbook.xsl"/> -->
<xsl:import href="xhtml-changebars.xsl"/>
<xsl:param name="paper.type" select="'A4'"/>
<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="pixels.per.inch" select="150"/>

</xsl:stylesheet>

Soubor $WORK/custom_xsl/fo/docbook.xsl

<?xml version='1.0'?>
<xsl:stylesheet
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

<xsl:import href="fo-docbook.xsl"/>
<xsl:param name="paper.type" select="'A4'"/>
<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="fop1.extensions" select="1"/>

</xsl:stylesheet>

Pokud budete používat PDF výstup, všimněte si v Makefile, že překlad je opravdu dvoufázový, nejdřív se vytvoří soubor s formátovacími objekty a potom teprve PDF.

Tak to by bylo všechno.

Odkazy

• [1] XML mind editor: http://www.xmlmind.com/xmleditor/
• [2] DocBook 5: The Definitive Guide - http://www.docbook.org/tdg5/en/html/docbook.html
• [3] DocBook XSL: The Complete Guide - http://www.sagehill.net/book-description.html
• [4] Xalan-Java http://xml.apache.org/xalan-j/index.html
• [5] Apache XML Commons Resolver http://xerces.apache.org/xml-commons/, přímé stažení nejspíš tady http://www.apache.org/dist/xerces/xml-commons/
• [6] DocBook XSL: The Complete Guide - How to use a catalog file http://www.sagehill.net/docbookxsl/UseCatalog.html
• [7] Apache™ FOP http://xml.apache.org/fop/
• [8] Podpora češtiny pro FOP http://www.kosek.cz/sw/fop/
• [9] Docbook stylesheets http://docbook.sourceforge.net/, balíček najdete na adrese http://sourceforge.net/projects/docbook/
• [10] DocBook XSL: The Complete Guide - Part II. Stylesheet options http://www.sagehill.net/docbookxsl/OptionsPart.html

       

Komentáře

[Miloslav Ponkrác]

A teď řekněte, není tento zápis dostatečným důvodem, proč se DocBook ještě nerozšířil na všechny kouty světa a všechny platformy?

Nemluvě vůbec o tom, že jsou různé verze DocBooku. Počáteční jsou ještě v SGML nikoli v XML.

Pak ještě si zkuste ovlivnit výslednoý vzhled dokumentu.

Já jsme v DocBook psal mnoho let a už mě to tak otrávilo, že to nedělám.

[Jakub Noll]

A v čem píšeš teď?

[GeBu]

To mě taky zajímá.

[Miloslav Ponkrác]

Je málo možností v čem psát texty?

DocBook je IMHO kromě XML ethusiasts asi jedna z nejhorších. Zase tak velké možnosti to nemá. Nástroje pro to nic moc. Nastavení pro různé platformy viz článek, a to to dříve bývalo i horší. Prohlížečů, které by zvládlo kompletní XML-FO moc není. Měnit výsledný vzhled dokumentu je na delší studium, myšleno opravdu delší.

Příliš moc snahy a času za málo muziky.

V DocBooku jsem napsal hodně, ale vždycky jsem měl takový ten pocit ruských továren. Kde je to všechno nějak přištoubované, visí tam dráty různě ve vzduchu, sem tam zpuchřelá izolace, občas šroub zatlučený kladivem, protože se momentálně nenajde šroubovák. Ve výsledku to ruský mužík nakonec uchodí, ale budí to smíšené pocity. Takový mám dojem z celého DocBooku i z celé kolony těch nástrojů.

[Jakub Noll]

Neodpověděl jsi mi. Ptal jsem se, v čem ty osobně tedy píšeš, neptal jsem se, proč se ti nelíbí Docbook. Ptám se proto, že sám hledám optimální nástroj pro práci s dokumentací a třeba bych se inspiroval. Tedy pokud to není tajná informace, v čem Miroslav Ponkrác píše texty.

[frdrx]

Silně jsem se sebou bojoval, abych nebyl tím, kdo pod tento zápisek něco napíše jako první, nedejte bozi dokonce napsal nějaký svůj názor na Docbook. Odolám nadále, ale rád bych si přečetl jakoukoli obhajobu Docbooku.

[Tomáš]

Tak asi proto tu nejsou skoro žádné komentáře, ač téma je jako stvořené pro flame.

[Miloslav Ponkrác]

To já bych si nějakou obhajobu DocBooku také rád přečetl.

[michal]

Existuje nějaký konvertor do docbooku přeba z ODT nebo PDF?

[Tomáš]

Z PDF asi těžko, přeci jenom PDF popisuje vzhled dokumentu a nezabývá se sémantikou. U toho ODT je naděje větší, vnitřně je to taky nějaké XML, takže asi není problém napsat šablony, které to převedou. Problém je v tom, že DocBook má mnohem jemnější dělení elementů podle významu, než základní šablony ODT, takže něco možná převedeš, ale významově ty elementy nebudou sedět.