**This is an old revision of the document!**
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.
Strengths [Weaknesses]
Familiar
XML is vastly different than HTML, but the concept is very similar. If you are good with HTML, then XML will feel like the “pro” version of what you already know.
Strict
XML is rigid in what its processors accept, so there is an absolutism to how you structure your documents. This may help you organise information better, and it guarantees predictable output in the end. You won't spend time shifting indents and special meta-characters around in your text editor; you will spend time writing content within a well-structured framework.
Documented
XML is a long-standing format, and Docbook is a well-respected schema. Docbook is well documented on http://docbook.org and XML is so well-known that you can take classes on the subject.
[Ex]Portable
One your text is in XML format, it is structured and predictable. This probably means that if there is another format (html, epub, pdf, ps, plain text, rtf, odt, and so on) that you want to output to, you can convert to it from XML. There just isn't any ambiguity about XML, and heaps of post-processors.
Weaknesses [Strengths]
Complex
The process of creating well-formed XML is not simple. It is a very verbose format, it will fail at the smallest error, it enforces inheritance, and it requires some number of post-processors in order to get it out of the XML format.
Strict
Unlike markdown or HTML, XML is intolerant of any deviation from its defined schema. Something as simple as a missing closing tag will break the processor. There are tools, such as xmllint to help ensure well-formed XML, but it is not uncommon to attempt at least three builds before a successful one.
Style
The look of documents output from Docbook are clean and professional, but to change the look and feel of your output, you probably need to learn XSL. XSL can be complex, especially if you have only just learnt XML and how to process it.
Install
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. The schemas are located in /usr/share/xml/docbook/xml-dtd-X.Y (where X.Y is a version number).
Quickstart
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.
The basics
–
> Adding the Docbook Header <--
One thing text2docbook did not add for you (because we commented it out) is the docbook header. This is the function of the config.sh I have with my sources; it permits the user to enter their docbook path (DOCLOC) and the creates a simple docbook.header file with the docbook header in it along with the appropriate path to the docbookx.dtd file.
If you are literally going to be working on just one system such that the location of docbookx.dtd will never change, you could hardcode this into the first xml file, or you can keep it modular and create a docbook.header file. Point is, this declaration needs to happen at the very beginning of your work:
p--------------------------------------------------------------q | <!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML V4.4//EN" | | "/usr/local/share/xml/docbook/4.4/docbookx.dtd"> | | | b------------------------------------/fig 5. the docbook header!
Docbook can format articles or books; so if you're writing a book the header should have: DOCTYPE book PUBLIC
If you are writing an article, then you want: DOCTYPE article PUBLIC
And, as I've said already, the actual PATH to docbookx.dtd is something you'll need to define for the system. You can always find that out with this command:
p-------------------------------------------------q | bash$ find /usr/share/xml/ -iname docbook*dtd | | | b-------------------------------------/fig 6. find!
–
> xmlto html and xmlto pdf <--