forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r376128 [12/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/linking.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/linking.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/linking.source.xml (added)
+++ forrest/site/docs_0_70/linking.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,602 @@
+<?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>Menus and Linking</title>
+  </header>
+
+  <body>
+    <section id="intro">
+      <title>Introduction</title>
+      <p>
+        This document describes Forrest's internal URI space; how it is managed
+        with the "site.xml" configuration file, how menus are generated,
+        and how various link schemes (site: and ext:) operate.
+        An overview of the implementation is also provided.
+      </p>
+    </section>
+
+    <section id="site">
+      <title>site.xml</title>
+      <p>
+        The "site.xml" configuration file is what we would call a "site map"
+        if Cocoon hadn't already claimed that term. 
+        The "site.xml" is a loosely structured XML file, acting as a map of the
+        site's contents.  It provides a unique identifier (an XPath address)
+        for "nodes" of information in the website.  A "node" of site information
+        can be:
+      </p>
+      <ul>
+        <li>A category of information, like "the user guide". A category may
+          correspond to a directory, but that is not required.</li>
+        <li>A specific page, e.g. "the FAQ page"</li>
+        <li>A specific section in a page, e.g. the "general" section of the FAQ
+          page (identified by <code>id="general"</code> attribute)</li>
+      </ul>
+      <p>
+        In addition to providing fine-grained addressing of site info, the site.xml
+        allows <em>metadata</em> to be associated with each node, using
+        attributes or child elements.  Most commonly, a <code>label</code>
+        attribute is used to provide a text description of the node.
+      </p>
+      <p>
+        There are currently two applications of site.xml
+      </p>
+      <dl>
+        <dt><link href="#menu_generation">Menu generation</link></dt>
+        <dd>site.xml is used to generate the menus for the HTML website.</dd>
+        <dt><link href="#indirect-linking">Indirect linking</link></dt>
+        <dd>site.xml provides a basic aliasing mechanism for linking, e.g. one
+          can write &lt;link href="site:v0.70//changes"&gt; from anywhere in the site, and
+          link to the "changes" information node (translated to changes.html).
+          More on this below.</dd>
+      </dl>
+      <p>
+        Here is a sample site.xml ...
+      </p>
+      <source xml:space="preserve"><![CDATA[
+<?xml version="1.0"?>
+<site label="Forrest" href="" tab="home"
+  xmlns="http://apache.org/forrest/linkmap/1.0">
+
+  <about label="About">
+    <index label="Index" href="index.html"/>
+    <license label="License" href="license.html"/>
+    <your-project label="Using Forrest" href="your-project.html">
+      <new_content_type href="#adding_new_content_type"/>
+    </your-project>
+    <linking label="Linking" href="linking.html"/>
+    <changes label="Changes" href="changes.html"/>
+    <todo label="Todo" href="todo.html"/>
+    <live-sites label="Live sites" href="live-sites.html"/>
+  </about>
+
+  <community label="Community" href="community/" tab="community">
+    <index label="About" href="index.html"/>
+    <howto-samples label="How-To Samples" href="howto/" tab="howto">
+      <overview label="Overview" href="index.html"/>
+      <single-page label="Single Page" href="v10/howto-v10.html"/>
+      <multi-page label="Multi-Page" href="multi/">
+        <intro label="Intro" href="howto-multi.html"/>
+        <step1 label="Step 1" href="step1.html"/>
+        <step2 label="Step 2" href="step2.html"/>
+      </multi-page>
+    </howto-samples>
+  </community>
+
+  <references label="References">
+    <gump label="Apache Gump" href="http://gump.apache.org/"/>
+    <cocoon label="Apache Cocoon" href="http://cocoon.apache.org/"/>
+  </references>
+
+  <external-refs>
+    <mail-archive href="http://marc.theaimsgroup.com"/>
+    <xml.apache.org href="http://xml.apache.org/">
+      <commons href="commons/">
+        <resolver href="components/resolver/"/>
+      </commons>
+      <fop href="fop/"/>
+      <batik href="batik/"/>
+    </xml.apache.org>
+
+    <mail>
+      <semantic-linking href="http://marc.theaimsgroup.com/?l=forrest-dev
+        &amp;m=103097808318773&amp;w=2"/>
+    </mail>
+    <cool-uris href="www.w3.org/Provider/Style/URI.html"/>
+    <uri-rfc href="http://zvon.org/tmRFC/RFC2396/Output/index.html"/>
+
+  </external-refs>
+</site>
+        ]]></source>
+      <p>As you can see, things are quite free-form. The rules are as follows:</p>
+      <ul>
+        <li>The root element must be "site", and normal content should be in the
+          namespace <code>http://apache.org/forrest/linkmap/1.0</code> (Feel
+          free to mix in your own content (RDF, dublin core, etc) under new
+          namespaces)</li>
+        <li>Element names are used as identifiers.  The "<code>foo</code>" in
+          "<code>site:foo</code>" must therefore be a valid NMTOKEN.</li>
+        <li>Elements with <code>href</code> attributes can be used as identifiers
+          in "<code>site:</code>" URIs</li>
+        <li>Relative href attribute contents are "accumulated" by prepending hrefs
+          from ancestor nodes</li>
+        <li>Elements without <code>label</code> attributes (and their children)
+          are not displayed in the menu.</li>
+        <li>Elements below <code>external-refs</code> are mapped to the
+          "<code>ext:</code>" scheme.  So "<code>ext:commons/resolver/</code>" becomes
+          "<code>http://xml.apache.org/commons/resolver/</code>"</li>
+      </ul>
+      <p>
+        See another <link href="site:v0.70//faq/site-xml">explained example</link>.
+      </p>
+    </section>
+
+    <section id="menu_generation">
+      <title>Generating Menus</title>
+      <p>
+        Two files are used to define a site's tabs and menu (site.xml and
+        <code>tabs.xml</code>).  Both files are located in
+        <code>src/documentation/content/xdocs/</code></p>
+      <p>Assume that our <code>tabs.xml</code> looks like this:</p>
+      <source xml:space="preserve"><![CDATA[
+<tabs ...>
+    <tab id="home" label="Home" dir=""/>
+    <tab id="community" label="Community" dir="community" indexfile="mailLists.html"/>
+    <tab id="howto" label="How-Tos" dir="community/howto"/>
+</tabs>
+      ]]></source>
+      <p>Using the "site.xml" listed above, we would get these menus:</p>
+      <p>
+        <img src="images/menu.png" alt="Menu generated from site.xml"/>   
+        <img src="images/menu2.png" alt="Community menu generated from site.xml"/>   
+        <img src="images/menu3.png" alt="Howto menu generated from site.xml"/>
+      </p>
+      
+      <p>When using the "<code>dir</code>" attribute as above the value of the
+      "<code>indexfile</code>" parameter is appended to the value of the 
+      "<code>dir</code>" attribute (together with a preceding '/'). For example,
+      the link for the community tab above is 
+      <code>community/mailLists.html</code>. Note that "<code>indexfile</code>"
+      defaults to "<code>index.html</code>" if no value is supplied. Therefore the
+      link for the howto tab is <code>community/howto/index.html</code></p>
+      
+      <section id="tabs-external">
+        <title>Tabs for External Resources</title>
+        <p>A tab can refer to an external resource by using the 
+        "<code>href</code>" attribute instead of the "<code>dir</code>" attribute.
+        The value of "<code>href</code>" should be the URI of the resource you wish 
+        to link to. For example:</p>
+      
+        <source xml:space="preserve"><![CDATA[
+<tab id="apache" label="XML Apache" href="http://xml.apache.org/"/>
+        ]]></source>
+        
+        <p>Unlike the "<code>dir</code>" attribute, the value of "<code>href</code>"
+        is left unmodified by Forrest unless it is root-relative and obviously 
+        specifies a directory (ends in '/'). In which case /index.html will be 
+        added.</p>
+      </section>
+
+      <section id="selecting-entries">
+        <title>Selecting menu entries</title>
+        <p>Forrest decides which menu entries to display, by examining the
+          "<code>tab</code>" attributes in the site.xml file. The children of 
+          all site.xml entries with a
+          "<code>tab</code>" which is equal to that of the current page, are
+          added to the menu, whilst the element itself forms the root of that
+          part of the menu (see the "<code>community</code>" element in the 
+          example below). Child elements that have a different 
+          "<code>tab</code>" attribute value will appear in the menu for their
+          parents, and will also form the root of a new menu for a tab with 
+          the appropriate name (see the "<code>howto-samples</code>" element
+          below).</p>
+        <p>Consider our site.xml example:</p>
+          <source xml:space="preserve">
+&lt;site label="Forrest" href="" <strong>tab="home"</strong>
+  xmlns="http://apache.org/forrest/linkmap/1.0"&gt;
+
+  &lt;about label="About"&gt;
+    &lt;index label="Index" href="index.html"/&gt;
+    &lt;license label="License" href="license.html"/&gt;
+    &lt;your-project label="Using Forrest" href="your-project.html"&gt;
+      &lt;new_content_type href="#adding_new_content_type"/&gt;
+    &lt;/your-project&gt;
+    &lt;linking label="Linking" href="linking.html"/&gt;
+    ....
+  &lt;/about&gt;
+
+  &lt;community label="Community" href="community/" <strong>tab="community"</strong>&gt;
+    &lt;index label="About" href="index.html"/&gt;
+    &lt;howto-samples label="How-To Samples" href="howto/" <strong>tab="howto"</strong>&gt;
+      &lt;overview label="Overview" href="index.html"/&gt;
+      &lt;single-page label="Single Page" href="v10/howto-v10.html"/&gt;
+      &lt;multi label="Multi-Page" href="multi/"&gt;
+        &lt;intro label="Intro" href="howto-multi.html"/&gt;
+        &lt;step1 label="Step 1" href="step1.html"/&gt;
+      ...</source>
+        <p>
+          Every site.xml node can potentially have a "<code>tab</code>" attribute.  If
+          unspecified, nodes inherit the "<code>tab</code>" of their parent.  Thus
+          everything in the <strong>&lt;about&gt;</strong> section has an implicit
+          <code>tab="home" </code>attribute.</p>
+        <note>You can see this by viewing your site's 
+        <link href="../abs-menulinks">abs-menulinks</link> pipeline in a
+          browser.</note>
+        <p>Say that the user is viewing the <code>linking.html</code>
+          page.  The <strong>&lt;linking&gt;</strong> node has an implicit tab
+          value of "<code>home</code>".  Forrest will select <em>all nodes with
+            tab="home"</em> and put them in the menu.
+        </p>
+      </section>
+
+      <section id="other-menu-selection">
+        <title>Alternative menu selection mechanisms.</title>
+        <p>
+          The "<code>tab</code>" attribute-based scheme for selecting a menu's
+          entries is not the only one, although it is the most flexible.  Here
+          we describe a few alternatives.
+        </p>
+        <section id="dir-menu-selection">
+          <title>Directory-based selection</title>
+          <p>In this scheme, each tab corresponds to a directory within the
+            site.  All content below that directory is included in the menu.</p>
+          <p>
+            <img src="images/dir-menu.png" alt="Directory-based site menu"/>   
+            <img src="images/dir-menu2.png" alt="community/ directory menu"/>   
+            <img src="images/dir-menu3.png" alt="community/howto/ directory menu"/>
+          </p>
+          <p>
+            To use this scheme:
+          </p>
+          <ul>
+            <li>Edit <code>forrest.properties</code> and set
+              <code>project.menu-scheme=directories</code></li>
+            <li>Remove the "<code>id</code>" attributes from <code>tabs.xml</code>
+              entries.</li>
+          </ul>
+        </section>
+        <section id="book-menu-selection">
+          <title>Specifying menus with book.xml</title>
+          <p>
+            Historically, menus in Forrest have been generated from a
+            <code>book.xml</code> file, one per directory.  This mechanism is
+            still available, and if a <code>book.xml</code> is found, it will be
+            used in preference to the menu generated by the site.xml file. The <code>book.xml</code>
+            files can use "<code>site:</code>" URIs to ease the maintenance burden
+            that led to obsolescence of book.xml files.  In general, however, we
+            recommend that users avoid <code>book.xml</code> files.
+          </p>
+        </section>
+      </section>
+
+      <section id="tab-selection">
+        <title>Selecting the current tab</title>
+        <p>
+          The tab selection algorithm is quite simple: the tab with the
+          "<code>id</code>" which matches that of the current site.xml
+          node is "selected". However the interaction of tabs.xml and site.xml
+          while powerful, can be complex to establish.
+        </p>
+      </section>
+
+      <section id="tab-site">
+        <title>Configuring the interaction between tabs.xml and site.xml</title>
+        <p>
+          This is a collection of tips to assist with getting your menus and tabs
+          to properly display.
+        </p>
+        <ul>
+          <li>
+            View your site's 
+            <link href="../abs-menulinks">abs-menulinks</link> pipeline in a
+            browser. This is part of the internal Cocoon machinery, but like
+            other sitemap resources, it is useful to view them to assist with
+            debugging.
+          </li>
+          <li>
+            The Forrest website also accompanies your software release
+            in the <code>site-author</code> directory, so
+            inspect its tabs.xml and site.xml to see how it is done. Also see the
+            'forrest seed site' example. It is not as complex as the Forrest website.
+          </li>
+          <li>
+            When you are fiddling with your attributes, change one thing at a time
+            and document what you have changed.</li>
+          <li>
+            The value of the tab @id attribute cannot begin with a digit.
+            Likewise, element names in tabs.xml and site.xml cannot begin with a digit.
+          </li>
+          <li>
+            Add label attributes to site.xml elements to make the menus show.
+            With nested elements in site.xml if the outer element does not have a label
+            attribute then the inner elements will not be displayed.
+          </li>
+          <li>
+            To cause tabs and menu items to be highlighted, there need to be
+            corresponding elements in site.xml that have href attributes which match
+            the relevant path.
+          </li>
+          <li>
+            When the tab points to a directory, then to make the tab highlighted
+            when selected, you need an element which matches index.html within the
+            group of elements that define the menus for this tab in the site.xml
+            file. That element can be without a label attribute, so that it doesn't
+            display as a menu item. However doing that causes that tab's menus
+            to be collapsed.
+          </li>
+          <li>
+            Q: The tab link in my site assumes that 'index.html'
+            is present in the linked-to directory. How do I fix this?
+            A: In tabs.xml use @href instead of @dir attribute and omit the trailing '/'.
+            Which file to serve is then a concern of the sitemap.
+            See more at the <link href="site:v0.70//faq/tab-index">FAQ</link>.
+          </li>
+        </ul>
+      </section>
+
+    </section>
+
+    <section id="toc-generation">
+      <title>Table of Contents Generation</title>
+      <p>Each page can have an automatically generated table of contents. This
+      is created from the titles of each section in your xdoc. By default only
+      sections up to two levels deep are included and the table of contents is
+      displayed at the top of the page. However, you can configure this
+      behaviour in <code>src/documentation/skinconf.xml</code> using the 
+      "<code>toc</code>" element.</p>
+      
+      <source xml:space="preserve"><![CDATA[
+<toc level="2" location="page"/>
+      ]]></source>
+      
+      <ul>
+        <li><strong><code>level</code></strong> - is the depth to which you
+        want your table of contents to go. Setting it to "3" will therefore 
+        include sections nested to 3 levels. Setting this to "0" will result in
+        no table of contents being generated.</li>
+        <li><strong><code>location</code></strong> - indicates where you
+        want the table of contents to be rendered. It can be set to one of
+        three values:
+          <ul>
+            <li><code>page</code> - the table of contents will be rendered
+            at the top of the body of your page</li>
+            <li><code>menu</code> - the table of contents will be rendered
+            in the menu to the left of the body of the page</li>
+            <li><code>menu, page</code> - table of contents will be rendered
+            in both the page and the menu positions</li>
+          </ul>
+        </li>
+      </ul>
+    </section>
+    
+    <section id="linking">
+      <title>Linking systems</title>
+
+      <section id="direct-linking">
+        <title>Direct linking</title>
+        <p>
+          In earlier versions of Forrest (and in similar systems), there has
+          been only one URI space: that of the generated site.  If index.xml wants to
+          link to todo.xml then index.xml would use
+        </p>
+        <source xml:space="preserve">
+          &lt;a href="todo.html"&gt;to-do list&lt;a&gt;
+        </source>
+        <p>
+          The theoretical problem with this is that the content producer should
+          not know or care how Forrest is going to render the source.  A URI
+          should only <em>identify</em> a resource, not specify it's type
+          [<link href="ext:semantic-linking">mail ref</link>] and
+          [<link href="ext:cool-uris">cool URIs</link>]. In fact, as Forrest
+          typically renders to multiple output formats (HTML and PDF), links in
+          one of them (here, the PDF) are likely to break.
+        </p>
+      </section>
+
+      <section id="indirect-linking">
+        <title>Indirect linking</title>
+        <p>
+          Forrest's solution is simple: instead of &lt;a href="todo.html"&gt;,
+          write &lt;a href="site:v0.70//todo"&gt; where:
+        </p>
+        <dl>
+          <dt>site</dt>
+          <dd>is a URI "scheme"; a namespace that restricts
+            the syntax and semantics of the rest of the URI
+            [<link href="ext:uri-rfc">rfc2396</link>].  The semantics of "site" are
+            "this identifier locates something in the site's XML sources".</dd>
+          <dt>todo</dt>
+          <dd>identifies the content in <code>todo.xml</code> by reference to a
+            "node" of content declared in site.xml</dd>
+        </dl>
+        <p>
+          We call this indirect, or <em>semantic</em> linking because instead of
+          linking to a physical representation (todo.html), we've linked to the
+          "idea" of "the todo file".  It doesn't matter where it physically lives;
+          that will be sorted out by Forrest.
+        </p>
+
+        <section id="resolve-site-uris">
+          <title>Resolving site: URIs</title>
+
+          <p>
+            So how does "<code>site:v0.70//todo</code>" get resolved?  A full answer
+            is provided in the <link href="#implementation">implementation</link>
+            section.  Essentially, the "<code>todo</code>" part has
+            "<code>/site//</code>" prepended, and "<code>/@href</code>" appended, to
+            form the string "<code>/site//todo/@href</code>".  This is
+            then used as an XPath expression in site.xml to identify the string
+            replacement, in this case "<code>todo.html</code>"
+          </p>
+          <p>
+            Thus by modifying the XPath prefix and suffix, almost any XML
+            format can be accommodated.
+          </p>
+          <note>
+            Actually, the XPath is applied to XML generated dynamically from
+            site.xml.  The generated XML has each "@href" fully expanded ("absolutized")
+            and dot-dots (..) added as needed ("relativized").
+          </note>
+
+          <p>
+            Notice that the "//" allows us any degree of specificity when linking.
+            In the sample site.xml above, both "<code>site:v0.70//new_content_type</code>" and
+            "<code>site:about/your-project/new_content_type</code>" identify the
+            same node.  It is up to you to decide how specific to make links.  One
+            nice benefit of link "ambiguity" is that site.xml can be reorganized
+            without breaking links.  For example, "new_content_type" currently
+            identifies a node in "your-project".  By leaving that fact unspecified
+            in "<code>site:new_content_type</code>" we are free to make
+            "new_content_type" its own XML file, or a node in another file, in
+            another category.
+          </p>
+        </section>
+
+        <section id="resolve-ext-uris">
+          <title>ext: URIs: linking to external URLs</title>
+          <p>
+            The "<code>ext:</code>" scheme was created partly to demonstrate the
+            ease with which new schemes can be defined, and partly for practical
+            use. The "<code>ext:</code>" URIs identify nodes in site.xml below the
+            &lt;external-refs&gt; node.  By convention, nodes here link to URLs
+            outside the website, and are not listed in the menu generated from
+            the site.xml file.
+          </p>
+          <p>Here is a site.xml snippet illustrating "<code>external-refs</code>":</p>
+          <source xml:space="preserve"><![CDATA[
+<site>
+  ...
+  <external-refs>
+    <mail-archive href="http://marc.theaimsgroup.com"/>
+    <xml.apache.org href="http://xml.apache.org/">
+      <commons href="commons/">
+        <resolver href="components/resolver/"/>
+      </commons>
+    </xml.apache.org>
+    ...
+  </external-refs>
+</site>]]></source>
+          <p>
+            As an example, &lt;a href="ext:commons/resolver"&gt;
+            generates the link
+            <link href="ext:commons/resolver">http://xml.apache.org/components/resolver/</link>
+          </p>
+          <p>
+            The general rules of site.xml and "<code>site:</code>" linking apply.
+            Specifically, the "@href" aggregation makes defining large numbers of
+            related URLs easy.
+          </p>
+        </section>
+
+        <section id="source-uris">
+          <title>Theory: source URIs</title>
+          <p>
+            The "<code>site:</code>" URIs like "<code>site:v0.70//todo</code>" are examples of
+            "<em>source</em>" URIs, in contrast to the more usual
+            <code>foo.html</code> style URIs, which we here call
+            "<em>destination</em>" URIs.  This introduces an important concept: that
+            the "<em>source</em>" URI space exists and is independent of that of the
+            generated site.  Furthermore, URIs (i.e. links) are first-class objects,
+            on par with XML documents, in that just as XML content is transformed,
+            so are the links.  Within the source URI space, we can have all sorts of
+            interesting schemes (person: mail: google: java: etc). These will
+            all be translated into plain old "<code>http:</code>" or relative URIs
+            in the destination URI space, just like exotic XML source formats are
+            translated into plain old HTML in the output.
+          </p>
+        </section>
+
+
+        <section id="future-schemes">
+          <title>Future schemes</title>
+          <p>
+            So far, the "<code>site:</code>" and "<code>ext:</code>" schemes are defined.
+            To give you some ideas on other things we'd like to implement (and
+            wouldd welcome help to implement) here are a few possibilities.
+          </p>
+          <table>
+            <tr><th colspan="1" rowspan="1">Scheme</th><th colspan="1" rowspan="1">Example "From"</th><th colspan="1" rowspan="1">Example "To"</th><th colspan="1" rowspan="1">Description</th></tr>
+            <tr>
+              <td colspan="1" rowspan="1">java</td>
+              <td colspan="1" rowspan="1">java:org.apache.proj.SomeClass</td>
+              <td colspan="1" rowspan="1"><code>../../apidocs/org/apache/proj/SomeClass.html</code></td>
+              <td colspan="1" rowspan="1">
+                Links to documentation for a Java class (typically generated by
+                <code>javadoc</code>).
+              </td>
+            </tr>
+            <tr>
+              <td colspan="1" rowspan="1">mail</td>
+              <td colspan="1" rowspan="1">mail::&lt;Message-Id&gt;</td>
+              <td colspan="1" rowspan="1"><code>http://marc.theaimsgroup.com?t=12345678</code></td>
+              <td colspan="1" rowspan="1">
+                Links to an email, identified by its <code>Message-Id</code>
+                header. Any mail archive website could be used.
+              </td>
+            </tr>
+            <tr>
+              <td colspan="1" rowspan="1">search</td>
+              <td colspan="1" rowspan="1">search:&lt;searchterm&gt;</td>
+              <td colspan="1" rowspan="1"><code>http://www.google.com/search?q=searchterm</code></td>
+              <td colspan="1" rowspan="1">Link to set of results from a search engine</td>
+            </tr>
+            <tr>
+              <td colspan="1" rowspan="1">person</td>
+              <td colspan="1" rowspan="1">person:JT, person:JT/blog etc</td>
+              <td colspan="1" rowspan="1"><code>mailto:jefft&lt;at&gt;apache.org</code>,
+                <code>http://www.webweavertech.com/jefft/weblog/</code></td>
+              <td colspan="1" rowspan="1">
+                A "<code>person:</code>" scheme could be used, say, to insert an
+                automatically obfuscated email address, or link to a URI in some
+                way associated with that person.
+              </td>
+            </tr>
+          </table>
+          <p>
+            There are even more possibilities in specific environments.  In an
+            intranet, a "<code>project:XYZ</code>" scheme could identify company
+            project pages.  In a project like <link href="ext:ant">Apache
+              Ant</link>, each Task could be identified with
+            <code>task:&lt;taskname&gt;</code>, e.g. <code>task:pathconvert</code>.
+          </p>
+        </section>
+      </section>
+    </section>
+    <section id="concept">
+      <title>Concept</title>
+      <p>
+        The "<code>site:</code>" scheme and associated ideas for site.xml were
+        originally described in <link href="ext:linkmaps">the 'linkmap' RT
+          email</link> to the forrest-dev list (RT means 'random thought'; a
+        Cocoon invention).   Only section 2 has been implemented, and there is
+        still significant work required to implement the full system
+        described.  In particular, there is much scope for automating the
+        creation of site.xml (section 4).  However, what is currently implemented
+        gains most of the advantages of the system.
+      </p>
+    </section>
+    <section id="implementation">
+      <title>Implementation</title>
+      <p>Full details on the implementation of
+      <link href="site:v0.70//linkrewriting_impl">link rewriting</link> and
+      <link href="site:v0.70//menu_generation_impl">menu generation</link> are available in
+      the <link href="site:v0.70//sitemap-ref">Sitemap Reference</link></p>
+    </section>
+
+  </body>
+</document>
\ No newline at end of file

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

Added: forrest/site/docs_0_70/primer.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/primer.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/primer.source.xml (added)
+++ forrest/site/docs_0_70/primer.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,558 @@
+<?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>The Forrest Primer</title> 
+    <subtitle>Don't panic!</subtitle> 
+    <abstract>Forrest is a so-called
+      <link href="http://www.dictionary.com/cgi-bin/dict.pl?term=fledgling">fledgling</link>
+      project that will have a broad impact on
+      <link href="http://xml.apache.org/">xml.apache.org</link> projects. This document
+      helps you to better understand the vision and scope of Forrest, so that you
+      learn what to expect (or not) from it, and eventually will help you discovering
+      places where your contribution could be valuable to all of us.</abstract> 
+  </header> 
+  <body> 
+    <warning>This document is <em>very</em> out of date. There is a lot of good
+      information here, but the focus of the project has shifted away from the
+      Sourceforge-like project management system described here, towards being a
+      simpler project-centric documentation tool -- JT</warning> 
+    <section>
+      <title>History</title> 
+      <p>Forrest has come into existence because of the abysmal state of the
+        <link href="http://xml.apache.org/">xml.apache.org</link> website in comparison
+        with other open source community sites such as Sourceforge. The old site had no
+        consistent visual look and feel, which was largely due to each and every
+        sub-project managing its own site. Furthermore, much information which could
+        potentially support community-based open source development was hidden inside
+        CVS repositories, mailing lists or word of mouth. Once we experienced the
+        usefullness of cross-project collaboration supported by the Jakarta
+        <link href="http://jakarta.apache.org/gump">Gump</link> project, we reckoned
+        having a single application responsible for the management of the
+        xml.apache.org site could be of benefit to our visitors. And if we added
+        aggregated access to other available resources such as download stats or
+        mailing list archives, the new xml.apache.org website could be a true
+        information clearinghouse for interested parties, both users and contributors
+        alike.</p> 
+      <p>The Forrest vision was articulated by Stefano Mazzocchi and Sam Ruby,
+        both long-time contributors to Apache projects, in the beginning of 2002, and
+        was rapidly picked up by a bunch of other 
+        <link href="site:who">contributors</link> as well, after a headstart by Nicola Ken
+        Barozzi. So here we are, plenty of work-in-progress to erect what eventually
+        will become a true community website infrastructure for Apache open source
+        development.</p> 
+    </section> 
+    <section>
+      <title>What is Forrest</title>
+      <p>Forrest is a framework that supports the cross-project generation and
+        management of development project websites using Cocoon as its XML publishing
+        framework. It not only provides access to project documentation, but also to
+        other types of information that open source developers depend upon daily:
+        source code repositories, mailing lists, contact info and the like. It
+        aggregates all these resources and publishes them on a regular basis to a
+        website, ensuring a consistent look and feel using skins implemented with XSLT
+        stylesheets. While Forrest's primary focus is XML Apache project websites, it
+        can be adapted to other community development projects as well, as long as they
+        are willing to commit to proven best practices such as Ant for build
+        automation, CVS for source code control and XML as a documentation source
+        format.</p> 
+      <p>Forrest is currently based on an
+        <link href="http://jakarta.apache.org/ant/">Ant</link>-based project build
+        system called <link href="http://www.krysalis.org/centipede/">Centipede</link>
+        that drives a <link href="http://cocoon.apache.org/">Cocoon</link>-based
+        document publication system. It contains a set of standard XML document type
+        declarations (DTDs) for project documentation, and different 'skins' consisting
+        of XSLT stylesheets that produce HTML renditions of XML documents using these
+        DTDs.</p> 
+      <p>The primary mode of operations for Forrest will be as follows:</p> 
+      <note>This process is not quite ready for prime time yet, but it gives
+        you an idea where we are heading to. Website generation with skins currently
+        works, try using the <code>docs</code> target when invoking the
+        <code>build</code> script. Add a <code>project.skin</code> property when invoking
+        the build script to experience Forrest skins: <code>build{.bat|.sh}
+          -Dproject.skin=&lt;thenameoftheskintouse&gt; docs</code>. Read our
+        <link href="#cvs">CVS crash course</link> to get hold of the current codebase and
+        start playing with it.</note> 
+      <ol> 
+        <li>Forrest will harvest documentation and related source files from
+          each of the projects within the community that uses Forrest for their website,
+          usually direct from the CVS repository. Which projects are included, and how
+          they are retrieved is configured by a project descriptor file. This is an
+          automated process that occurs several times a day to ensure Forrest has the
+          latest information available.</li>
+        <li>Forrest then uses Cocoon to generate an HTML rendition of each
+          project's website, configured by a generic sitemap. The result is a static
+          collection of HTML documents and related images and stylesheets comprising the
+          project's website. The impact Forrest has on the participating projects should
+          be minimal, i.e. one should simply author XML documents, put them in a
+          well-specified filesystem hierarchy, and Forrest will do its work.</li> 
+        <li>Forrest will enrich the documentation source files with common
+          information: a cross-project navigation structure (and rendition, of course),
+          and useful 'community indicators' such as download statistics, number of
+          contributors with commit access, ...</li> 
+        <li>If the individual project build runs are successful, the project's
+          website is automagically (re-)published to the (Apache) website, also several
+          times day.</li> 
+      </ol> 
+      <p>The Forrest website and the overall xml.apache.org website are
+        maintained and published using the same mechanism.</p> 
+    </section> 
+    <section>
+      <title>Forrest roles</title>
+      <p>Depending on your interests, your involvement with Forrest may vary,
+        hence your <em>role</em>. We currently envision three different roles:</p> 
+      <ul> 
+        <li><strong>User</strong> you want or need to use Forrest for your
+          project because it uses Forrest to manage its documentation.</li> 
+        <li><strong>Adaptor</strong> you want to adapt Forrest to support your
+          individual project needs, presumably outside the XML Apache context, building
+          your own skins or DTDs and the like.</li> 
+        <li><strong>Contributor</strong> you are a fledgling Forresteer and
+          want to contribute to the further development of it. If your contributions are
+          valuable and in true community spirit, you can possibly gain commit access to
+          the Forrest CVS repository and become an Apache committer. The first stage
+          towards becoming a contributor is to join the forrest dev
+          <link href="site:mail-lists">mailing list</link>, the second is to download
+          Forrest and start playing with it (see below).</li> 
+      </ul> 
+      <p>Depending on your role, your potential area of interest in Forrest
+        will vary:</p> 
+      <table> 
+        <tr> 
+          <th colspan="1" rowspan="1">Role</th> 
+          <th colspan="1" rowspan="1">Interests</th> 
+        </tr> 
+        <tr> 
+          <td colspan="1" rowspan="1">User</td> 
+          <td colspan="1" rowspan="1">Forrest DTDs and documentation filesystem hierarchy (Cocoon
+            sitemap)</td> 
+        </tr> 
+        <tr> 
+          <td colspan="1" rowspan="1">Adaptor</td> 
+          <td colspan="1" rowspan="1">+ skin system and build environment</td> 
+        </tr> 
+        <tr> 
+          <td colspan="1" rowspan="1">Contributor</td> 
+          <td colspan="1" rowspan="1">+ the Forrest codebase and runtime environment</td> 
+        </tr> 
+      </table> 
+    </section> 
+    <section id="cvs">
+      <title>Getting your local copy of Forrest through CVS</title> 
+      <section>
+        <title>System requirements</title>
+        <p>Forrest requires the following systems to be already installed on
+          your system:</p> 
+        <ul> 
+          <li><em>Java Virtual Machine</em> A Java virtual machine must be
+            present. Forrest has been tested against the latest Sun 1.3 JDK.</li> 
+        </ul> 
+      </section> 
+      <section>
+        <title>Getting Forrest</title>
+        <p>You can retrieve Forrest from its CVS repository or download
+         <link href="http://www.apache.org/dyn/closer.cgi/xml/forrest/">here</link>.
+          <br/>Some help with CVS follows (courtesy of our friends of the Cocoon project).</p> 
+      </section> 
+      <section>
+        <title>Step-by-step cvs instructions for Windows</title>
+        <ol> 
+          <li>Download a recent release of WinCVS (homepage is
+            <link href="http://www.wincvs.org/">http://www.wincvs.org/</link>); </li> 
+          <li>Install it;</li> 
+          <li>Start it;</li> 
+          <li>Click on Admin-&gt;Preferences;</li> 
+          <li> In "Enter the CVSROOT:" enter
+            "<code>:pserver:anoncvs@cvs.apache.org:/home/cvspublic</code>" (without
+            quotes);</li> 
+          <li>In "Authentication:" choose "passwd file on the cvs server";</li> 
+          <li>Click "Ok";</li> 
+          <li>Click Admin-&gt;Login;</li> 
+          <li> When asked for the password: answer "<code>anoncvs</code>"
+            (without quotes);</li> 
+          <li> Click "Create-&gt;Checkout module";</li> 
+          <li>Module name and path on the server is "<code>xml-forrest</code>"
+            (no quotes);</li> 
+          <li>Choose a dir to put the source code in;</li> 
+          <li>Click "Ok";</li> 
+          <li>If everything goes well, messages will start to appear in the log
+            window;</li> 
+          <li>Wait until you see "<code>*****CVS exited normally with code
+              0*****</code>" in the log window;</li> 
+          <li>The Forrest source is now on your harddrive.</li> 
+        </ol> 
+      </section> 
+      <section>
+        <title>Step-by-step cvs instructions for Unix</title>
+        <ol> 
+          <li>Make sure you have a CVS client package installed on your Unix
+            system.</li> 
+          <li>Start the shell of your choice.</li> 
+          <li>Enter "<code>cvs -d
+              :pserver:anoncvs@cvs.apache.org:/home/cvspublic login</code>".</li> 
+          <li>When asked for the password: answer "<code>anoncvs</code>".</li> 
+          <li>Enter "<code>cvs -d
+              :pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 checkout
+              xml-forrest</code>". This will create a directory called
+            "<code>xml-forrest</code>" where the Forrest source will be stored.</li> 
+          <li>Wait until cvs has finished.</li> 
+          <li>The Forrest source is now on your harddrive.</li> 
+        </ol> 
+        <p>In case you want to update your Forrest source tree to the current
+          version, change to the "<code>xml-forrest</code>" directory and invoke
+          "<code>cvs -z3 update -d -P</code>".</p> 
+      </section> 
+    </section> 
+    <section>
+      <title>Forrest distribution</title>
+      <p>Once you retrieved Forrest from its CVS repository, you will end up
+        with a filesystem hierarchy similar to this inside the <code>xml-forrest</code>
+        home directory:</p> 
+      <warning>This is highly volatile information!</warning> 
+      <source xml:space="preserve"><![CDATA[+---legal                             various licenses for included projects
++---lib                               jar library
++---src
+|   +---documentation               Forrest's documentation (not generally reusable)
+|   |   +---content                 content of the Forrest website
+|   |   |   +---xdocs               Forrest website XML documents
+|   |   +---resources               Forrest-specific doc resources
+|   |   |   +---images
+|   +---resources                   Generic resources for any Forrest-using project.
+|   |   +---conf                    Default (overridable) Forrest config files
+|   |   +---library                 common components (not skin-specific)
+|   |   |   +---xslt                document format transformers e.g. faq->xdoc
+|   |   +---convert                 XSLTs for aiding a transition to Forrest
+|   |   +---skins                   Forrest skins
+|   |       +---basic
+|   |       +---forrest-site        the future xml.apache.org skin
+|   |       |   +---css             Cascading Stylesheets
+|   |       |   +---images          skin-specific images
+|   |       |   +---xslt            the skin stylesheets (per medium)
+|   |       |       +---fo
+|   |       |       +---html        html rendering skins
+|   |       +---jakarta-site
+|   |       +---scarab-site
+|   |       +---xml-apache-site
+|   |   +---schema                  Generic Forrest DTDs
+|   |       +---dtd
+|   |       +---relaxng
+|   |       +---entity
+|   |   +---images                  Reusable skin-agnostic images 
+|   |   +---fresh-site              A template project structure
+|   |   +---forrest-shbat           'shbat' Forrest distribution files
+|   |   +---forrestbot              Ant-based Forrest deployment tool
+|   |   +---forrestbar              Mozilla Forrest toolbar
+|   |   +---charts                  charting trials
+|   |   +---layout                  HTML page mock-ups
+|   |   |   +---resources
+|   |   |   +---xml.apache.org
+|   |   |       +---images
+|
++---tools                           Tools used to build Forrest
+    +---ant                         Ant 1.6-dev scripts and jars
++---stylesheets                     Stylesheets used for project root XML files
+]]></source> 
+      <p>The <code>xml-forrest</code> home directory consists of the main Ant
+        build script (<code>build.xml</code>) and platform-specific batch files/shell
+        scripts to invoke it. Forrest comes with Ant included, so you do not need to
+        install Ant separately.</p> 
+      <p>Running Forrest is a batch operation you can start using the provided
+        <code>build.{sh|bat} &lt;targetname&gt;</code>. The current main targets
+        are:</p> 
+      <ul> 
+        <li><strong><code>docs</code></strong> - generates an HTML rendition of
+          the Forrest website using the default <code>forrest-site</code> skin</li> 
+        <li><strong><code>clean</code></strong> - cleans out the
+          <code>build</code> directory</li> 
+        <li><strong><code>webapp</code></strong> - for those who cannot resist
+          running Forrest live instead of its commandline invocation, this target builds
+          a WAR file you can deploy in your servlet container (currently only tested for
+          Tomcat 4.0.1). Mount-point of the web application will be
+          <code>xml-forrest</code>.</li> 
+      </ul> 
+      <p>After a build run, Forrest creates a <code>build</code> directory. You
+        can find the generated website in the <code>build/xml-forrest/docs/</code>
+        directory. Forrest also creates a <code>tools/tmp/anttasks/</code> upon its
+        first invocation. These are Centipede-specific compiled Ant tasks.</p> 
+    </section> 
+    <section>
+      <title>The Forrest DTDs</title>
+      <p>Forrest is the reference repository for the XML Apache documentation
+        DTDs. Special care is taken to provide a set of modular, extensible and
+        well-maintained DTDs for project documentation purposes. This modularity is
+        ensured using the
+        <link href="http://www.oasis-open.org/committees/entity/">OASIS catalog</link>
+        mechanism, extensive use of external parameter entities and an entity resolver
+        capable of resolving entities through the aforementioned catalog mechanism. For
+        the docheads amongst us, this means we adhere to the strict use of
+        <code>PUBLIC</code> entity identifiers both in document instances and DTD
+        modules.</p> 
+      <p>We have currently identified the following document types:</p> 
+      <ul> 
+        <li>General documents (<code>document-v11.dtd</code>),</li> 
+        <li>How-Tos (<code>howto-v10.dtd</code>),</li> 
+        <li>Collections of FAQs (<code>faq-v11.dtd)</code>.</li> 
+      </ul> 
+      <p>Some work is also under its way for other document types, in close
+        collaboration with the Cocoon project. You will also find some older document
+        types such as <code>changes</code>, <code>javadoc</code>,
+        <code>specification</code> and <code>todo</code>, which are currently under
+        consideration for automatic generation and maintenance using Gump or Centipede
+        descriptors and the like. DTDs will be subject of serious version management as
+        soon as Forrest has a 1.0 release: they are made to depend upon.</p> 
+      <p>The DTDs are located in <code>src/resources/schema/dtd</code> and also
+        refer to some character entity collections stored in the
+        <code>src/resources/schema/entity</code> directory. These are referred to by
+        the declarations found in the <code>src/resources/schema/catalog</code> OASIS
+        Catalog file. Take special care using the correct <code>PUBLIC</code>
+        identifiers in the DTD declaration of your instances:</p> 
+      <source xml:space="preserve"><![CDATA[<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd">
+<document>
+  ...
+  ]]></source> 
+      <p>The exact local location of the DTD for validation purposes is
+        obtained by the entity resolver evaluating the mapping scheme as defined in the
+        <code>catalog</code> file. This makes sure that you can move and re-arrange
+        your document instances apart from your DTD files. Later on, the DTDs will be
+        web-accessible from the Forrest website for your perusal.</p> 
+    </section> 
+    <section id="sitemap">
+      <title>Forrest site generation using Cocoon</title>
+      <p>The <code>docs</code> target of the Forrest build environment invokes
+        Cocoon as a command-line application to generate an HTML rendition of the
+        project's documentation. It is not within the scope of this document to explain
+        the Cocoon internals, please read its own
+        <link href="http://cocoon.apache.org/">documentation</link> to fully
+        understand the power of Cocoon.</p> 
+      <p>Cocoon's site rendition behaviour is configured in a so-called
+        <em>sitemap</em>, a switchboard that binds URLs to an XML processing pipeline.
+        This pipeline typically consists of a Generator, one or more Transformers and a
+        Serializer. Forrest also makes use of Cocoon's aggregation capabilities that
+        merge multiple pipelines into one resulting output document.</p> 
+      <p>A typical page generated using Forrest looks like this:</p>
+      <figure src="images/page-areas.png" height="291" width="336" alt="Pages areas"/> 
+      <p>This page is currently composed of two XML sources which are
+        transformed by a different XSLT stylesheet, aggregated by Cocoon with a
+        post-aggregation stylesheet adding the overall page grid and look &amp; feel.
+        This simple example is handled by the following <em>sitemap</em> snippets
+        (<code>src/documentation/conf/sitemap.xmap</code>):</p> 
+      <source xml:space="preserve"><![CDATA[<map:match pattern="*.html">
+  <map:aggregate element="site">
+    <map:part src="cocoon:/book-{1}.xml"/>
+    <map:part src="cocoon:/body-{1}.xml" label="content"/>
+  </map:aggregate>
+  <map:call resource="skinit">
+    <map:parameter name="type" value="site2xhtml"/>
+  </map:call>
+</map:match>]]></source> 
+      <source xml:space="preserve"><![CDATA[<map:match pattern="**book-**.xml">
+  <map:generate src="content/xdocs/{1}book.xml"/>
+  <map:call resource="skinit">
+    <map:parameter name="type" value="book2menu"/>
+  </map:call>
+</map:match>]]></source> 
+      <source xml:space="preserve"><![CDATA[<map:match pattern="body-**.xml">
+  <map:generate src="content/xdocs/{1}.xml"/>
+  <map:call resource="skinit">
+    <map:parameter name="type" value="document2html"/>
+  </map:call>
+</map:match>]]></source> 
+      <source xml:space="preserve"><![CDATA[<map:resource name="skinit">
+  <map:transform src="skins/@skin@/xslt/html/{type}.xsl">
+    <map:parameter name="isfaq" value="{isfaq}"/>
+  </map:transform>
+  <map:serialize/>
+</map:resource>]]></source> 
+      <p>When an URL (e.g.
+        <code>http://forrest.apache.org/index.html</code>) is passed through the
+        Cocoon system to generate the required page, the pipeline flow is basically as
+        follows:</p> 
+      <ol> 
+        <li>The URL is matched by the <code>*.html</code> pattern</li> 
+        <li>Cocoon responds by aggregating two 'sub-requests'. The first is for
+          the resource <code>book-{1}.xml</code>, the second is for the resource
+          <code>body-{1}.xml</code>. The <code>{1}</code> parameter is replaced by the
+          values of the first wildcard in the matching pattern above. These
+          'sub-requests' are passed through the Cocoon pipeline just like any other
+          request. This results in the following flow:</li> 
+        <ol> 
+          <li>The first 'sub-request' (for <code>book-index.xml</code> is matched
+            by the <code>**book-**.xml</code> pattern. This results in the file
+            <code>content/xdocs/book.xml</code> being read. This document is then run
+            through the <code>book2menu</code> stylesheet (which produces an HTML fragment
+            comprising the site navigation, the red area in the image above.</li> 
+          <li>The second 'sub-request' is matched by the <code>body-**.xml</code>
+            pattern. This results in the file <code>index.xml</code> being transformed
+            using the <code>document2html</code> stylesheet, the yellow area in the
+            screenshot.</li> 
+        </ol> 
+        <li>The aggregation result is then transformed using the
+          <code>site2xhtml</code> stylesheet which adds the cherries to the cake. The
+          grey zone.</li> 
+      </ol> 
+      <p>These <em>skin-specific</em> stylesheets are located in
+        <code>src/documentation/skins/&lt;nameoftheskin&gt;/xslt/html</code>, so if you
+        want to add your own skin, this is the place to be. Apart from these, there
+        exist a number of other stylesheets located in
+        <code>src/documentation/library/xslt</code> and more importantly:</p> 
+      <ul> 
+        <li><code>faq2document</code>: transforms documents following the
+          <code>faq-v11</code> DTD to <code>document-v11</code> grammar</li> 
+        <li><code>howto2document</code>: transforms documents following the
+          <code>howto-v10</code> DTD to <code>document-v11</code> grammar</li> 
+        <li>and some others.</li> 
+      </ul> 
+      <p>As you see, all documents, regardless of their original DTD, are
+        transformed to the <code>document</code> DTD prior to rendition. This
+        alleviates the burden of adding new skins to implementing 3 simple stylesheets:
+        <code>book2menu</code>, <code>document2html</code> and
+        <code>site2xhtml</code>.</p> 
+    </section> 
+    <section>
+      <title>Where we are heading to</title>
+      <p>We have been explaining so far where we are now and what already
+        works. The purpose of this document however is to attract newcomers and entice
+        them to start contributing to Forrest. We have a decent generation system for
+        static project documentation, a nice set of skins and some simple but effective
+        DTDs. Our goals however are much more ambitious: we have compiled a
+        <link href="site:v0.70//dreams">dream list</link> that lists most of them.</p> 
+      <ul> 
+        <li>Our first ambition is to support the project site generation and
+          maintenance of other Apache projects in an automated manner, starting with our
+          own website as a showcase. We are in the process of setting up the shell
+          scripts and Ant tasks for this and will assist projects transitioning to
+          Forrest.</li> 
+        <li>As it is often the case with collaborative open source development,
+          there is no formal planning nor task assignments, and we will stick to that
+          practice. We have however compiled a number of functional work areas:</li> 
+      </ul> 
+      <table> 
+        <tr> 
+          <th colspan="1" rowspan="1">URI Namespace Management</th> 
+          <td colspan="1" rowspan="1">Forrest will offer access to a broad set of information resources
+            using durable URIs: please review
+            <link href="ext:cool-uris">Tim Berners-Lee</link>'s
+            and <link href="http://www.useit.com/alertbox/990321.html">Jakob
+              Nielsen</link>'s opinion on this. We need a unified URI Namespace management
+            approach, bearing in mind mirroring and 'hackable' URIs.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Skins</th> 
+          <td colspan="1" rowspan="1">We currently have a nice set of skins which should be solidified.
+            Furthermore, we need some serious finetuning of the <code>forrest-site</code>
+            skin that will become the new xml.apache.org look&amp;feel.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Aggregation<br/>and Syndication</th> 
+          <td colspan="1" rowspan="1">We plan to aggregate on a per-project basis a number of relevant
+            developer resources, such as project-related news, download statistics,
+            committer bio pages (with photos!), navigable source code listings and the
+            like. Some of these resources need to be made available across content
+            syndication methods such as 
+            <link href="http://blogspace.com/rss/">RSS</link>.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Build Management</th> 
+          <td colspan="1" rowspan="1">Fool-proof automation of Forrest runs and site publication using
+            secure transfer methods and <code>cron</code> jobs.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Document Types</th> 
+          <td colspan="1" rowspan="1">Expanding the collection of DTDs, documenting them using formal
+            How-Tos and example documents.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">xml.apache.org</th> 
+          <td colspan="1" rowspan="1">Formation of an editorial team for the main xml.apache.org website,
+            working in close collaboration with the
+            <link href="http://xml.apache.org/whoweare.html">PMC</link> and the different
+            sub-project leads.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Integration</th> 
+          <td colspan="1" rowspan="1"> Forrest needs to coexist with existing cross-project collaboration
+            tools such as <link href="ext:gump">Gump</link>,
+            <link href="http://scarab.tigris.org/">Scarab</link> and
+            <link href="http://eyebrowse.tigris.org/">Eyebrowse</link> and provide
+            integrated access to them.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Authoring support</th> 
+          <td colspan="1" rowspan="1">Supporting document authors with preconfigured XML editing
+            solutions.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Content Management</th> 
+          <td colspan="1" rowspan="1">Establish an efficient content management practice, supporting
+            versioning, remote access and work flow, presumably supported by a CMS such as
+            <link href="http://jakarta.apache.org/slide/">Slide</link>.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Information Accessibility</th> 
+          <td colspan="1" rowspan="1">We need to be accessible using a wide range of browsing devices
+            operating on different platforms. Special care should be taken to support the
+            <link href="http://www.w3.org/WAI/">WAI</link> guidelines.</td> 
+        </tr> 
+      </table> 
+    </section> 
+    <section>
+      <title>Where you can help</title> 
+      <p>By now, you should have a better understanding of Forrest (if that is
+        not the case, consider contributing clarifications to this document).
+        We need more people to get the job done.
+        Forrest is a fun project to work on, and there is something in it for
+        all of us:</p> 
+      <ul> 
+        <li>XML docheads with skills for document analysis and DTDs
+          development</li> 
+        <li>Cocoon developers creating custom Cocoon components connecting
+          Forrest with external resources</li> 
+        <li>Graphical whizzkids for true cross-browser HTML/CSS
+          development</li> 
+        <li>People who believe XSLT will bring peace to earth (it will, but
+          keep that quiet)</li> 
+        <li>Ant wizards able to compete with Nicola and Stefan</li> 
+        <li>Unix shell scripting / CVS / cron gurus, preferably bearded</li> 
+      </ul> 
+      <p>Just drop us a line at 
+       the forrest-dev <link href="site:mail-lists">mail list</link>.
+      </p>
+
+    </section> 
+    <p>That is all, folks.</p> 
+    <table> 
+      <tr> 
+        <th colspan="1" rowspan="1">Revision history</th> 
+        <th colspan="1" rowspan="1"/> 
+      </tr> 
+      <tr> 
+        <td colspan="1" rowspan="1">2002-05-22</td> 
+        <td colspan="1" rowspan="1">Initial version, Steven Noels, stevenn.at.apache.org</td> 
+      </tr>
+      <tr>
+        <td colspan="1" rowspan="1">2002-05-23</td>
+        <td colspan="1" rowspan="1">Various rephrasings and clarifications thanks to Ross Gardler,
+          ross.at.saafe.org</td>
+      </tr> 
+      <tr>
+        <td colspan="1" rowspan="1">2002-09-23</td>
+        <td colspan="1" rowspan="1">Updated the directory outline (jefft.at.apache.org)</td>
+      </tr> 
+    </table> 
+  </body>
+</document>
\ No newline at end of file

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

Added: forrest/site/docs_0_70/project-sitemap.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/project-sitemap.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/project-sitemap.source.xml (added)
+++ forrest/site/docs_0_70/project-sitemap.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,80 @@
+<?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>Using project sitemaps</title> 
+  </header> 
+  <body> 
+    <section id="introduction">
+      <title>Introduction</title>
+
+      <p>After Forrest 0.6 it is now possible for projects to intercept
+      the core sitemaps, without needing to copy the main sitemaps and keep
+      them synchonised. This will enable hassle-free update to
+      future Forrest versions.</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>
+
+    <section id="how">
+      <title>How does it work?</title>
+
+      <p>If a project has a <code>sitemap.xmap</code> file in it's 
+      documentation dir, that gets mounted automatically by Forrest and 
+      becomes part of the processing: it is a preprocessing step, and 
+      is the first one to handle the request. Because of this it can 
+      serve any file directly. If it does not want to 
+      serve a file, it can simply not match the URL and Forrest will take 
+      care of it as usual.</p>
+
+      <p>The cool thing is that if that pipeline serves an xml representation, 
+      Forrest will provide a skinned version of it.</p>
+
+      <p>So if the project sitemap matches test.xml and transforms that to a
+      correctly structured Forrest intermediate "document-v*",
+      then the user will see test.html fully rendered by Forrest.</p>
+
+      <p>Of course, to resolve the directories in your sitemap it is important 
+      to use the 'project:' and 'forrest:' variables to prevent any possible 
+      issue in the future.</p>
+    </section>
+
+    <section id="examples">
+      <title>Example uses of this technique</title>
+
+      <section id="download">
+        <title>Adding a new content type</title>
+        <p>
+          See the section "Advanced customizations: sitemap.xmap" in
+          the <link href="site:v0.70//your-project">Using Forrest</link> document
+          and then follow the
+          <link href="site:v0.70//your-project/new_content_type">Example:
+          Adding a new content type</link>.
+        </p>
+      </section>
+    </section>
+  </body>
+</document>
\ No newline at end of file

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

Added: forrest/site/docs_0_70/searching.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/searching.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/searching.source.xml (added)
+++ forrest/site/docs_0_70/searching.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,124 @@
+<?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>Searching Forrest-built documentation</title>
+  </header>
+  <body>
+    <p>Forrest provides you with two distinct options for making your
+      documentation available through full-text search:</p>
+    <ul>
+      <li>Google SiteSearch,</li>
+      <li>Built-in search using Apache Lucene.</li>
+    </ul>
+    <p>Both options have their advantages and disadvantages. The
+      purpose of this document is to outline them, and to help you
+      make a choice. This document also tells you how to disable
+      full-text search completely, if you so choose.</p>
+    <section>
+      <title>Google SiteSearch</title>
+      <p>Forrest provides a simple interface to the Google search
+	engine. It invokes Google Advanced Search and limits the search
+	scope to the domain of your choice. Since the actual search
+	functionality is implemented on Google's end, you do not need
+	any additional capability on your Forrest server (which may
+	well be a simple static web server serving content generated
+	with <code>forrest site</code>).</p>
+      <p>To use Google SiteSearch in your Forrest application, open
+	your <code>skinconf.xml</code> file. By default this file is
+	in the <code>src/documentation</code> subdirectory of your
+	Forrest repository root. Find the <code>&lt;search&gt;</code>
+	element; it should be near the top of the file. If the element
+	does not exist, create it below the
+	<code>&lt;skinconfig&gt;</code> opening tag. If there is any
+	attribute named <code>provider</code>, remove it. The element
+	should look similar to this:</p>
+      <source xml:space="preserve"><![CDATA[<search name="MyProject"
+	domain="myproject.com"/>]]></source>
+      <p>Then, build your Forrest documentation and open it using your
+	favorite web browser. You are now invited to peruse the search
+	box (most skins render this in the top-right corner). Google's
+	search results will be displayed in a new browser window.</p>
+      <p>Needless to say, for this to work your content must be
+	accessible to Google's indexing robot. It can't be stored on a
+	server which is only locally accessible, or which requires
+	authentication. In addition, the content index is created and
+	updated at a time of Google's choosing. However, the search is fast
+	and search precision is usually excellent. So if your
+	Forrest content is placed on a busy, popular public web
+	server, Google search is probably the best choice.</p>
+    </section>
+    <section>
+      <title>Lucene search</title>
+      <p>Lucene is a high-performance, full-text search engine built
+	entirely in Java. To use Lucene-based search with your Forrest
+	documentation, you will need to run Forrest in a Java servlet
+	environment (such as Tomcat or Jetty). Lucene-based searching
+	will not work in a static site generated with the '<code>forrest
+	  site</code>' command.</p>
+      <p>In order to enable Lucene-based full-text search in your
+	Forrest application, you must first edit your
+	<code>skinconf.xml</code> file. Locate the
+	<code>&lt;search&gt;</code> element. If the element does not
+	exist, insert it right underneath the
+	<code>&lt;skinconfig&gt;</code> opening tag. Add an attribute
+	named <code>provider</code> with a value of
+	<code>lucene</code>, so that the element looks similar to
+	this:</p>
+      <source xml:space="preserve"><![CDATA[<search name="MyProject" domain="myproject.com"
+	provider="lucene"/>]]></source>
+      <p>Next, create and run your Forrest webapp. This may mean
+	simply invoking <code>forrest run</code>, or building and
+	bundling a servlet webapp (with <code>forrest webapp</code>),
+	and then deploying it to your servlet container.</p>
+      <p>You can now build a Lucene search index by pointing your web
+	browser at
+	<code>http://localhost:8888/lucene-update.html</code>. This
+	generates the search index and provides some information about
+	the index generation process.</p>
+      <note>You may have to substitute a different hostname, port, or
+	path, depending on your configuration. The path mentioned here
+	reflects Forrest's default settings when invoked as
+	<code>forrest run</code>.</note>
+      <p>Now you can utilize the full-text search box, located in the
+	top-right corner of the rendered Forrest pages. Search results
+	will be displayed in the same browser window and will look
+	remarkably similar to the rest of your Forrest documents.</p>
+      <p>Unlike with Google SiteSearch, the indexing information
+	retrieved by Lucene is stored on your own server, access to
+	which you may limit to users in your own organization.
+	Likewise, you may update or recreate the Lucene index at any
+	time and at your own discretion. So if you aren't making your
+	Forrest-built documentation publicly available, and you're
+	able to run Forrest on a Java-enabled web server, Lucene
+	search is probably right for you.</p>
+    </section>
+    <section>
+      <title>Disabling full-text search</title>
+      <p>If you are convinced your users don't need any full-text
+	search capability whatsoever, you may disallow displaying the
+	search box entirely. You may also wish to do so if you're
+	keeping Forrest-built content on a restricted server (meaning
+	you can't use Google), while at the same time not having any
+	usable servlet-capable web server at your disposal (meaning
+	you can't use Lucene, either).</p>
+      <p>To disable full-text search completely, open the
+	<code>skinconf.xml</code> file and remove (or comment out) the
+	entire <code>&lt;search&gt;</code> element.</p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

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



Mime
View raw message