1.2. Quick Start
Prev | Chapter 1. Overview | Next

## 1.2. 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.

1. Install the `textproc/docproj` package or port. This meta-port installs all of the software needed to edit and build FreeBSD documentation.

2. Install a local working copy of the documentation from a mirror of the FreeBSD repository in `~/doc` (see Chapter 3, The Working Copy).

   `%` `svn checkout https://`svn0.us-west.FreeBSD.org`/doc/head `~/doc``

3. 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 13, Editor Configuration.

4. Update the local working copy:

   `%` `svn up `~/doc``

5. 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.

6. 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.

7. 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.

8. When changes are complete and tested, generate a “diff file”:

   `%` `cd /usr/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.

9. Submit the diff file using the web-based Problem Report system or with send-pr(1). If using the web form, enter a synopsis of [patch] `short description of problem`. Select the category `docs` and the class `doc-bug`. In the body of the message, enter a short description of the changes and any important details about them. Use the [ Browse... ] button to attach the `.diff.txt`.

Prev | Up | Next
Chapter 1. Overview | Home | Chapter 2. Tools

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.