Saqib Ali

saqib@seagate.com

Vertaald door: Ellen Bokhorst

bokkie@nl.linux.org

v2.0 10-09-2002 sa De sectie toegevoegd over het met behulp van Tomcat+Cocoon bekijken van de inhoud van DocBook XML 4.1.2 v1.5 2002-08-11 sa De XML-sectie toegevoegd en het XML-voorbeeldbestand. v1.4 2002-08-08 sa Veel waardevolle aanpassingen/correcties aanbevolen door Lloyd D Budd. Bedankt Lloyd :) v1.3 2002-08-02 sa De sectie "Extra bronnen" toegevoegd. v1.2 2002-07-23 sa De sectie toegevoegd over het omzetten van HTML naar PDF met HTMLDOC. Met dank aan Luc De Louw voor de suggestie. v1.1 19-07-2002 KET Grammaticale fouten gecorrigeerd, processen genummerd v1.0 29-06-2002 sa Initiële publieke uitgave. In deze HOWTO wordt uitgelegd hoe OpenJade in te stellen voor de verwerking van SGML/XML DocBook documenten. Een aantal acroniemen: SGML - Standard Generalized Markup Language XML - Extensible Markup Language RTF - Rich Text Format HTML - HyperText Markup Language PDF - Portable Document Format Het doel van dit document is het opzetten van OpenJade om DocBook 3.2 en 4.2 Standaard Generalized Markup Language (SGML) en Extensible Markup Language (XML) documenten om te zetten in HyperText Markup Language (HTML), Rich Text Format (RTF) en Portable Document Format (PDF) documenten. 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 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: Greg Ferguson gferg (at) hoop.timonium.sgi.com - voor de zeer behulpzame aanwijzingen/suggesties op de docbook mailing list Kristin Thomas kristint (at) us.ibm.com - Voor de initiële voorbeschouwing van dit document. Luc de Louw luc@delouw.ch - Voor suggesties over HTMLDOC (PDF -> HTML) Lloyd D Budd ldp@foolswisdom.org - Voor suggesties ter verbetering van de meeste secties in dit document 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. 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. 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 Deze packages zijn vanaf het net vrij te downloaden. In het volgende hoofdstuk wordt uitgelegd hoe deze packages te downloaden. 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 Je hoeft slechts één package (OpenJade) te downloaden en compileren. In deze HOWTO wordt het compilatieproces uitgelegd, maar er wordt verwacht dat je reeds ervaring hebt met een installatie vanuit de broncode. De meeste packages die we nodig hebben, zijn de vinden op de website van Het Linux Documentatie Project (TLDP) Maak een directory /tmp/downloads aan. We zullen deze directory gebruiken om de broncode die we gaan downloaden in op te slaan. 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. 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 Download alsjeblieft alle zip-archieven. 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 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. 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 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 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 Download tevens de door de LDP aangepaste XML vanaf http://www.tldp.org/authors/tools/ldp-xsl.zip In deze sectie zullen we alle tools in de juiste directory's installeren. Alle tools komen terecht in de directory /usr/local/dbtools/. Maak deze directory met de volgende opdracht aan: mkdir /usr/local/dbtools 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: Ga naar de directory /tmp/downloads. # cd /tmp/downloads Decomprimeer het bestand. # gzip -d openjade-1.3.x.tar.gz Pak het archief uit. # tar -xvf openjade-1.3.x.tar Ga naar de directory openjade-1.3 # cd openjade-1.3.x Start de opdracht ./configure. # ./configure --prefix=/usr/local/dbtools/openjade Start de opdracht make. # make Voer de opdracht make install uit. Na deze stap zullen de openjade binary's worden geïnstalleerd onder /usr/local/dbtools/openjade. # make install Kopieer de directory dsssl vanuit /tmp/downloads/openjade-1.3.x naar /usr/local/dbtools/openjade # cp -dpR dsssl /usr/local/dbtools/openjade/ In deze stap zullen we DSSSL van Norman Walsh op de juiste lokatie gaan installeren. De DSSSL hoeft niet te worden gecompileerd. Ga naar de directory /tmp/downloads # cd /tmp/downloads Decomprimeer het bestand. # gzip -d docbook-dsssl-1.76.tar.gz Pak het archief uit. # tar -xvf docbook-dsssl-1.76.tar Verplaats het bestand naar /usr/local/dbtools/docbook-dsssl. # mv docbook-dsssl-1.76 /usr/local/dbtools/docbook-dsssl In deze sectie zullen we de DocBook DTD's installeren. Ga naar de directory /usr/local/dbtools. # cd /usr/local/dbtools Maak nieuwe directory's genaamd dtd3.1 dtd4.1 dtd4.1.2 aan. # mkdir dtd3.1 # mkdir dtd4.1 # mkdir dtd4.1.2 Ga naar de directory dtd3.1. # cd dtd3.1 Decomprimeer het bestand DocBook SGML v3.1 in deze directory. # unzip /tmp/downloads/docbk31.zip Ga naar de directory dtd4.1. # cd ../dtd4.1 Decomprimeer het bestand DocBook SGML v4.1 in deze directory. # unzip /tmp/downloads/docbk41.zip Ga naar de directory dtd4.1.2. # cd ../dtd4.1.2 Decomprimeer het bestand DocBook XML v4.1.2 in deze directory. # unzip /tmp/downloads/docbk412.zip 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 Ga naar de directory /usr/local/dbtools/dtd3.1. # cd /usr/local/dbtools/dtd3.1 Kopieer /tmp/download/entities.tar.gz naar deze directory. # cp /tmp/download/entities.tar.gz . Decomprimeer het bestand. # gzip -d entities.tar.gz Pak het archief uit. # tar -xvf entities.tar Vervolgens installeren we de ISO-entiteiten voor de 4.1 SGML DTD Ga naar de directory /usr/local/dbtools/dtd4.1. # cd /usr/local/dbtools/dtd4.1 Kopieer /tmp/download/entities.tar.gz naar deze directory. # cp /tmp/download/entities.tar.gz . Decomprimeer het bestand. # gzip -d entities.tar.gz Pak het archief uit. # tar -xvf entities.tar Als laatste installeren we ldp.dsl. Ga naar de directory /tmp/download. # cd /tmp/download 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 >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 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... In deze sectie zullen we OpenJade gebruiken om SGML/XML documenten om te zetten in HTML, RTF en PDF. Je kunt een SGML DocBook 3.1 voorbeeldbestand downloaden vanaf http://docbook.sc-icc.org/DocBook-OpenJade-SGML-XML-HOWTO.sgml De omgevingsvariabele SGML_CATALOG_FILES moet zo worden ingesteld dat het verwijst naar de van toepassing zijnde catalog bestanden. Gebruik de volgende opdracht om de variabele in te stellen: # export SGML_CATALOG_FILES=/usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd3.1/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog Gebruik de volgende opdracht voor de conversie van SGML naar HTML: # /usr/local/dbtools/openjade/bin/openjade -t sgml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html DocBook-OpenJade-SGML-XML-HOWTO.sgml Voor het creëren van één geheel HTML-bestand: # /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 Gebruik de volgende opdracht om een SGML-bestand naar het RTF-formaat om te zetten: # /usr/local/dbtools/openjade/bin/openjade -t rtf -d /usr/local/dbtools/docbook-dsssl/print/ldp.dsl#print DocBook-OpenJade-SGML-XML-HOWTO.sgml Je kunt een voorbeeldbestand in DocBook 4.1.2 XML downloaden vanaf http://docbook.sc-icc.org/DocBook-OpenJade-SGML-XML-HOWTO.xml De variabele SGML_CATALOG_FILES moet zodanig worden ingesteld, dat het verwijst naar de juiste catalog bestanden. Gebruik de volgende opdracht om de variabele in te stellen: # export SGML_CATALOG_FILES=/usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd4.1.2/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog Gebruik de volgende opdracht voor de omzetting van XML naar HTML # /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 Gebruik de volgende opdracht voor de omzetting van XML naar HTML: # /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 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 Er zijn 3 manieren om DocBOok 4.1.2 XML vanuit een webserver te bekijken: Voorverwerkt met OpenJade, XSLT Via scripts - PHP, Perl, Python Applicatieserver - Cocoon Het gebruik van een applicatieserver, zoals Cocoon is de beste optie. In deze sectie zullen we zien hoe we DocBook 4.1.2 XML bestanden met Cocoon+Tomcat kunnen tonen. 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. 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 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" $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> 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) In deze sectie staan een aantal verwijzingen naar gerelateerde bronnen op het internet. Als je aanbevelingen hebt voor extra bronnen in deze sectie, stuur me dan alsjeblieft een mail @ saqib@seagate.com. Bedankt. Een aantal van belang zijnde nieuwsgroepen: comp.text.sgml (makkelijk toegankelijk vanaf http://www.deja.com) comp.text.xml (makkelijk toegankelijk vanaf http://www.deja.com) htmldoc.general (server - nttp://news.easysw.com) Hier zijn een aantal relevante mailinglijsten DocBook mailing list @ OASIS. Ga naar http://www.oasis-open.org/committees/docbook/mailinglist/index.shtml voor meer info. DocBook mailing list @ TLDP. Ga naar http://www.tldp.org/mailinfo.html voor meer info. xml-doc @ Yahoo Groups. Ga naar http://groups.yahoo.com/group/xml-doc/ voor meer info. DocBook IRC Channel. #docbook op irc://irc.openprojects.net http://www.oasis-open.org/ OASIS beheert diverse DocBook DTD's http://docbook.org/wiki/moin.cgi/De DocBook Wiki http://www.docbook.org/tdg/en/Online versie van DocBook: The Definitive Guide http://www-106.ibm.com/developerworks/library/l-docbk.htmlA gentle guide to DocBook (zeer goede introductie). http://www.tldp.org/LDP/LDP-Author-Guide/index.htmlHet Linux Documentatie Project (TLDP) Author Guide http://www.tldp.org/authors/index.html#resourcesDocBook bronnen geleverd door de TLDP DocPro van Command Prompt, INC. http://www.commandprompt.com/entry.lxp?lxpe=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. Logictran RTF Converter. http://www.logictran.com/. Word/RTF naar HTML/XML MajiX - Word naar XML converter. http://tetrasys.dhs.org/ XMETAL van SoftQuad http://www.softquad.com/