forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject 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...
Date Thu, 09 Feb 2006 00:26:32 GMT
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">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;collection xmlns="http://outerx.org/yer/hierarchy/0.1"&gt;
+  &lt;collection label="content"&gt;
+    &lt;collection label="xdocs"&gt;
+      &lt;item label="dreams.xml" 
+               href="src/documentation/content/xdocs/dreams.xml" 
+               title="Forrest dream list"/&gt;
+      &lt;item label="faq.xml" 
+               href="src/documentation/content/xdocs/faq.xml"/&gt;
+      &lt;item label="book.xml" 
+               href="src/documentation/content/xdocs/book.xml"/&gt;
+      &lt;item label="contrib.xml" 
+               href="src/documentation/content/xdocs/contrib.xml" 
+               title="Contribution to Forrest"/&gt;
+      &lt;item label="mail-archives.xml" 
+               href="src/documentation/content/xdocs/mail-archives.xml" 
+               title="Mail Archives"/&gt;
+      &lt;item label="mail-lists.xml" 
+               href="src/documentation/content/xdocs/mail-lists.xml" 
+               title="Mailing Lists"/&gt;
+      &lt;item label="license.xml" 
+               href="src/documentation/content/xdocs/license.xml" 
+               title="The Apache Software License"/&gt;
+      &lt;item label="index.xml" 
+               href="src/documentation/content/xdocs/index.xml" 
+               title="Welcome to Forrest"/&gt;
+      &lt;item label="who.xml" 
+               href="src/documentation/content/xdocs/who.xml" 
+               title="Who we are"/&gt;
+    &lt;/collection&gt;
+  &lt;/collection&gt;
+&lt;/collection&gt;</source> 
+        <p>And it's not getting any harder in fact: only 2 elements,
+          <code>&lt;collection&gt;</code> and <code>&lt;item&gt;</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">&lt;!ELEMENT libre (entry | auto)*&gt;
+&lt;!ELEMENT entry (label?, href?)&gt;
+&lt;!ATTLIST entry
+  location CDATA #REQUIRED
+&gt;
+&lt;!ELEMENT auto (filter?, sorter?, label?, href?)&gt;
+&lt;!ELEMENT label (xpath | property)&gt;
+&lt;!ELEMENT href (xpath | property)&gt;
+&lt;!ELEMENT filter (xpath | property)&gt;
+&lt;!ATTLIST filter
+  logic (inverse | normal) "normal"
+  clear (yes | no) "no"
+&gt;
+&lt;!ELEMENT sorter (xpath | property)&gt;
+&lt;!ATTLIST sorter
+  order (ascending | descending) "ascending"
+  clear (yes | no) "no"
+&gt;
+&lt;!ELEMENT xpath EMPTY&gt;
+&lt;!ATTLIST xpath
+  expression CDATA #REQUIRED
+&gt;
+&lt;!ELEMENT property EMPTY&gt;
+&lt;!ATTLIST property
+  name CDATA #REQUIRED
+  mask CDATA #IMPLIED
+  regex CDATA #IMPLIED
+  substitute CDATA #IMPLIED
+&gt;</source> 
+        <section> 
+          <title>Building Blocks</title> 
+          <p>The following elements get the following meaning when interpreted
+            by the LibreConfigBuilder</p> 
+          <source xml:space="preserve">&lt;libre xmlns="http://outerx.org/libre/config/0.1"&gt;</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">&lt;entry location="[relative location path]" /&gt;</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>&lt;menu&gt;</code> and
+              <code>&lt;menu-item&gt;</code>, there just is <code>&lt;entry&gt;</code>. It
+              will become a <code>&lt;collection&gt;</code> or <code>&lt;item&gt;</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>&lt;filter&gt;</code> and
+              <code>&lt;sort&gt;</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">&lt;auto&gt;</source> 
+          <ul> 
+            <li>Automatically generates more <code>&lt;collection&gt;</code>
+              and <code>&lt;item&gt;</code> elements in the output, based on the
+              specifications of the nested elements: <code>&lt;filter&gt;</code> (which
+              resources?) and <code>&lt;sort&gt;</code> (in which order?).</li> 
+          </ul> 
+          <source xml:space="preserve">&lt;filter logic="inverse" clear="no"&gt;</source> 
+          <ul> 
+            <li>This element wraps a so-called AttributeReader (there are
+              currently two of them: <code>&lt;xpath&gt;</code> and
+              <code>&lt;property&gt;</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">&lt;sort order="descending" clear="no"&gt;</source> 
+          <ul> 
+            <li>This element wraps a so called AttributeReader (there are
+              currently two of them: <code>&lt;xpath&gt;</code> and
+              <code>&lt;property&gt;</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>&lt;collection&gt;</code> and <code>&lt;item&gt;</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-&gt;a instead of a-&gt;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">&lt;label&gt;, &lt;href&gt;, &lt;YOURTAG&gt;.... {AttributeDefinitions}</source> 
+          <ul> 
+            <li>The remainder of the elements inside the
+              <code>&lt;auto&gt;</code> tag specify the attributes that need to be applied to
+              the generated <code>&lt;collection&gt;</code> and <code>&lt;item&gt;</code>
+              elements in the output: <code>&lt;item label=".." href=".." YOURTAG=".."
+              /&gt;</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: &lt;xpath&gt; and &lt;property&gt;)</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">&lt;xpath expression="/document/header/title/text()"&gt;</source> 
+          <ul> 
+            <li>This element specifies an xpath AttributeReader to use inside
+              <code>&lt;filter&gt;</code>, <code>&lt;sort&gt;</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>&lt;sort&gt;</code> usage) or to fill in the
+              specified attribute (<code>&lt;label&gt;</code>, <code>&lt;href&gt;</code>...
+              use). When inside a <code>&lt;filter&gt;</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">&lt;property name="path" regex="(\.[\\/])*(.*)" substitute="$2"/&gt;
+&lt;property name="name"  mask="CVS"/&gt;</source> 
+          <ul> 
+            <li>This element specifies an xpath AttributeReader to use inside
+              <code>&lt;filter&gt;</code>, <code>&lt;sort&gt;</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>&lt;sort&gt;</code> usage) or to fill in the specified attribute
+              (<code>&lt;label&gt;</code>, <code>&lt;href&gt;</code>... use). When inside a
+              <code>&lt;filter&gt;</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>&lt;auto&gt; </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>&lt;entry&gt;</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>&lt;entry&gt;</code> and
+            <code>&lt;auto&gt;</code> elements after each other. The system will make sure
+            that the resulting list of <code>&lt;collection&gt;</code> and
+            <code>&lt;item&gt;</code> will not contain duplicates. So the filters in
+            <code>&lt;auto&gt;</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">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;!DOCTYPE libre PUBLIC "-//Outerthought//DTD Libre Configuration V0.1//EN" "libre-v01.dtd" &gt;
+&lt;libre xmlns="http://outerx.org/libre/config/0.1"&gt;
+  &lt;auto&gt;
+    &lt;filter logic="normal"&gt;
+      &lt;property name="name" regex="\d{3}(.*)"/&gt;
+    &lt;/filter&gt;
+    &lt;label&gt;
+      &lt;property name="name" regex="\d{3}(.*)" substitute="$1"/&gt;
+    &lt;/label&gt;
+  &lt;/auto&gt;
+&lt;/libre&gt;</source> 
+          <p>Will produce an automatic list of entries (collections and items
+            in the output) that </p> 
+          <ul> 
+            <li><code>&lt;filter&gt;</code>: only resources which name starts
+              with a 3-digit pattern</li> 
+            <li>No <code>&lt;sort&gt;</code>: in their natural filesystem order
+              assured by the digit-prefix</li> 
+            <li><code>&lt;label&gt;</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">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;!DOCTYPE libre PUBLIC "-//Outerthought//DTD Libre Configuration V0.1//EN" "libre-v01.dtd" &gt;
+&lt;libre xmlns="http://outerx.org/libre/config/0.1"&gt;
+  &lt;entry location="dreams.xml" &gt;
+      &lt;label&gt;
+         &lt;xpath expression="/document/header/title/text()"/&gt;
+      &lt;/label&gt;
+  &lt;/entry&gt;
+  &lt;auto&gt;
+    &lt;filter&gt;
+      &lt;property name="name" regex="\.xml$" /&gt;
+    &lt;/filter&gt;
+    &lt;sorter&gt;
+         &lt;xpath expression="/document/header/title/text()"/&gt;
+    &lt;/sorter&gt;
+      &lt;label&gt;
+          &lt;xpath expression="/document/header/title/text()"/&gt;
+      &lt;/label&gt;
+  &lt;/auto&gt;
+&lt;/libre&gt;</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 &lt;filter&gt; 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">&lt;!ELEMENT filter (xpath | property | and | or | not)&gt;
+&lt;!ELEMENT not    (xpath | property | and | or | not)&gt;
+&lt;!ELEMENT and    (xpath | property | and | or | not)+&gt;
+&lt;!ELEMENT or     (xpath | property | and | or | not)+&gt;</source> 
+          <p>So we can make up some richer:</p> 
+          <source xml:space="preserve">
+&lt;filter&gt;
+  &lt;not&gt;
+      &lt;and&gt;
+      &lt;xpath .../&gt;
+      &lt;not&gt;&lt;property ..../&gt;&lt;/not&gt;
+      &lt;or&gt;
+         ...
+      &lt;/or&gt;
+    &lt;/and&gt;
+  &lt;/not&gt;
+&lt;/filter&gt;
+    </source> 
+        </section> 
+        <section> 
+          <title>Separating property-retrieval from formatting and
+            testing</title> 
+          <p>Playing around with the attributes in
+            <code>&lt;property&gt;</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 &lt;filter&gt;== test or &lt;sort&gt;==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 &lt;xpath&gt;
+              ?</li> 
+          </ul> 
+          <p>So maybe an example more down the lines of the following would be
+            easier to use:</p> 
+          <source xml:space="preserve">&lt;label&gt;&lt;!-- same applies for the sort context --&gt;
+  &lt;regexformatter exp="..." substitute="...."&gt;
+    &lt;property name="absoluteLocation" /&gt;
+  &lt;/regexformatter&gt;
+&lt;/label&gt;</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>&lt;dateformat format="dd/mmm/yy"&gt; </code></p> 
+          <p>It would also clearly distinguish the semantical difference of
+            applying a test in the <code>&lt;filter&gt;</code> context:</p> 
+          <source xml:space="preserve">&lt;filter&gt;
+  &lt;regextest match="..."&gt;
+    &lt;property ... /&gt;
+  &lt;/regextest&gt;
+&lt;/filter&gt;</source> 
+          <p>And more logically introduce other tests like <code>&lt;globtest
+            match="..."&gt;</code> or <code>&lt;availabletest&gt;</code> or...</p> 
+        </section> 
+        <section> 
+          <title>Replace the introspection with semantically richer named
+            properties to read.</title> 
+          <p>Currently the <code>&lt;property
+            name="someJavaBeanProp"&gt;</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>&lt;item&gt;</code> output (retrieved by e.g. xpath expressions)?</li> 
+          <li>do we need an extra <code>&lt;constant&gt;</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 &lt;link href="site:v0.80//changes"&gt; 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
+        &amp;m=103097808318773&amp;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">
+&lt;site label="Forrest" href="" <strong>tab="home"</strong>
+  xmlns="http://apache.org/forrest/linkmap/1.0"&gt;
+
+  &lt;about label="About"&gt;
+    &lt;index label="Index" href="index.html"/&gt;
+    &lt;license label="License" href="license.html"/&gt;
+    &lt;your-project label="Using Forrest" href="your-project.html"&gt;
+      &lt;new_content_type href="#adding_new_content_type"/&gt;
+    &lt;/your-project&gt;
+    &lt;linking label="Linking" href="linking.html"/&gt;
+    ....
+  &lt;/about&gt;
+
+  &lt;community label="Community" href="community/" <strong>tab="community"</strong>&gt;
+    &lt;index label="About" href="index.html"/&gt;
+    &lt;howto-samples label="How-To Samples" href="howto/" <strong>tab="howto"</strong>&gt;
+      &lt;overview label="Overview" href="index.html"/&gt;
+      &lt;single-page label="Single Page" href="v10/howto-v10.html"/&gt;
+      &lt;multi label="Multi-Page" href="multi/"&gt;
+        &lt;intro label="Intro" href="howto-multi.html"/&gt;
+        &lt;step1 label="Step 1" href="step1.html"/&gt;
+      ...</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>&lt;about&gt;</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>&lt;linking&gt;</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">
+          &lt;a href="todo.html"&gt;to-do list&lt;a&gt;
+        </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 &lt;a href="todo.html"&gt;,
+          write &lt;a href="site:v0.80//todo"&gt; 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
+            &lt;external-refs&gt; 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, &lt;a href="ext:commons/resolver"&gt;
+            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::&lt;Message-Id&gt;</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:&lt;searchterm&gt;</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&lt;at&gt;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:&lt;taskname&gt;</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">
+   &lt;map:match pattern="locationmap-project.xml"&gt;
+     &lt;map:generate src="..."/&gt;
+     &lt;map:transform src="..."/&gt;
+     &lt;map:serialize type="xml"/&gt;
+   &lt;/map:match&gt;
+      </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">
+&lt;map:transform src="{lm:xhtml2html.xsl}"/&gt;
+      </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">
+&lt;map:transform src="{lm:transform.xhtml2.html}"/&gt;
+      </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">
+&lt;map:transform src="{lm:projectInfo.transform.doap.html}"/&gt;
+      </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">
+&lt;match pattern="tabs.xml"&gt;
+  &lt;select type="exists"&gt;      
+    &lt;location src="{project:content.xdocs}tabs1.xml"/&gt;
+    &lt;location src="{project:content.xdocs}tabs2.xml"/&gt;
+  &lt;/select&gt;   
+&lt;/match&gt;
+    </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">
+ &lt;match pattern="remoteDemo/**.xml"&gt;
+   &lt;location src="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/xdocs/{1}.xml" /&gt;
+ &lt;/match&gt;
+        </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">
+ &lt;match pattern="lenya/**.xml"&gt;
+   &lt;location src="http://lenya.zones.apache.org:8888/default/live/{1}.html?raw=true" /&gt;
+ &lt;/match&gt;
+        </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">
+&lt;map:match pattern="lenya/**.xml"&gt;
+  &lt;map:generate type="html" src="{lm:{0}}" /&gt;
+  &lt;map:transform src="{forrest:stylesheets}/html2document.xsl" /&gt;
+  &lt;map:serialize type="xml"/&gt;
+&lt;/map:match&gt;
+        </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">
+&lt;map:components&gt;
+  &lt;map:generators default="file"&gt;
+    &lt;map:generator name="html"
+      src="org.apache.cocoon.generation.HTMLGenerator"&gt;
+      &lt;jtidy-config&gt;WEB-INF/jtidy.properties&lt;/jtidy-config&gt;
+    &lt;/map:generator&gt;
+  &lt;/map:generators&gt;
+&lt;/map:components&gt;
+        </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">
+          &lt;xsl:import src="lm://OOo.transform.write.xdoc"/&gt;
+        
+        </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">
+ &lt;match pattern="rewriteDemo/**"&gt;
+   &lt;location src="http://www.domain.org/{1}.xml" /&gt;
+ &lt;/match&gt;
+        </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



Mime
View raw message