[Pig Wiki] Trivial Update of "HowToDocumentation" by CorinneC

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Pig Wiki" for change notification.

The following page has been changed by CorinneC:
http://wiki.apache.org/pig/HowToDocumentation

New page:
= How to Work with the Pig Documentation =

== Forrest Set Up ==

Pig's official documentation is authored using [http://forrest.apache.org/index.html Forrest]. To commit documentation changes you must have Forrest installed and the forrest executable on your $PATH. Note that the current version of Forrest (0.8) does not work properly with Java 6, use Java 5 instead (make sure JAVA_HOME points to Java 5).

Documentation is of two types:
 
1. The website (maintained separately in subversion, in the site branch) 

2. The user documentation, versioned with releases (maintained separately in subversion, in the trunk )


== Forrest Files ==

Forrest includes these files that you can modify for the Pig website docs or Pig user docs:
   * forrest.properties – add plugins and set other properties here
   * skinconf.xml – add CSS style changes and set other switches here
   * site.xml – add or remove *.xml docs files here; controls which documents appear in the menu
   * tab.xml – add or remove tabs here; controls which tabs on each page


== Updating the Pig Website Documentation ==

Checkout the site branch: https://svn.apache.org/repos/asf/hadoop/pig/site/

To edit site doc files:
   * Change to the directory that contains the XML files: site/author/src/documentation/content/xdocs.
   * Edit the existing files or add new files

To view your edits using forrest:
   * Change to the directory that includes the forrest.properties file: site/author
   * Run the "forrest run" command and leave it running ….
   * Open a browser and enter http://localhost:8888/ - the /xdocs/index.xml page is displayed as index.html
   * Make more changes to the XML doc files and then refresh the browser display to see your changes.

To build the site doc using forrest:
   * Change to the directory that includes the forrest.properties file: site/author
   * Run the "forrest" command (if the build fails due to broken links, the *.html/*.pdf files will still be generated).
   * To check the *.html and *.pdf output, move to this output directory: /publish


== Updating the Pig User Documentation ==

Checkout the trunk or relevant branch: http://svn.apache.org/repos/asf/hadoop/pig/trunk

To edit the user doc files:
   * Change to the directory that contains the XML files: /trunk/src/docs/src/documentation/content/xdocs
   * Edit the existing files or add new files

To view your edits using forrest:
   * Change to the directory that includes the forrest.properties file: trunk/src/docs/src/documentation/content/xdocs 
   * Run the "forrest run" command and leave it running ….
   * Open a browser and enter http://localhost:8888/ - the /xdocs/index.xml page is displayed as index.html
   * Make more changes to the XML doc files and then refresh the browser display to see your changes.

To build the user docs using forrest:
   * Change to the directory that includes the forrest.properties file: /trunk/scr/docs
   * Run the "forrest" command (if the build fails due to broken links, the *.html/*.pdf files will still be generated).
   * To check the *.html and *.pdf output, move to this output directory: /trunk/scr/docs/build/site

To build the user docs using ant:
   * Change to the top directory of your structure: /trunk
   * Run the "ant docs" command
   * To check the output, change to this directory: /trunk/docs