You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2007/04/10 05:48:57 UTC
svn commit: r527010 [8/26] - in /forrest/trunk/site-author/content: ./
skins/ xdocs/ xdocs/docs_0_70/ xdocs/docs_0_70/howto/
xdocs/docs_0_70/howto/bugzilla-patch/ xdocs/docs_0_70/howto/cvs-ssh/
xdocs/docs_0_70/howto/multi/ xdocs/docs_0_80/ xdocs/docs_0...
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/sitemap-ref.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/sitemap-ref.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/sitemap-ref.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/sitemap-ref.xml Mon Apr 9 20:48:52 2007
@@ -19,70 +19,66 @@
<!ENTITY s '<code>site.xml</code>'>
<!ENTITY linkrewriter '<link href="#linkrewriting_impl">linkrewriter</link>'>
]>
-
<document>
<header>
<title>Forrest Sitemap Reference</title>
</header>
<body>
<p>
- Technically, Forrest can be thought of as a
- <link href="ext:cocoon">Cocoon</link> distribution that has been stripped down
- and optimized for people with simple site publishing needs. Central to
- Cocoon, and hence Forrest, is the <strong>sitemap</strong>. The sitemap
+ Technically, Forrest can be thought of as a
+ <link href="ext:cocoon">Cocoon</link> distribution that has been stripped
+ down and optimized for people with simple site publishing needs. Central
+ to Cocoon, and hence Forrest, is the <strong>sitemap</strong>. The sitemap
defines the site's URI space (what pages are available), and how each page
- is constructed. Understanding the sitemap is the key to understanding
+ is constructed. Understanding the sitemap is the key to understanding
Forrest.
</p>
<note>
- We advise you to spend time to understand the Apache Cocoon sitemap.
- See <link href="ext:cocoon/sitemap">Cocoon sitemap</link>
- and <link href="ext:cocoon/concepts">Cocoon concepts</link>
- and related component documentation.
- The Forrest sitemap is broken into multiple files. The main one is
- <strong>sitemap.xmap</strong> which delegates to others.
+ We advise you to spend time to understand the Apache Cocoon sitemap. See
+ <link href="ext:cocoon/sitemap">Cocoon sitemap</link> and
+ <link href="ext:cocoon/concepts">Cocoon concepts</link> and related
+ component documentation. The Forrest sitemap is broken into multiple
+ files. The main one is <strong>sitemap.xmap</strong> which delegates to
+ others.
</note>
<p>
- This document provides an overview of the special sitemap which
- is used at the core of Apache Forrest.
+ This document provides an overview of the special sitemap which is used at
+ the core of Apache Forrest.
</p>
-
<section id="getting_started">
<title>Getting started</title>
<p>
Forrest's sitemap comprises the $FORREST_HOME/main/webapp/*.xmap files.
</p>
-
<p>
You can add pre-processing sitemaps to your project
<code>src/documentation</code> directory (or wherever
- <code>${project.sitemap-dir}</code> points to). Any match that
- is not handled, passes through to be handled by the default Forrest
- sitemaps - obviously extremely powerful. The capability is described
- in
- "<link href="site:v0.70//project-sitemap">Using project sitemaps</link>".
+ <code>${project.sitemap-dir}</code> points to). Any match that is not
+ handled, passes through to be handled by the default Forrest sitemaps -
+ obviously extremely powerful. The capability is described in
+ "<link href="site:v0.70//project-sitemap">Using project
+ sitemaps</link>".
</p>
-
<p>
Another way to experiment with the sitemap is to do '<code>forrest
- run</code>' on a Forrest-using site. Changes to the core
- <code>*.xmap</code> files will now be immediately visible
- at <code>>http://localhost:8888/</code>
+ run</code>' on a Forrest-using site. Changes to the core
+ <code>*.xmap</code> files will now be immediately visible at
+ <code>>http://localhost:8888/</code>
</p>
</section>
-
<section id="overview">
<title>Sitemap Overview</title>
<p>
- Forrest's sitemap is divided both physically and logically. The most
- obvious is the physical separation. There are a number of separate
- *.xmap files, each defining pipelines for a functional area. Each *.xmap
- file has its purpose documented in comments at the top. Here is a brief
+ Forrest's sitemap is divided both physically and logically. The most
+ obvious is the physical separation. There are a number of separate
+ *.xmap files, each defining pipelines for a functional area. Each *.xmap
+ file has its purpose documented in comments at the top. Here is a brief
overview of the files, in order of importance.
</p>
<table>
<tr>
- <th><strong>sitemap.xmap</strong></th>
+ <th><strong>sitemap.xmap</strong>
+ </th>
<td>Primary sitemap file, which delegates responsibility for serving
certain URIs to the others (technically called sub-sitemaps). More
about the structure of this file later.</td>
@@ -160,8 +156,7 @@
</tr>
</table>
</section>
-
- <!--
+<!--
<section>
<title>Logical structure</title>
<p>There are a few major groups of sitemap pipelines</p>
@@ -172,33 +167,31 @@
</dl>
</section>
-->
-
<section id="source_pipelines">
<title>Source pipelines (**.xml)</title>
<p>
Most *.xmap files (forrest, aggregate, faq, status, issues, revisions,
- dtd) define Source pipelines. Source pipelines define the content
- (body) XML for site pages. The input XML format can be any format
+ dtd) define Source pipelines. Source pipelines define the content (body)
+ XML for site pages. The input XML format can be any format
(document-v13, Docbook, RSS, FAQ, Howto) and from any source (local or
- remote). The output format is always Forrest's intermediate "document-v13"
- format.
+ remote). The output format is always Forrest's intermediate
+ "document-v13" format.
</p>
<p>
- Source pipelines always have a "<code>.xml</code>" extension.
- Thus,
+ Source pipelines always have a "<code>.xml</code>" extension. Thus,
<link href="index.xml">index.xml</link> gives you the XML source for the
- index page. Likewise, <link href="faq.xml">faq.xml</link> gives you XML
- for the FAQ (transformed from FAQ syntax), and
- <link href="changes.xml">changes.xml</link> returns XML from the status.xml file.
- Take any page, and replace its extension (<code>.html</code> or
- <code>.pdf</code>) with <code>.xml</code> and you'll have the Source
- XML.
+ index page. Likewise, <link href="faq.xml">faq.xml</link> gives you XML
+ for the FAQ (transformed from FAQ syntax), and
+ <link href="changes.xml">changes.xml</link> returns XML from the
+ status.xml file. Take any page, and replace its extension
+ (<code>.html</code> or <code>.pdf</code>) with <code>.xml</code> and
+ you'll have the Source XML.
</p>
<p>
This is quite powerful, because we now have an abstraction layer, or
"virtual filesystem", on which the rest of Forrest's sitemap can build.
Subsequent layers don't need to care whether the XML was obtained
- locally or remotely, or from what format. Wikis, RSS, FAQs and Docbook
+ locally or remotely, or from what format. Wikis, RSS, FAQs and Docbook
files are all processed identically from here on.
</p>
<source>
@@ -217,24 +210,31 @@
<p>
Most of the usual Source pipelines are defined in
<code>forrest.xmap</code> which is the default (fallback) handler for
- <code>**.xml</code> pages. The forrest.xmap uses the
- <link href="site:v0.70//cap">SourceTypeAction</link> to determine the type of XML
- it is processing, and converts it to document-v13 if necessary.
- </p>
- <p>For instance, say we are rendering <link href="site:v0.70//write-howto">a
- Howto document</link> called "howto-howto.xml". It contains this DOCTYPE
- declaration:</p>
+ <code>**.xml</code> pages. The forrest.xmap uses the
+ <link href="site:v0.70//cap">SourceTypeAction</link> to determine the
+ type of XML it is processing, and converts it to document-v13 if
+ necessary.
+ </p>
+ <p>
+ For instance, say we are rendering
+ <link href="site:v0.70//write-howto">a Howto document</link> called
+ "howto-howto.xml". It contains this DOCTYPE declaration:
+ </p>
<source>
<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.3//EN"
"http://forrest.apache.org/dtd/howto-v13.dtd"></source>
- <p>The SourceTypeAction sees this, and applies this transform to get it
- to document-v13:</p>
- <source><![CDATA[
+ <p>
+ The SourceTypeAction sees this, and applies this transform to get it
+ to document-v13:
+ </p>
+ <source>
+<![CDATA[
<map:when test="howto-v13">
<map:transform src="{forrest:forrest.stylesheets}/howto2document.xsl" />
</map:when>
- ]]></source>
- <!--
+ ]]>
+ </source>
+<!--
if we link to an intermediate .xml file, the CLI crawler tries
to fetch the @hrefs from it but they still have site: in them
which causes it to break
@@ -247,11 +247,14 @@
</section>
<section id="other_source">
<title>Other source pipelines</title>
- <p>As mentioned above, all non-core Source pipelines are distributed in
- independent <code>*.xmap</code> files. There is a block of
+ <p>
+ As mentioned above, all non-core Source pipelines are distributed in
+ independent <code>*.xmap</code> files. There is a block of
<code>sitemap.xmap</code> which simply delegates certain requests to
- these subsitemaps:</p>
- <source><![CDATA[
+ these subsitemaps:
+ </p>
+ <source>
+<![CDATA[
<!-- Body content -->
<map:match pattern="**.xml">
<map:match pattern="changes.xml">
@@ -278,36 +281,43 @@
<map:mount uri-prefix="" src="aggregate.xmap" check-reload="yes" />
</map:match>
....
- ....]]></source>
+ ....]]>
+ </source>
<section id="late_binding_pipelines">
<title>Late-binding pipelines</title>
<p>
One point of interest here is that the sub-sitemap is often not
specific about which URLs it handles, and relies on the caller (the
- section listed above) to only pass relevant requests to it. We term
- this "binding a URL" to a pipeline.</p>
- <p>For instance, the main pipeline in <code>faq.xmap</code> matches
+ section listed above) to only pass relevant requests to it. We term
+ this "binding a URL" to a pipeline.
+ </p>
+ <p>
+ For instance, the main pipeline in <code>faq.xmap</code> matches
<code>**.xml</code>, but only <code>**faq.xml</code> requests are
- sent to it.</p>
- <p>This "late binding" is useful, because the whole URL space is
+ sent to it.
+ </p>
+ <p>
+ This "late binding" is useful, because the whole URL space is
managed in <code>sitemap.xmap</code> and not spread over lots of
- *.xmap files. For instance, say you wish all <code>*.xml</code>
- inside a "<code>faq/</code>" directory to be processed as FAQs. Just
+ *.xmap files. For instance, say you wish all <code>*.xml</code>
+ inside a "<code>faq/</code>" directory to be processed as FAQs. Just
override <code>sitemap.xmap</code> and redefine the relevant source
- matcher:</p>
- <source><![CDATA[
+ matcher:
+ </p>
+ <source>
+<![CDATA[
<map:match pattern="**faq.xml">
<map:mount uri-prefix="" src="faq.xmap" check-reload="yes" />
- </map:match>]]></source>
+ </map:match>]]>
+ </source>
</section>
</section>
</section>
-
<section id="output_pipelines">
<title>Output pipelines</title>
<p>
To recap, we now have a <code>*.xml</code> pipeline defined for each
- page in the site, emitting standardized XML. These pipeline definitions
+ page in the site, emitting standardized XML. These pipeline definitions
are located in various *.xmap files, notably forrest.xmap
</p>
<p>
@@ -319,10 +329,11 @@
<p>
Easiest case first; PDFs don't require menus or headers, so we can
simply transform our intermediate format into XSL:FO, and from there
- to PDF. This is done by the following matcher in
+ to PDF. This is done by the following matcher in
<code>sitemap.xmap</code> ...
</p>
- <source><![CDATA[
+ <source>
+<![CDATA[
1 <map:match type="regexp" pattern="^(.*?)([^/]*).pdf$">
2 <map:generate src="cocoon:/{1}{2}.xml"/>
3 <map:transform type="xinclude"/>
@@ -333,7 +344,8 @@
8 </map:transform>
9 <map:serialize type="fo2pdf"/>
10 </map:match>
- ]]></source>
+ ]]>
+ </source>
<ol>
<li>The first line uses a matching regexp to break the URL into
directory <code>(.*?)</code> and filename
@@ -345,14 +357,18 @@
<li>and finally apply the document2fo.xsl stylesheet, to generate
XSL:FO XML.</li>
</ol>
- <p>Lastly, we generate a PDF using the fo2pdf serializer.</p>
+ <p>
+ Lastly, we generate a PDF using the fo2pdf serializer.
+ </p>
</section>
<section id="html">
<title>HTML output</title>
- <p>Generating HTML pages is more complicated, because we have to merge
+ <p>
+ Generating HTML pages is more complicated, because we have to merge
the page body with a menu and tabs, and then add a header and footer.
- Here is the <code>*.html</code> matcher in
- <code>sitemap.xmap</code> ...</p>
+ Here is the <code>*.html</code> matcher in <code>sitemap.xmap</code>
+ ...
+ </p>
<source>
<map:match pattern="*.html">
<map:aggregate element="site">
@@ -369,9 +385,9 @@
<p>
So <link href="index.html">index.html</link> is formed from
aggregating <link href="body-index.html">body-index.html</link> and
- <link href="menu-index.html">menu-index.html</link> and
- <link href="tab-index.html">tab-index.html</link> and then applying the
- <code>site2xhtml.xsl</code> stylesheet to the result.
+ <link href="menu-index.html">menu-index.html</link> and
+ <link href="tab-index.html">tab-index.html</link> and then applying
+ the <code>site2xhtml.xsl</code> stylesheet to the result.
</p>
<p>
There is a nearly identical matcher for HTML files in subdirectories:
@@ -400,8 +416,11 @@
<title>Intermediate pipelines</title>
<section id="body_pipeline">
<title>Page body</title>
- <p>Here is the matcher which generates the page body:</p>
- <source><![CDATA[
+ <p>
+ Here is the matcher which generates the page body:
+ </p>
+ <source>
+<![CDATA[
1 <map:match pattern="**body-*.html">
2 <map:generate src="cocoon:/{1}{2}.xml"/>
3 <map:transform type="idgen"/>
@@ -413,32 +432,37 @@
9 <map:parameter name="notoc" value="false"/>
10 </map:call>
11 </map:match>
- ]]></source>
+ ]]>
+ </source>
<ol>
<li>In our matcher pattern, {1} will be the directory (if any) and {2}
will be the filename.</li>
<li>First, we obtain XML content from a source pipeline</li>
- <li>
- <p>We then apply a custom-written
+ <li><p>
+ We then apply a custom-written
<code>IdGeneratorTransformer</code>, which ensures that every
- <section> has an "id" attribute if one is not supplied, by generating one from the
- <title> if necessary. For example, <idgen> will
- transform:</p>
+ <section> has an "id" attribute if one is not supplied, by
+ generating one from the <title> if necessary. For example,
+ <idgen> will transform:
+ </p>
<source>
<section>
<title>How to boil eggs</title>
...
</source>
- <p>into:</p>
+ <p>
+ into:
+ </p>
<source>
<section id="How+to+boil+eggs">
<title>How to boil eggs</title>
...
</source>
- <p>Later, the <code>document2html.xsl</code> stylesheet will create
+ <p>
+ Later, the <code>document2html.xsl</code> stylesheet will create
an <a name> element for every section, allowing this section to
- be referred to as <code>index.html#How+to+boil+eggs</code>.</p>
- </li>
+ be referred to as <code>index.html#How+to+boil+eggs</code>.
+ </p></li>
<li>We then expand XInclude elements.</li>
<li>and <link href="#linkrewriting_impl">rewrite links</link>..</li>
<li>and then finally apply the stylesheet that generates a fragment of
@@ -448,8 +472,12 @@
</section>
<section id="menu_pipeline">
<title>Page menu</title>
- <p>In the <code>sitemap.xmap</code> file, the matcher generating HTML for the menu is:</p>
- <source><![CDATA[
+ <p>
+ In the <code>sitemap.xmap</code> file, the matcher generating HTML for
+ the menu is:
+ </p>
+ <source>
+<![CDATA[
<map:match pattern="**menu-*.html">
<map:generate src="cocoon:/{1}book-{2}.html"/>
<map:transform type="]]>&linkrewriter;<![CDATA[" src="cocoon:/{1}linkmap-{2}.html"/>
@@ -458,19 +486,26 @@
<map:parameter name="path" value="{1}{2}.html"/>
</map:call>
</map:match>
- ]]></source>
- <p>We get XML from a "book" pipeline,
- <link href="#linkrewriting_impl">rewrite links</link>, and apply the
- <code>book2menu.xsl</code> stylesheet to generate HTML.</p>
- <p>How the menu XML is actually generated (the *book-*.html pipeline) is
- sufficiently complex to require a
- <link href="#menu_xml_generation">section of its own</link>.</p>
+ ]]>
+ </source>
+ <p>
+ We get XML from a "book" pipeline,
+ <link href="#linkrewriting_impl">rewrite links</link>, and apply the
+ <code>book2menu.xsl</code> stylesheet to generate HTML.
+ </p>
+ <p>
+ How the menu XML is actually generated (the *book-*.html pipeline) is
+ sufficiently complex to require a
+ <link href="#menu_xml_generation">section of its own</link>.
+ </p>
</section>
-
<section id="tab_pipeline">
<title>Page tabs</title>
- <p>Tab generation is quite tame compared to menus:</p>
- <source><![CDATA[
+ <p>
+ Tab generation is quite tame compared to menus:
+ </p>
+ <source>
+<![CDATA[
<map:match pattern="**tab-*.html">
<map:generate src="content/xdocs/tabs.xml" />
<map:transform type="]]>&linkrewriter;<![CDATA[" src="cocoon:/{1}linkmap-{2}.html"/>
@@ -479,37 +514,47 @@
<map:parameter name="path" value="{1}{2}.html"/>
</map:call>
</map:match>
- ]]></source>
- <p>All the smarts are in the <code>tab2menu.xsl</code> stylesheet, which
- needs to choose the correct tab based on the current path. Currently,
- a "longest matching path" algorithm is implemented. See the
- <code>tab2menu.xsl</code> stylesheet for details.</p>
+ ]]>
+ </source>
+ <p>
+ All the smarts are in the <code>tab2menu.xsl</code> stylesheet, which
+ needs to choose the correct tab based on the current path. Currently,
+ a "longest matching path" algorithm is implemented. See the
+ <code>tab2menu.xsl</code> stylesheet for details.
+ </p>
</section>
</section>
-
<section id="menu_xml_generation">
<title>Menu XML generation</title>
- <p>The "book" pipeline is defined in <code>sitemap.xmap</code>as:</p>
- <source><![CDATA[
+ <p>
+ The "book" pipeline is defined in <code>sitemap.xmap</code>as:
+ </p>
+ <source>
+<![CDATA[
<map:match pattern="**book-*.html">
<map:mount uri-prefix="" src="menu.xmap" check-reload="yes" />
</map:match>
- ]]></source>
- <p>Meaning that it is defined in the <code>menu.xmap</code> file. In there we find
- the real definition, which is quite complicated, because there are three
- supported menu systems (see <link href="site:v0.70//linking">menus and
- linking</link>). We will not go through the sitemap itself
- (menu.xmap), but will instead describe the logical steps involved:</p>
+ ]]>
+ </source>
+ <p>
+ Meaning that it is defined in the <code>menu.xmap</code> file. In there
+ we find the real definition, which is quite complicated, because there
+ are three supported menu systems (see
+ <link href="site:v0.70//linking">menus and linking</link>). We will not
+ go through the sitemap itself (menu.xmap), but will instead describe the
+ logical steps involved:
+ </p>
<ol>
<li>Take site.xml and expand hrefs so that they are all
root-relative.</li>
- <li><p>Depending on the <code>forrest.menu-scheme</code> property, we
- now apply one of the two algorithms for choosing a set of menu links
+ <li><p>
+ Depending on the <code>forrest.menu-scheme</code> property, we now
+ apply one of the two algorithms for choosing a set of menu links
(described in <link href="site:v0.70//menu_generation">menu
- generation</link>):</p>
+ generation</link>):
+ </p>
<ul>
- <li>
- <p>
+ <li><p>
For "@tab" menu generation, we first ensure each site.xml node
has a tab attribute (inherited from a parent if necessary), and
then pass through nodes whose tab attribute matches that of the
@@ -517,10 +562,10 @@
</p>
<p>
For example, say our current page's path is
- <code>community/howto/index.html</code>. In
+ <code>community/howto/index.html</code>. In
<code>site.xml</code> we look for the node with this
- "<code>href</code>" and discover its "<code>tab</code>" attribute
- value is "<code>howtos</code>". We then prune the
+ "<code>href</code>" and discover its "<code>tab</code>"
+ attribute value is "<code>howtos</code>". We then prune the
<code>site.xml</code>-derived content to contain only nodes with
<code>tab="howtos"</code>.
</p>
@@ -528,34 +573,38 @@
All this is done with XSLT, so the sitemap snippet does not
reveal this complexity:
</p>
- <source><![CDATA[
+ <source>
+<![CDATA[
<map:transform src="resources/stylesheets/site2site-normalizetabs.xsl" />
<map:transform src="resources/stylesheets/site2site-selectnode.xsl">
<map:parameter name="path" value="{1}{2}"/>
</map:transform>
- ]]></source>
- </li>
- <li>
- <p>For "directory" menu generation, we simply use an
+ ]]>
+ </source></li>
+ <li><p>
+ For "directory" menu generation, we simply use an
<code>XPathTransformer</code> to include only pages in the
- current page's directory, or below:</p>
- <source><![CDATA[
+ current page's directory, or below:
+ </p>
+ <source>
+<![CDATA[
<map:transform type="xpath">
<map:parameter name="include" value="//*[@href='{1}']" />
</map:transform>
- ]]></source>
+ ]]>
+ </source>
<p>
- Here, the "<code>{1}</code>" is the directory part of the current
- page. So if our current page is
- <code>community/howto/index.html</code> then "<code>{1}</code>" will
- be <code>community/howto/</code> and the transformer will
+ Here, the "<code>{1}</code>" is the directory part of the
+ current page. So if our current page is
+ <code>community/howto/index.html</code> then "<code>{1}</code>"
+ will be <code>community/howto/</code> and the transformer will
include all nodes in that directory.
- </p>
- </li>
+ </p></li>
</ul>
- <p>We now have a <code>site.xml</code> subset relevant to our current
- page.</p>
- </li>
+ <p>
+ We now have a <code>site.xml</code> subset relevant to our current
+ page.
+ </p></li>
<li>The "<code>href</code>" nodes in this are then made relative to the
current page.</li>
<li>The XML is then transformed into a legacy "<code>book.xml</code>"
@@ -564,48 +613,51 @@
<code>**book-*.html</code>).</li>
</ol>
</section>
-
<section id="linkrewriting_impl">
<title>Link rewriting</title>
- <p>In numerous places in <code>sitemap.xmap</code> you will see the
- "linkrewriter" transformer in action. For example:</p>
- <source><![CDATA[<map:transform type="linkrewriter" src="cocoon:/{1}linkmap-{2}.html"/>]]></source>
- <p>This statement is Cocoon's linking system in action. A full
- description is provided in <link href="site:v0.70//linking">Menus and
- Linking</link>. Here we describe the implementation of linking.</p>
+ <p>
+ In numerous places in <code>sitemap.xmap</code> you will see the
+ "linkrewriter" transformer in action. For example:
+ </p>
+ <source>
+<![CDATA[<map:transform type="linkrewriter" src="cocoon:/{1}linkmap-{2}.html"/>]]>
+ </source>
+ <p>
+ This statement is Cocoon's linking system in action. A full description
+ is provided in <link href="site:v0.70//linking">Menus and
+ Linking</link>. Here we describe the implementation of linking.
+ </p>
<section id="input_modules">
<title>Cocoon foundations: Input Modules</title>
<p>
The implementation of <code>site:</code> linking is heavily based on
Cocoon <link href="ext:cocoon/input-modules">Input Modules</link>, a
- little-known but quite powerful aspect of Cocoon. Input Modules are
+ little-known but quite powerful aspect of Cocoon. Input Modules are
generic Components which simply allow you to look up a value with a
- key. The value is generally dynamically generated, or obtained by
+ key. The value is generally dynamically generated, or obtained by
querying an underlying data source.
</p>
<p>
In particular, Cocoon contains an <code>XMLFileModule</code>, which
lets one look up the value of an XML node, by interpreting the key as
- an XPath expression. Cocoon also has a
+ an XPath expression. Cocoon also has a
<code>SimpleMappingMetaModule</code>, which allows the key to be
rewritten before it is used to look up a value.
</p>
<p>
The idea for putting these together to rewrite "<code>site:</code>"
links was described in <link href="ext:inputmoduletransformer">this
- thread</link>. The idea is to write a Cocoon Transformer that
- triggers on encountering <link
- href="<code>scheme:address</code>">, and interprets the
- <code>scheme:address</code> internal URI as
- <code>inputmodule:key</code>. The transformer then uses the named
+ thread</link>. The idea is to write a Cocoon Transformer that triggers
+ on encountering <link href="<code>scheme:address</code>">, and
+ interprets the <code>scheme:address</code> internal URI as
+ <code>inputmodule:key</code>. The transformer then uses the named
InputModule to look up the key value. The <code>scheme:address</code>
- URI is then rewritten with the found value. This transformer was
- implemented as
+ URI is then rewritten with the found value. This transformer was
+ implemented as
<link href="ext:linkrewritertransformer">LinkRewriterTransformer</link>,
currently distributed as a "block" in Cocoon 2.1
</p>
</section>
-
<section id="implement_rewriting">
<title>Implementing "<code>site:</code>" rewriting</title>
<p>
@@ -614,8 +666,11 @@
</p>
<section id="cocoon_xconf">
<title>cocoon.xconf</title>
- <p>First, we declare all the input modules we will be needing:</p>
- <source><![CDATA[
+ <p>
+ First, we declare all the input modules we will be needing:
+ </p>
+ <source>
+<![CDATA[
<!-- For the site: scheme -->
<component-instance
class="org.apache.cocoon.components.modules.input.XMLFileModule"
@@ -630,25 +685,25 @@
<component-instance
class="org.apache.cocoon.components.modules.input.SimpleMappingMetaModule"
logger="core.modules.mapper" name="ext"/>
-]]></source>
+]]>
+ </source>
<ul>
<li><strong>linkmap</strong> will provide access to the contents of
&s;; for example, <code>linkmap:/site/about/index/@href</code>
would return the value "index.html".</li>
<li><strong>site</strong> provides a "mask" over
<strong>linkmap</strong> such that <code>site:index</code> expands
- to <code>linkmap:/site//index/@href</code>
- </li>
+ to <code>linkmap:/site//index/@href</code></li>
<li><strong>ext</strong> provides another "mask" over
<strong>linkmap</strong>, such that <code>ext:ant</code> would
- expand to <code>linkmap:/site/external-refs//ant/@href</code>
- </li>
+ expand to <code>linkmap:/site/external-refs//ant/@href</code></li>
</ul>
- <p>However at the moment, we have only declared the input modules.
- They will be configured in <code>sitemap.xmap</code> as described in
- the next section.</p>
+ <p>
+ However at the moment, we have only declared the input modules. They
+ will be configured in <code>sitemap.xmap</code> as described in the
+ next section.
+ </p>
</section>
-
<section id="sitemap">
<title>sitemap.xmap</title>
<p>
@@ -656,7 +711,8 @@
insert it into any pipelines which deal with user-editable XML
content:
</p>
- <source><![CDATA[
+ <source>
+<![CDATA[
....
<!-- Rewrites links, e.g. transforming
href="site:index" to href="../index.html"
@@ -690,44 +746,56 @@
<map:transform type="xinclude"/>
<map:transform type="linkrewriter" src="cocoon:/{1}linkmap-{2}.html"/>
...
-</map:match>]]></source>
- <p>As you can see, our three input modules are configured as part of
- the LinkRewriterTransformer's configuration.</p>
+</map:match>]]>
+ </source>
+ <p>
+ As you can see, our three input modules are configured as part of
+ the LinkRewriterTransformer's configuration.
+ </p>
<ul>
- <li>
- <p>Most deeply nested, we have:</p>
- <source><![CDATA[
+ <li><p>
+ Most deeply nested, we have:
+ </p>
+ <source>
+<![CDATA[
<input-module name="linkmap">
<file src="{src}" reloadable="false" />
- </input-module>]]></source>
- <p>The "<code>{src}</code>" text is expanded to the value of the
+ </input-module>]]>
+ </source>
+ <p>
+ The "<code>{src}</code>" text is expanded to the value of the
"<code>src</code>" attribute in the "<code>linkrewriter</code>"
- instance, namely "<code>cocoon:/{1}linkmap-{2}.html</code>"
- Thus the <code>linkmap</code> module reads dynamically
- generated XML specific to the current request.</p>
- </li>
- <li>
- <p>One level out, we configure the "<code>site</code>" and
+ instance, namely "<code>cocoon:/{1}linkmap-{2}.html</code>" Thus
+ the <code>linkmap</code> module reads dynamically generated XML
+ specific to the current request.
+ </p></li>
+ <li><p>
+ One level out, we configure the "<code>site</code>" and
"<code>ext</code>" input modules, to map onto our dynamically
- configured "<code>linkmap</code>" module.</p>
- </li>
- <li>
- <p>Then at the outermost level, we configure the
- "<code>linkrewriter</code>" transformer. First we tell it which
- attributes to consider rewriting:</p>
- <source><![CDATA[
+ configured "<code>linkmap</code>" module.
+ </p></li>
+ <li><p>
+ Then at the outermost level, we configure the
+ "<code>linkrewriter</code>" transformer. First we tell it which
+ attributes to consider rewriting:
+ </p>
+ <source>
+<![CDATA[
<link-attrs>href src</link-attrs>
- <schemes>site ext</schemes>]]></source>
- <p>So, "<code>href</code>" and "<code>src</code>" attributes starting
- with "<code>site:</code>" or "<code>ext:</code>" are rewritten.</p>
-
- <p>By nesting the "<code>site</code>" and "<code>ext</code>" input
- modules in the "<code>linkrewriter</code>" configuration, we tell
- "<code>linkrewriter</code>" to use these two input modules when
- rewriting links.</p>
- </li>
+ <schemes>site ext</schemes>]]>
+ </source>
+ <p>
+ So, "<code>href</code>" and "<code>src</code>" attributes
+ starting with "<code>site:</code>" or "<code>ext:</code>" are
+ rewritten.
+ </p>
+ <p>
+ By nesting the "<code>site</code>" and "<code>ext</code>" input
+ modules in the "<code>linkrewriter</code>" configuration, we
+ tell "<code>linkrewriter</code>" to use these two input modules
+ when rewriting links.
+ </p></li>
</ul>
-
<p>
The end result is that, for example, the source XML for the
<code>community/body-index.html</code> page has its links rewritten
@@ -739,13 +807,14 @@
<title>Dynamically generating a linkmap</title>
<p>
Why do we need this "linkmap" pipeline generating dynamic XML from
- &s;, instead of just using &s; directly? The reasons are described
+ &s;, instead of just using &s; directly? The reasons are described
in <link href="ext:linkmaps">the linkmap RT</link>: we need to
concatenate @hrefs and add dot-dots to the paths, depending on which
- directory the linkee is in. This is done with the following
+ directory the linkee is in. This is done with the following
pipelines in <code>linkmap.xmap</code> ...
</p>
- <source><![CDATA[
+ <source>
+<![CDATA[
<!-- site.xml with @href's appended to be context-relative. -->
<map:match pattern="abs-linkmap">
<map:generate src="content/xdocs/site.xml" />
@@ -762,9 +831,11 @@
</map:transform>
<map:serialize type="xml" />
</map:match>
- ]]></source>
- <p>You can try these URIs out directly on a live Forrest to see what
- is going on (for example, Forrest's own
+ ]]>
+ </source>
+ <p>
+ You can try these URIs out directly on a live Forrest to see what is
+ going on (for example, Forrest's own
<link href="../abs-linkmap">abs-linkmap</link>).
</p>
</section>
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/skin-package.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/skin-package.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/skin-package.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/skin-package.xml Mon Apr 9 20:48:52 2007
@@ -18,61 +18,50 @@
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd" [
]>
-
<document>
<header>
<title>Skin packaging, provision, and use</title>
<subtitle>Automated distributed skin packages</subtitle>
</header>
-
<body>
<section id="overview">
<title>Overview</title>
<p>
-Skins are standard zip archives with a *.zip extension.
-This enables them to be unpacked and installed automatically.
+ Skins are standard zip archives with a *.zip extension. This enables
+ them to be unpacked and installed automatically.
</p>
-
<p>
-To publish a skin:
+ To publish a skin:
</p>
-
-<source>
+ <source>
1 - forrest package-skin
The skin package will be made in the skin dir, next to the custom skin.
2 - place the file in a directory on a web server
3 - ask forrest-dev to add the url and the skin name to the list of skins
</source>
-
-
<p>
-To use a custom skin with automatic download:
+ To use a custom skin with automatic download:
</p>
-
-<source>
+ <source>
1 - set the skin property in forrest.properties to the name of the skin
2 - forrest install-skin
3 - forrest
</source>
-
<p>
-Currently there are two test skins: "testskin" and "testskin2"
+ Currently there are two test skins: "testskin" and "testskin2"
</p>
-
<p>
-To see the names of the remote skins:
+ To see the names of the remote skins:
</p>
-
-<source>forrest available-skins</source>
+ <source>forrest available-skins</source>
</section>
-
<section id="notes">
<title>Notes</title>
<p>
-The skin will get blown away by the next 'build clean' in forrest.
-But that is okay because it is so quick to go get another copy. Also it
-may be preferable to get a fresh copy. If the user wanted to keep
-the skin and perhaps enhance it, then they can copy it to their project.
+ The skin will get blown away by the next 'build clean' in forrest. But
+ that is okay because it is so quick to go get another copy. Also it may
+ be preferable to get a fresh copy. If the user wanted to keep the skin
+ and perhaps enhance it, then they can copy it to their project.
</p>
</section>
</body>
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/skins.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/skins.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/skins.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/skins.xml Mon Apr 9 20:48:52 2007
@@ -29,104 +29,95 @@
many capabilities so that extra skins are not needed.
</p>
<p>
- Note that the new Dispatcher capability in future versions of
- Forrest will be a better solution.
+ Note that the new Dispatcher capability in future versions of Forrest
+ will be a better solution.
</p>
</section>
-
<section id="names">
<title>Convention for choosing skin names</title>
<p>
The skin names are based on playing with the word "skin". See our
technique for
- <a href="http://svn.apache.org/repos/asf/forrest/trunk/main/webapp/skins/new-skin-names.txt">choosing skin names</a>.
- A name with "-dev" extension signifies that it is under development.
- There is no concept of versions of default skins.
- New skins have new names.
+ <a href="http://svn.apache.org/repos/asf/forrest/trunk/main/webapp/skins/new-skin-names.txt">choosing
+ skin names</a>. A name with "-dev" extension signifies that it is under
+ development. There is no concept of versions of default skins. New skins
+ have new names.
</p>
</section>
-
<section id="skins">
<title>Skin descriptions and examples</title>
-
<section id="pelt">
<title>pelt</title>
<p>
Uses CSS "div" and no HTML tables.
</p>
- <p>Examples:
- <a href="site:forrest">Apache Forrest</a> |
+ <p>
+ Examples: <a href="site:forrest">Apache Forrest</a> |
<a href="ext:lenya">Apache Lenya</a>
</p>
</section>
-
<section id="tigris">
<title>tigris</title>
<p>
- This skin is based on version 1.1 of the
- <a href="http://style.tigris.org/">style.tigris.org</a> project.
- (It deliberately contravenes our skin naming convention.)
+ This skin is based on version 1.1 of the
+ <a href="http://style.tigris.org/">style.tigris.org</a> project. (It
+ deliberately contravenes our skin naming convention.)
</p>
- <p>Examples:
- <a href="http://www.core.gen.tr/">Core Computer Security Group</a>
+ <p>
+ Examples: <a href="http://www.core.gen.tr/">Core Computer Security
+ Group</a>
</p>
</section>
-
<section id="plain-dev">
<title>plain-dev</title>
<p>
- This is a very minimal skin to produce plain HTML documents.
- Such capability might be useful to generate a collection of
- documents for some off-line product's user help system.
- </p>
-
- <p>Examples:
- <a href="images/snapshot-plain-dev.png">snapshot</a>
+ This is a very minimal skin to produce plain HTML documents. Such
+ capability might be useful to generate a collection of documents for
+ some off-line product's user help system.
+ </p>
+ <p>
+ Examples: <a href="images/snapshot-plain-dev.png">snapshot</a>
</p>
</section>
</section>
-
<section id="old">
<title>Old and deprecated skins</title>
<p>
The following skins are retained for a little while longer, but are
deprecated, so please move to one of the other skins.
</p>
-
<section id="forrest-site">
<title>forrest-site</title>
<p>
This is the old skin that we have been dragging around since early
days. Uses HTML tables.
</p>
- <p>Examples:
- <a href="ext:xml.apache.org">Apache XML</a>
+ <p>
+ Examples: <a href="ext:xml.apache.org">Apache XML</a>
</p>
</section>
-
<section id="krysalis-site">
<title>krysalis-site</title>
<p>
Uses HTML tables.
</p>
-
- <p>Examples:
+ <p>
+ Examples:
</p>
</section>
-
<section id="view">
<title>view/viewHelper</title>
<p>
- This is the evolution of the "leather-dev" skin, to have contracts.
- It allows the user to provide their own implementations of contracts.
- The view is controlled by a config file that is easy to understand.
- It is still in development. Note: you need to have both plugins installed.
+ This is the evolution of the "leather-dev" skin, to have contracts. It
+ allows the user to provide their own implementations of contracts. The
+ view is controlled by a config file that is easy to understand. It is
+ still in development. Note: you need to have both plugins installed.
</p>
<note>
This is now out-of-date. See the new Dispatcher.
</note>
- <p>Examples:
- <a href="images/snapshot-view-viewHelper.png">snapshot</a>
+ <p>
+ Examples: <a href="images/snapshot-view-viewHelper.png">snapshot</a>
</p>
</section>
</section>
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/tab-index.fv
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/tab-index.fv?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/tab-index.fv (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/tab-index.fv Mon Apr 9 20:48:52 2007
@@ -17,7 +17,7 @@
-->
<forrest:views xmlns:forrest="http://apache.org/forrest/templates/1.0"
xmlns:jx="http://apache.org/cocoon/templates/jx/1.0">
- <!-- The following variables are used to contact data models and/or contracts. -->
+<!-- The following variables are used to contact data models and/or contracts. -->
<jx:set var="getRequest" value="#{$cocoon/parameters/getRequest}"/>
<forrest:view type="html" hooksXpath="/">
<forrest:contract name="genericMarkup">
@@ -27,4 +27,4 @@
</forrest:property>
</forrest:contract>
</forrest:view>
-</forrest:views>
\ No newline at end of file
+</forrest:views>
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/upgrading_07.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/upgrading_07.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/upgrading_07.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/upgrading_07.xml Mon Apr 9 20:48:52 2007
@@ -16,34 +16,31 @@
limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
-<document>
- <header>
- <title>Upgrading to Apache Forrest 0.7</title>
- </header>
- <body>
+<document>
+ <header>
+ <title>Upgrading to Apache Forrest 0.7</title>
+ </header>
+ <body>
<section id="introduction">
<title>Introduction</title>
<p>
- This page describes some changes to Apache Forrest that affect people who are
- upgrading to the 0.7 version.
- If you have other issues, then please discuss on either the
- <a href="site:mail-lists/forrest-dev">dev</a> or
- <a href="site:mail-lists/forrest-user">user</a>
- mailing lists.
- As more experience is gained, this document will be updated.
+ This page describes some changes to Apache Forrest that affect people
+ who are upgrading to the 0.7 version. If you have other issues, then
+ please discuss on either the
+ <a href="site:mail-lists/forrest-dev">dev</a> or
+ <a href="site:mail-lists/forrest-user">user</a> mailing lists. As more
+ experience is gained, this document will be updated.
</p>
<p>
- (If you are upgrading from a version prior to 0.6 then you will need
- to see the notes for the previous upgrade.)
+ (If you are upgrading from a version prior to 0.6 then you will need to
+ see the notes for the previous upgrade.)
</p>
</section>
-
<section id="new">
<title>New Features</title>
<p>
- The following list shows some of the key new features
- (for the full list of changes, see the
- <a href="site:changes">change log</a>).
+ The following list shows some of the key new features (for the full list
+ of changes, see the <a href="site:changes">change log</a>).
</p>
<ul>
<li>Plugin architecture</li>
@@ -54,104 +51,95 @@
forrest.properties and skinconf.xml with that of your project.
</p>
</section>
-
<section id="clean">
<title>Run a clean target after upgrade</title>
<p>
- Do 'forrest clean-work' in each of your projects. This also removes
- the old Cocoon disk cache.
+ Do 'forrest clean-work' in each of your projects. This also removes the
+ old Cocoon disk cache.
</p>
</section>
-
<section id="home">
<title>New location of $FORREST_HOME</title>
<p>
- $FORREST_HOME is now the top-level of the distribution.
- Also make sure $PATH gets updated to use the new $FORREST_HOME/bin
+ $FORREST_HOME is now the top-level of the distribution. Also make sure
+ $PATH gets updated to use the new $FORREST_HOME/bin
</p>
</section>
-
<section id="jdk14">
<title>Java 1.4 (or newer) is required</title>
- <p>Java 1.4 (or newer) is required, starting with this Forrest 0.7 version.
- For further information, see <a href="site:v0.70//faq/requirements">FAQ</a>.
+ <p>
+ Java 1.4 (or newer) is required, starting with this Forrest 0.7 version.
+ For further information, see
+ <a href="site:v0.70//faq/requirements">FAQ</a>.
</p>
</section>
-
<section id="tips">
<title>General upgrade tips</title>
<p>
- Synchronise your project's skinconf.xml and forrest.properties files.
+ Synchronise your project's skinconf.xml and forrest.properties files.
</p>
<p>
- Take advantage of the separation of concerns. In a new workspace,
- create a fresh
- '<code>forrest seed</code>' site, then tweak its forrest.properties
- and skinconf.xml until it reflects your old site.
- When it is ready, replace your project's skinconf.xml and
- forrest.properties files.
- Any remaining issues would concern other aspects of your configuration,
- such as site.xml and your actual content.
+ Take advantage of the separation of concerns. In a new workspace, create
+ a fresh '<code>forrest seed</code>' site, then tweak its
+ forrest.properties and skinconf.xml until it reflects your old site.
+ When it is ready, replace your project's skinconf.xml and
+ forrest.properties files. Any remaining issues would concern other
+ aspects of your configuration, such as site.xml and your actual content.
</p>
</section>
-
<section id="plugin">
<title>Plugin architecture</title>
<p>
- See
- <a href="site:plugins/infrastructure">Plugin Infrastructure</a>
- and
- <a href="site:plugins/using">Extending Forrest with Plugins</a>
- and for developing new plugins see
- <a href="site:v0.70//howto/buildPlugin">How to Build a Plugin</a>.
- See the list of
- <a href="site:plugins/index">current plugins</a>
- and their documentation.
+ See <a href="site:plugins/infrastructure">Plugin Infrastructure</a> and
+ <a href="site:plugins/using">Extending Forrest with Plugins</a> and for
+ developing new plugins see <a href="site:v0.70//howto/buildPlugin">How
+ to Build a Plugin</a>. See the list of
+ <a href="site:plugins/index">current plugins</a> and their
+ documentation.
</p>
<p>
Note that other experimental plugins can be found in the
"whiteboard/plugins" directory.
</p>
</section>
-
<section id="configure-plugin">
<title>Configure plugins</title>
<p>
- Some functionality has been moved out of the forrest core and into
- plugins. You will need to declare any plugins that are used by
- your project, e.g. if you use projectInfo (status, changes, todo)
- and PDF output, then declare the following in forrest.properties
+ Some functionality has been moved out of the forrest core and into
+ plugins. You will need to declare any plugins that are used by your
+ project, e.g. if you use projectInfo (status, changes, todo) and PDF
+ output, then declare the following in forrest.properties
</p>
<source>
project.required.plugins=org.apache.forrest.plugin.input.projectInfo,org.apache.forrest.plugin.output.pdf
</source>
</section>
-
<section id="raw">
<title>Including raw un-processed content</title>
- <p>The method for including "raw un-processed content" has changed.
+ <p>
+ The method for including "raw un-processed content" has changed.
</p>
<p>
In 0.6 version, the raw content was placed in the
- src/documentation/content/ directory and potential sub-directories.
- In the generated site, these links would automatically function.
- Any linked file with .html extension was not processed and not
- adorned with Forrest skin and navigation menus.
- </p>
- <p>It was also possible to place HTML content in the xdocs directory
- where it would be copied across if it was linked from the main
- content.</p>
- <p>
- In 0.7 version, any file that is linked to, needs to be placed in
- the content/xdocs/ directory structure.
- Any linked file with .html extension is now processed and is
- adorned with Forrest skin and navigation menus.
- </p>
- <p>If you
- you wish to emulate the behaviour of 0.6 and earlier then you
- must add the following to your project sitemap.</p>
-
- <source>
+ src/documentation/content/ directory and potential sub-directories. In
+ the generated site, these links would automatically function. Any linked
+ file with .html extension was not processed and not adorned with Forrest
+ skin and navigation menus.
+ </p>
+ <p>
+ It was also possible to place HTML content in the xdocs directory where
+ it would be copied across if it was linked from the main content.
+ </p>
+ <p>
+ In 0.7 version, any file that is linked to, needs to be placed in the
+ content/xdocs/ directory structure. Any linked file with .html extension
+ is now processed and is adorned with Forrest skin and navigation menus.
+ </p>
+ <p>
+ If you you wish to emulate the behaviour of 0.6 and earlier then you
+ must add the following to your project sitemap.
+ </p>
+ <source>
<map:match pattern="**.html">
<map:select type="exists">
<map:when test="{properties:content}{0}">
@@ -173,19 +161,17 @@
</map:select>
</map:match>
</source>
-
<p>
- If you need to include files that are not linked to,
- then place them in the src/documentation/content/ directories
- as with the 0.6 version.
+ If you need to include files that are not linked to, then place them in
+ the src/documentation/content/ directories as with the 0.6 version.
</p>
</section>
-
<section>
<title>To be continued...</title>
- <p>...as more issues are discovered/remembered :) Please send feedback
- to the
- <a href="site:mail-lists/forrest-dev">mailing list</a>.</p>
+ <p>
+ ...as more issues are discovered/remembered :) Please send feedback to
+ the <a href="site:mail-lists/forrest-dev">mailing list</a>.
+ </p>
</section>
</body>
</document>
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/validation.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/validation.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/validation.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/validation.xml Mon Apr 9 20:48:52 2007
@@ -22,33 +22,31 @@
"http://forrest.apache.org/entity/ISOnum.pen">
%ISOnum;
]>
-
<document>
<header>
<title>XML Validation</title>
<subtitle>DTDs, catalogs and whatnot</subtitle>
</header>
-
<body>
<section id="xml_validation">
<title>XML validation</title>
<p>
- By default, Forrest will validate your XML before generating
- HTML or a webapp from it, and fail if any XML files are not valid.
- Validation can be performed manually by doing
- '<code>forrest validate</code>' in the project root directory.
+ By default, Forrest will validate your XML before generating HTML or a
+ webapp from it, and fail if any XML files are not valid. Validation can
+ be performed manually by doing '<code>forrest validate</code>' in the
+ project root directory.
</p>
<p>
For an XML file to be valid, it <em>must</em> have a document type
- declaration at the top, indicating its content type. Hence by
- default, any Forrest-processed XML file that lacks a DOCTYPE
- declaration will cause the build to break.
+ declaration at the top, indicating its content type. Hence by default,
+ any Forrest-processed XML file that lacks a DOCTYPE declaration will
+ cause the build to break.
</p>
<p>
Despite the strict default behavior, Forrest is quite flexible about
- validation. Validation can be switched off for certain sections of a
- project. In validated sections, it is possible for projects to specify
- exactly what files they want (and don't want) validated. Forrest
+ validation. Validation can be switched off for certain sections of a
+ project. In validated sections, it is possible for projects to specify
+ exactly what files they want (and don't want) validated. Forrest
validation is controlled through a set of properties in
<code>forrest.properties</code>:
</p>
@@ -84,36 +82,34 @@
<source>forrest.validate.xdocs.excludes=slides.xml, manual/**</source>
<note>
The <code>failonerror</code> properties only work for files validated
- with Ant's <xmlvalidate> and not (yet) for those validated
- with <jing>, where <code>failonerror</code> defaults to
+ with Ant's <xmlvalidate> and not (yet) for those validated with
+ <jing>, where <code>failonerror</code> defaults to
<code>true</code>.
</note>
</section>
-
<section>
<title>Validating new XML types</title>
<p>
Forrest provides an <link href="ext:catalog_spec">OASIS Catalog</link>
[see <link href="ext:catalog_intro">tutorial</link>]
- <code>forrest/main/webapp/resources/schema/catalog.xcat</code>
- as a means of associating public identifiers
- (e.g. <code>-//APACHE//DTD Documentation V1.1//EN</code> above) with DTDs.
- If you <link href="site:v0.70//new_content_type">add a new content type</link>, you
- should add the DTD to <code>${project.schema-dir}/dtd/</code> and add
- an entry to the <code>${project.schema-dir}/catalog.xcat</code> file. This
- section describes the details of this process.
+ <code>forrest/main/webapp/resources/schema/catalog.xcat</code> as a
+ means of associating public identifiers (e.g. <code>-//APACHE//DTD
+ Documentation V1.1//EN</code> above) with DTDs. If you
+ <link href="site:v0.70//new_content_type">add a new content type</link>,
+ you should add the DTD to <code>${project.schema-dir}/dtd/</code> and
+ add an entry to the <code>${project.schema-dir}/catalog.xcat</code>
+ file. This section describes the details of this process.
</p>
-
<section>
<title>Creating or extending a DTD</title>
<p>
- The main Forrest DTDs are designed to be modular and extensible, so
- it is fairly easy to create a new document type that is a superset
- of one from Forrest. This is what we'll demonstrate here, using our
- earlier <link href="site:v0.70//new_content_type">download format</link>
- as an example. Our download format adds a group of new elements to
- the standard 'documentv13' format. Our new elements are described
- by the following DTD:
+ The main Forrest DTDs are designed to be modular and extensible, so it
+ is fairly easy to create a new document type that is a superset of one
+ from Forrest. This is what we'll demonstrate here, using our earlier
+ <link href="site:v0.70//new_content_type">download format</link> as an
+ example. Our download format adds a group of new elements to the
+ standard 'documentv13' format. Our new elements are described by the
+ following DTD:
</p>
<source>
<!ELEMENT release (downloads)>
@@ -135,10 +131,10 @@
The
<code>forrest/main/webapp/resources/schema/dtd/document-v13.dtd</code>
file provides a full description and basic example of how to pull in
- modules. In our example, our DTD reuses modules
+ modules. In our example, our DTD reuses modules
<code>common-charents-v10.mod</code> and
- <code>document-v13.mod</code>. Here is the full DTD, with
- explanation to follow.
+ <code>document-v13.mod</code>. Here is the full DTD, with explanation
+ to follow.
</p>
<source>
<!-- ===================================================================
@@ -211,157 +207,152 @@
<!-- End of DTD -->
<!-- =============================================================== -->
</source>
- <p>This custom DTD should be placed in your project resources
- directory at <code>src/documentation/resources/schema/dtd/</code></p>
<p>
- The <!ENTITY % ... > blocks are so-called
+ This custom DTD should be placed in your project resources directory
+ at <code>src/documentation/resources/schema/dtd/</code>
+ </p>
+ <p>
+ The <!ENTITY % ... > blocks are so-called
<link href="http://www.xml.com/axml/target.html#dt-PERef">parameter
- entities</link>. They are like macros, whose content will be
- inserted when a parameter-entity reference, like
- <code>%common-charents;</code> or <code>%document;</code> is
- inserted.
+ entities</link>. They are like macros, whose content will be inserted
+ when a parameter-entity reference, like <code>%common-charents;</code>
+ or <code>%document;</code> is inserted.
</p>
<p>
In our DTD, we first pull in the 'common-charents' entity, which
- defines character symbol sets. We then define the 'document'
- entity. However, before the <code>%document;</code> PE reference, we
- first override the 'local.section' entity. This is a hook into
- document-v13.mod. By setting its value to '|release', we declare
- that our <release> element is to be allowed wherever "local
- sections" are used. There are five or so such hooks for different
- areas of the document; see document-v13.dtd for more details. We then
- import the %document; contents, and declare the rest of our DTD
- elements.
+ defines character symbol sets. We then define the 'document' entity.
+ However, before the <code>%document;</code> PE reference, we first
+ override the 'local.section' entity. This is a hook into
+ document-v13.mod. By setting its value to '|release', we declare that
+ our <release> element is to be allowed wherever "local sections"
+ are used. There are five or so such hooks for different areas of the
+ document; see document-v13.dtd for more details. We then import the
+ %document; contents, and declare the rest of our DTD elements.
</p>
<p>
- We now have a DTD for the 'download' document type.
+ We now have a DTD for the 'download' document type.
</p>
<note>
- <link href="http://www.oasis-open.org/docbook/documentation/reference/html/ch05.html">Chapter
- 5: Customizing DocBook</link> of Norman Walsh's "DocBook: The
+ <link href="http://www.oasis-open.org/docbook/documentation/reference/html/ch05.html">Chapter
+ 5: Customizing DocBook</link> of Norman Walsh's "DocBook: The
Definitive Guide" gives a complete overview of the process of
customizing a DTD.
</note>
</section>
-
<section id="catalog">
<title>Associating DTDs with document types</title>
-
<p>
- Recall that our DOCTYPE declaration for our download document type
- is:
+ Recall that our DOCTYPE declaration for our download document type is:
</p>
<source><!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
"download-v10.dtd">
</source>
<p>
- We only care about the quoted section after <code>PUBLIC</code>, called
- the "public identifier", which globally identifies our document type.
- We cannot rely on the subsequent "system identifier" part
+ We only care about the quoted section after <code>PUBLIC</code>,
+ called the "public identifier", which globally identifies our document
+ type. We cannot rely on the subsequent "system identifier" part
("download-v10.dtd"), because as a relative reference it is liable to
- break. The solution Forrest uses is to ignore the system id, and rely
+ break. The solution Forrest uses is to ignore the system id, and rely
on a mapping from the public ID to a stable DTD location, via a
- Catalog file.</p>
+ Catalog file.
+ </p>
<note>
See <link href="ext:catalog_intro">this article</link> for a good
introduction to catalogs and the Cocoon documentation
- <link href="ext:cocoon/catalogs">Entity resolution with catalogs</link>.
+ <link href="ext:cocoon/catalogs">Entity resolution with
+ catalogs</link>.
</note>
<p>
Forrest provides a standard catalog file at
- <code>forrest/main/webapp/resources/schema/catalog.xcat</code>
- for the document
- types that Forrest provides. Projects can augment this with their
- own catalog file located in
+ <code>forrest/main/webapp/resources/schema/catalog.xcat</code> for the
+ document types that Forrest provides. Projects can augment this with
+ their own catalog file located in
<code>${project.schema-dir}/catalog.xcat</code> to use it you must
- specify either the path (full or relative) to your
- <code>catalog.xcat</code> in the <code>CatalogManager.properties</code>
- file. If you provide a relative path you must set the property
- <code>relative-catalogs</code> to "yes".
- </p>
- <p>
- When Cocoon starts, it reads the <code>CatalogManager.properties</code> file from your
- <code>project.classes-dir</code>. This is usually src/documentation/classes/
- but you can change this in <code>forrest.properties</code>. When you seed
- a new site using <code>forrest seed-site</code> a sample catalog file
- is placed in the site structure, you can use this as a template for your
- own files.
+ specify either the path (full or relative) to your
+ <code>catalog.xcat</code> in the
+ <code>CatalogManager.properties</code> file. If you provide a relative
+ path you must set the property <code>relative-catalogs</code> to
+ "yes".
+ </p>
+ <p>
+ When Cocoon starts, it reads the
+ <code>CatalogManager.properties</code> file from your
+ <code>project.classes-dir</code>. This is usually
+ src/documentation/classes/ but you can change this in
+ <code>forrest.properties</code>. When you seed a new site using
+ <code>forrest seed-site</code> a sample catalog file is placed in the
+ site structure, you can use this as a template for your own files.
</p>
<p>
Forrest uses the XML Catalog syntax by default, although the older
- plain-text
- format can also be used. Here is what the XML Catalog format looks
- like:
+ plain-text format can also be used. Here is what the XML Catalog
+ format looks like:
</p>
- <source><![CDATA[<?xml version="1.0"?>
+ <source>
+<![CDATA[<?xml version="1.0"?>
<!-- OASIS XML Catalog for Forrest -->
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<public publicId="-//Acme//DTD Download Documentation V1.0//EN"
uri="dtd/download-v10.dtd"/>
-</catalog>]]></source>
+</catalog>]]>
+ </source>
<p>
The format is described in <link href="ext:catalog_spec">the
- spec</link>, and is fairly simple and very powerful.
- The "<code>public</code>" elements map
- a public identifier to a DTD (relative to the catalog file).
+ spec</link>, and is fairly simple and very powerful. The
+ "<code>public</code>" elements map a public identifier to a DTD
+ (relative to the catalog file).
</p>
<p>
- We now have a custom DTD and a catalog mapping which lets both
- Forrest and Cocoon
- locate the DTD. Now if we were to run <code>'forrest validate'</code>
- our download file would validate along with all the others. If
- something goes wrong, try running <code>'forrest -v validate'</code> to
- see the error in more detail. Remember to raise the "verbosity"
- level in <code>cocoon.xconf</code> if you suspect problems
- with your catalog.
+ We now have a custom DTD and a catalog mapping which lets both Forrest
+ and Cocoon locate the DTD. Now if we were to run <code>'forrest
+ validate'</code> our download file would validate along with all the
+ others. If something goes wrong, try running <code>'forrest -v
+ validate'</code> to see the error in more detail. Remember to raise
+ the "verbosity" level in <code>cocoon.xconf</code> if you suspect
+ problems with your catalog.
</p>
</section>
</section>
-
<section id="entities">
<title>Referring to entities</title>
<p>
Look at the source of this document
(<code>xdocs/docs/validation.xml</code>) and see how the entity set
- <code>"Numeric and Special Graphic"</code> is declared in the
- document type declaration.
+ <code>"Numeric and Special Graphic"</code> is declared in the document
+ type declaration.
</p>
<table>
<tr>
- <td>ISOnum.pen</td>
- <td>&half;</td>
- <td>½</td>
+ <td>ISOnum.pen</td>
+ <td>&half;</td>
+ <td>½</td>
</tr>
</table>
</section>
-
<section>
<title>Validating in an XML editor</title>
<p>
- If you have an XML editor that understands SGML or XML catalogs, let
- it know where the Forrest catalog file is, and you will be able to
- validate any Forrest XML file, regardless of location, as you edit
- your files. See the
- <link href="site:v0.70//catalog">configuration notes</link> your favourite
- editor.
+ If you have an XML editor that understands SGML or XML catalogs, let it
+ know where the Forrest catalog file is, and you will be able to validate
+ any Forrest XML file, regardless of location, as you edit your files.
+ See the <link href="site:v0.70//catalog">configuration notes</link> your
+ favourite editor.
</p>
</section>
-
<section id="relaxng">
<title>Validation using RELAX NG</title>
<p>
Other validation is also conducted during build-time using RELAX NG.
- This validates all of the important configuration files, both in
- Forrest itself and in your project. At the moment it processes all
- skinconf.xml files, all sitemap.xmap files, and all XSLT stylesheets.
+ This validates all of the important configuration files, both in Forrest
+ itself and in your project. At the moment it processes all skinconf.xml
+ files, all sitemap.xmap files, and all XSLT stylesheets.
</p>
<p>
The RNG grammars to do this are located in the
- <code>main/webapp/resources/schema/relaxng</code> directory.
- If you want to
- know more about this, and perhaps extend it for your own use, then
- see <code>main/webapp/resources/schema/relaxng/README.txt</code>
- and the Ant targets in the various build.xml files.
+ <code>main/webapp/resources/schema/relaxng</code> directory. If you want
+ to know more about this, and perhaps extend it for your own use, then
+ see <code>main/webapp/resources/schema/relaxng/README.txt</code> and the
+ Ant targets in the various build.xml files.
</p>
</section>
</body>
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/views.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/views.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/views.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/views.xml Mon Apr 9 20:48:52 2007
@@ -21,49 +21,55 @@
<title>forrest:views concept (Draft -feature planed for 0.8)</title>
</header>
<body>
- <warning>This document is heavily under development</warning>
+ <warning>
+ This document is heavily under development
+ </warning>
<section id="introduction">
<title>Introduction</title>
<p>
- Like stated in the <a href="site:v0.70//documentation/skins">Skin documentation
- file</a> the aim of the forrest skins is to provide
- many capabilities so that extra skins are not needed. Our experience showed that many forrest user
- had to create a new skin because the default skin did not offer the feature their wanted to use.
- That leaded us to develop a new concept of creating skins that would be easily extensible by a user.
+ Like stated in the <a href="site:v0.70//documentation/skins">Skin
+ documentation file</a> the aim of the forrest skins is to provide many
+ capabilities so that extra skins are not needed. Our experience showed
+ that many forrest user had to create a new skin because the default skin
+ did not offer the feature their wanted to use. That leaded us to develop
+ a new concept of creating skins that would be easily extensible by a
+ user.
</p>
<p>
- The aim of the upcoming "forrest:views" skinning concept is to provide a flexible framework for creating
- site and page specific layout in different formats.
+ The aim of the upcoming "forrest:views" skinning concept is to provide a
+ flexible framework for creating site and page specific layout in
+ different formats.
</p>
-
</section>
-
<section id="background">
<title>Background</title>
<p>
- The problem with the forrest skins so far has been that "only" the design changed (html-skeleton),
- but still we had to write a completely new skin and implement all functionality.
- Another problem was that the functionality was not easy extensible by a user.
- Then we decided to support the a standard regarding naming conventions for css elements.
- This standard has been developed on the <a href="http://www.oscom.org/events/oscom4/proposals/skins">
- OSCOM website</a>, where you can find some more background informations.
+ The problem with the forrest skins so far has been that "only" the
+ design changed (html-skeleton), but still we had to write a completely
+ new skin and implement all functionality. Another problem was that the
+ functionality was not easy extensible by a user. Then we decided to
+ support the a standard regarding naming conventions for css elements.
+ This standard has been developed on the
+ <a href="http://www.oscom.org/events/oscom4/proposals/skins"> OSCOM
+ website</a>, where you can find some more background informations.
</p>
</section>
-
<section id="nc-definition">
<title>Definition of naming conventions</title>
<p>
- "A naming convention is an attempt to systematize names in a field so
- they unambiguously convey similar information in a similar manner."
- <a href="http://www.wordiq.com/definition/Naming_convention">wordiq-definition</a>
+ "A naming convention is an attempt to systematize names in a field so
+ they unambiguously convey similar information in a similar manner."
+ <a href="http://www.wordiq.com/definition/Naming_convention">wordiq-definition</a>
</p>
</section>
<section id="leather">
<title>leather-dev</title>
<p>
- That leaded to the development of the "leather-dev" skin which established a semantic container approach for div elements.
- The problems with leather-dev was pointed out on the mail
- <a href="http://marc.theaimsgroup.com/?l=forrest-dev m=111049344517653 w=2" >status on leather-dev?</a>
+ That leaded to the development of the "leather-dev" skin which
+ established a semantic container approach for div elements. The problems
+ with leather-dev was pointed out on the mail
+ <a href="http://marc.theaimsgroup.com/?l=forrest-dev m=111049344517653 w=2" >status
+ on leather-dev?</a>
</p>
</section>
</body>