<?xml version="1.0"?>
<!--
  Copyright 2002-2004 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>URI namespace description</title> 
    <subtitle>Background reading for the Forrest sitemap</subtitle>
    <abstract>This document describes the URI request namespace as being
      declared and supported by Forrest. Its concrete implementation can be found in
      Forrest's Cocoon sitemap.</abstract> 
  </header> 
  <body> 
    <p>Since Forrest uses Cocoon as its documentation generation mechanism, it
      ships with a Cocoon
      <link href="http://cocoon.apache.org/userdocs/concepts/sitemap.html">sitemap</link>
  stating the so-called URI namespace being declared by Forrest. So this document
  serves as a background reader for people trying to understand the sitemap and
  the internal workings of the Cocoon link crawling. It should answer questions
  like "what kind of resources can I add to my project documentation" and "how
  should I specify my links inside my documents so that they are correctly
  processed by Forrest". This doesn't mean your HTML hypertext writing skills of
  the past will not help you anymore while creating documents to be processed by
  Forrest, but since Cocoon is a less forgiving (read: "best practices
  enforcing") hypertext processing environment than the Web, there is a need for
  an authorative source on URIs in the Forrest space. This document is meant to
  be that source.</p> 
  <section> 
    <title>URI hierarchy</title> 
    <section> 
      <title>External</title> 
      <p><strong>Network protocol</strong> Currently, the only network protocol
        that can be used to access Forrest resources is <em>HTTP</em>. Of course, you
        can embed hypertext references to other protocols (<code>news:</code>,
        <code>mailto:</code>, ...), but these links are not processed by the
        crawler.</p> 
      <p><strong>Host</strong> Forrest publishes its generated documentation on
        some server, so part of the URI namespace is the <em>host address</em>, i.e.
        <code>xml.apache.org</code>,<code>intranetsrv2</code> or
        <code>localhost</code>.</p> 
      <p><strong>Mountpoint</strong> Similar to so-called Java Web
        Applications, a Forrest website URI is often prepended with a
        <em>mountpoint</em>, indicating the root of the website shouldn't be found on
        <code>http://somehost/</code>, but on <code>http://somehost/mountpoint/</code>
        instead. Declaring a mountpoint is <em>optional</em> however.</p> 
      <p>Both <code>host</code> and <code>mountpoint</code> are passed into the
        Forrest processing pipeline as Cocoon sitemap parameters and subsequently as
        XSLT parameters too, which means they are accessible to skin designers. They
        should be declared like:</p> 
      <ul> 
        <li><strong>host:</strong> <code>xml.apache.org</code> <em>(host
          address)</em></li> 
        <li><strong>mountpoint:</strong> <code>forrest</code> <em>(projectname,
          hence no trailing slash!)</em></li> 
      </ul> 
      <p>Forrest will add slashes in-between if needed.</p> 
      <note>It is currently undefined how these parameters will be configured
        when running Forrest. This can be done using Ant-filtered copying of the
        sitemap, or using some to-be-created Cocoon CLIInputModule.</note>
    </section> 
    <section> 
      <title>Internal</title> 
      <p>Adding documents to your local documentation fileset means they will
        become available across Forrest too. There exists however a naming convention
        for a number of 'special' documents, which has to be taken into account.
        Furthermore, Forrest adds a number of autogenerated resources.</p>
      <section>
        <title><code> (empty URI)</code></title>
        <p>This URI is automatically redirected (server-side) to
          <code>index.xml</code>. It serves as the root of your documentation site.</p>
      </section>
      <section>
        <title><code>http://host/mountpoint/*.html</code></title>
      </section>
    </section> 
  </section> 
  <section> 
    <title>Media types</title> 
    <p>Forrest is able to explicitely process the following media types:</p> 
    <table> 
      <tr> 
        <th>Extension</th> 
        <th>Description</th> 
      </tr> 
      <tr> 
        <td>.html</td> 
        <td>Plain web pages (default rendition format)</td> 
      </tr> 
      <tr> 
        <td>.pdf</td> 
        <td>Acrobat files</td> 
      </tr> 
      <tr> 
        <td>.png</td> 
        <td>Portable Network Graphic files (preferred image format)</td> 
      </tr> 
      <tr> 
        <td>.gif</td> 
        <td>Compuserve GIF graphics</td> 
      </tr> 
      <tr> 
        <td>.jpg</td> 
        <td>JPEG graphics</td> 
      </tr> 
      <tr> 
        <td>.svg</td> 
        <td>Scalable Vector Graphics</td> 
      </tr> 
      <tr> 
        <td>.txt</td> 
        <td>plain text documents</td> 
      </tr> 
      <tr> 
        <td>.zip</td> 
        <td>compressed file archive</td> 
      </tr> 
      <tr> 
        <td>.tar</td> 
        <td>'tape' archives</td> 
      </tr> 
      <tr> 
        <td>.tar.gz</td> 
        <td>compressed tar file archives</td> 
      </tr> 
      <tr> 
        <td>.tar.bz2</td> 
        <td>compressed tar file archives</td> 
      </tr> 
      <tr> 
        <td>.jar</td> 
        <td>Java application archives</td> 
      </tr> 
      <tr> 
        <td>.war</td> 
        <td>Java web application archives</td> 
      </tr> 
      <tr> 
        <td>.ear</td> 
        <td>Java enterprise application archives</td> 
      </tr> 
      <tr> 
        <td>...</td> 
        <td>...</td> 
      </tr> 
    </table> 
  </section> 
  </body>
</document>
