You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by rg...@apache.org on 2005/07/08 18:08:50 UTC
svn commit: r209833 - in /forrest/trunk/site-author:
content/xdocs/docs_0_80/locationmap.xml content/xdocs/site.xml status.xml
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>
+ <match pattern="remoteDemo/**.xml">
+ <location src="http://svn.apache.org/viewcvs.cgi/*checkout*/forrest/trunk/site-author/content/xdocs/{1}.xml" />
+ </match>
+ </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>
+ <match pattern="lenya/**.xml">
+ <location src="http://lenya.zones.apache.org:8888/default/live/{1}.html?raw=true" />
+ </match>
+ </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>
+<map:match pattern="lenya/**.xml">
+ <map:generate type="html" src="{lm:{0}}" />
+ <map:transform src="{forrest:stylesheets}/html2document.xsl" />
+ <map:serialize type="xml"/>
+</map:match>
+ </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>
+<map:components>
+ <map:generators default="file">
+ <map:generator name="html"
+ src="org.apache.cocoon.generation.HTMLGenerator">
+ <jtidy-config>WEB-INF/jtidy.properties</jtidy-config>
+ </map:generator>
+ </map:generators>
+</map:components>
+ </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>
+ <match pattern="rewriteDemo/**">
+ <location src="http://www.burrokeet.org/{1}.xml" />
+ </match>
+ </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>