src/documentation/content/xdocs/uri-namespace.xml - forrest - Git at Google

 <?xml version="1.0"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
 <document>
   <header>
     <title>URI namespace description</title>
     <subtitle>Background reading for the Forrest sitemap</subtitle>
     <authors><person name="Steven Noels" email="stevenn@apache.org"/></authors>
     <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://xml.apache.org/cocoon/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"?>
	<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
	<document>
	<header>
	<title>URI namespace description</title>
	<subtitle>Background reading for the Forrest sitemap</subtitle>
	<authors><person name="Steven Noels" email="stevenn@apache.org"/></authors>
	<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://xml.apache.org/cocoon/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>