The FreeBSD Documentation Project

02/08/2001

Like the main FreeBSD source tree, the FreeBSD documentation evolves constantly. The copy on FreeBSD.org is always current, but having a copy locally can be a lifesaver -- especially if you're looking for documentation on how to fix your Internet connection!

If all you want is the most recent documentation, it is easiest to download it from your nearby FreeBSD mirror under the /pub/FreeBSD/doc directory. Each translation has its own subdirectory, named after the two-letter ISO language code. If you want documents in English, go to the en directory. There, you'll find "books" and "articles."

The difference between books and articles is fairly arbitrary: Articles are short; books are long. There are no specific limits for either. Books include the FAQ and Handbook, plus project-specific documents such as the Documentation Primer and the Porters Handbook. Articles include the "Committers Guide" and the "New Users Guide."

Once you've chosen the documentation you want, you can pull down the article in a variety of formats: one HTML file, small HTML files, PostScript, RTF, and so on. I recommend HTML, so you can view it with your preferred web browser.

It's also boring. Why use preformatted anything when you can compile it from the original source code? This is BSD, after all; we use make world at the drop of a hat, why not do the same for the documentation?

Compiling documentation might seem like overkill -- after all, it's just words! Why keep it in a form that needs compiling when most people just want HTML? There's a solid reason for it: By storing the documentation in a medium-independent format, it can be automatically converted to any format desired.

Plus the documentation is updated by FreeBSD users just like you. If you find a documentation error, you can update it yourself. Or, if you see the same question asked over and over on your favorite mailing list, you can simply submit an addition to the FAQ. If you've done HTML work, changing the documentation at the source level is fairly simple. If you had to know HTML, PDF, and RTF to make a trivial change, you probably wouldn't bother.

The key to all this is called DocBook. Much like HTML, it's a format for marking up documents. Tags in HTML describe how a piece of text should look: bold, title, italic, and so on. Tags in DocBook identify what a piece of text is: a command, a file name, or whatever.

For example, a fragment of the FAQ marked up in HTML might look something like:

The <bold>send-pr(1)</bold> command...

This would print the command name in bold type making it stand out well when it's on a web page.

The same fragment marked up in DocBook would look like this:

The <command>send-pr(1)</command> command

Words that are command names are treated differently in each format. For example, you might want them to be bold in the HTML version and italics in the RTF version. Or you might want to adjust page breaks around commands in the PDF version. With a bit of minor tweaking, you can adjust how the text appears in each version. The style sheet contains instructions about how a document should appear. If a consensus of the FreeBSD Documentation Project decides that commands should be in italics rather than bold, the change can be made by adjusting the style sheet.

Compiling the documentation also ensures that the text is the same across all the versions of the document. If the HTML and PDF files were maintained separately, by hand, it would be difficult to guarantee that the text was identical. Repeat that by all the translations available, and you'd quickly find a new hobby.

If you want to be able to submit changes to the FreeBSD documentation project, you need a copy of the original document source code. Your changes will be accepted much more quickly if you can submit clean diffs rather than text that must be massaged by a third party.

To download the documentation, you need CVSup (/usr/ports/net/cvsup-bin). CVSup is a tool to access CVS repositories more easily than old-fashioned CVS. CVSup goes out to a CVS repository, compares what it finds to your local source code, then downloads and applies the diffs locally. If you've ever upgraded your OS from source, you might already have CVSup on your system.

You need a supfile to run CVSup. You can find a sample supfile for the docs collection under /usr/share/examples/cvsup/doc-supfile. The only change you need to make is to define a proper FreeBSD CVSup mirror in the line

*default host=CHANGE_THIS.FreeBSD.org

cvsup1.freebsd.org through cvsup11.freebsd.org are available for public use in the U.S. Ping several to see which are the closest, and try to use that one.

Become root, and run cvsup like this:

cvsup doc-supfile

If you have no local documentation source code, CVSup will download and install it all.

When CVSup finishes, you should have several directories of documentation source code under /usr/doc.

Now that you have the source, you need the proper tools to build it. These tools include DocBook formats, SGML conversion tools, and a variety of HTML tools. They can be installed easily with /usr/ports/textproc/docproj.

The docproj port has one important option. If you intend to create documents in PostScript or PDF formats, you need TeX. TeX is a huge package and you can save a good chunk of room if you don't install it. Folks who are only interested in HTML documentation don't need it.

You can use the JADETEX=no option to tell docproj not to install TeX:

# cd /usr/ports/textproc/docproj
# make JADETEX=no install clean

Once you have the documentation project tools installed, building and installing the documentation is pretty straightforward.

# cd /usr/doc
# make all install clean

This installs the complete documentation set on your local system in HTML format for easy local viewing. The only real catch is that it's installed in every available language. At the moment, that's eight different tongues. Chances are you don't need it in all those languages.

You can control this by going to the subdirectory for your language (probably en_US.ISO_8859-1) and doing the make install clean there. Alternately, you can specify the DOC_LANG environment variable to equal your language's directory name.

You can find lots of options to control doc-building behavior in the /usr/doc/share/mk directory. The files are well-commented, and contain everything you could want to know about the build process.

Next time we'll look at how to alter one of the DocBook source files, so you can submit your own patches to the FreeBSD Documentation Project.