forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r376128 [13/34] - in /forrest/site: ./ docs_0_60/ docs_0_60/howto/ docs_0_60/howto/bugzilla-patch/ docs_0_60/howto/multi/ docs_0_70/ docs_0_70/howto/ docs_0_70/howto/cvs-ssh/ docs_0_70/howto/multi/ docs_0_80/ docs_0_80/howto/ docs_0_80/howt...
Date Thu, 09 Feb 2006 00:26:32 GMT
Added: forrest/site/docs_0_70/sitemap-ref.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/sitemap-ref.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/sitemap-ref.source.xml (added)
+++ forrest/site/docs_0_70/sitemap-ref.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,765 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  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.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document>
+  <header>
+    <title>Forrest Sitemap Reference</title>
+  </header>
+  <body>
+    <p>
+      Technically, Forrest can be thought of as a 
+      <link href="ext:cocoon">Cocoon</link> distribution that has been stripped down
+      and optimized for people with simple site publishing needs.  Central to
+      Cocoon, and hence Forrest, is the <strong>sitemap</strong>.  The sitemap
+      defines the site's URI space (what pages are available), and how each page
+      is constructed.  Understanding the sitemap is the key to understanding
+      Forrest.
+    </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.
+    </note>
+    <p>
+      This document provides an overview of the special sitemap which
+      is used at the core of Apache Forrest.
+    </p>
+
+    <section id="getting_started">
+      <title>Getting started</title>
+      <p>
+        Forrest's sitemap comprises the $FORREST_HOME/main/webapp/*.xmap files.
+      </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). 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>".
+      </p>
+
+      <p>
+        Another way to experiment with the sitemap is to do '<code>forrest
+        run</code>' on a Forrest-using site.  Changes to the core
+        <code>*.xmap</code> files will now be immediately visible
+        at <code>&gt;http://localhost:8888/</code>
+      </p>
+    </section>
+
+    <section id="overview">
+      <title>Sitemap Overview</title>
+      <p>
+        Forrest's sitemap is divided both physically and logically.  The most
+        obvious is the physical separation.  There are a number of separate
+        *.xmap files, each defining pipelines for a functional area.  Each *.xmap
+        file has its purpose documented in comments at the top.  Here is a brief
+        overview of the files, in order of importance.
+      </p>
+      <table>
+        <tr>
+          <th colspan="1" rowspan="1"><strong>sitemap.xmap</strong></th>
+          <td colspan="1" rowspan="1">Primary sitemap file, which delegates responsibility for serving
+            certain URIs to the others (technically called sub-sitemaps).  More
+            about the structure of this file later.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">forrest.xmap</th>
+          <td colspan="1" rowspan="1">Sitemap defining Source pipelines, which generate the body section
+            of Forrest pages. All pipelines here deliver XML in Forrest's
+            intermediate "document-v13" format, regardless of originating source
+            or format.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">menu.xmap</th>
+          <td colspan="1" rowspan="1">Pipelines defining the XML that becomes the menu.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">linkmap.xmap</th>
+          <td colspan="1" rowspan="1">Defines a mapping from abstract ("site:index") to physical
+            ("index.html") links for the current page.  See 
+            <link href="site:v0.70//linking">Menus and Linking</link> for a conceptual
+            overview, and the <link href="#linkrewriting_impl">Link
+              rewriting</link> section for technical details.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">resources.xmap</th>
+          <td colspan="1" rowspan="1">Serves "resource" files (images, CSS, Javascript).</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">raw.xmap</th>
+          <td colspan="1" rowspan="1">Serves files located in <code>src/documentation/content/xdocs</code>
+            that are not to be modified by Forrest.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">aggregate.xmap</th>
+          <td colspan="1" rowspan="1">Generates a single page (HTML or PDF) containing all the content
+            for the site.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">faq.xmap</th>
+          <td colspan="1" rowspan="1">Processes FAQ documents.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">status.xmap</th>
+          <td colspan="1" rowspan="1">Generates <link href="site:v0.70//changes">changes</link> and 
+          <link href="site:v0.70//todo">todo</link> pages from a single
+            <code>status.xml</code> in the project root.
+          </td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">issues.xmap</th>
+          <td colspan="1" rowspan="1">Generates a page of content from an RSS feed.  Used in Forrest to
+            generate a "current issues" list from JIRA.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">revisions.xmap</th>
+          <td colspan="1" rowspan="1">
+            Support for HOWTO documents that want "revisions".  Revisions are
+            XML snippets containing comments on the main XML file.  The main
+            pipeline here automatically appends a page's revisions to the
+            bottom.
+          </td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">dtd.xmap</th>
+          <td colspan="1" rowspan="1">A Source pipeline that generates XML from a DTD, using Andy
+            Clark's 
+            <link href="http://www.apache.org/~andyc/neko/doc/dtd/index.html">DTD
+              Parser</link>.  Useful for documenting DTD-based XML schemas, such
+            as <link href="site:v0.70//dtd-docs">Forrest's own DTDs</link>.
+          </td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">profiler.xmap</th>
+          <td colspan="1" rowspan="1">Defines the "profiler" pipeline. allowing pipelines to be benchmarked.</td>
+        </tr>
+      </table>
+    </section>
+
+    <!--
+    <section>
+      <title>Logical structure</title>
+      <p>There are a few major groups of sitemap pipelines</p>
+      <dl>
+        <dt>Content pipelines</dt>
+        <dd>These define the body (without menu and header) for HTML pages, and all the content of PDFs.</dd>
+        <dt>Menu pileines.
+      </dl>
+    </section>
+    -->
+
+    <section id="source_pipelines">
+      <title>Source pipelines (**.xml)</title>
+      <p>
+        Most *.xmap files (forrest, aggregate, faq, status, issues, revisions,
+        dtd) define Source pipelines.  Source pipelines define the content
+        (body) XML for site pages.  The input XML format can be any format
+        (document-v13, Docbook, RSS, FAQ, Howto) and from any source (local or
+        remote).  The output format is always Forrest's intermediate "document-v13"
+        format.
+      </p>
+      <p>
+        Source pipelines always have a "<code>.xml</code>" extension.
+        Thus, 
+        <link href="index.xml">index.xml</link> gives you the XML source for the
+        index page.  Likewise, <link href="faq.xml">faq.xml</link> gives you XML
+        for the FAQ (transformed from FAQ syntax), and 
+        <link href="changes.xml">changes.xml</link> returns XML from the status.xml file.
+        Take any page, and replace its extension (<code>.html</code> or
+        <code>.pdf</code>) with <code>.xml</code> and you'll have the Source
+        XML.
+      </p>
+      <p>
+        This is quite powerful, because we now have an abstraction layer, or
+        "virtual filesystem", on which the rest of Forrest's sitemap can build.
+        Subsequent layers don't need to care whether the XML was obtained
+        locally or remotely, or from what format.  Wikis, RSS, FAQs and Docbook
+        files are all processed identically from here on.
+      </p>
+      <source xml:space="preserve">
+                   (subsequent Forrest pipelines)
+                                 |
+--------+------------------------^------------------------------------------
+        |          STANDARD FORREST FORMAT (current document-v13)
+        +-----^-------^--------^------------^------^-----^-----^------^-----
+SOURCE        |       |        |            |      |     |     |      |
+FORMATS    doc-v11  doc-v13  doc-v20 ... Docbook  FAQ  Howto  Wiki  RSS  ??
+(*.xml)
+                        (in forrest.xmap, faq.xmap, etc)
+      </source>
+      <section id="forrest_xmap">
+        <title>forrest.xmap</title>
+        <p>
+          Most of the usual Source pipelines are defined in
+          <code>forrest.xmap</code> which is the default (fallback) handler for
+          <code>**.xml</code> pages. The forrest.xmap uses the 
+          <link href="site:v0.70//cap">SourceTypeAction</link> to determine the type of XML
+          it is processing, and converts it to document-v13 if necessary.
+        </p>
+        <p>For instance, say we are rendering <link href="site:v0.70//write-howto">a
+            Howto document</link> called "howto-howto.xml".  It contains this DOCTYPE
+          declaration:</p>
+        <source xml:space="preserve">
+&lt;!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.3//EN"
+  "http://forrest.apache.org/dtd/howto-v13.dtd"&gt;</source>
+        <p>The SourceTypeAction sees this, and applies this transform to get it
+          to document-v13:</p>
+        <source xml:space="preserve"><![CDATA[
+          <map:when test="howto-v13">
+            <map:transform src="{forrest:stylesheets}/howto2document.xsl" />
+          </map:when>
+          ]]></source>
+          <!--
+    if we link to an intermediate .xml file, the CLI crawler tries
+    to fetch the @hrefs from it but they still have site: in them 
+    which causes it to break
+    
+        <p>
+          The intermediate result is visible at the URL 
+          <link href="../howto/howto-howto.xml">howtos/howto-howto.xml</link>.
+        </p>
+    -->
+      </section>
+      <section id="other_source">
+        <title>Other source pipelines</title>
+        <p>As mentioned above, all non-core Source pipelines are distributed in
+          independent <code>*.xmap</code> files.  There is a block of
+          <code>sitemap.xmap</code> which simply delegates certain requests to
+          these subsitemaps:</p>
+        <source xml:space="preserve"><![CDATA[
+      <!-- Body content -->
+      <map:match pattern="**.xml">
+        <map:match pattern="changes.xml">
+          <map:mount uri-prefix="" src="status.xmap" check-reload="yes" />
+        </map:match>
+
+        <map:match pattern="todo.xml">
+          <map:mount uri-prefix="" src="status.xmap" check-reload="yes" />
+        </map:match>
+
+        <map:match pattern="**dtdx.xml">
+          <map:mount uri-prefix="" src="dtd.xmap" check-reload="yes" />
+        </map:match>
+
+        <map:match pattern="forrest-issues.xml">
+          <map:mount uri-prefix="" src="issues.xmap" check-reload="yes" />
+        </map:match>
+
+        <map:match pattern="**faq.xml">
+          <map:mount uri-prefix="" src="faq.xmap" check-reload="yes" />
+        </map:match>
+
+        <map:match pattern="site.xml">
+          <map:mount uri-prefix="" src="aggregate.xmap" check-reload="yes" />
+        </map:match>
+        ....
+        ....]]></source>
+        <section id="late_binding_pipelines">
+          <title>Late-binding pipelines</title>
+          <p>
+            One point of interest here is that the sub-sitemap is often not
+            specific about which URLs it handles, and relies on the caller (the
+            section listed above) to only pass relevant requests to it.  We term
+            this "binding a URL" to a pipeline.</p>
+          <p>For instance, the main pipeline in <code>faq.xmap</code> matches
+            <code>**.xml</code>, but only <code>**faq.xml</code> requests are
+            sent to it.</p>
+          <p>This "late binding" is useful, because the whole URL space is
+            managed in <code>sitemap.xmap</code> and not spread over lots of
+            *.xmap files.  For instance, say you wish all <code>*.xml</code>
+            inside a "<code>faq/</code>" directory to be processed as FAQs.  Just
+            override <code>sitemap.xmap</code> and redefine the relevant source
+            matcher:</p>
+          <source xml:space="preserve"><![CDATA[
+        <map:match pattern="**faq.xml">
+          <map:mount uri-prefix="" src="faq.xmap" check-reload="yes" />
+        </map:match>]]></source>
+        </section>
+      </section>
+    </section>
+
+    <section id="output_pipelines">
+      <title>Output pipelines</title>
+      <p>
+        To recap, we now have a <code>*.xml</code> pipeline defined for each
+        page in the site, emitting standardized XML.  These pipeline definitions
+        are located in various *.xmap files, notably forrest.xmap
+      </p>
+      <p>
+        We now wish to render the XML from these pipelines to output formats
+        like HTML and PDF.
+      </p>
+      <section id="pdf">
+        <title>PDF output</title>
+        <p>
+          Easiest case first; PDFs don't require menus or headers, so we can
+          simply transform our intermediate format into XSL:FO, and from there
+          to PDF.  This is done by the following matcher in
+          <code>sitemap.xmap</code> ...
+        </p>
+        <source xml:space="preserve"><![CDATA[
+1   <map:match type="regexp" pattern="^(.*?)([^/]*).pdf$">
+2     <map:generate src="cocoon:/{1}{2}.xml"/>
+3     <map:transform type="xinclude"/>
+4     <map:transform type="]]>linkrewriter<![CDATA[" src="cocoon://{1}linkmap-{2}.pdf"/>
+5     <map:transform src="skins/{forrest:skin}/xslt/fo/document2fo.xsl">
+6       <map:parameter name="ctxbasedir" value="{realpath:.}/"/>
+7       <map:parameter name="xmlbasedir" value="content/xdocs/{1}"/>
+8     </map:transform>
+9     <map:serialize type="fo2pdf"/>
+10  </map:match>
+        ]]></source>
+        <ol>
+          <li>The first line uses a matching regexp to break the URL into
+            directory <code>(.*?)</code> and filename
+            <code>([^/]*)</code> parts.</li>
+          <li>We then generate XML from a <link href="#source_pipelines">Source
+              pipeline</link>, with the URL <code>cocoon:/{1}{2}.xml</code></li>
+          <li>We then expand any XInclude statements..</li>
+          <li>and <link href="#linkrewriting_impl">rewrite links</link>..</li>
+          <li>and finally apply the document2fo.xsl stylesheet, to generate
+            XSL:FO XML.</li>
+        </ol>
+        <p>Lastly, we generate a PDF using the fo2pdf serializer.</p>
+      </section>
+      <section id="html">
+        <title>HTML output</title>
+        <p>Generating HTML pages is more complicated, because we have to merge
+          the page body with a menu and tabs, and then add a header and footer.
+          Here is the <code>*.html</code> matcher in
+          <code>sitemap.xmap</code> ...</p>
+        <source xml:space="preserve">
+          &lt;map:match pattern="*.html"&gt;
+            &lt;map:aggregate element="site"&gt;
+            &lt;map:part src="<link href="#tab_pipeline">cocoon:/tab-{0}</link>"/&gt;
+            &lt;map:part src="<link href="#menu_pipeline">cocoon:/menu-{0}</link>"/&gt;
+            &lt;map:part src="<link href="#body_pipeline">cocoon:/body-{0}</link>"/&gt;
+            &lt;/map:aggregate&gt;
+            &lt;map:call resource="skinit"&gt;
+              &lt;map:parameter name="type" value="site2xhtml"/&gt;
+              &lt;map:parameter name="path" value="{0}"/&gt;
+            &lt;/map:call&gt;
+          &lt;/map:match&gt;
+        </source>
+        <p>
+          So <link href="index.html">index.html</link> is formed from
+          aggregating <link href="body-index.html">body-index.html</link> and
+          <link href="menu-index.html">menu-index.html</link> and 
+          <link href="tab-index.html">tab-index.html</link> and then applying the
+          <code>site2xhtml.xsl</code> stylesheet to the result.
+        </p>
+        <p>
+          There is a nearly identical matcher for HTML files in subdirectories:
+        </p>
+        <source xml:space="preserve">
+          &lt;map:match pattern="**/*.html"&gt;
+            &lt;map:aggregate element="site"&gt;
+            &lt;map:part src="<link href="#tab_pipeline">cocoon:/{1}/tab-{2}.html</link>"/&gt;
+            &lt;map:part src="<link href="#menu_pipeline">cocoon:/{1}/menu-{2}.html</link>"/&gt;
+            &lt;map:part src="<link href="#body_pipeline">cocoon:/{1}/body-{2}.html</link>"/&gt;
+            &lt;/map:aggregate&gt;
+            &lt;map:call resource="skinit"&gt;
+              &lt;map:parameter name="type"
+                value="site2xhtml"/&gt;
+              &lt;map:parameter name="path"
+                value="{0}"/&gt;
+            &lt;/map:call&gt;
+          &lt;/map:match&gt;
+        </source>
+      </section>
+    </section>
+    <section id="intermediate_pipelines">
+      <title>Intermediate pipelines</title>
+      <section id="body_pipeline">
+        <title>Page body</title>
+        <p>Here is the matcher which generates the page body:</p>
+        <source xml:space="preserve"><![CDATA[
+1   <map:match pattern="**body-*.html">
+2     <map:generate src="cocoon:/{1}{2}.xml"/>
+3     <map:transform type="idgen"/>
+4     <map:transform type="xinclude"/>
+5     <map:transform type="]]>linkrewriter<![CDATA[" src="cocoon:/{1}linkmap-{2}.html"/>
+6     <map:call resource="skinit">
+7       <map:parameter name="type" value="document2html"/>
+8       <map:parameter name="path" value="{1}{2}.html"/>
+9       <map:parameter name="notoc" value="false"/>
+10    </map:call>
+11  </map:match>
+          ]]></source>
+        <ol>
+          <li>In our matcher pattern, {1} will be the directory (if any) and {2}
+            will be the filename.</li>
+          <li>First, we obtain XML content from a source pipeline</li>
+          <li>
+            <p>We then apply a custom-written
+              <code>IdGeneratorTransformer</code>, which ensures that every
+              &lt;section&gt; has an "id" attribute if one is not supplied, by generating one from the
+              &lt;title&gt; if necessary.  For example, &lt;idgen&gt; will
+              transform:</p>
+            <source xml:space="preserve">
+              &lt;section&gt;
+              &lt;title&gt;How to boil eggs&lt;/title&gt;
+              ...
+            </source>
+            <p>into:</p>
+            <source xml:space="preserve">
+              &lt;section id="How+to+boil+eggs"&gt;
+              &lt;title&gt;How to boil eggs&lt;/title&gt;
+              ...
+            </source>
+            <p>Later, the <code>document2html.xsl</code> stylesheet will create
+              an &lt;a name&gt; element for every section, allowing this section to
+              be referred to as <code>index.html#How+to+boil+eggs</code>.</p>
+          </li>
+          <li>We then expand XInclude elements.</li>
+          <li>and <link href="#linkrewriting_impl">rewrite links</link>..</li>
+          <li>and then finally apply the stylesheet that generates a fragment of
+            HTML (minus the outer elements like
+            &lt;html&gt; and &lt;body&gt;) suitable for merging with the menu and tabs.</li>
+        </ol>
+      </section>
+      <section id="menu_pipeline">
+        <title>Page menu</title>
+        <p>In the <code>sitemap.xmap</code> file, the matcher generating HTML for the menu is:</p>
+        <source xml:space="preserve"><![CDATA[
+      <map:match pattern="**menu-*.html">
+        <map:generate src="cocoon:/{1}book-{2}.html"/>
+        <map:transform type="]]>linkrewriter<![CDATA[" src="cocoon:/{1}linkmap-{2}.html"/>
+        <map:call resource="skinit">
+          <map:parameter name="type" value="book2menu"/>
+          <map:parameter name="path" value="{1}{2}.html"/>
+        </map:call>
+      </map:match>
+      ]]></source>
+        <p>We get XML from a "book" pipeline, 
+        <link href="#linkrewriting_impl">rewrite links</link>, and apply the
+          <code>book2menu.xsl</code> stylesheet to generate HTML.</p>
+        <p>How the menu XML is actually generated (the *book-*.html pipeline) is
+          sufficiently complex to require a 
+          <link href="#menu_xml_generation">section of its own</link>.</p>
+      </section>
+
+      <section id="tab_pipeline">
+        <title>Page tabs</title>
+        <p>Tab generation is quite tame compared to menus:</p>
+        <source xml:space="preserve"><![CDATA[
+     <map:match pattern="**tab-*.html">
+       <map:generate src="content/xdocs/tabs.xml" />
+       <map:transform type="]]>linkrewriter<![CDATA[" src="cocoon:/{1}linkmap-{2}.html"/>
+       <map:call resource="skinit">
+         <map:parameter name="type" value="tab2menu"/>
+         <map:parameter name="path" value="{1}{2}.html"/>
+       </map:call>
+     </map:match>
+           ]]></source>
+        <p>All the smarts are in the <code>tab2menu.xsl</code> stylesheet, which
+          needs to choose the correct tab based on the current path.  Currently,
+          a "longest matching path" algorithm is implemented.  See the
+          <code>tab2menu.xsl</code> stylesheet for details.</p>
+      </section>
+    </section>
+
+    <section id="menu_xml_generation">
+      <title>Menu XML generation</title>
+      <p>The "book" pipeline is defined in <code>sitemap.xmap</code>as:</p>
+      <source xml:space="preserve"><![CDATA[
+        <map:match pattern="**book-*.html">
+          <map:mount uri-prefix="" src="menu.xmap" check-reload="yes" />
+        </map:match>
+        ]]></source>
+      <p>Meaning that it is defined in the <code>menu.xmap</code> file.  In there we find
+        the real definition, which is quite complicated, because there are three
+        supported menu systems (see <link href="site:v0.70//linking">menus and
+          linking</link>).  We will not go through the sitemap itself
+        (menu.xmap), but will instead describe the logical steps involved:</p>
+      <ol>
+        <li>Take site.xml and expand hrefs so that they are all
+          root-relative.</li>
+        <li><p>Depending on the <code>forrest.menu-scheme</code> property, we
+            now apply one of the two algorithms for choosing a set of menu links
+            (described in <link href="site:v0.70//menu_generation">menu
+              generation</link>):</p>
+          <ul>
+            <li>
+              <p>
+                For "@tab" menu generation, we first ensure each site.xml node
+                has a tab attribute (inherited from a parent if necessary), and
+                then pass through nodes whose tab attribute matches that of the
+                "current" node.
+              </p>
+              <p>
+                For example, say our current page's path is
+                <code>community/howto/index.html</code>.  In
+                <code>site.xml</code> we look for the node with this
+                "<code>href</code>" and discover its "<code>tab</code>" attribute
+                value is "<code>howtos</code>".  We then prune the
+                <code>site.xml</code>-derived content to contain only nodes with
+                <code>tab="howtos"</code>.
+              </p>
+              <p>
+                All this is done with XSLT, so the sitemap snippet does not
+                reveal this complexity:
+              </p>
+              <source xml:space="preserve"><![CDATA[
+<map:transform src="resources/stylesheets/site2site-normalizetabs.xsl" />
+<map:transform src="resources/stylesheets/site2site-selectnode.xsl">
+  <map:parameter name="path" value="{1}{2}"/>
+</map:transform>
+                ]]></source>
+            </li>
+            <li>
+              <p>For "directory" menu generation, we simply use an
+                <code>XPathTransformer</code> to include only pages in the
+                current page's directory, or below:</p>
+              <source xml:space="preserve"><![CDATA[
+<map:transform type="xpath">
+  <map:parameter name="include" value="//*[@href='{1}']" />
+</map:transform>
+                ]]></source>
+              <p>
+                Here, the "<code>{1}</code>" is the directory part of the current
+                page.  So if our current page is
+                <code>community/howto/index.html</code> then "<code>{1}</code>" will
+                be <code>community/howto/</code> and the transformer will
+                include all nodes in that directory.
+              </p>
+            </li>
+          </ul>
+          <p>We now have a <code>site.xml</code> subset relevant to our current
+            page.</p>
+        </li>
+        <li>The "<code>href</code>" nodes in this are then made relative to the
+          current page.</li>
+        <li>The XML is then transformed into a legacy "<code>book.xml</code>"
+          format, for compatibility with existing stylesheets, and this XML
+          format is returned (hence the name of the matcher:
+          <code>**book-*.html</code>).</li>
+      </ol>
+    </section>
+
+    <section id="linkrewriting_impl">
+      <title>Link rewriting</title>
+      <p>In numerous places in <code>sitemap.xmap</code> you will see the
+        "linkrewriter" transformer in action.  For example:</p>
+      <source xml:space="preserve"><![CDATA[<map:transform type="linkrewriter" src="cocoon:/{1}linkmap-{2}.html"/>]]></source>
+      <p>This statement is Cocoon's linking system in action.  A full
+        description is provided in <link href="site:v0.70//linking">Menus and
+          Linking</link>.  Here we describe the implementation of linking.</p>
+      <section id="input_modules">
+        <title>Cocoon foundations: Input Modules</title>
+        <p>
+          The implementation of <code>site:</code> linking is heavily based on
+          Cocoon <link href="ext:cocoon/input-modules">Input Modules</link>, a
+          little-known but quite powerful aspect of Cocoon.  Input Modules are
+          generic Components which simply allow you to look up a value with a
+          key.  The value is generally dynamically generated, or obtained by
+          querying an underlying data source.
+        </p>
+        <p>
+          In particular, Cocoon contains an <code>XMLFileModule</code>, which
+          lets one look up the value of an XML node, by interpreting the key as
+          an XPath expression.  Cocoon also has a
+          <code>SimpleMappingMetaModule</code>, which allows the key to be
+          rewritten before it is used to look up a value.
+        </p>
+        <p>
+          The idea for putting these together to rewrite "<code>site:</code>"
+          links was described in <link href="ext:inputmoduletransformer">this
+            thread</link>. The idea is to write a Cocoon Transformer that
+          triggers on encountering &lt;link
+          href="<code>scheme:address</code>"&gt;, and interprets the
+          <code>scheme:address</code> internal URI as
+          <code>inputmodule:key</code>.  The transformer then uses the named
+          InputModule to look up the key value. The <code>scheme:address</code>
+          URI is then rewritten with the found value.  This transformer was
+          implemented as 
+          <link href="ext:linkrewritertransformer">LinkRewriterTransformer</link>,
+          currently distributed as a "block" in Cocoon 2.1
+        </p>
+      </section>
+
+      <section id="implement_rewriting">
+        <title>Implementing "<code>site:</code>" rewriting</title>
+        <p>
+          Using the above components, "<code>site:</code>" URI rewriting is
+          accomplished as follows.
+        </p>
+        <section id="cocoon_xconf">
+          <title>cocoon.xconf</title>
+          <p>First, we declare all the input modules we will be needing:</p>
+          <source xml:space="preserve"><![CDATA[
+<!-- For the site: scheme -->
+<component-instance
+  class="org.apache.cocoon.components.modules.input.XMLFileModule"
+  logger="core.modules.xml" name="linkmap"/>
+
+<!-- Links to URIs within the site -->
+<component-instance
+  class="org.apache.cocoon.components.modules.input.SimpleMappingMetaModule"
+  logger="core.modules.mapper" name="site"/>
+
+<!-- Links to external URIs, as distinct from 'site' URIs -->
+<component-instance
+  class="org.apache.cocoon.components.modules.input.SimpleMappingMetaModule"
+  logger="core.modules.mapper" name="ext"/>
+]]></source>
+          <ul>
+            <li><strong>linkmap</strong> will provide access to the contents of
+              site.xml; for example, <code>linkmap:/site/about/index/@href</code>
+              would return the value "index.html".</li>
+            <li><strong>site</strong> provides a "mask" over
+              <strong>linkmap</strong> such that <code>site:index</code> expands
+              to <code>linkmap:/site//index/@href</code>
+            </li>
+            <li><strong>ext</strong> provides another "mask" over
+              <strong>linkmap</strong>, such that <code>ext:ant</code> would
+              expand to <code>linkmap:/site/external-refs//ant/@href</code>
+            </li>
+          </ul>
+          <p>However at the moment, we have only declared the input modules.
+            They will be configured in <code>sitemap.xmap</code> as described in
+            the next section.</p>
+        </section>
+
+        <section id="sitemap">
+          <title>sitemap.xmap</title>
+          <p>
+            Now in the sitemap, we define the LinkRewriterTransformer, and
+            insert it into any pipelines which deal with user-editable XML
+            content:
+          </p>
+          <source xml:space="preserve"><![CDATA[
+....
+<!-- Rewrites links, e.g. transforming
+     href="site:index" to href="../index.html"
+-->
+<map:transformer name="linkrewriter"
+  logger="sitemap.transformer.linkrewriter"
+  src="org.apache.cocoon.transformation.LinkRewriterTransformer">
+  <link-attrs>href src</link-attrs>
+  <schemes>site ext</schemes>
+
+  <input-module name="site">
+    <input-module name="linkmap">
+      <file src="{src}" reloadable="false" />
+    </input-module>
+    <prefix>/site//</prefix>
+    <suffix>/@href</suffix>
+  </input-module>
+  <input-module name="ext">
+    <input-module name="linkmap">
+      <file src="{src}" reloadable="false" />
+    </input-module>
+    <prefix>/site/external-refs//</prefix>
+    <suffix>/@href</suffix>
+  </input-module>
+</map:transformer>
+....
+....
+<map:match pattern="**body-*.html">
+  <map:generate src="cocoon:/{1}{2}.xml"/>
+  <map:transform type="idgen"/>
+  <map:transform type="xinclude"/>
+  <map:transform type="linkrewriter" src="cocoon:/{1}linkmap-{2}.html"/>
+  ...
+</map:match>]]></source>
+          <p>As you can see, our three input modules are configured as part of
+            the LinkRewriterTransformer's configuration.</p>
+          <ul>
+            <li>
+              <p>Most deeply nested, we have:</p>
+              <source xml:space="preserve"><![CDATA[
+                <input-module name="linkmap">
+                  <file src="{src}" reloadable="false" />
+              </input-module>]]></source>
+              <p>The "<code>{src}</code>" text is expanded to the value of the
+                "<code>src</code>" attribute in the "<code>linkrewriter</code>"
+                instance, namely "<code>cocoon:/{1}linkmap-{2}.html</code>"
+                Thus the <code>linkmap</code> module reads dynamically
+                generated XML specific to the current request.</p>
+            </li>
+            <li>
+              <p>One level out, we configure the "<code>site</code>" and
+                "<code>ext</code>" input modules, to map onto our dynamically
+                configured "<code>linkmap</code>" module.</p>
+            </li>
+            <li>
+              <p>Then at the outermost level, we configure the
+                "<code>linkrewriter</code>" transformer.  First we tell it which
+                attributes to consider rewriting:</p>
+              <source xml:space="preserve"><![CDATA[
+                <link-attrs>href src</link-attrs>
+                <schemes>site ext</schemes>]]></source>
+              <p>So, "<code>href</code>" and "<code>src</code>" attributes starting
+                with "<code>site:</code>" or "<code>ext:</code>" are rewritten.</p>
+
+              <p>By nesting the "<code>site</code>" and "<code>ext</code>" input
+                modules in the "<code>linkrewriter</code>" configuration, we tell
+                "<code>linkrewriter</code>" to use these two input modules when
+                rewriting links.</p>
+            </li>
+          </ul>
+
+          <p>
+            The end result is that, for example, the source XML for the
+            <code>community/body-index.html</code> page has its links rewritten
+            by an XMLFileModule reading XML from
+            <code>cocoon:/community/linkmap-index.html</code>
+          </p>
+        </section>
+        <section id="dynamic_linkmap">
+          <title>Dynamically generating a linkmap</title>
+          <p>
+            Why do we need this "linkmap" pipeline generating dynamic XML from
+            site.xml, instead of just using site.xml directly?  The reasons are described
+            in <link href="ext:linkmaps">the linkmap RT</link>: we need to
+            concatenate @hrefs and add dot-dots to the paths, depending on which
+            directory the linkee is in.  This is done with the following
+            pipelines in <code>linkmap.xmap</code> ...
+          </p>
+          <source xml:space="preserve"><![CDATA[
+<!-- site.xml with @href's appended to be context-relative. -->
+<map:match pattern="abs-linkmap">
+  <map:generate src="content/xdocs/site.xml" />
+  <map:transform src="resources/stylesheets/absolutize-linkmap.xsl" />
+  <map:serialize type="xml" />
+</map:match>
+
+<!-- Linkmap for regular pages -->
+<map:match pattern="**linkmap-*">
+  <map:generate src="cocoon://abs-linkmap" />
+  <map:transform src="resources/stylesheets/relativize-linkmap.xsl">
+    <map:parameter name="path" value="{1}{2}" />
+    <map:parameter name="site-root" value="{conf:project-url}" />
+  </map:transform>
+  <map:serialize type="xml" />
+</map:match>
+            ]]></source>
+          <p>You can try these URIs out directly on a live Forrest to see what
+            is going on (for example, Forrest's own 
+            <link href="../abs-linkmap">abs-linkmap</link>).
+          </p>
+        </section>
+      </section>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_70/sitemap-ref.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_70/skin-package.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/skin-package.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/skin-package.source.xml (added)
+++ forrest/site/docs_0_70/skin-package.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  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.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document>
+  <header>
+    <title>Skin packaging, provision, and use</title>
+    <subtitle>Automated distributed skin packages</subtitle>
+  </header>
+
+  <body>
+    <section id="overview">
+      <title>Overview</title>
+      <p>
+Skins are standard zip archives with a *.zip extension.
+This enables them to be unpacked and installed automatically.
+      </p>
+
+      <p>
+To publish a skin:
+      </p>
+
+<source xml:space="preserve">
+1 - forrest package-skin
+The skin package will be made in the skin dir, next to the custom skin.
+2 - place the file in a directory on a web server
+3 - ask forrest-dev to add the url and the skin name to the list of skins
+</source>
+
+
+      <p>
+To use a custom skin with automatic download:
+      </p>
+
+<source xml:space="preserve">
+1 - set the skin property in forrest.properties to the name of the skin
+2 - forrest install-skin
+3 - forrest
+</source>
+
+      <p>
+Currently there are two test skins: "testskin" and "testskin2"
+      </p>
+
+      <p>
+To see the names of the remote skins:
+      </p>
+
+<source xml:space="preserve">forrest available-skins</source>
+    </section>
+
+    <section id="notes">
+      <title>Notes</title>
+      <p>
+The skin will get blown away by the next 'build clean' in forrest.
+But that is okay because it is so quick to go get another copy. Also it
+may be preferable to get a fresh copy. If the user wanted to keep
+the skin and perhaps enhance it, then they can copy it to their project.
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_70/skin-package.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_70/skins.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/skins.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/skins.source.xml (added)
+++ forrest/site/docs_0_70/skins.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,125 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  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.
+--><document>
+  <header>
+    <title>Default skins</title>
+  </header>
+  <body>
+    <section id="introduction">
+      <title>Introduction</title>
+      <p>
+        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.
+      </p>
+    </section>
+
+    <section id="names">
+      <title>Convention for choosing skin names</title>
+      <p>
+        The skin names are based on playing with the word "skin". See our
+        technique for
+        <link href="http://svn.apache.org/repos/asf/forrest/trunk/main/webapp/skins/new-skin-names.txt">choosing skin names</link>.
+        A name with "-dev" extension signifies that it is under development.
+        There is no concept of versions of default skins.
+        New skins have new names.
+      </p>
+    </section>
+
+    <section id="skins">
+      <title>Skin descriptions and examples</title>
+
+      <section id="pelt">
+        <title>pelt</title>
+        <p>
+          Uses CSS "div" and no HTML tables.
+        </p>
+        <p>Examples:
+          <link href="site:forrest">Apache Forrest</link> |
+          <link href="ext:lenya">Apache Lenya</link>
+        </p>
+      </section>
+
+      <section id="view">
+        <title>view/viewHelper</title>
+        <p>
+          This is the evolution of the "leather-dev" skin, to have contracts. 
+          It allows the user to provide their own implementations of contracts.
+          The view is controlled by a config file that is easy to understand.
+          It is still in development. Note: you need to have both plugins installed.
+        </p>
+
+        <p>Examples:
+          <link href="images/snapshot-view-viewHelper.png">snapshot</link>
+        </p>
+      </section>
+  
+      <section id="tigris">
+        <title>tigris</title>
+        <p>
+          This skin is based on version 1.1 of the 
+          <link href="http://style.tigris.org/">style.tigris.org</link> project.
+          (It deliberately contravenes our skin naming convention.)
+        </p>
+        <p>Examples:
+          <link href="http://www.core.gen.tr/">Core Computer Security Group</link>
+        </p>
+      </section>
+
+      <section id="plain-dev">
+        <title>plain-dev</title>
+        <p>
+          This is a very minimal skin to produce plain HTML documents.
+          Such capability might be useful to generate a collection of
+          documents for some off-line product's user help system.
+        </p>
+
+        <p>Examples:
+          <link href="images/snapshot-plain-dev.png">snapshot</link>
+        </p>
+      </section>
+    </section>
+
+    <section id="old">
+      <title>Old and deprecated skins</title>
+      <p>
+        The following skins are retained for a little while longer, but are
+        deprecated, so please move to one of the other skins.
+      </p>
+
+      <section id="forrest-site">
+        <title>forrest-site</title>
+        <p>
+          This is the old skin that we have been dragging around since early
+          days. Uses HTML tables.
+        </p>
+        <p>Examples:
+          <link href="ext:xml.apache.org">Apache XML</link>
+        </p>
+      </section>
+
+      <section id="krysalis-site">
+        <title>krysalis-site</title>
+        <p>
+          Uses HTML tables.
+        </p>
+
+        <p>Examples:
+        </p>
+      </section>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_70/skins.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_70/todo.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/todo.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/todo.source.xml (added)
+++ forrest/site/docs_0_70/todo.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><document><header><title>Todo List</title></header><body>
+    <section><title>high</title><ul><li><strong>[code]</strong> 
+        <!-- Please leave this action at the top -->
+        Please see our Jira
+        <link href="site:bugs">issue tracker</link> for tasks to be done.
+        Note that the Todo list below is old. We need someone to move those
+        tasks over to the issue tracker.
+       &#8594; open</li><li><strong>[code]</strong> 
+        Rework the menu generation system to make it more flexible.  See thread
+        <link href="http://marc.theaimsgroup.com/?w=2&amp;r=1&amp;s=Fixing+menus&amp;q=t">Fixing
+          menus</link>
+       &#8594; open</li><li><strong>[code]</strong> 
+        Define an 'object model' for Forrest sites, in the form of a Cocoon
+        pipeline, that defines
+        - The directory structure of a site
+        - Site metadata (what currently lives in skinconf.xml + gump.xml
+         stuff)
+        - Perhaps site.xml metadata for pages?
+        
+        This info can then be made public to the sitemap (via XMLFileModule
+        attributes) and the stylesheets (through
+        <code>document(cocoon:/...)</code> calls or inlined with source XML).
+         &#8594; open</li><li><strong>[code]</strong> 
+          Finalise the project-definition DTDs, like status.xml and module.xml;
+          try to come up with a common format with others on community.at.apache.org.
+         &#8594; NKB</li></ul></section>
+
+      <section><title>medium</title><ul><li><strong>[code]</strong> 
+          Finish the RSS feed for status.xml.
+          Aggregate status.xml and project.xml to have all needed project data.
+         &#8594; NKB</li><li><strong>[docs]</strong> 
+          Add stylesheets to render the enhanced status.xml file contents.
+         &#8594; open</li><li><strong>[code]</strong> 
+          In skinconf.xml, change 'disable-search' to 'enable-search'.
+         &#8594; JT</li><li><strong>[code]</strong> 
+          Enhance the initial forrest toolbar for Mozilla.
+          See email discussion <link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=102471820523388">draft forrest toolbar for Mozilla</link>.
+         &#8594; NKB</li><li><strong>[code]</strong> 
+          Fix things so docs can be edited in src/*, and have the changes appear
+          immediately in the webapp.  Involves creating/using an InputModule for
+          passing 'forrest.skin' and other properties to the sitemap, so we can
+          avoid the @skin@ hack, and a bit of forrest.build.xml hacking.  There
+          are some @tokens@ in a forrest-site CSS file that also need some sort
+          of in-place modification.  Perhaps a @token@-to-value Transformer could
+          be the same ${variable}-to-value Transformer mentioned in the RT [3].
+         &#8594; open</li><li><strong>[code]</strong> 
+          Act on <link href="http://marc.theaimsgroup.com/?t=104099660500001&amp;r=1&amp;w=2">'Entities in XML docs' RT</link>.
+          I can implement Stefano's
+          suggested solution quite easily, but is such limited functionality
+          worth the cost of introducing a proprietary ${variable} syntax? Maybe..
+          Best short-term alternative seems to be using the XNI XInclude
+          processor for pre-validation inclusion.
+         &#8594; open</li><li><strong>[docs]</strong> 
+          A lot of the info on the website is outdated.
+         &#8594; open</li><li><strong>[docs]</strong> 
+          Using metadata
+          from site.xml, it would at least be possible to indicate how old the
+          doc is, and perhaps indicate its relevance from a small controlled
+          vocabulary.
+         &#8594; open</li><li><strong>[design]</strong> 
+          Develop a mechanism for supporting legacy URLs.
+          See email discussion -
+          <link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=102390892524750">redirects with static sites</link>
+         &#8594; open</li><li><strong>[code]</strong> 
+          Fix up and integrate the Forrest Maven plugin.
+         &#8594; open</li></ul></section>
+
+      <section><title>low</title><ul><li><strong>[code]</strong> 
+          Ensure that PHP-like stuff can be embedded easily in Forrest files and
+          document it.
+         &#8594; open</li><li><strong>[code]</strong> 
+          Continue the development of the <link href="site:v0.70//libre-intro">Libre</link> facility - replacement for
+          */book.xml
+         &#8594; open</li><li><strong>[docs]</strong> 
+          Start a community doc where we list tools such as "code".
+         &#8594; open</li><li><strong>[code]</strong> 
+          Migrate to a decent schema language, primarily so that we can use
+          namespaces in XML docs, allowing things like XInclude, 
+          <link href="http://www.xml.com/pub/a/2002/10/30/rdf-friendly.html">in-line metadata</link>,
+          in-line SVG, Jelly snippets, or anything else users can make a
+          Transformer for.
+         &#8594; open</li><li><strong>[code]</strong> 
+          Streamline the process of adding support for new schemas.  Ideally we'd
+          have an auto-download system, e.g. 'forrest-update docbook' would fetch
+          and install the Docbook DTDs, create catalog entries, sitemap mods etc.
+         &#8594; open</li><li><strong>[code]</strong> 
+          Make a CSS Generator and a stylesheet to serialize it to text.
+         &#8594; NKB</li><li><strong>[docs]</strong> 
+          Add a document about authoring in XML for beginners..
+         &#8594; open</li></ul></section>    
+    </body></document>
\ No newline at end of file

Propchange: forrest/site/docs_0_70/todo.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_70/upgrading_07.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/upgrading_07.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/upgrading_07.source.xml (added)
+++ forrest/site/docs_0_70/upgrading_07.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,189 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  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.
+--><document> 
+  <header> 
+    <title>Upgrading to Apache Forrest 0.7</title> 
+  </header> 
+  <body> 
+    <section id="introduction">
+      <title>Introduction</title>
+      <p>
+      This page describes some changes to Apache Forrest that affect people who are
+      upgrading to the 0.7 version.
+      If you have other issues, then please discuss on either the
+      <link href="site:mail-lists/forrest-dev">dev</link> or
+      <link href="site:mail-lists/forrest-user">user</link>
+      mailing lists.
+      As more experience is gained, this document will be updated.  
+      </p>
+      <p>
+      (If you are upgrading from a version prior to 0.6 then you will need
+      to see the notes for the <link href="site:v0.60//upgrading_06">previous</link>
+      upgrade.)
+      </p>
+    </section>
+
+    <section id="new">
+      <title>New Features</title>
+      <p>
+        The following list shows some of the key new features
+        (for the full list of changes, see the
+        <link href="site:changes">change log</link>).
+      </p>
+      <ul>
+        <li>Plugin architecture</li>
+        <li>Java 1.4</li>
+      </ul>
+      <p>
+        As usual, do a "forrest seed site" in a new directory and compare the
+        forrest.properties and skinconf.xml with that of your project.
+      </p>
+    </section>
+
+    <section id="clean">
+      <title>Run a clean target after upgrade</title>
+      <p>
+        Do 'forrest clean-work' in each of your projects. This also removes
+        the old Cocoon disk cache.
+      </p>
+    </section>
+
+    <section id="home">
+      <title>New location of $FORREST_HOME</title>
+      <p>
+      $FORREST_HOME is now the top-level of the distribution.
+      Also make sure $PATH gets updated to use the new $FORREST_HOME/bin
+      </p>
+    </section>
+
+    <section id="jdk14">
+      <title>Java 1.4 (or newer) is required</title>
+      <p>Java 1.4 (or newer) is required, starting with this Forrest 0.7 version.
+        For further information, see <link href="site:v0.70//faq/requirements">FAQ</link>.
+      </p>
+    </section>
+
+    <section id="tips">
+      <title>General upgrade tips</title>
+      <p>
+      Synchronise your project's skinconf.xml and forrest.properties files.
+      </p>
+      <p>
+      Take advantage of the separation of concerns. In a new workspace,
+      create a fresh
+      '<code>forrest seed</code>' site, then tweak its forrest.properties
+      and skinconf.xml until it reflects your old site.
+      When it is ready, replace your project's skinconf.xml and
+      forrest.properties files.
+      Any remaining issues would concern other aspects of your configuration,
+      such as site.xml and your actual content.
+      </p>
+    </section>
+
+    <section id="plugin">
+      <title>Plugin architecture</title>
+      <p>
+        See
+        <link href="site:plugins/infrastructure">Plugin Infrastructure</link>
+        and
+        <link href="site:plugins/using">Extending Forrest with Plugins</link>
+        and for developing new plugins see
+        <link href="site:v0.70//howto/buildPlugin">How to Build a Plugin</link>.
+        See the list of
+        <link href="site:plugins/index">current plugins</link>
+        and their documentation.
+      </p>
+      <p>
+        Note that other experimental plugins can be found in the
+        "whiteboard/plugins" directory.
+      </p>
+    </section>
+
+    <section id="configure-plugin">
+      <title>Configure plugins</title>
+      <p>
+       Some functionality has been moved out of the forrest core and into
+       plugins. You will need to declare any plugins that are used by
+       your project, e.g. if you use projectInfo (status, changes, todo)
+       and PDF output, then declare the following in forrest.properties
+      </p>
+      <source xml:space="preserve">
+project.required.plugins=org.apache.forrest.plugin.input.projectInfo,org.apache.forrest.plugin.output.pdf
+      </source>
+    </section>
+
+    <section id="raw">
+      <title>Including raw un-processed content</title>
+      <p>The method for including "raw un-processed content" has changed.
+      </p>
+      <p>
+        In 0.6 version, the raw content was placed in the
+        src/documentation/content/ directory and potential sub-directories.
+        In the generated site, these links would automatically function.
+        Any linked file with .html extension was not processed and not
+        adorned with Forrest skin and navigation menus.
+      </p>
+      <p>It was also possible to place HTML content in the xdocs directory
+      where it would be copied across if it was linked from the main
+      content.</p>
+      <p>
+        In 0.7 version, any file that is linked to, needs to be placed in
+        the content/xdocs/ directory structure.
+        Any linked file with .html extension is now processed and is
+        adorned with Forrest skin and navigation menus.
+      </p>
+      <p>If you 
+        you wish to emulate the behaviour of 0.6 and earlier then you
+        must add the following to your project sitemap.</p>
+
+        <source xml:space="preserve">
+&lt;map:match pattern="**.html"&gt;
+ &lt;map:select type="exists"&gt;
+  &lt;map:when test="{project:content}{0}"&gt;
+    &lt;map:read src="{project:content}/{0}" mime-type="text/html"/&gt;
+    &lt;!--
+      Use this instead if you want JTidy to clean up your HTML
+      &lt;map:generate type="html" src="{project:content}/{0}" /&gt;
+      &lt;map:serialize type="html"/&gt;
+    --&gt;
+  &lt;/map:when&gt;
+  &lt;map:when test="{project:content.xdocs}{0}"&gt;
+    &lt;map:read src="{project:content.xdocs}/{0}" mime-type="text/html"/&gt;
+    &lt;!--
+      Use this instead if you want JTidy to clean up your HTML
+      &lt;map:generate type="html" src="{project:content.xdocs}/{0}" /&gt;
+      &lt;map:serialize type="html"/&gt;
+    --&gt;
+  &lt;/map:when&gt;
+ &lt;/map:select&gt;
+&lt;/map:match&gt;
+        </source>
+
+      <p>
+        If you need to include files that are not linked to,
+        then place them in the src/documentation/content/ directories
+        as with the 0.6 version. 
+      </p>
+    </section>
+
+    <section>
+      <title>To be continued...</title>
+      <p>...as more issues are discovered/remembered :)  Please send feedback
+      to the
+      <link href="site:mail-lists/forrest-dev">mailing list</link>.</p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_70/upgrading_07.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_70/validation.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/validation.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/validation.source.xml (added)
+++ forrest/site/docs_0_70/validation.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,359 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  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.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document>
+  <header>
+    <title>XML Validation</title>
+    <subtitle>DTDs, catalogs and whatnot</subtitle>
+  </header>
+
+  <body>
+    <section id="xml_validation">
+      <title>XML validation</title>
+      <p>
+        By default, Forrest will validate your XML before generating
+        HTML or a webapp from it, and fail if any XML files are not valid.
+        Validation can be performed manually by doing
+        '<code>forrest validate</code>' in the project root directory.
+      </p>
+      <p>
+        For an XML file to be valid, it <em>must</em> have a document type
+        declaration at the top, indicating its content type.  Hence by
+        default, any Forrest-processed XML file that lacks a DOCTYPE
+        declaration will cause the build to break.
+      </p>
+      <p>
+        Despite the strict default behavior, Forrest is quite flexible about
+        validation.  Validation can be switched off for certain sections of a
+        project.  In validated sections, it is possible for projects to specify
+        exactly what files they want (and don't want) validated.  Forrest
+        validation is controlled through a set of properties in
+        <code>forrest.properties</code>:
+      </p>
+      <source xml:space="preserve">
+##############
+# validation properties
+
+# This set of properties determine if validation is performed
+# Values are inherited unless overridden.
+# e.g. if forrest.validate=false then all others are false unless set to true.
+#forrest.validate=true
+#forrest.validate.xdocs=${forrest.validate}
+#forrest.validate.skinconf=${forrest.validate}
+#forrest.validate.sitemap=${forrest.validate}
+#forrest.validate.stylesheets=${forrest.validate}
+#forrest.validate.skins=${forrest.validate}
+#forrest.validate.skins.stylesheets=${forrest.validate.skins}
+
+# *.failonerror=(true|false) - stop when an XML file is invalid
+#forrest.validate.failonerror=true
+
+# *.excludes=(pattern) - comma-separated list of path patterns to not validate
+# e.g.
+#forrest.validate.xdocs.excludes=samples/subdir/**, samples/faq.xml
+#forrest.validate.xdocs.excludes=
+      </source>
+      <p>
+        For example, to avoid validating
+        <code>${project.xdocs-dir}</code>/slides.xml and everything inside the
+        <code>${project.xdocs-dir}/manual/</code> directory, add this to
+        <code>forrest.properties</code>:
+      </p>
+      <source xml:space="preserve">forrest.validate.xdocs.excludes=slides.xml, manual/**</source>
+      <note>
+        The <code>failonerror</code> properties only work for files validated
+        with Ant's &lt;xmlvalidate&gt; and not (yet) for those validated
+        with &lt;jing&gt;, where <code>failonerror</code> defaults to
+        <code>true</code>.
+      </note>
+    </section>
+
+    <section>
+      <title>Validating new XML types</title>
+      <p>
+        Forrest provides an <link href="ext:catalog_spec">OASIS Catalog</link>
+        [see <link href="ext:catalog_intro">tutorial</link>]
+        <code>forrest/main/webapp/resources/schema/catalog.xcat</code>
+        as a means of associating public identifiers
+        (e.g. <code>-//APACHE//DTD Documentation V1.1//EN</code> above) with DTDs.
+        If you <link href="site:v0.70//new_content_type">add a new content type</link>, you
+        should add the DTD to <code>${project.schema-dir}/dtd/</code> and add
+        an entry to the <code>${project.schema-dir}/catalog.xcat</code> file.  This
+        section describes the details of this process.
+      </p>
+
+      <section>
+        <title>Creating or extending a DTD</title>
+        <p>
+          The main Forrest DTDs are designed to be modular and extensible, so
+          it is fairly easy to create a new document type that is a superset
+          of one from Forrest.  This is what we'll demonstrate here, using our
+          earlier <link href="site:v0.70//new_content_type">download format</link>
+          as an example.  Our download format adds a group of new elements to
+          the standard 'documentv13' format.  Our new elements are described
+          by the following DTD:
+        </p>
+        <source xml:space="preserve">
+&lt;!ELEMENT release (downloads)&gt;
+&lt;!ATTLIST release
+version CDATA #REQUIRED
+date CDATA #REQUIRED&gt;
+
+&lt;!ELEMENT downloads (file*)&gt;
+
+&lt;!ELEMENT file EMPTY&gt;
+&lt;!ATTLIST file
+url CDATA #REQUIRED
+name CDATA #REQUIRED
+size CDATA #IMPLIED&gt;
+        </source>
+        <p>
+          The document-v13 entities are defined in a reusable 'module':
+          <code>forrest/main/webapp/resources/schema/dtd/document-v13.mod</code>
+          The
+          <code>forrest/main/webapp/resources/schema/dtd/document-v13.dtd</code>
+          file provides a full description and basic example of how to pull in
+          modules.  In our example, our DTD reuses modules
+          <code>common-charents-v10.mod</code> and
+          <code>document-v13.mod</code>.  Here is the full DTD, with
+          explanation to follow.
+        </p>
+        <source xml:space="preserve">
+&lt;!-- ===================================================================
+
+Download Doc format
+
+PURPOSE:
+This DTD provides simple extensions on the Apache DocumentV11 format to link
+to a set of downloadable files.
+
+TYPICAL INVOCATION:
+
+&lt;!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
+"download-v10.dtd"&gt;
+
+COPYRIGHT:
+  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.
+
+==================================================================== --&gt;
+
+
+&lt;!-- =============================================================== --&gt;
+&lt;!-- Include the Common ISO Character Entity Sets --&gt;
+&lt;!-- =============================================================== --&gt;
+
+&lt;!ENTITY % common-charents PUBLIC
+"-//APACHE//ENTITIES Common Character Entity Sets V1.0//EN"
+"common-charents-v10.mod"&gt;
+%common-charents;
+
+&lt;!-- =============================================================== --&gt;
+&lt;!-- Document --&gt;
+&lt;!-- =============================================================== --&gt;
+
+&lt;!ENTITY % document PUBLIC "-//APACHE//ENTITIES Documentation V1.3//EN"
+"document-v13.mod"&gt;
+
+&lt;!-- Override this entity so that 'release' is allowed below 'section' --&gt;
+&lt;!ENTITY % local.sections "|release"&gt;
+
+%document;
+
+&lt;!ELEMENT release (downloads)&gt;
+&lt;!ATTLIST release
+version CDATA #REQUIRED
+date CDATA #REQUIRED&gt;
+
+&lt;!ELEMENT downloads (file*)&gt;
+
+&lt;!ELEMENT file EMPTY&gt;
+&lt;!ATTLIST file
+url CDATA #REQUIRED
+name CDATA #REQUIRED
+size CDATA #IMPLIED&gt;
+
+&lt;!-- =============================================================== --&gt;
+&lt;!-- End of DTD --&gt;
+&lt;!-- =============================================================== --&gt;
+        </source>
+        <p>This custom DTD should be placed in your project resources
+        directory at <code>src/documentation/resources/schema/dtd/</code></p>
+        <p>
+          The &lt;!ENTITY % ... &gt; blocks are so-called 
+          <link href="http://www.xml.com/axml/target.html#dt-PERef">parameter
+            entities</link>.  They are like macros, whose content will be
+          inserted when a parameter-entity reference, like
+          <code>%common-charents;</code> or <code>%document;</code> is
+          inserted.
+        </p>
+        <p>
+          In our DTD, we first pull in the 'common-charents' entity, which
+          defines character symbol sets.  We then define the 'document'
+          entity.  However, before the <code>%document;</code> PE reference, we
+          first override the 'local.section' entity.  This is a hook into
+          document-v13.mod.  By setting its value to '|release', we declare
+          that our &lt;release&gt; element is to be allowed wherever "local
+          sections" are used.  There are five or so such hooks for different
+          areas of the document; see document-v13.dtd for more details.  We then
+          import the %document; contents, and declare the rest of our DTD
+          elements.
+        </p>
+        <p>
+          We now have a DTD for the 'download' document type. 
+        </p>
+        <note>
+        <link href="http://www.oasis-open.org/docbook/documentation/reference/html/ch05.html">Chapter
+            5: Customizing DocBook</link> of Norman Walsh's "DocBook: The
+          Definitive Guide" gives a complete overview of the process of
+          customizing a DTD.
+        </note>
+      </section>
+
+      <section id="catalog">
+        <title>Associating DTDs with document types</title>
+
+        <p>
+          Recall that our DOCTYPE declaration for our download document type
+          is:
+        </p>
+        <source xml:space="preserve">&lt;!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
+          "download-v10.dtd"&gt;
+        </source>
+        <p>
+          We only care about the quoted section after <code>PUBLIC</code>, called
+          the "public identifier", which globally identifies our document type.
+          We cannot rely on the subsequent "system identifier" part
+          ("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
+          on a mapping from the public ID to a stable DTD location, via a
+          Catalog file.</p>
+        <note>
+          See <link href="ext:catalog_intro">this article</link> for a good
+          introduction to catalogs and the Cocoon documentation
+          <link href="ext:cocoon/catalogs">Entity resolution with catalogs</link>.
+        </note>
+        <p>
+          Forrest provides a standard catalog file at
+          <code>forrest/main/webapp/resources/schema/catalog.xcat</code>
+          for the document
+          types that Forrest provides.  Projects can augment this with their
+          own catalog file located in
+          <code>${project.schema-dir}/catalog.xcat</code> to use it you must
+	    specify either the path (full or relative) to your 
+	    <code>catalog.xcat</code> in the <code>CatalogManager.properties</code>
+	    file. If you provide a relative path you must set the property 
+	    <code>relative-catalogs</code> to "yes".
+	  </p>
+        <p>
+          When Cocoon starts, it reads the <code>CatalogManager.properties</code> file from your
+          <code>project.classes-dir</code>. This is usually src/documentation/classes/
+          but you can change this in <code>forrest.properties</code>. When you seed 
+          a new site using <code>forrest seed-site</code> a sample catalog file
+          is placed in the site structure, you can use this as a template for your
+          own files.
+        </p>
+        <p>
+          Forrest uses the XML Catalog syntax by default, although the older
+          plain-text
+          format can also be used.  Here is what the XML Catalog format looks
+          like:
+        </p>
+        <source xml:space="preserve"><![CDATA[<?xml version="1.0"?>
+<!-- OASIS XML Catalog for Forrest -->
+<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
+  <public publicId="-//Acme//DTD Download Documentation V1.0//EN"
+    uri="dtd/download-v10.dtd"/>
+</catalog>]]></source>
+        <p>
+          The format is described in <link href="ext:catalog_spec">the
+          spec</link>, and is fairly simple and very powerful.
+          The "<code>public</code>" elements map
+          a public identifier to a DTD (relative to the catalog file).
+        </p>
+        <p>
+          We now have a custom DTD and a catalog mapping which lets both
+          Forrest and Cocoon
+          locate the DTD.  Now if we were to run <code>'forrest validate'</code>
+          our download file would validate along with all the others.  If
+          something goes wrong, try running <code>'forrest -v validate'</code> to
+          see the error in more detail. Remember to raise the "verbosity"
+          level in <code>cocoon.xconf</code> if you suspect problems
+          with your catalog.
+        </p>
+      </section>
+    </section>
+
+    <section id="entities">
+      <title>Referring to entities</title>
+      <p>
+        Look at the source of this document
+        (<code>xdocs/docs/validation.xml</code>) and see how the entity set
+        <code>"Numeric and Special Graphic"</code> is declared in the
+        document type declaration.
+      </p>
+      <table>
+        <tr>
+          <td colspan="1" rowspan="1">ISOnum.pen</td> 
+          <td colspan="1" rowspan="1">&amp;half;</td> 
+          <td colspan="1" rowspan="1">½</td> 
+        </tr>
+      </table>
+    </section>
+
+    <section>
+      <title>Validating in an XML editor</title>
+      <p>
+        If you have an XML editor that understands SGML or XML catalogs, let
+        it know where the Forrest catalog file is, and you will be able to
+        validate any Forrest XML file, regardless of location, as you edit
+        your files. See the 
+        <link href="site:v0.70//catalog">configuration notes</link> your favourite
+        editor.
+      </p>
+    </section>
+
+    <section id="relaxng">
+      <title>Validation using RELAX NG</title>
+      <p>
+        Other validation is also conducted during build-time using RELAX NG.
+        This validates all of the important configuration files, both in
+        Forrest itself and in your project. At the moment it processes all
+        skinconf.xml files, all sitemap.xmap files, and all XSLT stylesheets.
+      </p>
+      <p>
+        The RNG grammars to do this are located in the
+        <code>main/webapp/resources/schema/relaxng</code> directory.
+        If you want to
+        know more about this, and perhaps extend it for your own use, then
+        see <code>main/webapp/resources/schema/relaxng/README.txt</code>
+        and the Ant targets in the various build.xml files.
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_70/validation.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_70/views.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/views.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/views.source.xml (added)
+++ forrest/site/docs_0_70/views.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  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.
+--><document>
+  <header>
+    <title>forrest:views concept (Draft -feature planed for 0.8)</title>
+  </header>
+  <body>
+    <warning>This document is heavily under development</warning>
+    <section id="introduction">
+      <title>Introduction</title>
+      <p>
+        Like stated in the <link href="site:v0.70//documentation/skins">Skin documentation 
+        file</link> the aim of the forrest skins is to provide
+        many capabilities so that extra skins are not needed. Our experience showed that many forrest user 
+        had to create a new skin because the default skin did not offer the feature their wanted to use. 
+        That leaded us to develop a new concept of creating skins that would be easily extensible by a user.
+      </p>
+      <p>
+        The aim of the upcoming "forrest:views" skinning concept is to provide a flexible framework for creating
+        site and page specific layout in different formats.
+      </p>
+
+    </section>
+
+    <section id="background">
+      <title>Background</title>
+      <p>
+        The problem with the forrest skins so far has been that "only" the design changed (html-skeleton),
+        but still we had to write a completely new skin and implement all functionality.
+        Another problem was that the functionality was not easy extensible by a user.
+        Then we decided to support the a standard regarding naming conventions for css elements.
+        This standard has been developed on the <link href="http://www.oscom.org/events/oscom4/proposals/skins">
+        OSCOM website</link>, where you can find some more background informations.
+      </p>
+    </section>
+
+    <section id="nc-definition">
+      <title>Definition of naming conventions</title>
+      <p>
+        "A naming convention is an attempt to systematize names in a field so 
+        they unambiguously convey similar information in a similar manner." 
+        <link href="http://www.wordiq.com/definition/Naming_convention">wordiq-definition</link> 
+      </p>
+    </section>
+    <section id="leather">
+      <title>leather-dev</title>
+      <p>
+        That leaded to the development of the "leather-dev" skin which established a semantic container approach for div elements. 
+        The problems with leather-dev was pointed out on the mail 
+          <link href="http://marc.theaimsgroup.com/?l=forrest-dev m=111049344517653 w=2">status on leather-dev?</link> 
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_70/views.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message