You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by jt...@apache.org on 2006/10/18 05:10:35 UTC
svn commit: r465131 - in /db/derby/site/trunk:
build/site/papers/derby_web.html
src/documentation/content/xdocs/papers/derby_web.xml
Author: jta
Date: Tue Oct 17 20:10:31 2006
New Revision: 465131
URL: http://svn.apache.org/viewvc?view=rev&rev=465131
Log:
Updated instructions for building the Derby web site:
1) Linked to the Forrest installation instructions
2) Brought the section describing the source directory structure up to date
3) Added a (small) section on how to create a patch
3) Included miscellaneous clarifications
Modified:
db/derby/site/trunk/build/site/papers/derby_web.html
db/derby/site/trunk/src/documentation/content/xdocs/papers/derby_web.xml
Modified: db/derby/site/trunk/build/site/papers/derby_web.html
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/build/site/papers/derby_web.html?view=diff&rev=465131&r1=465130&r2=465131
==============================================================================
--- db/derby/site/trunk/build/site/papers/derby_web.html (original)
+++ db/derby/site/trunk/build/site/papers/derby_web.html Tue Oct 17 20:10:31 2006
@@ -162,13 +162,16 @@
<a href="#odd_diffs">6. Odd diffs under build/site/skin and build/site/papers explained (sort of) </a>
</li>
<li>
-<a href="#7.+Commit+changes+to+the+src+and+build%2Fsite+directories">7. Commit changes to the src and build/site directories</a>
+<a href="#7.+Create+a+patch">7. Create a patch</a>
</li>
<li>
-<a href="#8.+Make+web+site+changes+visible">8. Make web site changes visible</a>
+<a href="#8.+Commit+changes+to+the+src+and+build%2Fsite+directories">8. Commit changes to the src and build/site directories</a>
</li>
<li>
-<a href="#9.+Considering+a+quick+fix+to+the+build+tree%3F">9. Considering a quick fix to the build tree?</a>
+<a href="#9.+Make+web+site+changes+visible">9. Make web site changes visible</a>
+</li>
+<li>
+<a href="#10.+Considering+a+quick+fix+to+the+build+tree%3F">10. Considering a quick fix to the build tree?</a>
</li>
</ul>
</li>
@@ -183,7 +186,7 @@
uses
<a class="external" href="http://forrest.apache.org">Forrest</a>.
Page source and built pages are managed in the Apache DB
-Subversion repository.
+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
@@ -320,13 +323,19 @@
<a name="N100B5"></a><a name="Create+a+Forrest+seed+site"></a>
<h3 class="boxed">Create a Forrest seed site</h3>
<p>
-To get started:
+To get started with learning Forrest:
</p>
<ul>
-<li> Install Forrest. </li>
+<li>
+<a class="external" href="http://forrest.apache.org/mirrors.cgi">Download</a>
+ Forrest 0.7. </li>
+
+<li>
+<a class="external" href="http://forrest.apache.org/docs_0_70/your-project.html#installing">Install Forrest and set up your environment</a>. </li>
-<li> After it is installed, cd into the directory of your choice
+<li>
+<span class="codefrag">cd</span> into the directory of your choice
and enter '<span class="codefrag">forrest seed</span>' to initialize a new project.
</li>
@@ -340,10 +349,11 @@
<li> Look at the sample pages that are included in the seed site.</li>
</ul>
-<a name="N100DA"></a><a name="Add+your+new+page+to+the+seed+site"></a>
+<a name="N100E8"></a><a name="Add+your+new+page+to+the+seed+site"></a>
<h3 class="boxed">Add your new page to the seed site</h3>
<p>
-Next, incorporate the new page(s) into the newly-created seed site:
+If you don't need to add a new page, skip this step.
+Otherwise, incorporate the new page(s) into the newly-created seed site:
</p>
<ul>
@@ -429,7 +439,7 @@
source file. </li>
</ul>
-<a name="N1013D"></a><a name="What+editor+can+you+use+for+Forrest+XML%3F"></a>
+<a name="N1014B"></a><a name="What+editor+can+you+use+for+Forrest+XML%3F"></a>
<h3 class="boxed">What editor can you use for Forrest XML?</h3>
<p>
The Forrest web site mentions jEdit, oXygen, xmlspy,
@@ -460,7 +470,7 @@
by posting to
<a href="../derby_mail.html">derby-dev@db.apache.org</a>.
</p>
-<a name="N10167"></a><a name="Resolve+Forrest+DTDs+locally"></a>
+<a name="N10175"></a><a name="Resolve+Forrest+DTDs+locally"></a>
<h3 class="boxed">Resolve Forrest DTDs locally</h3>
<p>
Many source files in the Derby web site repository are in Forrest XML format.
@@ -493,82 +503,164 @@
-<a name="N10186"></a><a name="Updating+the+Apache+Derby+web+site"></a>
+<a name="N10194"></a><a name="Updating+the+Apache+Derby+web+site"></a>
<h2 class="boxed">Updating the Apache Derby web site </h2>
<div class="section">
<p>
-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.
+This section explains how to add a new page to the Derby web site or
+modify an existing page.
+Steps 1-6 are for both contributors and committers.
+Step 7 tells contributors how to create a patch.
+Steps 8-10 tell committers how to commit and publish changes.
</p>
-<a name="N1018F"></a><a name="1.+Install+Forrest+on+your+machine"></a>
+<a name="N1019D"></a><a name="1.+Install+Forrest+on+your+machine"></a>
<h3 class="boxed">1. Install Forrest on your machine</h3>
<p>
If you haven't installed Forrest yet,
<a class="external" href="http://forrest.apache.org/mirrors.cgi">install Forrest 0.7</a>
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.
</p>
-<a name="N1019D"></a><a name="2.+Check+out+the+Derby+web+site+pages"></a>
+<a name="N101AB"></a><a name="2.+Check+out+the+Derby+web+site+pages"></a>
<h3 class="boxed">2. Check out the Derby web site pages </h3>
<p>
-Check the Derby web site files out of the Subversion repository:
+Check the Derby web site files out of the subversion repository:
</p>
<pre class="code">
svn co https://svn.apache.org/repos/asf/db/derby/site/trunk
</pre>
-<a name="N101AB"></a><a name="3.+Modify+files+in+the+src+tree"></a>
+<a name="N101B9"></a><a name="3.+Modify+files+in+the+src+tree"></a>
<h3 class="boxed">3. Modify files in the src tree </h3>
<p>
-Source files are in the places listed below:
+After checking the site out of subversion,
+the web site source is in
+<span class="codefrag">src/documentation/content/xdocs</span> and the files processed
+("skinned") by Forrest are in <span class="codefrag">build/site</span>.
+(Forrest also outputs files to <span class="codefrag">build/webapp</span> and
+<span class="codefrag">build/tmp</span>, but we don't commit
+those directories to subversion.)
+Modifying the web site requires changing files in the
+<span class="codefrag">src</span> tree, then building the site with Forrest.
+</p>
+<p>
+The Derby web site is composed of many file types and
+it's helpful to understand what Forrest does with them:
+</p>
+<ul>
+
+<li> *.xml and *.html:
+ Forrest reads these files, adds site navigation and
+ decoration, then outputs them as .html files to the
+ <span class="codefrag">build</span> directory.
+ </li>
+
+<li> *.htm:
+ Forrest copies these files without modifying them to
+ the <span class="codefrag">build/site</span> directory (in other words,
+ they don't get site navigation and decoration).
+ </li>
+
+<li> binary (*.tar.gz, *.zip) and image (*.gif, *.jpg) files:
+ Forrest copies these files without modifying them to
+ <span class="codefrag">build/site/binaries</span>
+ <span class="codefrag">and build/site/images</span>, respectively.
+ </li>
+
+<li> *.aart :
+ These files contain ascii stick diagrams that Forrest converts to png,
+ then outputs to the <span class="codefrag">build/site</span> directory.
+ </li>
+
+<li> *.cgi :
+ Forrest copies these files without modifying them to the
+ <span class="codefrag">build/site</span> directory.
+ </li>
+
+</ul>
+<p>
+The table below describes the source directory structure
+and indicates which tabs might link to files in a given directory
+(the Derby project sometimes changes tab names and linkages):
</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr>
-<th colspan="1" rowspan="1"> Source File Location </th>
- <th colspan="1" rowspan="1"> File types </th>
- <th colspan="1" rowspan="1"> Comment</th>
+<th colspan="1" rowspan="1"> Source Location </th>
+ <th colspan="1" rowspan="1"> Description </th>
+ <th colspan="1" rowspan="1"> Tab(s) </th>
</tr>
<tr>
-<td colspan="1" rowspan="1"> <span class="codefrag">src/documentation/content/xdocs</span></td>
- <td colspan="1" rowspan="1"> Source files in formats Forrest can consume, such as *.xml and *.html.</td>
- <td colspan="1" rowspan="1"> Forrest ingests these files, adds site navigation and
- decoration, and outputs them as .html files to
- build/site and build/app.
- </td>
+<td colspan="1" rowspan="1"> <span class="codefrag">xdocs</span></td>
+ <td colspan="1" rowspan="1"> The root location of the web site source.</td>
+ <td colspan="1" rowspan="1"> Home, Quick Start, Community </td>
</tr>
<tr>
-
-<td colspan="1" rowspan="1"> <span class="codefrag">src/documentation/content/xdocs/papers</span></td>
- <td colspan="1" rowspan="1"> Source HTML files you don't want Forrest to touch (*.htm).</td>
- <td colspan="1" rowspan="1"> Forrest copies these files without modifying them to
- build/site/papers.
- </td>
+
+<td colspan="1" rowspan="1"> <span class="codefrag">xdocs/binaries</span></td>
+ <td colspan="1" rowspan="1"> Binary files, such as *.tar.gz and *.ZIP. </td>
+ <td colspan="1" rowspan="1"> Linked to from various pages.</td>
</tr>
<tr>
-<td colspan="1" rowspan="1"> <span class="codefrag">src/documentation/content/xdocs/binaries</span></td>
- <td colspan="1" rowspan="1"> Binary files, such as *.tar.gz and *.ZIP. </td>
- <td colspan="1" rowspan="1"> Forrest copies these files without modifying them to
- build/site/binaries.
- </td>
+<td colspan="1" rowspan="1"> <span class="codefrag">xdocs/images</span></td>
+ <td colspan="1" rowspan="1"> Image files, such as *.gif, *.jpg and *.png. </td>
+ <td colspan="1" rowspan="1"> Linked to from various pages. </td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1"> <span class="codefrag">xdocs/integrate</span></td>
+ <td colspan="1" rowspan="1"> Documents that explain how to use Derby with some other product. </td>
+ <td colspan="1" rowspan="1"> Resources (Products and Eclipse Plug-ins sections) </td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1"> <span class="codefrag">xdocs/logo</span></td>
+ <td colspan="1" rowspan="1"> Apache Derby logo files. </td>
+ <td colspan="1" rowspan="1"> Community </td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1"> <span class="codefrag">xdocs/manuals</span></td>
+ <td colspan="1" rowspan="1"> Files that describe the Derby manuals and DITA
+ processing.</td>
+ <td colspan="1" rowspan="1"> Documentation </td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1"> <span class="codefrag">xdocs/papers</span></td>
+ <td colspan="1" rowspan="1"> Miscellaneous contributions.</td>
+ <td colspan="1" rowspan="1"> Resources (Papers section), Community </td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1"> <span class="codefrag">xdocs/releases</span></td>
+ <td colspan="1" rowspan="1"> Contains files for the Derby downloads.</td>
+ <td colspan="1" rowspan="1"> Download </td>
</tr>
</table>
<p>
-Two files in <span class="codefrag">src/documentation/content/xdocs</span>
-don't get output to the <span class="codefrag">build</span> tree;
+Two files in <span class="codefrag">xdocs</span>
+don't get output to the <span class="codefrag">build/site</span> tree;
they control the information and links in the resulting navigation bar:
</p>
<ul>
@@ -576,11 +668,7 @@
<li>
<p>
<span class="codefrag">tabs.xml</span>: sets up the tabs for the web site.
- As of this writing there are five:
- <em>Home</em>, <em>Community</em>, <em>Manuals</em>,
- <em>Papers</em>, and <em>Integration</em>.
- Adding a tab is easy, but it also requires updates to the
- <span class="codefrag">site.xml</span> file.
+ Over time the specific tabs have changed.
</p>
</li>
@@ -597,28 +685,34 @@
</li>
</ul>
-<a name="N10235"></a><a name="4.+Build+the+site"></a>
+<a name="N102CE"></a><a name="4.+Build+the+site"></a>
<h3 class="boxed">4. Build the site </h3>
<p>
-After modifying files, you need to rebuild the site with the
+After modifying files, rebuild the site with the
'<span class="codefrag">forrest site</span>' command.
-Do this in the directory that is one level above the
-<span class="codefrag">src</span>
-and
-<span class="codefrag">build</span>
-directories.
+Do this in the trunk (one level above the <span class="codefrag">src</span> and
+<span class="codefrag">build</span> directories).
</p>
<p>Due to <a class="external" href="http://issues.apache.org/jira/browse/FOR-480">FOR-480</a>,
-note that the skinned HTML for the release pages will be built into your
-$FORREST/main/site directory. If you have made changes to the site navigation or to
-the release pages themselves these files will need to be moved into
-build/site/releases so that they can be checked into subversion with the source
+the skinned HTML for the release pages will be output to your
+<span class="codefrag">FORREST_HOME/main/site</span> directory.
+If you have made changes to the site navigation or to
+the release pages themselves copy these files to
+<span class="codefrag">build/site/releases</span>
+so that they can be checked into subversion with the source
changes.
</p>
-<a name="N1024F"></a><a name="5.+Test+the+changes"></a>
+<p>
+If you run out of memory building the web site,
+try setting the <span class="codefrag">ANT_OPTS</span> environment variable to
+<span class="codefrag">-mx512M</span>.
+</p>
+<a name="N102F7"></a><a name="5.+Test+the+changes"></a>
<h3 class="boxed">5. Test the changes </h3>
<p>
There are a couple ways (at least) to review changes.
+</p>
+<p>
One way is to open <span class="codefrag">build/site/index.html</span> with your web browser.
</p>
<p>
@@ -643,14 +737,14 @@
apache > db
</pre>
<p>
-This is alright, if somewhat confusing.
+The difference in bread crumb behavior is alright, though confusing.
The <span class="codefrag">skinconf.xml</span> specifies the base links for the trail,
then Javascript adds extra breadcrumbs for each directory after the domain.
<a class="external" href="http://forrest.apache.org/faq.html#breadcrumbs">Extra breadcrumbs
won't be added when the site is viewed locally.</a>
</p>
-<a name="N10281"></a><a name="odd_diffs"></a>
+<a name="N1032C"></a><a name="odd_diffs"></a>
<h3 class="boxed">6. Odd diffs under build/site/skin and build/site/papers explained (sort of) </h3>
<p>
Forrest generates inconsistent line endings on Windows machines
@@ -678,15 +772,26 @@
<a href="../derby_mail.html">derby-dev@db.apache.org</a>
if a particular file should be committed or not.
</p>
-<a name="N102B2"></a><a name="7.+Commit+changes+to+the+src+and+build%2Fsite+directories"></a>
-<h3 class="boxed">7. Commit changes to the src and build/site directories</h3>
+<a name="N1035D"></a><a name="7.+Create+a+patch"></a>
+<h3 class="boxed">7. Create a patch</h3>
+<p>
+Create a patch at the <span class="codefrag">trunk</span> level and only include the
+<span class="codefrag">src</span> directory, as shown below:
+</p>
+<pre class="code">svn diff src > changes.diff</pre>
+<a name="N10371"></a><a name="8.+Commit+changes+to+the+src+and+build%2Fsite+directories"></a>
+<h3 class="boxed">8. Commit changes to the src and build/site directories</h3>
+<p>
+Apply any patch, if one was provided, then build and test the web site
+(Steps 4-6).
+</p>
<p>
Commit modified pages in the <span class="codefrag">src</span> and
<span class="codefrag">build/site</span> trees.
The '<span class="codefrag">forrest site</span>' command also outputs
<span class="codefrag">build/webapp</span> and
<span class="codefrag">build/tmp</span> directories,
-but they aren't checked into the Subversion repository.
+but they aren't checked into the subversion repository.
</p>
<p>
If you add or delete a file, you must 'svn add' or 'svn delete' it in the
@@ -713,15 +818,14 @@
<p>
When you're ready to commit,
one way is to enter the command shown below
-from the directory that is one level above the
-<span class="codefrag">src</span> and
+one level above the <span class="codefrag">src</span> and
<span class="codefrag">build</span> directories:
</p>
<pre class="code">
svn commit --message "here is my commit message" src build/site
</pre>
-<a name="N102F7"></a><a name="8.+Make+web+site+changes+visible"></a>
-<h3 class="boxed">8. Make web site changes visible</h3>
+<a name="N103B9"></a><a name="9.+Make+web+site+changes+visible"></a>
+<h3 class="boxed">9. Make web site changes visible</h3>
<p>
A Derby committer can make web site changes visible as follows:
</p>
@@ -734,8 +838,8 @@
www.apache.org automatically syncs up with people.apache.org every couple hours
(the specific schedule could change).
</p>
-<a name="N1030B"></a><a name="9.+Considering+a+quick+fix+to+the+build+tree%3F"></a>
-<h3 class="boxed">9. Considering a quick fix to the build tree?</h3>
+<a name="N103CD"></a><a name="10.+Considering+a+quick+fix+to+the+build+tree%3F"></a>
+<h3 class="boxed">10. Considering a quick fix to the build tree?</h3>
<p>
If you modify a file in the <span class="codefrag">build/site</span> tree,
be sure to also change the source file in the <span class="codefrag">src</span> tree.
@@ -743,7 +847,7 @@
will likely overwrite your changes to the build tree.
</p>
<p>
-<em>Last updated October 11, 2006</em>
+<em>Last updated Oct 17, 2006</em>
</p>
</div>
Modified: db/derby/site/trunk/src/documentation/content/xdocs/papers/derby_web.xml
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/src/documentation/content/xdocs/papers/derby_web.xml?view=diff&rev=465131&r1=465130&r2=465131
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/papers/derby_web.xml (original)
+++ db/derby/site/trunk/src/documentation/content/xdocs/papers/derby_web.xml Tue Oct 17 20:10:31 2006
@@ -30,7 +30,7 @@
uses
<a href="http://forrest.apache.org">Forrest</a>.
Page source and built pages are managed in the Apache DB
-Subversion repository.
+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
@@ -164,12 +164,14 @@
<section>
<title>Create a Forrest seed site</title>
<p>
-To get started:
+To get started with learning Forrest:
</p>
<ul>
- <li> Install Forrest. </li>
- <li> After it is installed, cd into the directory of your choice
+ <li> <a href="http://forrest.apache.org/mirrors.cgi">Download</a>
+ Forrest 0.7. </li>
+ <li> <a href="http://forrest.apache.org/docs_0_70/your-project.html#installing">Install Forrest and set up your environment</a>. </li>
+ <li> <code>cd</code> into the directory of your choice
and enter '<code>forrest seed</code>' to initialize a new project.
</li>
<li> Enter 'forrest site' to build the site. </li>
@@ -185,7 +187,8 @@
<title>Add your new page to the seed site</title>
<p>
-Next, incorporate the new page(s) into the newly-created seed site:
+If you don't need to add a new page, skip this step.
+Otherwise, incorporate the new page(s) into the newly-created seed site:
</p>
<ul>
@@ -335,8 +338,11 @@
<title>Updating the Apache Derby web site </title>
<p>
-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.
+This section explains how to add a new page to the Derby web site or
+modify an existing page.
+Steps 1-6 are for both contributors and committers.
+Step 7 tells contributors how to create a patch.
+Steps 8-10 tell committers how to commit and publish changes.
</p>
<section>
@@ -346,9 +352,6 @@
If you haven't installed Forrest yet,
<a href="http://forrest.apache.org/mirrors.cgi">install Forrest 0.7</a>
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.
</p>
</section>
@@ -356,7 +359,7 @@
<title>2. Check out the Derby web site pages </title>
<p>
-Check the Derby web site files out of the Subversion repository:
+Check the Derby web site files out of the subversion repository:
</p>
<source>
@@ -369,53 +372,113 @@
<title>3. Modify files in the src tree </title>
<p>
-Source files are in the places listed below:
+After checking the site out of subversion,
+the web site source is in
+<code>src/documentation/content/xdocs</code> and the files processed
+("skinned") by Forrest are in <code>build/site</code>.
+(Forrest also outputs files to <code>build/webapp</code> and
+<code>build/tmp</code>, but we don't commit
+those directories to subversion.)
+Modifying the web site requires changing files in the
+<code>src</code> tree, then building the site with Forrest.
+</p>
+
+<p>
+The Derby web site is composed of many file types and
+it's helpful to understand what Forrest does with them:
+</p>
+
+<ul>
+ <li> *.xml and *.html:
+ Forrest reads these files, adds site navigation and
+ decoration, then outputs them as .html files to the
+ <code>build</code> directory.
+ </li>
+ <li> *.htm:
+ Forrest copies these files without modifying them to
+ the <code>build/site</code> directory (in other words,
+ they don't get site navigation and decoration).
+ </li>
+ <li> binary (*.tar.gz, *.zip) and image (*.gif, *.jpg) files:
+ Forrest copies these files without modifying them to
+ <code>build/site/binaries</code>
+ <code>and build/site/images</code>, respectively.
+ </li>
+ <li> *.aart :
+ These files contain ascii stick diagrams that Forrest converts to png,
+ then outputs to the <code>build/site</code> directory.
+ </li>
+ <li> *.cgi :
+ Forrest copies these files without modifying them to the
+ <code>build/site</code> directory.
+ </li>
+</ul>
+
+<p>
+The table below describes the source directory structure
+and indicates which tabs might link to files in a given directory
+(the Derby project sometimes changes tab names and linkages):
</p>
<table>
<tr>
- <th> Source File Location </th>
- <th> File types </th>
- <th> Comment</th>
+ <th> Source Location </th>
+ <th> Description </th>
+ <th> Tab(s) </th>
+</tr>
+<tr>
+ <td> <code>xdocs</code></td>
+ <td> The root location of the web site source.</td>
+ <td> Home, Quick Start, Community </td>
</tr>
<tr>
- <td> <code>src/documentation/content/xdocs</code></td>
- <td> Source files in formats Forrest can consume, such as *.xml and *.html.</td>
- <td> Forrest ingests these files, adds site navigation and
- decoration, and outputs them as .html files to
- build/site and build/app.
- </td>
+ <td> <code>xdocs/binaries</code></td>
+ <td> Binary files, such as *.tar.gz and *.ZIP. </td>
+ <td> Linked to from various pages.</td>
</tr>
<tr>
- <td> <code>src/documentation/content/xdocs/papers</code></td>
- <td> Source HTML files you don't want Forrest to touch (*.htm).</td>
- <td> Forrest copies these files without modifying them to
- build/site/papers.
- </td>
+ <td> <code>xdocs/images</code></td>
+ <td> Image files, such as *.gif, *.jpg and *.png. </td>
+ <td> Linked to from various pages. </td>
</tr>
<tr>
- <td> <code>src/documentation/content/xdocs/binaries</code></td>
- <td> Binary files, such as *.tar.gz and *.ZIP. </td>
- <td> Forrest copies these files without modifying them to
- build/site/binaries.
- </td>
+ <td> <code>xdocs/integrate</code></td>
+ <td> Documents that explain how to use Derby with some other product. </td>
+ <td> Resources (Products and Eclipse Plug-ins sections) </td>
+</tr>
+<tr>
+ <td> <code>xdocs/logo</code></td>
+ <td> Apache Derby logo files. </td>
+ <td> Community </td>
+</tr>
+<tr>
+ <td> <code>xdocs/manuals</code></td>
+ <td> Files that describe the Derby manuals and DITA
+ processing.</td>
+ <td> Documentation </td>
+</tr>
+<tr>
+ <td> <code>xdocs/papers</code></td>
+ <td> Miscellaneous contributions.</td>
+ <td> Resources (Papers section), Community </td>
+</tr>
+<tr>
+ <td> <code>xdocs/releases</code></td>
+ <td> Contains files for the Derby downloads.</td>
+ <td> Download </td>
</tr>
</table>
<p>
-Two files in <code>src/documentation/content/xdocs</code>
-don't get output to the <code>build</code> tree;
+Two files in <code>xdocs</code>
+don't get output to the <code>build/site</code> tree;
they control the information and links in the resulting navigation bar:
</p>
<ul>
<li><p> <code>tabs.xml</code>: sets up the tabs for the web site.
- As of this writing there are five:
- <em>Home</em>, <em>Community</em>, <em>Manuals</em>,
- <em>Papers</em>, and <em>Integration</em>.
- Adding a tab is easy, but it also requires updates to the
- <code>site.xml</code> file.
+ Over time the specific tabs have changed.
</p>
</li>
<li> <p> <code>site.xml</code>: contains a site map for files on the site.
@@ -432,23 +495,28 @@
<title>4. Build the site </title>
<p>
-After modifying files, you need to rebuild the site with the
+After modifying files, rebuild the site with the
'<code>forrest site</code>' command.
-Do this in the directory that is one level above the
-<code>src</code>
-and
-<code>build</code>
-directories.
+Do this in the trunk (one level above the <code>src</code> and
+<code>build</code> directories).
</p>
<p>Due to <a href="http://issues.apache.org/jira/browse/FOR-480">FOR-480</a>,
-note that the skinned HTML for the release pages will be built into your
-$FORREST/main/site directory. If you have made changes to the site navigation or to
-the release pages themselves these files will need to be moved into
-build/site/releases so that they can be checked into subversion with the source
+the skinned HTML for the release pages will be output to your
+<code>FORREST_HOME/main/site</code> directory.
+If you have made changes to the site navigation or to
+the release pages themselves copy these files to
+<code>build/site/releases</code>
+so that they can be checked into subversion with the source
changes.
</p>
+<p>
+If you run out of memory building the web site,
+try setting the <code>ANT_OPTS</code> environment variable to
+<code>-mx512M</code>.
+</p>
+
</section>
<section>
@@ -456,6 +524,9 @@
<p>
There are a couple ways (at least) to review changes.
+</p>
+
+<p>
One way is to open <code>build/site/index.html</code> with your web browser.
</p>
@@ -488,7 +559,7 @@
</source>
<p>
-This is alright, if somewhat confusing.
+The difference in bread crumb behavior is alright, though confusing.
The <code>skinconf.xml</code> specifies the base links for the trail,
then Javascript adds extra breadcrumbs for each directory after the domain.
<a href="http://forrest.apache.org/faq.html#breadcrumbs">Extra breadcrumbs
@@ -531,7 +602,25 @@
</section>
<section>
-<title>7. Commit changes to the src and build/site directories</title>
+<title>7. Create a patch</title>
+
+
+<p>
+Create a patch at the <code>trunk</code> level and only include the
+<code>src</code> directory, as shown below:
+</p>
+
+<source>svn diff src > changes.diff</source>
+
+</section>
+
+<section>
+<title>8. Commit changes to the src and build/site directories</title>
+
+<p>
+Apply any patch, if one was provided, then build and test the web site
+(Steps 4-6).
+</p>
<p>
Commit modified pages in the <code>src</code> and
@@ -539,7 +628,7 @@
The '<code>forrest site</code>' command also outputs
<code>build/webapp</code> and
<code>build/tmp</code> directories,
-but they aren't checked into the Subversion repository.
+but they aren't checked into the subversion repository.
</p>
<p>
@@ -570,8 +659,7 @@
<p>
When you're ready to commit,
one way is to enter the command shown below
-from the directory that is one level above the
-<code>src</code> and
+one level above the <code>src</code> and
<code>build</code> directories:
</p>
@@ -581,7 +669,7 @@
</section>
<section>
-<title>8. Make web site changes visible</title>
+<title>9. Make web site changes visible</title>
<p>
A Derby committer can make web site changes visible as follows:
@@ -601,7 +689,7 @@
</section>
<section>
-<title>9. Considering a quick fix to the build tree?</title>
+<title>10. Considering a quick fix to the build tree?</title>
<p>
If you modify a file in the <code>build/site</code> tree,
be sure to also change the source file in the <code>src</code> tree.
@@ -611,7 +699,7 @@
</section>
-<p><em>Last updated October 11, 2006</em></p>
+<p><em>Last updated Oct 17, 2006</em></p>
</section>
</body>