Overview
Welcome to the FreeBSD Documentation Project. Good quality
documentation is very important to the success of FreeBSD, and the
FreeBSD Documentation Project (FDP) is how a lot of that
documentation is produced. Your contributions are very
valuable.
This document's main purpose is to clearly explain
how the FDP is organized, how to
write and submit documentation to the FDP, and
how to effectively use the tools available to you when
writing documentation.
Membership
Everyone is welcome to join the FDP. There is no minimum
membership requirement, no quota of documentation you need to
produce per month. All you need to do is subscribe to the
&a.doc;.
After you have finished reading this document you
should:
Know which documentation is maintained by the FDP.
Be able to read and understand the XML source code for
the documentation maintained by the FDP.
Be able to make changes to the documentation.
Be able to submit your changes back for review and
eventual inclusion in the FreeBSD documentation.
The FreeBSD Documentation Set
The FDP is responsible for four categories of FreeBSD
documentation.
Manual pages
The English language system manual pages are not
written by the FDP, as they are part of the base system.
However, the FDP can (and has) re-worded parts of existing
manual pages to make them clearer, or to correct
inaccuracies.
The translation teams are responsible for translating
the system manual pages into different languages. These
translations are kept within the FDP.
FAQ
The FAQ aims to address (in short question and answer
format) questions that are asked, or should be asked, on
the various mailing lists and newsgroups devoted to
FreeBSD. The format does not permit long and
comprehensive answers.
Handbook
The Handbook aims to be the comprehensive on-line
resource and reference for FreeBSD users.
Web site
This is the main FreeBSD presence on the World Wide
Web, visible at http://www.FreeBSD.org/
and many mirrors around the world. The web site is many
people's first exposure to FreeBSD.
The documentation for the web site, &os; Handbook, and FAQ
are available in the doc/ Subversion
repository, which is located at
svn://svn.FreeBSD.org/doc/.
Manual pages are available in the src/
Subversion repository, which is available at
svn://svn.FreeBSD.org/base/.
This means that the logs of changes to these
files are visible to anyone, and anyone can use
svn to view the changes.
In addition, many people have written tutorials or other web
sites relating to FreeBSD. Some of these are stored in the
Subversion repository as well (where the author has agreed to
this). In other cases the author has decided to keep his
documentation separate from the main FreeBSD repository. The
FDP endeavors to provide links to as much of this documentation
as possible.
Before You Start
This document assumes that you already know:
How to maintain an up-to-date local copy of the FreeBSD
documentation by maintaining a local copy of the FreeBSD
Subversion repository using
svn.
How to download and install new software using either
the FreeBSD Ports system or &man.pkg.add.1;.
Quick Start
If you just want to get going, and feel confident you can
pick things up as you go along, follow these
instructions.
Install the
textproc/docproj
meta-port.
&prompt.root; cd /usr/ports/textproc/docproj
&prompt.root; make JADETEX=no install
Get a local copy of the FreeBSD doc
tree using svn.
If network bandwidth or local drive space is a concern,
then at minimum, the head/share and
head/language/share
directories will need to be checked out. For
example:
&prompt.user; mkdir -p head/share
&prompt.user; mkdir -p head/en_US.ISO8859-1/share
&prompt.user; svn checkout svn://svn.FreeBSD.org/doc/head/share head/share
&prompt.user; svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share
If you have plenty of disk space then you could check
out everything.
&prompt.user; svn checkout svn://svn.FreeBSD.org/doc/head head
If you are preparing a change to an existing book or
article, check it out of the repository as necessary. If
you are planning on contributing a new book or article then
use an existing one as a guide.
For example, if you want to contribute a new article
about setting up a VPN between FreeBSD and Windows 2000 you
might do the following.
Check out the articles
directory.
&prompt.user; svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/articles
Copy an existing article to use as a template. In
this case, you have decided that your new article
belongs in a directory called
vpn-w2k.
&prompt.user; cd head/en_US.ISO8859-1/articles
&prompt.user; svn export committers-guide vpn-w2k
If you wanted to edit an existing document, such as the
FAQ, which is in
head/en_US.ISO8859-1/books/faq you
would check it out of the repository like this.
&prompt.user; svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/books/faq
Edit the .xml files using your
editor of choice.
Test the markup using the lint
target. This will quickly find any errors in the document
without actually performing the time-consuming
transformation.
&prompt.user; make lint
When you are ready to actually build the document, you
may specify a single format or a list of formats in the
FORMATS variable. Currently,
html, html-split,
txt, ps,
pdf, and rtf are
supported. The most up to date list of supported formats is
listed at the top of the
head/share/mk/doc.docbook.mk file.
Make sure to use quotes around the list of formats when you
build more than one format with a single command.
For example, to convert the document to
html only, you would use:
&prompt.user; make FORMATS=html
But when you want to convert the document to both
html and txt format,
you could use either two separate &man.make.1; runs,
with:
&prompt.user; make FORMATS=html
&prompt.user; make FORMATS=txt
or, you can do it in one command:
&prompt.user; make FORMATS="html txt"
Submit your changes using &man.send-pr.1;.