Docbook

Docbook is a typesetting and layout tool for authors. Specifically, it is an XML schema intended to produce both print and electronic copies of text. Combined with any one of many powerful xml processors available, it achieves the goal of letting an author write once and publish to anything. It is widely used in technical documentation (such as the first few editions of Slackermedia itself), but also for works of fiction, academia, and more.

Docbook is not an application, but a schema, meaning that it is nothing more than a set of rules that you follow whilst writing text in any plain text editor of your choice. If you have ever used HTML, it's a little like that; you don't install HTML, you just write it, and other programmes bear the burden of interpreting it and processing it into a form for public consumption.

The docbook schema, along with a number of XML tools, comes pre-installed on Slackware.

To find where you schemas are located, use the find command:

find / -iname "*docbook*dtd*"

This reveals that the schemas are located in /usr/share/xml/docbook/xml-dtd-X.Y (where X.Y is a version number).

The best quickstart guide to Docbook is a short work by David Rugge, Mark Galassi, and Eric Bischoff and located at http://xml.web.cern.ch/XML/goossens/dbatcern/dbatcern.html.

Here is a basic summary, featuring a severely limited set of functionality:

The Docbook header is a line of text at the top of a Docbook file which identifies the file as being an XML document following the Docbook schema, and points to where the schema's rules are located on your computer (or a networked location, if you have confidence in your network environment).

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML V4.5//EN" "/usr/local/share/xml/docbook/4.5/docbookx.dtd">

Docbook can format articles or books; so your header should match what you intend to write:

• If writing a book, the header should include: DOCTYPE book PUBLIC
• If you are writing an article, then: DOCTYPE article PUBLIC

The structure of a Docbook file is inflexible. If you are writing an article, then the order of tags is defined by the article schema, and if you are writing a book then the order of tags is defined by the book schema. Any deviation from the schema rules will result in invalid XML and usually will be rejected by an XML processor.

The easiest way to learn what a particular schema demands is straight from the Docbook documentation, available online at http://www.docbook.org/tdgXY/en/html/docbook.html (where tdgXY is the version of Docbook that you are using).

A simple example of a Docbook file using the book schema:

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML V4.5//EN" "/usr/local/share/xml/docbook/4.5/docbookx.dtd">

<book>
  <title>
    Restricting Less
  </title>

  <chapter id="one">
    <title>How Open Source Excludes No One</title>

    <para>
      Download it and try it
    </para>

And now to create a directory for the files, and process tmp.xml with xmlto:

p---------------------------------------------q 
|  bash$ mkdir ./html                         |
|  bash$ xmlto html tmp.xml -o ./html         |
|                                             |
b----------------------/fig 8. xmlto in action!

Obviously the syntax of xmlto is… xmlto - the command html - the type of output we want -o - the flag to tell xmlto where to dump the output files

And now if you navigate into the html folder you'll find a BUNCH of html files, and if you launch konqueror or some other web browser to that folder, then you'll see it lookin' all pretty and really nicely laid out and stuff.

For a pdf, the first and second steps are essentially the same; if you already have a concatenated tmp.xml then you can skip that step, and the second is similar:

p---------------------------------------------q 
|  bash$ mkdir ./pdf                          |
|  bash$ xmlto fo tmp.xml -o ./pdf            |
|                                             |
b----------------/fig 9. xmlto in action again!

WTF is an fo file? I don't know, but it's the intermediate step between raw unadulterated XML and a fancy hot-link-clickable PDF. It dumps out a tmp.fo in your ./pdf directory.

To get the tmp.fo into pdf, we use Apache's fop:

p-----------------------------------------------------q 
|  bash$ fop ./pdf/tmp.fo ./pdf/myBook_by_myName.pdf  |
|                                                     |
b-----------------------------------------/fig 10. fop!

And now in your ./pdf directory you have a really really cool pdf with a table of contents that is clickable, and text that can be copied and pasted, and all that good stuff, just like the pro's. Except, in our case, we didn't have to sell our souls to the evil that is Ad0be :^)

So, that's it, you're done. Oh, well, unless you want to take it to the next level. I mean, if you think you can handle it. Well, take a moment, think it over, and if you want this to be a really lean-and-mean docbook-wielding machine, gather your party and venture forth:

–

> The Makefile <--