XML & DocBook: Structured Technical Documentation Authoring

An introduction to XML and DocBook: what is it and why should I learn yet another data format?
Modular XML Documents

Some documents contain too much information for a single XML file. To create entire books or guides, it might be easier to split the content among multiple files. In that case, use book as the document type in the XML file declaration lines. Each of the subfiles making up the bigger document can be called on from a central file or included at any time in one of the other subfiles. However, there should be a central file that names the ENTITY. Entities can be public or local on your system. When writing your own documentation, the most common form is <!ENTITY entity_name SYSTEM "entity_xml_file.xml">.

In the central document or wherever you want to include the extra file, call on it using the &entity_name; statement. A common use of entities is in chapters of a book, where a central file declares the entities and holds the introductory content, while the chapters of the book are individual XML files.

The content of these individual files is formed using the same tags as used for shorter documentation; refer again to the DocBook Element Reference. You do not have to declare the document type again in each subfile. Instead, specify only the type of data; for instance, put content between <chapter> and </chapter> tags when writing a book or guide.

For larger documents, you may want several introductory sections, such as Feedback, Licensing Information and Acknowledgments. These sections usually are created with <section> tags. In the chapters, you are more likely to use <sect1>, <sect2>, <sect3> and <sect4> subsection tags. Books also should also contain a Table of Contents or TOC. The TOC can be generated automatically if you use the <toc> tag around the chapter headings or whatever other headings you want included in the table of contents. The DocBook DTD specifies various other tags for glossaries, indexes, cross-references and bibliographies.

Conversion to Printable Formats

As we explained before, printable files cannot be generated directly from the XML file. We need an intermediate step that generates formatted documents, in which page layout, typography, chapter and section numbering, cross references, icon graphics and a number of other things are specified.

These basic definitions for printed formats can be configured without having to customize the XSL stylesheets. Using xsltproc, specifications are entered on the command line or in a script. Here is an example command:


   xsltproc --stringparam paper.type A4 --stringparam fop.extentions 1
   /usr/share/sgml/docbook/xsl-stylesheets/fo/docbook.xslarticle.xml>
   article.fo

This command tells the processor to generate pages that fit on the standard A4 paper size, using a locally defined stylesheet on the source XML file. It also specifies that the output should be saved in an FO file.

Once we have the FO file, the next step is to transform the file into the desired format. This is done using the fop command:


   fop -fo article.fo -pdf article.pdf

Conversion to HTML

Conversion to HTML is somewhat more straightforward, because all that needs to be done, simply put, is to map XML tags to HTML tags. Here's a basic example command, again using xsltproc:


   xsltproc
   /usr/share/sgml/docbook/xsl-stylesheets-1.65.1-1/html/docbook.xsl
   article.xml > article.html

Of course, that would generate a rather ugly and unmanageable HTML file, so usually a Cascading Stylesheet or CSS is applied. This and the XSL stylesheet that is applied can make the same sources look totally different. An example of two different looks of the same document can be found here:

Fine-tuning stylesheets is a meticulous work. Various individuals have made their styles publicly downloadable, however, so you can apply them to your own sources.

Conclusion

DocBook XML is accessible to use, especially for those who have a grasp of HTML already. It is a markup language developed for writing computer documentation. It thus provides hundreds of little ways to specify content. How this content is displayed later--what fonts and font sizes are used, what colors, how the layout is done--should not be the concern of the authors. Authors can write once and publish in any desired format, which saves time, effort and, to a lesser degree, disk space and other computing resources.

This brief article really is not enough space to demonstrate fully the capabilities of DocBook. For instance, we didn't even begin to discuss DocBook's special features, such as the use of cross references, glossaries, bibliographies, automatic index generation, language settings, support for mathematical expressions and so on. Therefore, I recommend the following resources for further reading:

DocBook XSL: The Complete Guide, by Bob Stayton, ISBN: 0-9741521-1-0, published by Sagehill Enterprises.

DocBook, The Definite Guide, by Norman Walsh, ISBN: 1-56592-580-7, published by O'Reilly.

"Take My Advice: Don't Learn XML", by Michael Smith, O'Reilly XML

______________________

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Thanks a trillion!!

Anonymous's picture

Thanks a lot... This is indeed a great documentation... helped me a lot ... !!!!

Sample code won't compile! ;-)

thundt's picture

The example in Listing 1 has an error: It is missing the </author> tag.

Laughable!

Red-3's picture

I had to laugh (out loud and for a very long time) when I read this statement half-way through this article:

"General Guidelines for Writing Content

If you are an author, it is okay to skim or skip the above technical explanations..."

The author then goes on to give advice on how to write a good, well structured document. I would hate to be an author, having gone through all the technical explanations, only to read that it was okay to "skim or skip" the stuff I had already trawled through for half an hour!
Surely a statement like this would have been much more useful at the start of the document...

Oh the mindset of the developer - details first, usability second. ;)
Nice one!

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

Does anyone know a good Docbook editor. As far as I am concern, it is not obvious to write a big document under vim :)

The one I know:
Conglomerate : a gnome XML (Docbook) editor
Butterfly : a java XML editor
Jaxe : another java XML editor

The first is the best...
Any other ?

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

XML Mind is a nice and easy WYSIWYG editor.

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

XML is Extensible Markup Language, not Extended Markup Language.

http://www.w3.org/XML/

Need for a stylesheet catalogue

Anonymous's picture

Thanks for the great howto.

I have used docbook a little and I always get annoyed with the rather plain results of the default stylesheets. I see docbook written material in books and web sites that look good but I do not have the time to learn all the stylesheet stuff to set up my own.

Is there a catalogue of stylesheets/css for docbook somewhere. If not I think it would be a good idea. I think that more people (myself included) would make more use of docbook if it was easier to get nice looking final format results.

Richard

Re: Need for a stylesheet catalogue

Anonymous's picture

Whilst I generally don't get on with LaTeX too well, I do find that it produces great looking output. Therefore, I tend to convert DocBook files to LaTeX (you can get XSL files which will do this) and then use either latex itself or pdflatex to convert to a printable format. For the XSL files, start at http://db2latex.sourceforge.net/

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

Does anyone know of an XML format for storing or creating exams? I am interested in online and paper tests, and I am beginning to believe that XML would be a natural format to store tests in. Is there already a standard defined for this usage?

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

For assessment/test information in XML you might be in interested in the "IMS Question & Test Interoperability Specification" from the IMS Global Learning Consortium

http://www.imsglobal.org/question/

Re: XML & DocBook: Structured Technical Documentation Authoring

Anonymous's picture

This might be one of those situations where creating your own DTD for a test would be applicable. Then write your exams based on that DTD. I am pretty sure you can then use the same xml/xsl tools to generate your .html, .ps, .pdf, etc. files.

send me a linux project

kuldeep's picture

sir
pleaz send me a linux project about any new topic
thanx
kuldeep

White Paper
Linux Management with Red Hat Satellite: Measuring Business Impact and ROI

Linux has become a key foundation for supporting today's rapidly growing IT environments. Linux is being used to deploy business applications and databases, trading on its reputation as a low-cost operating environment. For many IT organizations, Linux is a mainstay for deploying Web servers and has evolved from handling basic file, print, and utility workloads to running mission-critical applications and databases, physically, virtually, and in the cloud. As Linux grows in importance in terms of value to the business, managing Linux environments to high standards of service quality — availability, security, and performance — becomes an essential requirement for business success.

Learn More

Sponsored by Red Hat

White Paper
Private PaaS for the Agile Enterprise

If you already use virtualized infrastructure, you are well on your way to leveraging the power of the cloud. Virtualization offers the promise of limitless resources, but how do you manage that scalability when your DevOps team doesn’t scale? In today’s hypercompetitive markets, fast results can make a difference between leading the pack vs. obsolescence. Organizations need more benefits from cloud computing than just raw resources. They need agility, flexibility, convenience, ROI, and control.

Stackato private Platform-as-a-Service technology from ActiveState extends your private cloud infrastructure by creating a private PaaS to provide on-demand availability, flexibility, control, and ultimately, faster time-to-market for your enterprise.

Learn More

Sponsored by ActiveState