DocBook XML/SGML verwerking met OpenJade

Copyright en Licentie

Dit document is auteursrechtelijk beschermd 2001 door Saqib Ali. Het is toegestaan dit document onder de voorwaarden van de GNU Free Documentation License, versie 1.1 of enige latere versie gepubliceerd door de Free Software Foundation te kopi�ren, distribueren en of aan te passen; zonder Invariant secties, zonder Front-Cover teksten, en zonder back-cover teksten. Een kopie van de licentie is beschikbaar op http://www.gnu.org/copyleft/fdl.html

Krediet

Alle lof komt toe aan Allah, De heer van de wereld. Alle krediet gaat naar Allah. Alle fouten in dit document liggen aan mijzelf.

Bovendien zou ik graag de volgende mensen willen erkennen voor hun waardevolle bijdragen aan dit document:

1. Greg Ferguson <gferg (at) hoop.timonium.sgi.com> - voor de zeer behulpzame aanwijzingen/suggesties op de docbook mailing list

2. Kristin Thomas <kristint (at) us.ibm.com> - Voor de initi�le voorbeschouwing van dit document.

3. Luc de Louw <[email protected]> - Voor suggesties over HTMLDOC (PDF -> HTML)

4. Lloyd D Budd <[email protected]> - Voor suggesties ter verbetering van de meeste secties in dit document

Wat is DocBook?

DocBook is een document type definitie (DTD). In een DTD wordt de syntax van een document gedefinieerd. DocBook beschrijft de in technische documenten te gebruiken typen structuren en formaten. Het wordt over het algemeen gebruikt vanwege zijn eenvoud en volledigheid.

In een DTD wordt de syntax van een document gedefinieerd. In wezen bestaat het uit een boek met regels waarin de set tags en attributen worden beschreven die zullen worden gebruikt om specifieke soorten inhoud te beschrijven. Dus DocBook is een boek met regels welke wordt gebruikt voor het schrijven van documenten. Elke TAG die wordt gebruikt bij het schrijven van een document, moet zeer specifiek en formeel worden gedefinieerd in de DTD.

Wat is DSSSL?

In een Document Style Semantics and Specification Language (DSSSL) wordt gedefinieerd hoe een Standard Generalized Markup Language (SGML) document in een voor mensen leesbaar formaat wordt omgezet.

Wat hebben we nodig?

De benodigde tools om met OpenJade SGML en XML om te zetten, zijn:

• OpenJade

• Entities

• Norman Walsh's DSSSL

• DocBook DTDs

• LDP DSL

• Norman Walsh's XSL

• LDP XSL

	Noot
	Deze packages zijn vanaf het net vrij te downloaden. In het volgende hoofdstuk wordt uitgelegd hoe deze packages te downloaden.

Veronderstellingen

In dit document wordt verondersteld dat je het volgende reeds op je systeem hebt ge�nstalleerd:

• gzip - beschikbaar vanafhttp://www.gnu.org

• gcc en GNU make - beschikbaar vanaf http://www.gnu.org

Voorbereiding

Maak een directory /tmp/downloads aan. We zullen deze directory gebruiken om de broncode die we gaan downloaden in op te slaan.

OpenJade

OpenJade zal worden gebruikt om DocBook documenten te verwerken. OpenJade kan worden gedownload vanaf: http://openjade.sourceforge.net/.

Op moment van schrijven is OpenJade 1.3.1 beschikbaar. Download het openjade-1.3.x.tar.gz bestand.

DocBook DTD

Alle DocBook DTD's zijn beschikbaar vanaf de website van het Linux Documentatie Project op http://www.tldp.org/authors/index.html#resources

Download DocBook SGML v4.1, DocBook SGML v3.1, en DocBook XML v4.1.2

	Noot
	Download alsjeblieft alle zip-archieven.

ISO-entiteiten

Het Linux Documentatie Project heeft voor het gemak van de gebruikers alle entiteiten in ��n groot tar-bestand verpakt en dit geplaatst op http://www.tldp.org/authors/tools/entities.tar.gz. Met dank aan de TLDP.

DSSSL van Norman Walsh

DSSSL van Norman Walsh kan worden gedownload vanaf de website van het DocBook project op http://sourceforge.net/project/showfiles.php?group_id=21935.

Tijdens dit schrijven was docbook-dsssl-1.76 beschikbaar.

Door de LDP aangepaste DSL-stylesheets

LDP DSL is een aangepaste stylesheet welke wordt gebruikt door het Linux Documentatie Project (TLDP). Het is een uitbreiding op DSSSL van Norman Walsh. Het voegt het een en ander toe, zoals een achtergrond en een inhoudsopgave. Het kan worden gedownload vanaf http://www.tldp.org/authors/tools/ldp.dsl.

Voor ldp.dsl is DSSSL nodig van Norman Walsh

HTMLDOC (optioneel)

HTMLDOC kan worden gebruikt voor het omzetten van HTML in PDF. Als je PDF documenten wilt kunnen produceren, download dan HTMLDOC vanaf http://www.easysw.com/htmldoc/software.php

Norman Walsh's XSL (optioneel)

Dit is niet noodzakelijk. Maar als je met Tomcat+Cocoon DocBook 4.1.2 XML wilt kunnen bekijken, dan zul je de XML stylesheets van Norman Walsh nodig hebben.

De Stylesheets kunnen worden gedownload vanaf http://sourceforge.net/projects/docbook/

Download het package genaamd docbook-xsl

Door de LDP aangepaste XSL (optioneel)

Download tevens de door de LDP aangepaste XML vanaf http://www.tldp.org/authors/tools/ldp-xsl.zip

OpenJade installeren

Dit proces is het makkelijke deel, maar het kost wel de meeste tijd. Houdt in gedachten dat het lang duurt eer OpenJade is gecompileerd. Voltooi de volgende stappen om OpenJade te installeren:

1. Ga naar de directory /tmp/downloads.

   # cd /tmp/downloads

2. Decomprimeer het bestand.

   # gzip -d openjade-1.3.x.tar.gz

3. Pak het archief uit.

   # tar -xvf openjade-1.3.x.tar

4. Ga naar de directory openjade-1.3

   # cd openjade-1.3.x

5. Start de opdracht ./configure.

   # ./configure --prefix=/usr/local/dbtools/openjade

6. Start de opdracht make.

   # make

7. Voer de opdracht make install uit. Na deze stap zullen de openjade binary's worden ge�nstalleerd onder /usr/local/dbtools/openjade.

   # make install

8. Kopieer de directory dsssl vanuit /tmp/downloads/openjade-1.3.x naar /usr/local/dbtools/openjade

   # cp -dpR dsssl /usr/local/dbtools/openjade/

DSSSL van Norman Walsh installeren

In deze stap zullen we DSSSL van Norman Walsh op de juiste lokatie gaan installeren. De DSSSL hoeft niet te worden gecompileerd.

1. Ga naar de directory /tmp/downloads

   # cd /tmp/downloads

2. Decomprimeer het bestand.

   # gzip -d docbook-dsssl-1.76.tar.gz

3. Pak het archief uit.

   # tar -xvf docbook-dsssl-1.76.tar

4. Verplaats het bestand naar /usr/local/dbtools/docbook-dsssl.

   # mv docbook-dsssl-1.76 /usr/local/dbtools/docbook-dsssl

DocBook DTD's installeren

In deze sectie zullen we de DocBook DTD's installeren.

1. Ga naar de directory /usr/local/dbtools.

   # cd /usr/local/dbtools

2. Maak nieuwe directory's genaamd dtd3.1 dtd4.1 dtd4.1.2 aan.

   # mkdir dtd3.1 # mkdir dtd4.1 # mkdir dtd4.1.2

3. Ga naar de directory dtd3.1.

   # cd dtd3.1

4. Decomprimeer het bestand DocBook SGML v3.1 in deze directory.

   # unzip /tmp/downloads/docbk31.zip

5. Ga naar de directory dtd4.1.

   # cd ../dtd4.1

6. Decomprimeer het bestand DocBook SGML v4.1 in deze directory.

   # unzip /tmp/downloads/docbk41.zip

7. Ga naar de directory dtd4.1.2.

   # cd ../dtd4.1.2

8. Decomprimeer het bestand DocBook XML v4.1.2 in deze directory.

   # unzip /tmp/downloads/docbk412.zip

ISO-entiteiten installeren

In deze sectie zullen we de ISO-entiteiten installeren die we downloadde vanaf de LDP-website.

Als eerste installeren we de ISO-entiteiten voor de 3.1 SGML DTD

1. Ga naar de directory /usr/local/dbtools/dtd3.1.

   # cd /usr/local/dbtools/dtd3.1

2. Kopieer /tmp/download/entities.tar.gz naar deze directory.

   # cp /tmp/download/entities.tar.gz .

3. Decomprimeer het bestand.

   # gzip -d entities.tar.gz

4. Pak het archief uit.

   # tar -xvf entities.tar

Vervolgens installeren we de ISO-entiteiten voor de 4.1 SGML DTD

1. Ga naar de directory /usr/local/dbtools/dtd4.1.

   # cd /usr/local/dbtools/dtd4.1

2. Kopieer /tmp/download/entities.tar.gz naar deze directory.

   # cp /tmp/download/entities.tar.gz .

3. Decomprimeer het bestand.

   # gzip -d entities.tar.gz

4. Pak het archief uit.

   # tar -xvf entities.tar

Installeren van de LDP DSL

Als laatste installeren we ldp.dsl.

1. Ga naar de directory /tmp/download.

   # cd /tmp/download

2. Kopieer het bestand ldp.dsl naar de directory /usr/local/dbtools/docbook-dsssl/print/ldp.dsl.

   # cp ldp.dsl /usr/local/dbtools/docbook-dsssl/print/ldp.dsl

3. >Kopieer het bestand ldp.dsl naar de directory /usr/local/dbtools/docbook-dsssl/html/ldp.dsl.

   # cp ldp.dsl /usr/local/dbtools/docbook-dsssl/html/ldp.dsl

HTMLDOC installeren

Deze stap is optioneel. Ze is alleen nodig als je PDF documenten wilt produceren.

Keer terug naar de directory downloads

	# Ga naar de directory /tmp/download

Pak de broncode voor HTMLDOC uit

	# gzip -d htmldoc-1.8.xx-source.tar.gz 
	# tar -xvf htmldoc-1.8.xx-source.tar 
	# cd htmldoc-1.8.xx-1

Start configure om de installatielokatie te configureren

	# ./configure --prefix=/usr/local/dbtools/htmldoc
	# make

Tijdens dit schrijven was HTMLDOC versie 1.8.20-1 beschikbaar. Deze versie had een klein probleem in de fonts Makefile. Het geeft een foutmelding tijdens het installeren van de fonts, omdat de juiste fonts niet beschikbaar waren op het systeem.

Tijdens de uitvoering van make install krijg je de volgende foutmelding:

	# make install
Making all in htmldoc...
Making all in doc...
Installing in fonts...
Installing font files in /usr/local/dbtools/htmldoc/share/htmldoc/fonts...
/bin/cp: cannot stat `ZapfChancery.afm': No such file or directory
/bin/cp: cannot stat `ZapfChancery.pfa': No such file or directory
/bin/cp: cannot stat `ZapfDingbats.afm': No such file or directory
/bin/cp: cannot stat `ZapfDingbats.pfa': No such file or directory
make[1]: *** [install] Error 1

Ter correctie van dit installatieprobleem bewerk je fonts/Makefile en plaats je een commentaarteken voor de regels met verwijzingen naar de ZapfChancery en ZapfDingbats fonts

Voer dan de volgende installatie uit:

# make install Making all in htmldoc... Making all in doc... Installing in fonts... Installing font files in /usr/local/dbtools/htmldoc/share/htmldoc/fonts... Installing in data... Installing in doc... Installing in htmldoc...

SGML verwerken

Je kunt een SGML DocBook 3.1 voorbeeldbestand downloaden vanaf http://docbook.sc-icc.org/DocBook-OpenJade-SGML-XML-HOWTO.sgml

# export SGML_CATALOG_FILES=/usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd3.1/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog

# /usr/local/dbtools/openjade/bin/openjade -t sgml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html DocBook-OpenJade-SGML-XML-HOWTO.sgml 

# /usr/local/dbtools/openjade/bin/openjade -V nochunks -t sgml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html DocBook-OpenJade-SGML-XML-HOWTO.sgml 

# /usr/local/dbtools/openjade/bin/openjade -t rtf -d /usr/local/dbtools/docbook-dsssl/print/ldp.dsl#print DocBook-OpenJade-SGML-XML-HOWTO.sgml 

XML verwerken

Je kunt een voorbeeldbestand in DocBook 4.1.2 XML downloaden vanaf http://docbook.sc-icc.org/DocBook-OpenJade-SGML-XML-HOWTO.xml

# export SGML_CATALOG_FILES=/usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd4.1.2/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog

# /usr/local/dbtools/openjade/bin/openjade -t xml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html /usr/local/dbtools/docbook-dsssl/dtds/decls/xml.dcl DocBook-OpenJade-SGML-XML-HOWTO.xml

# /usr/local/dbtools/openjade/bin/openjade -t rtf -d /usr/local/dbtools/docbook-dsssl/print/ldp.dsl#print /usr/local/dbtools/docbook-dsssl/dtds/decls/xml.dcl DocBook-OpenJade-SGML-XML-HOWTO.xml

HTML naar PDF (optioneel)

Om HTML naar PDF om te zetten, moeten we gebruik maken van HTMLDOC. Zet het SGML-bestand als eerste om in een geheel HTML-uitvoerbestand:

# /usr/local/dbtools/openjade/bin/openjade -V nochunks -t sgml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html DocBook-OpenJade-SGML-XML-HOWTO.sgml 

Voer dan HTMLDOC uit om PDF te produceren:

# /usr/local/dbtools/htmldoc/bin/htmldoc -f outfile.pdf input.html

Tomcat + Cocoon

Tomcat is de Java Servlet Container. Kijk voor meer informatie op http://jakarta.apache.org/tomcat/index.html

Apache Cocoon is een XML publishing framework. Kijk voor meer informatie op http://xml.apache.org/cocoon/index.html

In deze HOWTO zal niet worden ingegaan op details nodig voor het instellen van Cocoon+Tomcat, aangezien dit reeds wordt uitgelegd op @ http://xml.apache.org/cocoon/installing/index.html. In instellen van Tomcat+Cocoon is niet moeilijk en het zou in minder dan 5 minuten moeten kunnen.

Zodra je Cocoon + Tomcat werkend hebt, volg je de volgende secties om de inhoud van DocBook 4.1.2 XML in een browser te kunnen bekijken.

XSL van Norman Walsh installeren

In deze stap zullen we XSL van Norman Walsh installeren onder /usr/local/dbtools/.

Ga naar de directory /tmp/downloadsen pak het archiefbestand docbook-xsl uit.

# cd /tmp/downloads/

# gzip -d docbook-xsl-1.53.0.tar.gz

# tar -xvf docbook-xsl-1.53.0.tar

Verplaats voor de installatie van docbook-xsl de bestanden naar de directory /usr/local/dbtools

# mv docbook-xsl-1.53.0 /usr/local/dbtool/docbook-xsl

Installeer dan de LDP XSL

LDP XSL installeren

Decomprimeer het bestand ldp-xs.zip en kopieer alle bestanden naar de directory /usr/local/dbtools/docbook-xsl/html.

# cd /tmp/downloads

# unzip ldp-xs.zip

# mv ldp-html*.xsl /usr/local/dbtools/docbook-xsl/html

Bewerk vervolgens het bestand /usr/local/dbtools/docbook-xsl/html/ldp-html.xsl om het pad voor het importbestand in te stellen.

# vi /usr/local/dbtools/docbook-xsl/html/ldp-html.xsl

wijzig:

import href="/usr/share/sgml/docbook/docbook-xsl-1.44/html/docbook.xsl"

in:

import href="/usr/local/dbtools/docbook-xsl/html/docbook.xsl"

Instellen van sitemap.xmap

$COCOON_HOME verwijst naar de Cocoon Web Application Directory. Dit is de directory /usr/local/jakarta-tomcat-4.1.9/webapps/cocoon/

Maak een directory met de naam docbook aan onder $COCOON_HOME/mount. Hier zullen we alle DocBook XML 4.1.2 inhoud gaan plaatsen.

# mkdir $COCOON_HOME/mount/docbook

Maak een bestand sitemap.xmap aan in de directory $COCOON_HOME/mount/docbook met de volgende inhoud:

# cd $COCOON_HOME/mount/docbook

# vi sitemap.xmap

<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

    <!-- gebruik de standaardcomponenten -->
    <map:components>
        <map:generators default="file"/>
        <map:transformers default="xslt"/>
        <map:readers default="resource"/>
        <map:serializers default="html"/>
        <map:selectors default="browser"/>
        <map:matchers default="wildcard"/>
        <map:transformers default="xslt"/>
    </map:components>
      
    <map:pipelines>
        <map:pipeline>

   <map:match pattern="">
    <map:generate src="samples.xml"/>
    <map:transform src="/usr/local/jakarta-tomcat-4.1.9/webapps/cocoon/mount/editor/stylesheets/simple-page2html.xsl"/>
    <map:serialize/>
   </map:match>

   <!-- reageer op *.html verzoeken met
                 onze docs verwerkt door .xsl -->
            <map:match pattern="*.html">
                <map:generate src="{1}.xml"/>
                <map:transform src="/usr/local/dbtools/docbook-xsl/html/ldp-html.xsl"/>
                <map:serialize type="html"/>
            </map:match>
            
	    <!-- later, reageer op *.pdf verzoeken met
                 onze docs verwerkt door doc2pdf.xsl -->
            <map:match pattern="*.pdf">
                <map:generate src="{1}.xml"/>
                <map:transform src="/usr/local/dbtools/docbook-xsl/fo/docbook.xsl"/>
                <map:serialize type="fo2pdf"/>
            </map:match>

            <map:match pattern="*.xml">
                <map:generate src="{1}.xml"/>
                <map:serialize type="xml"/>
            </map:match>


        </map:pipeline>
    </map:pipelines>
</map:sitemap>

Inhoud van een DocBook 4.1.2 XML bestand bekijken vanuit een webbrowser

Plaats een DocBook 4.1.2 XML-bestand in $COCOON_HOME/mount/docbook/

Een voorbeeldbestand is beschikbaar vanaf http://docbook.sc-icc.org/sample.xml

Nu kun je het document benaderen vanuit een browser @ http://localhost:8080/cocoon/mount/sample.html (HTML) of http://localhost:8080/cocoon/mount/sample.pdf (PDF)

Nieuwsgroepen

Een aantal van belang zijnde nieuwsgroepen:

1. comp.text.sgml (makkelijk toegankelijk vanaf http://www.deja.com)

2. comp.text.xml (makkelijk toegankelijk vanaf http://www.deja.com)

3. htmldoc.general (server - nttp://news.easysw.com)

Mailinglijsten

Hier zijn een aantal relevante mailinglijsten

1. DocBook mailing list @ OASIS. Ga naar http://www.oasis-open.org/committees/docbook/mailinglist/index.shtml voor meer info.

2. DocBook mailing list @ TLDP. Ga naar http://www.tldp.org/mailinfo.html voor meer info.

3. xml-doc @ Yahoo Groups. Ga naar http://groups.yahoo.com/group/xml-doc/ voor meer info.

IRC

1. DocBook IRC Channel. #docbook op irc://irc.openprojects.net

Websites

1. http://www.oasis-open.org/ OASIS beheert diverse DocBook DTD's

2. http://docbook.org/wiki/moin.cgi/De DocBook Wiki

3. http://www.docbook.org/tdg/en/Online versie van DocBook: The Definitive Guide

4. http://www-106.ibm.com/developerworks/library/l-docbk.htmlA gentle guide to DocBook (zeer goede introductie).

5. http://www.tldp.org/LDP/LDP-Author-Guide/index.htmlHet Linux Documentatie Project (TLDP) Author Guide

6. http://www.tldp.org/authors/index.html#resourcesDocBook bronnen geleverd door de TLDP

Commerci�le tools

1. DocPro van Command Prompt, INC. http://www.commandprompt.com/entry.lxp?lxpe=2

2. YAWC Pro van XML Workshop LTD. http://www.yawcpro.com/. Kan worden gebruikt om MS Word documenten om te zetten in Simple DocBook XML.

3. Logictran RTF Converter. http://www.logictran.com/. Word/RTF naar HTML/XML

4. MajiX - Word naar XML converter. http://tetrasys.dhs.org/

5. XMETAL van SoftQuad http://www.softquad.com/