Login | Register
My pages Projects Community openCollabNet

1.  Motivation

[ fromfile: motivation.xml id: motivation ]

If you're like me, you learned HTML a long time ago, and were quite frustrated by its limitations as a documentation language.

Perhaps you also find yourself typing HTML tags all the time and linking to external webpages as well as internal document locations when you write text notes to yourself.

Slacker's Docbook consists of a preprocessor, some scripts, and some style sheets which extend Docbook XSL. I developed Slacker v1 in Perl as I was learning Docbook, and Slacker V2 in Python as I was learning Python. It is designed for coders like us who hate to do repetative tasks and want to achieve the maximum possible reuse of every piece of text or sourcecode. Slacker v2 is a re-work in Python which is not backward compatible with Slacker v1.

By writing the source documents in Slacker's Docbook, you can generate multiple renditions of it, in HTML, PDF, or other formats. And while it is not necessary to learn most of the Docbook language, you can incorporate Docbook tags at any time during your development (such as indexterm, glossaries, cross-references, bibliographies, etc).

Another interesting thing about Docbook is that many of its tags are now also in HTML5!

Slacker's Docbook, therefore, is XML, and it is Docbook, but at the same time, it looks a lot like XHTML! If you already know a little HTML, you can start writing Slacker after learning the strict XML syntax rules and the meanings of a few basic Docbook tags.

The build script in this package searches your "docs.dir" for all .xml documents and produces a docbook versions of each file. The subsequent transformations using the docbook stylesheets provide you a table of contents, list of code examples, and cross-reference capabilities.

You place no formatting or presentation info in your .xml file - only content and markup tags. The presentation styles are all handled by XSL and (if you are generating HTML) CSS stylesheets.

There are so many advantages to using Docbook/XML.

  • You can take an existing Docbook document and start adding Slacker's tags right away, since it is a superset of Docbook.

  • It enables you to maintain modular reusable documentation components, linking to and including other pieces of content. It has more power and flexibility than DHTML, and greater ease of use than xincludes, or DTD entity references.

  • It is human-readable and machine-readable.

  • You can use any editor you want, and there are lots of free XML editors to choose from.

  • With an XML editor that recognizes XSD, you can get validation and completion popups.

  • Everything you write can be reused in other books or documents.

  • Once your documentation is in this format, it can be converted easily to HTML, LaTEX, postscript, PDF (click here to see sample), or plain text. Or any other format that comes up later.

  • It generates the table of contents and index for you.

  • It's customizability rivals LaTEX.

  • There are lots of tools that can read Docbook as the input language.

Docbook cumbersome to compose documentation directly in. Some of the tags are too verbose, and we needed a preprocessor for the source code examples anyway.

I wanted simpler HTML tags for the most commonly used elements, and very convenient tags for the most common operations (inclusion, inserting images). Further, the formatting of included sourcecode needed to be performed before any XML parser processed it.

Slacker's Docbook is a preprocessor for Docbook, so it produces standard Docbook/XML as its output. Any tag that the preprocessor does not recognize gets passed through from input to output. This means that in addition to the entire Docbook language, you can use these tags:

  • <b>bold</b> and <i>italic</i> tags just like XHTML

  • <li> </li> listitem tags for <ul>unordered and <ol> ordered lists

  •       You can use pre tags for
          preformatted
          output 

  • <tt> alternate font for computer output

  • a convenient way of including XML documents

  • a convenient way of including non-XML documents

  • Comment-processing of included C++ and Java code, with // start and //end comments.

  • Comment-processing to translate multiline comments into callouts.

  • Language-intelligent text formatting.

  • Auto-Hyperlinking based on keywords, to HTML docs.

  • Comment-processing for hash-comment languages like python, bash, and perl.

[Note] Future Plans

The current transformation is written using a very fast parser known as pyRXP, by ReportLab. It requires an installation step, which non-python programmers might not want to perform. It might be accepted more widely if there was a 100% pure Java or Python (standard API) implementation of Slacker's to transform files.