Kapitel 3. DocBook i XML : Ett konkret exempel

Autogenerering av databasbeskrivning

Här skall vi prova att sätta DocBook i arbete, och samtidigt prova köra DockBook i XML istället för SGML. Vi tänker oss att vi jobbar med en relativt stor databas, som dessutom genomgår förändringar ibland. Vi vill kunna ta ut, automatiskt, ett dokument som beskriver tabellerna i databasen. Dokumentformaten skall vara pdf, en ensam HTML fil och en HTML struktur, uppdelad per tabell. Dessutom vill vi gärna kunna byta plattform, om det skulle behövas.

Ett externt verktyg kommer att gå igenom databasen, i detta fall en PostgreSQL 7.3.1, och skapa en fil med XML-syntax för att beskriva databasen. Vi använder oss av tcl för att gå igenom databasen, pgtcl som har stöd för PostgreSQl inbyggt. Utdata från pgtcl passar dock inte riktig in i DocBooks struktur, så vi måste stuva om datat. Det gör vi med XSL. Vi beskriver hur transformeringen skall gå till i ett XSL-dokument. Vi har dessutom ett ramdokument för att beskriva metadata om dokumentet, och vi gör 'include' på den XSL-processade databasbeskrivningen. Vi är dessutom lata, och stoppar allt i en Makefile.

Databasen kan givetvis bytas mot någon annan, men då måste XSL-dokumentet anpassas därefter, likaså det externa verktyget, dvs tcl-skriptet.

3.1. Verktyg

För att klara detta kommer vi att använda oss av:

För att bringa ordning i detta kommer vi att hantera dessa filer:

3.1.1. Installation av verktyg

Här går vi bara genom de docbookrelaterade verktygen, databas och make utgår jag från att de redan finns.

3.1.1.1. Java

Java kan hämtas på Suns javasidor. Detta exempel har använt Java SDK 1.4.1 rpm-versionen, men de flesta nyare versioner duger. Rpm-versionen installerar det mesta, men jag brukar lägga till följande i ~/.basrc:


export JAVA_HOME=/usr/java/j2sdk1.4.1_01/jre
       
Dessutom brukar jag skapa en symbolisk länk till java

ln -s $JAVA_HOME/bin/java /usr/bin/java
       


3.1.1.2. FOP

Fop kan hämtas på Apaches XML sidor. Detta exempel har använt Fop 0.20.5. Tara upp Fop, och lägg det t.ex. under /usr/java/fop. Det är bra att lägga till följande i ~/.basrc:


export FOP_HOME=/usr/java/fop/fop-0.20.5rc3a
         


För att hantera bilder behövs ett bildbibliotek. Hämta Jimi hos Sun och packa upp det med tar xvzf jimi1_0.tar.Z. Leta upp JimiProClasses.zip och kopiera det till $FOP_HOME/lib/jim-1.0.jar. Det skall alltså till ett namnbyte på filen.

3.1.1.3. Saxon

Saxon kan hämtas hos SourceForge. Detta exempel har använt Saxon 6.5.2, eftersom det är den rekomenderade versionen, även om det finns nyare. Packa upp Saxon, och lägg det t.ex. under /usr/java/saxon.

3.1.1.4. DocBook Stylesheets

Stylesheets kan hämtas hos SourceForge. Det är 'Docbook-xsl' som skall hämtas, jag kör version 1.61.2. Mandrake 9.1 har 1.60.1 installerat och det duger bra. Finns som /usr/share/sgml/docbook/xsl-stylesheets-1.60.1. Det är ganska vettigt att skapa katalogen /usr/share/sgml/docbook/xsl-stylesheets som en symbolisk länk till den docbook-version som anväds i systemet. Då blir det lätt att byta mellan versioner, om man vill. Mandrake 9.1 har satt upp det så.

Dessutom behövs en DTD, Mandrake har xml-dtd-4.1.2, som finns som /usr/share/sgml/docbook/xml-dtd-4.1.2 men vill man den nyaste är det 4.2, som finns hos Oasis.