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 2006/02/09 01:26:32 UTC
svn commit: r376128 [4/34] - in /forrest/site: ./ docs_0_60/
docs_0_60/howto/ docs_0_60/howto/bugzilla-patch/ docs_0_60/howto/multi/
docs_0_70/ docs_0_70/howto/ docs_0_70/howto/cvs-ssh/ docs_0_70/howto/multi/
docs_0_80/ docs_0_80/howto/ docs_0_80/howto...
Added: forrest/site/docs_0_60/howto/multi/step3.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/multi/step3.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/multi/step3.source.xml (added)
+++ forrest/site/docs_0_60/howto/multi/step3.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ 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.
+--><document><header>
+ <title>Multi-page how-to: Step 3</title>
+ <last-modified-content-date date="2002-09-10"/>
+ </header><body><section id="Step 3: Finish up"><title>Step 3: Finish up</title>
+ <section>
+ <title>First section of this step</title>
+ <p>Description here.</p>
+ </section>
+ <section>
+ <title>Second section of this step</title>
+ <p>Description here.</p>
+ <p>Congratulations, you have finished. Now return to the
+ <link href="site:v0.60//multi-page/intro">start</link>.</p>
+ </section>
+ </section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/howto/multi/step3.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/index.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/index.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/index.source.xml (added)
+++ forrest/site/docs_0_60/index.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ 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 V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document>
+ <header>
+ <title>Apache Forrest 0.6 Documentation</title>
+ </header>
+ <body>
+ <p>This is the documentation for Apache Forrest 0.6.</p>
+ <p>See the <link href="../">Forrest Project</link> for main documents and links to other versions of documentation.</p>
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/index.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/linking.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/linking.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/linking.source.xml (added)
+++ forrest/site/docs_0_60/linking.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,546 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ 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 V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document>
+ <header>
+ <title>Menus and Linking</title>
+ </header>
+
+ <body>
+ <section id="intro">
+ <title>Introduction</title>
+ <p>
+ This document describes Forrest's internal URI space; how it is managed
+ with the "site.xml" configuration file, how menus are generated,
+ and how various link schemes (site: and ext:) operate.
+ An overview of the implementation is also provided.
+ </p>
+ </section>
+
+ <section id="site">
+ <title>site.xml</title>
+ <p>
+ The "site.xml" configuration file is what we would call a "site map"
+ if Cocoon hadn't already claimed that term.
+ The "site.xml" is a loosely structured XML file, acting as a map of the
+ site's contents. It provides a unique identifier (an XPath address)
+ for "nodes" of information in the website. A "node" of site information
+ can be:
+ </p>
+ <ul>
+ <li>A category of information, like "the user guide". A category may
+ correspond to a directory, but that is not required.</li>
+ <li>A specific page, e.g. "the FAQ page"</li>
+ <li>A specific section in a page, e.g. the "general" section of the FAQ
+ page (identified by <code>id="general"</code> attribute)</li>
+ </ul>
+ <p>
+ In addition to providing fine-grained addressing of site info, the site.xml
+ allows <em>metadata</em> to be associated with each node, using
+ attributes or child elements. Most commonly, a <code>label</code>
+ attribute is used to provide a text description of the node.
+ </p>
+ <p>
+ There are currently two applications of site.xml
+ </p>
+ <dl>
+ <dt><link href="#menu_generation">Menu generation</link></dt>
+ <dd>site.xml is used to generate the menus for the HTML website.</dd>
+ <dt><link href="#semantic_linking">Indirect linking</link></dt>
+ <dd>site.xml provides a basic aliasing mechanism for linking, e.g. one
+ can write <link href="site:v0.60//changes"> from anywhere in the site, and
+ link to the "changes" information node (translated to changes.html).
+ More on this below.</dd>
+ </dl>
+ <p>
+ Here is a sample site.xml ... a modified version from Forrest's
+ own <link href="ext:forrest">website</link>:
+ </p>
+ <source xml:space="preserve"><![CDATA[
+<?xml version="1.0"?>
+<site label="Forrest" href="" tab="home"
+ xmlns="http://apache.org/forrest/linkmap/1.0">
+
+ <about label="About">
+ <index label="Index" href="index.html"/>
+ <license label="License" href="license.html"/>
+ <your-project label="Using Forrest" href="your-project.html">
+ <new_content_type href="#adding_new_content_type"/>
+ </your-project>
+ <linking label="Linking" href="linking.html"/>
+ <changes label="Changes" href="changes.html"/>
+ <todo label="Todo" href="todo.html"/>
+ <live-sites label="Live sites" href="live-sites.html"/>
+ </about>
+
+ <community label="Community" href="community/" tab="community">
+ <index label="About" href="index.html"/>
+ <howto-samples label="How-To Samples" href="howto/" tab="howto">
+ <overview label="Overview" href="index.html"/>
+ <single-page label="Single Page" href="v10/howto-v10.html"/>
+ <multi-page label="Multi-Page" href="multi/">
+ <intro label="Intro" href="howto-multi.html"/>
+ <step1 label="Step 1" href="step1.html"/>
+ <step2 label="Step 2" href="step2.html"/>
+ </multi-page>
+ </howto-samples>
+ </community>
+
+ <references label="References">
+ <gump label="Apache Gump" href="http://gump.apache.org/"/>
+ <cocoon label="Apache Cocoon" href="http://cocoon.apache.org/"/>
+ </references>
+
+ <external-refs>
+ <mail-archive href="http://marc.theaimsgroup.com"/>
+ <xml.apache.org href="http://xml.apache.org/">
+ <commons href="commons/">
+ <resolver href="components/resolver/"/>
+ </commons>
+ <fop href="fop/"/>
+ <batik href="batik/"/>
+ </xml.apache.org>
+
+ <mail>
+ <semantic-linking href="http://marc.theaimsgroup.com/?l=forrest-dev
+ &m=103097808318773&w=2"/>
+ </mail>
+ <cool-uris href="www.w3.org/Provider/Style/URI.html"/>
+ <uri-rfc href="http://zvon.org/tmRFC/RFC2396/Output/index.html"/>
+
+ </external-refs>
+</site>
+ ]]></source>
+ <p>As you can see, things are quite free-form. The rules are as follows:</p>
+ <ul>
+ <li>The root element must be "site", and normal content should be in the
+ namespace <code>http://apache.org/forrest/linkmap/1.0</code> (Feel
+ free to mix in your own content (RDF, dublin core, etc) under new
+ namespaces)</li>
+ <li>Element names are used as identifiers. The "<code>foo</code>" in
+ "<code>site:foo</code>" must therefore be a valid NMTOKEN.</li>
+ <li>Elements with <code>href</code> attributes can be used as identifiers
+ in "<code>site:</code>" URIs</li>
+ <li>Relative href attribute contents are "accumulated" by prepending hrefs
+ from ancestor nodes</li>
+ <li>Elements without <code>label</code> attributes (and their children)
+ are not displayed in the menu.</li>
+ <li>Elements below <code>external-refs</code> are mapped to the
+ "<code>ext:</code>" scheme. So "<code>ext:commons/resolver/</code>" becomes
+ "<code>http://xml.apache.org/commons/resolver/</code>"</li>
+ </ul>
+ </section>
+
+ <section id="menu_generation">
+ <title>Generating Menus</title>
+ <p>
+ Two files are used to define a site's tabs and menu (site.xml and
+ <code>tabs.xml</code>). Both files are located in
+ <code>src/documentation/content/xdocs/</code></p>
+ <p>Assume that our <code>tabs.xml</code> looks like this:</p>
+ <source xml:space="preserve"><![CDATA[
+<tabs ...>
+ <tab id="home" label="Home" dir=""/>
+ <tab id="community" label="Community" dir="community" indexfile="mailLists.html"/>
+ <tab id="howto" label="How-Tos" dir="community/howto"/>
+</tabs>
+ ]]></source>
+ <p>Using the "site.xml" listed above, we would get these menus:</p>
+ <p>
+ <img src="images/menu.png" alt="Menu generated from site.xml"/>
+ <img src="images/menu2.png" alt="Community menu generated from site.xml"/>
+ <img src="images/menu3.png" alt="Howto menu generated from site.xml"/>
+ </p>
+
+ <p>When using the "<code>dir</code>" attribute as above the value of the
+ "<code>indexfile</code>" parameter is appended to the value of the
+ "<code>dir</code>" attribute (together with a preceding '/'). For example,
+ the link for the community tab above is
+ <code>community/mailLists.html</code>. Note that "<code>indexfile</code>"
+ defaults to "<code>index.html</code>" if no value is supplied. Therefore the
+ link for the howto tab is <code>community/howto/index.html</code></p>
+
+ <section id="tabs-external">
+ <title>Tabs for External Resources</title>
+ <p>A tab can refer to an external resource by using the
+ "<code>href</code>" attribute instead of the "<code>dir</code>" attribute.
+ The value of "<code>href</code>" should be the URI of the resource you wish
+ to link to. For example:</p>
+
+ <source xml:space="preserve"><![CDATA[
+<tab id="apache" label="XML Apache" href="http://xml.apache.org/"/>
+ ]]></source>
+
+ <p>Unlike the "<code>dir</code>" attribute, the value of "<code>href</code>"
+ is left unmodified by Forrest unless it is root-relative and obviously
+ specifies a directory (ends in '/'). In which case /index.html will be
+ added.</p>
+ </section>
+
+ <section id="selecting-entries">
+ <title>Selecting menu entries</title>
+ <p>Forrest decides which menu entries to display, by examining the
+ "<code>tab</code>" attributes in the site.xml file. The children of
+ all site.xml entries with a
+ "<code>tab</code>" which is equal to that of the current page, are
+ added to the menu, whilst the element itself forms the root of that
+ part of the menu (see the "<code>community</code>" element in the
+ example below). Child elements that have a different
+ "<code>tab</code>" attribute value will appear in the menu for their
+ parents, and will also form the root of a new menu for a tab with
+ the appropriate name (see the "<code>howto-samples</code>" element
+ below).</p>
+ <p>Consider our site.xml example:</p>
+ <source xml:space="preserve">
+<site label="Forrest" href="" <strong>tab="home"</strong>
+ xmlns="http://apache.org/forrest/linkmap/1.0">
+
+ <about label="About">
+ <index label="Index" href="index.html"/>
+ <license label="License" href="license.html"/>
+ <your-project label="Using Forrest" href="your-project.html">
+ <new_content_type href="#adding_new_content_type"/>
+ </your-project>
+ <linking label="Linking" href="linking.html"/>
+ ....
+ </about>
+
+ <community label="Community" href="community/" <strong>tab="community"</strong>>
+ <index label="About" href="index.html"/>
+ <howto-samples label="How-To Samples" href="howto/" <strong>tab="howto"</strong>>
+ <overview label="Overview" href="index.html"/>
+ <single-page label="Single Page" href="v10/howto-v10.html"/>
+ <multi label="Multi-Page" href="multi/">
+ <intro label="Intro" href="howto-multi.html"/>
+ <step1 label="Step 1" href="step1.html"/>
+ ...</source>
+ <p>
+ Every site.xml node can potentially have a "<code>tab</code>" attribute. If
+ unspecified, nodes inherit the "<code>tab</code>" of their parent. Thus
+ everything in the <strong><about></strong> section has an implicit
+ <code>tab="home" </code>attribute.</p>
+ <note>You can see this by viewing your site's
+ <link href="../abs-menulinks">abs-menulinks</link> pipeline in a
+ browser.</note>
+ <p>Say that the user is viewing the <code>linking.html</code>
+ page. The <strong><linking></strong> node has an implicit tab
+ value of "<code>home</code>". Forrest will select <em>all nodes with
+ tab="home"</em> and put them in the menu.
+ </p>
+ </section>
+
+ <section id="other-menu-selection">
+ <title>Alternative menu selection mechanisms.</title>
+ <p>
+ The "<code>tab</code>" attribute-based scheme for selecting a menu's
+ entries is not the only one, although it is the most flexible. Here
+ we describe a few alternatives.
+ </p>
+ <section id="dir-menu-selection">
+ <title>Directory-based selection</title>
+ <p>In this scheme, each tab corresponds to a directory within the
+ site. All content below that directory is included in the menu.</p>
+ <p>
+ <img src="images/dir-menu.png" alt="Directory-based site menu"/>
+ <img src="images/dir-menu2.png" alt="community/ directory menu"/>
+ <img src="images/dir-menu3.png" alt="community/howto/ directory menu"/>
+ </p>
+ <p>
+ To use this scheme:
+ </p>
+ <ul>
+ <li>Edit <code>forrest.properties</code> and set
+ <code>project.menu-scheme=directories</code></li>
+ <li>Remove the "<code>id</code>" attributes from <code>tabs.xml</code>
+ entries.</li>
+ </ul>
+ </section>
+ <section id="book-menu-selection">
+ <title>Specifying menus with book.xml</title>
+ <p>
+ Historically, menus in Forrest have been generated from a
+ <code>book.xml</code> file, one per directory. This mechanism is
+ still available, and if a <code>book.xml</code> is found, it will be
+ used in preference to the menu generated by the site.xml file. The <code>book.xml</code>
+ files can use "<code>site:</code>" URIs to ease the maintenance burden
+ that led to obsolescence of book.xml files. In general, however, we
+ recommend that users avoid <code>book.xml</code> files.
+ </p>
+ </section>
+ </section>
+
+ <section id="tab-selection">
+ <title>Selecting the current tab</title>
+ <p>
+ The tab selection algorithm is quite simple: the tab with the
+ "<code>id</code>" which matches that of the current <code>site.xml</code>
+ node is "selected". If you experience any problems, try to add a
+ <code><foo label="Foo" href="index.html"/></code> to the
+ <code>site.xml</code> configuration.
+ </p>
+ </section>
+
+ </section>
+
+ <section id="toc-generation">
+ <title>Table of Contents Generation</title>
+ <p>Each page can have an automatically generated table of contents. This
+ is created from the titles of each section in your xdoc. By default only
+ sections up to two levels deep are included and the table of contents is
+ displayed at the top of the page. However, you can configure this
+ behaviour in <code>src/documentation/skinconf.xml</code> using the
+ "<code>toc</code>" element.</p>
+
+ <source xml:space="preserve"><![CDATA[
+<toc level="2" location="page"/>
+ ]]></source>
+
+ <ul>
+ <li><strong><code>level</code></strong> - is the depth to which you
+ want your table of contents to go. Setting it to "3" will therefore
+ include sections nested to 3 levels. Setting this to "0" will result in
+ no table of contents being generated.</li>
+ <li><strong><code>location</code></strong> - indicates where you
+ want the table of contents to be rendered. It can be set to one of
+ three values:
+ <ul>
+ <li><code>page</code> - the table of contents will be rendered
+ at the top of the body of your page</li>
+ <li><code>menu</code> - the table of contents will be rendered
+ in the menu to the left of the body of the page</li>
+ <li><code>menu, page</code> - table of contents will be rendered
+ in both the page and the menu positions</li>
+ </ul>
+ </li>
+ </ul>
+ </section>
+
+ <section id="linking">
+ <title>Linking systems</title>
+
+ <section id="direct-linking">
+ <title>Direct linking</title>
+ <p>
+ In earlier versions of Forrest (and in similar systems), there has
+ been only one URI space: that of the generated site. If index.xml wants to
+ link to todo.xml then index.xml would use
+ </p>
+ <source xml:space="preserve">
+ <link href="todo.html">to-do list<link>
+ </source>
+ <p>
+ The theoretical problem with this is that the content producer should
+ not know or care how Forrest is going to render the source. A URI
+ should only <em>identify</em> a resource, not specify it's type
+ [<link href="ext:semantic-linking">mail ref</link>] and
+ [<link href="ext:cool-uris">cool URIs</link>]. In fact, as Forrest
+ typically renders to multiple output formats (HTML and PDF), links in
+ one of them (here, the PDF) are likely to break.
+ </p>
+ </section>
+
+ <section id="indirect-linking">
+ <title>Indirect linking</title>
+ <p>
+ Forrest's solution is simple: instead of <link href="todo.html">,
+ write <link href="site:v0.60//todo"> where:
+ </p>
+ <dl>
+ <dt>site</dt>
+ <dd>is a URI "scheme"; a namespace that restricts
+ the syntax and semantics of the rest of the URI
+ [<link href="ext:uri-rfc">rfc2396</link>]. The semantics of "site" are
+ "this identifier locates something in the site's XML sources".</dd>
+ <dt>todo</dt>
+ <dd>identifies the content in <code>todo.xml</code> by reference to a
+ "node" of content declared in site.xml</dd>
+ </dl>
+ <p>
+ We call this indirect, or <em>semantic</em> linking because instead of
+ linking to a physical representation (todo.html), we've linked to the
+ "idea" of "the todo file". It doesn't matter where it physically lives;
+ that will be sorted out by Forrest.
+ </p>
+
+ <section id="resolve-site-uris">
+ <title>Resolving site: URIs</title>
+
+ <p>
+ So how does "<code>site:todo</code>" get resolved? A full answer
+ is provided in the <link href="#implementation">implementation</link>
+ section. Essentially, the "<code>todo</code>" part has
+ "<code>/site//</code>" prepended, and "<code>/@href</code>" appended, to
+ form the string "<code>/site//todo/@href</code>". This is
+ then used as an XPath expression in site.xml to identify the string
+ replacement, in this case "<code>todo.html</code>"
+ </p>
+ <p>
+ Thus by modifying the XPath prefix and suffix, almost any XML
+ format can be accommodated.
+ </p>
+ <note>
+ Actually, the XPath is applied to XML generated dynamically from
+ site.xml. The generated XML has each "@href" fully expanded ("absolutized")
+ and dot-dots (..) added as needed ("relativized").
+ </note>
+
+ <p>
+ Notice that the "//" allows us any degree of specificity when linking.
+ In the sample site.xml above, both "<code>site:new_content_type</code>" and
+ "<code>site:about/your-project/new_content_type</code>" identify the
+ same node. It is up to you to decide how specific to make links. One
+ nice benefit of link "ambiguity" is that site.xml can be reorganized
+ without breaking links. For example, "new_content_type" currently
+ identifies a node in "your-project". By leaving that fact unspecified
+ in "<code>site:new_content_type</code>" we are free to make
+ "new_content_type" its own XML file, or a node in another file, in
+ another category.
+ </p>
+ </section>
+
+ <section id="resolve-ext-uris">
+ <title>ext: URIs: linking to external URLs</title>
+ <p>
+ The "<code>ext:</code>" scheme was created partly to demonstrate the
+ ease with which new schemes can be defined, and partly for practical
+ use. The "<code>ext:</code>" URIs identify nodes in site.xml below the
+ <external-refs> node. By convention, nodes here link to URLs
+ outside the website, and are not listed in the menu generated from
+ the site.xml file.
+ </p>
+ <p>Here is a site.xml snippet illustrating "<code>external-refs</code>":</p>
+ <source xml:space="preserve"><![CDATA[
+<site>
+ ...
+ <external-refs>
+ <mail-archive href="http://marc.theaimsgroup.com"/>
+ <xml.apache.org href="http://xml.apache.org/">
+ <commons href="commons/">
+ <resolver href="components/resolver/"/>
+ </commons>
+ </xml.apache.org>
+ ...
+ </external-refs>
+</site>]]></source>
+ <p>
+ As an example, <link href="ext:commons/resolver">
+ generates the link
+ <link href="ext:commons/resolver">http://xml.apache.org/components/resolver/</link>
+ </p>
+ <p>
+ The general rules of site.xml and "<code>site:</code>" linking apply.
+ Specifically, the "@href" aggregation makes defining large numbers of
+ related URLs easy.
+ </p>
+ </section>
+
+ <section id="source-uris">
+ <title>Theory: source URIs</title>
+ <p>
+ The "<code>site:</code>" URIs like "<code>site:todo</code>" are examples of
+ "<em>source</em>" URIs, in contrast to the more usual
+ <code>foo.html</code> style URIs, which we here call
+ "<em>destination</em>" URIs. This introduces an important concept: that
+ the "<em>source</em>" URI space exists and is independent of that of the
+ generated site. Furthermore, URIs (i.e. links) are first-class objects,
+ on par with XML documents, in that just as XML content is transformed,
+ so are the links. Within the source URI space, we can have all sorts of
+ interesting schemes (person: mail: google: java: etc). These will
+ all be translated into plain old "<code>http:</code>" or relative URIs
+ in the destination URI space, just like exotic XML source formats are
+ translated into plain old HTML in the output.
+ </p>
+ </section>
+
+
+ <section id="future-schemes">
+ <title>Future schemes</title>
+ <p>
+ So far, the "<code>site:</code>" and "<code>ext:</code>" schemes are defined.
+ To give you some ideas on other things we'd like to implement (and
+ wouldd welcome help to implement) here are a few possibilities.
+ </p>
+ <table>
+ <tr><th colspan="1" rowspan="1">Scheme</th><th colspan="1" rowspan="1">Example "From"</th><th colspan="1" rowspan="1">Example "To"</th><th colspan="1" rowspan="1">Description</th></tr>
+ <tr>
+ <td colspan="1" rowspan="1">java</td>
+ <td colspan="1" rowspan="1">java:org.apache.proj.SomeClass</td>
+ <td colspan="1" rowspan="1"><code>../../apidocs/org/apache/proj/SomeClass.html</code></td>
+ <td colspan="1" rowspan="1">
+ Links to documentation for a Java class (typically generated by
+ <code>javadoc</code>).
+ </td>
+ </tr>
+ <tr>
+ <td colspan="1" rowspan="1">mail</td>
+ <td colspan="1" rowspan="1">mail::<Message-Id></td>
+ <td colspan="1" rowspan="1"><code>http://marc.theaimsgroup.com?t=12345678</code></td>
+ <td colspan="1" rowspan="1">
+ Links to an email, identified by its <code>Message-Id</code>
+ header. Any mail archive website could be used.
+ </td>
+ </tr>
+ <tr>
+ <td colspan="1" rowspan="1">search</td>
+ <td colspan="1" rowspan="1">search:<searchterm></td>
+ <td colspan="1" rowspan="1"><code>http://www.google.com/search?q=searchterm</code></td>
+ <td colspan="1" rowspan="1">Link to set of results from a search engine</td>
+ </tr>
+ <tr>
+ <td colspan="1" rowspan="1">person</td>
+ <td colspan="1" rowspan="1">person:JT, person:JT/blog etc</td>
+ <td colspan="1" rowspan="1"><code>mailto:jefft<at>apache.org</code>,
+ <code>http://www.webweavertech.com/jefft/weblog/</code></td>
+ <td colspan="1" rowspan="1">
+ A "<code>person:</code>" scheme could be used, say, to insert an
+ automatically obfuscated email address, or link to a URI in some
+ way associated with that person.
+ </td>
+ </tr>
+ </table>
+ <p>
+ There are even more possibilities in specific environments. In an
+ intranet, a "<code>project:XYZ</code>" scheme could identify company
+ project pages. In a project like <link href="ext:ant">Apache
+ Ant</link>, each Task could be identified with
+ <code>task:<taskname></code>, e.g. <code>task:pathconvert</code>.
+ </p>
+ </section>
+ </section>
+ </section>
+ <section id="concept">
+ <title>Concept</title>
+ <p>
+ The "<code>site:</code>" scheme and associated ideas for site.xml were
+ originally described in <link href="ext:linkmaps">the 'linkmap' RT
+ email</link> to the forrest-dev list (RT means 'random thought'; a
+ Cocoon invention). Only section 2 has been implemented, and there is
+ still significant work required to implement the full system
+ described. In particular, there is much scope for automating the
+ creation of site.xml (section 4). However, what is currently implemented
+ gains most of the advantages of the system.
+ </p>
+ </section>
+ <section id="implementation">
+ <title>Implementation</title>
+ <p>Full details on the implementation of
+ <link href="site:v0.60//linkrewriting_impl">link rewriting</link> and
+ <link href="site:v0.60//menu_generation_impl">menu generation</link> are available in
+ the <link href="site:v0.60//sitemap-ref">Sitemap Reference</link></p>
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/linking.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/project-sitemap.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/project-sitemap.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/project-sitemap.source.xml (added)
+++ forrest/site/docs_0_60/project-sitemap.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ 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 V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document>
+ <header>
+ <title>Using project sitemaps</title>
+ </header>
+ <body>
+ <section id="introduction">
+ <title>Introduction</title>
+
+ <p>With Forrest 0.6 it is now possible for projects to "plugin"
+ to our sitemaps, without needing to copy the main sitemaps and keep
+ them them synchonised. This will enable hassle-free update to
+ future Forrest versions.</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. See the
+ <link href="site:v0.60//sitemap-ref">Sitemap Reference</link> for a tour of the
+ default sitemap.
+ </note>
+ </section>
+
+ <section id="how">
+ <title>How does it work?</title>
+
+ <p>If a project has a <code>sitemap.xmap</code> file in it's
+ documentation dir, that gets mounted automatically by Forrest and
+ becomes part of the processing: it is a preprocessing step, and
+ is the first one to handle the request. Because of this it can
+ serve any file directly. If it does not want to
+ serve a file, it can simply not match the URL and Forrest will take
+ care of it as usual.</p>
+
+ <p>The cool thing is that if that pipeline serves an xml representation,
+ Forrest will provide a skinned version of it.</p>
+
+ <p>So if the project sitemap matches test.xml and transforms that to a
+ correctly structured Forrest intermediate "document-v*",
+ then the user will see test.html fully rendered by Forrest.</p>
+
+ <p>Of course, to resolve the directories in your sitemap it is important
+ to use the 'project:' and 'forrest:' variables to prevent any possible
+ issue in the future.</p>
+ </section>
+
+ <section id="examples">
+ <title>Example uses of this technique</title>
+
+ <section id="download">
+ <title>Adding a new content type</title>
+ <p>
+ See the section "Advanced customizations: sitemap.xmap" in
+ the <link href="site:v0.60//your-project">Using Forrest</link> document
+ and then follow the
+ <link href="site:v0.60//your-project/new_content_type">Example:
+ Adding a new content type</link>.
+ </p>
+ </section>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/project-sitemap.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/searching.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/searching.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/searching.source.xml (added)
+++ forrest/site/docs_0_60/searching.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ 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 V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document>
+ <header>
+ <title>Searching Forrest-built documentation</title>
+ </header>
+ <body>
+ <p>Forrest provides you with two distinct options for making your
+ documentation available through full-text search:</p>
+ <ul>
+ <li>Google SiteSearch,</li>
+ <li>Built-in search using Apache Lucene.</li>
+ </ul>
+ <p>Both options have their advantages and disadvantages. The
+ purpose of this document is to outline them, and to help you
+ make a choice. This document also tells you how to disable
+ full-text search completely, if you so choose.</p>
+ <section>
+ <title>Google SiteSearch</title>
+ <p>Forrest provides a simple interface to the Google search
+ engine. It invokes Google Advanced Search and limits the search
+ scope to the domain of your choice. Since the actual search
+ functionality is implemented on Google's end, you do not need
+ any additional capability on your Forrest server (which may
+ well be a simple static web server serving content generated
+ with <code>forrest site</code>).</p>
+ <p>To use Google SiteSearch in your Forrest application, open
+ your <code>skinconf.xml</code> file. By default this file is
+ in the <code>src/documentation</code> subdirectory of your
+ Forrest repository root. Find the <code><search></code>
+ element; it should be near the top of the file. If the element
+ does not exist, create it below the
+ <code><skinconfig></code> opening tag. If there is any
+ attribute named <code>provider</code>, remove it. The element
+ should look similar to this:</p>
+ <source xml:space="preserve"><![CDATA[<search name="MyProject"
+ domain="myproject.com"/>]]></source>
+ <p>Then, build your Forrest documentation and open it using your
+ favorite web browser. You are now invited to peruse the search
+ box (most skins render this in the top-right corner). Google's
+ search results will be displayed in a new browser window.</p>
+ <p>Needless to say, for this to work your content must be
+ accessible to Google's indexing robot. It can't be stored on a
+ server which is only locally accessible, or which requires
+ authentication. In addition, the content index is created and
+ updated at a time of Google's choosing. However, the search is fast
+ and search precision is usually excellent. So if your
+ Forrest content is placed on a busy, popular public web
+ server, Google search is probably the best choice.</p>
+ </section>
+ <section>
+ <title>Lucene search</title>
+ <p>Lucene is a high-performance, full-text search engine built
+ entirely in Java. To use Lucene-based search with your Forrest
+ documentation, you will need to run Forrest in a Java servlet
+ environment (such as Tomcat or Jetty). Lucene-based searching
+ will not work in a static site generated with the '<code>forrest
+ site</code>' command.</p>
+ <p>In order to enable Lucene-based full-text search in your
+ Forrest application, you must first edit your
+ <code>skinconf.xml</code> file. Locate the
+ <code><search></code> element. If the element does not
+ exist, insert it right underneath the
+ <code><skinconfig></code> opening tag. Add an attribute
+ named <code>provider</code> with a value of
+ <code>lucene</code>, so that the element looks similar to
+ this:</p>
+ <source xml:space="preserve"><![CDATA[<search name="MyProject" domain="myproject.com"
+ provider="lucene"/>]]></source>
+ <p>Next, create and run your Forrest webapp. This may mean
+ simply invoking <code>forrest run</code>, or building and
+ bundling a servlet webapp (with <code>forrest webapp</code>),
+ and then deploying it to your servlet container.</p>
+ <p>You can now build a Lucene search index by pointing your web
+ browser at
+ <code>http://localhost:8888/lucene-update.html</code>. This
+ generates the search index and provides some information about
+ the index generation process.</p>
+ <note>You may have to substitute a different hostname, port, or
+ path, depending on your configuration. The path mentioned here
+ reflects Forrest's default settings when invoked as
+ <code>forrest run</code>.</note>
+ <p>Now you can utilize the full-text search box, located in the
+ top-right corner of the rendered Forrest pages. Search results
+ will be displayed in the same browser window and will look
+ remarkably similar to the rest of your Forrest documents.</p>
+ <p>Unlike with Google SiteSearch, the indexing information
+ retrieved by Lucene is stored on your own server, access to
+ which you may limit to users in your own organization.
+ Likewise, you may update or recreate the Lucene index at any
+ time and at your own discretion. So if you aren't making your
+ Forrest-built documentation publicly available, and you're
+ able to run Forrest on a Java-enabled web server, Lucene
+ search is probably right for you.</p>
+ </section>
+ <section>
+ <title>Disabling full-text search</title>
+ <p>If you are convinced your users don't need any full-text
+ search capability whatsoever, you may disallow displaying the
+ search box entirely. You may also wish to do so if you're
+ keeping Forrest-built content on a restricted server (meaning
+ you can't use Google), while at the same time not having any
+ usable servlet-capable web server at your disposal (meaning
+ you can't use Lucene, either).</p>
+ <p>To disable full-text search completely, open the
+ <code>skinconf.xml</code> file and remove (or comment out) the
+ entire <code><search></code> element.</p>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/searching.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/sitemap-ref.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/sitemap-ref.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/sitemap-ref.source.xml (added)
+++ forrest/site/docs_0_60/sitemap-ref.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,764 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ 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 V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<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
+ defines the site's URI space (what pages are available), and how each page
+ 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.
+ </note>
+ <p>
+ 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/context/*.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.60//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>
+ </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
+ overview of the files, in order of importance.
+ </p>
+ <table>
+ <tr>
+ <th colspan="1" rowspan="1"><strong>sitemap.xmap</strong></th>
+ <td colspan="1" rowspan="1">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>
+ </tr>
+ <tr>
+ <th colspan="1" rowspan="1">forrest.xmap</th>
+ <td colspan="1" rowspan="1">Sitemap defining Source pipelines, which generate the body section
+ of Forrest pages. All pipelines here deliver XML in Forrest's
+ intermediate "document-v13" format, regardless of originating source
+ or format.</td>
+ </tr>
+ <tr>
+ <th colspan="1" rowspan="1">menu.xmap</th>
+ <td colspan="1" rowspan="1">Pipelines defining the XML that becomes the menu.</td>
+ </tr>
+ <tr>
+ <th colspan="1" rowspan="1">linkmap.xmap</th>
+ <td colspan="1" rowspan="1">Defines a mapping from abstract ("site:index") to physical
+ ("../index.html") links for the current page. See
+ <link href="site:v0.60//linking">Menus and Linking</link> for a conceptual
+ overview, and the <link href="#linkrewriting_impl">Link
+ rewriting</link> section for technical details.</td>
+ </tr>
+ <tr>
+ <th colspan="1" rowspan="1">resources.xmap</th>
+ <td colspan="1" rowspan="1">Serves "resource" files (images, CSS, Javascript).</td>
+ </tr>
+ <tr>
+ <th colspan="1" rowspan="1">raw.xmap</th>
+ <td colspan="1" rowspan="1">Serves files located in <code>src/documentation/content/</code>
+ that are not to be modified by Forrest.</td>
+ </tr>
+ <tr>
+ <th colspan="1" rowspan="1">aggregate.xmap</th>
+ <td colspan="1" rowspan="1">Generates a single page (HTML or PDF) containing all the content
+ for the site.</td>
+ </tr>
+ <tr>
+ <th colspan="1" rowspan="1">faq.xmap</th>
+ <td colspan="1" rowspan="1">Processes FAQ documents.</td>
+ </tr>
+ <tr>
+ <th colspan="1" rowspan="1">status.xmap</th>
+ <td colspan="1" rowspan="1">Generates <link href="site:v0.60//changes">changes</link> and
+ <link href="site:v0.60//todo">todo</link> pages from a single
+ <code>status.xml</code> in the project root.
+ </td>
+ </tr>
+ <tr>
+ <th colspan="1" rowspan="1">issues.xmap</th>
+ <td colspan="1" rowspan="1">Generates a page of content from an RSS feed. Used in Forrest to
+ generate a "current issues" list from JIRA.</td>
+ </tr>
+ <tr>
+ <th colspan="1" rowspan="1">revisions.xmap</th>
+ <td colspan="1" rowspan="1">
+ Support for HOWTO documents that want "revisions". Revisions are
+ XML snippets containing comments on the main XML file. The main
+ pipeline here automatically appends a page's revisions to the
+ bottom.
+ </td>
+ </tr>
+ <tr>
+ <th colspan="1" rowspan="1">dtd.xmap</th>
+ <td colspan="1" rowspan="1">A Source pipeline that generates XML from a DTD, using Andy
+ Clark's
+ <link href="http://www.apache.org/~andyc/neko/doc/dtd/index.html">DTD
+ Parser</link>. Useful for documenting DTD-based XML schemas, such
+ as <link href="site:dtd-docs">Forrest's own DTDs</link>.
+ </td>
+ </tr>
+ <tr>
+ <th colspan="1" rowspan="1">profiler.xmap</th>
+ <td colspan="1" rowspan="1">Defines the "profiler" pipeline. allowing pipelines to be benchmarked.</td>
+ </tr>
+ </table>
+ </section>
+
+ <!--
+ <section>
+ <title>Logical structure</title>
+ <p>There are a few major groups of sitemap pipelines</p>
+ <dl>
+ <dt>Content pipelines</dt>
+ <dd>These define the body (without menu and header) for HTML pages, and all the content of PDFs.</dd>
+ <dt>Menu pileines.
+ </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
+ (document-v13, Docbook, RSS, FAQ, Howto) and from any source (local or
+ remote). The output format is always Forrest's intermediate "document-v13"
+ format.
+ </p>
+ <p>
+ 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="site:v0.60//faq">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
+ files are all processed identically from here on.
+ </p>
+ <source xml:space="preserve">
+ (subsequent Forrest pipelines)
+ |
+--------+------------------------^------------------------------------------
+ | STANDARD FORREST FORMAT (current document-v13)
+ +-----^-------^--------^------------^------^-----^-----^------^-----
+SOURCE | | | | | | | |
+FORMATS doc-v11 doc-v13 doc-v20 ... Docbook FAQ Howto Wiki RSS ??
+(*.xml)
+ (in forrest.xmap, faq.xmap, etc)
+ </source>
+ <section id="forrest_xmap">
+ <title>forrest.xmap</title>
+ <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.60//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.60//write-howto">a
+ Howto document</link> called "howto-howto.xml". It contains this DOCTYPE
+ declaration:</p>
+ <source xml:space="preserve">
+<!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 xml:space="preserve"><![CDATA[
+ <map:when test="howto-v13">
+ <map:transform src="{forrest:stylesheets}/howto2document.xsl" />
+ </map:when>
+ ]]></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
+
+ <p>
+ The intermediate result is visible at the URL
+ <link href="../howto/howto-howto.xml">howtos/howto-howto.xml</link>.
+ </p>
+ -->
+ </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
+ <code>sitemap.xmap</code> which simply delegates certain requests to
+ these subsitemaps:</p>
+ <source xml:space="preserve"><![CDATA[
+ <!-- Body content -->
+ <map:match pattern="**.xml">
+ <map:match pattern="changes.xml">
+ <map:mount uri-prefix="" src="status.xmap" check-reload="yes" />
+ </map:match>
+
+ <map:match pattern="todo.xml">
+ <map:mount uri-prefix="" src="status.xmap" check-reload="yes" />
+ </map:match>
+
+ <map:match pattern="**dtdx.xml">
+ <map:mount uri-prefix="" src="dtd.xmap" check-reload="yes" />
+ </map:match>
+
+ <map:match pattern="forrest-issues.xml">
+ <map:mount uri-prefix="" src="issues.xmap" check-reload="yes" />
+ </map:match>
+
+ <map:match pattern="**faq.xml">
+ <map:mount uri-prefix="" src="faq.xmap" check-reload="yes" />
+ </map:match>
+
+ <map:match pattern="site.xml">
+ <map:mount uri-prefix="" src="aggregate.xmap" check-reload="yes" />
+ </map:match>
+ ....
+ ....]]></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
+ <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
+ 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
+ override <code>sitemap.xmap</code> and redefine the relevant source
+ matcher:</p>
+ <source xml:space="preserve"><![CDATA[
+ <map:match pattern="**faq.xml">
+ <map:mount uri-prefix="" src="faq.xmap" check-reload="yes" />
+ </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
+ are located in various *.xmap files, notably forrest.xmap
+ </p>
+ <p>
+ We now wish to render the XML from these pipelines to output formats
+ like HTML and PDF.
+ </p>
+ <section id="pdf">
+ <title>PDF output</title>
+ <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
+ <code>sitemap.xmap</code> ...
+ </p>
+ <source xml:space="preserve"><![CDATA[
+1 <map:match type="regexp" pattern="^(.*?)([^/]*).pdf$">
+2 <map:generate src="cocoon:/{1}{2}.xml"/>
+3 <map:transform type="xinclude"/>
+4 <map:transform type="]]>linkrewriter<![CDATA[" src="cocoon://{1}linkmap-{2}.pdf"/>
+5 <map:transform src="skins/{forrest:skin}/xslt/fo/document2fo.xsl">
+6 <map:parameter name="ctxbasedir" value="{realpath:.}/"/>
+7 <map:parameter name="xmlbasedir" value="content/xdocs/{1}"/>
+8 </map:transform>
+9 <map:serialize type="fo2pdf"/>
+10 </map:match>
+ ]]></source>
+ <ol>
+ <li>The first line uses a matching regexp to break the URL into
+ directory <code>(.*?)</code> and filename
+ <code>([^/]*)</code> parts.</li>
+ <li>We then generate XML from a <link href="#source_pipelines">Source
+ pipeline</link>, with the URL <code>cocoon:/{1}{2}.xml</code></li>
+ <li>We then expand any XInclude statements..</li>
+ <li>and <link href="#linkrewriting_impl">rewrite links</link>..</li>
+ <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>
+ </section>
+ <section id="html">
+ <title>HTML output</title>
+ <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>
+ <source xml:space="preserve">
+ <map:match pattern="*.html">
+ <map:aggregate element="site">
+ <map:part src="<link href="#tab_pipeline">cocoon:/tab-{0}</link>"/>
+ <map:part src="<link href="#menu_pipeline">cocoon:/menu-{0}</link>"/>
+ <map:part src="<link href="#body_pipeline">cocoon:/body-{0}</link>"/>
+ </map:aggregate>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="site2xhtml"/>
+ <map:parameter name="path" value="{0}"/>
+ </map:call>
+ </map:match>
+ </source>
+ <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.
+ </p>
+ <p>
+ There is a nearly identical matcher for HTML files in subdirectories:
+ </p>
+ <source xml:space="preserve">
+ <map:match pattern="**/*.html">
+ <map:aggregate element="site">
+ <map:part src="<link href="#tab_pipeline">cocoon:/{1}/tab-{2}.html</link>"/>
+ <map:part src="<link href="#menu_pipeline">cocoon:/{1}/menu-{2}.html</link>"/>
+ <map:part src="<link href="#body_pipeline">cocoon:/{1}/body-{2}.html</link>"/>
+ </map:aggregate>
+ <map:call resource="skinit">
+ <map:parameter name="type"
+ value="site2xhtml"/>
+ <map:parameter name="path"
+ value="{0}"/>
+ </map:call>
+ </map:match>
+ </source>
+ </section>
+ </section>
+ <section id="intermediate_pipelines">
+ <title>Intermediate pipelines</title>
+ <section id="body_pipeline">
+ <title>Page body</title>
+ <p>Here is the matcher which generates the page body:</p>
+ <source xml:space="preserve"><![CDATA[
+1 <map:match pattern="**body-*.html">
+2 <map:generate src="cocoon:/{1}{2}.xml"/>
+3 <map:transform type="idgen"/>
+4 <map:transform type="xinclude"/>
+5 <map:transform type="]]>linkrewriter<![CDATA[" src="cocoon:/{1}linkmap-{2}.html"/>
+6 <map:call resource="skinit">
+7 <map:parameter name="type" value="document2html"/>
+8 <map:parameter name="path" value="{1}{2}.html"/>
+9 <map:parameter name="notoc" value="false"/>
+10 </map:call>
+11 </map:match>
+ ]]></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
+ <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>
+ <source xml:space="preserve">
+ <section>
+ <title>How to boil eggs</title>
+ ...
+ </source>
+ <p>into:</p>
+ <source xml:space="preserve">
+ <section id="How+to+boil+eggs">
+ <title>How to boil eggs</title>
+ ...
+ </source>
+ <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>
+ <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
+ HTML (minus the outer elements like
+ <html> and <body>) suitable for merging with the menu and tabs.</li>
+ </ol>
+ </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 xml:space="preserve"><![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"/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="book2menu"/>
+ <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>
+ </section>
+
+ <section id="tab_pipeline">
+ <title>Page tabs</title>
+ <p>Tab generation is quite tame compared to menus:</p>
+ <source xml:space="preserve"><![CDATA[
+ <map:match pattern="**tab-*.html">
+ <map:generate src="content/xdocs/tabs.xml" />
+ <map:transform type="]]>linkrewriter<![CDATA[" src="cocoon:/{1}linkmap-{2}.html"/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="tab2menu"/>
+ <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>
+ </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 xml:space="preserve"><![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.60//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
+ (described in <link href="site:v0.60//menu_generation">menu
+ generation</link>):</p>
+ <ul>
+ <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
+ "current" node.
+ </p>
+ <p>
+ For example, say our current page's path is
+ <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>site.xml</code>-derived content to contain only nodes with
+ <code>tab="howtos"</code>.
+ </p>
+ <p>
+ All this is done with XSLT, so the sitemap snippet does not
+ reveal this complexity:
+ </p>
+ <source xml:space="preserve"><![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
+ <code>XPathTransformer</code> to include only pages in the
+ current page's directory, or below:</p>
+ <source xml:space="preserve"><![CDATA[
+<map:transform type="xpath">
+ <map:parameter name="include" value="//*[@href='{1}']" />
+</map:transform>
+ ]]></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
+ include all nodes in that directory.
+ </p>
+ </li>
+ </ul>
+ <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>"
+ format, for compatibility with existing stylesheets, and this XML
+ format is returned (hence the name of the matcher:
+ <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 xml:space="preserve"><![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.60//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
+ generic Components which simply allow you to look up a value with a
+ 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
+ <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
+ 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
+ <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>
+ Using the above components, "<code>site:</code>" URI rewriting is
+ accomplished as follows.
+ </p>
+ <section id="cocoon_xconf">
+ <title>cocoon.xconf</title>
+ <p>First, we declare all the input modules we will be needing:</p>
+ <source xml:space="preserve"><![CDATA[
+<!-- For the site: scheme -->
+<component-instance
+ class="org.apache.cocoon.components.modules.input.XMLFileModule"
+ logger="core.modules.xml" name="linkmap"/>
+
+<!-- Links to URIs within the site -->
+<component-instance
+ class="org.apache.cocoon.components.modules.input.SimpleMappingMetaModule"
+ logger="core.modules.mapper" name="site"/>
+
+<!-- Links to external URIs, as distinct from 'site' URIs -->
+<component-instance
+ class="org.apache.cocoon.components.modules.input.SimpleMappingMetaModule"
+ logger="core.modules.mapper" name="ext"/>
+]]></source>
+ <ul>
+ <li><strong>linkmap</strong> will provide access to the contents of
+ site.xml; 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>
+ <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>
+ </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>
+ </section>
+
+ <section id="sitemap">
+ <title>sitemap.xmap</title>
+ <p>
+ Now in the sitemap, we define the LinkRewriterTransformer, and
+ insert it into any pipelines which deal with user-editable XML
+ content:
+ </p>
+ <source xml:space="preserve"><![CDATA[
+....
+<!-- Rewrites links, e.g. transforming
+ href="site:index" to href="../index.html"
+-->
+<map:transformer name="linkrewriter"
+ logger="sitemap.transformer.linkrewriter"
+ src="org.apache.cocoon.transformation.LinkRewriterTransformer">
+ <link-attrs>href src</link-attrs>
+ <schemes>site ext</schemes>
+
+ <input-module name="site">
+ <input-module name="linkmap">
+ <file src="{src}" reloadable="false" />
+ </input-module>
+ <prefix>/site//</prefix>
+ <suffix>/@href</suffix>
+ </input-module>
+ <input-module name="ext">
+ <input-module name="linkmap">
+ <file src="{src}" reloadable="false" />
+ </input-module>
+ <prefix>/site/external-refs//</prefix>
+ <suffix>/@href</suffix>
+ </input-module>
+</map:transformer>
+....
+....
+<map:match pattern="**body-*.html">
+ <map:generate src="cocoon:/{1}{2}.xml"/>
+ <map:transform type="idgen"/>
+ <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>
+ <ul>
+ <li>
+ <p>Most deeply nested, we have:</p>
+ <source xml:space="preserve"><![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
+ "<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
+ "<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 xml:space="preserve"><![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>
+ </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
+ by an XMLFileModule reading XML from
+ <code>cocoon:/community/linkmap-index.html</code>
+ </p>
+ </section>
+ <section id="dynamic_linkmap">
+ <title>Dynamically generating a linkmap</title>
+ <p>
+ Why do we need this "linkmap" pipeline generating dynamic XML from
+ site.xml, instead of just using site.xml 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
+ pipelines in <code>linkmap.xmap</code> ...
+ </p>
+ <source xml:space="preserve"><![CDATA[
+<!-- site.xml with @href's appended to be context-relative. -->
+<map:match pattern="abs-linkmap">
+ <map:generate src="content/xdocs/site.xml" />
+ <map:transform src="resources/stylesheets/absolutize-linkmap.xsl" />
+ <map:serialize type="xml" />
+</map:match>
+
+<!-- Linkmap for regular pages -->
+<map:match pattern="**linkmap-*">
+ <map:generate src="cocoon://abs-linkmap" />
+ <map:transform src="resources/stylesheets/relativize-linkmap.xsl">
+ <map:parameter name="path" value="{1}{2}" />
+ <map:parameter name="site-root" value="{conf:project-url}" />
+ </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
+ <link href="../abs-linkmap">abs-linkmap</link>).
+ </p>
+ </section>
+ </section>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/sitemap-ref.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/skin-package.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/skin-package.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/skin-package.source.xml (added)
+++ forrest/site/docs_0_60/skin-package.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ 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 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.
+ </p>
+
+ <p>
+To publish a skin:
+ </p>
+
+<source xml:space="preserve">
+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:
+ </p>
+
+<source xml:space="preserve">
+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"
+ </p>
+
+ <p>
+To see the names of the remote skins:
+ </p>
+
+<source xml:space="preserve">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.
+ </p>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/skin-package.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/skins.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/skins.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/skins.source.xml (added)
+++ forrest/site/docs_0_60/skins.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ 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 V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">
+<document>
+ <header>
+ <title>Default skins</title>
+ </header>
+ <body>
+ <section id="introduction">
+ <title>Introduction</title>
+ <p>
+ Forrest supplies a collection of default skins which are configurable
+ and so should meet the needs of most projects. The aim is to provide
+ many capabilities so that extra skins are not needed.
+ </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
+ <link href="http://svn.apache.org/repos/asf/forrest/trunk/src/core/context/skins/new-skin-names.txt">choosing skin names</link>.
+ 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</title>
+
+ <section id="pelt">
+ <title>pelt</title>
+ <p>
+ Uses CSS "div" and no HTML tables.
+ During its earlier development, this skin used to be called "css-style-dev".
+ </p>
+ </section>
+
+ <section id="leather-dev">
+ <title>leather-dev</title>
+ <p>
+ This is the evolution of the "pelt" skin, to have naming
+ conventions for css elements. It is still in development.
+ </p>
+ </section>
+
+ <section id="tigris">
+ <title>tigris</title>
+ <p>
+ This skin is based on version 1.1 of the
+ <link href="http://style.tigris.org/">style.tigris.org</link> project.
+ (It deliberately contravenes our skin naming convention.)
+ </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>
+ </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>
+ </section>
+
+ <section id="krysalis-site">
+ <title>krysalis-site</title>
+ <p>
+ Uses HTML tables.
+ </p>
+ </section>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/skins.source.xml
------------------------------------------------------------------------------
svn:eol-style = native