1.3. Quick Start
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 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 https://svn0.us-east.FreeBSD.org/doc/head/share head/share % svn checkout https://svn0.us-east.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 https://svn0.us-east.FreeBSD.org/doc/head head

    Note:

    svn0.us-east.FreeBSD.org is a public SVN server. Select the closest mirror and verify the mirror server certificate from the list of Subversion mirror sites.

  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.

      % svn checkout https://svn0.us-east.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 https://svn0.us-east.FreeBSD.org/doc/head/en_US.ISO8859-1/books/faq

  4. Edit the .xml 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 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"

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

Prev Up Next
1.2. Before You Start Home Chapter 2. Tools

This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.

For questions about this documentation, e-mail <doc@FreeBSD.org>.