BSD DevCenter
oreilly.comSafari Books Online.Conferences.


Changing FreeBSD Documentation
Pages: 1, 2

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.

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

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

<para>You can find full information in the <ulink
entry on mailing-lists.</ulink></para>

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:

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

<para>Put your answer here</para>

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.

Sponsored by: