Linux Documentation Overview

Introduction Everyone who has spent much time working with the Linux operating system understands the value of good, current documentation. It's also nice to read in a format appropriate for what your trying to learn. Skimming a few README pages is fine on the web but if you have a 100 or more pages to absorb, it's a lot nicer to download the information to your PDA, or print out a pdf and and head for your local coffeehouse or pub. Furthermore, if your interested in assembling a group of documents from different authors so they can be published on the web or in book format you'll want a system that can enforce a structure and revision history. The problem with MS-Word The problem with most word processors is also their advantage. They blur the content with the style of the document, and while this gives author complete freedom over the look of the document, it makes it very easy to subtle errors in the layout. In the Linux world there are some great alternatives to this primitive way of working. Tools such as Latex, LyX, LinuxDoc, and DocBook allow authors to create their content once, marking up various elements such as title, author, and various section headings. Then when the source is complete, the computer can apply a style based on your target media. In other words, from a single source file, you can create documentation formatted for a web site, an O'Reily book, ASCII text, a magazine, etc. TeX LaTeX and LyX LaTeX is based on Donald E. Knuth's TeX typesetting language. LaTeX was first developed in 1985 by Leslie Lamport, and is now being maintained and developed by the LaTeX3 Project. LyX is a front end to to LaTeX (and therefore TeX) and in spite of its perpetual brokenness and obtuse interface, it is probably my favorite word processor I've used. TeX and LaTeX LaTeX is really a series of macros that define nice looking target formats for TeX. A simple TeX/LaTeX source file looks like this: \documentclass{article} \title{Cartesian closed categories and the price of eggs} \author{Jane Doe} \date{September 1994} \begin{document} \maketitle Hello world! \end{document} On the surface it looks a little like HTML but the result is much nicer. If you type it in to a file called latex, and compile it with: $ texi2dvi latex and display the result with: $ xdvi latex.dvi You be surprised at how good the result looks. LyX If you're the type who doesn't like remembering markup and just want to get down to the business of writing, you should have a look at LyX. LyX describes itself as a WYSIWYM (What You See Is What You Mean) word processing system. It's has a GUI but it's based on xforms so it has a little more 'rustic charm' than most of the Gnome or Kde applications you're used to. It also seems to be eternally undergoing a major source overhaul so there are little odds and ends that don't work and sometimes the whole program just disappears. Don't let that get you down though. The design is very intelligent and the output is beautiful. The LyX work cycle goes a little like this. Start by choosing File > New from template > DocBook_article.LyX. A rough looking document will appear but this is only the content editor. To see the finished product choose View > DVI. After a few seconds of processing, you'll see a finished, professionally formatted product. Under Help there is a great tutorial that should answer any further questions. LinuxDoc SGML Not long after Linux was able to boot on it's own, the Linux Documentation Project (LDP) was formed to help Linux hackers share their documentation. To manage the documents they standardized on Mat Welsh's LinuxDoc package. The LDP is believed to be the first Linux website ever LinuxDoc is an SGML Standard Generalized Markup Language based system for creating the familiar HOWTO style documents. A sample for LinuxDoc SGML looks like this:

The LinuxDoc Howto James Scott Hunter The first section

Here's a little regular text to get things going. LinuxDoc is great for simple computer documentation. Especially if that documentation should be ported to web pages, man pages or DVI.

Converting to other formats

Converting to other formats is easy with LinuxDoc

Another section

]]> As you can see, SGML tags surround the document information making it possible for a formatting program to come along later and do neat things like automatically build an index, enumerate the sections or sub sections, and connect the footnotes to the correct page. Exporting LinuxDoc When your LinuxDoc SGML file is complete you can export it to another format using one of the following commands: sgml2html sgml2info sgml2latex sgml2lyx sgml2rtf sgml2txt sgml2xml Creating LinuxDoc SGML with LyX You can also use LyX to create LinuxDoc SGML files. When you start LyX, make sure that under Layout, Document, that CLASS is set to LinuxDoc Article. Using this template, you'll be able to create all elements of a LinuxDoc file and export proper SGML right from the LyX interface. LinuxDoc Conclusion Everything I tried with LinuxDoc worked. It seems mature and bug free - even when using it with LyX. I was surprised to find it is being phased out in favor of the newer and more complete DocBook method. The very first things I tried to make work with DocBook resulted in cryptic errors. Exporting DocBook from LyX doesn't seem to work yet which was a letdown for me. Now that I've switched to Emacs as my DocBook editor I'm a lot happier. DocBook SGML Last and certainly not least is DocBook. DocBook aims at being the technical documentation replacement for all of the above systems. It's development is more aggressive than anything else out there. I'm composing this in version 4.1. I've been told the spec for 5.0 is complete and work is underway on version 6.0 There are DTDs available for both XML and SGML but for the purpose of this document I'm only going to cover SGML. DocBook SGML looks a fair amount like LinuxDoc, which looks similar to HTML. Don't believe me? Well, have a look at some of the source for this document.

Linux Documentation Overview August 1, 2002 James Scott Hunter The Tacoma Linux User's Group (TACLUG)

scott@surrealistic.org

This article gives an overview of the different tools available for creating structured documentation in the GNU/Linux operating environment. Introduction ]]> You'll notice the increased granularity of the markup. Instead of my name being surrounded by just the author tag, each section of my name has it's own tag to delimit it within the author which needs to exist inside of the articleinfo tag. Editing DocBook When I started experimenting with DocBook I was using Lyx with the DocBook class to create my documents in a GUI environment. DocBook support seems about 80% 'there' under LyX but everything I did create required me to manually edit the exported SGML. Emacs After reading a few people's postings on the subject I decided to try out Emacs. I didn't have to customize anything as the default emacs Roms shipped with Red Hat 7.3 include DocBook support. The new Emacs GUI makes things much easier than trying to remember the through key bindings. As soon as emacs 'sees' the first line: ]]> You'll be able to use the Markup menu in the tool bar to automatically display the relevant tags available based on the position of the cursor. Processing DocBook SGML When you are finished editing your DocBook file you can use one of the jade wrappers to process your file into something worthwhile. db2dvi db2html db2pdf db2ps db2rtf These commands apply a DSSSL The Document Style Semantics and Specification Language found in the SGML header, to the file to define its layout. Think of it this way: The DTD specifies the rules of the SGML file. The DSSSL controls how that SGML file is rendered by converting a title tag into a header tag in HTML, or to 14 point bold Times Roman for RTF. Conclusion Of the three formatting systems I've talked about here LaTeX wins for both completeness and quality of output. There are dozens of templates available, all of which render perfectly. I don't like the markup style LateX uses but its really not as bad as it could be. LinuxDoc also wins for completeness but since it's own authors are trying to move people along to DocBook I can't really recommend it for anything new. DocBook really seems to be where all of the action is these days. In spite of the small glitches I encountered, it seems to be the most actively developed publishing system available.