forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgard...@apache.org
Subject svn commit: r209833 - in /forrest/trunk/site-author: content/xdocs/docs_0_80/locationmap.xml content/xdocs/site.xml status.xml
Date Fri, 08 Jul 2005 16:08:50 GMT
Author: rgardler
Date: Fri Jul  8 09:08:48 2005
New Revision: 209833

URL: http://svn.apache.org/viewcvs?rev=209833&view=rev
Log:
Add some basic docs for the locationmap

Added:
    forrest/trunk/site-author/content/xdocs/docs_0_80/locationmap.xml   (with props)
Modified:
    forrest/trunk/site-author/content/xdocs/site.xml
    forrest/trunk/site-author/status.xml

Added: forrest/trunk/site-author/content/xdocs/docs_0_80/locationmap.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs_0_80/locationmap.xml?rev=209833&view=auto
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/locationmap.xml (added)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/locationmap.xml Fri Jul  8 09:08:48
2005
@@ -0,0 +1,189 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright 2002-2005 The Apache Software Foundation or its licensors,
+  as applicable.
+
+  Licensed 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 V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document> 
+  <header> 
+    <title>Locationmaps</title> 
+  </header> 
+  <body> 
+    <section id="overview">
+      <title>About Locationmaps</title>
+      <p>A locationmap defines a mapping from requests to location strings.</p>
+
+      <p>It was conceived to:</p>  
+
+      <ul>
+        <li>Provide a more powerful means for semantic linking.</li>
+        <li>Enable Forrest with a standard configuration override mechanism.</li>
+        <li>decouple the conceptual source space used by Cocoon from
+        the concrete source space, so that a change in the concrete sources
+        does not impact on the sitemap</li>
+      </ul>
+      
+      <p>In other words, the locationmap enables content to be retrieved from a location
+        that is defined in a locationmap file (located at 
+        <code>PROJECT_HOME/src/documentation/content/locationmap.xml</code> file.
The
+        advantage of this is that the URL seen by the user need bear no relation to the location
+        of the source document, thus Forrest can separate the client URL space from the source
+        docuement URL space. Thus, using the locationmap it is possible to pull together
+        documents from many different locations into a single uniform site.</p>
+        
+        <p>In addition, since the user URL space is now unconnected to the source URL
space
+        it is possible to move source documents without breaking any existing user links.</p>
+
+      <p>The syntax of a locationmap resembles that of the sitemap in that it also
makes use
+      of Matchers and Selectors to traverse a tree of nodes towards a leaf. In the case of
+      the locationmap however the leaf does not identify a pipeline but instead identifies
+      a location string.</p>
+      
+      <p>Apache Forrest looks in the standard location for the source file first (by
default
+      <code>PROJECT_HOME/src/documentation/content/xdocs/...</code>), if a file
is found in this
+      location then the locationmap is not consulted. However, if one is not found then the

+      locationmap is used to resolve the source file.</p>
+      
+    </section>
+    
+    <section id="examples">
+      <title>Locationmap Examples</title>
+      <section>
+        <title>Retrieving an XDoc via HTTP</title>
+        
+        
+        <p>Normally files are generated from <code>{project:content.xdocs}</code>.
+        Using the Locationmap it is possible to make these files come from elsewhere.
+        This is useful if you want to pull files from different directory structures,
+        or even remote repositories. For example, the following location match 
+        will match any request for a document delow "remoteDemo" and will retrieve
+        the source file from forrests SVN repository via the viewCVS interface. This
+        is an ideal way of ensuring your published docs are always up to date.</p>
       
+        
+        <source>
+ &lt;match pattern="remoteDemo/**.xml"&gt;
+   &lt;location src="http://svn.apache.org/viewcvs.cgi/*checkout*/forrest/trunk/site-author/content/xdocs/{1}.xml"
/&gt;
+ &lt;/match&gt;
+        </source>
+      
+        <p>Note that because this is a wildcard matcher you can request any page
+        from viewsSVN simply by requesting 
+        <code>/remoteDemo/PATH/TO/FILE/FILENAME.html</code>. In addition, we
+        can request any other output format available via Forrest plugins.</p>
+        
+        <p>When including resources from remote repositories one has to
+        be careful about things like <code>site</code> and <code>ext</code>
+        linking. If the targets are not defined in the local 
+        <code>site.xml</code> file then these links will be broken.</p>
+        
+        <warning>Because of the above limitation many of the links in the
+        page generated from the above example are broken.</warning>
+        
+      </section>
+
+      <section>
+        <title>Retrieving HTML from a CMS</title>
+        
+        <p>Using the locationmap you can use Forrest to retrieve data from a CMS, wither
local or remote.
+        As an example we will consider Apache Lenya.</p> 
+        
+        <p><a href="http://lenya.apache.org">Apache Lenya</a> is a Java
Open-Source Content Management System based 
+        on open standards such as XML and XSLT and the Apache Software Stack, in particular
the XML publishing 
+        framework Apache Cocoon.</p>
+        
+        <p>The following locationmap matcher will instruct Forrest to retrieve content
from
+        <code>http://lenya.zones.apache.org:8888/default/live/*.html?raw=true</code>,
whenever a local URL of
+        <code>lenya/**</code> is encountered.</p>
+        
+        <source>
+ &lt;match pattern="lenya/**.xml"&gt;
+   &lt;location src="http://lenya.zones.apache.org:8888/default/live/{1}.html?raw=true"
/&gt;
+ &lt;/match&gt;
+        </source>
+        
+        <p>However, since the source returned by this match is HTML and not XDoc we
must convert this
+        to our internal XDoc format before we can use it. We do this by adding the match
below to our 
+        projects <code>sitemap.xmap</code> file.</p>
+        
+        <source>
+&lt;map:match pattern="lenya/**.xml"&gt;
+  &lt;map:generate type="html" src="{lm:{0}}" /&gt;
+  &lt;map:transform src="{forrest:stylesheets}/html2document.xsl" /&gt;
+  &lt;map:serialize type="xml"/&gt;
+&lt;/map:match&gt;
+        </source>
+        
+        <p>Since this snippet uses the HTML generator you must also ensure that your
sitemap has the HTML generator
+        component defined. That is, your sitemap must also include:</p>
+        
+        <source>
+&lt;map:components&gt;
+  &lt;map:generators default="file"&gt;
+    &lt;map:generator name="html"
+      src="org.apache.cocoon.generation.HTMLGenerator"&gt;
+      &lt;jtidy-config&gt;WEB-INF/jtidy.properties&lt;/jtidy-config&gt;
+    &lt;/map:generator&gt;
+  &lt;/map:generators&gt;
+&lt;/map:components&gt;
+        </source>
+        
+        <p>Since the HTML generator uses JTidy we need to make available a JTidy configuration
file.
+        This is placed in <code>PROJECT_HOME/src/documentation/WEB-INF/jtidy.properties</code>
(the
+        location can be changed in the above sitemap snippet). A sample config file is given
below:</p>
+        
+        <source>
+indent=yes
+indent-spaces=8
+wrap=72
+markup=no
+output-xml=no
+input-xml=no
+show-warnings=yes
+numeric-entities=yes
+quote-marks=yes
+quote-nbsp=yes
+quote-ampersand=yes
+break-before-br=yes
+uppercase-tags=no
+uppercase-attributes=no
+char-encoding=latin1
+        </source>
+                
+        <note>This requirement to add items to your project sitemap will be removed
in a future version either by Lenya
+        outputting XDoc, by Forrest switching to using XHTML as its internal format or through
the development of a
+        plugin for Lenya that will include the necessary processing (whichever comes first).</note>
+                
+        <warning>This demo is an example only, it does not work fully work at this
time. For exammple, absolute URLs
+        in the source document need to be rewritten to ensure that they are matched by the
locationmap.</warning>
+        
+      </section>
+
+      <section>
+        <title>Link Rewriting</title>
+        <p>The locationmap can be used to rewrite URLs when the page is generated.
+        For example, when the locationmap has:</p>
+        <source>
+ &lt;match pattern="rewriteDemo/**"&gt;
+   &lt;location src="http://www.burrokeet.org/{1}.xml" /&gt;
+ &lt;/match&gt;
+        </source>
+        <p><a href="lm:rewriteDemo/index">This link leads is rewritten to
+        an offsite address</a> not
+        specified in the link, which has <code>href="lm:rewriteDemo/index"</code>.</p>
+      </section>
+
+    </section>
+  </body>
+</document>

Propchange: forrest/trunk/site-author/content/xdocs/docs_0_80/locationmap.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: forrest/trunk/site-author/content/xdocs/site.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/site.xml?rev=209833&r1=209832&r2=209833&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/site.xml (original)
+++ forrest/trunk/site-author/content/xdocs/site.xml Fri Jul  8 09:08:48 2005
@@ -190,6 +190,7 @@
           <new-skin href="#new_skin"/>
           <invoking_from_ant href="#invoking_from_ant"/>
         </your-project>
+        <locationmap label="Locationmap" href="locationmap.html"/>
         <validation label="XML Validation" href="validation.html"/>
         <linking label="Menus and Linking" href="linking.html">
           <menu_generation href="#menu_generation"/>

Modified: forrest/trunk/site-author/status.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/status.xml?rev=209833&r1=209832&r2=209833&view=diff
==============================================================================
--- forrest/trunk/site-author/status.xml (original)
+++ forrest/trunk/site-author/status.xml Fri Jul  8 09:08:48 2005
@@ -125,10 +125,25 @@
         </section>
       </notes>
 
-      <action dev="DC" type="add" context="docs">
+      <action dev="DC" type="add" context="docs" importance="high">
 <!-- Please keep this action at the top -->
         Added document to facilitate
         <link href="site:v0.80//upgrading_08">upgrading to v0.8</link>
+      </action>
+       
+      <action dev="RDG" type="add" context="code" importance="high">
+        Added support for a locationmap. This enables content to be retrieved from a location
+        that is defined in a locationmap file (located at 
+        <code>PROJECT_HOME/src/documentation/content/locationmap.xml</code> file.
The
+        advantage of this is that the URL seen by the user need bear no relation to the location
+        of the source document, thus Forrest can separate the client URL space from the source
+        docuement URL space. Thus, using the locationmap it is possible to pull together
+        documents from many different locations into a single uniform site.<br/>
+        
+        In addition, since the user URL space is now unconnected to the source URL space
+        it is possible to move source documents without breaking any existing user links.<br/>
+        
+        See <link href="site:v0.80//locationmap">locationmap docs</link> for
more information.
       </action>
       
     </release>



Mime
View raw message