forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r527010 [17/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/docs_0_80/validation.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/validation.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/validation.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/validation.xml Mon Apr  9 20:48:52 2007
@@ -22,55 +22,58 @@
    "http://forrest.apache.org/entity/ISOnum.pen">
  %ISOnum;
 ]>
-
 <document>
   <header>
     <title>XML validation and entity resolution</title>
     <subtitle>DTDs, catalogs and whatnot</subtitle>
   </header>
-
   <body>
     <section id="intro">
       <title>Introduction</title>
       <p>
-        When a source document uses a DTD to define its structure, then various abilities are enabled. Forrest handles the annoying side of this and takes advantage of the benefits.
+        When a source document uses a DTD to define its structure, then various
+        abilities are enabled. Forrest handles the annoying side of this and
+        takes advantage of the benefits.
       </p>
       <p>
-        The xml parser must locate the DTDs and other entities. Forrest uses the XML
-        Catalog Entity Resolver to associate DTD references with local copies.
+        The xml parser must locate the DTDs and other entities. Forrest uses the
+        XML Catalog Entity Resolver to associate DTD references with local
+        copies.
       </p>
       <p>
         Forrest also uses the XML Document Type Declaration to effect the
-        <link href="site:cap">Content Aware Pipelines</link>. Remember that you are
-        not required to use DTDs (for example Forrest can also respond to a namespace)
-        so RELAX NG or W3c XML Schema can be used.
+        <link href="site:cap">Content Aware Pipelines</link>. Remember that you
+        are not required to use DTDs (for example Forrest can also respond to a
+        namespace) so RELAX NG or W3c XML Schema can be used.
       </p>
       <p>
-        If you do use DTDs, then forrest is automatically configured to do XML validation.
+        If you do use DTDs, then forrest is automatically configured to do XML
+        validation.
       </p>
       <p>
-        This document explains both the validation and entity resolution aspects of the Forrest XML framework.
+        This document explains both the validation and entity resolution aspects
+        of the Forrest XML framework.
       </p>
     </section>
     <section id="xml_validation">
       <title>XML validation</title>
       <p>
-        By default, Forrest will validate your XML before generating
-        HTML or a webapp from it, and fail if any XML files are not valid.
-        Validation can be performed manually by doing
-        '<code>forrest validate</code>' in the project root directory.
+        By default, Forrest will validate your XML before generating HTML or a
+        webapp from it, and fail if any XML files are not valid. Validation can
+        be performed manually by doing '<code>forrest validate</code>' in the
+        project root directory.
       </p>
       <p>
         For an XML file to be valid, it <em>must</em> have a document type
-        declaration at the top, indicating its content type.  Hence by
-        default, any Forrest-processed XML file that lacks a DOCTYPE
-        declaration will cause the build to break.
+        declaration at the top, indicating its content type. Hence by default,
+        any Forrest-processed XML file that lacks a DOCTYPE declaration will
+        cause the build to break.
       </p>
       <p>
         Despite the strict default behavior, Forrest is quite flexible about
-        validation.  Validation can be switched off for certain sections of a
-        project.  In validated sections, it is possible for projects to specify
-        exactly what files they want (and don't want) validated.  Forrest
+        validation. Validation can be switched off for certain sections of a
+        project. In validated sections, it is possible for projects to specify
+        exactly what files they want (and don't want) validated. Forrest
         validation is controlled through a set of properties in
         <code>forrest.properties</code>:
       </p>
@@ -106,36 +109,35 @@
       <source>forrest.validate.xdocs.excludes=slides.xml, manual/**</source>
       <note>
         The <code>failonerror</code> properties only work for files validated
-        with Ant's &lt;xmlvalidate&gt; and not (yet) for those validated
-        with &lt;jing&gt;, where <code>failonerror</code> defaults to
+        with Ant's &lt;xmlvalidate&gt; and not (yet) for those validated with
+        &lt;jing&gt;, where <code>failonerror</code> defaults to
         <code>true</code>.
       </note>
     </section>
-
     <section>
       <title>Validating new XML types</title>
       <p>
         Forrest provides an <link href="ext:catalog_spec">OASIS Catalog</link>
         [see <link href="ext:catalog_intro">tutorial</link>]
-        <code>forrest/main/webapp/resources/schema/catalog.xcat</code>
-        as a means of associating public identifiers
-        (e.g. <code>-//APACHE//DTD Documentation V1.1//EN</code> above) with DTDs.
-        If you <link href="site:your-project/new_content_type">add a new content type</link>, you
-        should add the DTD to <code>${project.schema-dir}/dtd/</code> and add
-        an entry to the <code>${project.schema-dir}/catalog.xcat</code> file.  This
-        section describes the details of this process.
+        <code>forrest/main/webapp/resources/schema/catalog.xcat</code> as a
+        means of associating public identifiers (e.g. <code>-//APACHE//DTD
+        Documentation V1.1//EN</code> above) with DTDs. If you
+        <link href="site:your-project/new_content_type">add a new content
+        type</link>, you should add the DTD to
+        <code>${project.schema-dir}/dtd/</code> and add an entry to the
+        <code>${project.schema-dir}/catalog.xcat</code> file. This section
+        describes the details of this process.
       </p>
-
       <section>
         <title>Creating or extending a DTD</title>
         <p>
-          The main Forrest DTDs are designed to be modular and extensible, so
-          it is fairly easy to create a new document type that is a superset
-          of one from Forrest.  This is what we'll demonstrate here, using our
-          earlier <link href="site:your-project/new_content_type">download format</link>
-          as an example.  Our download format adds a group of new elements to
-          the standard 'documentv13' format.  Our new elements are described
-          by the following DTD:
+          The main Forrest DTDs are designed to be modular and extensible, so it
+          is fairly easy to create a new document type that is a superset of one
+          from Forrest. This is what we'll demonstrate here, using our earlier
+          <link href="site:your-project/new_content_type">download format</link>
+          as an example. Our download format adds a group of new elements to the
+          standard 'documentv13' format. Our new elements are described by the
+          following DTD:
         </p>
         <source>
 &lt;!ELEMENT release (downloads)&gt;
@@ -157,10 +159,10 @@
           The
           <code>forrest/main/webapp/resources/schema/dtd/document-v13.dtd</code>
           file provides a full description and basic example of how to pull in
-          modules.  In our example, our DTD reuses modules
+          modules. In our example, our DTD reuses modules
           <code>common-charents-v10.mod</code> and
-          <code>document-v13.mod</code>.  Here is the full DTD, with
-          explanation to follow.
+          <code>document-v13.mod</code>. Here is the full DTD, with explanation
+          to follow.
         </p>
         <source>
 &lt;!-- ===================================================================
@@ -217,196 +219,191 @@
 &lt;!-- End of DTD --&gt;
 &lt;!-- =============================================================== --&gt;
         </source>
-        <p>This custom DTD should be placed in your project resources
-        directory at <code>src/documentation/resources/schema/dtd/</code></p>
         <p>
-          The &lt;!ENTITY % ... &gt; blocks are so-called 
+          This custom DTD should be placed in your project resources directory
+          at <code>src/documentation/resources/schema/dtd/</code>
+        </p>
+        <p>
+          The &lt;!ENTITY % ... &gt; blocks are so-called
           <link href="http://www.xml.com/axml/target.html#dt-PERef">parameter
-            entities</link>.  They are like macros, whose content will be
-          inserted when a parameter-entity reference, like
-          <code>%common-charents;</code> or <code>%document;</code> is
-          inserted.
+          entities</link>. They are like macros, whose content will be inserted
+          when a parameter-entity reference, like <code>%common-charents;</code>
+          or <code>%document;</code> is inserted.
         </p>
         <p>
           In our DTD, we first pull in the 'common-charents' entity, which
-          defines character symbol sets.  We then define the 'document'
-          entity.  However, before the <code>%document;</code> PE reference, we
-          first override the 'local.section' entity.  This is a hook into
-          document-v13.mod.  By setting its value to '|release', we declare
-          that our &lt;release&gt; element is to be allowed wherever "local
-          sections" are used.  There are five or so such hooks for different
-          areas of the document; see document-v13.dtd for more details.  We then
-          import the %document; contents, and declare the rest of our DTD
-          elements.
+          defines character symbol sets. We then define the 'document' entity.
+          However, before the <code>%document;</code> PE reference, we first
+          override the 'local.section' entity. This is a hook into
+          document-v13.mod. By setting its value to '|release', we declare that
+          our &lt;release&gt; element is to be allowed wherever "local sections"
+          are used. There are five or so such hooks for different areas of the
+          document; see document-v13.dtd for more details. We then import the
+          %document; contents, and declare the rest of our DTD elements.
         </p>
         <p>
-          We now have a DTD for the 'download' document type. 
+          We now have a DTD for the 'download' document type.
         </p>
         <note>
-        <link href="http://www.oasis-open.org/docbook/documentation/reference/html/ch05.html">Chapter
-            5: Customizing DocBook</link> of Norman Walsh's "DocBook: The
+          <link href="http://www.oasis-open.org/docbook/documentation/reference/html/ch05.html">Chapter
+          5: Customizing DocBook</link> of Norman Walsh's "DocBook: The
           Definitive Guide" gives a complete overview of the process of
           customizing a DTD.
         </note>
       </section>
-
       <section id="catalog">
         <title>Associating DTDs with document types</title>
-
         <p>
-          Recall that our DOCTYPE declaration for our download document type
-          is:
+          Recall that our DOCTYPE declaration for our download document type is:
         </p>
         <source>&lt;!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
           "download-v10.dtd"&gt;
         </source>
         <p>
-          We only care about the quoted section after <code>PUBLIC</code>, called
-          the "public identifier", which globally identifies our document type.
-          We cannot rely on the subsequent "system identifier" part
+          We only care about the quoted section after <code>PUBLIC</code>,
+          called the "public identifier", which globally identifies our document
+          type. We cannot rely on the subsequent "system identifier" part
           ("download-v10.dtd"), because as a relative reference it is liable to
-          break.  The solution Forrest uses is to ignore the system id, and rely
+          break. The solution Forrest uses is to ignore the system id, and rely
           on a mapping from the public ID to a stable DTD location, via a
-          Catalog file.</p>
+          Catalog file.
+        </p>
         <note>
           See <link href="ext:catalog_intro">this article</link> for a good
           introduction to catalogs and the Cocoon documentation
-          <link href="ext:cocoon/catalogs">Entity resolution with catalogs</link>.
+          <link href="ext:cocoon/catalogs">Entity resolution with
+          catalogs</link>.
         </note>
         <p>
           Forrest provides a standard catalog file at
-          <code>forrest/main/webapp/resources/schema/catalog.xcat</code>
-          for the document types that Forrest supplies.
+          <code>forrest/main/webapp/resources/schema/catalog.xcat</code> for the
+          document types that Forrest supplies.
         </p>
-
         <p>
-          An additional system-wide catalog can be configured for use by multiple forrest-based projects.
-          See the "local-catalog" parameter in <code>main/webapp/WEB-INF/xconf/forrest-core.xconf</code>
+          An additional system-wide catalog can be configured for use by
+          multiple forrest-based projects. See the "local-catalog" parameter in
+          <code>main/webapp/WEB-INF/xconf/forrest-core.xconf</code>
         </p>
-
         <p>
           Projects can augment this with their own catalog file located in
           <code>${project.schema-dir}/catalog.xcat</code> to use it you must
-	    specify either the path (full or relative) to your 
-	    <code>catalog.xcat</code> in the <code>CatalogManager.properties</code>
-	    file. If you provide a relative path you must set the property 
-	    <code>relative-catalogs</code> to "yes".
-	  </p>
-        <p>
-          When Cocoon starts, it reads the <code>CatalogManager.properties</code> file from your
-          <code>project.classes-dir</code>. This is usually src/documentation/classes/
-          but you can change this in <code>forrest.properties</code>. When you seed 
-          a new site using <code>forrest seed</code> a sample catalog file
-          is placed in the site structure, you can use this as a template for your
-          own files.
+          specify either the path (full or relative) to your
+          <code>catalog.xcat</code> in the
+          <code>CatalogManager.properties</code> file. If you provide a relative
+          path you must set the property <code>relative-catalogs</code> to
+          "yes".
+        </p>
+        <p>
+          When Cocoon starts, it reads the
+          <code>CatalogManager.properties</code> file from your
+          <code>project.classes-dir</code>. This is usually
+          src/documentation/classes/ but you can change this in
+          <code>forrest.properties</code>. When you seed a new site using
+          <code>forrest seed</code> a sample catalog file is placed in the site
+          structure, you can use this as a template for your own files.
         </p>
         <p>
           Forrest uses the XML Catalog syntax by default, although the older
-          plain-text
-          format can also be used.  Here is what the XML Catalog format looks
-          like:
+          plain-text format can also be used. Here is what the XML Catalog
+          format looks like:
         </p>
-        <source><![CDATA[<?xml version="1.0"?>
+        <source>
+<![CDATA[<?xml version="1.0"?>
 <!-- OASIS XML Catalog for Forrest -->
 <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
   <public publicId="-//Acme//DTD Download Documentation V1.0//EN"
     uri="dtd/download-v10.dtd"/>
-</catalog>]]></source>
+</catalog>]]>
+        </source>
         <p>
           The format is described in <link href="ext:catalog_spec">the
-          spec</link>, and is fairly simple and very powerful.
-          The "<code>public</code>" elements map
-          a public identifier to a DTD (relative to the catalog file).
+          spec</link>, and is fairly simple and very powerful. The
+          "<code>public</code>" elements map a public identifier to a DTD
+          (relative to the catalog file).
         </p>
         <p>
-          We now have a custom DTD and a catalog mapping which lets both
-          Forrest and Cocoon
-          locate the DTD.  Now if we were to run <code>'forrest validate-xdocs'</code>
-          our download file would validate along with all the others.  If
-          something goes wrong, try running <code>'forrest -v validate-xdocs'</code> to
-          see the error in more detail.
+          We now have a custom DTD and a catalog mapping which lets both Forrest
+          and Cocoon locate the DTD. Now if we were to run <code>'forrest
+          validate-xdocs'</code> our download file would validate along with all
+          the others. If something goes wrong, try running <code>'forrest -v
+          validate-xdocs'</code> to see the error in more detail.
         </p>
       </section>
     </section>
-
     <section id="debug-catalog">
       <title>Debugging the Catalog Entity Resolver</title>
       <p>
-        If you suspect problems with your project catalog, then raise the "verbosity"
-        level in <code>src/documentation/classes/CatalogManager.properties</code>
-        and re-start forrest.
-        This should show your project catalogs being parsed and loaded.
+        If you suspect problems with your project catalog, then raise the
+        "verbosity" level in
+        <code>src/documentation/classes/CatalogManager.properties</code> and
+        re-start forrest. This should show your project catalogs being parsed
+        and loaded.
       </p>
       <p>
-        However this configuration does not show your DTDs being resolved.
-        So raise the verbosity level in the central configuration at
-        <code>main/webapp/WEB-INF/properties/dev/core.properties</code>
-        and re-start forrest. This also shows the main catalogs being loaded
-        and shows the resolving of every DTD and entity set.
+        However this configuration does not show your DTDs being resolved. So
+        raise the verbosity level in the central configuration at
+        <code>main/webapp/WEB-INF/properties/dev/core.properties</code> and
+        re-start forrest. This also shows the main catalogs being loaded and
+        shows the resolving of every DTD and entity set.
       </p>
       <p>
         When a DTD is successfully resolved you should see the message:
         <code>Resolved public:</code>
       </p>
       <p>
-        When debugging such issues, a network monitoring tool (e.g. ngrep.sf.net)
-        is useful to ensure that all resources are being locally resolved and not       wandering onto the network to find remote copies.
+        When debugging such issues, a network monitoring tool (e.g.
+        ngrep.sf.net) is useful to ensure that all resources are being locally
+        resolved and not wandering onto the network to find remote copies.
       </p>
     </section>
-
     <section id="entities">
       <title>Referring to entities</title>
       <p>
         Look at the source of this document
         (<code>xdocs/docs/validation.xml</code>) and see how the entity set
-        <code>"Numeric and Special Graphic"</code> is declared in the
-        document type declaration.
+        <code>"Numeric and Special Graphic"</code> is declared in the document
+        type declaration.
       </p>
       <table>
         <tr>
-          <td>ISOnum.pen</td> 
-          <td>&amp;half;</td> 
-          <td>&half;</td> 
+          <td>ISOnum.pen</td>
+          <td>&amp;half;</td>
+          <td>&half;</td>
         </tr>
       </table>
     </section>
-
     <section>
       <title>Validating in an XML editor</title>
       <p>
-        If you have an XML editor that understands SGML or XML catalogs, let
-        it know where the Forrest catalog file is, and you will be able to
-        validate any Forrest XML file, regardless of location, as you edit
-        your files. See the 
-        <link href="site:catalog">configuration notes</link> your favourite
-        editor.
+        If you have an XML editor that understands SGML or XML catalogs, let it
+        know where the Forrest catalog file is, and you will be able to validate
+        any Forrest XML file, regardless of location, as you edit your files.
+        See the <link href="site:catalog">configuration notes</link> your
+        favourite editor.
       </p>
     </section>
-
     <section id="relaxng">
       <title>Validation using RELAX NG</title>
       <p>
         Other validation is also conducted during build-time using RELAX NG.
-        This validates all of the important configuration files, both in
-        Forrest itself and in your project. At the moment it processes all
-        skinconf.xml files, all sitemap.xmap files, and all XSLT stylesheets.
+        This validates all of the important configuration files, both in Forrest
+        itself and in your project. At the moment it processes all skinconf.xml
+        files, all sitemap.xmap files, and all XSLT stylesheets.
       </p>
       <p>
         The RNG grammars to do this are located in the
-        <code>main/webapp/resources/schema/relaxng</code> directory.
-        If you want to
-        know more about this, and perhaps extend it for your own use, then
-        see <code>main/webapp/resources/schema/relaxng/README.txt</code>
-        and the Ant targets in the various build.xml files.
+        <code>main/webapp/resources/schema/relaxng</code> directory. If you want
+        to know more about this, and perhaps extend it for your own use, then
+        see <code>main/webapp/resources/schema/relaxng/README.txt</code> and the
+        Ant targets in the various build.xml files.
       </p>
     </section>
-
     <section id="sitemap">
       <title>Validation using Cocoon sitemap and the Cocoon Validation block</title>
       <p>
-        The content of pipelines can be validated at various points in the Cocoon sitemaps
-        using RELAX NG or W3C XML Schema.
-        See <link href="site:forrest-dev/debug-validation">notes</link>.
+        The content of pipelines can be validated at various points in the
+        Cocoon sitemaps using RELAX NG or W3C XML Schema. See
+        <link href="site:forrest-dev/debug-validation">notes</link>.
       </p>
     </section>
   </body>

Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/your-project.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/your-project.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/your-project.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/your-project.xml Mon Apr  9 20:48:52 2007
@@ -16,89 +16,108 @@
   limitations under the License.
 -->
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">
-
 <document>
   <header>
     <title>Using Forrest</title>
     <subtitle>A tutorial on how to use Forrest in your own projects</subtitle>
     <version>SVN: $Revision$ $Date$</version>
   </header>
-
   <body>
     <section id="intro">
       <title>Introduction</title>
       <p>
-        This tutorial will lead you through the process of installing Forrest, and using
-        it to create a new project, or add Forrest-based docs to an existing project.
+        This tutorial will lead you through the process of installing Forrest,
+        and using it to create a new project, or add Forrest-based docs to an
+        existing project.
       </p>
     </section>
-
-   <section id="installing">
-     <title>Installing Forrest</title>
-     <p>
-       <link href="ext:forrest/download">Download</link> the latest release
-       of Forrest and follow the index.html in the top-level, or
-       if you want to try the development version, then
-       <link href="site:build">build Forrest</link> from source.
-     </p>
-     
-     <section>
-       <title>Setting up the Environment</title>
-       <p>
-       After downloading and extracting Forrest, you need to add environment variables.
-       The reason for this is so that the 'forrest' command is available everywhere and it can
-       locate its home directory and resources.
-       It is beyond the scope of Forrest to explain how to manage your operating system. Some tips are listed below and this
-       <link href="http://mail-archives.apache.org/mod_mbox/forrest-user/200610.mbox/%3ceab855560610181625u6e49b49at7df6c0c5e6812c74@mail.gmail.com%3e">message</link>
-       explains further and provides other tips about using Windows.
-       </p>
-       
-       <section>
-         <title>In Unix/Linux:</title>
-         <p class="instruction">change directory to the top-level of the forrest distribution and do ...</p>
-         <p class="instruction">~/apache-forrest$ export FORREST_HOME=`pwd`</p>
-         <p class="instruction">~/apache-forrest$ export PATH=$PATH:$FORREST_HOME/bin</p>
-       
-         <section>
-           <title>Permanently Setting The Environment Variables for Linux/Unix</title>
-           <p>Export only changes the variables during that terminal session for that 
-           user, this is useful for testing. To permanently add the variable edit either 
-           <code>/etc/bash.bashrc</code> (for all users) or <code>~/.bash_profile</code>
-           (for individual users). Add these lines to the end of the file you edit:</p>
-         
-           <source>
+    <section id="installing">
+      <title>Installing Forrest</title>
+      <p>
+        <link href="ext:forrest/download">Download</link> the latest release of
+        Forrest and follow the index.html in the top-level, or if you want to
+        try the development version, then <link href="site:build">build
+        Forrest</link> from source.
+      </p>
+      <section>
+        <title>Setting up the Environment</title>
+        <p>
+          After downloading and extracting Forrest, you need to add environment
+          variables. The reason for this is so that the 'forrest' command is
+          available everywhere and it can locate its home directory and
+          resources. It is beyond the scope of Forrest to explain how to manage
+          your operating system. Some tips are listed below and this
+          <link href="http://mail-archives.apache.org/mod_mbox/forrest-user/200610.mbox/%3ceab855560610181625u6e49b49at7df6c0c5e6812c74@mail.gmail.com%3e">message</link>
+          explains further and provides other tips about using Windows.
+        </p>
+        <section>
+          <title>In Unix/Linux:</title>
+          <p class="instruction">
+            change directory to the top-level of the forrest distribution and do
+            ...
+          </p>
+          <p class="instruction">
+            ~/apache-forrest$ export FORREST_HOME=`pwd`
+          </p>
+          <p class="instruction">
+            ~/apache-forrest$ export PATH=$PATH:$FORREST_HOME/bin
+          </p>
+          <section>
+            <title>Permanently Setting The Environment Variables for Linux/Unix</title>
+            <p>
+              Export only changes the variables during that terminal session for
+              that user, this is useful for testing. To permanently add the
+              variable edit either <code>/etc/bash.bashrc</code> (for all users)
+              or <code>~/.bash_profile</code> (for individual users). Add these
+              lines to the end of the file you edit:
+            </p>
+            <source>
       FORREST_HOME=/full/path/to/forrest
       export FORREST_HOME
       
       PATH=$PATH:$FORREST_HOME/bin
       export PATH
           </source>
+          </section>
+        </section>
+        <section>
+          <title>Windows 2000</title>
+          <p class="instruction">
+            Go to "My Computer", "Properties", "Advanced", "Environment
+            Variables"
+          </p>
+          <p class="instruction">
+            add a new variable <code>FORREST_HOME</code> as
+            <code>C:\full\path\to\apache-forrest</code>
+          </p>
+          <p class="instruction">
+            edit <code>PATH</code> as <code>%PATH%;%FORREST_HOME%\bin</code>
+          </p>
+        </section>
+        <section>
+          <title>In Windows XP:</title>
+          <p class="instruction">
+            Go to "My Computer", "Properties", "Advanced", "Environment
+            Variables"
+          </p>
+          <p class="instruction">
+            Create a New variable with name: FORREST_HOME value:
+            C:\full\path\to\apache-forrest
+          </p>
+          <p class="instruction">
+            Edit PATH by adding ;%FORREST_HOME%\bin to the end of the current
+            value.
+          </p>
         </section>
       </section>
-     
-       <section>
-         <title>Windows 2000</title>
-         <p class="instruction">Go to "My Computer", "Properties", "Advanced", "Environment Variables"</p>
-         <p class="instruction">add a new variable <code>FORREST_HOME</code> as <code>C:\full\path\to\apache-forrest</code></p>
-         <p class="instruction">edit <code>PATH</code> as <code>%PATH%;%FORREST_HOME%\bin</code></p>
-       </section>
-       
-       <section>
-         <title>In Windows XP:</title>
-         <p class="instruction">Go to "My Computer", "Properties", "Advanced", "Environment Variables"</p>
-         <p class="instruction">Create a New variable with name: FORREST_HOME value: C:\full\path\to\apache-forrest</p>
-         <p class="instruction">Edit PATH by adding ;%FORREST_HOME%\bin to the end of the current value.</p>
-       </section>
-     </section>
-   </section>
-   
-   <section>
-     <title>The 'forrest' Command</title>
-       <p>
-         To see what the 'forrest' command can do, type 'forrest -projecthelp'.
-         The build targets that are marked with * are the commonly used ones.
-         </p>
-       <source>
+    </section>
+    <section>
+      <title>The 'forrest' Command</title>
+      <p>
+        To see what the 'forrest' command can do, type 'forrest -projecthelp'.
+        The build targets that are marked with * are the commonly used ones.
+      </p>
+      <source>
   Apache Forrest.  Run 'forrest -projecthelp' to list options
   
   Buildfile: /usr/local/svn/forrest/src/core/bin/../forrest.build.xml
@@ -142,14 +161,14 @@
                            target if you wish to deploy remotely.
   Default target: site
        </source>
-        <p>
-          As 'site' is the default target, just running 'forrest' without options will
-          generate a "static HTML website". For example, typing 'forrest' in the
-         top-level "forrest/site-author" directory would build Forrest's own website.
-         But we're going to be building a new site for your project, so read on.
-        </p>
+      <p>
+        As 'site' is the default target, just running 'forrest' without options
+        will generate a "static HTML website". For example, typing 'forrest' in
+        the top-level "forrest/site-author" directory would build Forrest's own
+        website. But we're going to be building a new site for your project, so
+        read on.
+      </p>
     </section>
-
     <section id="seeding_new">
       <title>Seeding a new project</title>
       <p>
@@ -157,21 +176,24 @@
         documentation set to your project, which you can then customize.
       </p>
       <p>
-        To try this out, create a completely new directory (outside the
-        Forrest distribution), then change directory
-        to it, and do 'forrest seed'. This will give you a new site with lots 
-        of demonstration documents. You can also do "forrest seed-business", this
-        will ask you a number of questions about the site and will create a 
-        smaller site without all the demonstration pages of the standard seed site.
+        To try this out, create a completely new directory (outside the Forrest
+        distribution), then change directory to it, and do 'forrest seed'. This
+        will give you a new site with lots of demonstration documents. You can
+        also do "forrest seed-business", this will ask you a number of questions
+        about the site and will create a smaller site without all the
+        demonstration pages of the standard seed site.
+      </p>
+      <note>
+        <code>forrest seed</code> is useful to see what is possible within
+        Forrest, but if you are creating a real site <code>forrest
+        seed-business</code> has less content initially, and is therefore easier
+        to edit (even if it is not a business site). We hope to include more
+        seed sites in the future.
+      </note>
+      <p>
+        If you run <code>forrest seed</code> you should see output like this
+        below:
       </p>
-      
-      <note><code>forrest seed</code> is useful to see what is possible within Forrest,
-      but if you are creating a real site <code>forrest seed-business</code> has less
-      content initially, and is therefore easier to edit (even if it is not a business
-      site). We hope to include more seed sites in the future.</note>
-      
-      <p>If you run <code>forrest seed</code> you should see output like this below:</p>
-      
       <source>
 [/home/me/forrest/my-test]$ forrest seed
 
@@ -228,7 +250,8 @@
       </source>
       <note>
         As you have probably noticed, we like to document things right in the
-        script, on the theory that people only read online docs when desperate :)
+        script, on the theory that people only read online docs when desperate
+        :)
       </note>
       <p>
         You now have a template documentation structure all set up:
@@ -294,17 +317,17 @@
 |           `-- tabs_es.xml
       </source>
       <p>
-        To render this to HTML, type 'forrest'. You should have a HTML site rendered
-        into the <code>build/site</code> directory:
+        To render this to HTML, type 'forrest'. You should have a HTML site
+        rendered into the <code>build/site</code> directory:
       </p>
       <figure src="images/new-project.png" height="356" width="500" alt="New project"/>
       <p>
         Practise with adding new content. Change to the directory
         <code>src/documentation/content/xdocs</code> and copy the file
-        <code>index.xml</code> to create <code>my-new-file.xml</code> as a
-        new document. Edit it to change some text. Add an entry to 
-        <code>site.xml</code> by copying one of the other entries and
-        changing it to suit. Now do 'forrest' to see the result.
+        <code>index.xml</code> to create <code>my-new-file.xml</code> as a new
+        document. Edit it to change some text. Add an entry to
+        <code>site.xml</code> by copying one of the other entries and changing
+        it to suit. Now do 'forrest' to see the result.
       </p>
     </section>
     <section id="seeding_existing">
@@ -320,26 +343,26 @@
         If your project already has XML documentation, it may be easier to tell
         Forrest where the XML sources are, rather than rearrange your project
         directories to accommodate Forrest. This can be done by editing
-        <code>forrest.properties</code> (consult
-        the <link href="#Changing_the_layout">Changing the layout</link>
-        section for more details).
+        <code>forrest.properties</code> (consult the
+        <link href="#Changing_the_layout">Changing the layout</link> section for
+        more details).
       </p>
     </section>
     <section id="customizing">
       <title>Customizing your project</title>
       <p>
-        Having seeded a project with template docs, you will now want to customize it
-        to your project's needs. Here we will deal with configuring the skin, and
-        changing the project layout.
+        Having seeded a project with template docs, you will now want to
+        customize it to your project's needs. Here we will deal with configuring
+        the skin, and changing the project layout.
       </p>
       <section id="skinconf.xml">
         <title>Configuring the Forrest skin: skinconf.xml</title>
-
         <p>
           Most Forrest skins can be customized through a single XML file,
           <code>src/documentation/skinconf.xml</code>, which looks like this:
         </p>
-<source><![CDATA[
+        <source>
+<![CDATA[
 <!--
 Skin configuration file. This file contains details of your project,
 which will be used to configure the chosen Forrest skin.
@@ -499,35 +522,35 @@
   </credits>
 
 </skinconfig>
-]]></source>
+]]>
+        </source>
         <p>
-          Customise this file for your project. The <code>images/</code> directory
-          mentioned in 'project-logo' and 'group-logo' elements corresponds to the
-          <code>src/documentation/resources/images</code> directory
-          (this mapping is done automatically by the sitemap).
+          Customise this file for your project. The <code>images/</code>
+          directory mentioned in 'project-logo' and 'group-logo' elements
+          corresponds to the <code>src/documentation/resources/images</code>
+          directory (this mapping is done automatically by the sitemap).
         </p>
         <p>
-          Having edited this file (and ensured it is valid XML), re-run the 'forrest'
-          command in the site root, and the site would be updated.
+          Having edited this file (and ensured it is valid XML), re-run the
+          'forrest' command in the site root, and the site would be updated.
         </p>
       </section>
       <section id="Changing_the_layout">
         <title>Changing the layout: forrest.properties</title>
         <p>
-          Forrest allows you to place files anywhere you want in your
-          project, so long as you tell Forrest where you have placed the
-          major file types.
+          Forrest allows you to place files anywhere you want in your project,
+          so long as you tell Forrest where you have placed the major file
+          types.
         </p>
         <p>
           The <code>forrest.properties</code> file maps from your directory
-          layout to Forrest's. If you generated your site with 'forrest seed', you
-          will have one pre-written, with all the entries commented out.
+          layout to Forrest's. If you generated your site with 'forrest seed',
+          you will have one pre-written, with all the entries commented out.
         </p>
         <note>
-         You only need to un-comment entries if you are going to change them
-         to something different.
-         If you keep in synchronisation with the 'forrest seed' defaults,
-         then it is easy to diff each time that you update.
+          You only need to un-comment entries if you are going to change them to
+          something different. If you keep in synchronisation with the 'forrest
+          seed' defaults, then it is easy to diff each time that you update.
         </note>
         <p>
           The main entries (with default values) are:
@@ -551,23 +574,25 @@
 #project.lib-dir=${project.content-dir}/lib
 #project.classes-dir=${project.content-dir}/classes
        </source>
-       <p>
-         For example, if you wish to keep XML documentation in src/xdocs rather than
-         <code>src/documentation/content/xdocs</code> simply change the
-         definition for project.xdocs-dir
-       </p>
-       <source>project.xdocs-dir=src/xdocs</source>
-       <p>
-         For example, to emulate the simple 
-         <link href="http://maven.apache.org/">Maven</link> format:
-       </p>
-       <source>
+        <p>
+          For example, if you wish to keep XML documentation in src/xdocs rather
+          than <code>src/documentation/content/xdocs</code> simply change the
+          definition for project.xdocs-dir
+        </p>
+        <source>project.xdocs-dir=src/xdocs</source>
+        <p>
+          For example, to emulate the simple
+          <link href="http://maven.apache.org/">Maven</link> format:
+        </p>
+        <source>
          /xdocs
          /xdocs/images
          /xdocs/stylesheets
        </source>
-       <p>Here are the required property definitions:</p>
-       <source>
+        <p>
+          Here are the required property definitions:
+        </p>
+        <source>
 project.content-dir=xdocs
 project.sitemap-dir=${project.content-dir}
 project.xdocs-dir=${project.content-dir}
@@ -576,17 +601,15 @@
 project.skinconf=${project.content-dir}/skinconf.xml
          </source>
 <!-- FIXME: Does anyone know what this note means? -->
-         <note>
-           Internally, Forrest rearranges the specified directory into the default
-           <code>src/documentation/content/xdocs</code> structure. In the layout above, we have
-           overlapping directories, so you will end up with duplicate files. This small
-           glitch doesn't usually cause problems; just always remember that all links
-           are resolved through the sitemap.
-         </note>
-       </section>
-
-     </section>
-
+        <note>
+          Internally, Forrest rearranges the specified directory into the
+          default <code>src/documentation/content/xdocs</code> structure. In the
+          layout above, we have overlapping directories, so you will end up with
+          duplicate files. This small glitch doesn't usually cause problems;
+          just always remember that all links are resolved through the sitemap.
+        </note>
+      </section>
+    </section>
     <section id="adding_content">
       <title>Adding content</title>
       <p>
@@ -596,67 +619,68 @@
       <section id="site.xml">
         <title>site.xml</title>
         <p>
-          When adding a new xml document, you would add an entry to the project's
-          <code>site.xml</code> file. This site.xml is like a site index, and is rendered as
-          the vertical column of links in the default skin.  Look at Forrest's own
-          xdocs for an example.  More detailed info about site.xml is provided in 
-          the document <link href="site:linking">Menus and Linking</link>.
+          When adding a new xml document, you would add an entry to the
+          project's <code>site.xml</code> file. This site.xml is like a site
+          index, and is rendered as the vertical column of links in the default
+          skin. Look at Forrest's own xdocs for an example. More detailed info
+          about site.xml is provided in the document
+          <link href="site:linking">Menus and Linking</link>.
         </p>
       </section>
       <section id="tabs.xml">
         <title>tabs.xml</title>
         <p>
-          The <code>tabs.xml</code> file is used to produce the 'tabs'.
-          which enable users to quickly jump to sections of your site.
-          See the
+          The <code>tabs.xml</code> file is used to produce the 'tabs'. which
+          enable users to quickly jump to sections of your site. See the
           <link href="site:menu_generation">menu generation</link> documentation
           for more details, and again, consult Forrest's own docs for a usage
           example.
         </p>
         <figure src="images/tabs.png" alt="Tabs"/>
-        <p>You can have one or two levels of tabs. The images above show a 
-        single level. However, you can create a second level that
-        will only be displayed when its parent tab is selected. For example,
-        the <code>tabs.xml</code> snippet below will display either one or
-        two rows of tabs, depending on which of the top level tabs is selected.
-        The first row will have two tabs: one labelled <code>How-Tos</code>
-        and the other labelled <code>Apache XML Projects</code>. When the 
-        <code>How-Tos</code> tab is selected there will
-        be no second row of tabs. However, when the <code>Apache XML
-        Projects</code> tab is selected, a second row of tabs will be displayed
-        below the first.</p>
-        <source><![CDATA[
+        <p>
+          You can have one or two levels of tabs. The images above show a single
+          level. However, you can create a second level that will only be
+          displayed when its parent tab is selected. For example, the
+          <code>tabs.xml</code> snippet below will display either one or two
+          rows of tabs, depending on which of the top level tabs is selected.
+          The first row will have two tabs: one labelled <code>How-Tos</code>
+          and the other labelled <code>Apache XML Projects</code>. When the
+          <code>How-Tos</code> tab is selected there will be no second row of
+          tabs. However, when the <code>Apache XML Projects</code> tab is
+          selected, a second row of tabs will be displayed below the first.
+        </p>
+        <source>
+<![CDATA[
   <tab label="How-Tos" dir="community/howto/"/>
   <tab label="Apache XML Projects" href="http://xml.apache.org">
     <tab label="Forrest" href="http://forrest.apache.org/"/>
     <tab label="Xerces" href="http://xml.apache.org/xerces"/>
   </tab>
-]]></source>
+]]>
+        </source>
       </section>
       <section id="images">
         <title>Images</title>
         <p>
-          Images usually go in the <code>resources/images/</code> directory.
-          The default sitemap
-          maps this directory to <code>images/</code> so image tags will typically look
-          like <code>&lt;figure src="images/project-logo.png" alt="Project Logo"/&gt;</code> 
+          Images usually go in the <code>resources/images/</code> directory. The
+          default sitemap maps this directory to <code>images/</code> so image
+          tags will typically look like <code>&lt;figure
+          src="images/project-logo.png" alt="Project Logo"/&gt;</code>
         </p>
       </section>
     </section>
-
     <section id="sitemap.xmap">
       <title>Advanced customizations: sitemap.xmap</title>
       <p>
-        The Cocoon sitemap is a set of rules for generating content (HTML, PDFs etc)
-        from XML sources. Forrest has a default sitemap, which is adequate for
-        everyday sites. For example, the
-        <link href="site:forrest">Forrest website</link> itself uses the
-        default sitemap.
+        The Cocoon sitemap is a set of rules for generating content (HTML, PDFs
+        etc) from XML sources. Forrest has a default sitemap, which is adequate
+        for everyday sites. For example, the <link href="site:forrest">Forrest
+        website</link> itself uses the default sitemap.
       </p>
       <p>
-        Sometimes, one needs to go beyond the default set of rules. This is where
-        Forrest really shines, because its Cocoon backend allows virtually any
-        processing pipeline to be defined. For example, one can:
+        Sometimes, one needs to go beyond the default set of rules. This is
+        where Forrest really shines, because its Cocoon backend allows virtually
+        any processing pipeline to be defined. For example, one can:
       </p>
       <ul>
         <li>Transform custom XML content types with XSLT stylesheets.</li>
@@ -680,40 +704,38 @@
           samples.</li>
       </ul>
       <p>
-        The Forrest sitemaps are at
-        <code>main/webapp/*.xmap</code>
+        The Forrest sitemaps are at <code>main/webapp/*.xmap</code>
       </p>
-
       <p>
         You can add pre-processing sitemaps to your project
         <code>src/documentation</code> directory (or wherever
         <code>${project.sitemap-dir}</code> points to). Get a copy of a simple
-        sitemap.xmap from a 'forrest seed site'. </p>
-      <p>Any match that
-        is not handled, passes through to be handled by the default Forrest
-        sitemaps - obviously extremely powerful. The capability is described
-        in 
-        "<link href="site:project-sitemap">Using project sitemaps</link>"
-        and some worked examples are shown in the following sections here.
+        sitemap.xmap from a 'forrest seed site'.
+      </p>
+      <p>
+        Any match that is not handled, passes through to be handled by the
+        default Forrest sitemaps - obviously extremely powerful. The capability
+        is described in "<link href="site:project-sitemap">Using project
+        sitemaps</link>" and some worked examples are shown in the following
+        sections here.
       </p>
       <note>
-        We advise you to spend time to understand the Apache Cocoon sitemap.
-        See <link href="ext:cocoon/sitemap">Cocoon sitemap</link>
-        and <link href="ext:cocoon/concepts">Cocoon concepts</link>
-        and related component documentation.
-        The Forrest sitemap is broken into multiple files. The main one is
-        <strong>sitemap.xmap</strong> which delegates to others.  See the
-         <link href="site:sitemap-ref">Sitemap Reference</link> for a tour of the
-        default sitemap.
+        We advise you to spend time to understand the Apache Cocoon sitemap. See
+        <link href="ext:cocoon/sitemap">Cocoon sitemap</link> and
+        <link href="ext:cocoon/concepts">Cocoon concepts</link> and related
+        component documentation. The Forrest sitemap is broken into multiple
+        files. The main one is <strong>sitemap.xmap</strong> which delegates to
+        others. See the <link href="site:sitemap-ref">Sitemap Reference</link>
+        for a tour of the default sitemap.
       </note>
       <section id="adding_new_content_type">
         <title>Example: Adding a new content type</title>
         <p>
-          There are two methods for detecting types of documents
-          and doing special handling. The more complete solution is
-          <link href="#adding_new_content_type_2">described</link>
-          in the advanced section below. However, this basic method
-          is also worth understanding.
+          There are two methods for detecting types of documents and doing
+          special handling. The more complete solution is
+          <link href="#adding_new_content_type_2">described</link> in the
+          advanced section below. However, this basic method is also worth
+          understanding.
         </p>
         <p>
           Follow this worked example. In a fresh directory do 'forrest seed'
@@ -722,12 +744,13 @@
         <p>
           An example scenario is that we have a specialised list of downloads
           for a certain software package. It would be best to represent the
-          download information in a custom XML format. This means that it
-          will have its own document type declaration. We will need
-          to detect this new document type via our project sitemap
-          and also provide a mapping to a local copy of this DTD.
+          download information in a custom XML format. This means that it will
+          have its own document type declaration. We will need to detect this
+          new document type via our project sitemap and also provide a mapping
+          to a local copy of this DTD.
         </p>
-        <source><![CDATA[<?xml version="1.0" encoding="utf-8"?>
+        <source>
+<![CDATA[<?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
   "dtd/download-v10.dtd">
 <document> 
@@ -766,17 +789,21 @@
       <p>....</p>
     </section>
   </body>
-</document>]]></source>
-        <p>This file called "<code>download.xml</code>" would be placed in
-          your content directory (typically
+</document>]]>
+        </source>
+        <p>
+          This file called "<code>download.xml</code>" would be placed in your
+          content directory (typically
           <code>src/documentation/content/xdocs</code>) and an entry added to
-          <code>site.xml</code></p>
+          <code>site.xml</code>
+        </p>
         <p>
           To handle these special tags, one would write a stylesheet to convert
-          them to the intermediate Forrest xdocs structure. Here is such a stylesheet,
-          called "<code>download-to-document.xsl</code>" ...
+          them to the intermediate Forrest xdocs structure. Here is such a
+          stylesheet, called "<code>download-to-document.xsl</code>" ...
         </p>
-        <source><![CDATA[<?xml version="1.0" encoding="utf-8"?>
+        <source>
+<![CDATA[<?xml version="1.0" encoding="utf-8"?>
 <xsl:stylesheet
   version="1.0"
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
@@ -808,97 +835,101 @@
   </xsl:template>
 
 </xsl:stylesheet>
-]]></source>
-          <p>
-            Place this file in the default stylesheets directory,
-            <code>src/documentation/resources/stylesheets</code> (or wherever
-            ${project.stylesheets-dir} points).
-          </p>
-          <p>
-            Now we will create a project sitemap to control the
-            transformation of our custom xml
-            structure into the Forrest intermediate xdocs structure.
-          </p>
-          <note>
-            The <link href="site:sitemap-ref">Sitemap
-            Reference</link> provides details about how the sitemap works.
-          </note>
-          <p>
-            Add the following match to the file
-            <code>src/documentation/sitemap.xmap</code> ...
-          </p>
-          <source><![CDATA[<?xml version="1.0"?>
+]]>
+        </source>
+        <p>
+          Place this file in the default stylesheets directory,
+          <code>src/documentation/resources/stylesheets</code> (or wherever
+          ${project.stylesheets-dir} points).
+        </p>
+        <p>
+          Now we will create a project sitemap to control the transformation of
+          our custom xml structure into the Forrest intermediate xdocs
+          structure.
+        </p>
+        <note>
+          The <link href="site:sitemap-ref">Sitemap Reference</link> provides
+          details about how the sitemap works.
+        </note>
+        <p>
+          Add the following match to the file
+          <code>src/documentation/sitemap.xmap</code> ...
+        </p>
+        <source>
+<![CDATA[<?xml version="1.0"?>
 <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
  <map:pipelines>
   <map:pipeline>]]>
   ...
-  <strong><![CDATA[
+  <strong>
+<![CDATA[
    <map:match pattern="**download.xml">
     <map:generate src="{properties:content.xdocs}{1}download.xml" />
     <map:transform src="{properties:resources.stylesheets}/download-to-document.xsl" />
     <map:serialize type="xml"/>
    </map:match>
-]]></strong><![CDATA[
+]]></strong>
+<![CDATA[
   </map:pipeline>
  </map:pipelines>
 </map:sitemap>
-]]></source>
+]]>
+        </source>
+        <p>
+          That will intercept the request for the body content, for only this
+          specific "download" document, and will transform it into the
+          intermediate Forrest "document" format. The normal Forrest machinery
+          will handle the aggregation with navigation menus etc. and will apply
+          the normal skin.
+        </p>
+        <section id="new_dtd">
+          <title>Registering a new DTD</title>
           <p>
-            That will intercept the request for the body content, for only
-            this specific "download" document, and will transform it into the
-            intermediate Forrest "document" format. The normal Forrest machinery
-            will handle the aggregation with navigation menus etc. and will
-            apply the normal skin.
+            By default, Forrest requires that all XML files be valid, i.e. they
+            must have a DOCTYPE declaration and associated DTD, and validate
+            against it. Our new 'downloads' document type is no exception. The
+            <link href="site:validation">XML Validation</link> document
+            continues this example, showing how to register a new document type.
+            Briefly, this involves:
           </p>
-
-            <section id="new_dtd">
-              <title>Registering a new DTD</title>
-              <p>
-                 By default, Forrest requires that all XML files be valid, i.e.
-                 they must have a DOCTYPE declaration and associated DTD, and
-                 validate against it.  Our new 'downloads' document type is no
-                 exception.  The <link href="site:validation">XML
-                   Validation</link> document continues this example, showing how
-                 to register a new document type.  Briefly, this involves:
-               </p>
-               <ul>
-                 <li>Create a new DTD or (in our case) extend an existing
+          <ul>
+            <li>Create a new DTD or (in our case) extend an existing
                    one.</li>
-                 <li>Place the new DTD in the
+            <li>Place the new DTD in the
                    <code>${project.schema-dir}/dtd</code> directory.</li>
-                 <li>Add an XML Catalog to enable a mapping from the
+            <li>Add an XML Catalog to enable a mapping from the
                    DOCTYPE public id to the relevant DTD file.</li>
-                 <li>Tell the system about your catalog.</li>
-               </ul>
-               <note>
-                 Please see <link href="site:validation">XML Validation</link>
-                 for the complete description for those steps.
-               </note>
-            </section>
-          </section>
-
-          <section id="adding_new_content_type_2">
-            <title>Example: Adding a new content type (advanced)</title>
-            <p>
-              The simple user sitemap in the previous example is fine for
-              simple situations. For a complete solution to the "Download DTD"
-              issue we need a more advanced sitemap which will do different
-              processing depending on the type of the source document.
-            </p>
-            <p>
-              We need to digress and explain the powerful 
-              <link href="site:cap">SourceTypeAction (content aware pipelines)</link>.
-              It is a Cocoon sitemap component that peeks at the top-part of
-              a document to look for hints about the type of the document.
-              It has four methods: document-declaration, document-element and
-              namespace, processing-instruction, w3c-xml-schema.
-            </p>
-            <p>
-             Now to return to our specific example which uses SourceTypeAction
-             to detect the Document Type Declaration. Let us show the sitemap
-             and then explain it.
-            </p>
-            <source><![CDATA[<?xml version="1.0"?>
+            <li>Tell the system about your catalog.</li>
+          </ul>
+          <note>
+            Please see <link href="site:validation">XML Validation</link> for
+            the complete description for those steps.
+          </note>
+        </section>
+      </section>
+      <section id="adding_new_content_type_2">
+        <title>Example: Adding a new content type (advanced)</title>
+        <p>
+          The simple user sitemap in the previous example is fine for simple
+          situations. For a complete solution to the "Download DTD" issue we
+          need a more advanced sitemap which will do different processing
+          depending on the type of the source document.
+        </p>
+        <p>
+          We need to digress and explain the powerful
+          <link href="site:cap">SourceTypeAction (content aware
+          pipelines)</link>. It is a Cocoon sitemap component that peeks at the
+          top-part of a document to look for hints about the type of the
+          document. It has four methods: document-declaration, document-element
+          and namespace, processing-instruction, w3c-xml-schema.
+        </p>
+        <p>
+          Now to return to our specific example which uses SourceTypeAction to
+          detect the Document Type Declaration. Let us show the sitemap and then
+          explain it.
+        </p>
+        <source>
+<![CDATA[<?xml version="1.0"?>
 <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
 
  <map:components>
@@ -943,174 +974,182 @@
   </map:pipeline>
  </map:pipelines>
 </map:sitemap>
-]]></source>
-            <p>
-              This is the type of processing that happens in the main
-              <code>main/webapp/forrest.xmap</code> sitemap. We have
-              added similar handling to our project sitemap. Basically, this
-              uses the <link href="site:cap">SourceTypeAction (content aware pipelines)</link>
-              to detect the doctype. The new document-v11.dtd needs to be also
-              added to your project Catalog as
-              <link href="#new_dtd">described above</link>.
-            </p>
-            <p>
-              Note that any sitemap component must be declared before it
-              can be used, because the project sitemap is the first sitemap
-              to be consulted.
-            </p>
-          </section>
-
-          <section id="integrating_rss">
-            <title>Example: integrating external RSS content</title>
-            <p>Similar to the previous example, we can integrate RSS into our
-              site simply by providing a match in our project sitemap.xmap ...
-            </p>
-            <source><![CDATA[<?xml version="1.0"?>
+]]>
+        </source>
+        <p>
+          This is the type of processing that happens in the main
+          <code>main/webapp/forrest.xmap</code> sitemap. We have added similar
+          handling to our project sitemap. Basically, this uses the
+          <link href="site:cap">SourceTypeAction (content aware
+          pipelines)</link> to detect the doctype. The new document-v11.dtd
+          needs to be also added to your project Catalog as
+          <link href="#new_dtd">described above</link>.
+        </p>
+        <p>
+          Note that any sitemap component must be declared before it can be
+          used, because the project sitemap is the first sitemap to be
+          consulted.
+        </p>
+      </section>
+      <section id="integrating_rss">
+        <title>Example: integrating external RSS content</title>
+        <p>
+          Similar to the previous example, we can integrate RSS into our site
+          simply by providing a match in our project sitemap.xmap ...
+        </p>
+        <source>
+<![CDATA[<?xml version="1.0"?>
 <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
  <map:pipelines>
-  <map:pipeline>]]>
-  <strong><![CDATA[
+  <map:pipeline>]]><strong>
+<![CDATA[
    <map:match pattern="**weblog.xml">
     <map:generate src="http://blogs.cocoondev.org/stevenn/index.rss"/>
     <map:transform src="{forrest:forrest.stylesheets}/rss-to-document.xsl"/>
     <map:serialize type="xml"/>
    </map:match>
-]]></strong><![CDATA[
+]]></strong>
+<![CDATA[
    <map:match pattern=".......">
     <!-- handle other project-specific matches -->
    </map:match>
   </map:pipeline>
  </map:pipelines>
 </map:sitemap>
-]]></source>
-            <p>You will probably want to copy the core Forrest 
-              <code>rss-to-document.xsl</code> to your project,
-              customise it to your needs, and refer to it with
-              <code>src="{properties:resources.stylesheets}/rss-to-document.xsl"</code>.
-              Then of course you would add an entry to site.xml to link
-              to weblog.html
-            </p>
-          </section>
-      </section>
-
-      <section id="skins">
-        <title>Forrest skins</title>
+]]>
+        </source>
         <p>
-          As Forrest separates content from presentation, we can plug in different
-          "skins" to instantly change a site's look and feel.  Forrest provides one
-          primary skin, <code>pelt</code>, and some others in various
-          states of development.
+          You will probably want to copy the core Forrest
+          <code>rss-to-document.xsl</code> to your project, customise it to your
+          needs, and refer to it with
+          <code>src="{properties:resources.stylesheets}/rss-to-document.xsl"</code>.
+          Then of course you would add an entry to site.xml to link to
+          weblog.html
         </p>
+      </section>
+    </section>
+    <section id="skins">
+      <title>Forrest skins</title>
+      <p>
+        As Forrest separates content from presentation, we can plug in different
+        "skins" to instantly change a site's look and feel. Forrest provides one
+        primary skin, <code>pelt</code>, and some others in various states of
+        development.
+      </p>
+      <p>
+        To change the skin, edit the <code>forrest.properties</code> file to set
+        <code>project.skin=pelt</code> or some other skin name. If running in
+        dynamic mode you need to restart Forrest in order to see the new skin.
+      </p>
+      <note>
+        Forrest supplies a collection of <link href="site:skins">default
+        skins</link> which are configurable and so should meet the needs of most
+        projects. The aim is to provide many capabilities so that extra skins
+        are not needed.
+      </note>
+      <section id="skin-configuration">
+        <title>Configuration of skins</title>
         <p>
-          To change the skin, edit the <code>forrest.properties</code> file
-          to set <code>project.skin=pelt</code> or some other skin name.
-          If running in dynamic mode you need to restart Forrest in order to see
-          the new skin.
-        </p>
-        <note>
-          Forrest supplies a collection of 
-          <link href="site:skins">default skins</link> which are configurable
-          and so should meet the needs of most projects. The aim is to provide
-          many capabilities so that extra skins are not needed.
-        </note>
-
-        <section id="skin-configuration">
-          <title>Configuration of skins</title>
-          <p>
           All configuration is done via your project
-          <code>src/documentation/skinconf.xml</code> file.
-          It contains many comments to describe each capability.
-          Please read those, there is no point repeating here.
-          </p>
-        </section>
-
-        <section id="new_skin">
-          <title>Defining a new skin</title>
-          <p>Consider discussing your needs on the mailing lists. There may
-          be planned enhancements to the core skins. Also consider contributing
+          <code>src/documentation/skinconf.xml</code> file. It contains many
+          comments to describe each capability. Please read those, there is no
+          point repeating here.
+        </p>
+      </section>
+      <section id="new_skin">
+        <title>Defining a new skin</title>
+        <p>
+          Consider discussing your needs on the mailing lists. There may be
+          planned enhancements to the core skins. Also consider contributing
           your extensions to the core skins, rather than write your own skin.
           Bear in mind that you could be creating an update and management
           issue. Anyway, ...
-          </p>
-          <p>
-            Projects can define their own skin in the
-            <code>src/documentation/skins</code> directory (or wherever
-            <code>${project.skins-dir}</code> points). The default sitemap assumes a
-            certain skin layout, so the easiest way to create a new skin is by
-            copying an existing Forrest skin.  For example, copy
-            <code>main/webapp/skins/pelt</code>
-            to your project area at
-            <code>src/documentation/skins/my-fancy-skin</code> and add
-            <code>project.skin=my-fancy-skin</code> to forrest.properties
-          </p>
-          <p>
-            The two most interesting XSLT stylesheets involved are:
-          </p>
-          <dl>
-            <dt><code>xslt/html/document-to-html.xsl</code></dt>
-            <dd>
+        </p>
+        <p>
+          Projects can define their own skin in the
+          <code>src/documentation/skins</code> directory (or wherever
+          <code>${project.skins-dir}</code> points). The default sitemap assumes
+          a certain skin layout, so the easiest way to create a new skin is by
+          copying an existing Forrest skin. For example, copy
+          <code>main/webapp/skins/pelt</code> to your project area at
+          <code>src/documentation/skins/my-fancy-skin</code> and add
+          <code>project.skin=my-fancy-skin</code> to forrest.properties
+        </p>
+        <p>
+          The two most interesting XSLT stylesheets involved are:
+        </p>
+        <dl>
+          <dt><code>xslt/html/document-to-html.xsl</code></dt>
+          <dd>
               This stylesheet is applied to individual Forrest xdocs XML files, and
               converts them to HTML suitable for embedding in a larger HTML page.
             </dd>
-            <dt><code>xslt/html/site-to-xhtml.xsl</code></dt>
-            <dd>
+          <dt><code>xslt/html/site-to-xhtml.xsl</code></dt>
+          <dd>
               This stylesheet generates the final HTML file from an intermediate
               'site' structure produced by the other stylesheets. It defines the general
               layout, and adds the header and footer.
             </dd>
-          </dl>
-          <p>
-            Typically there is a lot of commonality between skins.  XSLT
-            provides an 'import' mechanism whereby one XSLT can extend another.
-            Forrest XSLTs typically 'import' from a common base:
-          </p>
-          <source><![CDATA[
+        </dl>
+        <p>
+          Typically there is a lot of commonality between skins. XSLT provides
+          an 'import' mechanism whereby one XSLT can extend another. Forrest
+          XSLTs typically 'import' from a common base:
+        </p>
+        <source>
+<![CDATA[
 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 
   <xsl:import href="../../../common/xslt/html/document-to-html.xsl"/>
 
-  ]]><strong>... overrides of default templates ...</strong><![CDATA[ 
-</xsl:stylesheet>]]></source>
-
-          <p>In order to use this feature in your custom skins you must copy
-          the common skin from the forrest distribution into your custom skins 
-          directory (from <code>main/webapp/skins/common</code>).
-          This will protect your skin from changes in the Forrest common skin,
-          but you must remember to update this skin in order to take advantage
-          of new features added over time by the Forrest team.</p>
-          
-          <note>The above paragraph means that if you do copy an existing skin
-          as this section recomends you will also need to copy the common skin
-          since all existing skins import the common skin.</note>
-          
-          <p>This is particularly relevant for menu rendering (book-to-menu.xsl),
-            where the common stylesheet does the 'logic' of which item is
-            selected, and over-riding stylesheets define the presentation.</p>
-        </section>
+  ]]><strong>... overrides of default templates ...</strong>
+<![CDATA[ 
+</xsl:stylesheet>]]>
+        </source>
+        <p>
+          In order to use this feature in your custom skins you must copy the
+          common skin from the forrest distribution into your custom skins
+          directory (from <code>main/webapp/skins/common</code>). This will
+          protect your skin from changes in the Forrest common skin, but you
+          must remember to update this skin in order to take advantage of new
+          features added over time by the Forrest team.
+        </p>
+        <note>
+          The above paragraph means that if you do copy an existing skin as this
+          section recomends you will also need to copy the common skin since all
+          existing skins import the common skin.
+        </note>
+        <p>
+          This is particularly relevant for menu rendering (book-to-menu.xsl),
+          where the common stylesheet does the 'logic' of which item is
+          selected, and over-riding stylesheets define the presentation.
+        </p>
       </section>
-
+    </section>
     <section id="webapp">
       <title>Interactive Forrest: faster turnaround when developing your docs</title>
       <p>
-        In comparison to simpler tools (like 
-        <link href="ext:anakia">Anakia</link>) the Cocoon command-line mode
-        (and hence Forrest command-line mode) is slow.
-        As the <link href="site:dreams">dream list</link> notes, Forrest was
-        originally intended to be used for
-        dynamic sites, and the Cocoon crawler used only to create static
-        snapshots for mirroring.  This section describes how, by using
-        a "live" Forrest webapp instance, the Forrest-based documentation
+        In comparison to simpler tools (like
+        <link href="ext:anakia">Anakia</link>) the Cocoon command-line mode (and
+        hence Forrest command-line mode) is slow. As the
+        <link href="site:dreams">dream list</link> notes, Forrest was originally
+        intended to be used for dynamic sites, and the Cocoon crawler used only
+        to create static snapshots for mirroring. This section describes how, by
+        using a "live" Forrest webapp instance, the Forrest-based documentation
         development can be faster and easier than with comparable tools.
       </p>
       <section id="forrest_run">
         <title>Running as a webapp</title>
         <p>
-          Type '<code>forrest run</code>' in your project root to start Forrest's
-          built-in Jetty web server.  Once it has started, point your browser at
-          <link href="http://localhost:8888/">http://localhost:8888/</link>, which
-          will show your website, rendered on demand as each link is followed.
+          Type '<code>forrest run</code>' in your project root to start
+          Forrest's built-in Jetty web server. Once it has started, point your
+          browser at
+          <link href="http://localhost:8888/">http://localhost:8888/</link>,
+          which will show your website, rendered on demand as each link is
+          followed.
         </p>
-        <p>(Alternatively, if you wish to run Forrest from within an existing
+        <p>
+          (Alternatively, if you wish to run Forrest from within an existing
           servlet container, type <code>forrest webapp</code> to build an open
           webapp in <code>build/webapp/</code>)
         </p>
@@ -1129,10 +1168,12 @@
       <p>
         Ant has an
         <link href="http://ant.apache.org/manual/CoreTasks/import.html">&lt;import&gt;</link>
-        task which can be used to invoke Forrest from Ant.  All targets and properties
-        are imported and can be used in your project build.  Here is a simple example:
+        task which can be used to invoke Forrest from Ant. All targets and
+        properties are imported and can be used in your project build. Here is a
+        simple example:
       </p>
-      <source><![CDATA[
+      <source>
+<![CDATA[
 <project name="myproject" default="hello">
      <!-- FORREST_HOME must be set as an environment variable -->
      <property environment="env"/>
@@ -1144,37 +1185,37 @@
        <echo>something here</echo>
      </target>
 </project>
-        ]]></source>
-
-      <warning>See issue
+        ]]>
+      </source>
+      <warning>
+        See issue
         <link href="http://issues.apache.org/jira/browse/FOR-145">FOR-145</link>
         which causes clashes of Ant target names.
       </warning>
-
-      <warning>There is a bug in the plugin download mechanism in
-      Forrest 0.7 that may prevent
-      your plugins being installed correctly when calling Forrest from ANT. You
-      can work around this bug by either ensuring a version number is 
-      defined for the plugin in forrest.properties or by manually 
-      installing the required plugins.
+      <warning>
+        There is a bug in the plugin download mechanism in Forrest 0.7 that may
+        prevent your plugins being installed correctly when calling Forrest from
+        ANT. You can work around this bug by either ensuring a version number is
+        defined for the plugin in forrest.properties or by manually installing
+        the required plugins.
       </warning>
-        
-      <p>Because you are using your own version
-      of Ant to do Forrest's work, you will need to provide the
-      supporting catalog entity resolver:
-      '<code>cp forrest/lib/core/xml-commons-resolver-1.1.jar $ANT_HOME/lib</code>'
-      </p>
-
-      <p>Note: The technique described above requires Ant 1.6+ otherwise
-        the &lt;import&gt;
-        task will not be available for you to use. Forrest
-        bundles the latest version of Ant, so you can invoke your project
-        like this: '<code>forrest -f myproject.xml</code>'.
-        This will not run the '<code>forrest</code>' command. It will just
-        use Forrest's Ant and resolver to execute your buildfile.
+      <p>
+        Because you are using your own version of Ant to do Forrest's work, you
+        will need to provide the supporting catalog entity resolver: '<code>cp
+        forrest/lib/core/xml-commons-resolver-1.1.jar $ANT_HOME/lib</code>'
+      </p>
+      <p>
+        Note: The technique described above requires Ant 1.6+ otherwise the
+        &lt;import&gt; task will not be available for you to use. Forrest
+        bundles the latest version of Ant, so you can invoke your project like
+        this: '<code>forrest -f myproject.xml</code>'. This will not run the
+        '<code>forrest</code>' command. It will just use Forrest's Ant and
+        resolver to execute your buildfile.
       </p>
       <p>
-        Another option is to use the Forrest Antlet from the Krysalis Project's <link href="http://antworks.sourceforge.net/importer/">Antworks Importer</link>.
+        Another option is to use the Forrest Antlet from the Krysalis Project's
+        <link href="http://antworks.sourceforge.net/importer/">Antworks
+        Importer</link>.
       </p>
       <p>
         The <link href="site:forrestbot">Forrestbot</link> provides workstages

Modified: forrest/trunk/site-author/content/xdocs/documentation_bestpractices.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/documentation_bestpractices.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/documentation_bestpractices.xml (original)
+++ forrest/trunk/site-author/content/xdocs/documentation_bestpractices.xml Mon Apr  9 20:48:52 2007
@@ -22,23 +22,28 @@
     <title>Documentation Best Practices</title>
   </header>
   <body>
-   
     <section id="goldenRules">
       <title>Golden Rules</title>
-        <p>
-            All help is welcome building and maintaining Forrest documentation. But please take the time to read this
-            before you start.
-        </p>  
+      <p>
+        All help is welcome building and maintaining Forrest documentation. But
+        please take the time to read this before you start.
+      </p>
       <ul>
-          <li><p>Never physically move an existing file in docs unless you really have to. Consider the alternative of
-              moving the file in site. See site for examples.</p></li>
-          <li><p>If you physically move a file, make sure you add an entry in the section '# Some moved documents' of
-              <code>site-author/content/.htaccess</code>. The entry will redirect visitors from old (invalid) urls to
-              the new URL of a resource and should look like this:<br/>
-              <code>RedirectMatch ^/[old URL] http://[new URL]</code></p>
-          </li>
+        <li><p>
+            Never physically move an existing file in docs unless you really
+            have to. Consider the alternative of moving the file in site. See
+            site for examples.
+          </p></li>
+        <li><p>
+            If you physically move a file, make sure you add an entry in the
+            section '# Some moved documents' of
+            <code>site-author/content/.htaccess</code>. The entry will redirect
+            visitors from old (invalid) urls to the new URL of a resource and
+            should look like this:
+            <br/>
+            <code>RedirectMatch ^/[old URL] http://[new URL]</code>
+          </p></li>
       </ul>
-        
     </section>
   </body>
 </document>



Mime
View raw message