Author: steveh
Date: Wed Mar 23 09:49:58 2005
New Revision: 158808
URL: http://svn.apache.org/viewcvs?view=rev&rev=158808
Log:
Describes how to develop and contribute docs to Beehive.
Added:
incubator/beehive/trunk/docs/how_to_contribute_docs.txt (with props)
Added: incubator/beehive/trunk/docs/how_to_contribute_docs.txt
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/how_to_contribute_docs.txt?view=auto&rev=158808
==============================================================================
--- incubator/beehive/trunk/docs/how_to_contribute_docs.txt (added)
+++ incubator/beehive/trunk/docs/how_to_contribute_docs.txt Wed Mar 23 09:49:58
2005
@@ -0,0 +1,77 @@
+
+ -------------------------------------
+ | 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.
\ No newline at end of file
Propchange: incubator/beehive/trunk/docs/how_to_contribute_docs.txt
------------------------------------------------------------------------------
svn:eol-style = native
