Web Site for Version 10.0 Manuals
- Why a separate web site for 10.0 manuals?
- This web site uses Forrest 0.7
- Updating the 10.0 Files
Why a separate web site for 10.0 manuals?
This web site hosts the 10.0 Derby documentation. The files that comprise the documentation are numerous (about 750), static, and take a while to build, so they were split out into a separate mini-site linked to by the main Derby web site. This page describes this site.
This web site uses Forrest 0.7
This web site uses Forrest 0.7. For an introduction to Derby's use of Forrest, see the Apache Derby Web Site writeup. This page explains enough so a committer can rebuild the 10.0 manuals if required.
If you haven't installed Forrest yet, install Forrest 0.7 on your local system. If you have never worked with Forrest before, generate a seed project, as described in the Apache Derby Web Site writeup, and play with it to get comfortable working with Forrest.
Updating the 10.0 Files
1. Check out the 10.0 manuals web site pages
Check the web site files out of the Subversion repository:
svn co https://svn.apache.org/repos/asf/db/derby/docs/branches/10.0
2. Modify files in the src tree
Source files for this site are under src/documentation/content/xdocs. The manuals are in the manuals subdirectory. Each file has an ihtml extension, which is deprecated, but still works in 0.7.
3. Build the site
After modifying files, you need to rebuild the site with the 'forrest site' command. Do this in the directory that is one level above the src and build directories.
4. Test the changes
There are a couple ways (at least) to review changes. The easiest way is to open build/site/index.html with your web browser. The Apache Derby Web Site writeup also describes how to start the Jetty webserver that is included in the Forrest distribution.
5. Commit changes to the src directory
Commit modified pages in the src tree only. The Derby web site also commits built pages, but this site does not. ASF guidelines now specify keeping web site pages under version control, so at some point the built pages for the 10.0 docs will likely be committed to svn and steps 6 and 7 below will be modified accordingly.
6. Package up the built pages
Tar up or zip up the forrest output to build/site.
7. Copy the built pages to people.apache.org
Use sync or scp to copy your package from step 7 to people.apache.org. Unpack it in /www/db.apache.org/derby/docs/10.0.
www.apache.org automatically syncs up with people.apache.org periodically.
Last updated April 20, 2006