FreeBSD Documentation Project Primer for New Contributors
Prev	Chapter 1 Overview	Next

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

# cd /usr/ports/textproc/docproj
# 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:
```
% mkdir -p head/share
% mkdir -p head/en_US.ISO8859-1/share
% svn checkout svn://svn.FreeBSD.org/doc/head/share head/share
% 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.
```
% 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.
1. Check out the articles directory.
```
% svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/articles
```
2. 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.
```
% cd head/en_US.ISO8859-1/articles
% 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.
```
% 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.
```
% 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:
```
% make FORMATS=html
```
But when you want to convert the document to both html and txt format, you could use either two separate make(1) runs, with:
```
% make FORMATS=html
% make FORMATS=txt
```
or, you can do it in one command:
```
% make FORMATS="html txt"
```
Submit your changes using send-pr(1).

Prev	Home	Next
Before You Start	Up	Tools