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

## 1.2. Quick Start

Some preparatory steps must be taken before editing the FreeBSD documentation. 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 12.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.

1. Subscribe to the FreeBSD documentation project mailing list. Some mailing list members also interact on the `#bsddocs` IRC channel on EFnet.

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

3. Install a local working copy of the documentation from a mirror of the FreeBSD repository. 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``

   For the fastest download, pick the nearest mirror from the list of Subversion mirror sites.

4. The editor to be used 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.

   Some specific editor configurations are listed in Chapter 12, Writing Style.

5. Run `svn up` to update the local working copy. Edit the documentation files that need changes. Before making major changes to a file, ask for input on the FreeBSD documentation project mailing list.

   To learn which tags and entities are needed to achieve the desired formatting, compare some text in the HTML formatted version of the document to the text, tags, and entities in the XML file. References to the commonly used tags and entities 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 that are fixable are resolved. If an error seems unsolvable, ask for assistance on the FreeBSD documentation project mailing list.

7. 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 in HTML, type `make` in the `en_US.ISO8859-1/books/handbook/` directory. This step is necessary to make sure that edits do not break the build.

8. After successfully completing the previous steps, generate a “diff file” of the changes:

   `%` `cd /usr/doc` `%` `svn diff > `bsdinstall`.diff.txt`

   Give the diff file a name that describes the contents. 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, 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 [ Browse... ] button to attach the `.diff.txt`.

   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 can take some time to review changes. If a response is not received 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.

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