forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From stev...@apache.org
Subject cvs commit: xml-forrest/src/documentation/content/xdocs uri-namespace.xml
Date Tue, 12 Nov 2002 10:53:44 GMT
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>
  
  
  

Mime
View raw message