You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by je...@apache.org on 2003/07/13 14:19:22 UTC
cvs commit: xml-forrest/src/documentation/content/xdocs linking.xml
jefft 2003/07/13 05:19:22
Modified: src/documentation/content/xdocs linking.xml
Log:
Lots of updates, and move the Implementation section into a separate "sitemap
reference" page.
Revision Changes Path
1.7 +294 -457 xml-forrest/src/documentation/content/xdocs/linking.xml
Index: linking.xml
===================================================================
RCS file: /home/cvs/xml-forrest/src/documentation/content/xdocs/linking.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- linking.xml 5 Jun 2003 12:29:07 -0000 1.6
+++ linking.xml 13 Jul 2003 12:19:22 -0000 1.7
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
-"document-v11.dtd" [
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN"
+"document-v12.dtd" [
<!ENTITY a '<code>index.xml</code>'>
<!ENTITY b '<code>todo.xml</code>'>
<!ENTITY s '<code>site.xml</code>'>
@@ -37,9 +37,9 @@
<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, eg 'the FAQ page'</li>
- <li>A specific element (identified by <code>id</code> attribute) in an
- XML file.</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, &s;
@@ -52,9 +52,8 @@
</p>
<dl>
<dt><link href="#menu_generation">Menu generation</link></dt>
- <dd>&s; is used to generate the menus for the HTML website, replacing
- the old <code>book.xml</code> system</dd>
- <dt><link href="#semantic_linking">Semantic linking</link></dt>
+ <dd>&s; is used to generate the menus for the HTML website.</dd>
+ <dt><link href="#semantic_linking">Indirect linking</link></dt>
<dd>&s; provides a basic aliasing mechanism for linking, e.g. one
can write <link href="site:changes"> from anywhere in the site, and
link to the 'changes' information node (translated to changes.html).
@@ -66,7 +65,8 @@
</p>
<source><![CDATA[
<?xml version="1.0"?>
- <site label="Forrest" href="" xmlns="http://apache.org/forrest/linkmap/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"/>
@@ -80,9 +80,10 @@
<live-sites label="Live sites" href="live-sites.html"/>
</about>
- <community label="Community" href="community/">
+ <community label="Community" href="community/" tab="community">
<index label="About" href="index.html"/>
- <howto-samples label="How-To Samples" href="howto/">
+ <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"/>
<xmlform label="Multi-Page" href="xmlform/">
<intro label="Intro" href="howto-xmlform.html"/>
@@ -143,501 +144,337 @@
<section id="menu_generation">
<title>Generating Menus</title>
<p>
- If the &s; above were placed in
- <code>src/documentation/content/xdocs/</code>, the generated website
- would have a menu like this:
- </p>
- <figure src="images/menu.png" alt="Menu generated from site.xml"/>
- <p>
- As you can see, the elements without labels, like <new_content_type
- href="#adding_new_content_type"/>, and the <code>external-refs</code>
- section, are not displayed.
- </p>
- <p>
- Files in subdirectories are displayed with a menu local to that
- subdirectory:
- </p>
- <figure src="images/menu2.png" alt="Subdirectory menu generated from site.xml"/>
- <note>Yes, this truncating of the menu is annoying in many circumstances,
- and will be made configurable eventually. For now, to avoid generating
- truncated menus, edit sitemap.xmap, line 661 or thereabouts:
- <map:generate src="cocoon:/{dir}linkmap/{dir}"/> and remove the
- '/{dir}'. See <link href="#menus_from_site">here</link> for more info.
- </note>
- <section>
- <title>Overriding 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 &s;-generated menu. Not only does this
- preserve backwards-compatibility, it is sometimes necessary for sites
- whose content isn't strictly hierarchical, or where the &s;-generated
- menu isn't appropriate. <code>book.xml</code> files can use
- <code>site:</code> URIs to ease the maintenance burden that led to
- book.xml's obsolescence. In general however, we prefer to enhance the
- &s;-based solution than rely on <code>book.xml</code> hacks - please
- <link href="site:forrest-dev">let us know</link> if the &s; menu isn't
- meeting your use-case.
- </p>
- </section>
- </section>
-
- <section id="destination_linking">
- <title>The old system: destination 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 &a; wants to
- link to &b; then &a; would use
- </p>
- <source>
- <link href="todo.html">todo.html<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>] [<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 going to break.
- </p>
- </section>
-
- <section id="semantic_linking">
- <title>Semantic linking</title>
- <p>
- Forrest's solution is simple: instead of <link href="todo.html">, write
- <link href="site: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 &s;.</dd>
- </dl>
- <p>
- We call this <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.
+ Two files are used to define a site's tabs and menu; &s; 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> looked as follows:</p>
+ <source><![CDATA[
+<tabs ...>
+ <tab id="home" label="Home" dir=""/>
+ <tab id="community" label="Community" dir="community"/>
+ <tab id="howto" label="How-Tos" dir="community/howto"/>
+</tabs>
+ ]]></source>
+ <p>Using the &s; 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>
<section>
- <title>Resolving site: URIs</title>
-
- <p>
- How exactly 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 string <code>/site//todo/@href</code>. This is
- then used as an XPath expression in &s; identifying the string
- replacement, in this case <code>todo.html</code>.
- </p>
- <note>
- Actually, the XPath is applied to XML generated dynamically from
- &s;. The generated XML has @href's fully expanded ('absolutized')
- and ..'s added ('relativized') as needed.
- </note>
- <p>
- Thus by modifying the XPath prefix and suffix, just about any XML
- format can be accommodated.
- </p>
-
- <p>
- Notice that the '//' allows us any degree of specificity when linking.
- In the sample &s; 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 &s; 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.
+ <title>Selecting menu entries</title>
+ <p>Forrest decides which menu entries to display by examining the
+ <code>tab</code> attributes in &s;. All &s; entries with a
+ <code>tab</code> equal to that of the current page are put in the
+ menu.</p>
+ <p>Consider our &s; example:</p>
+ <source>
+<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"/>
+ <xmlform label="Multi-Page" href="xmlform/">
+ <intro label="Intro" href="howto-xmlform.html"/>
+ <step1 label="Step 1" href="step1.html"/>
+ ...</source>
+ <p>
+ Every &s; 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>.</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>
- <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. <code>ext:</code> URIs identify nodes in &s; below the
- <external-refs> node. By convention, nodes here link to URLs
- outside the website, and are not listed in the menu generated from
- &s;.
- </p>
- <p>Here is a &s; snippet illustrating <code>external-refs</code>:</p>
- <source><![CDATA[
- <site>
- ...
- <external-refs>
- <mail-archive href="http://marc.theaimsgroup.com"/>
- <xml.apache.org href="http://xml.apache.org/">
- <cocoon href="cocoon/">
- <ml href="mail-lists.html"/>
- <actions href="userdocs/concepts/actions.html"/>
- </cocoon>
- </xml.apache.org>
- <forrest href="forrest/"/>
- <xindice href="xindice/"/>
- <fop href="fop/"/>
-
- ...
- </external-refs>
- </site>
- ]]></source>
- <p>
- As an example, <link href="ext:cocoon/ml">
- generates the link <link
- href="ext:cocoon/ml">http://xml.apache.org/cocoon/mail-lists.html</link>
- </p>
+ <title>Alternative menu selection mechanisms.</title>
<p>
- The general rules of &s; and <code>site:</code> linking apply.
- Specifically, the @href aggregation makes defining large numbers of
- related URLs easy.
+ 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>
+ <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>
+ <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 &s;-generated menu. <code>book.xml</code>
+ files can use <code>site:</code> URIs to ease the maintenance burden
+ that led to book.xml's obsolescence. In general, however, we
+ recommend that users avoid <code>book.xml</code>.
+ </p>
+ </section>
</section>
<section>
- <title>Theory: source URIs</title>
+ <title>Selecting the current tab</title>
<p>
- <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 (ie, 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.
+ The tab selection algorithm is quite simple: the tab with the
+ <code>id</code> matching that of the current <code>site.xml</code>
+ node is "selected".
</p>
</section>
-
- <section>
- <title>Future schemes</title>
- <p>
- So far, <code>site:</code> and <code>ext:</code> schemes are defined.
- To give you some ideas on other things we'd like to implement (and
- we'd welcome help implementing), here are a few possibilities.
- </p>
- <table>
- <tr><td>Scheme</td><td>Example 'From'</td><td>Example 'To'</td><td>Description</td></tr>
- <tr>
- <td>java</td>
- <td>java:org.apache.proj.SomeClass</td>
- <td><code>../../apidocs/org/apache/proj/SomeClass.html</code></td>
- <td>
- Links to documentation for a Java class (typically generated by
- <code>javadoc</code>).
- </td>
- </tr>
- <tr>
- <td>mail</td>
- <td>mail::<Message-Id></td>
- <td><code>http://marc.theaimsgroup.com?t=12345678</code></td>
- <td>
- Links to an email, identified by its <code>Message-Id</code>
- header. Any mail archive website could be used.
- </td>
- </tr>
- <tr>
- <td>search</td>
- <td>search:<searchterm></td>
- <td><code>http://www.google.com/search?q=searchterm</code></td>
- <td>Link to set of results from a search engine</td>
- </tr>
- <tr>
- <td>person</td>
- <td>person:JT, person:JT/blog etc</td>
- <td><code>mailto:jefft<at>apache.org</code>,
- <code>http://www.webweavertech.com/jefft/weblog/</code>, etc:</td>
- <td>
- 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>, eg <code>task:pathconvert</code>.
- </p>
- </section>
</section>
-
- <section id="implementation">
- <title>Implementation</title>
- <p>
- This section describes how the menu and linking systems are currently
- implemented in Forrest. This is primarily of interest to Forrest
- developers, and users wishing to implement their own schemes.
- </p>
-
- <section>
- <title>Concept</title>
- <p>
- The <code>site:</code> scheme and associated ideas for &s; 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 &s; (section 4). However, what is currently implemented
- gains most of the advantages of the system.
+
+ <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 &a; wants to
+ link to &b; then &a; would use
+ </p>
+ <source>
+ <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>] [<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>
- <title>Cocoon foundations: Input Modules</title>
+ <section id="indirect-linking">
+ <title>Indirect linking</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.
+ Forrest's solution is simple: instead of <link href="todo.html">,
+ write <link href="site:todo">, where:
</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.
+ <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 &s;.</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>
- <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 was 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>.
- </p>
- </section>
- <section>
- <title>Implementing site: rewriting</title>
- <p>
- Using the above components, <code>site:</code> URI rewriting is
- accomplished as follows.
- </p>
<section>
- <title>cocoon.xconf</title>
- <p>
- First, we declare an XMLFileModule called 'linkmap'. This is going
- to provide access to the contents of &s;; for example,
- <code>linkmap:/site/about/index/@href</code> should return the value
- 'index.html'. We declare this InputModule in
- <code>WEB-INF/cocoon.xconf</code> with:
- </p>
- <source><![CDATA[
- <component-instance
- class="org.apache.cocoon.components.modules.input.XMLFileModule"
- logger="core.modules.xml" name="linkmap">
- <file src="cocoon:/linkmap"/>
- <reloadable>true</reloadable>
- </component-instance>
- ]]></source>
+ <title>Resolving site: URIs</title>
+
<p>
- An interesting point is that we tell XMLFileModule to use
- <em>dynamically generated XML</em> as its source. This allows us to
- transform &s; before the XPath is applied. These transformations
- are described below. Note that the <code>cocoon:/linkmap</code>
- specified here is a static configuration which will be overridden,
- as described below.
+ How exactly 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 string <code>/site//todo/@href</code>. This is
+ then used as an XPath expression in &s; identifying the string
+ replacement, in this case <code>todo.html</code>.
</p>
<p>
- To simplify things for the user, and to hide the structure of our
- XML, we now define a <em>mapping</em> module:
+ Thus by modifying the XPath prefix and suffix, just about any XML
+ format can be accommodated.
</p>
- <source><![CDATA[
- <!-- Links to URIs within the site -->
- <component-instance
- class="org.apache.cocoon.components.modules.input.SimpleMappingMetaModule"
- logger="core.modules.mapper" name="site">
- <input-module name="linkmap"/>
- <prefix>/site//</prefix>
- <suffix>/@href</suffix>
- </component-instance>
- ]]></source>
+ <note>
+ Actually, the XPath is applied to XML generated dynamically from
+ &s;. The generated XML has @href's fully expanded ('absolutized')
+ and ..'s added ('relativized') as needed.
+ </note>
+
<p>
- This module rewrites the key, and uses it to query the
- <code>linkmap</code> module. This means <code>site:index</code>
- is equivalent to <code>linkmap:/site//index/@href</code>.
+ Notice that the '//' allows us any degree of specificity when linking.
+ In the sample &s; 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 &s; 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>
- <p>The <code>ext</code> module is similarly defined: </p>
- <source><![CDATA[
- <!-- 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">
- <input-module name="linkmap"/>
- <prefix>/site/external-refs//</prefix>
- <suffix>/@href</suffix>
- </component-instance>
- ]]></source>
</section>
<section>
- <title>sitemap.xmap</title>
+ <title>ext: URIs: linking to external URLs</title>
<p>
- Now in the sitemap, we have to define the LinkRewriterTransformer,
- and insert it into any pipelines dealing with user-editable XML
- content:
+ The <code>ext:</code> scheme was created partly to demonstrate the
+ ease with which new schemes can be defined, and partly for practical
+ use. <code>ext:</code> URIs identify nodes in &s; below the
+ <external-refs> node. By convention, nodes here link to URLs
+ outside the website, and are not listed in the menu generated from
+ &s;.
</p>
+ <p>Here is a &s; snippet illustrating <code>external-refs</code>:</p>
<source><![CDATA[
- ....
- <map:transformer name="linkrewriter"
- src="org.apache.cocoon.transformation.LinkRewriterTransformer">
- <input-module name="linkmap" src="{src}" reloadable="true"/>
- <input-module name="site">
- <input-module name="linkmap" src="{src}"
- reloadable="true"/>
- <prefix>/site//</prefix>
- <suffix>/@href</suffix>
- </input-module>
- </map:transformer>
- ....
-
- <!-- Generates body HTML for files in subdirs -->
- <map:match pattern="body-**/*.xml">
- <map:generate src="content/xdocs/{1}/{2}.xml"/>
- <map:transform type="linkrewriter" src="cocoon:/{1}/linkmap"/>
- ....
- </map:match>
+ <site>
+ ...
+ <external-refs>
+ <mail-archive href="http://marc.theaimsgroup.com"/>
+ <xml.apache.org href="http://xml.apache.org/">
+ <cocoon href="cocoon/">
+ <ml href="mail-lists.html"/>
+ <actions href="userdocs/concepts/actions.html"/>
+ </cocoon>
+ </xml.apache.org>
+ <forrest href="forrest/"/>
+ <xindice href="xindice/"/>
+ <fop href="fop/"/>
+
+ ...
+ </external-refs>
+ </site>
]]></source>
-
<p>
- Why is the LinkRewriterTransformer reconfiguring the InputModules?
- Because we only know what XML to feed the XMLFileModule at request
- time. The XML is generated by the
- <code>cocoon:/{1}/linkmap</code> pipeline, and we don't know
- <code>{1}</code> until request time. Thus we need to effectively
- reconfigure the InputModule on every request. Fortunately
- InputModules are designed for this. They can be configured twice:
- once 'statically' in <code>cocoon.xconf</code>, and then
- 'dynamically' at the point of execution.
+ As an example, <link href="ext:cocoon/ml">
+ generates the link <link
+ href="ext:cocoon/ml">http://xml.apache.org/cocoon/mail-lists.html</link>
</p>
<p>
- The end result is that the source XML for sitemap request
- <code>body-community/index.xml</code> has its links rewritten by
- an XMLFileModule reading XML from
- <code>cocoon:/community/linkmap</code>.
+ The general rules of &s; and <code>site:</code> linking apply.
+ Specifically, the @href aggregation makes defining large numbers of
+ related URLs easy.
</p>
</section>
+
<section>
- <title>Dynamically generating a linkmap</title>
+ <title>Theory: source URIs</title>
<p>
- Why do we need this 'linkmap' pipeline generating dynamic XML from
- <code>site.xml</code>? The reasons are described in <link
- href="ext:linkmaps">the linkmap RT</link>: we need to concatenate
- @hrefs and add ..'s to the paths, depending on which directory the
- linkee is in. This is done with the following pipelines:
+ <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 (ie, 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>
- <source><![CDATA[
- <map:match pattern="abs-linkmap">
- <map:generate src="content/xdocs/site.xml"/>
- <map:transform src="library/xslt/absolutize-linkmap.xsl"/>
- <map:serialize type="xml"/>
- </map:match>
-
- <map:match pattern="**linkmap">
- <map:generate src="cocoon:/abs-linkmap"/>
- <map:transform src="library/xslt/relativize-linkmap.xsl">
- <map:parameter name="path" value="{0}"/>
- </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.</p>
</section>
- </section>
-
-
- <section id="menus_from_site">
- <title>Generating menus from site.xml</title>
- <p>
- The process of generating a HTML menu from &s; is fairly
- straightforward Cocoon work. It is currently implemented with these
- pipelines:
- </p>
- <source><![CDATA[
- <map:resource name="book">
- .... <!-- Stuff for using book.xml if present -->
- <!-- If no book.xml, generate it from the linkmap. -->
-
- <map:generate src="cocoon:/{dir}linkmap/{dir}"/>
- <!-- The above generates the subset of the linkmap relevant to our
- directory. -->
- <map:transform src="library/xslt/site2book.xsl"/>
- <map:call resource="skinit">
- <map:parameter name="type" value="book2menu"/>
- <map:parameter name="path" value="{path}"/>
- </map:call>
- </map:resource>
-
- .....
-
- <map:match pattern="abs-linkmap/**">
- <map:generate src="cocoon:/abs-linkmap"/>
- <map:transform type="xpath">
- <map:parameter name="include" value="//*[@href='{1}']"/>
- </map:transform>
- <map:serialize type="xml"/>
- </map:match>
-
- <map:match pattern="**linkmap/**">
- <map:generate src="cocoon:/abs-linkmap/{2}"/>
- <map:transform
- src="library/xslt/relativize-linkmap.xsl">
- <map:parameter name="path"
- value="{1}linkmap"/>
- </map:transform>
- <map:serialize type="xml"/>
- </map:match>
- ]]></source>
-
- <p>As with linking, we need to first 'absolutize' our &s; file by
- concatenating all @hrefs. This is done in
- <code>cocoon:/abs-linkmap</code>, shown in the previous section.
- The twist is that, for subdirectories, we only want to show the part
- of the menu relevant to that directory. We achieve this by filtering
- out everything except the node with a specific @href value, using an
- <link href="ext:xpathtransformer">XPathTransformer</link>. The
- <code>include</code> param is <code>//*[@href='{1}']</code>, where
- <code>{1}</code> will be replaced with the second <code>{dir}</code>
- in the line:
- <code><map:generate src="cocoon:/{dir}linkmap/{dir}"/></code>.
- This is why removing the '/{dir}' stops truncation of menus.
- </p>
- <p>
- The <code>site2book.xml</code> stylesheet generates
- <code>book.xml</code> XML, as expected by the subsequent
- <code>book2menu.xsl</code> stylesheet. In the future, this
- intermediate format can be removed.
- </p>
+ <section>
+ <title>Future schemes</title>
+ <p>
+ So far, <code>site:</code> and <code>ext:</code> schemes are defined.
+ To give you some ideas on other things we'd like to implement (and
+ we'd welcome help implementing), here are a few possibilities.
+ </p>
+ <table>
+ <tr><td>Scheme</td><td>Example 'From'</td><td>Example 'To'</td><td>Description</td></tr>
+ <tr>
+ <td>java</td>
+ <td>java:org.apache.proj.SomeClass</td>
+ <td><code>../../apidocs/org/apache/proj/SomeClass.html</code></td>
+ <td>
+ Links to documentation for a Java class (typically generated by
+ <code>javadoc</code>).
+ </td>
+ </tr>
+ <tr>
+ <td>mail</td>
+ <td>mail::<Message-Id></td>
+ <td><code>http://marc.theaimsgroup.com?t=12345678</code></td>
+ <td>
+ Links to an email, identified by its <code>Message-Id</code>
+ header. Any mail archive website could be used.
+ </td>
+ </tr>
+ <tr>
+ <td>search</td>
+ <td>search:<searchterm></td>
+ <td><code>http://www.google.com/search?q=searchterm</code></td>
+ <td>Link to set of results from a search engine</td>
+ </tr>
+ <tr>
+ <td>person</td>
+ <td>person:JT, person:JT/blog etc</td>
+ <td><code>mailto:jefft<at>apache.org</code>,
+ <code>http://www.webweavertech.com/jefft/weblog/</code>, etc:</td>
+ <td>
+ 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>, eg <code>task:pathconvert</code>.
+ </p>
+ </section>
</section>
-
+ </section>
+ <section>
+ <title>Concept</title>
+ <p>
+ The <code>site:</code> scheme and associated ideas for &s; 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 &s; (section 4). However, what is currently implemented
+ gains most of the advantages of the system.
+ </p>
+ </section>
+ <section>
+ <title>Implementation</title>
+ Full details on the implementation of <link
+ href="site:linkrewriting_impl">link rewriting</link> and <link
+ href="site:menu_generation_impl">menu generation</link>
</section>
</body>