ONLamp.com    
 Published on ONLamp.com (http://www.onlamp.com/)
 See this if you're having trouble printing code examples


Big Scary Daemons

Changing FreeBSD Documentation

02/22/2001

Also in Big Scary Daemons:

Running Commercial Linux Software on FreeBSD

Building Detailed Network Reports with Netflow

Visualizing Network Traffic with Netflow and FlowScan

Monitoring Network Traffic with Netflow

Information Security with Colin Percival

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
setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES

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.

Just like HTML, DocBook has tags. Every element on the page has a tag of one sort or another. Unlike HTML, all DocBook tags have openings and closings. If you leave out a closing tag, nsgmls will complain:

# nsgmls -s book.sgml
nsgmls:book.sgml:175:18:E: end tag for "ANSWER" omitted, but its declaration does not permit this
nsgmls:book.sgml:152:8: start tag was here
#

The first number given in the first line is the location of the first error.

Let's look at typical, but brief, FAQ entry.

<qandaentry>
<question id="mailing">
<para>Where do I find info on the FreeBSD mailing lists?</para>
</question>

<answer>
<para>You can find full information in the <ulink
URL="../handbook/eresources.html#ERESOURCES-MAIL">Handbook
entry on mailing-lists.</ulink></para>
</answer>
</qandaentry>

This is actually pretty straightforward. The entry opens and ends with a <qandaentry> tag. This indicates that one question and one answer are contained within the tag.

Related Reading:

DocBook: The Definitive Guide

DocBook: The Definitive Guide
by Norman Walsh & Leonard Muellner

Inside this set of tags, <question> and <answer> tags set off the two parts of the FAQ entry. The <question> tag has an additional marker so that outside indexers can find it easily. When this is converted into HTML, it will show up as a link within the page. Other formats can use this for their native indexes.

Each paragraph has open and close <para> tags.

Finally, the hyperlink uses a <ulink> tag.

You can make almost anything happen in the FAQ by finding an answer with a similar format. For example, if you have a question with several answers, and you want to list them, look through the FAQ. You'll soon find examples of the <itemizedlist> and <listitem> tags.

Similarly, if you want to show exactly what to type on the command line, checking the FAQ will show (among other things) a question on what to do when Windows 95 fries your boot manager. The source code for the example command is:

<screen><prompt>Fixit#</prompt> <userinput>fdisk -B -b /boot/boot0 <replaceable>bootdevice</replaceable></userinput></screen>

With a bit of work, you can rewrite these samples into something appropriate for your entry.

Finally, when you think you've made your change properly, you can use nsgmls to verify your work. If you've made any obvious goofs, such as not closing or improperly nesting a tag, nsgmls will catch it and complain. Loudly. If nsgmls -s runs silently, you've probably done things correctly.

DocBook is concerned almost entirely with what a piece of text is, not with how it looks. You can choose to emphasize occasional words with the <emphasis> tag.

Given the above, you can easily suggest a new entry for the FAQ. Write it up in the following template:

<qandaentry>
<question id="string-describing-question-here">
<para>Put your question here</para>
</question>

<answer>
<para>Put your answer here</para>
</answer>
</qandaentry>

Place this in a reasonable section in the FAQ, and run nsgmls -s to confirm that you haven't broken the document. If you're feeling particularly ambitious, or you've made a large change, you should probably build the docs tree before submitting your change.

The docs team is grateful for any contributions. Not too long ago, I went through the FAQ and added question IDs to every entry lacking one. Despite the fact that I touched darn near every FAQ entry, my patch was accepted and committed within 48 hours.

In the last two months, we've looked at how to make some changes to vital FreeBSD systems. Next month we'll look at how you can submit your patches through the ever-popular send-pr command.

Michael W. Lucas


Read more Big Scary Daemons columns.

Discuss this article in the Operating Systems Forum.

Return to the BSD DevCenter.

Copyright © 2009 O'Reilly Media, Inc.