db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j..@apache.org
Subject svn commit: r465131 - in /db/derby/site/trunk: build/site/papers/derby_web.html src/documentation/content/xdocs/papers/derby_web.xml
Date Wed, 18 Oct 2006 03:10:35 GMT
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 &gt; 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 &gt; 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 &gt; 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>



Mime
View raw message