Introduction

Most of the time when people update their system, they only update the source and ports trees, and forget about the documentation. The documentation (the handbook, FAQ, tutorials, etc.) can also be updated (man pages are part of the source tree).

Getting Ready

As with a source or ports update, you will need to have cvsup(1) installed. If you don't currently have it installed, you can either use the port to install it, or you can install the package.

To install the port:

# cd /usr/ports/net/cvsup-bin && make install clean

To install the package (assuming you're online):

# pkg_add -r cvsup-bin

Many tools are required to build the actual documentation from its source. Luckily, there is a port that will install everything you need:

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

The above will install all of the tools required to build the documentation in plain text and HTML format. If you want to produce PostScript or PDF files, replace the no with yes in the command above. Keep in mind this will install JadeTeX, which requires TeX. TeX uses a ton of disk space and will take a while to download if you're on a modem, so you might want to think twice about installing it.

Configuration and Build

The first thing to do is cvsup the docs tree. I started with /usr/share/examples/cvsup/doc-supfile. The only thing I changed was the server. I used a mirror near me:

*default host=cvsup.fr.FreeBSD.org

The rest of the file doesn't have to be changed.

Most of us don't need the documentation for languages we don't speak. You can refuse collections by using the /usr/sup/refuse file. If you only want to get the English versions of the documentation, put the following in /usr/sup/refuse:

doc/de_DE.ISO_8859-1
doc/es_ES.ISO_8859-1
doc/fr_FR.ISO_8859-1
doc/ja_JP.eucJP
doc/nl_NL.ISO_8859-1
doc/ru_RU.KOI8-R
doc/zh_TW.Big5

The above will make cvsup(1) ignore everything but the English documentation (en_US.ISO_8859-1). For more information on refuse files, read the cvsup(1) man page.

Now we're ready to cvsup the documentation. As root, do the following:

# cvsup -g -L2 doc-supfile

Everything that's pulled in by cvsup(1) will be saved in /usr/doc. Now that we have the files we need, there's one more thing that we need to do which will come in handy before building the docs. Add the following to your /etc/make.conf:

DOC_LANG=	en_US.ISO_8859-1

Now, let's assume that you also want to build the French documentation. First you'd remove doc/fr_FR.ISO_8859-1 from /usr/sup/refuse and run cvsup(1) again. Then you'd change the line in /etc/make.conf to look like this:

DOC_LANG=	en_US.ISO_8859-1 fr_FR.ISO_8859-1

Now we're ready to build the docs. To start the build, do the following:

# cd /usr/doc && make all install

The documentation will now be installed in /usr/share/doc.

Conclusion

Keeping the handbook and FAQ up-to-date is quite easy and often useful, so it would be a shame to ignore it. For more information about FreeBSD documentation, you can consult the FreeBSD Documentation Project's web site.

- Marc Fonvieille

Return to Issue 1, May 2001