site-author/content/xdocs/uri-namespace.xml - forrest - Git at Google

 <?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>
	<?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>