You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by st...@apache.org on 2002/11/12 11:53:44 UTC
cvs commit: xml-forrest/src/documentation/content/xdocs uri-namespace.xml
stevenn 2002/11/12 02:53:44
Added: src/documentation/content/xdocs uri-namespace.xml
Log:
something which has been laying around on my harddisk for much too long time
please expand!
Revision Changes Path
1.1 xml-forrest/src/documentation/content/xdocs/uri-namespace.xml
Index: uri-namespace.xml
===================================================================
<?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>