The tools
In this section, we will cover some of the tools that you'll need or want to use to create your own LDP documentation. I'll describe them here, and better define them later on, along with how to install them. If you use some other tool to assist in writing LDP, please let me know and I'll add a blurb here for it.
DSSSL
The Normal Walsh version is required, the LDP is optional.
Norman Walsh DSSSL
http://nwalsh.com/docbook/dsssl/db152.zip
The Document Style Semantics and Specification Language tells jade how to render a SGML document into print or online form. The DSSSL is what converts a title tag into an <H1> tag in HTML, or bold, 14 point Times Roman for RTF, for example. Documentation for DSSSL is located at http://nwalsh.com/docbook/dsssl/db152d.zip.Note that modifying the DSSSL doesn't modify DocBook itself. It merely changes the way the rendered text looks. The LDP uses a modified DSSSL that provides for a table of contents.
LDP DSSSL
http://metalab.unc.edu/gferg/ldp/ldp.dsl
The LDP DSSSL requires the Norman Walsh version (see above) but is a slightly modified DSSSL to provide things like a table of contents.
DocBook DTD (version 3.1)
Required - http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip
The DocBook DTD defines the tags and structure of a DocBook SGML document. Modifying the DTD, such as adding a new tag, doesn't make it DocBook anymore.
Jade
Jade and OpenJade are two of the programs that do most of the rendering and validation of code based off the DTD and DSSSL. One of the following is required and should be installed after the DTD and DSSSL have been installed.
Jade
ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz
Jade is the front-end processor for SGML. It uses the DSSSL and DocBook DTD to perform the verification and rendering from SGML into the target format.
OpenJade
http://openjade.sourceforge.net/
An extension of Jade written by the DSSSL community. Some applications require jade, but are being updated to support either software package.
Jade wrappers
These tools are optional and may be installed after Jade, the DSSSL, and DTD have been installed.
sgmltools-lite
http://sgmltools-lite.sourceforge.net/
This is the successor to the sgmltools project, which has officially been disbanded for over a year. Since then, Cees de Groot has created a slightly different project, which acts as a wrapper to the jade SGML processor. It hides much of the ugliness of syntax. This author was able to install the old sgmltools package followed by the sgmltools-lite and could format this document quite easily. There's even a man page for sgmltools showing syntax.
Cygnus DocBook Tools
May be Red Hat specific - http://www.redhat.com/
Red Hat distributes three packages, starting with the 6.2 release, that include DocBook support and some tools. The tools are easily installed, allowing you to focus more on writing than wrestling with the tools. TeTex, Jade, and JadeTeX must be installed first. All three of these packages are available on the installation CD.
Editing tools
The following tools may be used to create, edit, or validate your HOWTO.
LyX
LyX provides the power of writing SGML with the ease-of-use of a regular word processor. It's not a WYSIWYG program, but more WYSIWYM (What You See Is What You Mean) application, since what you see on the screen isn't necessarily what happens after the SGML processor is done with it. The display that LyX provides is similar to, but not exactly like, what the output from jade would look like. However, it's close enough for you to see the flow of the document. Sections and subsections are numbered and put in bold, and different fonts are used to signify things like <code> or <url> tags. Most tags are hidden from the main LyX window while you edit, since LyX writes in TeX, then exports the TeX to SGML.
Figure 1. LyX screen shot
Emacs (PSGML)
Optional - http://www.lysator.liu.se/~lenst/about_psgml/
Emacs has an SGML writing mode called psgml that is a major mode designed for editing SGML and XML documents. It provides "syntax highlighting" or "pretty printing" features that make SGML tags stand out, a way to insert tags other than typing them by hand, and the ability to validate your document while writing.
For users of Emacs, it's a great way to go, and many believe it to allow more versatility than any other SGML documentation tool. It works with DocBook,LinuxDoc and other DTDs equally well.
VIM
No mention of Emacs is complete without talking about vi. The VIM (Vi IMproved)editor has the functionality of regular vi, but also has an SGML mode that will color-coordinate your screen to show where tags are.
WordPerfect 9 (Corel Office 2000)
WordPerfect 9 for the MS Windows platform has support for SGML and DocBook 3.0. WordPerfect 9 for Linux has no SGML capabilities.
This is the least expensive of the commercial applications that support SGML.
sgedit
The sgedit program allows you to visually edit SGML files. It has the advantages of not needing to know Emacs or VI before starting, and is cross-platform, working in both Windows and Linux. It's a commercial application, but pricing has not been set. There will be free licenses for private and academic use.
Along with visual editing, sgedit will also validate documents on loading, and on demand by using the Document->Validate command.
Other/Reference
The items in this section are reference books or other utilities that can't quite be categorized (yet).
DocBook: The Definitive Guide
This book was released by O'Reilly in October 1999, and is a great reference to DocBook. I have not found it to be a great practical book, and much of the emphasis is on XML, but the DocBook tags for version 3.1 are all listed in a handy format. You can pick it up at the book vendor of choice. The entire book is also available online (in HTML and SGML formats) at the above URL.
Aspell
Optional - http://aspell.sourceforge.net/
This spell checking application can work around SGML tags, and only spell check the content within the tags. Default spell checkers like ispell will try to spell check the tags, causing errors at every new tag.