-------------------------------------
     | How To Contribute Docs to Beehive |
     -------------------------------------

Introduction
------------

Beehive documentation is created using Apache Forrest--a tool for
building web sites from XML source docs.  

To contribute documentation you must first install Forrest on 
your local machine.  For installation details see 

  /beehive/trunk/BUILDING.txt.

You should also install some form of XML validation tool before 
contributing docs.  The XML source files which you contribute must
be valid for the Beehive source to build.


Developing Documentation
------------------------

Beehive documentation is written in the form of Forrest XML source
files, located in the following directory:

  /docs/forrest/src/documentation/content/xdocs

These XML source files are transformed by the Forrest tool into 
an HTML web site.  Forrest XML contains many idiomatic shorthand 
expressions for referencing common HTML elements, esp. HTML links.
For details on this shorthand see 

  http://forrest.apache.org/docs/linking.html

The basic development cycle for Beehive documentation runs as follows:

(1) Turn on the Jetty Server

The Jetty server is a web server provided by Forrest used to view/test
the Forrest docs while they are development.

To turn on the Jetty Server, run the following Ant command:

  docs/forrest>ant run

Once the Jetty Server has been turned on, it is automatically aware of the
Forrest XML files in

  /docs/forrest/src/documentation/content/xdocs

Any changes you make to these XML files, will automatically be reflected 
in the HTML served up the Jetty server.

(2) Edit the Forrest XML source

Make the desired changes to the Forrest XML source files.
Your changes should result in valid XML documents according to
the appropriate Forrest DTDs E.g., 

  http://forrest.apache.org/dtd/document-v20.dtd

This where having an XML validation tool is important:
if you checkin invalid Forrest XML files, you will break
the Beehive build!

(3) View your changes on the Jetty Browser
------------------------------------------

Once your have produced valid Forrest XML source files,
you can view the HTML produced by visiting:

  http://localhost:8888/index.html

If you are satisfied with the resulting docs, 
you are ready to checkin the XML source files to Beehive.