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.
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.
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
The root file is
tcc_fo.xsl for the print route.
Many style features of DocBook web pages use CSS,
referring to file
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
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.