Here we describe the steps contributors must take before making changes to the FDP. New contributors will interact with other members of the FreeBSD Documentation Team, which can assist in learning to use XML and the suggestions in Section 11.3, “Style Guide”. If a new user contributes regularly, a Documentation Team member may be assigned as a mentor to guide the user through the process from contributor to documentation committer.
Subscribe to the FreeBSD documentation project mailing list. Some members of the mailing
list also interact on the #bsddocs
IRC channel on EFnet.
Install the
textproc/docproj
package or port. This meta-port installs all of the
utilities needed by the FDP.
Install a local working copy of the documentation
from a mirror of the FreeBSD repository. For the fastest
download, pick the nearest mirror from the list of Subversion
mirror sites. If /usr/doc
already exists, move
or delete it first to prevent file conflicts.
%
svn checkout https://svn0.us-west.FreeBSD.org
/doc/head /usr/doc
Before making any documentation edits, configure your editor to conform to FDP standards. How to do so varies by editor. Some editor configurations are listed in Chapter 11, Writing Style. The editor should be configured as follows:
Word wrap set to 70 characters.
Tab stops set to 2.
Replace each group of 8 leading spaces with a single tab.
Locate the file to edit. Run
svn up
within the local working copy to
make sure that it is up to date. Before making major
changes to a file, discuss the proposed changes with the
FreeBSD documentation project mailing list.
When making edits, determine which tags and entities are needed to achieve the desired formatting. One way to learn is to compare some text in the HTML formatted version of the document to the tags which surround the text or the entities that represent that text in the XML file. References to the commonly used tags and entities can be found in Chapter 4, XHTML Markup and Chapter 5, DocBook Markup.
After edits are complete, check for problems by running:
%
igor -R filename.xml | less -RS
Review the output and edit the file to fix any listed tab errors, spelling mistakes, and improper grammar. Save the changes and rerun this command to find any remaining problems. Repeat until all of the errors that you deem fixable are resolved. If you get stuck trying to fix errors, ask for assistance on the FreeBSD documentation project mailing list.
Always build-test changes before
submitting them. By default, typing
make
in the top-level directory of
the type of documentation being edited will generate that
documentation in split HTML format. For example, to build
the English version of the Handbook, type
make
in the
en_US.ISO8859-1/books/handbook/
directory. This step is necessary to make sure that the
edits do not break the build.
In order to build the output in other formats, other
make targets are defined in
head/share/mk/doc.docbook.mk
. Use
quotes around the list of formats when building more than
one format with a single command.
For example, to convert the document to both
.html
and .txt
, use
this command:
%
make FORMATS="html txt"
Once these steps are successfully completed, generate
a “diff file” of the changes. While in
/usr/doc
, run this
command, replacing bsdinstall
with the name of the directory containing the
edits:
%
svn diff > bsdinstall
.diff.txt
Submit the diff file using the web-based Problem
Report system or with send-pr(1). If using
the web form, input a synopsis of [patch]
short description of
problem
. Select the category
docs
and the class
doc-bug
. The body of the message
should contain a short description of the edits and any
important discussion points. Use the
button to
attach the .diff.txt
file and enter
the captcha phrase.
It is important to remember that the FDP is comprised of volunteers who review edits in their spare time and who live in different time zones around the globe. It takes time to review edits and to either commit them or respond if additional edits are required. If you do not receive a response in a reasonable amount of time, send a follow-up email to the FreeBSD documentation project mailing list and ask if anyone has had a chance to review the patch or if additional information is required.
This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/
For questions about FreeBSD, read the
documentation before
contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.