The Linux Documentation Project (LDP) was started to provide new users a way of getting information quickly about a particular subject. It not only contains a series of books on administration, networking, and programming, but has a large number of smaller works on individual subjects, written by those who have used it. If you want to find out about printing, you get the Printing HOWTO. If you want to do find out if your Ethernet card works with Linux, grab the Ethernet HOWTO, and so on. At first, many of these works were in text or HTML. As time went on, there had to be a better way of managing these documents. One that would let you read it from a web page, a text file on a CD-ROM, or even your hand-held PDA. The answer, as it turns out, is SGML.
The Standard Generalized Markup Language (SGML) is a language that is based on embedding codes within a document. In this way, its similar to HTML, but there is where any similarities end. The power of SGML is that unlike WYSIWYG (What You See Is What You Get), you don't define things like colors, or font sizes, or even some kinds of formatting. Instead, you define elements (paragraph, section, numbered list) and let the SGML processor and the end program worry about placement, colors, fonts, and so on. HTML does the same thing, and is actually a subset of SGML. SGML has really two parts that make it up. First is the Structure, which is what is commonly called the DTD, or Document Type Definition. The DTD defines the relationship between each of the elements. The DocBook DTD, used to create this document, is an example of this. The DTD gives a common look and feel to each document that's created using the DTD. Second is the Content, which is what gets rendered by the SGML processor and is eventually seen by the user. This paragraph is content, but so would a graphic image, table, numbered list, and so on. Content is surrounded by tags to separate out each element.
SGML provides for more than just formatting. You can automatically build indexes, table of contents, and links within the document or to outside. The Jade and OpenJade packages also lets you export (I'll call it render from here on) SGML to LaTeX, info, text, HTML, and RTF. From these basic formats, you can then create other formats such as MS Word, PostScript, PDF and so on. Programs like LyX allow you to write in TeX format, then export it as SGML and render from SGML to whatever you chose. In the end, SGML is more concerned about the way elements work instead of the way they look. A big distinction, and one that will let you write faster, since you don't have to worry about placement of paragraphs, font sizes, font types, and so on.
In this section, I'll go over 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.
Required - 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.
Replacement for Jade - http://openjade.sourceforge.net/
An extension of Jade written by the DSSSL community (see below for what a DSSSL is). Some applications require jade, but are being updated to support either software package.
Required - 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.
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.
Highly Recommended - 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.
Optional
TeX (rhymes with blech!) is the markup language of choice for many, including those in the mathematics world. I still remember many Calculus exams that were written in TeX. It is also one of the first markup languages that is still around (the other being the *roff formats used in man pages). TeX actually follows some of the same concepts that SGML does. However, TeX renders its files into DVI (Device Independent) that can then be rendered into another format. Unfortunately, DVI can't be easily converted into anything other than printer languages (PostScript, PCL), making it hard to use to generate HTML. TeX is installed or is available with most Linux distributions. TeX is available on almost all distributions as LaTeX or TeTeX. Either should work for you.
Optional - http://www.lyx.org/
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.
Optional - http://www.lysator.liu.se/~lenst/about_psgml/
Emacs has an SGML writing mode called psgml. Anyone with experience writing in this mode is welcome to e-mail the author of this document. psgml is a major mode in Emacs designed for editing SGML and XML documents. It provides "syntax highlighting" or "pretty printing" features that make SGML tag 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.
Not recommended - http://www.corel.com/
WordPerfect 2000 for the MS Windows platform has limited support for SGML and DocBook 3.0. WordPerfect 2000 for Linux has no SGML capabilities.
Optional (but recommended) - http://www.docbook.org/
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 at the above URL.
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 spellcheck the tags, causing errors at every new tag.
Optional (may be Red Hat specific) - http://www.redhat.com/
Red Hat distributes three packages, possibly starting with 6.2, that include DocBook support and some tools. They provide for only rendering to HTML and PDF, but they're easily installed if you have Red Hat, allowing you to focus more on writing than wrestling with the tools. TeTex 0.9, Jade, and Jadetex must be installed first.