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 some networking, 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 LinuxDoc 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 different element.
Over time, the LinuxDoc DTD is going to change over to the DocBook DTD, used by others and giving the LDP a consistent look and feel to other SGML documentation. As this happens, we'll keep you updated via this HOWTO or on the mailing lists. The biggest difference between LinuxDoc and DocBook is that DocBook assigns tags to different types of content (such as commands, file names, directories, and so on) while LinuxDoc assigns tags based on the way the text should look (you can assign emphasized or typewriter for example)
SGML provides for more than just formatting. You can automatically build indexes, table of contents, and links within the document or to outside. The sgmltools package 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 (DOC, PostScript, and so on). Programs like LyX (right now my LinuxDoc editor of choice) 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
The sgmltools package contains the SGML tools needed to render SGML as any of the file formats listed above. It also contains the LinuxDoc DTD, needed to make LDP documentation. To create only SGML documentation, this is all you need. If you want to render to formats like TeX, you'll need to get those packages as well. The sgmltools package is available either with your distribution of choice, or via http://www.sgmltools.org/. Note that you will need version 1.0.9 to use LinuxDoc. Any other version is written for DocBook.
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 actually 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
The LyX program is a graphical WYSIWYM (What You See Is What You Mean) and provides a much-needed link between an easy-to-use graphical app and renderer and the sometimes-complex rules of SGML. LyX was really used to write TeX documentation, and many of the TeX rules apply in LyX. For example, while sections are automatically numbered, you can't insert whitespace (spaces and tabs) easily. It's against what TeX was designed to do. As it is, SGML often ignore the same whitespace. The LyX program can read the LinuxDoc DTD and provide a template document for you to write (or edit) your LDP documentation in a way that you're familiar with, without having to use vi and remember what the tags are for itemizing a list. LyX is available at http://www.lyx.org/.
For those of you using KDE, there is a port of LyX using the Qt libraries. You can find more information on this version at http://www.devel.lyx.org/~ettrich/klyx.html.
Optional
There is an Emacs mode for writing SGML and XML documents. You can get more iformation about it at http://www.lysator.liu.se/projects/about_psgml.html.
Optional
The latest release of WordPerfect 2000 will have support for SGML modes. I'm not sure yet if this includes LinuxDoc, or only DocBook. If you're a beta tester of WP2k and can tell me how well it works, I'll be happy to include your notes.