Chapter 1. Overview
Prev		Next

Chapter 1. Overview

Table of Contents

1.1. Quick Start
1.2. The FreeBSD Documentation Set

Welcome to the FreeBSD Documentation Project (FDP). Quality documentation is crucial to the success of FreeBSD, and we value your contributions very highly.

This document describes how the FDP is organized, how to write and submit documentation, and how to effectively use the available tools.

Everyone is welcome to contribute to the FDP. Willingness to contribute is the only membership requirement.

This primer shows how to:

Identify which parts of FreeBSD are maintained by the FDP.
Install the required documentation tools and files.
Make changes to the documentation.
Submit changes back for review and inclusion in the FreeBSD documentation.

1.1. Quick Start

Some preparatory steps must be taken before editing the FreeBSD documentation. First, subscribe to the FreeBSD documentation project mailing list. Some team members also interact on the #bsddocs IRC channel on EFnet. These people can help with questions or problems involving the documentation.

Install the textproc/docproj meta-package and Subversion. This meta-package installs all of the software needed to edit and build FreeBSD documentation. The Subversion package is needed to obtain a working copy of the documentation and generate patches with.
```
# pkg install docproj subversion
```
Optional: to generate PDF documentation, install the textproc/fop package as it is not installed by default by textproc/docproj.
```
# pkg install fop
```
Install a local working copy of the documentation from the FreeBSD repository in ~/doc (see Chapter 3, The Working Copy).
```
% svn checkout https://svn.FreeBSD.org/doc/head ~/doc
```
Configure the text editor:
- Word wrap set to 70 characters.
- Tab stops set to 2.
- Replace each group of 8 leading spaces with a single tab.
Specific editor configurations are listed in Chapter 15, Editor Configuration.
Update the local working copy:
```
% svn up ~/doc
```
Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input.
References to tag and entity usage can be found in Chapter 8, XHTML Markup and Chapter 9, DocBook Markup.
After editing, check for problems by running:
```
% igor -R filename.xml | less -RS
```
Review the output and edit the file to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved.
Always build-test changes before submitting them. Running make in the top-level directory of the documentation being edited will generate that documentation in split HTML format. For example, to build the English version of the Handbook in HTML, run make in the en_US.ISO8859-1/books/handbook/ directory.
When changes are complete and tested, generate a “diff file”:
```
% cd ~/doc
% svn diff > bsdinstall.diff.txt
```
Give the diff file a descriptive name. In the example above, changes have been made to the bsdinstall portion of the Handbook.
Submit the diff file using the web-based Problem Report system. If using the web form, enter a Summary of [patch] short description of problem. Select the Component Documentation. In the Description field, enter a short description of the changes and any important details about them. Use the [ Add an attachment ] button to attach the diff file. Finally, use the [ Submit Bug ] button to submit your diff to the problem report system.

Prev		Next
4. Acknowledgments	Home	1.2. The FreeBSD Documentation Set