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. Either use CVSup in checkout mode to do this, or get a full copy of the CVS repository locally.

If you have the CVS repository locally then as a minimum you will need to checkout the doc/share, and doc/en_US.ISO8859-1/share directories.
```
% cvs checkout doc/share
% cvs checkout doc/en_US.ISO8859-1/share
```
If you have plenty of disk space then you could check out everything.
```
% cvs checkout doc
```
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.
```
% cvs checkout doc/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 doc/en_US.ISO8859-1/articles
% cp -r committers-guide vpn-w2k
```
If you wanted to edit an existing document, such as the FAQ, which is in doc/en_US.ISO8859-1/books/faq you would check it out of the repository like this.
```
% cvs checkout doc/en_US.ISO8859-1/books/faq
```
Edit the .sgml 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 doc/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