forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r527010 [20/26] - in /forrest/trunk/site-author/content: ./ skins/ xdocs/ xdocs/docs_0_70/ xdocs/docs_0_70/howto/ xdocs/docs_0_70/howto/bugzilla-patch/ xdocs/docs_0_70/howto/cvs-ssh/ xdocs/docs_0_70/howto/multi/ xdocs/docs_0_80/ xdocs/docs_...
Date Tue, 10 Apr 2007 03:48:57 GMT
Modified: forrest/trunk/site-author/content/xdocs/howto-dev.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/howto-dev.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/howto-dev.xml (original)
+++ forrest/trunk/site-author/content/xdocs/howto-dev.xml Mon Apr  9 20:48:52 2007
@@ -20,24 +20,22 @@
 <howto>
   <header>
     <title>How to be a Forrest developer</title>
-
     <abstract>
-      This How-To provides some tips and procedures for being a
-      Forrest developer.
+      This How-To provides some tips and procedures for being a Forrest
+      developer.
     </abstract>
-
     <last-modified-content-date date="2005-08-22" />
   </header>
   <audience title="Intended Audience">
-<warning>
-This document is under initial development.
-</warning>
+    <warning>
+      This document is under initial development.
+    </warning>
     <p>
-      People who are ready to go beyond the basics of using Forrest.
-      This might be to utilise Forrest for your advanced needs, debugging,
-      creating a new plugin, enhancing an existing plugin, enhancing the core
-      capabilities, contributing such enhancements back to the Apache Forrest
-      project, etc. In all cases, this is what we mean by "developer".
+      People who are ready to go beyond the basics of using Forrest. This might
+      be to utilise Forrest for your advanced needs, debugging, creating a new
+      plugin, enhancing an existing plugin, enhancing the core capabilities,
+      contributing such enhancements back to the Apache Forrest project, etc. In
+      all cases, this is what we mean by "developer".
     </p>
     <p>
       Actually, users will also find that some parts of this document are
@@ -45,24 +43,23 @@
       editing content.
     </p>
   </audience>
-
   <purpose title="Purpose">
     <p>
-      This How-To provides some tips and procedures for being
-      an Apache Forrest developer. Ideally a developer would
-      also contribute back to the project, so these notes assume that.
-      Various key development tasks are used as worked examples.
+      This How-To provides some tips and procedures for being an Apache Forrest
+      developer. Ideally a developer would also contribute back to the project,
+      so these notes assume that. Various key development tasks are used as
+      worked examples.
     </p>
     <p>
-      This document is intended to be an introduction to developing in Forrest, specifically,
-      for those developers without a strong Cocoon background.  Some key concepts in Forrest 
-      like sitemaps, pipelines, and locationmaps can be challenging enough to understand without
-      also struggling with the fundamental development chores of debugging, extension methods, etc.
-      The goal of this document is to reduce the steep learning curve by providing answers to 
-      some really practical Forrest development questions.
+      This document is intended to be an introduction to developing in Forrest,
+      specifically, for those developers without a strong Cocoon background.
+      Some key concepts in Forrest like sitemaps, pipelines, and locationmaps
+      can be challenging enough to understand without also struggling with the
+      fundamental development chores of debugging, extension methods, etc. The
+      goal of this document is to reduce the steep learning curve by providing
+      answers to some really practical Forrest development questions.
     </p>
   </purpose>
-
   <prerequisites title="Prerequisites">
     <ul>
       <li>
@@ -80,28 +77,25 @@
       </li>
     </ul>
   </prerequisites>
-
   <steps title="Development techniques and scenarios">
     <p>
-      Various scenarios are utilised to describe aspects of development.
-      Bear in mind that there are many
-      ways to do things. Each developer has different tools and habits,
-      and different operating systems are used. So you will need to glean
-      the principles and apply them to your own situation.
+      Various scenarios are utilised to describe aspects of development. Bear in
+      mind that there are many ways to do things. Each developer has different
+      tools and habits, and different operating systems are used. So you will
+      need to glean the principles and apply them to your own situation.
     </p>
-
     <p>
-      This document assumes that you intend to contribute some parts of
-      your work back to the project. Techniques for network-based collaborative
+      This document assumes that you intend to contribute some parts of your
+      work back to the project. Techniques for network-based collaborative
       development are encouraged.
     </p>
-
     <section id="dev-environment">
       <title>Development environment</title>
       <p>
         There is no *proper* dev environment. It really depends on your personal
-        preferences. In an opensource project there is huge variety of environments.
-        This makes it quite a challenge to keep sources consistent (see discussion below).
+        preferences. In an opensource project there is huge variety of
+        environments. This makes it quite a challenge to keep sources consistent
+        (see discussion below).
       </p>
       <p>
         Some people use vi or emacs, others use graphical editors, others use
@@ -109,66 +103,58 @@
       </p>
       <p>
         Ensure to <a href="site:catalog">configure</a> your xml editor to take
-        advantage of the local sets of DTDs provided by Forrest. This also explains how
-        to use xml validators such as 'xmllint'. If your editor of choice doesn't
-        validate XML, then most XML validation issues can be discovered using
-        <code>forrest validate-xdocs</code>
+        advantage of the local sets of DTDs provided by Forrest. This also
+        explains how to use xml validators such as 'xmllint'. If your editor of
+        choice doesn't validate XML, then most XML validation issues can be
+        discovered using <code>forrest validate-xdocs</code>
       </p>
       <p>
-        There really isn't much Java code in Forrest, but a Java Development Environment
-        such as Eclipse or any text editor of your choice will work just fine.
-        If you point Eclipse at the Forrest build file it will make life easy for you.
+        There really isn't much Java code in Forrest, but a Java Development
+        Environment such as Eclipse or any text editor of your choice will work
+        just fine. If you point Eclipse at the Forrest build file it will make
+        life easy for you.
       </p>
     </section>
-
     <section id="svn">
       <title>Using Subversion</title>
       <p>
-        The Subversion source control system is used for all ASF projects.
-        You can leverage this to ease your own development.
+        The Subversion source control system is used for all ASF projects. You
+        can leverage this to ease your own development.
       </p>
-
       <p>
-        The "trunk" is where all new development and bugfixing happens.
-        We aim to keep the trunk usable at all times.
+        The "trunk" is where all new development and bugfixing happens. We aim
+        to keep the trunk usable at all times.
       </p>
-
       <p>
-        Each version release is a "branch", such as "forrest_07_branch".
-        Crucial bugfixes are also applied to the relevant release branch.
+        Each version release is a "branch", such as "forrest_07_branch". Crucial
+        bugfixes are also applied to the relevant release branch.
       </p>
-
       <p>
-        Branches are also used for developing
-        complex new code which would otherwise disrupt the trunk. When the new
-        work is suitable, then that branch is merged back to the trunk as soon
-        as possible.
+        Branches are also used for developing complex new code which would
+        otherwise disrupt the trunk. When the new work is suitable, then that
+        branch is merged back to the trunk as soon as possible.
       </p>
-
       <p>
-        To get started, see the
-        <a href="site:build">instructions</a>
-        for obtaining the Apache Forrest sources via SVN.
+        To get started, see the <a href="site:build">instructions</a> for
+        obtaining the Apache Forrest sources via SVN.
       </p>
-
       <p>
-        Whether you use the svn command-line client or a fancy client,
-        then you still need to make sure you know how to operate SVN properly.
+        Whether you use the svn command-line client or a fancy client, then you
+        still need to make sure you know how to operate SVN properly.
         <a href="http://svnbook.red-bean.com/">http://svnbook.red-bean.com</a>
         is a must.
       </p>
-
       <section id="multiple">
         <title>Multiple working copies</title>
         <p>
           Most developers would have a number of separate SVN working copies.
           Hopefully you are brave enough to use the trunk for all your sites.
           Sometimes that is not possible, for example when you are
-          co-operativley managing a site with other people who are not so
-          brave, so you need to use a specific release. However consider using
-          the SVN release branch, rather than the release archive (tar or zip).
-          This enables you to easily keep up with bugfixes. You can also easily
-          see what local changes that you have made by using 'svn status; svn diff'.
+          co-operativley managing a site with other people who are not so brave,
+          so you need to use a specific release. However consider using the SVN
+          release branch, rather than the release archive (tar or zip). This
+          enables you to easily keep up with bugfixes. You can also easily see
+          what local changes that you have made by using 'svn status; svn diff'.
         </p>
         <p>
           Here is one layout ...
@@ -179,23 +165,22 @@
 forrest-trunk
         </source>
       </section>
-
       <section id="svn-email">
         <title>Watch email notifications for svn differences</title>
         <p>
           Either subscribe to the project's
-          <a href="site:mail-lists/forrest-svn">svn mailing list</a>
-          or monitor it via one of the mail archives. This enables you
-          to be immediately up-to-date with changes to the repositories.
-          The svn differences (diffs) are automatically sent whenever
-          a committer makes some changes.
+          <a href="site:mail-lists/forrest-svn">svn mailing list</a> or monitor
+          it via one of the mail archives. This enables you to be immediately
+          up-to-date with changes to the repositories. The svn differences
+          (diffs) are automatically sent whenever a committer makes some
+          changes.
         </p>
       </section>
-
       <section id="svn-find-break">
         <title>Updating svn backwards to find where something broke</title>
-        <p>Sometimes the addition of new features will break something. Often
-          it is difficult to find where the break occurred and what caused it.
+        <p>
+          Sometimes the addition of new features will break something. Often it
+          is difficult to find where the break occurred and what caused it.
           Updating your svn backwards will enable this.
         </p>
         <p>
@@ -224,10 +209,12 @@
 svn update -r HEAD.
         </source>
       </section>
-        <section id="svn-merge">
-          <title>Reverting Changes using SVN Merge</title>
-          <p>Two examples of using SVN Merge.</p>
-          <source>
+      <section id="svn-merge">
+        <title>Reverting Changes using SVN Merge</title>
+        <p>
+          Two examples of using SVN Merge.
+        </p>
+        <source>
 $ svn merge -r 400:300 /site-author/content/xdocs/index.xml /site-author/content/xdocs/index.xml
 
 or
@@ -236,25 +223,28 @@
 
 ... then commit as usual.
           </source>
-          <p> More information can be found at <a href="http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2">Common use-cases for merging</a> section of the Red Bean SVN Book.</p>
+        <p>
+          More information can be found at
+          <a href="http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2">Common
+          use-cases for merging</a> section of the Red Bean SVN Book.
+        </p>
       </section>
-
       <section id="svn-patch">
         <title>Creating patches</title>
-        <p>See 
-        <a href="site:contrib/patch">instructions</a> for creating and contributing patches.
-        Make sure to do three things before creating the patch:</p>
-
+        <p>
+          See <a href="site:contrib/patch">instructions</a> for creating and
+          contributing patches. Make sure to do three things before creating the
+          patch:
+        </p>
         <ul>
           <li>Do 'svn update' to be in sync with the repository in case someone else changed your files in SVN.</li>
           <li>Do 'svn status' to ensure that you are not including unnecessary changes.</li>
           <li>Do 'svn diff' to ensure that changes are what you expect.</li>
         </ul>
-        
-        <p>After creating the patch, open it with a text editor and review it.
+        <p>
+          After creating the patch, open it with a text editor and review it.
         </p>
       </section>
-
       <section id="tips-svn">
         <title>Tips</title>
         <ul>
@@ -265,13 +255,11 @@
           </li>
           <li>
             See all available branches and other repositories:
-            <a href="http://svn.apache.org/repos/asf/forrest/">http://svn.apache.org/repos/asf/forrest/</a>
-          </li>
+            <a href="http://svn.apache.org/repos/asf/forrest/">http://svn.apache.org/repos/asf/forrest/</a></li>
           <li>
             Use online repository browsers to quickly see past activity for
             the files that you are working on:
-            <a href="http://svn.apache.org/viewcvs.cgi/forrest/trunk/">http://svn.apache.org/viewcvs.cgi/forrest/trunk/</a>
-          </li>
+            <a href="http://svn.apache.org/viewcvs.cgi/forrest/trunk/">http://svn.apache.org/viewcvs.cgi/forrest/trunk/</a></li>
           <li>
             Use 'svn log foo.xsl' for a summary of recent activity and to
             see dates and revision numbers for changes.
@@ -279,70 +267,65 @@
         </ul>
       </section>
     </section>
-
     <section id="edit">
       <title>Editing content</title>
       <p>
-        See the 
-        <a href="site:faq/edit-content">FAQ</a>.
-        Basically any editor can
-        be used, because Forrest treats the editing of content as a separate
+        See the <a href="site:faq/edit-content">FAQ</a>. Basically any editor
+        can be used, because Forrest treats the editing of content as a separate
         concern. Be sure to configure the editor to find local copies of DTDs.
       </p>
-
       <section id="code-style">
         <title>Code style guidelines</title>
         <p>
-          Consistent code makes everyone's life easier.
-          See the 
-          <a href="http://cocoon.apache.org/community/committer.html">Apache Cocoon tips</a>.
-          We don't get too hung up on style, but those few basic things are important.
-          However we know that coding style is mixed, so just follow the same style
-          as that which exists in the file you are editing. We can occasionally clean up later.
+          Consistent code makes everyone's life easier. See the
+          <a href="http://cocoon.apache.org/community/committer.html">Apache
+          Cocoon tips</a>. We don't get too hung up on style, but those few
+          basic things are important. However we know that coding style is
+          mixed, so just follow the same style as that which exists in the file
+          you are editing. We can occasionally clean up later.
         </p>
         <p>
-          Don't change anything that is not necessary. Remember that people need to be
-          able to read the differences on the svn@forrest mailing list.
+          Don't change anything that is not necessary. Remember that people need
+          to be able to read the differences on the svn@forrest mailing list.
         </p>
       </section>
-
       <section id="whitespace">
         <title>Whitespace</title>
         <p>
-          For new files, use spaces instead of tabs (java files have four-space indentation,
-          xml files and other text files have two-space indentation).
+          For new files, use spaces instead of tabs (java files have four-space
+          indentation, xml files and other text files have two-space
+          indentation).
         </p>
         <p>
           Don't let your editor automatically change the whitespace for existing
           files.
         </p>
         <p>
-          We know that many files in SVN do not have consistent whitespace.
-          This issue is continually being addressed. Please don't attempt
-          to rectify whitespace mixed up with other changes. This makes the
-          important changes difficult to see. Occasionally committers will
-          rectify whitespace for a set of files, when they know that no-one
-          else is working on that set.
+          We know that many files in SVN do not have consistent whitespace. This
+          issue is continually being addressed. Please don't attempt to rectify
+          whitespace mixed up with other changes. This makes the important
+          changes difficult to see. Occasionally committers will rectify
+          whitespace for a set of files, when they know that no-one else is
+          working on that set.
         </p>
         <fixme author="open">
-          The issues of whitespace and line endings needs to be very clearly described.
-          See some
-          <a href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=112450886218545">mail discussion</a>
-          references.
+          The issues of whitespace and line endings needs to be very clearly
+          described. See some
+          <a href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=112450886218545">mail
+          discussion</a> references.
         </fixme>
       </section>
-
       <section id="line-length">
         <title>Line length</title>
         <p>
           If each paragraph of an xml source document is one enourmous long
-          line, then it is extremely difficult to know the changes with the
-          SVN diffs. Developers and especially committers, need to be able to
+          line, then it is extremely difficult to know the changes with the SVN
+          diffs. Developers and especially committers, need to be able to
           efficiently review the changes. Fold long lines to a sensible
-          line-length (normally 80-characters wide but not more than 120 characters).
+          line-length (normally 80-characters wide but not more than 120
+          characters).
         </p>
       </section>
-
       <section id="review">
         <title>Use 'forrest run' for immediate gratification</title>
         <p>
@@ -352,17 +335,14 @@
           references.
         </p>
         <p>
-          In the dynamic 'forrest run' mode, you will get some feedback
-          about some xml validation errors. However, it is better to treat
-          validation as a separate concern. Use an xml editor or command-line
-          tools such as "xmllint". As a last resort, you can use
-          'forrest validate-xdocs'.
+          In the dynamic 'forrest run' mode, you will get some feedback about
+          some xml validation errors. However, it is better to treat validation
+          as a separate concern. Use an xml editor or command-line tools such as
+          "xmllint". As a last resort, you can use 'forrest validate-xdocs'.
         </p>
       </section>
-
       <section id="tips-edit">
         <title>Tips</title>
-
         <ul>
           <li>
 ####
@@ -370,11 +350,11 @@
         </ul>
       </section>
     </section>
-
     <section id="sitemap">
       <title>Understanding the Cocoon sitemap</title>
       <p>
-        The Cocoon sitemap is essential for Forrest developers. See some introductions ....
+        The Cocoon sitemap is essential for Forrest developers. See some
+        introductions ....
       </p>
       <ul>
         <li><a href="site:sitemap-ref">Forrest sitemap reference</a>.</li>
@@ -386,48 +366,43 @@
         <li><a href="ext:cocoon/sitemap">Cocoon sitemap</a>.</li>
         <li><a href="ext:cocoon/protocols">Cocoon protocols</a>, i.e. cocoon:/ and
           cocoon:// and context:// and resource:// etc. and the
-          <a href="ext:cocoon/file-url">file://</a>
-        </li>
+          <a href="ext:cocoon/file-url">file://</a></li>
       </ul>
     </section>
-
     <section id="debug">
       <title>Debugging and profiling techniques</title>
-
       <section id="debug-logfiles">
         <title>View logfiles</title>
         <p>
-          The log files in WEB-INF/logs are indispensible when it comes
-          to debugging sitemaps. While ERRORs will generally always print in the log files, 
-          while you're debugging something you may find it useful to also customize log output in
-          the "logkit.xconf" in webapp/WEB-INF and raise the level of some loggers to WARN.
-      </p>
+          The log files in WEB-INF/logs are indispensible when it comes to
+          debugging sitemaps. While ERRORs will generally always print in the
+          log files, while you're debugging something you may find it useful to
+          also customize log output in the "logkit.xconf" in webapp/WEB-INF and
+          raise the level of some loggers to WARN.
+        </p>
         <p>
-          This <a href="site:faq/logs">FAQ</a>
-          describes the location of the Cocoon logfiles and their
-          configuration.
+          This <a href="site:faq/logs">FAQ</a> describes the location of the
+          Cocoon logfiles and their configuration.
         </p>
       </section>
-
       <section id="debug-modes">
         <title>Cocoon Running Modes</title>
         <p>
-          Cocoon startup reads additional properties from various files.
-          This enables some different properties to be used for production or development.
-          By default, Forrest uses Cocoon in running mode "dev".
-          So it first reads from <code>main/webapp/WEB-INF/properties/core.properties</code>
-          then from
+          Cocoon startup reads additional properties from various files. This
+          enables some different properties to be used for production or
+          development. By default, Forrest uses Cocoon in running mode "dev". So
+          it first reads from
+          <code>main/webapp/WEB-INF/properties/core.properties</code> then from
           <code>main/webapp/WEB-INF/properties/dev/core.properties</code>
         </p>
         <p>
-          To use a different mode, say "prod" for production, add to the 
+          To use a different mode, say "prod" for production, add to the
           forrest.jvmargs in your forrest.properties file:
           <code>-Dorg.apache.cocoon.mode=prod</code> and provide the relevant
-           properties in a matching "prod" sub-directory of
+          properties in a matching "prod" sub-directory of
           <code>main/webapp/WEB-INF/properties</code>
         </p>
       </section>
-
       <section id="debug-intermediate">
         <title>View intermediate processing</title>
         <p>
@@ -435,155 +410,157 @@
           processing steps between taking in the source and outputting the end
           result. When you know these you can do 'forrest run' and request the
           intermediate documents, such as "http://localhost:8888/body-index.xml"
-          which will return the intermediate processing of the body of the document.
+          which will return the intermediate processing of the body of the
+          document.
         </p>
         <p>
-          The techniques described below help you to be aware of the intermediate processing steps.
+          The techniques described below help you to be aware of the
+          intermediate processing steps.
         </p>
       </section>
-
       <section id="debug-cocoon-profiler">
         <title>Using Cocoon sitemap profiler</title>
         <p>
-          Cocoon provides a simple profiler to analyse itself.
-          This enables us to list the various sitemap pipelines and
-          components that are being used, how much time was used
-          by each, whether each component uses the Cocoon cache,
-          and show the actual xml data.
+          Cocoon provides a simple profiler to analyse itself. This enables us
+          to list the various sitemap pipelines and components that are being
+          used, how much time was used by each, whether each component uses the
+          Cocoon cache, and show the actual xml data.
         </p>
         <p>
-          Note that the profiler is not used by default. To switch
-         it on, edit <code>main/webapp/sitemap.xmap</code> and search
-         for "profiler". Follow the instructions there to replace the
-          standard "map:pipe" components with the profiling pipes.
+          Note that the profiler is not used by default. To switch it on, edit
+          <code>main/webapp/sitemap.xmap</code> and search for "profiler".
+          Follow the instructions there to replace the standard "map:pipe"
+          components with the profiling pipes.
         </p>
         <p>
-          Now start your application as normal using 'forrest run'
-          and request localhost:8888/index.html three or four times
-          to populate the profiler with data.
+          Now start your application as normal using 'forrest run' and request
+          localhost:8888/index.html three or four times to populate the profiler
+          with data.
         </p>
         <p>
-          Now request the special uri localhost:8888/cprofile.html
-          to see the results. Start at the "index.html" request,
-          then follow the processing. (If the table is empty, then
-          you either forgot to do some requests before looking for results,
-          or forgot to switch on the profiler in sitemap.)
+          Now request the special uri localhost:8888/cprofile.html to see the
+          results. Start at the "index.html" request, then follow the
+          processing. (If the table is empty, then you either forgot to do some
+          requests before looking for results, or forgot to switch on the
+          profiler in sitemap.)
         </p>
         <p>
-          NOTE: Do not forget to turn off the profiler in 
+          NOTE: Do not forget to turn off the profiler in
           <code>main/webapp/sitemap.xmap</code> when finished.
         </p>
       </section>
-
       <section id="debug-sitemap-exec">
         <title>Using Cocoon sitemap execution logger</title>
         <p>
-          In main/webapp/WEB-INF/xconf/forrest-core.xconf
-          search for "sitemap execution" and uncomment the component.
-          For each sitemap component that is executed, a message will go to
-          WEB-INF/logs/debug.log
+          In main/webapp/WEB-INF/xconf/forrest-core.xconf search for "sitemap
+          execution" and uncomment the component. For each sitemap component
+          that is executed, a message will go to WEB-INF/logs/debug.log
         </p>
       </section>
-
       <section id="debug-logtransformer">
         <title>Using Cocoon LogTransformer</title>
         <p>
-          LogTransformers can be inserted in the sitemaps. This will write
-          the sax events at that point into a named log file.
-          Here is an example (the logfile will be written relative to this
-          particular sitemap) ...
+          LogTransformers can be inserted in the sitemaps. This will write the
+          sax events at that point into a named log file. Here is an example
+          (the logfile will be written relative to this particular sitemap) ...
         </p>
-      <source><![CDATA[
+        <source>
+<![CDATA[
 <map:match pattern="*.html">
-  <map:generate src="sources/{1}.xml"/>]]><strong><![CDATA[
+  <map:generate src="sources/{1}.xml"/>]]><strong>
+<![CDATA[
   <map:transform type="log">
     <map:parameter name="logfile" value="my-1.log"/>
     <map:parameter name="append" value="no"/>
-  </map:transform>]]></strong><![CDATA[
+  </map:transform>]]></strong>
+<![CDATA[
   <map:transform src="stylesheets/source-to-table.xsl"/>
-  <map:transform src="stylesheets/table-to-page.xsl"/>]]><strong><![CDATA[
+  <map:transform src="stylesheets/table-to-page.xsl"/>]]><strong>
+<![CDATA[
   <map:transform type="log">
     <map:parameter name="logfile" value="my-2.log"/>
     <map:parameter name="append" value="no"/>
-  </map:transform>]]></strong><![CDATA[
+  </map:transform>]]></strong>
+<![CDATA[
   <map:transform src="stylesheets/page-to-html.xsl"/>
   <map:serialize type="html"/>
 </map:match>
-]]></source>
+]]>
+        </source>
         <p>
-          Another use for this technique is when you are not sure which
-          path is being taken through the sitemap. Add various LogTransformers
-          with different filenames and see which one gets triggered.
+          Another use for this technique is when you are not sure which path is
+          being taken through the sitemap. Add various LogTransformers with
+          different filenames and see which one gets triggered.
         </p>
       </section>
-
       <section id="debug-validation">
         <title>Using Cocoon Validation Transformers</title>
         <p>
           Validating Transformers can be inserted in the sitemaps to validate
-          the xml stream at that stage.
-          Enables RELAX NG validation and W3C XML Schema validation using
-          Jing and Xerces.
+          the xml stream at that stage. Enables RELAX NG validation and W3C XML
+          Schema validation using Jing and Xerces.
         </p>
         <p>
-          The Validation Block is already added to Forrest and configured.
-          To use it simply add entries to your sitemap like this:
+          The Validation Block is already added to Forrest and configured. To
+          use it simply add entries to your sitemap like this:
         </p>
-      <source><![CDATA[
+        <source>
+<![CDATA[
 ...
 <map:transform type="validation-report"
   src="{forrest:forrest.context}/resources/schema/relaxng/unstable/any.rng"/>
 ...
-]]></source>
-        <p>See
-          <a href="http://marc.theaimsgroup.com/?t=112541971900003">Pier's note to cocoon-dev</a> and
-
-          Cocoon documentation:
-          <a href="http://cocoon.zones.apache.org/daisy/documentation/components/1058/g2/684.html">ValidatingTransformer</a> and
+]]>
+        </source>
+        <p>
+          See <a href="http://marc.theaimsgroup.com/?t=112541971900003">Pier's
+          note to cocoon-dev</a> and Cocoon documentation:
+          <a href="http://cocoon.zones.apache.org/daisy/documentation/components/1058/g2/684.html">ValidatingTransformer</a>
+          and
           <a href="http://cocoon.zones.apache.org/daisy/documentation/components/1058/g2/691.html">ValidationReportTransformer</a>.
         </p>
       </section>
-
       <section id="debug-java">
         <title>Java code</title>
-        <p>There are two ways to debug your java code. The first is through embedded
-        logging, the second is by tracing the codes execution.</p>
         <p>
-          You may find <code>getLogger().debug()</code> useful for
-          understanding the processing that goes on. You can then open the page that will
-          use the selected code and use the log files mentioned above to look for
+          There are two ways to debug your java code. The first is through
+          embedded logging, the second is by tracing the codes execution.
+        </p>
+        <p>
+          You may find <code>getLogger().debug()</code> useful for understanding
+          the processing that goes on. You can then open the page that will use
+          the selected code and use the log files mentioned above to look for
           the information message.
         </p>
-        <p>To step through the java code you need to run forrest with Java debugging turned
-        on. The <code>forrest.jvmargs</code>code> property in the <code>forrest.properties</code>
-        file can be used to start forrest in debug mode on a specific port. For example:</p>
-        
+        <p>
+          To step through the java code you need to run forrest with Java
+          debugging turned on. The <code>forrest.jvmargs</code>code> property in
+          the <code>forrest.properties</code> file can be used to start forrest
+          in debug mode on a specific port. For example:
+        </p>
         <source>forrest.jvmargs=-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n</source>
       </section>
-
       <section id="debug-links">
         <title>Finding broken internal links</title>
         <p>
-          Do 'forrest site' to produce the whole documentation set.
-          Cocoon will report its progress and reveal any problems.
-          This <a href="site:faq/build_msg_a">FAQ</a>
-          explains the messages that Cocoon sends to standard output.
-          Broken links are also reported to a special file, which also shows
-          the source file containing the break. The location
-          of this file is reported when Cocoon starts.
+          Do 'forrest site' to produce the whole documentation set. Cocoon will
+          report its progress and reveal any problems. This
+          <a href="site:faq/build_msg_a">FAQ</a> explains the messages that
+          Cocoon sends to standard output. Broken links are also reported to a
+          special file, which also shows the source file containing the break.
+          The location of this file is reported when Cocoon starts.
         </p>
         <p>
-          Broken links are also reported in 'forrest run' mode.
-          Use your mouse to point to each link. The browser status bar
-          will show "error:..." instead of the actual URL.
+          Broken links are also reported in 'forrest run' mode. Use your mouse
+          to point to each link. The browser status bar will show "error:..."
+          instead of the actual URL.
         </p>
         <p>
           The most common cause is that the entry is missing in the site.xml
-          configuration file or the link in your source document is not
-          using the correct name for the "site:..." value.
+          configuration file or the link in your source document is not using
+          the correct name for the "site:..." value.
         </p>
       </section>
-
       <section id="tips-debug">
         <title>Tips</title>
         <ul>
@@ -593,48 +570,51 @@
           </li>
         </ul>
       </section>
-
       <note>
-        The next two sections describe the configuration of profiling tools but they are not
-        integrated with the IDE.  If you can figure out how to properly configure them for 
-        integrated operation with the IDE, please provide a documentation patch.
+        The next two sections describe the configuration of profiling tools but
+        they are not integrated with the IDE. If you can figure out how to
+        properly configure them for integrated operation with the IDE, please
+        provide a documentation patch.
       </note>
-      
       <section id="profile-yourkit">
         <title>Profiling Forrest with YourKit</title>
         <p>
-          Assuming you have the YourKit software installed you simply need to do two things to
-          profile a particular Forrest Project. First, you need to add *YourKit Home*\bin\win32 to
-          your PATH environment variable - where *YourKit Home* is the installation directory of that 
-          software.  Next you need to add the following to your forrest.properties file for the project.
+          Assuming you have the YourKit software installed you simply need to do
+          two things to profile a particular Forrest Project. First, you need to
+          add *YourKit Home*\bin\win32 to your PATH environment variable - where
+          *YourKit Home* is the installation directory of that software. Next
+          you need to add the following to your forrest.properties file for the
+          project.
         </p>
         <source>forrest.jvmargs=-agentlib:yjpagent</source>
         <p>
-          You are now all set, simply type 'forrest run', then open up YourKit and select "Connect 
-          to locally running profiled application...".   If you don't see the types of objects that you
-          expected, check the current filters - YourKit seems to filter out org.apache.* namespaces by
-          default.
+          You are now all set, simply type 'forrest run', then open up YourKit
+          and select "Connect to locally running profiled application...". If
+          you don't see the types of objects that you expected, check the
+          current filters - YourKit seems to filter out org.apache.* namespaces
+          by default.
         </p>
       </section>
       <section id="profile-netbeans">
         <title>Profiling Forrest with Netbeans</title>
         <p>
-          Assuming you have the Netbeans IDE installed, you simply need to do a couple things to 
-          profile a particular Forrest Project.  First, you need to add 
-          *Netbeans Home*\profiler1\lib\deployed\jdk142\windows to your path.  Obviously, this needs
-          to be slightly modified for a Unix machine.  Now, you need to add the following line to your
-          forrest.properties file for the project (replacing *NetbeansHome* with the path to your install).
+          Assuming you have the Netbeans IDE installed, you simply need to do a
+          couple things to profile a particular Forrest Project. First, you need
+          to add *Netbeans Home*\profiler1\lib\deployed\jdk142\windows to your
+          path. Obviously, this needs to be slightly modified for a Unix
+          machine. Now, you need to add the following line to your
+          forrest.properties file for the project (replacing *NetbeansHome* with
+          the path to your install).
         </p>
         <source>forrest.jvmargs=-agentpath:C:\*NetbeansHome*\\profiler1\\lib\\deployed\\jdk15\\windows\\
 profilerinterface.dll=\C:\\*NetbeansHome*\\profiler1\\lib\\,5140</source>
         <p>
-          You are now all set, simply type 'forrest run', then open up the Netbeans IDE with your Forrest 
-          project.  Click Profile->Attach Profiler and make selections appropriate to what you are trying 
-          to achieve. 
+          You are now all set, simply type 'forrest run', then open up the
+          Netbeans IDE with your Forrest project. Click Profile->Attach Profiler
+          and make selections appropriate to what you are trying to achieve.
         </p>
       </section>
     </section>
-
     <section id="find">
       <title>Finding the relevant sources</title>
       <p>
@@ -648,27 +628,24 @@
           exploring some of the sources.
         </p>
         <p>
-          The UNIX tools find, grep, and sed are very powerful. We need a
-          helper script, otherwise 'find' is going to report matches for
-          the hidden .svn files and also files in /build/ directories.
+          The UNIX tools find, grep, and sed are very powerful. We need a helper
+          script, otherwise 'find' is going to report matches for the hidden
+          .svn files and also files in /build/ directories.
         </p>
-
         <source>
 echo "sed '/\.svn/d;/\/build\//d;/\/work\//d'" > ~/bin/exclude-find-svn
 chmod +x ~/bin/exclude-find-svn</source>
         <p>
-          Now we will run find, use grep to search for the pattern in each
-          file and list the filenames. However, there is a stack of
+          Now we will run find, use grep to search for the pattern in each file
+          and list the filenames. However, there is a stack of
           forrest.properties files from the plugins, and there is i18n:text
-          being used in the viewHelper plugin, and some DTDs.
-          So weed them out ...
+          being used in the viewHelper plugin, and some DTDs. So weed them out
+          ...
         </p>
-
         <source>
 cd /svn/asf/forrest-trunk
 find . -type f | xargs grep -l "i18n" | ~/bin/exclude-find-svn \
  | grep -v "forrest.properties" | grep -v viewHelper | grep -v "\/schema\/"</source>
-
         <p>
           The list of files shows that there is an FAQ about i18n, there are
           various sitemaps in main/webapp/, some stylesheets in
@@ -681,14 +658,13 @@
 grep i18n *.*</source>
         <p>
           Shows that five sitemaps are involved in some way. Always start with
-          sitemap.xamp and forrest.xmap as they do initial processing and
-          then delegate to other sitemaps. Open each file in your editor,
-          and search within for each "i18n" match. See that the xslt transformer 
-          is declared to use i18n, then further down the page the "skinit"
-          pipeline uses the i18n transformer only if i18n is switched on.
+          sitemap.xamp and forrest.xmap as they do initial processing and then
+          delegate to other sitemaps. Open each file in your editor, and search
+          within for each "i18n" match. See that the xslt transformer is
+          declared to use i18n, then further down the page the "skinit" pipeline
+          uses the i18n transformer only if i18n is switched on.
         </p>
       </section>
-
       <section id="tips-find">
         <title>Tips</title>
         <ul>
@@ -698,7 +674,6 @@
         </ul>
       </section>
     </section>
-
 <!-- template
     <section id="foo">
       <title>Foo</title>
@@ -722,9 +697,7 @@
       </section>
     </section>
 -->
-
   </steps>
-
   <faqs id="faqs">
     <title>Frequently Asked Questions</title>
     <faqsection id="faq-general">
@@ -732,51 +705,44 @@
       <faq id="faq-1-1">
         <question>FAQ 1
         </question>
-
         <answer>
           <p>
-####
+            ####
           </p>
         </answer>
       </faq>
     </faqsection>
-
     <faqsection id="faq-other">
       <title>Other issues</title>
       <faq id="faq-2-1">
         <question>FAQ 2.1</question>
-
         <answer>
           <p>
-###
+            ###
           </p>
         </answer>
       </faq>
     </faqsection>
   </faqs>
-
   <tips title="Tips">
     <p>
-      This is a collection of general tips that do not fit in the sections above. 
+      This is a collection of general tips that do not fit in the sections
+      above.
     </p>
-
     <section id="tip-howto">
       <title>Explanations about howto topics on the mailing lists</title>
-
       <p>
         Often there are useful discussions on the mailing lists which explain
         how to do certain tasks. If you don't have time to summarise that and
-        add to this howto document, then please consider just adding a tip
-        which links to the email discussion. Later someone else can summarise.
+        add to this howto document, then please consider just adding a tip which
+        links to the email discussion. Later someone else can summarise.
       </p>
     </section>
   </tips>
-
   <references title="References">
     <p>
       These are some other documents that are useful for developers.
     </p>
-
     <ul>
       <li>
 ###

Modified: forrest/trunk/site-author/content/xdocs/howto-howto.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/howto-howto.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/howto-howto.xml (original)
+++ forrest/trunk/site-author/content/xdocs/howto-howto.xml Mon Apr  9 20:48:52 2007
@@ -20,161 +20,159 @@
 <howto>
   <header>
     <title>How to write a How-To</title>
-
     <version>0.3</version>
-
-    <abstract>This How-To describes the steps necessary to write a How-To
-    document. Writing documentation is a valuable way to give back to the
-    community.</abstract>
-
+    <abstract>
+      This How-To describes the steps necessary to write a How-To document.
+      Writing documentation is a valuable way to give back to the community.
+    </abstract>
     <last-modified-content-date date="2005-07-18" />
   </header>
-
   <audience title="Intended Audience">
-    <p>Users who are ready to share their knowledge and experiences with the
-    community.</p>
+    <p>
+      Users who are ready to share their knowledge and experiences with the
+      community.
+    </p>
   </audience>
-
   <purpose title="Purpose">
-    <p>These guidelines are based on successful how-to document structures
-    used by other open source projects with diverse author groups. Following
-    these tried and true guidelines will help to ensure the effectiveness of
-    your work.</p>
+    <p>
+      These guidelines are based on successful how-to document structures used
+      by other open source projects with diverse author groups. Following these
+      tried and true guidelines will help to ensure the effectiveness of your
+      work.
+    </p>
   </purpose>
-
   <prerequisites title="Prerequisites">
-    <p>How-To authors should have:</p>
-
+    <p>
+      How-To authors should have:
+    </p>
     <ul>
       <li>A unique How-To topic, related to using Forrest, which fulfills a
       specific need. Look at existing How-Tos to find a niche for your work.
       Consider posting your idea for the How-To to user mailing list, to make
       sure another author's draft is not already in process.</li>
-
       <li>A sufficient ability in English to write the document. However, we would
       rather that you just make a start, as the community can help to
       fine-tune the document.</li>
-      
       <li>Copy this template document "howto-howto.xml" to be modified with
       your own content as necessary.</li>
-
       <li>An understanding of the How-To document structure. Just use this
       template document and you will be safe.
       Make sure you run '<code>forrest validate-xdocs</code>' before
       contributing your document.</li>
     </ul>
-
-    <note>See the <a href="site:howto-v20-dtd">DTD documentation</a>
-    which explains the document structure.</note>
+    <note>
+      See the <a href="site:howto-v20-dtd">DTD documentation</a> which explains
+      the document structure.
+    </note>
   </prerequisites>
-
   <steps title="Steps">
-    <p>Here is how to proceed.</p>
-
+    <p>
+      Here is how to proceed.
+    </p>
     <section id="overview">
       <title>Write the Overview</title>
-
-      <p>An overview helps potential readers to determine quickly if a
-      particular How-To matches their interests or needs. In a few sentences,
-      summarize the main points of your How-To. Make sure to include any
-      critical definitions which will help readers evaluate the utility of
-      your How-To. Consider writing the overview last, after you have
-      completed all other sections.</p>
+      <p>
+        An overview helps potential readers to determine quickly if a particular
+        How-To matches their interests or needs. In a few sentences, summarize
+        the main points of your How-To. Make sure to include any critical
+        definitions which will help readers evaluate the utility of your How-To.
+        Consider writing the overview last, after you have completed all other
+        sections.
+      </p>
     </section>
-
     <section id="audience">
       <title>Describe your Intended Audience</title>
-
-      <p>If your How-To is targetted at a specific audience, describe it here.
-      For example, potential readers will have different levels of skill using
-      Forrest. They will also bring different areas of expertise and
-      backgrounds to their How-To learning experience. When you clarify your
-      target audience up front, you will save all other readers time and
-      confusion.</p>
+      <p>
+        If your How-To is targetted at a specific audience, describe it here.
+        For example, potential readers will have different levels of skill using
+        Forrest. They will also bring different areas of expertise and
+        backgrounds to their How-To learning experience. When you clarify your
+        target audience up front, you will save all other readers time and
+        confusion.
+      </p>
     </section>
-
     <section id="purpose">
       <title>State the Purpose</title>
-
-      <p>State the purpose of your How-To. Explain how the reader will benefit
-      by reading it. Give your reader an incentive or two to continue.</p>
+      <p>
+        State the purpose of your How-To. Explain how the reader will benefit by
+        reading it. Give your reader an incentive or two to continue.
+      </p>
     </section>
-
     <section id="prerequisites">
       <title>List any Prerequisites</title>
-
-      <p>Inform your reader about any required knowledge, configuration, or
-      resources they may need before stepping through your How-To. Assist them
-      in this preparation by linking to other useful resources on the Forrest
-      site or the web. Helping your readers to prepare increases the
-      likelihood that they will continue reading your How-To.</p>
+      <p>
+        Inform your reader about any required knowledge, configuration, or
+        resources they may need before stepping through your How-To. Assist them
+        in this preparation by linking to other useful resources on the Forrest
+        site or the web. Helping your readers to prepare increases the
+        likelihood that they will continue reading your How-To.
+      </p>
     </section>
-
     <section id="steps">
       <title>Describe the Steps of your How-To</title>
-
-      <p>In a precise, step-by-step approach, walk your reader through the
-      process. Make sure your reader can reproduce your intended result by
-      following your exact steps. Make the learning process efficient by
-      supplying sample code snippets or configuration details as
-      necessary.</p>
+      <p>
+        In a precise, step-by-step approach, walk your reader through the
+        process. Make sure your reader can reproduce your intended result by
+        following your exact steps. Make the learning process efficient by
+        supplying sample code snippets or configuration details as necessary.
+      </p>
     </section>
-
     <section id="extension">
       <title>Extend the Learning</title>
-
-      <p>Provide your reader with a few real-world examples of how the
-      techniques or capabilities gained from your How-To could be applied.
-      Reward the reader for successfully completing the How-To with a few
-      ideas about how it will pay off.</p>
+      <p>
+        Provide your reader with a few real-world examples of how the techniques
+        or capabilities gained from your How-To could be applied. Reward the
+        reader for successfully completing the How-To with a few ideas about how
+        it will pay off.
+      </p>
     </section>
-
     <section id="summarize">
       <title>Summarize the Entire Process</title>
-
-      <p>In a few sentences, remind the reader what they have just learned.
-      This helps to reinforce the main points of your How-To.</p>
+      <p>
+        In a few sentences, remind the reader what they have just learned. This
+        helps to reinforce the main points of your How-To.
+      </p>
     </section>
-
     <section id="tips">
       <title>Additional Tips or FAQs</title>
-
-      <p>In some cases, step-by-step instructions simply aren't enough. Use
-      this section to pass on any other tips or frequently asked questions.
-      Anticipating the needs of your readers will increase the overall success
-      of your writing effort.</p>
+      <p>
+        In some cases, step-by-step instructions simply aren't enough. Use this
+        section to pass on any other tips or frequently asked questions.
+        Anticipating the needs of your readers will increase the overall success
+        of your writing effort.
+      </p>
     </section>
-
     <section id="references">
       <title>References</title>
-
-      <p>Remember to acknowledge any third-party resources or individuals who
-      contributed to the development of your How-To. Consider providing links
-      for those motivated readers who want to learn more.</p>
+      <p>
+        Remember to acknowledge any third-party resources or individuals who
+        contributed to the development of your How-To. Consider providing links
+        for those motivated readers who want to learn more.
+      </p>
     </section>
-
     <section id="contribute">
       <title>Submit via the project issue tracker</title>
-
-      <p>Create an attachment for your How-To document, and submit it via the
-      project <a href="site:bugs">issue tracker</a>.</p>
+      <p>
+        Create an attachment for your How-To document, and submit it via the
+        project <a href="site:bugs">issue tracker</a>.
+      </p>
     </section>
-
     <section id="feedback">
       <title>Get some feedback</title>
-
-      <p>When the committers have added your document then it will be
-      available for everyone to to build upon and enhance. Feedback will
-      happen via the <a href="site:mail-lists">mailing lists</a>.</p>
+      <p>
+        When the committers have added your document then it will be available
+        for everyone to to build upon and enhance. Feedback will happen via the
+        <a href="site:mail-lists">mailing lists</a>.
+      </p>
     </section>
   </steps>
-
   <extension title="Extension">
-    <p>Solutions can be extended to cover many different problem domains. A
-    nearly unlimited number of potential How-To topics, from simple to
-    complex, are available right now, limited only by your imagination.</p>
+    <p>
+      Solutions can be extended to cover many different problem domains. A
+      nearly unlimited number of potential How-To topics, from simple to
+      complex, are available right now, limited only by your imagination.
+    </p>
   </extension>
-
   <faqs id="faqs">
     <title>Frequently Asked Questions</title>
     <faqsection id="faq-general">
@@ -182,51 +180,51 @@
       <faq id="faq-difference">
         <question>What is the difference between a How-To and a
         tutorial?</question>
-
         <answer>
-          <p>The goal of a How-To is to help the reader to accomplish a specific
-          task with clear and consise instructions. While tutorials may contain
-          How-To-like instructions and content, they also include additional
-          background and conceptual content to help teach their readers higher
-          order concepts along the way. How-Tos are concerned about filling an
-          immediate, short-term need. Tutorials often provide long-term
-          knowledge which can be applied across a range of needs.</p>
+          <p>
+            The goal of a How-To is to help the reader to accomplish a specific
+            task with clear and consise instructions. While tutorials may
+            contain How-To-like instructions and content, they also include
+            additional background and conceptual content to help teach their
+            readers higher order concepts along the way. How-Tos are concerned
+            about filling an immediate, short-term need. Tutorials often provide
+            long-term knowledge which can be applied across a range of needs.
+          </p>
         </answer>
       </faq>
     </faqsection>
-
     <faqsection id="faq-style">
       <title>Style issues</title>
       <faq id="spelling">
         <question>What spelling convention should I follow?</question>
-
         <answer>
-          <p>Use whatever spelling convention (American, British, etc.) that is
-          most intuitive to you.</p>
+          <p>
+            Use whatever spelling convention (American, British, etc.) that is
+            most intuitive to you.
+          </p>
         </answer>
       </faq>
     </faqsection>
   </faqs>
-
   <tips title="Tips">
     <section id="tip-dtd">
       <title>How-To dtd</title>
-
-      <p>The document structure is likely to change at some time. Please note that
-      this HOWTO page is likely to change as well.</p>
+      <p>
+        The document structure is likely to change at some time. Please note
+        that this HOWTO page is likely to change as well.
+      </p>
     </section>
   </tips>
-
   <references title="References">
-    <p>This is not the first, nor will it be the last, How-To on writing
-    How-Tos. For other ideas and opinions on the matter, check out the
-    following sources.</p>
-
+    <p>
+      This is not the first, nor will it be the last, How-To on writing How-Tos.
+      For other ideas and opinions on the matter, check out the following
+      sources.
+    </p>
     <ul>
       <li>Joel D. Canfield's <a
       href="http://www.evolt.org/article/How_To_Write_A_How_To/9741/18250/index.html">How
       to Write a How-To</a> on evolt.org.</li>
-
       <li>The Linux Documentation Project's <a
       href="http://www.tldp.org/HOWTO/HOWTO-INDEX/index.html">HOWTO</a>
       index page provides many excellent How-To documents to inspire your

Modified: forrest/trunk/site-author/content/xdocs/index.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/index.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/index.xml (original)
+++ forrest/trunk/site-author/content/xdocs/index.xml Mon Apr  9 20:48:52 2007
@@ -20,34 +20,30 @@
   <header>
     <title>Welcome to Apache Forrest</title>
     <abstract>
-      Apache Forrest is a publishing framework that transforms
-      input from various sources into a unified presentation
-      in one or more output formats. The modular and extensible
-      plugin architecture is based on Apache Cocoon and relevant
-      standards, which separates presentation from content.
-      Forrest can generate static documents, or be used as a
-      dynamic server, or be deployed by its automated facility.
+      Apache Forrest is a publishing framework that transforms input from
+      various sources into a unified presentation in one or more output formats.
+      The modular and extensible plugin architecture is based on Apache Cocoon
+      and relevant standards, which separates presentation from content. Forrest
+      can generate static documents, or be used as a dynamic server, or be
+      deployed by its automated facility.
     </abstract>
   </header>
   <body>
     <p>
       The Apache Forrest project uses the opensource
-      <link href="site:license">Apache License 2.0</link>
-      and adheres to
+      <link href="site:license">Apache License 2.0</link> and adheres to
       <link href="site:way">open development</link> ideals.
     </p>
-
-      <note>
-        Please realise that Forrest is still pre-1.0 release version.
-        It is certainly usable for those who are prepared to move with it.
-        See more notes about <link href="#status">status</link> below.
-      </note>
-
+    <note>
+      Please realise that Forrest is still pre-1.0 release version. It is
+      certainly usable for those who are prepared to move with it. See more
+      notes about <link href="#status">status</link> below.
+    </note>
     <section>
       <title>Explanation and features</title>
       <p>
-        Forrest is designed with the new user in mind.  Much effort has gone
-        into making the process of generating a new site <strong>easy</strong> and
+        Forrest is designed with the new user in mind. Much effort has gone into
+        making the process of generating a new site <strong>easy</strong> and
         <strong>simple</strong>:
       </p>
       <ul>
@@ -57,8 +53,7 @@
           task-specific, presentation-neutral XML.</li>
         <li><strong>Step 3</strong>: Do <code>'forrest run'</code> then use
           the web browser to immediately review
-          changes at <code>http://localhost:8888/</code>
-        </li>
+          changes at <code>http://localhost:8888/</code></li>
         <li><strong>Step 4</strong>: Do <code>'forrest'</code> to generate the
           complete website from the XML sources.
           Various styles (known as skins) are available. Custom skins
@@ -72,43 +67,42 @@
       <note>
         The first time you run Forrest it may attempt to retrieve some plugins
         from the Internet (it depends on which distribution of Forrest you have
-        installed). In some cases this will happen whenever a new plugin is specified,
-        in other cases, for example when you have installed all plugins locally
-        or have checked out the full source tree, the plugins will be retrieved
-        from your local installation. In all cases once a plugin has been installed
-        locally there is no need for Forrest to access the Internet. 
-        For more information see the 
+        installed). In some cases this will happen whenever a new plugin is
+        specified, in other cases, for example when you have installed all
+        plugins locally or have checked out the full source tree, the plugins
+        will be retrieved from your local installation. In all cases once a
+        plugin has been installed locally there is no need for Forrest to access
+        the Internet. For more information see the
         <link href="site:pluginVersions/overview">plugins documentation</link>.
       </note>
       <p>
         Forrest's focus on low "startup cost" makes it ideal for rapid
         development of small sites, where time and budget constraints do not
         allow time-wasting HTML experiments. Of course, that same methodology
-        can scale up to large projects.
-        Your development team does not need Java experience, or even XML skills,
-        to use Forrest. The framework lets you concentrate on content and design.
-      </p>
-      <p>
-        By <strong>separating content from
-          presentation</strong>, providing <strong>content templates</strong>
-        and <strong>pre-written skins</strong>, Forrest is unequalled at enabling
-        content producers to get their message out fast.  This separation of
-        concerns makes Forrest excellent
-        to publish <strong>project documentation</strong> (notably software projects),
-        <strong>intranets</strong>, and <strong>home pages</strong>,
-        and anything else you can think of.
+        can scale up to large projects. Your development team does not need Java
+        experience, or even XML skills, to use Forrest. The framework lets you
+        concentrate on content and design.
+      </p>
+      <p>
+        By <strong>separating content from presentation</strong>, providing
+        <strong>content templates</strong> and <strong>pre-written
+        skins</strong>, Forrest is unequalled at enabling content producers to
+        get their message out fast. This separation of concerns makes Forrest
+        excellent to publish <strong>project documentation</strong> (notably
+        software projects), <strong>intranets</strong>, and <strong>home
+        pages</strong>, and anything else you can think of.
       </p>
-
       <p>
-        Forrest is far from a quick and dirty solution however.  Forrest is
-        built on the world's leading XML application framework,
+        Forrest is far from a quick and dirty solution however. Forrest is built
+        on the world's leading XML application framework,
         <link href="ext:cocoon">Apache Cocoon</link>, which provides advanced
         users with extremely powerful publishing capabilities.
       </p>
       <ul>
         <li>Multiple task-specific source XML formats can be used
             (<link href="site:write-howto">How-To</link>,
-          <link href="site:v0.70//faq"><acronym title="Frequently Asked
+          <link href="site:v0.70//faq">
+          <acronym title="Frequently Asked
               Questions">FAQ</acronym></link>,
           <link href="site:v0.70//changes">changelogs</link> and
           <link href="site:v0.70//todo">todo lists</link> supported natively).
@@ -139,77 +133,72 @@
           XML data that it processes.
         </li>
       </ul>
-
-        <p>
-          Unique amongst comparable documentation tools, Forrest generates
-          sites that can run both <strong>interactively</strong> as a dynamic
-          web application, or as statically rendered pages.
-        </p>
-        <p>
-          This provides a path for site growth: start off small and static, and
-          if dynamic features (user login, forms processing, runtime data, site
-          search etc) are one day needed, these can be accommodated by switching
-          to webapp mode.
-        </p>
-        <p>
-          Running as a webapp has a major advantage during development:
-          content can be written, and
-          then the rendered output viewed almost instantly in a web browser.
-          This <link href="site:v0.70//your-project/webapp">webapp technique</link>
-          enables Forrest's edit/review cycle to be faster than command-line
-          transformation tools.
-        </p>
+      <p>
+        Unique amongst comparable documentation tools, Forrest generates sites
+        that can run both <strong>interactively</strong> as a dynamic web
+        application, or as statically rendered pages.
+      </p>
+      <p>
+        This provides a path for site growth: start off small and static, and if
+        dynamic features (user login, forms processing, runtime data, site
+        search etc) are one day needed, these can be accommodated by switching
+        to webapp mode.
+      </p>
+      <p>
+        Running as a webapp has a major advantage during development: content
+        can be written, and then the rendered output viewed almost instantly in
+        a web browser. This <link href="site:v0.70//your-project/webapp">webapp
+        technique</link> enables Forrest's edit/review cycle to be faster than
+        command-line transformation tools.
+      </p>
     </section>
-
     <section id="status">
       <title>History and project status</title>
-      <p>Apache Forrest was started in January 2002, with the major use-case being to
-        create a consistent and efficient
-        <link href="http://xml.apache.org/">xml.apache.org</link> group of project
-        websites with a
-        uniform, lightweight, easy-to-navigate layout and structure.  In
-        addition, Forrest was to be a Sourceforge-like project management
-        tool, complementing <link href="ext:gump">Apache Gump</link> (hence
-        the name 'Forrest').
-      </p>
-      <p>
-        The focus shifted for Apache Forrest to primarily be a generic documentation
-        tool capable of meeting many needs. Certain relevant project management
-        facilities are being added.
-      </p>
-
-      <p>Apache Forrest is currently progressing rapidly through a series of 0.x
-        releases. It is certainly usable now (despite not yet being version 1.x).
-         See the growing list of
-         <link href="site:live-sites">example sites</link> including
-         many Apache sites.
+      <p>
+        Apache Forrest was started in January 2002, with the major use-case
+        being to create a consistent and efficient
+        <link href="http://xml.apache.org/">xml.apache.org</link> group of
+        project websites with a uniform, lightweight, easy-to-navigate layout
+        and structure. In addition, Forrest was to be a Sourceforge-like project
+        management tool, complementing <link href="ext:gump">Apache Gump</link>
+        (hence the name 'Forrest').
+      </p>
+      <p>
+        The focus shifted for Apache Forrest to primarily be a generic
+        documentation tool capable of meeting many needs. Certain relevant
+        project management facilities are being added.
+      </p>
+      <p>
+        Apache Forrest is currently progressing rapidly through a series of 0.x
+        releases. It is certainly usable now (despite not yet being version
+        1.x). See the growing list of <link href="site:live-sites">example
+        sites</link> including many Apache sites.
       </p>
       <p>
         In general, prior to 1.0, ensuring quality of design will be considered
-        more important than retaining backwards-compatibility.  Users
+        more important than retaining backwards-compatibility. Users
         (particularly those with custom sitemaps and skins) should be aware that
         this is evolving software, and read the release notes carefully before
-        upgrading.  That said, we appreciate the commitment in time that
-        adopters make, and will not make capricious or undocumented
+        upgrading. That said, we appreciate the commitment in time that adopters
+        make, and will not make capricious or undocumented
         backwards-incompatible changes.
       </p>
-
       <p>
         Documentation on the Apache Forrest website exists for various versions
-        including the latest release, the current development, and past releases.
-        All versions of Forrest include their own copy of the documentation.
-        There is also documentation for each plugin and the forrest seed site
-        contains further examples and documentation (see
+        including the latest release, the current development, and past
+        releases. All versions of Forrest include their own copy of the
+        documentation. There is also documentation for each plugin and the
+        forrest seed site contains further examples and documentation (see
         <link href="site:faq/docs">FAQ</link>).
       </p>
     </section>
     <section id="news">
       <title>News and events</title>
-      <p>See the <link href="site:events">events</link> list for more detail.
+      <p>
+        See the <link href="site:events">events</link> list for more detail.
       </p>
       <ul>
-        <li>
-         <!--
+        <li><!--
          <link href="http://apachecon.com/">
            <img src="http://apache.org/images/ac2005eu_135x50.gif"
              alt="ApacheCon Europe 2005" width="135" height="50"/>
@@ -221,8 +210,7 @@
 <!--
          See our <link href="site:events">events</link> list for the schedule
          of Forrest meetings at ApacheCon.
--->
-        </li>
+--></li>
         <li>Apache Forrest 0.7 was released on 2005-06-23.
           An architecture for Plugins which enables a smaller Forrest
           core and the ability to add new features in a modular way.
@@ -232,13 +220,13 @@
     <section id="help">
       <title>Help Wanted!</title>
       <p>
-        Apache Forrest is fairly new, and is in need of developers.
-        If you know (or want to learn) any of XML, Ant, HTML, XSLT, or CSS,
-        then you are qualified to help.
+        Apache Forrest is fairly new, and is in need of developers. If you know
+        (or want to learn) any of XML, Ant, HTML, XSLT, or CSS, then you are
+        qualified to help.
       </p>
       <p>
-        As with all Apache projects, Forrest is a meritocracy; the more you
-        put in, the more you get to define the project's future.  See the
+        As with all Apache projects, Forrest is a meritocracy; the more you put
+        in, the more you get to define the project's future. See the
         <link href="site:contrib">"contributing"</link> page for more
         information.
       </p>

Modified: forrest/trunk/site-author/content/xdocs/issues.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/issues.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/issues.xml (original)
+++ forrest/trunk/site-author/content/xdocs/issues.xml Mon Apr  9 20:48:52 2007
@@ -17,182 +17,162 @@
 -->
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
 <document>
-<header>
-  <title>Apache Forrest issue tracker</title>
-</header>
-<body>
-
-  <section id="intro">
-    <title>Introduction</title>
-  <p>
-    The Apache Forrest uses an issue tracker call Jira. All of the project
-    contributions should go there (not to the mailing list). This enables us to
-    keep track of contributions and to classify and manage the issues.
-  </p>
-
-  <p>
-    <a href="http://issues.apache.org/jira/browse/FOR">http://issues.apache.org/jira/browse/FOR</a>
-    is the main entry point which provides access to enter, view, search, and
-    add additional comments to issues. There are some additional search
-    <a href="#filters">filters</a> provided below.
-  </p>
-
-  <p>
-    You need to set up an account there before you can create new issues or
-    add comments to existing issues.
-    Anyone can register as a user and report issues.
-    See <a href="#guide">guidelines</a> below.
-  </p>
-
-  <p>
-    Note that the issue tracker is not a discussion or user help forum.
-    Please discuss issues about using Forrest on the user or dev mailing list.
-  </p>
-
-  </section>
-
-  <section id="guide">
-    <title>Guidelines and hints for reporting issues</title>
-    <ul>
-      <li>Ensure that an issue does not already exist.</li>
-      <li>Use Jira's powerful "Find Issues" ability. Set the Project and
-        Status fields. See the Help about boolean queries in the Query field.
-      </li>
-      <li>Follow the prompts below each entry field.</li>
-      <li>If you don't know the answer to a particular question, then
-        leave the field blank.</li>
-      <li>Add a concise initial Description, then add more Comments later to
-        further describe the issue.</li>
-      <li>Other people will follow up and enhance your description and
-        classifications.</li>
-      <li>If details about your computing environment are relevant
-        (e.g. Java version or operating system) then add them to a Comment.</li>
-      <li>If you are going to also add a patch, then select "Patch available".
-        (Reporters of issues can add this later via "Edit issue".)
-        Follow the instructions about "Grant license" and ensure that you are
-        able to do so.</li>
-    </ul>
-
-    <section id="priority">
-      <title>Special fields: Priority (a.k.a. Severity)</title>
+  <header>
+    <title>Apache Forrest issue tracker</title>
+  </header>
+  <body>
+    <section id="intro">
+      <title>Introduction</title>
       <p>
-        The Priority is the severity according to the issue reporter. This will
-        be a guideline to the development team to identify the most urgent
-        issues. It is not a guarantee that a Critical issue will be resolved
-        before a Major issue.
+        The Apache Forrest uses an issue tracker call Jira. All of the project
+        contributions should go there (not to the mailing list). This enables us
+        to keep track of contributions and to classify and manage the issues.
       </p>
       <p>
-        Follow the Jira help icon to see the definition of the options.
+        <a href="http://issues.apache.org/jira/browse/FOR">http://issues.apache.org/jira/browse/FOR</a>
+        is the main entry point which provides access to enter, view, search,
+        and add additional comments to issues. There are some additional search
+        <a href="#filters">filters</a> provided below.
       </p>
-    </section>
-
-    <section id="urgency">
-      <title>Special fields: Urgency</title>
       <p>
-        The project team will classify this according to their urgency. The aim is
-        to be able to see at a glance which issues should be attended to, so that
-        developers can operate efficiently and so that the product can be released
-        as soon as possible. Some issues hinder the project, so need to be identified.
+        You need to set up an account there before you can create new issues or
+        add comments to existing issues. Anyone can register as a user and
+        report issues. See <a href="#guide">guidelines</a> below.
       </p>
-
-<fixme author="open">
-Not sure about the project's use of the "Urgency" field.
-See issue <a href="http://issues.apache.org/jira/browse/FOR-853">FOR-853</a>
-</fixme>
-
       <p>
-        We use the following definition of the options.
+        Note that the issue tracker is not a discussion or user help forum.
+        Please discuss issues about using Forrest on the user or dev mailing
+        list.
       </p>
-
+    </section>
+    <section id="guide">
+      <title>Guidelines and hints for reporting issues</title>
       <ul>
-        <li>
+        <li>Ensure that an issue does not already exist.</li>
+        <li>Use Jira's powerful "Find Issues" ability. Set the Project and
+        Status fields. See the Help about boolean queries in the Query field.
+      </li>
+        <li>Follow the prompts below each entry field.</li>
+        <li>If you don't know the answer to a particular question, then
+        leave the field blank.</li>
+        <li>Add a concise initial Description, then add more Comments later to
+        further describe the issue.</li>
+        <li>Other people will follow up and enhance your description and
+        classifications.</li>
+        <li>If details about your computing environment are relevant
+        (e.g. Java version or operating system) then add them to a Comment.</li>
+        <li>If you are going to also add a patch, then select "Patch available".
+        (Reporters of issues can add this later via "Edit issue".)
+        Follow the instructions about "Grant license" and ensure that you are
+        able to do so.</li>
+      </ul>
+      <section id="priority">
+        <title>Special fields: Priority (a.k.a. Severity)</title>
+        <p>
+          The Priority is the severity according to the issue reporter. This
+          will be a guideline to the development team to identify the most
+          urgent issues. It is not a guarantee that a Critical issue will be
+          resolved before a Major issue.
+        </p>
+        <p>
+          Follow the Jira help icon to see the definition of the options.
+        </p>
+      </section>
+      <section id="urgency">
+        <title>Special fields: Urgency</title>
+        <p>
+          The project team will classify this according to their urgency. The
+          aim is to be able to see at a glance which issues should be attended
+          to, so that developers can operate efficiently and so that the product
+          can be released as soon as possible. Some issues hinder the project,
+          so need to be identified.
+        </p>
+        <fixme author="open">
+          Not sure about the project's use of the "Urgency" field. See issue
+          <a href="http://issues.apache.org/jira/browse/FOR-853">FOR-853</a>
+        </fixme>
+        <p>
+          We use the following definition of the options.
+        </p>
+        <ul>
+          <li>
           None: The default. Not yet classified.
         </li>
-        <li>
+          <li>
           Blocker: Prevents other developers from working; or critical issue with functionality;
           or holds up the implementation of other functionality.
           Cannot release until it is fixed. Will be fixed ASAP.
         </li>
-        <li>
+          <li>
           Urgent: Is a key new feature; or affects many users. Will be fixed before the next
           release.
         </li>
-        <li>
+          <li>
           Normal: If this issue scratches the itch of any particular developer, then
           they should help to solve it and provide a patch.
         </li>
-        <li>
+          <li>
           Low: If this issue bothers you, then fix it because it is not a high priority
           for the project.
         </li>
-      </ul>
-    </section>
-
-    <section id="permissions">
-      <title>Permissions</title>
-      <ul>
-        <li>
+        </ul>
+      </section>
+      <section id="permissions">
+        <title>Permissions</title>
+        <ul>
+          <li>
           Anyone: Browse, Find, View.
         </li>
-        <li>
+          <li>
           jira-users: People who have registered as a user of the ASF Jira.
           Create, Edit, Comment, Attach, Vote, Watch.
           The reporter can also Close.
         </li>
-        <li>
+          <li>
           forrest-developers: People who are Forrest committers.
           Resolve, Close, Delete issues, Delete coments, Link, Assign, Schedule Fix Version, Administer Project.
         </li>
-        <li>
+          <li>
           Some committers are global adminstrators: Edit user details, Add users to groups, Configure.
         </li>
-      </ul>
+        </ul>
+      </section>
     </section>
-  </section>
-
-  <section id="filters">
-    <title>Some search filters</title>
-    <p>
-      Various general searches are available from the
-      <a href="http://issues.apache.org/jira/browse/FOR">front page</a>,
-      e.g. "open issues classified by component", or "Added recently".
-      The following are some special filters.
-    </p>
-
-    <ul>
-      <li>
-        <a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&amp;requestId=12310472">FOR-open-with-patch</a>
+    <section id="filters">
+      <title>Some search filters</title>
+      <p>
+        Various general searches are available from the
+        <a href="http://issues.apache.org/jira/browse/FOR">front page</a>, e.g.
+        "open issues classified by component", or "Added recently". The
+        following are some special filters.
+      </p>
+      <ul>
+        <li><a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&amp;requestId=12310472">FOR-open-with-patch</a>
         - Committers need to visit this regularly and deal with the patches.
       </li>
-      <li>
-        <a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&amp;requestId=12310820">FOR-roadmap-dev</a>
+        <li><a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&amp;requestId=12310820">FOR-roadmap-dev</a>
         - Open issues that are scheduled to be investigated.
       </li>
-      <li>
-        <a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&amp;requestId=12310476">FOR-unresolved-with-attachment</a>
+        <li><a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&amp;requestId=12310476">FOR-unresolved-with-attachment</a>
         - Issues that have demonstrations of problems, but no solution or patch.
         Of course it will include FOR-open-with-patch.
         (Note that this filter searches for the string "attach" so will not find all.)
       </li>
-      <li>
-        <a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&amp;requestId=12310043">FOR-unscheduled</a>
+        <li><a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&amp;requestId=12310043">FOR-unscheduled</a>
         - Issues that have not yet been scheduled to be fixed for a certain version.
       </li>
-    </ul>
-<fixme author="open">
-Not sure about the project's use of the "Urgency" field.
-</fixme>
-    <ul>
-      <li>
-        <a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&amp;requestId=12310473">FOR-urgency-blocker</a>
+      </ul>
+      <fixme author="open">
+        Not sure about the project's use of the "Urgency" field.
+      </fixme>
+      <ul>
+        <li><a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&amp;requestId=12310473">FOR-urgency-blocker</a>
         - Issues that the project considers to be Blockers.
       </li>
-      <li>
-        <a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&amp;requestId=12310475">FOR-urgency-urgent</a>
+        <li><a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&amp;requestId=12310475">FOR-urgency-urgent</a>
         - Issues that the project considers to be Urgent.
       </li>
-    </ul>
-  </section>
-
-</body>
+      </ul>
+    </section>
+  </body>
 </document>

Modified: forrest/trunk/site-author/content/xdocs/license.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/license.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/license.xml (original)
+++ forrest/trunk/site-author/content/xdocs/license.xml Mon Apr  9 20:48:52 2007
@@ -16,23 +16,21 @@
   limitations under the License.
 -->
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
-
 <document>
- <header>
-  <title>Apache License</title>
- </header>
-
-<body>
-  <p>
-    The Forrest distribution is licensed according to the liberal
-    Apache License. See the files in the top-level of the Forrest
-    distribution called LICENSE.txt (copy shown below) and NOTICE.txt
-    and see licenses for accompanying products in the "lib" directories
-    of the Forrest core and plugins.
-    See full explanation and FAQs regarding the
-    <link href="ext:asf/asl">Apache License</link>.
-  </p>
-<source><![CDATA[
+  <header>
+    <title>Apache License</title>
+  </header>
+  <body>
+    <p>
+      The Forrest distribution is licensed according to the liberal Apache
+      License. See the files in the top-level of the Forrest distribution called
+      LICENSE.txt (copy shown below) and NOTICE.txt and see licenses for
+      accompanying products in the "lib" directories of the Forrest core and
+      plugins. See full explanation and FAQs regarding the
+      <link href="ext:asf/asl">Apache License</link>.
+    </p>
+    <source>
+<![CDATA[
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -234,6 +232,7 @@
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-]]></source>
-</body>
+]]>
+    </source>
+  </body>
 </document>



Mime
View raw message