Next / Previous / Contents / TCC Help System / NM Tech homepage

3. Software tools for document creation

3.1. DocBook

There are times for Web-based documentation, and there are times for physical paper documents. Good Web-based information is the way most people operate nowadays. On the other hand, if the power is off in the server room, you probably don't want to rely on Web-based documentation for the procedure on bringing up servers.

3.1.1. Why DocBook?

The DocBook system gives you the best of both worlds and has these advantages:

  • The document exists in a single form that is automatically translated into both Web pages and a paper document.

  • To write a document in DocBook, the author doesn't have to worry about exactly how it is presented, just the structure of the document (paragraphs, sections, bullet lists, and so forth).

To learn DocBook, see these TCC documents:

Another advantage of DocBook is that all the documents created with it will bear the official TCC logo, and use consistent fonts and layout conventions, so that documents written by different authors will still look like they came from the same organization.

One of the chief duties of the documentation staff is to customize the local presentation of DocBook documents, both in Web and print form, to make them more useable and attractive.

Some people say, why do we need a separate print form? Why can't we just use the print function in our browser to print the web pages? That may work for very short documents, but longer documents need a lot of navigational features to help the reader find their way around:

  • The table of contents of a document shows the overall structure of the document so the reader can decide what parts are relevant, and jump straight to those parts.

  • Cross-references are vital in larger works. For example, a document describing how to build a graphical user interface should have a section on color, so that all the other sections that discuss how to specify colors can refer to it.

  • An index is a good idea for book-length documents.

All these features need a way for part of a document to point at some other part. In a Web document, we can use links. But a proper print document should have page numbers, and the table of contents, cross-references and index should use those page numbers. Printing from a browser won't do that.

Using DocBook, the author specifies the cross-references directly in the document, and doesn't even worry about the table of contents or index. When the document is written, it can be translated mechanically into both forms, with links holding the Web form together and the print form structured with page numbers. In either case, the table of contents and index are generated automatically.

3.1.2. Local customization of DocBook

The customization of both Web page and PDF files generated from DocBook documents is controlled by a local customization layer built on top of Norman Walsh's Modular Style Sheets. This customization layer is currently located in directory /u/www/docs/tcc/doc/docbook42xep. The root file is tcc_html.xsl for HTML, tcc_fo.xsl for the print route. Many style features of DocBook web pages use CSS, referring to file “tcc/docbook.css”.

The XSLT code for the customization layer is available in a literate exposition: see Customization of the DocBook XSL stylesheets for the TCC.

We currently have two DocBook systems in place. The one mentioned above is the production version. It uses a proprietary program named XEP to create the final PDF version of DocBook documents. We don't currently have to pay for XEP, having gotten a free academic license. However, if they ever get too expensive, we may have to fall back to the inferior open-source equivalent FOP. Documentation for this system lives in tcc/doc/docbook42/.

These documents are essential to anyone who wants to understand or modify our customization layer:

  • XSLT, for Extended Stylesheet Language Transforms, is the language used in the stylesheets. A good reference is XSLT by Doug Tidwell (O'Reilly, ISBN 0596000537). The official TCC publication XSLT Reference will help you remember XSLT's features once you've learned the language.

  • DocBook XSL Stylesheet Reference Documentation by Norman Walsh. This is a fairly skeletal introduction to obtaining, installing and customizing the style sheets.

  • DocBook XSL: The Complete Guide by Bob Stayton. This is now available as a published book from Sagehill Enterprises, ISBN 0974152110. The TCC purchased a license for the PDF version of this book, and there is a ring-bound hardcopy. This book is absolutely essential for anyone doing serious customization of DocBook.