m0n0wall Users Guide Editors Guidelines

Contents:

• How You Can Help
• Discussion Group
• Documentation Test Bed
• CVS
• Editing
• Compiling
• Committing
• Results
• Development Statistics

How You Can Help

Wondering how you can contribute? Check out the m0n0wall Documentation Project's wish list.

Discussion Group

Discussions about the m0n0wall Users Guide take place on the m0n0wall-doc email list.

• To subscribe, send an empty message to m0n0wall-doc-subscribe@lists.m0n0.ch
• To unsubscribe, send an empty message to m0n0wall-doc-unsubscribe@lists.m0n0.ch
• To post a message, send mail to m0n0wall-doc@lists.m0n0.ch

Documentation Test Bed

The m0n0wall Documentation Project has made a wiki available as a documentation test bed. The official source of documentation will remain the Users Guide, however we encourage people to contribute to the wiki. Changes on the wiki will be incorporated into the DocBook Users Guide after appropriate formatting, review, and editing.

The official m0n0wall wiki can be found at http://wiki.m0n0.ch.

CVS

The m0n0wall Users Guide is maintained in a CVS repository. Write privileges to the CVS repository are granted by Manuel. Anonymous access is available at

:pserver:anonymous@m0n0.ch:/m0n0wall

You can check out a copy of the files to your machine with this sequence of commands:

mkdir m0n0doc
cd m0n0doc
cvs -d :pserver:anonymous@m0n0.ch:/m0n0wall login
cvs -d :pserver:anonymous@m0n0.ch:/m0n0wall checkout doc

If you want to see a copy of the documentation DocBook XML sources but do not want to configure CVS, you can download a tgz of the documentation.

Editing

To edit the XML files, you can either use your favorite text editor to directly edit the files, in which case you must be familiar with the DocBook XML tags, or you can use an XML editor, such as the XMLmind XML Editor Standard Edition, which is free for personal or corporate internal use.

If you aren't comfortable with editing in docbook format, you can also submit documentation in plain text, HTML, or other common formats and the editor will convert to docbook.

If you are interested in learning DocBook, check out the following:

DocBook XML 4.2
Official DocBook home page
DocBook: The Definitive Guide

Compiling

After editing any of the XML files, you should compile the HTML files to make sure they still look reasonable. The Makefile in this directory is set up to create three different types of output:

• A directory (html.d) of html files, one for each chapter and section ("make html_dir" or just "make").
• A single html file (m0n0doc.html) containing the entire manual ("make html_file").
• A PDF file (m0n0doc.pdf) containing the entire manual ("make pdf_file").

You may need to download and install some additional software in order to compile the XML files into HTML or PDF. See the Makefile for more information about what tools are required.

Committing Changes

There are a limited number of people with commit privileges to the CVS repository. If you do not have commit privileges, email your changes to the editor, Chris Buechler.

If you do have commit privileges, please make sure of the following before committing your changes:

• Contributor attributions are up to date (if someone sends you a file to commit, make sure they are properly credited in the Contributors section).
• book.xml is up to date (if any chapter files have been added or renamed).
• "make html_dir" produces a correct set of html files (this is the primary output format, used on the m0n0wall web site).

Results

There is a nightly script that runs at 02:00 CEST (UTC + 2 hours) to convert the current (most recently committed) XML files into a set of HTML files for display on the m0n0wall web site at http://m0n0.ch/wall/docbook.

Development Statistics

StatCVS statistics on the m0n0wall documentation CVS repository.