BSD DevCenter
oreilly.comSafari Books Online.Conferences.


Big Scary Daemons

Changing FreeBSD Documentation


If you've answered a question on a FreeBSD mailing list one too many times, or if you've just discovered some undocumented feature that is simply too cool for words, you probably want to update some part of the FreeBSD documentation.

However, before you can improve the docs, you must have all the tools needed to build the docs. These tools include everything you need to handle DocBook, FreeBSD's document format. Take a look at the prior article for details. I'll assume you've installed the docs utilities and have CVSupped the latest docs collection, as that article suggests.

The first thing to remember is that the FreeBSD Documentation Project has made an FDP Primer available online. If you intend to do any serious documentation hacking, or you have problems you just can't figure out, start here. The docs team happily helps people with weird or obscure questions, but to complain about documentation without first reading the documentation for the documentation is just plain dumb.

I also suggest emacs for any serious FreeBSD documentation work. Emacs has some nifty DocBook tools. Please don't take this as the first shot of an editor war; if you have ways to make vi do similar tricks, feel free to write them up using the techniques given below and submit them to the documentation project. I'm sure they'll be accepted happily.

Once you have the FreeBSD Documentation Project tools installed, you need to configure your system environment. Assuming you're using BSD-standard csh/tcsh, the Documentation Project primer recommends that you add the following to your .login:

setenv SGML_ROOT /usr/local/share/sgml
setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog

This works for a vanilla-standard SGML/DocBook environment, but FreeBSD includes other FreeBSD-specific DocBook extensions. I suggest that you include those in your environment with the following line:

setenv SGML_CATALOG_FILES /usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES

The doc source files can be found under /usr/doc/en_US.ISO_8859-1/. Once you're there, you can choose which piece of documentation you want to alter. I'm going to pick on the FAQ here, since that's one of the easiest to alter. You can find the FAQ under books/faq.

If you've never built the documentation, /usr/doc/en_US.ISO_8859-1/books/faq contains the following:

# ls
Makefile        book.sgml

The "makefile" includes the build instructions, as you might expect. The entire FAQ is stored in the file book.sgml.

If you find a bunch of HTML files here, you've built the documentation and never cleaned it. A make clean in this directory will get rid of all that stuff; once you install the documents, it's basically useless.

First confirm that your environment is properly set up. You can use the syntax-checking program nsgmls for this.

# nsgmls -s book.sgml 

If you get any messages, either your source is corrupt or your tools are not properly installed.

Before you do anything, copy the original books.sgml. That way, you can edit book.sgml to your heart's content, and even build the docs tree, while still having a good copy at hand.

Open book.sgml in your favorite pager or editor. The first few lines are DocBook internal structure. If you think you need to change these at this point, you're doing something wrong.

Pages: 1, 2

Next Pagearrow

Sponsored by: