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, it is 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 three 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 lists the rules that the content must follow. Second is the DSSSL or Document Style Semantics and Specification Language. The DSSSL tells the program doing the rendering how to convert the SGML into something that a human can read. It tells the renderer to convert a <table> tag into 14 point bold if it is going to RTF format, or to turn it into a <h1> tag if you're going to HTML. Finally there 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 let 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.
If you are a new to the LDP and want to pick up an unmaintained HOWTO or write a new HOWTO or mini-HOWTO document, contact the HOWTO coordinator at <ldp-discuss@lists.linuxdoc.org>. This is to make sure the HOWTO coordinator can know who is working on what documentation.
Once that part is complete, you may write your documentation in the format of your choice and submit a draft to <ldp-submit@lists.linuxdoc.org>and the draft will be reviewed by an LDP volunteer. In a few short days you will get the draft and comments from the volunteer. After applying the comments,you may send this version to the ldp-submit list again for final submission into the LDP.
At this point, another LDP volunteer will translate your document into DocBook and send you the finished DocBook document. From here on, all submissions to the LDP has to be in DocBook format. If you have markup questions, you may ask the volunteer who assisted you, or ask the LDP DocBook list.
There are a few mailing lists to subscribe to so you can take part in how the LDP works. First is <ldp-discuss@lists.linuxdoc.org>, which is the main discussion group of the LDP. To subscribe, send a message with the subject reading "subscribe" to <ldp-discuss-request@lists.linuxdoc.org>. To unsubscribe, send an e-mail with the subject of "unsubscribe" to <ldp-discuss-request@lists.linuxdoc.org>.
Another list is the <ldp-docbook@lists.linuxdoc.org> list, which is for markup or other questions about DocBook itself. If you run into trouble with a particular markup tag, you can send your question here for answers. You can subscribe to the DocBook list by sending a "subscribe"message to <ldp-docbook-request@lists.linuxdoc.org>.