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 [20/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/howt...
Added: forrest/site/docs_0_80/libre-intro.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/libre-intro.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/libre-intro.source.xml (added)
+++ forrest/site/docs_0_80/libre-intro.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,584 @@
+<?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>Libre QuickStart</title>
+ <abstract>This document is the current full documentation on the "libre"
+ generator that was implanted into xml-forrest.</abstract>
+ </header>
+ <body>
+ <section>
+ <title>Intro</title>
+ <warning>This document is still relevant for ideas and potential
+ solutions. However, the experimental code for Libre was removed from
+ the scratchpad on 2003-04-18 during spring cleaning. If you want to
+ resurrect it, then use the cvs tag "before_libre_departure".
+ </warning>
+ <p>The libre idea was born out of the cocoon book.xml itch. The actual
+ need to start scratching was introduced by the higher volume of
+ book.xml-editing-work that came along with the cocoon documentation and
+ xml-forrest efforts.</p>
+ <p>The single idea behind it in fact is trying to automatically generate
+ part of the navigation tree which is held now in the different book.xml 's.
+ This automation effort however is held back by the lack of meta-data you can
+ extract from the filesystem itself. This is why the libre approach still
+ requires you to add this extra metadata using some libre.xml file. This
+ libre.xml however has the following main advantages over the book.xml:</p>
+ <ul>
+ <li>The settings are 'inherited' down the directory tree, so you do not
+ need a libre.xml on each directory level. You only need it to change
+ the subdir traversing strategy from its parent dir.</li>
+ <li>It combines some 'filesystem-introspection'-like declarations
+ that are used in run-time filtering, sorting and attributing decisions.
+ Introspection strategies are currently based on either (1) reading properties
+ of the java.io.File object at hand, or (2) executing xpath expressions on the
+ pointed at XML file. </li>
+ </ul>
+ </section>
+ <section>
+ <title>Using Libre now (0.0 alfa)</title>
+ <warning>Disclaimer: most of what you read below is 'how it was intended'
+ . To what extent that matches the actual execution process is largely dependent
+ on my programming skills and thoroughness of testing. <br/>In other words:
+ don't expect a thing unless you've seen it work. (at this time)</warning>
+ <section>
+ <title>Generated Output</title>
+ <p>The XML output that comes out of the generator largely follows this
+ example:</p>
+ <source xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?>
+<collection xmlns="http://outerx.org/yer/hierarchy/0.1">
+ <collection label="content">
+ <collection label="xdocs">
+ <item label="dreams.xml"
+ href="src/documentation/content/xdocs/dreams.xml"
+ title="Forrest dream list"/>
+ <item label="faq.xml"
+ href="src/documentation/content/xdocs/faq.xml"/>
+ <item label="book.xml"
+ href="src/documentation/content/xdocs/book.xml"/>
+ <item label="contrib.xml"
+ href="src/documentation/content/xdocs/contrib.xml"
+ title="Contribution to Forrest"/>
+ <item label="mail-archives.xml"
+ href="src/documentation/content/xdocs/mail-archives.xml"
+ title="Mail Archives"/>
+ <item label="mail-lists.xml"
+ href="src/documentation/content/xdocs/mail-lists.xml"
+ title="Mailing Lists"/>
+ <item label="license.xml"
+ href="src/documentation/content/xdocs/license.xml"
+ title="The Apache Software License"/>
+ <item label="index.xml"
+ href="src/documentation/content/xdocs/index.xml"
+ title="Welcome to Forrest"/>
+ <item label="who.xml"
+ href="src/documentation/content/xdocs/who.xml"
+ title="Who we are"/>
+ </collection>
+ </collection>
+</collection></source>
+ <p>And it's not getting any harder in fact: only 2 elements,
+ <code><collection></code> and <code><item></code> and that should
+ do. The first maps to a menu-group in the navigation, guess what the second
+ maps to?</p>
+ <p>The number and value (and its meaning) of the attributes on these
+ elements are specified in the libre.xml file.</p>
+ </section>
+ <section>
+ <title><code>libre.xml</code> Contents</title>
+ <p>That libre.xml file follows the
+ src/resources/schema/dtd/libre-v10.dtd. In fact the current release allows for
+ some extra elements (I'll explain where) and some unrestricted attribute CDATA
+ types that cause some extensible xml output resp. some java-introspection to be
+ triggered. So basically the DTD will be limiting you more than the runtime
+ interpretation. (future versions will try to narrow this down seriously, main
+ reason is that a more elaborate DTD allows for more XML-editor assistance in
+ editing the files.)</p>
+ <p>The dtd:</p>
+ <source xml:space="preserve"><!ELEMENT libre (entry | auto)*>
+<!ELEMENT entry (label?, href?)>
+<!ATTLIST entry
+ location CDATA #REQUIRED
+>
+<!ELEMENT auto (filter?, sorter?, label?, href?)>
+<!ELEMENT label (xpath | property)>
+<!ELEMENT href (xpath | property)>
+<!ELEMENT filter (xpath | property)>
+<!ATTLIST filter
+ logic (inverse | normal) "normal"
+ clear (yes | no) "no"
+>
+<!ELEMENT sorter (xpath | property)>
+<!ATTLIST sorter
+ order (ascending | descending) "ascending"
+ clear (yes | no) "no"
+>
+<!ELEMENT xpath EMPTY>
+<!ATTLIST xpath
+ expression CDATA #REQUIRED
+>
+<!ELEMENT property EMPTY>
+<!ATTLIST property
+ name CDATA #REQUIRED
+ mask CDATA #IMPLIED
+ regex CDATA #IMPLIED
+ substitute CDATA #IMPLIED
+></source>
+ <section>
+ <title>Building Blocks</title>
+ <p>The following elements get the following meaning when interpreted
+ by the LibreConfigBuilder</p>
+ <source xml:space="preserve"><libre xmlns="http://outerx.org/libre/config/0.1"></source>
+ <ul>
+ <li>This is one of those libre.xml files, that will configure how
+ items are filteres, sorted and attributed</li>
+ </ul>
+ <source xml:space="preserve"><entry location="[relative location path]" /></source>
+ <ul>
+ <li>Allows to manually sort out specific files or directories.</li>
+
+ <li>Comparable to standard book.xml behaviour, except for the fact
+ that </li>
+ <ul>
+ <li>libre doesn't yet support external hrefs (should be easy
+ though)</li>
+ <li>there is no difference between <code><menu></code> and
+ <code><menu-item></code>, there just is <code><entry></code>. It
+ will become a <code><collection></code> or <code><item></code> in
+ the output based on the fact if the location points to a directory resp. a
+ file.</li>
+ <li>For locations that point to a filter it doesn't make sense, but
+ when it points to a directory it is nested <code><filter></code> and
+ <code><sort></code> elements get inherited down to the next level. </li>
+ </ul>
+ </ul>
+ <fixme author="mpo">This last remarks actually means (1) I need to
+ update the DTD to reflect this and (2) check the code for actually doing
+ this.</fixme>
+ <source xml:space="preserve"><auto></source>
+ <ul>
+ <li>Automatically generates more <code><collection></code>
+ and <code><item></code> elements in the output, based on the
+ specifications of the nested elements: <code><filter></code> (which
+ resources?) and <code><sort></code> (in which order?).</li>
+ </ul>
+ <source xml:space="preserve"><filter logic="inverse" clear="no"></source>
+ <ul>
+ <li>This element wraps a so-called AttributeReader (there are
+ currently two of them: <code><xpath></code> and
+ <code><property></code>)</li>
+ <li>The AttributeReader is going to specify which
+ information-element is going to be retrieved from the file or directory it is
+ pointing at. Depending on which one is used this wrapping filter will test for
+ presence or regex match of the resource being read. Based on the outcome of
+ this test (true or false) the passed file will be accepted or not in the
+ list.</li>
+ <li>This wrapping filter element allows to inverse the
+ acceptance-logic (accept what normally should be rejected and vice versa).</li>
+
+ <li>Using the <code>clear="yes"</code> attribute stops the
+ inheritance of the used filter strategy from the parent directory. Instead the
+ default filter strategy (which is to accept all files) is slided in at this
+ level.</li>
+ </ul>
+ <source xml:space="preserve"><sort order="descending" clear="no"></source>
+ <ul>
+ <li>This element wraps a so called AttributeReader (there are
+ currently two of them: <code><xpath></code> and
+ <code><property></code>).</li>
+ <li>The AttributeReader is going to specify which
+ information-element is going to be retrieved from the file or directory it is
+ pointing at. This information element will be considered to be a simple
+ Key-String and <code><collection></code> and <code><item></code>
+ elements in the output will appear in the order defined by the alphabetic
+ sorting of these keys.</li>
+ <li>This wrapping sort element allows to reverse the order.
+ (z->a instead of a->z)</li>
+ <li>Using the <code>clear="yes"</code> attribute stops the
+ inheritance of the used sort strategy from the parent directory. Instead the
+ default sort strategy (which is to use default filesystem sorting, alphabetic
+ on filename) is slided in at this level.</li>
+ </ul>
+ <source xml:space="preserve"><label>, <href>, <YOURTAG>.... {AttributeDefinitions}</source>
+ <ul>
+ <li>The remainder of the elements inside the
+ <code><auto></code> tag specify the attributes that need to be applied to
+ the generated <code><collection></code> and <code><item></code>
+ elements in the output: <code><item label=".." href=".." YOURTAG=".."
+ /></code></li>
+ <li>There is currently only support for adding attributes, not
+ nested elements.</li>
+ <li>These elements all wrap a so called AttributeReader (there are
+ currently two of them: <xpath> and <property>)</li>
+ <li>In these cases the wrapped AttributeReader is going to specify
+ which information-element is going to be retrieved from the file or directory
+ it is pointing at. This information element will be considered to be a simple
+ String-value that gets slided in as the corresponding output attribute
+ value.</li>
+ </ul>
+ <source xml:space="preserve"><xpath expression="/document/header/title/text()"></source>
+ <ul>
+ <li>This element specifies an xpath AttributeReader to use inside
+ <code><filter></code>, <code><sort></code> or
+ {AttributeDefinitions}.</li>
+ <li>It allows to specify an xpath expression that should result in
+ one single text node to be returned when applied to the root node of the xml
+ file at the location of any given entry. The contents of this text-node is the
+ string value to sort (<code><sort></code> usage) or to fill in the
+ specified attribute (<code><label></code>, <code><href></code>...
+ use). When inside a <code><filter></code>: the presence of the node
+ results in passing the test.</li>
+ </ul>
+ <warning>This currently breaks for non xml (<code>*.gif</code>)
+ files, so get your filter right please, and in the mean time: sorry for not
+ being able to use it in the filter yet <code>:-(</code>.</warning>
+ <source xml:space="preserve"><property name="path" regex="(\.[\\/])*(.*)" substitute="$2"/>
+<property name="name" mask="CVS"/></source>
+ <ul>
+ <li>This element specifies an xpath AttributeReader to use inside
+ <code><filter></code>, <code><sort></code> or
+ {AttributeDefinitions}.</li>
+ <li>It allows to specify a JavaBean-like property to read (this
+ introspection behavior will probably not survive the future release) on the
+ file at the 'location' of any given entry. The (object-)value of this property
+ is automatically converted to a String (toString()) that becomes the value to
+ sort (<code><sort></code> usage) or to fill in the specified attribute
+ (<code><label></code>, <code><href></code>... use). When inside a
+ <code><filter></code>, the test passes if the read property is not null
+ or "".</li>
+ <li>Furthermore this element allows to express more elaborate
+ true-false tests (filter use) or regex substitution (other use)
+ attributes:</li>
+ <ul>
+ <li>combination of @regex with @substitute accounts for a
+ s/{regex}/{substitute}/ kind of operation on the string property.</li>
+ <li>while @mask or @regex by their own (filter use) allow for a
+ glob-mask or regex test to be applied on the read property.</li>
+ </ul>
+ </ul>
+ </section>
+ </section>
+ <section>
+ <title>Important Side Effects</title>
+ <p>There are some things that libre is doing that you should be aware of.</p>
+ <section>
+ <title>No libre.xml</title>
+ <p>When using an <code><auto> </code>section, the filter will
+ NEVER accept the <code>libre.xml</code> file to be in the generated output. You
+ can however include a manual <code><entry></code> to point to the
+ <code>libre.xml</code> file if needed.</p>
+ </section>
+ <section>
+ <title>No Duplicates</title>
+ <p>You can combine multiple <code><entry></code> and
+ <code><auto></code> elements after each other. The system will make sure
+ that the resulting list of <code><collection></code> and
+ <code><item></code> will not contain duplicates. So the filters in
+ <code><auto></code> sections lower down the <code>libre.xml</code> file
+ can include already accepted files or directories, they will only show up once
+ in the output.</p>
+ </section>
+ </section>
+ <section>
+ <title>Example Constructs</title>
+ <p>Adding sorting and filtering to the filesystem with libre becomes a
+ subtle play with editable filesystem properties, smart XML content and
+ <code>libre.xml</code> configs. This should be considered as the 'extended'
+ contract between the following roles in the documentation system: the one
+ choosing (or creating) the DTDs, the one applying those to create content and
+ give the resulting files a name, the one that sets up the directories to store
+ those files and writes the <code>libre.xml</code> files.</p>
+ <section>
+ <title>Sorting your files or your menu entries?</title>
+ <p>In every case the very pragmatic approach can become something
+ like this:</p>
+ <source xml:space="preserve">+ content
+ + xdocs
+ + 010Topic
+ + 010Foo
+ + 111Bar
+ + 050Aspect
+ + NotInList</source>
+ <p>In combination with something that lives by the introduced
+ alphabetic order, but yet hides the ugly number-prefixes:</p>
+ <source xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE libre PUBLIC "-//Outerthought//DTD Libre Configuration V0.1//EN" "libre-v01.dtd" >
+<libre xmlns="http://outerx.org/libre/config/0.1">
+ <auto>
+ <filter logic="normal">
+ <property name="name" regex="\d{3}(.*)"/>
+ </filter>
+ <label>
+ <property name="name" regex="\d{3}(.*)" substitute="$1"/>
+ </label>
+ </auto>
+</libre></source>
+ <p>Will produce an automatic list of entries (collections and items
+ in the output) that </p>
+ <ul>
+ <li><code><filter></code>: only resources which name starts
+ with a 3-digit pattern</li>
+ <li>No <code><sort></code>: in their natural filesystem order
+ assured by the digit-prefix</li>
+ <li><code><label></code>: hold a label attribute that strips
+ of the ugly number prefix</li>
+ </ul>
+ <p>Of course the advantage over book.xml only comes when more menu
+ items should be easily slided in later on, and/or deeply nested directory
+ structures can all benefit from this same filenaming/sorting strategy.</p>
+ </section>
+ <section>
+ <title>Naming your files or asking them their name?</title>
+ <p>Given the poor expressiveness of the filesystem, the labels that
+ need to show up in the menu can hardly remain the filenames they are now
+ (specially if we're adding these ugly number prefixes). Instead we can sign a
+ contract with the content writer to also provide the navigation system with a
+ sensible name for his entry using XML metadata that the system will pick up
+ using an xpath expression.</p>
+ <source xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE libre PUBLIC "-//Outerthought//DTD Libre Configuration V0.1//EN" "libre-v01.dtd" >
+<libre xmlns="http://outerx.org/libre/config/0.1">
+ <entry location="dreams.xml" >
+ <label>
+ <xpath expression="/document/header/title/text()"/>
+ </label>
+ </entry>
+ <auto>
+ <filter>
+ <property name="name" regex="\.xml$" />
+ </filter>
+ <sorter>
+ <xpath expression="/document/header/title/text()"/>
+ </sorter>
+ <label>
+ <xpath expression="/document/header/title/text()"/>
+ </label>
+ </auto>
+</libre></source>
+ </section>
+ </section>
+ </section>
+ <section>
+ <title>Next Libre (0.1)</title>
+ <note>Next libre is in fact largely in your hands... just drop
+ the forrest-dev <link href="site:mail-lists">mail list</link>
+ a line, and see what happens...</note>
+ <section>
+ <title>Itches</title>
+ <p>There is quite a number of fast code patches that can/need to
+ happen</p>
+ <ul>
+ <li>package renaming and restructuring (ideas welcome, but not top of
+ mind)</li>
+ <li>on same level: possible xmlns and/or elms/atts renaming on the
+ generated output and the libre.xml file</li>
+ <li>when compiling you currently get 4 stupid deprecation warnings
+ that should be removed, in fact:</li>
+ <li>LibreConfigHelper has a silly test in it to switch to own parser
+ and resolver if there is no avalon component manager in the neighborhoud
+ (historical reason is the testing outside cocoon with the command line util,
+ which should become some kind of avalon based junit task: if you have a clue
+ how to start this, throw it at us please.)</li>
+ <li>xpath property reader needs to survive working on a non-xml
+ document (by returning nothing rather then breaking on the exception)</li>
+ <li>general robustness and resilience towards
+ mis-configurations</li>
+ <li>filestreams need to get closed and avalon resources need to be
+ released properly</li>
+ <li>caching at the level of the generator needs to be set up</li>
+ <li>in fact general performance has not been subject to loads of
+ early optimizations :-P</li>
+ </ul>
+ </section>
+ <section>
+ <title>Upcoming Features</title>
+ <p>More importantly however there is a major set of new features that
+ is waiting to get in there. It all boils down in fact to having a more
+ expressive libre.xml file... some of the thoughts:</p>
+ <section>
+ <title>Combinations of filter logic</title>
+ <p>Some itching stuff:</p>
+ <ul>
+ <li>logic="inverse" on the <filter> element seems a bit
+ awkward</li>
+ <li><em>n</em>th degree of slickness in the regexes will only bring
+ us so far, combinatory filter logic seems to be the way to go...:</li>
+ </ul>
+ <source xml:space="preserve"><!ELEMENT filter (xpath | property | and | or | not)>
+<!ELEMENT not (xpath | property | and | or | not)>
+<!ELEMENT and (xpath | property | and | or | not)+>
+<!ELEMENT or (xpath | property | and | or | not)+></source>
+ <p>So we can make up some richer:</p>
+ <source xml:space="preserve">
+<filter>
+ <not>
+ <and>
+ <xpath .../>
+ <not><property ..../></not>
+ <or>
+ ...
+ </or>
+ </and>
+ </not>
+</filter>
+ </source>
+ </section>
+ <section>
+ <title>Separating property-retrieval from formatting and
+ testing</title>
+ <p>Playing around with the attributes in
+ <code><property></code>:</p>
+ <ul>
+ <li>poses hard to explain combinatory effects (@regex with
+ @substitute vs without, @regex can't be combined with @mask, different
+ behaviour inside <filter>== test or <sort>==formatting)</li>
+ <li>which in fact are hard (if not impossible) to rule out by
+ modifying the DTD</li>
+ <li>makes you wonder why it's not available on the <xpath>
+ ?</li>
+ </ul>
+ <p>So maybe an example more down the lines of the following would be
+ easier to use:</p>
+ <source xml:space="preserve"><label><!-- same applies for the sort context -->
+ <regexformatter exp="..." substitute="....">
+ <property name="absoluteLocation" />
+ </regexformatter>
+</label></source>
+ <p>Allowing the formatter to be used around the xpath reader as well.
+ And opening up the possibility to maybe format other stuff than Strings:
+ <code><dateformat format="dd/mmm/yy"> </code></p>
+ <p>It would also clearly distinguish the semantical difference of
+ applying a test in the <code><filter></code> context:</p>
+ <source xml:space="preserve"><filter>
+ <regextest match="...">
+ <property ... />
+ </regextest>
+</filter></source>
+ <p>And more logically introduce other tests like <code><globtest
+ match="..."></code> or <code><availabletest></code> or...</p>
+ </section>
+ <section>
+ <title>Replace the introspection with semantically richer named
+ properties to read.</title>
+ <p>Currently the <code><property
+ name="someJavaBeanProp"></code> is applied in a java introspection for the
+ <code>getSomeJavaBeanProp()</code> on the <code>java.io.File</code> object that
+ is actually representing the node in the hierarchy at any given time. The DTD
+ declares the attribute as of type CDATA. These decisions however:</p>
+ <ul>
+ <li>lead to a lesser user guidance for the libre.xml writer using
+ an XML (and DTD) savvy editor </li>
+ <li>leads to assuming the <code>libre.xml</code> editor has access
+ to and knows how to interpret jdk javadoc</li>
+ <li>leads to poor semantical support and thus more possible RUNTIME
+ errors for those just filling in some valid CDATA value that is not mapping any
+ getter.</li>
+ <li>leads to confusion for all, since who actually knows the subtle
+ difference between all the get*Path methods on java.io.File?</li>
+ </ul>
+ <p>So the big idea here would be to go for an upfront declared list
+ of sensible and clearly defined properties that we would like to
+ read... Today's ideas about that list:</p>
+ <ul>
+ <li>name</li>
+ <li>isDirectory (isCollection?)</li>
+ <li>abs and relPath (or abs/rel Location? why would we need
+ abs?)</li>
+ <li>canRead</li>
+ <li>canWrite</li>
+ <li>lastModified</li>
+ <li>length</li>
+ </ul>
+ <p>The DTD would then list the possible attributeValues.</p>
+ </section>
+ </section>
+ <section>
+ <title>Avalonising</title>
+ <p>There are a number of perceived opportunities in taking up a
+ stronger dependecy towards Avalon. Some of the possibilities become clear when
+ looking into the current design...</p>
+ <ul>
+ <li>Currently the EntryFactory is a abstract factory, the factory
+ part could be done by an Avalon Component manager. Which would also allow the
+ EntryFactory to become a cleaner component interface then it is now.</li>
+ <li>Some investigation/feedback on the current hacker-way of using
+ the Composables could be nice</li>
+ <li>The current cli part in the package is only there for testing
+ (avoiding the cocoon webapp cycle when developing/testing) it should be
+ replaced by a more formal test class that actually would take up the role
+ (probably delegate to ECM or the like) of the componentmanager to give the
+ HierarchyReader the (avalon) environment he needs.</li>
+ </ul>
+ </section>
+ <section>
+ <title>Unresolved Discussions</title>
+ <ul>
+ <li>do we need support for nested elements inside
+ <code><item></code> output (retrieved by e.g. xpath expressions)?</li>
+ <li>do we need an extra <code><constant></code> like
+ attributereader that would allow like book.xml to add fixed values for
+ expressed attributes</li>
+ <li>clear set out inheritance rules, just doing 'something' now
+ :-(</li>
+ <li>votes on needed file properties to replace the current (limiting
+ and semantically poor) Java-introspection</li>
+ </ul>
+ </section>
+ </section>
+ <section>
+ <title>Libre Design</title>
+ <p> So why is that silly 'yer' package name in there? Yer originally was
+ some all-hierarchy-structures to SAX event thing, and since some of that is in
+ here as well, we kind of picked that idea up out of the dustbin.</p>
+ <p>So reflecting the current packagenames we kind of have these sets of
+ responsibilities</p>
+ <ul>
+ <li><em>*.yer.hierarchy</em>: describe in a formal way how hierarchies
+ should be built up in order to have them dumped to XML using the
+ HierarchyReader.</li>
+ <li><em>*.yer.use.cocoon</em>:house of the generator. It basically just
+ gets a reader and subscribes the next ContentHandler in the cocoon pipeline to
+ the HierarchyReader that it is using.</li>
+ <li><em>*.yer.impl</em>: hold the different implementations of the
+ *.yer.hierarchy API </li>
+ <li><em>*.yer.impl.fs</em>: (only current impl) Build the described
+ filesystem oriented implementation of the hierarchy. It is using the libre
+ configuration strategy.</li>
+ <li><em>*.yer.libre</em>: provide a generic strategy for adding
+ filtering, sorting and attributing information to a hierarchy through the use
+ of XML config files (in an XML configuration/declarative manner)</li>
+ </ul>
+ <p>... hope this somewhat clarifies how things have been setup for
+ now.</p>
+ <section>
+ <title>Dependencies</title>
+ <ul>
+ <li>The regex stuff inside libre adds the dependency upon the oro
+ package. Basically I failed to find substitution support inside the regex
+ package (which is already in cocoon) in a timeframe comparable to just get on
+ with this using oro.</li>
+ <li>The HierarchyGenerator is the first one in the chain (and the
+ last in fact) that actually needs the cocoon package (at least it was intended
+ this way, could be that there are some glitches on this statement)</li>
+ <li>There is a sort of false dependency on Avalon right now (some
+ Composables in there, no real container stuff though). As expressed higher
+ there are some plans to stronger benefit from this dependency. </li>
+ </ul>
+ </section>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_80/libre-intro.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_80/linking.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/linking.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/linking.source.xml (added)
+++ forrest/site/docs_0_80/linking.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,602 @@
+<?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="#indirect-linking">Indirect linking</link></dt>
+ <dd>site.xml provides a basic aliasing mechanism for linking, e.g. one
+ can write <link href="site:v0.80//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 ...
+ </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>
+ <p>
+ See another <link href="site:v0.80//faq/site-xml">explained example</link>.
+ </p>
+ </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 site.xml
+ node is "selected". However the interaction of tabs.xml and site.xml
+ while powerful, can be complex to establish.
+ </p>
+ </section>
+
+ <section id="tab-site">
+ <title>Configuring the interaction between tabs.xml and site.xml</title>
+ <p>
+ This is a collection of tips to assist with getting your menus and tabs
+ to properly display.
+ </p>
+ <ul>
+ <li>
+ View your site's
+ <link href="../abs-menulinks">abs-menulinks</link> pipeline in a
+ browser. This is part of the internal Cocoon machinery, but like
+ other sitemap resources, it is useful to view them to assist with
+ debugging.
+ </li>
+ <li>
+ The Forrest website also accompanies your software release
+ in the <code>site-author</code> directory, so
+ inspect its tabs.xml and site.xml to see how it is done. Also see the
+ 'forrest seed site' example. It is not as complex as the Forrest website.
+ </li>
+ <li>
+ When you are fiddling with your attributes, change one thing at a time
+ and document what you have changed.</li>
+ <li>
+ The value of the tab @id attribute cannot begin with a digit.
+ Likewise, element names in tabs.xml and site.xml cannot begin with a digit.
+ </li>
+ <li>
+ Add label attributes to site.xml elements to make the menus show.
+ With nested elements in site.xml if the outer element does not have a label
+ attribute then the inner elements will not be displayed.
+ </li>
+ <li>
+ To cause tabs and menu items to be highlighted, there need to be
+ corresponding elements in site.xml that have href attributes which match
+ the relevant path.
+ </li>
+ <li>
+ When the tab points to a directory, then to make the tab highlighted
+ when selected, you need an element which matches index.html within the
+ group of elements that define the menus for this tab in the site.xml
+ file. That element can be without a label attribute, so that it doesn't
+ display as a menu item. However doing that causes that tab's menus
+ to be collapsed.
+ </li>
+ <li>
+ Q: The tab link in my site assumes that 'index.html'
+ is present in the linked-to directory. How do I fix this?
+ A: In tabs.xml use @href instead of @dir attribute and omit the trailing '/'.
+ Which file to serve is then a concern of the sitemap.
+ See more at the <link href="site:v0.80//faq/tab-index">FAQ</link>.
+ </li>
+ </ul>
+ </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">
+ <a href="todo.html">to-do list<a>
+ </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 <a href="todo.html">,
+ write <a href="site:v0.80//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:v0.80//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:v0.80//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, <a href="ext:commons/resolver">
+ generates the link
+ <link href="ext:commons/resolver">http://xml.apache.org/commons/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:v0.80//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.80//linkrewriting_impl">link rewriting</link> and
+ <link href="site:v0.80//menu_generation_impl">menu generation</link> are available in
+ the <link href="site:v0.80//sitemap-ref">Sitemap Reference</link></p>
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_80/linking.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_80/locationmap.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/locationmap.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/locationmap.source.xml (added)
+++ forrest/site/docs_0_80/locationmap.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,280 @@
+<?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>Locationmaps</title>
+ </header>
+ <body>
+ <section id="overview">
+ <title>About Locationmaps</title>
+ <p>A locationmap defines a mapping from requests to location strings.</p>
+
+ <p>It was conceived to:</p>
+
+ <ul>
+ <li>Provide a more powerful means for semantic linking.</li>
+ <li>Enable Forrest with a standard configuration override mechanism.</li>
+ <li>Decouple the conceptual source space used by Cocoon from
+ the concrete source space, so that a change in the concrete sources
+ does not impact on the sitemap.</li>
+ </ul>
+
+ <p>In other words, the locationmap enables content to be retrieved from a location
+ that is defined in a locationmap file (located at
+ <code>PROJECT_HOME/src/documentation/content/locationmap.xml</code> file. The
+ advantage of this is that the URL seen by the user need bear no relation to the location
+ of the source document, thus Forrest can separate the client URL space from the source
+ document URL space. Thus, using the locationmap it is possible to pull together
+ documents from many different locations into a single uniform site.</p>
+
+ <p>In addition, since the user URL space is now not connected to the source URL space
+ it is possible to move source documents without breaking any existing user links.</p>
+
+ <p>The syntax of a locationmap resembles that of the sitemap, in that it also makes use
+ of Matchers and Selectors to traverse a tree of nodes towards a leaf. In the case of
+ the locationmap however the leaf does not identify a pipeline, but instead identifies
+ a location string.</p>
+
+ <p>Apache Forrest looks in the standard location for the source file first (by default
+ <code>PROJECT_HOME/src/documentation/content/...</code>), if a file is found in this
+ location then the locationmap is not consulted. However, if one is not found then the
+ locationmap is used to resolve the source file. The locationmap is resolved via the
+ core sitemap, this means that you can generate it dynamically if you so wish. Simply
+ add a match that looks something like this to your projects sitemap:</p>
+
+ <source xml:space="preserve">
+ <map:match pattern="locationmap-project.xml">
+ <map:generate src="..."/>
+ <map:transform src="..."/>
+ <map:serialize type="xml"/>
+ </map:match>
+ </source>
+
+ </section>
+
+ <section id="namingConvention">
+ <title>Naming Convention</title>
+ <p>For those that are familiar with name
+ resolution servers or the Handles Service, it might be easier to think of the
+ locationmap as a name resolution module or sort of a handle resolution module
+ that it accepts "names" or whatever you desire to call these "hints" and
+ returns the location.</p>
+
+ <p>The thought is that by using hints that look a little like a
+ file name it disguises what locationmaps are really doing for us.
+ By using URN-style names, we are truly
+ disassociating the name/hint from the physical location.</p>
+
+ <p>For example, here is a locationmap entry based purely on filename:</p>
+
+ <source xml:space="preserve">
+<map:transform src="{lm:xhtml2html.xsl}"/>
+ </source>
+
+ <p>and here is that same entry using a "name" style. One implies
+ a certain physical location where as the one below is truly a name that
+ needs to be resolved to a physical location.</p>
+
+ <source xml:space="preserve">
+<map:transform src="{lm:transform.xhtml2.html}"/>
+ </source>
+
+ <p>Where the resource is provided by a plugin rather than Forrest itself
+ this is prefixed with the last part of the plugin name. For example:</p>
+
+ <source xml:space="preserve">
+<map:transform src="{lm:projectInfo.transform.doap.html}"/>
+ </source>
+
+ <p>The format is essentially one of:</p>
+
+ <source xml:space="preserve">
+[PLUGIN_NAME.]resource-type(dot)from-format(dot)to-format
+ </source>
+ <p>or</p>
+ <source xml:space="preserve">
+[PLUGIN_NAME.]resource-type(dot)type(dot)name
+ </source>
+
+ <p>Examples of these two:</p>
+ <source xml:space="preserve">
+transform.transform.xthml2.html
+graphic.png.project-logo
+projectInfo.transform.changes.rss
+ </source>
+ </section>
+
+ <section id="selector">
+ <title>Multiple Location Selectors</title>
+ <p>You can define multiple possble locations for a file in the locationmap
+ with the following code:</p>
+
+ <source xml:space="preserve">
+<match pattern="tabs.xml">
+ <select type="exists">
+ <location src="{project:content.xdocs}tabs1.xml"/>
+ <location src="{project:content.xdocs}tabs2.xml"/>
+ </select>
+</match>
+ </source>
+
+ <p>Each location will be tested in turn, if the file exists then it will be returned
+ as a match, otherwise testing will continue.</p>
+ </section>
+
+ <section id="examples">
+ <title>Locationmap Examples</title>
+ <section id="source-via-http">
+ <title>Retrieving an XDoc via HTTP</title>
+
+
+ <p>Normally files are generated from <code>{project:content.xdocs}</code>.
+ Using the Locationmap it is possible to make these files come from elsewhere.
+ This is useful if you want to pull files from different directory structures,
+ or even remote repositories. For example, the following location match
+ will match any request for a document below "remoteDemo" and will retrieve
+ the source file from the Apache Forrest SVN repository (directly from the
+ ASF's SVN webserver). This
+ is an ideal way to ensure that your published docs are always up-to-date.</p>
+
+ <source xml:space="preserve">
+ <match pattern="remoteDemo/**.xml">
+ <location src="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/xdocs/{1}.xml" />
+ </match>
+ </source>
+
+ <p>Note that because this is a wildcard matcher you can request any page
+ from the svn server simply by requesting
+ <code>/remoteDemo/PATH/TO/FILE/FILENAME.html</code>. In addition, we
+ can request any other output format available via Forrest plugins.</p>
+
+ <p>When including resources from remote repositories one has to
+ be careful about things like <code>site</code> and <code>ext</code>
+ linking. If the targets are not defined in the local
+ <code>site.xml</code> file then these links will be broken.</p>
+
+ <warning>Because of the above limitation many of the links in the
+ page generated from the above example are broken.</warning>
+
+ </section>
+
+ <section id="source-from-remote-cms">
+ <title>Retrieving HTML from a CMS</title>
+
+ <p>Using the locationmap you can use Forrest to retrieve data from a
+ Content Management System (CMS), wither local or remote.
+ As an example we will consider Apache Lenya.</p>
+
+ <p><link href="http://lenya.apache.org">Apache Lenya</link> is a Java Open-Source Content Management System based
+ on open standards such as XML and XSLT and the Apache Software Stack, in particular the XML publishing
+ framework Apache Cocoon.</p>
+
+ <p>The following locationmap matcher will instruct Forrest to retrieve content from
+ <code>http://lenya.zones.apache.org:8888/default/live/*.html?raw=true</code>, whenever a local URL of
+ <code>lenya/**</code> is encountered.</p>
+
+ <source xml:space="preserve">
+ <match pattern="lenya/**.xml">
+ <location src="http://lenya.zones.apache.org:8888/default/live/{1}.html?raw=true" />
+ </match>
+ </source>
+
+ <p>However, since the source returned by this match is HTML and not XDoc we must convert this
+ to our internal XDoc format before we can use it. We do this by adding the match below to our
+ project's <code>sitemap.xmap</code> file.</p>
+
+ <source xml:space="preserve">
+<map:match pattern="lenya/**.xml">
+ <map:generate type="html" src="{lm:{0}}" />
+ <map:transform src="{forrest:stylesheets}/html2document.xsl" />
+ <map:serialize type="xml"/>
+</map:match>
+ </source>
+
+ <p>Since this snippet uses the HTML generator you must also ensure that your sitemap has the HTML generator
+ component defined. That is, your sitemap must also include:</p>
+
+ <source xml:space="preserve">
+<map:components>
+ <map:generators default="file">
+ <map:generator name="html"
+ src="org.apache.cocoon.generation.HTMLGenerator">
+ <jtidy-config>WEB-INF/jtidy.properties</jtidy-config>
+ </map:generator>
+ </map:generators>
+</map:components>
+ </source>
+
+ <p>Since the HTML generator uses JTidy we need to make available a JTidy configuration file.
+ This is placed in <code>PROJECT_HOME/src/documentation/WEB-INF/jtidy.properties</code> (the
+ location can be changed in the above sitemap snippet). A sample config file is given below:</p>
+
+ <source xml:space="preserve">
+indent=yes
+indent-spaces=8
+wrap=72
+markup=no
+output-xml=no
+input-xml=no
+show-warnings=yes
+numeric-entities=yes
+quote-marks=yes
+quote-nbsp=yes
+quote-ampersand=yes
+break-before-br=yes
+uppercase-tags=no
+uppercase-attributes=no
+char-encoding=latin1
+ </source>
+
+ <note>This requirement to add items to your project sitemap will be removed in a future version either by Lenya
+ outputting XDoc, or by Forrest switching to using XHTML as its internal format, or through the development of a
+ plugin for Lenya that will include the necessary processing (whichever comes first).</note>
+
+ <warning>This demo is an example only, it does not fully work at this time. For example, absolute URLs
+ in the source document need to be rewritten to ensure that they are matched by the locationmap.</warning>
+
+ </section>
+
+ <section id="sourceResolving">
+ <title>Source Resolving</title>
+ <p>As well as being able to use the locationmap as a parameter in the sitemap,
+ it is also possible to use it as a psuedo-protocol within resources processed
+ by Forrest. For example, you can use it to import an XSL provided by one plugin
+ within another plugin:</p>
+
+ <source xml:space="preserve">
+ <xsl:import src="lm://OOo.transform.write.xdoc"/>
+
+ </source>
+ </section>
+
+ <section id="linkrewriting">
+ <title>Link Rewriting</title>
+ <p>The locationmap can be used to rewrite URLs when the page is generated.
+ For example, when the locationmap has:</p>
+ <source xml:space="preserve">
+ <match pattern="rewriteDemo/**">
+ <location src="http://www.domain.org/{1}.xml" />
+ </match>
+ </source>
+ <p>With the above match in the locationmap, a link which has <code>href="lm:rewriteDemo/index"</code>
+ will be rewritten to an offsite address at <code>domain.org</code></p>
+ </section>
+
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_80/locationmap.source.xml
------------------------------------------------------------------------------
svn:eol-style = native