<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2005 The Apache Software Foundation or its licensors,
  as applicable.

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!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>
  </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.
      </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:v0.70//developers/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.
       </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-0.7$ export FORREST_HOME=`pwd`</p>
         <p class="instruction">~/apache-forrest-0.7$ 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-0.7</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-0.7</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>
  Apache Forrest.  Run 'forrest -projecthelp' to list options
  
  Buildfile: /usr/local/svn/forrest/src/core/bin/../forrest.build.xml
  
      *=======================================================*
      |                 Forrest Site Builder                  |
      |                        X.Y-dev                        |
      *=======================================================*
    
               Call this through the 'forrest' command
    
  Main targets:
  
   available-plugins     What plugins are available?
   available-skins       What skins are available?
   clean                 * Clean all directories and files generated during
                          the build
   init-plugins          Ensure the required plugins are available locally,
                         if any are not, download them automatically
   install-skin          Install the needed skin from the remote repository
   package-skin          Make a package of an existing skin
   run                   * Run Jetty (instant live webapp)
   run_custom_jetty      Run Jetty with configuration file found in the project
   run_default_jetty     Run Jetty with configuration file found in Forrest
   seed                  * Seeds a directory with a template project doc structure
   site                  * Generates a static HTML website for this project
   validate              Validate all: xdocs, skins, sitemap, etc
   validate-sitemap      Validate the project sitemaps
   validate-skinchoice   Validate skin choice
   validate-skinconf     Validate skinconf
   validate-skins        Validate skins
   validate-stylesheets  Validate XSL files
   validate-xdocs        Validate the project xdocs
   war                   * Generates a dynamic servlet-based website
                           (a packaged .war file)
   webapp                Generates a dynamic servlet-based website
                           (an unpackaged webapp).
   webapp-local          Generates a dynamic servlet-based website
                           (an unpackaged webapp). Note this webapp is suitable
                           for local execution only, use the 'war' or 'webapp'
                           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" 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>
        'Seeding' a project is our own arborial term for adding a template
        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':
      </p>
      <source>
[/home/me/forrest/my-test]$ forrest seed

Apache Forrest.  Run 'forrest -projecthelp' to list options

Buildfile: /usr/local/svn/forrest/src/core/bin/../forrest.build.xml

init-props:
Loading project specific properties from
 /home/me/forrest/my-test/forrest.properties
...
echo-settings:

check-contentdir:

ensure-nocontent:

seed:
Copying 41 files to /home/me/forrest/my-test

-------------------------------
~~ Template project created! ~~

Here is an outline of the generated files:

/                        # /home/me/forrest/my-test
/status.xml              # List of project developers, todo list and change log
/forrest.properties      # Optional file describing your site layout
/src/documentation/      # Doc-specific files
/src/documentation/skinconf.xml    # Info about your project used by the skin
/src/documentation/content/xdocs   # Site content.
/src/documentation/content/xdocs   # XML content.
/src/documentation/content/xdocs/index.xml # Home page
/src/documentation/content/xdocs/site.xml  # Navigation file for site structure
/src/documentation/content/xdocs/tabs.xml  # Skin-specific 'tabs' file.
/src/documentation/content/xdocs/*.html,pdf # Static content files, may have subdirs
/src/documentation/resources/images   # Project images (logos, etc)
# you can create other directories as needed (see forrest.properties)


What to do now?

- Render this template to static HTML by typing 'forrest'.
  View the generated HTML in a browser to make sure everything works.
- Alternatively 'forrest run' and browse to http://localhost:8888/ live demo.
- Edit status.xml and src/documentation/skinconf.xml
  to customize for your project.
- Start adding content in xdocs/ remembering to declare new files in site.xml
- Follow the document http://forrest.apache.org/docs/your-project.html
- Provide any feedback to dev@forrest.apache.org

Thanks for using Apache Forrest
-------------------------------

BUILD SUCCESSFUL
Total time: 5 seconds
      </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 :)
      </note>
      <p>
        You now have a template documentation structure all set up:
      </p>
      <source>
[/home/me/forrest/my-test]$ tree
.
|-- build
|   `-- tmp
|       `-- projfilters.properties
|-- forrest.properties
|-- src
|   `-- documentation
|       |-- README.txt
|       |-- classes
|       |   `-- CatalogManager.properties
|       |-- content
|       |   `-- xdocs
|       |       |-- images
|       |       |   |-- group-logo.gif
|       |       |   |-- group.svg
|       |       |   |-- icon.png
|       |       |   |-- project-logo.gif
|       |       |   `-- project.svg
|       |       |-- index.xml
|       |       |-- samples
|       |       |   |-- ascii-art.xml
|       |       |   |-- cocoon-pyramid.aart
|       |       |   |-- faq.xml
|       |       |   |-- ihtml-sample.ihtml
|       |       |   |-- index.xml
|       |       |   |-- openoffice-writer.sxw
|       |       |   |-- sample.xml
|       |       |   |-- sample2.xml
|       |       |   |-- sdocbook.xml
|       |       |   |-- subdir
|       |       |   |   |-- book-sample.xml
|       |       |   |   `-- index.xml
|       |       |-- site.xml
|       |       |-- tabs.xml
|       |       |-- hello.pdf
|       |       |-- test1.html
|       |       `-- test2.html
|       |-- sitemap.xmap
|       |-- skinconf.xml
|       `-- translations
|           |-- langcode.xml
|           |-- languages_en.xml
|           |-- languages_es.xml
|           |-- menu.xml
|           |-- menu_af.xml
|           |-- menu_de.xml
|           |-- menu_es.xml
|           |-- menu_it.xml
|           |-- menu_no.xml
|           |-- menu_ru.xml
|           |-- menu_sk.xml
|           |-- tabs.xml
|           `-- tabs_es.xml
|-- status.xml
      </source>
      <p>
        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.
      </p>
    </section>
    <section id="seeding_existing">
      <title>Seeding an existing project</title>
      <p>
        In the section above, we have run 'forrest seed' in an empty directory
        to create a new project. If you have an existing codebase to which you
        want to add Forrest docs, then run 'forrest seed' in your project base
        directory, and the Forrest doc structure will be grafted onto your
        project. This procedure only needs to be done once.
      </p>
      <p>
        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).
      </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.
      </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[
<!--
Skin configuration file. This file contains details of your project,
which will be used to configure the chosen Forrest skin.
-->

 <!DOCTYPE skinconfig PUBLIC
        "-//APACHE//DTD Skin Configuration V0.6-3//EN"
        "skinconfig-v06-3.dtd">

<skinconfig>
  <!-- To enable lucene search add provider="lucene"
    Add box-location="alt" to move the search box to an alternate location
    (if the skin supports it) and box-location="all" to show it in all
    available locations on the page.  Remove the <search> element to show
    no search box.
  -->
  <search name="MyProject" domain="mydomain"/>

  <!-- Disable the print link? If enabled, invalid HTML 4.0.1 -->
  <disable-print-link>true</disable-print-link>  
  <!-- Disable the PDF link? -->
  <disable-pdf-link>false</disable-pdf-link>
  <!-- Disable the xml source link? -->
  <!-- The xml source link makes it possible to access the xml rendition
    of the source frim the html page, and to have it generated statically.
    This can be used to enable other sites and services to reuse the
    xml format for their uses. Keep this disabled if you don't want other
    sites to easily reuse your pages.-->
  <disable-xml-link>true</disable-xml-link>
  
  <!-- Disable navigation icons on all external links? -->
  <disable-external-link-image>false</disable-external-link-image>
  
  <!-- Disable w3c compliance links? -->
  <disable-compliance-links>false</disable-compliance-links>
  <!-- Render mailto: links unrecognisable by spam harvesters? -->
  <obfuscate-mail-links>true</obfuscate-mail-links>

  <!-- mandatory project logo
       skin: forrest-site renders it at the top -->
  <project-name>MyProject</project-name>
  <project-description>MyProject Description</project-description>
  <project-url>http://myproj.mygroup.org/</project-url>
  <project-logo>images/project.png</project-logo>
  <!-- Alternative static image:
  <project-logo>images/project-logo.gif</project-logo> -->

  <!-- optional group logo
       skin: forrest-site renders it at the top-left corner -->
  <group-name>MyGroup</group-name>
  <group-description>MyGroup Description</group-description>
  <group-url>http://mygroup.org</group-url>
  <group-logo>images/group.png</group-logo>
  <!-- Alternative static image:
  <group-logo>images/group-logo.gif</group-logo> -->

  <!-- optional host logo (e.g. sourceforge logo)
       skin: forrest-site renders it at the bottom-left corner -->
  <host-url></host-url>
  <host-logo></host-logo>
  
  <!-- relative url of a favicon file, normally favicon.ico -->
  <favicon-url></favicon-url>

  <!-- The following are used to construct a copyright statement -->
  <year>2004</year>
  <vendor>The Acme Software Foundation.</vendor>
  <!-- The optional copyright-link URL will used as a link in the
    copyright statement
  <copyright-link>http://www.apache.org/licenses/</copyright-link>
  -->

  <!-- Some skins use this to form a 'breadcrumb trail' of links.
    If you don't want these, then set the attributes to blank.
    The DTD purposefully requires them.
    Use location="alt" to move the trail to an alternate location
    (if the skin supports it).
  -->
  <trail>
    <link1 name="myGroup" href="http://www.apache.org/"/>
    <link2 name="myProject" href="http://forrest.apache.org/"/>
    <link3 name="" href=""/>
  </trail>

  <!-- Configure the TOC, i.e. the Table of Contents.
  @max-depth
   how many "section" levels need to be included in the
   generated Table of Contents (TOC). 
  @min-sections
   Minimum required to create a TOC.
  @location ("page","menu","page,menu")
   Where to show the TOC.
  -->
  <toc max-depth="2" min-sections="1" location="page"/>

  <!-- Heading types can be clean|underlined|boxed  -->
  <headings type="boxed"/>

  <extra-css>
    <!-- A sample to show how the class attribute can be used -->
    p.quote {
      margin-left: 2em;
      padding: .5em;
      background-color: #f0f0f0;
      font-family: monospace;
    }
  </extra-css>

  <colors>
  <!-- CSS coloring examples omitted for brevity -->
  </colors>
 
  <!-- Settings specific to PDF output.  -->
  <pdf>
    <!-- 
       Supported page sizes are a0, a1, a2, a3, a4, a5, executive,
       folio, legal, ledger, letter, quarto, tabloid (default letter).
       Supported page orientations are portrait, landscape (default
       portrait).
       Supported text alignments are left, right, justify (default left).
    -->
    <page size="letter" orientation="portrait" text-align="left"/>

    <!--
       Margins can be specified for top, bottom, inner, and outer
       edges. If double-sided="false", the inner edge is always left
       and the outer is always right. If double-sided="true", the
       inner edge will be left on odd pages, right on even pages,
       the outer edge vice versa.
       Specified below are the default settings.
    -->
    <margins double-sided="false">
      <top>1in</top>
      <bottom>1in</bottom>
      <inner>1.25in</inner>
      <outer>1in</outer>
    </margins>

    <!--
      Print the URL text next to all links going outside the file
    -->
    <show-external-urls>false</show-external-urls>
  </pdf>

  <!-- Credits are typically rendered as a set of small clickable
    images in the page footer -->
  <credits>
    <credit>
      <name>Built with Apache Forrest</name>
      <url>http://forrest.apache.org/</url>
      <image>images/built-with-forrest-button.png</image>
      <width>88</width>
      <height>31</height>
    </credit>
    <!-- A credit with @role='pdf' will have its name and url
      displayed in the PDF page's footer. -->
  </credits>

</skinconfig>
]]></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).
        </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.
        </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.
        </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.
        </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.
        </note>
        <p>
          The main entries (with default values) are:
        </p>
        <source>
# Properties that must be set to override the default locations
#
# Parent properties must be set. This usually means uncommenting
# project.content-dir if any other property using it is uncommented

#project.status=status.xml
#project.content-dir=src/documentation
#project.conf-dir=${project.content-dir}/conf
#project.sitemap-dir=${project.content-dir}
#project.xdocs-dir=${project.content-dir}/content/xdocs
#project.resources-dir=${project.content-dir}/resources
#project.stylesheets-dir=${project.resources-dir}/stylesheets
#project.images-dir=${project.resources-dir}/images
#project.schema-dir=${project.resources-dir}/schema
#project.skins-dir=${project.content-dir}/skins
#project.skinconf=${project.content-dir}/skinconf.xml
#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>
       <p xml:space="preserve">
         /xdocs
         /xdocs/images
         /xdocs/stylesheets
       </p>
       <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}
project.stylesheets-dir=${project.content-dir}/stylesheets
project.images-dir=${project.content-dir}/images
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>

    <section id="adding_content">
      <title>Adding content</title>
      <p>
        Now you can start adding content of your own, in
        <code>src/documentation/content/xdocs</code>
      </p>
      <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:v0.70//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
          <link href="site:v0.70//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[
  <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>
      </section>
      <section id="images">
        <title>Images</title>
        <p>
          Images usually go in the <code>content/xdocs/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.
      </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:
      </p>
      <ul>
        <li>Transform custom XML content types with XSLT stylesheets.</li>
        <li>Generate PNG or JPEG images from 
        <link href="http://www.w3.org/TR/SVG/">SVG</link> XML files.
          (<strong>Note:</strong> Forrest's sitemap now does this natively.)</li>
        <li>Integrate external XML feeds (e.g. RSS) into your site's content.
          (<strong>Note:</strong> See issues.xmap for an example.)</li>
        <li>Merge XML sources via aggregation, or make content from large XML
          sources available as "virtual" files.
          (<strong>Note:</strong> Forrest makes extensive use of aggregation
          in the default sitemaps. It also defines a whole-site HTML
          and PDF, available as the standard names <code>wholesite.html</code>
          and <code>wholesite.pdf</code>.)</li>
        <li>Read content from exotic sources like
        <link href="http://www.rpbourret.com/xml/XMLDBLinks.htm">XML
            databases</link>.</li>
        <li>Integrate any of <link href="ext:cocoon">Cocoon's</link> vast array
          of capabilities.  The possibilities are best appreciated by
          downloading the latest Cocoon distribution and playing with the
          samples.</li>
      </ul>
      <p>
        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:v0.70//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:v0.70//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.
        </p>
        <p>
          Follow this worked example. In a fresh directory do 'forrest seed'
          then follow the steps described in this section.
        </p>
        <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.
        </p>
        <source><![CDATA[<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
  "dtd/download-v10.dtd">
<document> 
  <header>
    <title>Downloading Binaries</title>
  </header>
  <body>
    <section id="download">
      <title>Downloading binaries</title>
      <p>
        Here are the binaries for FooProject
      </p>
      <release version="0.9.13" date="2002-10-11">
        <downloads>
          <file
            url="http://prdownloads.sf.net/aft/fooproj-0.9.13-bin.zip?download"
            name="fooproj-0.9.13-bin.zip"
            size="5738322"/>
          <file
            url="http://prdownloads.sf.net/aft/fooproj-0.9.13-src.zip?download"
            name="fooproj-0.9.13-src.zip"
            size="10239777"/>
        </downloads>
      </release>
      <release version="0.9.12" date="2002-10-08">
        <downloads>
          <file
            url="http://prdownloads.sf.net/aft/fooproj-0.9.12-src.zip?download"
            name="fooproj-0.9.12-src.zip"
            size="10022737"/>
         </downloads>
       </release>
    </section>
    <section id="cvs">
      <title>Getting FooProject from CVS</title>
      <p>....</p>
    </section>
  </body>
</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>
        <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>download2document.xsl</code>" ...
        </p>
        <source><![CDATA[<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet
  version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:template match="release">
    <section id="{@version}">
      <title>Version <xsl:value-of select="@version"/> (released
          <xsl:value-of select="@date"/>)</title>
      <table>
        <tr><th>File</th><th>Size</th></tr>
        <xsl:apply-templates select="downloads/*"/>
      </table>
    </section>
  </xsl:template>

  <xsl:template match="file">
    <tr>
      <td><link href="{@url}"><xsl:value-of select="@name"/></link></td>
      <td><xsl:value-of
           select="format-number(@size div (1024*1024), '##.##')"/> MB</td>
    </tr>
  </xsl:template>

  <xsl:template match="@* | node() | comment()">
    <xsl:copy>
      <xsl:apply-templates select="@*"/>
      <xsl:apply-templates/>
    </xsl:copy>
  </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:v0.70//sitemap-ref">Sitemap
            Reference</link> provides details about how the sitemap works.
          </note>
          <p>
            Add the following as 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>
   <map:match pattern="**download.xml">
    <map:generate src="{project:content.xdocs}{1}download.xml" />
    <map:transform src="{project:resources.stylesheets}/download2document.xsl" />
    <map:serialize type="xml"/>
   </map:match>
  </map:pipeline>
 </map:pipelines>
</map:sitemap>
]]></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>
                 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:v0.70//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
                   one.</li>
                 <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
                   DOCTYPE public id to the relevant DTD file.</li>
                 <li>Tell the system about your catalog.</li>
               </ul>
               <note>
                 Please see <link href="site:v0.70//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:v0.70//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>
  <map:selectors default="parameter">
   <map:selector logger="sitemap.selector.parameter"
       name="parameter" src="org.apache.cocoon.selection.ParameterSelector" />
  </map:selectors>
  <map:actions>
   <map:action logger="sitemap.action.sourcetype" name="sourcetype"
       src="org.apache.forrest.sourcetype.SourceTypeAction">
    <sourcetype name="download-v1.0">
     <document-declaration
        public-id="-//Acme//DTD Download Documentation V1.0//EN" />
    </sourcetype>      
    <sourcetype name="download-v1.1">
     <document-declaration
        public-id="-//Acme//DTD Download Documentation V1.1//EN" />
    </sourcetype>      
   </map:action>
  </map:actions>
 </map:components>

 <map:pipelines>
  <map:pipeline>
   <map:match pattern="**download.xml">
    <map:generate src="{project:content.xdocs}{1}download.xml" />
    <map:act type="sourcetype" src="{project:content.xdocs}{1}download.xml">
     <map:select type="parameter">
      <map:parameter name="parameter-selector-test" value="{sourcetype}" />
      <map:when test="download-v1.0">
       <map:transform
          src="{project:resources.stylesheets}/download2document.xsl" />
      </map:when>
      <map:when test="download-v1.1">
       <map:transform
          src="{project:resources.stylesheets}/download-v11-2document.xsl" />
      </map:when>
     </map:select>
    </map:act>
    <map:serialize type="xml"/>
   </map:match>
  </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:v0.70//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:match pattern="**weblog.xml">
    <map:generate src="http://blogs.cocoondev.org/stevenn/index.rss"/>
    <map:transform src="{forrest:stylesheets}/rss2document.xsl"/>
    <map:serialize type="xml"/>
   </map:match>
]]></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>rss2document.xsl</code> to your project,
              customise it to your needs, and refer to it with
              <code>src="{project:resources.stylesheets}/rss2document.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.
          To change the skin, edit the <code>forrest.properties</code> file
          to set <code>project.skin=leather-dev</code> or some other skin name.
        </p>
        <note>
          Forrest supplies a collection of 
          <link href="site:v0.70//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
          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/document2html.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/site2xhtml.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[
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:import href="../../../common/xslt/html/document2html.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 (book2menu.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:v0.70//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.
        </p>
        <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>
        <section id="using_webapp">
          <title>Using the webapp</title>
          <p>
            You can now edit the XML content in
            <code>build/webapp/content/xdocs</code> and see the changes
            immediately in the browser.
          </p>
        </section>
      </section>
    </section>
    <section id="invoking_from_ant">
      <title>Invoking Forrest from Ant</title>
      <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:
      </p>
      <source><![CDATA[
<project name="myproject" default="hello">
     <!-- FORREST_HOME must be set as an environment variable -->
     <property environment="env"/>
     <property name="forrest.home" value="${env.FORREST_HOME}"/>
     <import file="${env.FORREST_HOME}/main/forrest.build.xml"/>

     <!-- 'site' is a target imported from forrest.build.xml -->
     <target name="post-build" depends="site">
       <echo>something here</echo>
     </target>
</project>
        ]]></source>
        
      <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>
      <p>
        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
        to get source, build, deploy, and notify. This is very useful for
        automating builds; you may want to consider using the Forrestbot.
      </p>
    </section>
  </body>
</document>
