Generate HTML and PDF from DocBook in Debian

DocBook is a widely-used format for writing documentation, articles, books, etc. For my purposes, I needed to generate XHTML and PDF files from documentation in DocBook format on a Debian Wheezy server.

Install

You need to install the following packages.

sudo aptitude install xsltproc docbook-xsl-ns docbook5-xml

Convert single DocBook file to XHTML

Now comes the conversion. Run xsltproc as below and it will create an HTML file (mybook.html in this case) in the current directory.

xsltproc -o mybook.html /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/xhtml-1_1/docbook.xsl mydocbook.xml

You can explore the /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/ path for more options.

Convert modular DocBook file to XHTML

You can create a modular DocBook document (a book in my case) by separating out chapters of the book into separate files and including them in the main file. For example, there’s only one chapter in my book so I’ll have two files: docbook.book.xml and docbook.chapter.xml. These two files would look something like the following:

An example of file docbook.book.xml

<?xml version="1.0" encoding="UTF-8"?>
<book xml:id="wikiply_doc" xmlns="http://docbook.org/ns/docbook" version="5.0" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Sample Book</title>
    <bookinfo>
        <author>
            <personname><firstname>Code</firstname><surname>Ghar</surname></personname>
        </author>
        <legalnotice>
            <para>Copyright 2011-2012 Code Ghar. All rights reserved.</para>
            <para>Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted.</para>
        </legalnotice>
    <copyright><year>2012</year><holder>Code Ghar</holder></copyright>
    </bookinfo>
    <xi:include href="docbook.chapter.xml" />
</book>

An example of file docbook.chapter.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="installation" xmlns="http://docbook.org/ns/docbook" version="5.0" >
<title>Sample Chapter</title>
    <section xml:id="sample_chapter">
        <title>Sample Chapter</title>
        <para>This is example text in sample chapter</para>
    </section>
</chapter>

Run xsltproc as below and it will create an HTML file (mybook.html in this case) in the current directory from both files.

xsltproc -xinclude -o mybook.html /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/xhtml-1_1/docbook.xsl docbook.book.xml

Note the use of the -xinclude flag in the command and the xi:include XML tag in the docbook.book.xml file. These two things make the magic of modular DocBook possible.

bash alias

Since I work with a DocBook book often, I have created a bash alias as below:

alias dbtohtml="xsltproc -xinclude -o /home/codeghar/book/mybook.html /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/xhtml-1_1/docbook.xsl /home/codeghar/book/docbook.book.xml; sed -e 's/</\n</g' -e 's/<meta name/\n<meta http-equiv="Content-Type" content="text\/html; charset=utf-8" \/> \n <meta name/g' -i /home/codeghar/book/mybook.html"

The generated file does not have the HTML meta tag to identify it as UTF-8 and so space characters display as the character  in the web browser. Therefore, sed is used to enter the appropriate meta tag in the file.

Convert DocBook to PDF

Using the same example files (docbook.book.xml and docbook.chapter.xml), we will create a PDF instead of an XHTML file.

You need to install Apache FOP.

sudo aptitude install fop

Next you need to create an intermediate file (mybook.fo) as below.

xsltproc -xinclude -o mybook.fo /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/fo/docbook.xsl docbook.book.xml

Finally, run the following command to create the PDF file:

fop mybook.fo -pdf mybook.pdf

Hat Tips

DocBook Ubuntu Documentation; How to generate pdf from docbook 5.0; Getting Started with Docbook Book Authoring on Ubuntu; Writing Documentation; Playing With DocBook 5.0

2 Responses to Generate HTML and PDF from DocBook in Debian

  1. Pingback: Primeros pasos con DocBook « Desde lo alto del Cerro

  2. Vanessa says:

    I need a help documentation that generate HTML files and it must be free. Nowadays I use Help and Manual, but it is too rustic and is not good enough. Could somebody recommend me a good free help tool?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 30 other followers

%d bloggers like this: