Since Forrest uses Cocoon as its documentation generation mechanism, it ships with a Cocoon sitemap 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.
Network protocol Currently, the only network protocol
that can be used to access Forrest resources is HTTP. Of
course, you can embed hypertext references to other protocols
(news:, mailto:, ...), but these links are
not processed by the crawler.
Host Forrest publishes its generated documentation on
some server, so part of the URI namespace is the host
address, i.e.
xml.apache.org,intranetsrv2 or
localhost.
Mountpoint Similar to so-called Java Web
Applications, a Forrest website URI is often prepended with a
mountpoint, indicating the root of the website shouldn't be
found on http://somehost/, but on
http://somehost/mountpoint/ instead. Declaring a
mountpoint is optional however.
Both host and mountpoint 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:
xml.apache.org(host
address)forrest(projectname,
hence no trailing slash!)Forrest will add slashes in-between if needed.
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.
This URI is automatically redirected (server-side) to
index.xml. It serves as the root of your documentation
site.
Forrest is able to explicitely process the following media types:
| Extension | Description |
|---|---|
| .html | Plain web pages (default rendition format) |
| Acrobat files | |
| .png | Portable Network Graphic files (preferred image format) |
| .gif | Compuserve GIF graphics |
| .jpg | JPEG graphics |
| .svg | Scalable Vector Graphics |
| .txt | plain text documents |
| .zip | compressed file archive |
| .tar | 'tape' archives |
| .tar.gz | compressed tar file archives |
| .tar.bz2 | compressed tar file archives |
| .jar | Java application archives |
| .war | Java web application archives |
| .ear | Java enterprise application archives |
| ... | ... |