Chapter 4. Common Elements for all nALFS Documentation Editors

Editing the guides for nALFS is not difficult at any stretch of the imagination. The biggest piece is have an understanding of the DocBook XML DTD. The DTD's home page has a lot of information on how to use it and a book is also available.

The nALFS books (or guides) each have their own unique design and layout. They all, however, share some common pieces.

  • As mentioned above, they are all written using the DocBook XML DTD v4.3.

  • They all can be parsed into three formats: chunks-html, nochunks-html and flat-text.

  • Each has a Preface that contains: a foreward, the guide's organization, a "Who would want to read this" section and finally a prerequisites page.

  • Each has an Introduction that contains: a welcome page, acknowledgements, document conventions, contact info and changelog.

This is where the similarities end. After this point, each book takes on the characteristics necessary for its audience.

The books are available from the SVN repository. See the SVN page for instructions. In the root of the guide's source tree is a README file. It provides the necessary instructions to help you install the tools that you will need to use the makefile to parse the XML source into one of the three rendered editions.

A note on version numbers : The guides each have a separate version number. The number is split into two pieces. The first piece is the major and minor version of nALFS that the guide is written for. The second piece is the version of the guide itself. The version numbering scheme is set up this way to ensure that a reader will know that the version of the guide they are reading goes with the version of the package they are using. The version number of the ALFS DTD syntax document is special. It is versioned to be the same as the version of the DTD itself. The ALFS DTD is special in this regard. nALFS uses the DTD, but the DTD is "implementation agnostic" and keeps its own version number separate from any implementation (nALFS is one implementation of the ALFS DTD).