Apache Derby Web Site

Forrest in a Nutshell
Testing New Pages for the Derby Site
- Create a Forrest seed site
- Add your new page to the seed site
Updating the Apache Derby web site

The Derby incubator project web site at http://incubator.apache.org/derby uses Forrest. Page source and built pages are managed in the Apache incubator Subversion repository. This page introduces Forrest, suggests a way to test new pages using a local Forrest site, and provides information for committers on how to update the Derby web site itself.

Forrest in a Nutshell

Apache Forrest is an XML documentation framework that is used for generating static/dynamic web sites. For many details, see forrest.apache.org.

This web page walks you through using two Forrest commands: 'forrest site' and 'forrest run'.

The 'forrest site' command consumes the source input files in the src tree of the project hierarchy and spits out a static site composed of HTML pages in the build tree of the project hierarchy.

The 'forrest run' command starts up the Jetty web server that is included in the Forrest distribution on port 8888.

Warning

The Derby web site uses Forrest 0.5.1, which is no longer the current official release. Until the Derby web site has been upgraded to use Forrest 0.6, use Forrest 0.5.1 to build it.

Testing New Pages for the Derby Site

The information in this section is intended for anyone who wants to develop content for the Derby web site (in other words, for both committers and non-committers).

It takes 20-40 minutes to build the Derby web site, depending on the machine and the scope of the change. By comparison, the seed site used for testing the Papers tab took only 25 seconds to build. So, it is much easier to integrate new pages by first testing them outside the Derby web site source tree.

Create a Forrest seed site

To get started:

Install Forrest 0.5.1.
After it is installed, cd into the directory of your choice and enter 'forrest seed' to initialize a new project.
Enter 'forrest site' to build the site.
Enter 'forrest run' to start the jetty server that is bundled with Forrest.
Point your browser at localhost:8888.
Look at the sample pages that are included in the seed site.

Add your new page to the seed site

Next, incorporate the new page(s) into the newly-created seed site:

If you have an HTML file, perhaps named your_file.html, one option is to copy it to a file named your_file.ihtml. Forrest will convert it into a new your_file.html file in the build tree -- and you may or may not like how Forrest formatted it. The Derby JDBC Implementation Notes paper is an example of an HTML document that is stored in the project source tree as an ihtml file. Likewise, all of the Derby document files are stored as ihtml files.
You can also create an XML file for it that uses the Forrest DTD. The Derby Engine Architecture Overview is an example. Also, the site you just seeded provides examples.

If you have a file that is ascii text, one option is to create an XML file and include it in a CDATA block, as shown below:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" 
    "http://apache.org/forrest/dtd/document-v12.dtd">

<document>
 <header>
   <title>The Title of your Document</title>
 </header>

 <body>

    <p>An introductory blurb for your document.</p>

    <source><![CDATA[
    Put the contents of your text file here ]]></source>

 </body>
</document>

The seed site includes a "Samples" tab. After you create the file for Forrest to ingest, update the src/documentation/content/xdocs/site.xml file to include your new page in that tab, as shown below:
```
<samples label="Samples" href="samples/" tab="samples">
  <your_tag label="Your page" href="your_file.html" description="Your test page" />
```
Notice that at this point you need to refer to the file as your_file.html even if the source file is your_file.ihtml or your_file.xml.
Execute 'forrest site' to rebuild your site.
Restart the jetty server ('forrest run').
Do you like what Forrest did? If you don't, go back and tweak your source file.

When you're satisfied with how your new page looks on your seed site, then it is ready to be added to the Derby web site by a Derby committer.

Updating the Apache Derby web site

The information in this section is intended for committers who need to add a page to the Derby web site or modify an existing page.

1. Install Forrest on your machine

If you haven't installed Forrest yet, install Forrest 0.5.1 on your local system. Then generate a seed project, as described in the previous section, and play with it to get comfortable working with Forrest.

2. Check out the Derby web site pages

Check the Derby web site files out of the Subversion repository:

svn co https://svn.apache.org/repos/asf/incubator/derby/site/trunk

3. Modify files in the src tree

Source files are in the places listed below:

Source File Location	File types	Comment
src/documentation/content/xdocs	Source files in formats Forrest can consume (.xml and .ihtml).	Forrest ingests these files, adds navigation and decorations, and outputs them as .html files to build/site and build/app.
src/documentation/content	Source HTML files you don't want Forrest to touch.	Forrest copies these files without modifying them to build/site.
src/documentation/content/binaries	Binary files, such as .tar.gz and .ZIP.	Forrest copies these files without modifying them to build/site/binaries.

What might be counter intuitive is the directory structure is different for the src and build trees. Links in source files need to point to the name and the location of the target file in the build tree.

Two files in src/documentation/content/xdocs don't get output to the build tree, but control the information and links in the resulting navigation bar:

tabs.xml: sets up the tabs for the web site. As of this writing there are three: Home, Manuals, and Papers. Adding a tab is easy, but it also requires updates to the site.xml file.
site.xml: contains a site map for files on the site. If you add or delete a file you must update site.xml, which can be tricky. If you haven't updated it before, it might be a good idea to ask somebody already familiar with Forrest to help you the first time. You might notice entries for the Manuals tab that don't include a label; for example, below is the first entries for the Getting Started guide:
```
     <getstart label="Getting Started" href="getstart/">
         <toc label="Table of Contents" href="gspr02.html"
             description="Table of Contents" />
         <index label="Index" href="gspr40.html" description="Index" />
         <gspr href="gspr.html"/>
         <gspr03 href="gspr03.html"/>
         <gspr04 href="gspr04.html"/>
```
The tab for the built site lists the "Table of Contents" and "Index" labels, but not the title and other pages. Including the pages in the site.xml keeps them associated with the tab. Without that association, Forrest builds a remarkable left-hand navigation tab that includes the entire site contents. It's kind of exciting to see this side effect once, but then it gets tiresome.

4. 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.

Because the Derby manuals are included in the web site, 'forrest site' takes a while, anywhere from 20 - 40 minutes, depending on the machine.

5. Test the changes

Test your changes by starting the Jetty webserver that is included in the Forrest distribution:

forrest run

After it starts, point your browser at localhost:8888 and review the new or modified pages.

The breadcrumb trail will be different. Instead of this:

apache > incubator > derby

You'll see this with your local Jetty server:

apache > incubator

This is alright, if somewhat confusing. The skinconf.xml specifies the base links for the trail, then Javascript adds extra breadcrumbs for each directory after the domain. Extra breadcrumbs won't be added when the site is viewed locally.

6. Commit changes to the src and build/site directories

You need to check in the pages that were modified in both the src and build/site trees. The 'forrest site' command also outputs build/webapp and build/tmp directories, but they aren't checked into the Subversion repository.

If you add / delete a file, you must 'svn add' or 'svn delete' it in src, build/site, and build/webapp. Do this after 'forrest site' has been run but before committing changes into Subversion.

When you're ready to commit, one way is to enter the command shown below from the directory that is one level above the src and build directories:

svn commit --message "here is my commit message" src build/site

7. Post a request to derby-dev to make the changes visible

Derby committers don't have access to the filesystem hosting the actual web site, so can't make web site changes visible (for details, see this email thread). Post a request to derby-dev@db.apache.org, requesting an 'svn update' for the web site.

8. Considering a quick fix to the build tree?

If you modify a file in the build/site tree, be sure to also change the source file in the src tree. Otherwise, the next 'forrest site' / 'svn commit' will overwrite your changes to the build tree.

Last updated November 11, 2004


Copyright © 2004 Apache Software Foundation All rights reserved.