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
Recent Comments