From site-svn-return-84-apmail-forrest-site-svn-archive=forrest.apache.org@forrest.apache.org Tue Apr 10 04:45:13 2007 Return-Path: Delivered-To: apmail-forrest-site-svn-archive@locus.apache.org Received: (qmail 77211 invoked from network); 10 Apr 2007 04:45:07 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 10 Apr 2007 04:45:07 -0000 Received: (qmail 68868 invoked by uid 500); 10 Apr 2007 04:45:13 -0000 Delivered-To: apmail-forrest-site-svn-archive@forrest.apache.org Received: (qmail 68829 invoked by uid 500); 10 Apr 2007 04:45:13 -0000 Mailing-List: contact site-svn-help@forrest.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@forrest.apache.org Delivered-To: mailing list site-svn@forrest.apache.org Received: (qmail 68819 invoked by uid 99); 10 Apr 2007 04:45:13 -0000 Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 09 Apr 2007 21:45:13 -0700 X-ASF-Spam-Status: No, hits=-99.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 09 Apr 2007 21:44:57 -0700 Received: by eris.apache.org (Postfix, from userid 65534) id 4758E1A9862; Mon, 9 Apr 2007 21:44:11 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r527020 [11/20] - in /forrest/site: ./ docs_0_80/ docs_0_80/howto/ docs_0_80/howto/cvs-ssh/ docs_0_80/howto/multi/ dtdx/ plan/ pluginDocs/plugins_0_70/ pluginDocs/plugins_0_80/ procedures/ procedures/release/ skins/ tools/ Date: Tue, 10 Apr 2007 04:44:05 -0000 To: site-svn@forrest.apache.org From: crossley@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20070410044411.4758E1A9862@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: forrest/site/docs_0_80/validation.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_80/validation.html?view=diff&rev=527020&r1=527019&r2=527020 ============================================================================== --- forrest/site/docs_0_80/validation.html (original) +++ forrest/site/docs_0_80/validation.html Mon Apr 9 21:44:00 2007 @@ -362,23 +362,28 @@

Introduction

- 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.

- 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.

Forrest also uses the XML Document Type Declaration to effect the - Content Aware Pipelines. 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. + Content Aware Pipelines. 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.

- 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.

- 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.

@@ -386,22 +391,22 @@

XML validation

- 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 - 'forrest validate' 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 'forrest validate' in the + project root directory.

For an XML file to be valid, it must 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.

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 forrest.properties:

@@ -439,13 +444,12 @@
Note
The failonerror properties only work for files validated - with Ant's <xmlvalidate> and not (yet) for those validated - with <jing>, where failonerror defaults to + with Ant's <xmlvalidate> and not (yet) for those validated with + <jing>, where failonerror defaults to true.
-

Validating new XML types

@@ -453,24 +457,25 @@

Forrest provides an OASIS Catalog [see tutorial] - forrest/main/webapp/resources/schema/catalog.xcat - as a means of associating public identifiers - (e.g. -//APACHE//DTD Documentation V1.1//EN above) with DTDs. - If you add a new content type, you - should add the DTD to ${project.schema-dir}/dtd/ and add - an entry to the ${project.schema-dir}/catalog.xcat file. This - section describes the details of this process. + forrest/main/webapp/resources/schema/catalog.xcat as a + means of associating public identifiers (e.g. -//APACHE//DTD + Documentation V1.1//EN above) with DTDs. If you + add a new content + type, you should add the DTD to + ${project.schema-dir}/dtd/ and add an entry to the + ${project.schema-dir}/catalog.xcat file. This section + describes the details of this process.

Creating or extending a 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 download format - 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 + download format + 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: 

 <!ELEMENT release (downloads)>
@@ -492,10 +497,10 @@
           The
           forrest/main/webapp/resources/schema/dtd/document-v13.dtd
           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
           common-charents-v10.mod and
-          document-v13.mod.  Here is the full DTD, with
-          explanation to follow.
+          document-v13.mod. Here is the full DTD, with explanation
+          to follow.
         

 
 <!-- ===================================================================
@@ -552,137 +557,141 @@
 <!-- End of DTD -->
 <!-- =============================================================== -->
         

-
This custom DTD should be placed in your project resources
-        directory at src/documentation/resources/schema/dtd/
+

+          This custom DTD should be placed in your project resources directory
+          at src/documentation/resources/schema/dtd/
+        
 

 

-          The <!ENTITY % ... > blocks are so-called 
+          The <!ENTITY % ... > blocks are so-called
           parameter
-            entities.  They are like macros, whose content will be
-          inserted when a parameter-entity reference, like
-          %common-charents; or %document; is
-          inserted.
+          entities. They are like macros, whose content will be inserted
+          when a parameter-entity reference, like %common-charents;
+          or %document; is inserted.
         

 

           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 %document; 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 <release> 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 %document; 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 <release> 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.
         

 

-          We now have a DTD for the 'download' document type. 
+          We now have a DTD for the 'download' document type.
         

 

 
Note

 

-        
+          
 Chapter
-            5: Customizing DocBook of Norman Walsh's "DocBook: The
+          5: Customizing DocBook of Norman Walsh's "DocBook: The
           Definitive Guide" gives a complete overview of the process of
           customizing a DTD.
         

 

-
+
 
Associating DTDs with document types

 

-          Recall that our DOCTYPE declaration for our download document type
-          is:
+          Recall that our DOCTYPE declaration for our download document type is:
         

 
<!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
           "download-v10.dtd">
         

 

-          We only care about the quoted section after PUBLIC, 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 PUBLIC,
+          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.

+          Catalog file.
+        

 

 
Note

 

           See this article for a good
           introduction to catalogs and the Cocoon documentation
-          Entity resolution with catalogs.
+          Entity resolution with
+          catalogs.
         

 

 

           Forrest provides a standard catalog file at
-          forrest/main/webapp/resources/schema/catalog.xcat
-          for the document types that Forrest supplies.
+          forrest/main/webapp/resources/schema/catalog.xcat for the
+          document types that Forrest supplies.
         

 

-          An additional system-wide catalog can be configured for use by multiple forrest-based projects.
-          See the "local-catalog" parameter in main/webapp/WEB-INF/xconf/forrest-core.xconf
+          An additional system-wide catalog can be configured for use by
+          multiple forrest-based projects. See the "local-catalog" parameter in
+          main/webapp/WEB-INF/xconf/forrest-core.xconf
         
 

 

           Projects can augment this with their own catalog file located in
           ${project.schema-dir}/catalog.xcat to use it you must
-	    specify either the path (full or relative) to your 
-	    catalog.xcat in the CatalogManager.properties
-	    file. If you provide a relative path you must set the property 
-	    relative-catalogs to "yes".
-	  

-

-          When Cocoon starts, it reads the CatalogManager.properties file from your
-          project.classes-dir. This is usually src/documentation/classes/
-          but you can change this in forrest.properties. When you seed 
-          a new site using forrest seed 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
+          catalog.xcat in the
+          CatalogManager.properties file. If you provide a relative
+          path you must set the property relative-catalogs to
+          "yes".
+        

+

+          When Cocoon starts, it reads the
+          CatalogManager.properties file from your
+          project.classes-dir. This is usually
+          src/documentation/classes/ but you can change this in
+          forrest.properties. When you seed a new site using
+          forrest seed a sample catalog file is placed in the site
+          structure, you can use this as a template for your own files.
         

 

           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:
         

-
<?xml version="1.0"?>
+
+<?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>

+</catalog>
+        

 

           The format is described in the
-          spec, and is fairly simple and very powerful.
-          The "public" elements map
-          a public identifier to a DTD (relative to the catalog file).
+          spec, and is fairly simple and very powerful. The
+          "public" elements map a public identifier to a DTD
+          (relative to the catalog file).
         

 

-          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 'forrest validate-xdocs'
-          our download file would validate along with all the others.  If
-          something goes wrong, try running 'forrest -v validate-xdocs' 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 'forrest
+          validate-xdocs' our download file would validate along with all
+          the others. If something goes wrong, try running 'forrest -v
+          validate-xdocs' to see the error in more detail.
         

 
-
     
-
+
 
Debugging the Catalog Entity Resolver

 

 

-        If you suspect problems with your project catalog, then raise the "verbosity"
-        level in src/documentation/classes/CatalogManager.properties
-        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
+        src/documentation/classes/CatalogManager.properties and
+        re-start forrest. This should show your project catalogs being parsed
+        and loaded.
       

 

-        However this configuration does not show your DTDs being resolved.
-        So raise the verbosity level in the central configuration at
-        main/webapp/WEB-INF/properties/dev/core.properties
-        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
+        main/webapp/WEB-INF/properties/dev/core.properties and
+        re-start forrest. This also shows the main catalogs being loaded and
+        shows the resolving of every DTD and entity set.
       

 

         When a DTD is successfully resolved you should see the message:
@@ -690,76 +699,71 @@
       
 

 

-        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.
       

 

-
     
-
+
 
Referring to entities

 

 

         Look at the source of this document
         (xdocs/docs/validation.xml) and see how the entity set
-        "Numeric and Special Graphic" is declared in the
-        document type declaration.
+        "Numeric and Special Graphic" is declared in the document
+        type declaration.
       

 
           
- 
-           
-           
+
+          
+          

         
 
ISOnum.pen&half;½ISOnum.pen&half;½
         
 

       
 

 

-
     
-
+
 
Validating in an XML 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 
-        configuration notes 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 configuration notes your
+        favourite editor.
       

 

-
     
-
+
 
Validation using RELAX NG

 

 

         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.
       

 

         The RNG grammars to do this are located in the
-        main/webapp/resources/schema/relaxng directory.
-        If you want to
-        know more about this, and perhaps extend it for your own use, then
-        see main/webapp/resources/schema/relaxng/README.txt
-        and the Ant targets in the various build.xml files.
+        main/webapp/resources/schema/relaxng directory. If you want
+        to know more about this, and perhaps extend it for your own use, then
+        see main/webapp/resources/schema/relaxng/README.txt and the
+        Ant targets in the various build.xml files.
       

 

-
     
-
+
 
Validation using Cocoon sitemap and the Cocoon Validation block

 

 

-        The content of pipelines can be validated at various points in the Cocoon sitemaps
-        using RELAX NG or W3C XML Schema.
-        See notes.
+        The content of pipelines can be validated at various points in the
+        Cocoon sitemaps using RELAX NG or W3C XML Schema. See
+        notes.
       

 

   

Modified: forrest/site/docs_0_80/validation.pdf
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_80/validation.pdf?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
Binary files - no diff available.

Modified: forrest/site/docs_0_80/your-project.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_80/your-project.html?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
--- forrest/site/docs_0_80/your-project.html (original)
+++ forrest/site/docs_0_80/your-project.html Mon Apr  9 21:44:00 2007
@@ -432,43 +432,54 @@
 
Introduction

 

 

-        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.
       

 

-
-   
+    
 
 
Installing Forrest

 

 

-       
-Download the latest release
-       of Forrest and follow the index.html in the top-level, or
-       if you want to try the development version, then
-       build Forrest from source.
-     

+        
+Download the latest release of
+        Forrest and follow the index.html in the top-level, or if you want to
+        try the development version, then build
+        Forrest from source.
+      

 
 
Setting up the Environment

 

-       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
-       message
-       explains further and provides other tips about using Windows.
-       

+          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
+          message
+          explains further and provides other tips about using Windows.
+        

 
 
In Unix/Linux:

-
change directory to the top-level of the forrest distribution and do ...

-
~/apache-forrest$ export FORREST_HOME=`pwd`

-
~/apache-forrest$ export PATH=$PATH:$FORREST_HOME/bin

+

+            change directory to the top-level of the forrest distribution and do
+            ...
+          

+

+            ~/apache-forrest$ export FORREST_HOME=`pwd`
+          

+

+            ~/apache-forrest$ export PATH=$PATH:$FORREST_HOME/bin
+          

 
 
Permanently Setting The Environment Variables for Linux/Unix

-
Export only changes the variables during that terminal session for that 
-           user, this is useful for testing. To permanently add the variable edit either 
-           /etc/bash.bashrc (for all users) or ~/.bash_profile
-           (for individual users). Add these lines to the end of the file you edit:

+

+              Export only changes the variables during that terminal session for
+              that user, this is useful for testing. To permanently add the
+              variable edit either /etc/bash.bashrc (for all users)
+              or ~/.bash_profile (for individual users). Add these
+              lines to the end of the file you edit:
+            

 
       FORREST_HOME=/full/path/to/forrest
       export FORREST_HOME
@@ -478,26 +489,42 @@
           

 
 
Windows 2000

-
Go to "My Computer", "Properties", "Advanced", "Environment Variables"

-
add a new variable FORREST_HOME as C:\full\path\to\apache-forrest
+

+            Go to "My Computer", "Properties", "Advanced", "Environment
+            Variables"
+          

+

+            add a new variable FORREST_HOME as
+            C:\full\path\to\apache-forrest
+          
 

-
edit PATH as %PATH%;%FORREST_HOME%\bin
+

+            edit PATH as %PATH%;%FORREST_HOME%\bin
+          
 

-
+
 
In Windows XP:

-
Go to "My Computer", "Properties", "Advanced", "Environment Variables"

-
Create a New variable with name: FORREST_HOME value: C:\full\path\to\apache-forrest

-
Edit PATH by adding ;%FORREST_HOME%\bin to the end of the current value.

-

-   
-   
-
+

+            Go to "My Computer", "Properties", "Advanced", "Environment
+            Variables"
+          

+

+            Create a New variable with name: FORREST_HOME value:
+            C:\full\path\to\apache-forrest
+          

+

+            Edit PATH by adding ;%FORREST_HOME%\bin to the end of the current
+            value.
+          

+
+    
+
 
The 'forrest' Command

 

 

-         To see what the 'forrest' command can do, type 'forrest -projecthelp'.
-         The build targets that are marked with * are the commonly used ones.
-         

+        To see what the 'forrest' command can do, type 'forrest -projecthelp'.
+        The build targets that are marked with * are the commonly used ones.
+      

 
   Apache Forrest.  Run 'forrest -projecthelp' to list options
   
@@ -543,15 +570,15 @@
   Default target: site
        

 

-          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.
-        

+        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.
+      

 

-
     
-
+
 
Seeding a new project

 

 

@@ -559,22 +586,28 @@
         documentation set to your project, which you can then customize.
       

 

-        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.
       

 

 
Note

 

-forrest seed is useful to see what is possible within Forrest,
-      but if you are creating a real site forrest seed-business 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.

+        
+forrest seed is useful to see what is possible within
+        Forrest, but if you are creating a real site forrest
+        seed-business 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.
+      

 

-
If you run forrest seed you should see output like this below:

+

+        If you run forrest seed you should see output like this
+        below:
+      

 
 [/home/me/forrest/my-test]$ forrest seed
 
@@ -633,7 +666,8 @@
 
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
+        :)
       

 
 

@@ -700,22 +734,22 @@
 |           `-- tabs_es.xml
       

 

-        To render this to HTML, type 'forrest'. You should have a HTML site rendered
-        into the build/site directory:
+        To render this to HTML, type 'forrest'. You should have a HTML site
+        rendered into the build/site directory:
       

 

 New project

 

         Practise with adding new content. Change to the directory
         src/documentation/content/xdocs and copy the file
-        index.xml to create my-new-file.xml as a
-        new document. Edit it to change some text. Add an entry to 
-        site.xml by copying one of the other entries and
-        changing it to suit. Now do 'forrest' to see the result.
+        index.xml to create my-new-file.xml as a new
+        document. Edit it to change some text. Add an entry to
+        site.xml by copying one of the other entries and changing
+        it to suit. Now do 'forrest' to see the result.
       

 
     
-
+
 
Seeding an existing project

 

 

@@ -729,27 +763,28 @@
         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
-        forrest.properties (consult
-        the Changing the layout
-        section for more details).
+        forrest.properties (consult the
+        Changing the layout section for
+        more details).
       

 

     
-
+
 
Customizing your project

 

 

-        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.
       

-
+
 
Configuring the Forrest skin: skinconf.xml

 

           Most Forrest skins can be customized through a single XML file,
           src/documentation/skinconf.xml, which looks like this:
         

 
+
 <!--
 Skin configuration file. This file contains details of your project,
 which will be used to configure the chosen Forrest skin.
@@ -909,36 +944,36 @@
   </credits>
 
 </skinconfig>
-

+
+

- Customise this file for your project. The images/ directory - mentioned in 'project-logo' and 'group-logo' elements corresponds to the - src/documentation/resources/images directory - (this mapping is done automatically by the sitemap). + Customise this file for your project. The images/ + directory mentioned in 'project-logo' and 'group-logo' elements + corresponds to the src/documentation/resources/images + directory (this mapping is done automatically by the sitemap).

- 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.

- +

Changing the layout: forrest.properties

- 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.

The forrest.properties 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.

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.

@@ -964,21 +999,23 @@ #project.classes-dir=${project.content-dir}/classes

- For example, if you wish to keep XML documentation in src/xdocs rather than - src/documentation/content/xdocs simply change the - definition for project.xdocs-dir -

+ For example, if you wish to keep XML documentation in src/xdocs rather + than src/documentation/content/xdocs simply change the + definition for project.xdocs-dir + 

project.xdocs-dir=src/xdocs

- For example, to emulate the simple - Maven format: -

+ For example, to emulate the simple + Maven format: + 

          /xdocs
          /xdocs/images
          /xdocs/stylesheets
-

Here are the required property definitions:

+

+ Here are the required property definitions: + 

 project.content-dir=xdocs
 project.sitemap-dir=${project.content-dir}
@@ -990,17 +1027,16 @@
 

 
Note

 

-           Internally, Forrest rearranges the specified directory into the default
-           src/documentation/content/xdocs 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.
-         

+          Internally, Forrest rearranges the specified directory into the
+          default src/documentation/content/xdocs 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.
+        

 
 
-
     
-
+
 
Adding content

 

 

@@ -1008,71 +1044,72 @@
         src/documentation/content/xdocs
       
 

-
+
 
site.xml

 

-          When adding a new xml document, you would add an entry to the project's
-          site.xml 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 Menus and Linking.
+          When adding a new xml document, you would add an entry to the
+          project's site.xml 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
+          Menus and Linking.
         

-
+
 
tabs.xml

 

-          The tabs.xml file is used to produce the 'tabs'.
-          which enable users to quickly jump to sections of your site.
-          See the
+          The tabs.xml file is used to produce the 'tabs'. which
+          enable users to quickly jump to sections of your site. See the
           menu generation documentation
           for more details, and again, consult Forrest's own docs for a usage
           example.
         

 

 Tabs

-
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 tabs.xml 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 How-Tos
-        and the other labelled Apache XML Projects. When the 
-        How-Tos tab is selected there will
-        be no second row of tabs. However, when the Apache XML
-        Projects tab is selected, a second row of tabs will be displayed
-        below the first.

+

+          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
+          tabs.xml 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 How-Tos
+          and the other labelled Apache XML Projects. When the
+          How-Tos tab is selected there will be no second row of
+          tabs. However, when the Apache XML Projects tab is
+          selected, a second row of tabs will be displayed below the first.
+        

 
+
   <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>
-

-
+
+
+

Images

- Images usually go in the resources/images/ directory. - The default sitemap - maps this directory to images/ so image tags will typically look - like <figure src="images/project-logo.png" alt="Project Logo"/> + Images usually go in the resources/images/ directory. The + default sitemap maps this directory to images/ so image + tags will typically look like <figure + src="images/project-logo.png" alt="Project Logo"/>

- - +

Advanced customizations: sitemap.xmap

- 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 - Forrest website 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 Forrest + website itself uses the default sitemap.

- 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:

    @@ -1103,43 +1140,42 @@

- The Forrest sitemaps are at - main/webapp/*.xmap + The Forrest sitemaps are at main/webapp/*.xmap

You can add pre-processing sitemaps to your project src/documentation directory (or wherever ${project.sitemap-dir} points to). Get a copy of a simple - sitemap.xmap from a 'forrest seed site'.

-

Any match that - is not handled, passes through to be handled by the default Forrest - sitemaps - obviously extremely powerful. The capability is described - in - "Using project sitemaps" - and some worked examples are shown in the following sections here. + sitemap.xmap from a 'forrest seed site'. +

+

+ Any match that is not handled, passes through to be handled by the + default Forrest sitemaps - obviously extremely powerful. The capability + is described in "Using project + sitemaps" and some worked examples are shown in the following + sections here.

Note
- We advise you to spend time to understand the Apache Cocoon sitemap. - See Cocoon sitemap - and Cocoon concepts - and related component documentation. - The Forrest sitemap is broken into multiple files. The main one is - sitemap.xmap which delegates to others. See the - Sitemap Reference for a tour of the - default sitemap. + We advise you to spend time to understand the Apache Cocoon sitemap. See + Cocoon sitemap and + Cocoon concepts and related + component documentation. The Forrest sitemap is broken into multiple + files. The main one is sitemap.xmap which delegates to + others. See the Sitemap Reference + for a tour of the default sitemap.
- +

Example: Adding a new content type

- There are two methods for detecting types of documents - and doing special handling. The more complete solution is - described - 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 + described in the + advanced section below. However, this basic method is also worth + understanding.

Follow this worked example. In a fresh directory do 'forrest seed' @@ -1148,12 +1184,13 @@

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.

-
<?xml version="1.0" encoding="utf-8"?>
+
+<?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
   "dtd/download-v10.dtd">
 <document> 
@@ -1192,18 +1229,22 @@
       <p>....</p>
     </section>
   </body>
-</document>

-
This file called "download.xml" would be placed in
-          your content directory (typically
+</document>
+
+

+ This file called "download.xml" would be placed in your + content directory (typically src/documentation/content/xdocs) and an entry added to site.xml +

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 "download-to-document.xsl" ... + them to the intermediate Forrest xdocs structure. Here is such a + stylesheet, called "download-to-document.xsl" ...

-
<?xml version="1.0" encoding="utf-8"?>
+
+<?xml version="1.0" encoding="utf-8"?>
 <xsl:stylesheet
   version="1.0"
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
@@ -1235,104 +1276,110 @@
   </xsl:template>
 
 </xsl:stylesheet>
-

+
+

- Place this file in the default stylesheets directory, - src/documentation/resources/stylesheets (or wherever - ${project.stylesheets-dir} points). -

+ Place this file in the default stylesheets directory, + src/documentation/resources/stylesheets (or wherever + ${project.stylesheets-dir} points). +

- Now we will create a project sitemap to control the - transformation of our custom xml - structure into the Forrest intermediate xdocs structure. -

+ Now we will create a project sitemap to control the transformation of + our custom xml structure into the Forrest intermediate xdocs + structure. +

Note
- The Sitemap - Reference provides details about how the sitemap works. -
+ The Sitemap Reference provides + details about how the sitemap works. +

- Add the following match to the file - src/documentation/sitemap.xmap ... -

-
<?xml version="1.0"?>
+          Add the following match to the file
+          src/documentation/sitemap.xmap ...
+        

+
+<?xml version="1.0"?>
 <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
  <map:pipelines>
   <map:pipeline>
   ...
   
+
    <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>
 
+
   </map:pipeline>
  </map:pipelines>
 </map:sitemap>
-

+
+

- 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. -

- + 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. +

+

Registering a new DTD

- 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 XML - Validation document continues this example, showing how - to register a new document type. Briefly, this involves: -

+ 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 + XML Validation document + continues this example, showing how to register a new document type. + Briefly, this involves: +

    - +
  • Create a new DTD or (in our case) extend an existing one.
    • - +
  • Place the new DTD in the ${project.schema-dir}/dtd directory.
    • - +
  • Add an XML Catalog to enable a mapping from the DOCTYPE public id to the relevant DTD file.
    • - +
  • Tell the system about your catalog.
    • - +
Note
- Please see XML Validation - for the complete description for those steps. -
+ Please see XML Validation for + the complete description for those steps. +
- +

Example: Adding a new content type (advanced)

- 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. -

+ 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. +

- We need to digress and explain the powerful - SourceTypeAction (content aware pipelines). - 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. -

+ We need to digress and explain the powerful + SourceTypeAction (content aware + pipelines). 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. +

- 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. -

-
<?xml version="1.0"?>
+          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.
+        

+
+<?xml version="1.0"?>
 <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
 
  <map:components>
@@ -1377,187 +1424,201 @@
   </map:pipeline>
  </map:pipelines>
 </map:sitemap>
-

+
+

- This is the type of processing that happens in the main - main/webapp/forrest.xmap sitemap. We have - added similar handling to our project sitemap. Basically, this - uses the SourceTypeAction (content aware pipelines) - to detect the doctype. The new document-v11.dtd needs to be also - added to your project Catalog as - described above. -

+ This is the type of processing that happens in the main + main/webapp/forrest.xmap sitemap. We have added similar + handling to our project sitemap. Basically, this uses the + SourceTypeAction (content aware + pipelines) to detect the doctype. The new document-v11.dtd + needs to be also added to your project Catalog as + described above. +

- Note that any sitemap component must be declared before it - can be used, because the project sitemap is the first sitemap - to be consulted. -

- + Note that any sitemap component must be declared before it can be + used, because the project sitemap is the first sitemap to be + consulted. +

+

Example: integrating external RSS content

-

Similar to the previous example, we can integrate RSS into our - site simply by providing a match in our project sitemap.xmap ... -

-
<?xml version="1.0"?>
+

+          Similar to the previous example, we can integrate RSS into our site
+          simply by providing a match in our project sitemap.xmap ...
+        

+
+<?xml version="1.0"?>
 <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
  <map:pipelines>
-  <map:pipeline>
-  
+  <map:pipeline>
+
    <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>
 
+
    <map:match pattern=".......">
     <!-- handle other project-specific matches -->
    </map:match>
   </map:pipeline>
  </map:pipelines>
 </map:sitemap>
-

-
You will probably want to copy the core Forrest 
-              rss-to-document.xsl to your project,
-              customise it to your needs, and refer to it with
-              src="{properties:resources.stylesheets}/rss-to-document.xsl".
-              Then of course you would add an entry to site.xml to link
-              to weblog.html
-            

-
 
-      
-
+
+

+ You will probably want to copy the core Forrest + rss-to-document.xsl to your project, customise it to your + needs, and refer to it with + src="{properties:resources.stylesheets}/rss-to-document.xsl". + Then of course you would add an entry to site.xml to link to + weblog.html +

+ + +

Forrest skins

- 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, pelt, and some others in various - states of development. -

+ 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, pelt, and some others in various states of + development. +

- To change the skin, edit the forrest.properties file - to set project.skin=pelt or some other skin name. - If running in dynamic mode you need to restart Forrest in order to see - the new skin. -

+ To change the skin, edit the forrest.properties file to set + project.skin=pelt or some other skin name. If running in + dynamic mode you need to restart Forrest in order to see the new skin. +

Note
- Forrest supplies a collection of - default skins 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. -
+ Forrest supplies a collection of default + skins 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. +
- +

Configuration of skins

All configuration is done via your project - src/documentation/skinconf.xml file. - It contains many comments to describe each capability. - Please read those, there is no point repeating here. -

- + src/documentation/skinconf.xml file. It contains many + comments to describe each capability. Please read those, there is no + point repeating here. +

+

Defining a new skin

-

Consider discussing your needs on the mailing lists. There may - be planned enhancements to the core skins. Also consider contributing +

+ 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, ... -

+

- Projects can define their own skin in the - src/documentation/skins directory (or wherever - ${project.skins-dir} 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 - main/webapp/skins/pelt - to your project area at - src/documentation/skins/my-fancy-skin and add - project.skin=my-fancy-skin to forrest.properties -

+ Projects can define their own skin in the + src/documentation/skins directory (or wherever + ${project.skins-dir} 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 + main/webapp/skins/pelt to your project area at + src/documentation/skins/my-fancy-skin and add + project.skin=my-fancy-skin to forrest.properties +

- The two most interesting XSLT stylesheets involved are: -

+ The two most interesting XSLT stylesheets involved are: +

- +
xslt/html/document-to-html.xsl
- +
This stylesheet is applied to individual Forrest xdocs XML files, and converts them to HTML suitable for embedding in a larger HTML page.
- +
xslt/html/site-to-xhtml.xsl
- +
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.
- +

- 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: -

+ 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: + 

+
 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 
   <xsl:import href="../../../common/xslt/html/document-to-html.xsl"/>
 
-  ... overrides of default templates ... 
-</xsl:stylesheet>
-

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 main/webapp/skins/common). - 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.

+ ... overrides of default templates ... + +</xsl:stylesheet> + +

+ 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 main/webapp/skins/common). 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. +

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.
-
-

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.

+
+ 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. +
+ +

+ 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. +

- - +

Interactive Forrest: faster turnaround when developing your docs

- In comparison to simpler tools (like - Anakia) the Cocoon command-line mode - (and hence Forrest command-line mode) is slow. - As the dream list 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 + Anakia) the Cocoon command-line mode (and + hence Forrest command-line mode) is slow. As the + dream list 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.

- +

Running as a webapp

- Type 'forrest run' in your project root to start Forrest's - built-in Jetty web server. Once it has started, point your browser at - http://localhost:8888/, which - will show your website, rendered on demand as each link is followed. + Type 'forrest run' in your project root to start + Forrest's built-in Jetty web server. Once it has started, point your + browser at + http://localhost:8888/, + which will show your website, rendered on demand as each link is + followed.

-

(Alternatively, if you wish to run Forrest from within an existing +

+ (Alternatively, if you wish to run Forrest from within an existing servlet container, type forrest webapp to build an open webapp in build/webapp/)

- +

Using the webapp

You can now edit the XML content in @@ -1566,16 +1627,18 @@

- +

Invoking Forrest from Ant

Ant has an <import> - 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: 

+
 <project name="myproject" default="hello">
      <!-- FORREST_HOME must be set as an environment variable -->
      <property environment="env"/>
@@ -1587,39 +1650,43 @@
        <echo>something here</echo>
      </target>
 </project>
-
+ +
Warning
-
See issue +
+ See issue FOR-145 which causes clashes of Ant target names.
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. +
+ 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.
-

Because you are using your own version - of Ant to do Forrest's work, you will need to provide the - supporting catalog entity resolver: - 'cp forrest/lib/core/xml-commons-resolver-1.1.jar $ANT_HOME/lib' -

-

Note: The technique described above requires Ant 1.6+ otherwise - the <import> - task will not be available for you to use. Forrest - bundles the latest version of Ant, so you can invoke your project - like this: 'forrest -f myproject.xml'. - This will not run the 'forrest' command. It will just - use Forrest's Ant and resolver to execute your buildfile. +

+ Because you are using your own version of Ant to do Forrest's work, you + will need to provide the supporting catalog entity resolver: 'cp + forrest/lib/core/xml-commons-resolver-1.1.jar $ANT_HOME/lib' +

+

+ Note: The technique described above requires Ant 1.6+ otherwise the + <import> task will not be available for you to use. Forrest + bundles the latest version of Ant, so you can invoke your project like + this: 'forrest -f myproject.xml'. This will not run the + 'forrest' command. It will just use Forrest's Ant and + resolver to execute your buildfile.

- Another option is to use the Forrest Antlet from the Krysalis Project's Antworks Importer. + Another option is to use the Forrest Antlet from the Krysalis Project's + Antworks + Importer.

The Forrestbot provides workstages Modified: forrest/site/docs_0_80/your-project.pdf URL: http://svn.apache.org/viewvc/forrest/site/docs_0_80/your-project.pdf?view=diff&rev=527020&r1=527019&r2=527020 ============================================================================== Binary files - no diff available. Modified: forrest/site/documentation_bestpractices.html URL: http://svn.apache.org/viewvc/forrest/site/documentation_bestpractices.html?view=diff&rev=527020&r1=527019&r2=527020 ============================================================================== --- forrest/site/documentation_bestpractices.html (original) +++ forrest/site/documentation_bestpractices.html Mon Apr 9 21:44:00 2007 @@ -238,30 +238,36 @@

-

Golden Rules

- All help is welcome building and maintaining Forrest documentation. But please take the time to read this - before you start. -

+ All help is welcome building and maintaining Forrest documentation. But + please take the time to read this before you start. +

    - +
  • -

    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.

    +

    + 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. +

    • - +
  • -

    If you physically move a file, make sure you add an entry in the section '# Some moved documents' of - site-author/content/.htaccess. The entry will redirect visitors from old (invalid) urls to - the new URL of a resource and should look like this:
    - +

    + If you physically move a file, make sure you add an entry in the + section '# Some moved documents' of + site-author/content/.htaccess. The entry will redirect + visitors from old (invalid) urls to the new URL of a resource and + should look like this: +
    + RedirectMatch ^/[old URL] http://[new URL] -

    +