From 7389cc2a493a4ce5c3f7bea9d19dfdc4a8ce6606 Mon Sep 17 00:00:00 2001
From: Jeremias Maerki <jeremias@apache.org>
Date: Tue, 23 Aug 2005 19:35:22 +0000
Subject: [PATCH] Rewrite DocMgmt docs to use Forrest 0.7 and a local
 ForrestBot.

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@239450 13f79535-47bb-0310-9956-ffa450edef68
---
 src/documentation/content/xdocs/dev/doc.xml | 141 ++++++--------------
 1 file changed, 41 insertions(+), 100 deletions(-)

diff --git a/src/documentation/content/xdocs/dev/doc.xml b/src/documentation/content/xdocs/dev/doc.xml
index 070300cd5..bcc812aff 100644
--- a/src/documentation/content/xdocs/dev/doc.xml
+++ b/src/documentation/content/xdocs/dev/doc.xml
@@ -71,126 +71,67 @@ Maintenance branch releases either copy the trunk content to the maintenance bra
             <td><link href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/src/documentation/content/xdocs/">ViewCVS</link></td>
           </tr>
           <tr>
-            <td>Developer builds documentation and commits it to xml-site.</td>
-            <td>xml-site repository (cvs) at cvs.apache.org/home/cvs/xml-site</td>
-            <td>web-ready</td>
-            <td><link href="http://cvs.apache.org/viewcvs.cgi/xml-site/targets/fop/">ViewCVS</link></td>
-          </tr>
-          <tr>
-            <td>Developer publishes website.</td>
-            <td>FOP live web site, /www/xml.apache.org/fop on www.apache.org</td>
-            <td>web-ready</td>
-            <td><link href="http://xml.apache.org/fop">FOP Web Site</link></td>
-          </tr>
-<!--
-          <tr>
-            <td>
-              <link href="#forrestbot-refresh">Forrestbot "refresh"</link>. Automatically done every six hours. Can be manually refreshed by authorized users at <link href="http://forrestbot.cocoondev.org">the Forrestbot Web Interface</link>.
-          </td>
-            <td>Physical location unknown and unimportant to us</td>
-            <td>web-ready</td>
-            <td>Content can be viewed <link href="http://forrestbot.cocoondev.org/sites/xml-fop">here</link>.</td>
+            <td>Developer builds and uploads documentation using ForrestBot.</td>
+            <td>/www/xmlgraphics.apache.org/fop on cvs.apache.org</td>
+            <td>sync-ready</td>
+            <td>n/a</td>
           </tr>
           <tr>
-            <td><link href="#forrestbot-publish">Forrestbot "publish"</link>. Always done manually at <link href="http://forrestbot.cocoondev.org">the Forrestbot Web Interface</link>.</td>
-            <td>FOP web repository (cvs) at icarus.apache.org/home/cvs/xml-site/targets/fop</td>
+            <td>Cron job runs rsync to synchronize the website with the real web server (runs every few hours).</td>
+            <td>Infrastructure knows. :-)</td>
             <td>web-ready</td>
-            <td><link href="http://cvs.apache.org/viewcvs.cgi/xml-site/targets/fop/">ViewCVS</link></td>
+            <td><link href="http://xmlgraphics.apache.org/fop">FOP Web Site</link></td>
           </tr>
-          <tr>
-            <td>Automatic Live Site Update every six hours (midnight, 6am, noon, 6pm Pacific time).</td>
-            <td>FOP live web site, somewhere on daedalus.apache.org</td>
-            <td>web-ready</td>
-            <td><link href="http://xml.apache.org/fop">FOP Web Site</link></td>
-          </tr>
--->
         </table>
-        <note>Forrestbot is currently not available for website publishing.</note>
-      </section>
-<!--
-      <section id="web-forrestbot-refresh">
-        <title>Forrestbot "refresh" Step-by-Step</title>
-        <note>The Forrestbot "refresh" is automatically run on the server every six hours. Only follow the steps below if you need to check the results more promptly than that allows, or if you need to "refresh" in preparation for a "publish".</note>
-        <p>To manually use the Forrestbot "refresh", simply follow these steps:</p>
-        <ul>
-          <li>Make sure your changes are committed to the FOP source repository.</li>
-          <li>Open http://forrestbot.cocoondev.org in your browser.</li>
-          <li>Login.</li>
-          <li>In the "Select a module" box, select "xml-fop".</li>
-          <li>Click the "refresh" button to have the interim site built.
-On-screen instructions tell you how to view the log as the build progresses.</li>
-        </ul>
+        <note>Server-side ForrestBot is currently not available for website publishing. We use it locally and with manual invocation.</note>
       </section>
       <section id="web-forrestbot-publish">
-        <title>Forrestbot "publish" Step-by-Step</title>
-        <p>To "publish" the Forrestbot output to the FOP Web repository:</p>
+        <title>ForrestBot "publish" Step-by-Step</title>
+        <p>
+          We're using ForrestBot for build and deploy the FOP website. ForrestBot comes with Apache Forrest 0.7. 
+          The root directory of your FOP checkout contains the file "publish.xml" which is an Ant build file
+          that manages the build and the deployment of the FOP website. Please look into this file for
+          further instructions to set up ForrestBot on your machine. Basically, we're simply running ForrestBot 
+          manually by typing "ant -f publish.xml" once we're happy with our changes to the site. Be sure to set
+          up the "deploy.settings" file as described in the "publish.xml" file. Step-by-step instructions for 
+          the deployment process again:
+        </p>
         <ul>
-          <li>Make sure you are satisfied with the "refreshed" site.</li>
-          <li>Open http://forrestbot.cocoondev.org in your browser.</li>
-          <li>Login.</li>
-          <li>In the "Select a module" box, select "xml-fop".</li>
-          <li>Click the "publish" button.
-On-screen instructions tell you how to view the log as the build progresses.</li>
-          <li>Wait for the next 6-hour live-site update cycle and check your changes.</li>
+          <li>Modify the sources of the website and check locally with Forrest 0.7 (run "forrest run" or just "forrest").</li>
+          <li>
+            Once you're satisfied, run "ant -f publish.xml" to do a clean build of the website. If the build 
+            runs without problems, the website will be uploaded as a whole using SCP to cvs.apache.org.
+          </li>
+          <li>Wait for the next rsync cycle and check your changes in the live site. (Sorry, no manual rsync available ATM)</li>
         </ul>
       </section>
--->
-<!--
-      <section id="web-live-update">
-        <title>Live Site Update</title>
-        <p>If there are problems with the live site update (the process of copying the web site contents from the FOP web repository to the live site:</p>
-        <ul>
-          <li>The CVS update logs can be viewed at http://www.apache.org/~rubys/updatesite.logx, where "x" is a number from 1-4, these four files being the updates done over the past 24 hours.
-Review the most recent log file for clues.</li>
-          <li>The script is maintained by Sam Ruby (rubys@apache.org).
-Contact him for further help.</li>
-        </ul>
-      </section>
--->
       <section id="web-local-forrest">
         <title>Using a Local Forrest</title>
-<!--        
-        <note>Most documentation content changes do not require a local copy of Forrest.
-In general, use the Forrestbot instead. Forrestbot is easy to use, always uses the "approved" methodology, and has fewer error-prone manual steps.</note>
-        <p>There are some situations where you may want to have a local Forrest installation. For example, you do not want to tie up server resources testing major changes, such as sitemap building, that may require many edit/build/test/debug cycles. After you are done testing, use the forrestbot to "refresh" and "publish" the site.</p>
-        <note>Forrest needs to be run on a machine with a graphical environment.
-It will fail in a headless environment when it tries to use FOP to generate the PDF files.</note>
--->
-        <p>To use a local Forrest:</p>
+        <p>To use a local Forrest (during website development, not for deployment):</p>
         <ul>
-          <!--<li>checkout the xml-forrest module (same repository as xml-fop)</li>-->
-          <li><link href="http://forrest.apache.org/mirrors.cgi#closest">download</link> latest the Forrest release</li>
-          <li>checkout the xml-site/targets/fop module (same repository as xml-fop)</li>
-          <li>set environment variable FORREST_HOME=~/apache-forrest-0.6/src/core where ~ is the directory where Forrest is installed
+          <li><link href="http://forrest.apache.org/mirrors.cgi#closest">download</link> latest the Forrest release (currently Forrest 0.7)</li>
+          <li>set environment variable FORREST_HOME=~/apache-forrest-0.7 where ~ is the directory where Forrest is installed
               (see <link href="http://forrest.apache.org/docs/your-project.html">http://forrest.apache.org/docs/your-project.html</link> for details)</li>
           <li>set environment variable PATH=$PATH:$FORREST_HOME/bin</li>
-          <li>cd to xml-fop directory</li>
+          <li>cd to your local FOP checkout</li>
+          <li>update your local FOP checkout (svn update)</li>
           <li>run forrest(.bat), which will build the web-site documents in xml-fop/build/site.</li>
         </ul>
-      </section>
-      <section id="web-manual">
-        <title>Updating the FOP Web Repository Manually</title>
-<!--
-<warning>The steps in this section should not ordinarily be used. They are documented here for historical reasons, and for emergencies.
-See <link href="#delete">manually deleting retired files</link> for an exception to this rule.</warning>
--->
-        <ul>
-          <li>Copy (or sym-link) the documents generated by Forrest (in xml-fop/build/site) to xml-site/targets/fop on your local machine.</li>
-          <li>Commit xml-site/targets/fop.</li>
-        </ul>
+        <note>
+          You can use "forrest run" to start a local web server. That improves development speed as you 
+          can simply refresh in the browser after a change.
+        </note>
       </section>
       <section id="delete">
         <title>Deleting Documentation Files</title>
-        <p>The one place where manual updates of the web cvs repository are required is when a document is retired. At this point, it will no longer be generated. However, it will still exist in the web cvs repository. You will need to use a cvs client to remove the files, then commit the changes to keep them from continuing to exist on the live site.</p>
-      </section>
-      <section id="publish">
-        <title>Publish the Website</title>
-        <ul>
-          <li>ssh to www.apache.org</li>
-          <li>cd /www/xml.apache.org/fop</li>
-          <li>make sure your umask is 0002 (to make the files group writeable)</li>
-          <li>cvs up -Pd</li>
-        </ul>
+        <p>
+          ForrestBot simply uploads the whole generated site. It doesn't delete obsolete files. You
+          can do that manually in the /www/xmlgraphics.apache.org/fop folder on cvs.apache.org. Be careful
+          when doing stuff like that.
+        </p>
+        <note>
+          Please make sure you always have <strong>group rw permissions on all files</strong> under the /www directory!
+        </note>
       </section>
       
     </section>
-- 
2.39.5