<?xml version="1.0"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You 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>
