PDF documenten maken met DocBook

ArticleCategory: [Choose a category for your article]

Applications

AuthorImage:[Here we need a little image form you]

TranslationInfo:[Author and translation history]

AboutTheAuthor:[A small biography about the author]

Werd lid van het Nederlandse LF team in 1999 en werd tweede redacteur eerder dit jaar. Is informatische chemie student op de Universiteit van Nijmegen. Speelt basketbal en houdt van rondreizen.

Abstract:[Here you write a little summary]

Dit artikel beschrijft hoe je DocBook kunt gebruiken voor het maken van PDF documenten. Programma's die nodig zijn voor het schrijven van DocBook artikels en voor het omzetten naar PDF documenten worden ook behandeld. Aangezien dit artikel de tools enkel vernoemt en niet vertelt hoe je ze moet installeren, is het bedoeld voor ervaren Linux gebruikers.

Het eerste gedeelte van dit artikel zal gaan over het formaat van DocBook documenten. Nadat DocBook is geïntroduceerd, zal ik proberen uit te leggen welke programma's nodig zijn voor het omzetten van deze DocBook bestanden naar PDF-formaat (te lezen met Adobe's Acrobat.)

ArticleIllustration:[This is the title picture for your article]

ArticleBody:[The article body]

Wat is DocBook?

DocBook [1] is een SGML applicatie ontwikkeld voor de opmaak van documenten, net zoals HTML de opmaak voor web documenten verzorgt. In tegenstelling tot HTML, biedt DocBook geen directe informatie over de layout van het document. Dat is de reden waarom DocBook documenten eerst moeten worden omgezet naar een ander formaat voordat ze kunnen worden gelezen. Omzetting naar andere formaten wordt gedaan door tools die het DocBook document van een zekere stylesheet voorzien.

Figuur 1: Omzetting van DocBook naar PDF met een stylesheet

Later in dit artikel zal worden uitgelegd welke stylesheet je moet gebruiken voor deze omzetting en welke tool de stylesheet toepast op het DocBook document. Eerst gaan we zien hoe documenten zijn samengesteld.

Schrijven van een artikel

DocBook is in staat de opmaak te verzorgen van twee soorten documenten: boeken en artikels. Aangezien ze in principe hetzelfde zijn, zal ik de opmaak van een artikel als voorbeeld nemen. Voordat ik een voorbeeld geef van een eenvoudig document, eerst wat basis principes over DocBook

DocBook is in principe een SGML toepassing, net als HTML. Maar er is ook een XML versie van DocBook. De XML versie is wat strikter, maar makkelijker te lezen en daardoor makkelijker te leren. Omdat XML op zich ook een SGML toepassing is, kunnen alle SGML tools nog steeds worden gebruikt. De belangrijke verschillen tussen SGML en de XML variant zijn het volgende (dit geldt voor elke XML toepassing):

XML elementen moeten altijd gesloten zijn
XML elementen moeten zorgvuldig genest (genesteld) worden

Dit betekent dat je   niet kunt gebruiken zoals in HTML, maar je zou   moeten gebruiken. (Alhoewel   ook goed is, het element wordt hierbij meteen gesloten.) Het tweede punt betekent dat je niet <A HREF="een_url">klik hier</A> kan schrijven, maar de elementen zorgvuldig moet nesten: <A HREF="een_url">klik hier</A>.

Nu we deze belangrijke punten hebben besproken, kunnen we beginnen met het schrijven van artikels in DocBook.

    <?xml version="1.0"?>
    <article>
      <title>Het schrijven van DocBook artikels</title>
      <artheader>
        <abstract>
          Dit artikel beschrijft hoe je DocBook kunt
          gebruiken voor het maken van PDF documenten.
        </abstract>
        <author>
          <firstname>Egon</firstname>
          <surname>Willighagen</surname>
        </author>
        <date></date>
      </artheader>
    </article>

Niet zo moeilijk zou ik zeggen. We hebben een artikel gemaakt met een titel, een korte uitleg, een datum wanneer het was geschreven en de naam van de auteur.

De volgende stap is het toevoegen van secties aan het artikel door het gebruik maken van sectie elementen:

    <?xml version="1.0"?>
    <article>
      <title>Het schrijven van DocBook artikels</title>
      <artheader>
        ... de kop van het artikel ...
      </artheader>
  
      <section>
        <title>Introductie</title>
      </section>

      ... andere secties ...

    </article>

We hebben nu een Introductie sectie aan het artikel toegevoed. Extra sectie-elementen kunnen worden gebruikt voor bijvoorbeeld Resultaten, Conclusie of welke andere sectie dan ook.

Toevoegen van tekst en andere informatie

Alle tekst staat tussen para elementen, vergelijkbaar met HTML's p elementen:

    <section>
      <title>Introductie</title>
      <para>
        DocBook is een SGML applicatie ontwikkeld
        voor de opmaak van documenten, precies zoals
        HTML de opmaak voor web documenten verzorgt.
      </para>
    </section>

Maar naast tekst zijn er ook veel andere elementen beschikbaar. In de rest van deze sectie is te zien hoe informatie zoals voorbeelden, lijsten, plaatjes en anderen kunnen worden ingevoegd in het artikel.

Voorbeelden toevoegen

Voorbeelden kunnen worden toegevoed met het gebruik van het example element, zoals in het volgende voorbeeld waar een voorbeeld-programma wordt weergegeven:

<example>
  <title>
    Perl programma dat een XML document in een HTML document vertaalt.
  </title>
  <programlisting>
    #!/usr/bin/perl -w
    use diagnostics;
    use strict;
    use XML::XSLT;

    my $XSLTparser = XML::XSLT->new();
    $XSLTparser->open_project ("file.xml", "stylesheet.xsl", "FILE", "FILE");
    $XSLTparser->process_project;
    $XSLTparser->print_result();
  </programlisting>
</example>

Maar voorbeelden kunnen ook tekst, plaatjes en andere informatie bevatten.

Lijsten toevoegen

Net als in HTML kan DocBook ook lijsten bevatten. Lijsten worden gedefineerd door het itemizedlist element dat een of meer listitem elementen kan bevatten:

<itemizedlist>
  <listitem>
    <para>een item</para>
  </listitem>
  <listitem>
    <para>nog een item</para>
  </listitem>
  <listitem>
    <para>en nog een item</para>
  </listitem>
</itemizedlist>

Merk op dat hier ook de tekst tussen het para element staat. Tekst moet altijd binnenin dit element komen te staan!

Lijsten kunnen ook worden gesorteerd. In dat geval kun je het orderedlist element gebruiken in plaats van het itemizedlist element. Door het invoegen van een numeration parameter (<orderedlist numeration="Arabic">) kun je het type nummer instellen

Figuren invoegen

Afbeeldingen kunnen in het artikel worden gezet:

<mediaobject>
<imageobject>
<imagedata fileref="een_afbeelding.gif" format="gif"/>
</imageobject>
<textobject>
  <para>
    Als je niet gebruik maakte van <productname>Lynx</productname>
    zou je nu een afbeelding zien.
  </para>
</textobject>
</mediaobject>

Je kunt zien dat naast het plaatje ook een tekst is gegeven. Ik had ook nog een filmpje kunnen invoegen. De stylesheet bewerker die zorgt dat DocBook documenten worden omgezet in PDF kan dan het beste type medium kiezen, wat voor de uitvoer waarschijnlijk het beste van toepassing is. De stylesheet bewerker maakt dus zelf een keuze uit wat er voorhanden is.

Merk op dat het woord "Lynx" een speciale markering heeft. Dit is een specifieke eigenschap voor de DocBook taal waarbij layout gescheiden is van informatie. Het artikel zegt gewoon dat Lynx een programma is waarvan Lynx de naam is. De stylesheet beschrijft later dat het productnaam in een speciaal lettertype moet worden getoond, bijvoorbeeld, italic. In de volgende sectie zien we hoe we andere woorden een opmaak kunnen geven.

Woord opmaak

Zoals in het voorbeeld figuurtje hierboven was te zien, kunnen de woorden zelf een opmaak hebben. In de tabel hieronder zijn een paar opmaak elementen voor woorden gegeven:

Element	Beschrijving
`abbrev`	Een afkorting, vooral wanneer gevolgd door een punt. Voorbeeld: `<para><abbrev>`bijv.`</abbrev>` bedoeld als voorbeeld.`</para>`
`acronym`	Een acronym Voorbeeld: `<para><acronym>`DSM`</acronym>` (chemisch bedrijf) betekent "De StaatsMijnen"`</para>`
`email`	Iemands emailadres Voorbeeld: `<para>`Mijn email is `<email>`egon.w@linuxfocus.org`</email></para>`
`keyword`	Een sleutelwoord van het artikel Voorbeeld: `<para>`Naar mijn bescheiden mening is `<keyword>`scheikunde`</keyword>` erg belangrijk.`</para>`

En zijn nog vele andere elementen die je kan terug vinden in een aardige Reference Card [2].

Nu dat we een kleine inleiding over DocBook elementen hebben gezien, is het tijd om verder te gaan en om te beginnen met het maken van een PDF document.

Omzetting van documenten naar PDF

Als we eenmaal een DocBook bestand hebben kunnen we deze omzetten naar verschillende formaten. Het omzetten naar PDF is al vermeld, maar we zouden het document ook om kunnen zetten naar een website, een PostScript document, een Tex source bestand of een RTF (Rich Text Format) document dat WordPerfect, Word, StarWriter en andere tekstverwerkers kunnen lezen. Maar in dit artikel hebben we het alleen maar over het omzetten naar een PDF document.

DocBook documenten kunnen worden geschreven in elke editor zoals VI en Nedit. Nog beter is Emacs: Norman Walsh schreef een Emacs major mode voor DocBook [3] wat enige nuttige functies toevoegt, zoals het aanvullen van elementnamen of het invoegen van een compleet voorbeeld element.
Naast het maken van je eigen test-artikel, kun je ook mijn versie downloaden wat alle voorbeelden bevat die in dit artikel worden gegeven.

Zoals werd verteld aan het begin van dit artikel, hebben we een stylesheet en een tool nodig dat dit stylesheet gebruikt voor het omzetten van het DocBook artikel in PDF formaat. De stylesheet converteert het DocBook niet direct naar PDF formaat, er zit nog een TeX stap tussen. De stylesheet die wij gebruiken zijn de DocBook Stylesheets van Norman Walsh [4] die zijn geschreven in DSSSL.

Om deze DSSSL stylesheets te kunnen gebruiken heb je een DSSSL processor nodig. De processor die ik gebruik heet Jade [5] en is ontworpen door James Clark (hij stopte met het onderhoud ervan). Het is vervangen door OpenJade [6], maar die tool heb ik nog niet gebruikt.

Merk op dat het Modular Stylesheet pakket, Jade en JadeTex (zie beneden) beschikbaar zijn voor alle distributies die met packages kunnen omgaan (zoals RedHat, Suse, Corel en Debian)! Dus controleer eerst je installatie programma, CD of de website van je distributie!

Op mijn Debian systeem zijn de Modular Stylesheets van Walsh voor het omzetten in PDF, geïnstalleerd in /usr/lib/sgml/stylesheets/dsssl/docbook/nwalsh/print/ wat wordt weergegeven met de "-d" parameter voor Jade. De "-t" optie vertelt Jade om de TeX uitvoerfilter te gebruiken:

egonw@localhost> ls -al
total 3
-rw-r--r--    1 egonw    egonw        2887 Apr  8 22:06 docbook_article.xml
egonw@localhost> jade -t tex -d 
 /usr/lib/sgml/stylesheets/dsssl/docbook/nwalsh/print/docbook.dsl
 docbook_article.xml
egonw@localhost> ls -al
total 21
-rw-r--r--    1 egonw    egonw        2887 Apr  8 22:06 docbook_article.xml
-rw-r--r--    1 egonw    egonw       17701 Apr  8 22:29 docbook_article.tex

Zoals je ziet maakt Jade een TeX-bestand aan. Dit TeX-bestand kan worden omgezet in een PDF bestand met behulp van de pdfjadetex tool dat bij het JadeTeX-pakket zit. [7]:

 egonw@localhost> pdfjadetex docbook_article.tex

Dit maakt een een aardige docbook_article.pdf aan. Merk op dat er veel grafische layout wordt toegevoegd, bijvoorbeeld de titel van het artikel verschijnt bovenaan op elke pagina en programmacode staat in een ander lettertype. Toen ik met DocBook begon ging de meeste tijd zitten in het begrijpen welke combinaties van elementen ik zou kunnen hebben. Dit artikel laat maar één mogelijke combinatie zien.

Opmerkingen

De DocBook XML taal is erg uitgebreid. En hetzelfde geldt voor de tools waarmee je DocBook documenten omzet in andere formaten. Dit artikel geeft alleen maar een korte inleiding. Vragen kunnen worden gesteld op de talkback pagina van dit artikel. Meer informatie kan worden gevonden in de referenties [8] en [9]. Merk op dat deze laatste referentie compleet is geschreven in DocBook!

Geavanceerde onderwerpen die niet behandeld zijn in dit artikel, maar wel mogelijk met Docbook:

mogelijkheid tot het gebruik van referenties
het maken van links naar andere secties, voorbeelden

Misschien onderwerpen voor een toekomstig artikel?

Referenties

1. De DocBook website

2. Quick References: DocBook Elementen

3. De Emacs major mode voor DocBook

4. De Modular DocBook Stylesheets

5. Jade

6. OpenJade

7. JadeTeX

8. De DocBook site van Norman Walsh

9. DocBook: The Definite Guide een SGML variant