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>
    Texto Ekzempla
  </title>

  <chapter>
    <title>
      Kiel Libera Programmaro Intigas Arton
    </title>

    <para>
      Elsxuti <ulink url="http://slackware.com">Linukso</ulink>, kaj provu gxin.
    </para>
  </chapter>
</book>

To some degree, it is intuitive as long as you know the tags that you have to work with, and the order of the basic skeleton structure. In the case of a book, the basic structure is:

• book
• book title
• chapter
• chapter title
• paragraphs
• (close chapter tag)
• (close book tag)

This file, saved, is a valid Docbook file, but it is essentially source code.

The easiest XML processor to use is xmlto, an application run in the shell with the sole purpose of translating XML into any number of other formats.

For example, to convert the book into an html file:

$ mkdir html
$ xmlto html book.xml -o ./html 

Or into plain text:

$ xmlto txt book.xml -o book.txt

There are several ways to generate a PDF, but the most reliable tends to be the Apache Foundation's fop tool. Fop is written in Java, so it does require that the Java runtime is installed.

Install Java (called jdk; the Java Development Kit) from either the /extra directory on your install media, or from http://slackbuilds.org/repository/X.Y/development/jdk/ (where X.Y is the version of Slackware that you are running). As Java is currently owned and maintained by Oracle, it requires a EULA agreement that can only be satisfied with a GUI, so you must manually download the Java installer, but you can then run the SlackBuild installer separately so that you have Java properly logged in /var/log/packages.

Once JDK is installed, install fop from http://slackbuilds.org/repository/14.1/office/fop/?search=fop.

To create a PDF, first translate your Docbook file to fo with xmlto:

$ mkdir ./pdf
$ xmlto fo book.xml -o ./pdf
$ fop ./pdf/book.fo -o ./pdf/book.pdf

Wait for the document to process, and at the end you have, in the pdf directory that you created, a PDF file. Even the hyperlink is fully-functional, just like in a “real” PDF (because it is a real PDF, fully compliant with the spec).

In large works, there is an advantage to keeping your writing modular. Structuring your work such that each chapter is an individual file allows your text editors to load and work on them faster, and makes rearranging the order of the chapters trivial.

If you choose to work modularly, you only need your Docbook header in the first file, and you should only close your <book> tag in the final file.
–

> The Makefile <--