HowToDocument

Forrest Set Up

Pig's official documentation is authored using 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:

The website documentation (maintained separately in subversion, in the site branch)

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:

/src/docs/forrest.properties – add plugins and set other properties here
/src/docs/src/documentation/skinconf.xml – add CSS style changes, change logos, and set other switches here
/src/docs/src/documentation//content/xdocs/site.xml – add or remove *.xml docs files here; controls which documents appear in the menu
/src/docs/src/documentation//content/xdocs/tabs.xml – add or remove tabs here; controls which tabs appear on each page

Note: Some *.xml files in the Pig user docs require the Forrest simplified Docbook plugin. In the forrest.properties file, the plugin entry has been updated to include the Docbook plugin: project.required.plugins=org.apache.forrest.plugin.output.pdf,org.apache.forrest.plugin.input.simplifiedDocbook

Updating the Pig Website Documentation

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

To edit website doc files:

Change to the directory that includes 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 create a local doc build:

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 and *.pdf ouptut will still be generated).
To check the *.html and *.pdf output, move to this output directory: /site/author/build/site

Updating the Pig User Documentation

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

To edit the user doc files:

Change to the directory that includes the *.xml files: /trunk/src/docs/src/documentation/content/xdocs
Edit the existing files or add new files