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.

1. Install the `textproc/docproj` meta-port.

       # cd /usr/ports/textproc/docproj
       # make JADETEX=no install

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

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

4. Edit the `.sgml` files using your editor of choice.

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

6. Submit your changes using send-pr(1).

Prev | Home | Next
Before You Start | Up | Tools