forrest-site-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r527020 [8/20] - in /forrest/site: ./ docs_0_80/ docs_0_80/howto/ docs_0_80/howto/cvs-ssh/ docs_0_80/howto/multi/ dtdx/ plan/ pluginDocs/plugins_0_70/ pluginDocs/plugins_0_80/ procedures/ procedures/release/ skins/ tools/
Date Tue, 10 Apr 2007 04:44:05 GMT
Modified: forrest/site/docs_0_80/libre-intro.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_80/libre-intro.html?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
--- forrest/site/docs_0_80/libre-intro.html (original)
+++ forrest/site/docs_0_80/libre-intro.html Mon Apr  9 21:44:00 2007
@@ -317,8 +317,10 @@
 	          &nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
 </div>
 <h1>Libre QuickStart</h1>
-<div class="abstract">This document is the current full documentation on the "libre"
-      generator that was implanted into xml-forrest.</div>
+<div class="abstract">
+      This document is the current full documentation on the "libre" generator
+      that was implanted into xml-forrest.
+    </div>
 <div id="motd-area">
         This is documentation for development version v0.8
        (<a href="http://forrest.apache.org/versions/">More</a>)</div>
@@ -404,58 +406,70 @@
 </ul>
 </li>
 </ul>
-</div> 
+</div>
     
 <a name="N10010"></a><a name="Intro"></a>
 <h2 class="underlined_10">Intro</h2>
 <div class="section">
 <div class="warning">
 <div class="label">Warning</div>
-<div class="content">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".
+<div class="content">
+        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".
       </div>
 </div>
-<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
+<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> 
+        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> 
+          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> 
+          pointed at XML file. </li>
       
 </ul>
-</div> 
+</div>
     
 <a name="N10029"></a><a name="Using+Libre+now+%280.0+alfa%29"></a>
 <h2 class="underlined_10">Using Libre now (0.0 alfa)</h2>
 <div class="section">
 <div class="warning">
 <div class="label">Warning</div>
-<div class="content">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)</div>
+<div class="content">
+        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)
+      </div>
 </div>
 <a name="N10034"></a><a name="Generated+Output"></a>
 <h3 class="underlined_5">Generated Output</h3>
-<p>The XML output that comes out of the generator largely follows this
-          example:</p>
+<p>
+          The XML output that comes out of the generator largely follows this
+          example:
+        </p>
 <pre class="code">&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;
@@ -488,23 +502,32 @@
     &lt;/collection&gt;
   &lt;/collection&gt;
 &lt;/collection&gt;</pre>
-<p>And it's not getting any harder in fact: only 2 elements,
-          <span class="codefrag">&lt;collection&gt;</span> and <span class="codefrag">&lt;item&gt;</span> 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>
+<p>
+          And it's not getting any harder in fact: only 2 elements,
+          <span class="codefrag">&lt;collection&gt;</span> and <span class="codefrag">&lt;item&gt;</span> 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>
 <a name="N1004E"></a><a name="Contents"></a>
 <h3 class="underlined_5">libre.xml Contents</h3>
-<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>
+<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>
 <pre class="code">&lt;!ELEMENT libre (entry | auto)*&gt;
 &lt;!ELEMENT entry (label?, href?)&gt;
 &lt;!ATTLIST entry
@@ -536,133 +559,134 @@
 &gt;</pre>
 <a name="N10060"></a><a name="Building+Blocks"></a>
 <h4>Building Blocks</h4>
-<p>The following elements get the following meaning when interpreted
-            by the LibreConfigBuilder</p>
+<p>
+            The following elements get the following meaning when interpreted by
+            the LibreConfigBuilder
+          </p>
 <pre class="code">&lt;libre xmlns="http://outerx.org/libre/config/0.1"&gt;</pre>
-<ul> 
+<ul>
             
 <li>This is one of those libre.xml files, that will configure how
-              items are filteres, sorted and attributed</li> 
+              items are filteres, sorted and attributed</li>
           
 </ul>
 <pre class="code">&lt;entry location="[relative location path]" /&gt;</pre>
-<ul> 
+<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> 
+              that </li>
             
+<ul>
+              
 <li>libre doesn't yet support external hrefs (should be easy
-              though)</li> 
-            
+              though)</li>
+              
 <li>there is no difference between <span class="codefrag">&lt;menu&gt;</span> and
               <span class="codefrag">&lt;menu-item&gt;</span>, there just is <span class="codefrag">&lt;entry&gt;</span>. It
               will become a <span class="codefrag">&lt;collection&gt;</span> or <span class="codefrag">&lt;item&gt;</span> in
               the output based on the fact if the location points to a directory resp. a
-              file.</li> 
-            
+              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 <span class="codefrag">&lt;filter&gt;</span> and
-              <span class="codefrag">&lt;sort&gt;</span> elements get inherited down to the next level. </li> 
-          
-</ul> 
+              <span class="codefrag">&lt;sort&gt;</span> elements get inherited down to the next level. </li>
+            
+</ul>
           
 </ul>
 <div class="fixme">
 <div class="label">Fixme (mpo)</div>
-<div class="content">This last remarks actually means (1) I need to
-            update the DTD to reflect this and (2) check the code for actually doing
-            this.</div>
+<div class="content">
+            This last remarks actually means (1) I need to update the DTD to
+            reflect this and (2) check the code for actually doing this.
+          </div>
 </div>
 <pre class="code">&lt;auto&gt;</pre>
-<ul> 
+<ul>
             
 <li>Automatically generates more <span class="codefrag">&lt;collection&gt;</span>
               and <span class="codefrag">&lt;item&gt;</span> elements in the output, based on the
               specifications of the nested elements: <span class="codefrag">&lt;filter&gt;</span> (which
-              resources?) and <span class="codefrag">&lt;sort&gt;</span> (in which order?).</li> 
+              resources?) and <span class="codefrag">&lt;sort&gt;</span> (in which order?).</li>
           
 </ul>
 <pre class="code">&lt;filter logic="inverse" clear="no"&gt;</pre>
-<ul> 
+<ul>
             
 <li>This element wraps a so-called AttributeReader (there are
               currently two of them: <span class="codefrag">&lt;xpath&gt;</span> and
-              <span class="codefrag">&lt;property&gt;</span>)</li> 
+              <span class="codefrag">&lt;property&gt;</span>)</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> 
+              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 <span class="codefrag">clear="yes"</span> 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> 
+              level.</li>
           
 </ul>
 <pre class="code">&lt;sort order="descending" clear="no"&gt;</pre>
-<ul> 
+<ul>
             
 <li>This element wraps a so called AttributeReader (there are
               currently two of them: <span class="codefrag">&lt;xpath&gt;</span> and
-              <span class="codefrag">&lt;property&gt;</span>).</li> 
+              <span class="codefrag">&lt;property&gt;</span>).</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 <span class="codefrag">&lt;collection&gt;</span> and <span class="codefrag">&lt;item&gt;</span>
               elements in the output will appear in the order defined by the alphabetic
-              sorting of these keys.</li> 
+              sorting of these keys.</li>
             
 <li>This wrapping sort element allows to reverse the order.
-              (z-&gt;a instead of a-&gt;z)</li> 
+              (z-&gt;a instead of a-&gt;z)</li>
             
 <li>Using the <span class="codefrag">clear="yes"</span> 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> 
+              on filename) is slided in at this level.</li>
           
 </ul>
 <pre class="code">&lt;label&gt;, &lt;href&gt;, &lt;YOURTAG&gt;.... {AttributeDefinitions}</pre>
-<ul> 
+<ul>
             
 <li>The remainder of the elements inside the
               <span class="codefrag">&lt;auto&gt;</span> tag specify the attributes that need to be applied to
               the generated <span class="codefrag">&lt;collection&gt;</span> and <span class="codefrag">&lt;item&gt;</span>
               elements in the output: <span class="codefrag">&lt;item label=".." href=".." YOURTAG=".."
               /&gt;</span>
-</li> 
+</li>
             
 <li>There is currently only support for adding attributes, not
-              nested elements.</li> 
+              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> 
+              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> 
+              value.</li>
           
 </ul>
 <pre class="code">&lt;xpath expression="/document/header/title/text()"&gt;</pre>
-<ul> 
+<ul>
             
 <li>This element specifies an xpath AttributeReader to use inside
               <span class="codefrag">&lt;filter&gt;</span>, <span class="codefrag">&lt;sort&gt;</span> or
-              {AttributeDefinitions}.</li> 
+              {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
@@ -670,22 +694,24 @@
               string value to sort (<span class="codefrag">&lt;sort&gt;</span> usage) or to fill in the
               specified attribute (<span class="codefrag">&lt;label&gt;</span>, <span class="codefrag">&lt;href&gt;</span>...
               use). When inside a <span class="codefrag">&lt;filter&gt;</span>: the presence of the node
-              results in passing the test.</li> 
+              results in passing the test.</li>
           
 </ul>
 <div class="warning">
 <div class="label">Warning</div>
-<div class="content">This currently breaks for non xml (<span class="codefrag">*.gif</span>)
-            files, so get your filter right please, and in the mean time: sorry for not
-            being able to use it in the filter yet <span class="codefrag">:-(</span>.</div>
+<div class="content">
+            This currently breaks for non xml (<span class="codefrag">*.gif</span>) files, so get
+            your filter right please, and in the mean time: sorry for not being
+            able to use it in the filter yet <span class="codefrag">:-(</span>.
+          </div>
 </div>
 <pre class="code">&lt;property name="path" regex="(\.[\\/])*(.*)" substitute="$2"/&gt;
 &lt;property name="name"  mask="CVS"/&gt;</pre>
-<ul> 
+<ul>
             
 <li>This element specifies an xpath AttributeReader to use inside
               <span class="codefrag">&lt;filter&gt;</span>, <span class="codefrag">&lt;sort&gt;</span> or
-              {AttributeDefinitions}.</li> 
+              {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
@@ -694,54 +720,65 @@
               sort (<span class="codefrag">&lt;sort&gt;</span> usage) or to fill in the specified attribute
               (<span class="codefrag">&lt;label&gt;</span>, <span class="codefrag">&lt;href&gt;</span>... use). When inside a
               <span class="codefrag">&lt;filter&gt;</span>, the test passes if the read property is not null
-              or "".</li> 
+              or "".</li>
             
 <li>Furthermore this element allows to express more elaborate
               true-false tests (filter use) or regex substitution (other use)
-              attributes:</li> 
-          
-<ul> 
+              attributes:</li>
             
+<ul>
+              
 <li>combination of @regex with @substitute accounts for a
-              s/{regex}/{substitute}/ kind of operation on the string property.</li> 
-            
+              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> 
+              glob-mask or regex test to be applied on the read property.</li>
+            
+</ul>
           
 </ul>
 <a name="N1016C"></a><a name="Important+Side+Effects"></a>
 <h3 class="underlined_5">Important Side Effects</h3>
-<p>There are some things that libre is doing that you should be aware of.</p>
+<p>
+          There are some things that libre is doing that you should be aware of.
+        </p>
 <a name="N10175"></a><a name="No+libre.xml"></a>
 <h4>No libre.xml</h4>
-<p>When using an <span class="codefrag">&lt;auto&gt; </span>section, the filter will
-            NEVER accept the <span class="codefrag">libre.xml</span> file to be in the generated output. You
-            can however include a manual <span class="codefrag">&lt;entry&gt;</span> to point to the
-            <span class="codefrag">libre.xml</span> file if needed.</p>
+<p>
+            When using an <span class="codefrag">&lt;auto&gt; </span>section, the filter will
+            NEVER accept the <span class="codefrag">libre.xml</span> file to be in the generated
+            output. You can however include a manual <span class="codefrag">&lt;entry&gt;</span>
+            to point to the <span class="codefrag">libre.xml</span> file if needed.
+          </p>
 <a name="N1018B"></a><a name="No+Duplicates"></a>
 <h4>No Duplicates</h4>
-<p>You can combine multiple <span class="codefrag">&lt;entry&gt;</span> and
-            <span class="codefrag">&lt;auto&gt;</span> elements after each other. The system will make sure
-            that the resulting list of <span class="codefrag">&lt;collection&gt;</span> and
-            <span class="codefrag">&lt;item&gt;</span> will not contain duplicates. So the filters in
-            <span class="codefrag">&lt;auto&gt;</span> sections lower down the <span class="codefrag">libre.xml</span> file
-            can include already accepted files or directories, they will only show up once
-            in the output.</p>
+<p>
+            You can combine multiple <span class="codefrag">&lt;entry&gt;</span> and
+            <span class="codefrag">&lt;auto&gt;</span> elements after each other. The system will
+            make sure that the resulting list of <span class="codefrag">&lt;collection&gt;</span>
+            and <span class="codefrag">&lt;item&gt;</span> will not contain duplicates. So the
+            filters in <span class="codefrag">&lt;auto&gt;</span> sections lower down the
+            <span class="codefrag">libre.xml</span> file can include already accepted files or
+            directories, they will only show up once in the output.
+          </p>
 <a name="N101A8"></a><a name="Example+Constructs"></a>
 <h3 class="underlined_5">Example Constructs</h3>
-<p>Adding sorting and filtering to the filesystem with libre becomes a
+<p>
+          Adding sorting and filtering to the filesystem with libre becomes a
           subtle play with editable filesystem properties, smart XML content and
-          <span class="codefrag">libre.xml</span> 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 <span class="codefrag">libre.xml</span> files.</p>
+          <span class="codefrag">libre.xml</span> 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
+          <span class="codefrag">libre.xml</span> files.
+        </p>
 <a name="N101B7"></a><a name="Sorting+your+files+or+your+menu+entries%3F"></a>
 <h4>Sorting your files or your menu entries?</h4>
-<p>In every case the very pragmatic approach can become something
-            like this:</p>
+<p>
+            In every case the very pragmatic approach can become something like
+            this:
+          </p>
 <pre class="code">+ content
   + xdocs
     + 010Topic
@@ -749,8 +786,10 @@
       + 111Bar
     + 050Aspect
     + NotInList</pre>
-<p>In combination with something that lives by the introduced
-            alphabetic order, but yet hides the ugly number-prefixes:</p>
+<p>
+            In combination with something that lives by the introduced
+            alphabetic order, but yet hides the ugly number-prefixes:
+          </p>
 <pre class="code">&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;
@@ -763,33 +802,40 @@
     &lt;/label&gt;
   &lt;/auto&gt;
 &lt;/libre&gt;</pre>
-<p>Will produce an automatic list of entries (collections and items
-            in the output) that </p>
-<ul> 
+<p>
+            Will produce an automatic list of entries (collections and items in
+            the output) that
+          </p>
+<ul>
             
 <li>
 <span class="codefrag">&lt;filter&gt;</span>: only resources which name starts
-              with a 3-digit pattern</li> 
+              with a 3-digit pattern</li>
             
 <li>No <span class="codefrag">&lt;sort&gt;</span>: in their natural filesystem order
-              assured by the digit-prefix</li> 
+              assured by the digit-prefix</li>
             
 <li>
 <span class="codefrag">&lt;label&gt;</span>: hold a label attribute that strips
-              of the ugly number prefix</li> 
+              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>
+<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>
 <a name="N101E5"></a><a name="Naming+your+files+or+asking+them+their+name%3F"></a>
 <h4>Naming your files or asking them their name?</h4>
-<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>
+<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>
 <pre class="code">&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;
@@ -810,76 +856,85 @@
       &lt;/label&gt;
   &lt;/auto&gt;
 &lt;/libre&gt;</pre>
-</div> 
+</div>
     
 <a name="N101F5"></a><a name="Next+Libre+%280.1%29"></a>
 <h2 class="underlined_10">Next Libre (0.1)</h2>
 <div class="section">
 <div class="note">
 <div class="label">Note</div>
-<div class="content">Next libre is in fact largely in your hands... just drop
-        the forrest-dev <a href="../mail-lists.html">mail list</a>
-        a line, and see what happens...</div>
+<div class="content">
+        Next libre is in fact largely in your hands... just drop the forrest-dev
+        <a href="../mail-lists.html">mail list</a> a line, and see what
+        happens...
+      </div>
 </div>
 <a name="N10202"></a><a name="Itches"></a>
 <h3 class="underlined_5">Itches</h3>
-<p>There is quite a number of fast code patches that can/need to
-          happen</p>
-<ul> 
+<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> 
+            mind)</li>
           
 <li>on same level: possible xmlns and/or elms/atts renaming on the
-            generated output and the libre.xml file</li> 
+            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> 
+            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> 
+            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> 
+            document (by returning nothing rather then breaking on the exception)</li>
           
 <li>general robustness and resilience towards
-            mis-configurations</li> 
+            mis-configurations</li>
           
 <li>filestreams need to get closed and avalon resources need to be
-            released properly</li> 
+            released properly</li>
           
-<li>caching at the level of the generator needs to be set up</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> 
+            early optimizations :-P</li>
         
 </ul>
 <a name="N1022A"></a><a name="Upcoming+Features"></a>
 <h3 class="underlined_5">Upcoming Features</h3>
-<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>
+<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>
 <a name="N10233"></a><a name="Combinations+of+filter+logic"></a>
 <h4>Combinations of filter logic</h4>
-<p>Some itching stuff:</p>
-<ul> 
+<p>
+            Some itching stuff:
+          </p>
+<ul>
             
 <li>logic="inverse" on the &lt;filter&gt; element seems a bit
-              awkward</li> 
+              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> 
+              us so far, combinatory filter logic seems to be the way to go...:</li>
           
 </ul>
 <pre class="code">&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;</pre>
-<p>So we can make up some richer:</p>
+<p>
+            So we can make up some richer:
+          </p>
 <pre class="code">
 &lt;filter&gt;
   &lt;not&gt;
@@ -896,184 +951,207 @@
 <a name="N10253"></a><a name="Separating+property-retrieval+from+formatting+and%0A++++++++++++testing"></a>
 <h4>Separating property-retrieval from formatting and
             testing</h4>
-<p>Playing around with the attributes in
-            <span class="codefrag">&lt;property&gt;</span>:</p>
-<ul> 
+<p>
+            Playing around with the attributes in <span class="codefrag">&lt;property&gt;</span>:
+          </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> 
+              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> 
+              modifying the DTD</li>
             
 <li>makes you wonder why it's not available on the &lt;xpath&gt;
-              ?</li> 
+              ?</li>
           
 </ul>
-<p>So maybe an example more down the lines of the following would be
-            easier to use:</p>
+<p>
+            So maybe an example more down the lines of the following would be
+            easier to use:
+          </p>
 <pre class="code">&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;</pre>
-<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:
-            <span class="codefrag">&lt;dateformat format="dd/mmm/yy"&gt; </span>
+<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: <span class="codefrag">&lt;dateformat format="dd/mmm/yy"&gt; </span>
+          
 </p>
-<p>It would also clearly distinguish the semantical difference of
-            applying a test in the <span class="codefrag">&lt;filter&gt;</span> context:</p>
+<p>
+            It would also clearly distinguish the semantical difference of
+            applying a test in the <span class="codefrag">&lt;filter&gt;</span> context:
+          </p>
 <pre class="code">&lt;filter&gt;
   &lt;regextest match="..."&gt;
     &lt;property ... /&gt;
   &lt;/regextest&gt;
 &lt;/filter&gt;</pre>
-<p>And more logically introduce other tests like <span class="codefrag">&lt;globtest
-            match="..."&gt;</span> or <span class="codefrag">&lt;availabletest&gt;</span> or...</p>
-<a name="N1028B"></a><a name="Replace+the+introspection+with+semantically+richer+named%0A++++++++++++properties+to+read."></a>
+<p>
+            And more logically introduce other tests like <span class="codefrag">&lt;globtest
+            match="..."&gt;</span> or <span class="codefrag">&lt;availabletest&gt;</span> or...
+          </p>
+<a name="N1028C"></a><a name="Replace+the+introspection+with+semantically+richer+named%0A++++++++++++properties+to+read."></a>
 <h4>Replace the introspection with semantically richer named
             properties to read.</h4>
-<p>Currently the <span class="codefrag">&lt;property
-            name="someJavaBeanProp"&gt;</span> is applied in a java introspection for the
-            <span class="codefrag">getSomeJavaBeanProp()</span> on the <span class="codefrag">java.io.File</span> 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> 
+<p>
+            Currently the <span class="codefrag">&lt;property name="someJavaBeanProp"&gt;</span>
+            is applied in a java introspection for the
+            <span class="codefrag">getSomeJavaBeanProp()</span> on the <span class="codefrag">java.io.File</span>
+            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> 
+              an XML (and DTD) savvy editor </li>
             
 <li>leads to assuming the <span class="codefrag">libre.xml</span> editor has access
-              to and knows how to interpret jdk javadoc</li> 
+              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> 
+              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> 
+              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> 
+<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>name</li>
             
-<li>isDirectory (isCollection?)</li> 
+<li>isDirectory (isCollection?)</li>
             
 <li>abs and relPath (or abs/rel Location? why would we need
-              abs?)</li> 
+              abs?)</li>
             
-<li>canRead</li> 
+<li>canRead</li>
             
-<li>canWrite</li> 
+<li>canWrite</li>
             
-<li>lastModified</li> 
+<li>lastModified</li>
             
-<li>length</li> 
+<li>length</li>
           
 </ul>
-<p>The DTD would then list the possible attributeValues.</p>
-<a name="N102CF"></a><a name="Avalonising"></a>
+<p>
+            The DTD would then list the possible attributeValues.
+          </p>
+<a name="N102D0"></a><a name="Avalonising"></a>
 <h3 class="underlined_5">Avalonising</h3>
-<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> 
+<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> 
+            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> 
+            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> 
+            HierarchyReader the (avalon) environment he needs.</li>
         
 </ul>
-<a name="N102E5"></a><a name="Unresolved+Discussions"></a>
+<a name="N102E6"></a><a name="Unresolved+Discussions"></a>
 <h3 class="underlined_5">Unresolved Discussions</h3>
-<ul> 
+<ul>
           
 <li>do we need support for nested elements inside
-            <span class="codefrag">&lt;item&gt;</span> output (retrieved by e.g. xpath expressions)?</li> 
+            <span class="codefrag">&lt;item&gt;</span> output (retrieved by e.g. xpath expressions)?</li>
           
 <li>do we need an extra <span class="codefrag">&lt;constant&gt;</span> like
             attributereader that would allow like book.xml to add fixed values for
-            expressed attributes</li> 
+            expressed attributes</li>
           
 <li>clear set out inheritance rules, just doing 'something' now
-            :-(</li> 
+            :-(</li>
           
 <li>votes on needed file properties to replace the current (limiting
-            and semantically poor) Java-introspection</li> 
+            and semantically poor) Java-introspection</li>
         
 </ul>
-</div> 
+</div>
     
-<a name="N10302"></a><a name="Libre+Design"></a>
+<a name="N10303"></a><a name="Libre+Design"></a>
 <h2 class="underlined_10">Libre Design</h2>
 <div class="section">
-<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> 
+<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> 
+          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> 
+          the HierarchyReader that it is using.</li>
         
 <li>
 <em>*.yer.impl</em>: hold the different implementations of the
-          *.yer.hierarchy API </li> 
+          *.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> 
+          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> 
+          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>
-<a name="N1032D"></a><a name="Dependencies"></a>
+<p>
+        ... hope this somewhat clarifies how things have been setup for now.
+      </p>
+<a name="N1032E"></a><a name="Dependencies"></a>
 <h3 class="underlined_5">Dependencies</h3>
-<ul> 
+<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> 
+            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> 
+            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> 
+            there are some plans to stronger benefit from this dependency. </li>
         
 </ul>
-</div> 
+</div>
   
 </div>
 <!--+

Modified: forrest/site/docs_0_80/libre-intro.pdf
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_80/libre-intro.pdf?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
Binary files - no diff available.

Modified: forrest/site/docs_0_80/linking.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_80/linking.html?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
--- forrest/site/docs_0_80/linking.html (original)
+++ forrest/site/docs_0_80/linking.html Mon Apr  9 21:44:00 2007
@@ -398,32 +398,29 @@
 <div class="section">
 <p>
         This document describes Forrest's internal URI space; how it is managed
-        with the "<span class="codefrag">site.xml</span>" configuration file, how menus are generated,
-        and how various link schemes (site: and ext:) operate.
-        An overview of the implementation is also provided.
+        with the "<span class="codefrag">site.xml</span>" configuration file, how menus are generated, and how
+        various link schemes (site: and ext:) operate. An overview of the
+        implementation is also provided.
       </p>
 <p>
         While reading this document, bear in mind that the Cocoon
         <a href="../docs_0_80/sitemap-ref.html">Sitemap</a> is handling the processing.
         The sitemaps are resolving the site: URIs and then matching them to
-        determine how to process each.
-        In general, you can use the power of the Cocoon Sitemap to
-        handle certain difficult linking and menu situations 
-       (for example see this <a href="../docs_0_80/faq.html#tab-index">FAQ</a>).
+        determine how to process each. In general, you can use the power of the
+        Cocoon Sitemap to handle certain difficult linking and menu situations
+        (for example see this <a href="../docs_0_80/faq.html#tab-index">FAQ</a>).
       </p>
 </div>
-
     
 <a name="N10025"></a><a name="site"></a>
 <h2 class="underlined_10">site.xml</h2>
 <div class="section">
 <p>
-        The "<span class="codefrag">site.xml</span>" configuration file is what we would call a "site map"
-        if Cocoon hadn't already claimed that term. 
-        The "<span class="codefrag">site.xml</span>" 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:
+        The "<span class="codefrag">site.xml</span>" configuration file is what we would call a "site map" if
+        Cocoon hadn't already claimed that term. The "<span class="codefrag">site.xml</span>" 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>
         
@@ -439,7 +436,7 @@
 <p>
         In addition to providing fine-grained addressing of site info, the <span class="codefrag">site.xml</span>
         allows <em>metadata</em> to be associated with each node, using
-        attributes or child elements.  Most commonly, a <span class="codefrag">label</span>
+        attributes or child elements. Most commonly, a <span class="codefrag">label</span>
         attribute is used to provide a text description of the node.
       </p>
 <p>
@@ -470,6 +467,7 @@
         Here is a sample <span class="codefrag">site.xml</span> ...
       </p>
 <pre class="code">
+
 &lt;?xml version="1.0"?&gt;
 &lt;site label="Forrest" href="" tab="home"
   xmlns="http://apache.org/forrest/linkmap/1.0"&gt;
@@ -523,8 +521,11 @@
 
   &lt;/external-refs&gt;
 &lt;/site&gt;
-        </pre>
-<p>As you can see, things are quite free-form. The rules are as follows:</p>
+        
+      </pre>
+<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
@@ -551,69 +552,89 @@
 </ul>
 <p>
         See another <a href="../docs_0_80/faq.html#site-xml">explained example</a>.
-        Also remember to look at the comprehensive example with Forrest's own documentation.
+        Also remember to look at the comprehensive example with Forrest's own
+        documentation.
       </p>
 </div>
-
     
 <a name="N100B4"></a><a name="menu_generation"></a>
 <h2 class="underlined_10">Generating Menus</h2>
 <div class="section">
 <p>
         Two files are used to define a site's tabs and menu (<span class="codefrag">site.xml</span> and
-        <span class="codefrag">tabs.xml</span>).  Both files are located in
+        <span class="codefrag">tabs.xml</span>). Both files are located in
         <span class="codefrag">src/documentation/content/xdocs/</span>
+      
 </p>
-<p>Assume that our <span class="codefrag">tabs.xml</span> looks like this:</p>
+<p>
+        Assume that our <span class="codefrag">tabs.xml</span> looks like this:
+      </p>
 <pre class="code">
+
 &lt;tabs ...&gt;
     &lt;tab id="home" label="Home" dir=""/&gt;
     &lt;tab id="community" label="Community" dir="community" indexfile="mailLists.html"/&gt;
     &lt;tab id="howto" label="How-Tos" dir="community/howto"/&gt;
 &lt;/tabs&gt;
+      
       </pre>
-<p>Using the "<span class="codefrag">site.xml</span>" listed above, we would get these menus:</p>
+<p>
+        Using the "<span class="codefrag">site.xml</span>" listed above, we would get these menus:
+      </p>
 <p>
         
-<img alt="Menu generated from site.xml" src="images/menu.png">&nbsp;&nbsp;&nbsp;
-        <img alt="Community menu generated from site.xml" src="images/menu2.png">&nbsp;&nbsp;&nbsp;
+<img alt="Menu generated from site.xml" src="images/menu.png">
+        &nbsp;&nbsp;&nbsp;
+        <img alt="Community menu generated from site.xml" src="images/menu2.png">
+        &nbsp;&nbsp;&nbsp;
         <img alt="Howto menu generated from site.xml" src="images/menu3.png">
       </p>
-<p>When using the "<span class="codefrag">dir</span>" attribute as above the value of the
-      "<span class="codefrag">indexfile</span>" parameter is appended to the value of the 
-      "<span class="codefrag">dir</span>" attribute (together with a preceding '/'). For example,
-      the link for the community tab above is 
-      <span class="codefrag">community/mailLists.html</span>. Note that "<span class="codefrag">indexfile</span>"
-      defaults to "<span class="codefrag">index.html</span>" if no value is supplied. Therefore the
-      link for the howto tab is <span class="codefrag">community/howto/index.html</span>
+<p>
+        When using the "<span class="codefrag">dir</span>" attribute as above the value of the
+        "<span class="codefrag">indexfile</span>" parameter is appended to the value of the
+        "<span class="codefrag">dir</span>" attribute (together with a preceding '/'). For
+        example, the link for the community tab above is
+        <span class="codefrag">community/mailLists.html</span>. Note that
+        "<span class="codefrag">indexfile</span>" defaults to "<span class="codefrag">index.html</span>" if no
+        value is supplied. Therefore the link for the howto tab is
+        <span class="codefrag">community/howto/index.html</span>
+      
 </p>
-<a name="N100FB"></a><a name="tabs-external"></a>
+<a name="N100FD"></a><a name="tabs-external"></a>
 <h3 class="underlined_5">Tabs for External Resources</h3>
-<p>A tab can refer to an external resource by using the 
-        "<span class="codefrag">href</span>" attribute instead of the "<span class="codefrag">dir</span>" attribute.
-        The value of "<span class="codefrag">href</span>" should be the URI of the resource you wish 
-        to link to. For example:</p>
+<p>
+          A tab can refer to an external resource by using the
+          "<span class="codefrag">href</span>" attribute instead of the "<span class="codefrag">dir</span>"
+          attribute. The value of "<span class="codefrag">href</span>" should be the URI of the
+          resource you wish to link to. For example:
+        </p>
 <pre class="code">
+
 &lt;tab id="apache" label="XML Apache" href="http://xml.apache.org/"/&gt;
+        
         </pre>
-<p>Unlike the "<span class="codefrag">dir</span>" attribute, the value of "<span class="codefrag">href</span>"
-        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>
-<a name="N1011B"></a><a name="selecting-entries"></a>
+<p>
+          Unlike the "<span class="codefrag">dir</span>" attribute, the value of
+          "<span class="codefrag">href</span>" 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>
+<a name="N1011D"></a><a name="selecting-entries"></a>
 <h3 class="underlined_5">Selecting menu entries</h3>
-<p>Forrest decides which menu entries to display, by examining the
-          "<span class="codefrag">tab</span>" attributes in the <span class="codefrag">site.xml</span> file. The children of 
-          all <span class="codefrag">site.xml</span> entries with a
-          "<span class="codefrag">tab</span>" 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 "<span class="codefrag">community</span>" element in the 
-          example below). Child elements that have a different 
+<p>
+          Forrest decides which menu entries to display, by examining the
+          "<span class="codefrag">tab</span>" attributes in the <span class="codefrag">site.xml</span> file. The children of all <span class="codefrag">site.xml</span>
+          entries with a "<span class="codefrag">tab</span>" 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 "<span class="codefrag">community</span>"
+          element in the example below). Child elements that have a different
           "<span class="codefrag">tab</span>" 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 "<span class="codefrag">howto-samples</span>" element
-          below).</p>
-<p>Consider our <span class="codefrag">site.xml</span> example:</p>
+          parents, and will also form the root of a new menu for a tab with the
+          appropriate name (see the "<span class="codefrag">howto-samples</span>" element below).
+        </p>
+<p>
+          Consider our <span class="codefrag">site.xml</span> example:
+        </p>
 <pre class="code">
 &lt;site label="Forrest" href="" <strong>tab="home"</strong>
   xmlns="http://apache.org/forrest/linkmap/1.0"&gt;
@@ -638,36 +659,44 @@
         &lt;step1 label="Step 1" href="step1.html"/&gt;
       ...</pre>
 <p>
-          Every <span class="codefrag">site.xml</span> node can potentially have a "<span class="codefrag">tab</span>" attribute.  If
-          unspecified, nodes inherit the "<span class="codefrag">tab</span>" of their parent.  Thus
-          everything in the <strong>&lt;about&gt;</strong> section has an implicit
-          <span class="codefrag">tab="home" </span>attribute.</p>
+          Every <span class="codefrag">site.xml</span> node can potentially have a "<span class="codefrag">tab</span>" attribute. If
+          unspecified, nodes inherit the "<span class="codefrag">tab</span>" of their parent.
+          Thus everything in the <strong>&lt;about&gt;</strong> section has an
+          implicit <span class="codefrag">tab="home" </span>attribute.
+        </p>
 <div class="note">
 <div class="label">Note</div>
-<div class="content">You can see this by viewing your site's 
-        <a href="../abs-menulinks">abs-menulinks</a> pipeline in a
-          browser.</div>
+<div class="content">
+          You can see this by viewing your site's
+          <a href="../abs-menulinks">abs-menulinks</a> pipeline in a
+          browser.
+        </div>
 </div>
-<p>Say that the user is viewing the <span class="codefrag">linking.html</span>
-          page.  The <strong>&lt;linking&gt;</strong> node has an implicit tab
-          value of "<span class="codefrag">home</span>".  Forrest will select <em>all nodes with
-            tab="home"</em> and put them in the menu.
+<p>
+          Say that the user is viewing the <span class="codefrag">linking.html</span> page. The
+          <strong>&lt;linking&gt;</strong> node has an implicit tab value of
+          "<span class="codefrag">home</span>". Forrest will select <em>all nodes with
+          tab="home"</em> and put them in the menu.
         </p>
-<a name="N10175"></a><a name="other-menu-selection"></a>
+<a name="N10177"></a><a name="other-menu-selection"></a>
 <h3 class="underlined_5">Alternative menu selection mechanisms.</h3>
 <p>
           The "<span class="codefrag">tab</span>" 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.
+          entries is not the only one, although it is the most flexible. Here we
+          describe a few alternatives.
         </p>
-<a name="N10181"></a><a name="dir-menu-selection"></a>
+<a name="N10183"></a><a name="dir-menu-selection"></a>
 <h4>Directory-based selection</h4>
-<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>
+            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 alt="Directory-based site menu" src="images/dir-menu.png">&nbsp;&nbsp;&nbsp;
-            <img alt="community/ directory menu" src="images/dir-menu2.png">&nbsp;&nbsp;&nbsp;
+<img alt="Directory-based site menu" src="images/dir-menu.png">
+            &nbsp;&nbsp;&nbsp;
+            <img alt="community/ directory menu" src="images/dir-menu2.png">
+            &nbsp;&nbsp;&nbsp;
             <img alt="community/howto/ directory menu" src="images/dir-menu3.png">
           </p>
 <p>
@@ -683,30 +712,31 @@
               entries.</li>
           
 </ul>
-<a name="N101B1"></a><a name="book-menu-selection"></a>
+<a name="N101B3"></a><a name="book-menu-selection"></a>
 <h4>Specifying menus with book.xml</h4>
 <p>
             Historically, menus in Forrest have been generated from a
-            <span class="codefrag">book.xml</span> file, one per directory.  This mechanism is
+            <span class="codefrag">book.xml</span> file, one per directory. This mechanism is
             still available, and if a <span class="codefrag">book.xml</span> is found, it will be
-            used in preference to the menu generated by the <span class="codefrag">site.xml</span> file. The <span class="codefrag">book.xml</span>
-            files can use "<span class="codefrag">site:</span>" URIs to ease the maintenance burden
-            that led to obsolescence of book.xml files.  In general, however, we
-            recommend that users avoid <span class="codefrag">book.xml</span> files.
+            used in preference to the menu generated by the <span class="codefrag">site.xml</span> file. The
+            <span class="codefrag">book.xml</span> files can use "<span class="codefrag">site:</span>" URIs to
+            ease the maintenance burden that led to obsolescence of book.xml
+            files. In general, however, we recommend that users avoid
+            <span class="codefrag">book.xml</span> files.
           </p>
-<a name="N101CE"></a><a name="tab-selection"></a>
+<a name="N101D0"></a><a name="tab-selection"></a>
 <h3 class="underlined_5">Selecting the current tab</h3>
 <p>
           The tab selection algorithm is quite simple: the tab with the
-          "<span class="codefrag">id</span>" which matches that of the current <span class="codefrag">site.xml</span>
-          node is "selected". However the interaction of <span class="codefrag">tabs.xml</span> and <span class="codefrag">site.xml</span>
-          while powerful, can be complex to establish.
+          "<span class="codefrag">id</span>" which matches that of the current <span class="codefrag">site.xml</span> node is
+          "selected". However the interaction of <span class="codefrag">tabs.xml</span> and <span class="codefrag">site.xml</span> while powerful, can
+          be complex to establish.
         </p>
-<a name="N101E4"></a><a name="tab-site"></a>
+<a name="N101E6"></a><a name="tab-site"></a>
 <h3 class="underlined_5">Configuring the interaction between tabs.xml and site.xml</h3>
 <p>
-          This is a collection of tips to assist with getting your menus and tabs
-          to properly display.
+          This is a collection of tips to assist with getting your menus and
+          tabs to properly display.
         </p>
 <ul>
           
@@ -771,19 +801,22 @@
         
 </ul>
 </div>
-
     
-<a name="N10237"></a><a name="toc-generation"></a>
+<a name="N10239"></a><a name="toc-generation"></a>
 <h2 class="underlined_10">Table of Contents Generation</h2>
 <div class="section">
-<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 <span class="codefrag">src/documentation/skinconf.xml</span> using the 
-      "<span class="codefrag">toc</span>" element.</p>
+<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 <span class="codefrag">src/documentation/skinconf.xml</span> using the
+        "<span class="codefrag">toc</span>" element.
+      </p>
 <pre class="code">
+
 &lt;toc level="2" location="page"/&gt;
+      
       </pre>
 <ul>
         
@@ -812,21 +845,19 @@
             in both the page and the menu positions</li>
           
 </ul>
-        
 </li>
       
 </ul>
 </div>
     
-    
-<a name="N1026C"></a><a name="linking"></a>
+<a name="N1026D"></a><a name="linking"></a>
 <h2 class="underlined_10">Linking systems</h2>
 <div class="section">
-<a name="N10272"></a><a name="direct-linking"></a>
+<a name="N10273"></a><a name="direct-linking"></a>
 <h3 class="underlined_5">Direct linking</h3>
 <p>
           In earlier versions of Forrest (and in similar systems), there has
-          been only one URI space: that of the generated site.  If <span class="codefrag">index.xml</span> wants to
+          been only one URI space: that of the generated site. If <span class="codefrag">index.xml</span> wants to
           link to <span class="codefrag">todo.xml</span> then <span class="codefrag">index.xml</span> would use
         </p>
 <pre class="code">
@@ -834,14 +865,14 @@
         </pre>
 <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
+          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
           [<a href="http://marc.theaimsgroup.com/?l=forrest-dev&m=103097808318773&w=2">mail ref</a>] and
           [<a href="http://www.w3.org/Provider/Style/URI.html">cool URIs</a>]. 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>
-<a name="N10297"></a><a name="indirect-linking"></a>
+<a name="N10298"></a><a name="indirect-linking"></a>
 <h3 class="underlined_5">Indirect linking</h3>
 <p>
           Forrest's solution is simple: instead of &lt;a href="todo.html"&gt;,
@@ -866,56 +897,60 @@
 <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.
+          "idea" of "the todo file". It doesn't matter where it physically
+          lives; that will be sorted out by Forrest.
         </p>
-<a name="N102BE"></a><a name="resolve-site-uris"></a>
+<a name="N102BF"></a><a name="resolve-site-uris"></a>
 <h4>Resolving site: URIs</h4>
 <p>
-            So how does "<span class="codefrag">site:todo</span>" get resolved?  A full answer
-            is provided in the <a href="#implementation">implementation</a>
-            section.  Essentially, the "<span class="codefrag">todo</span>" part has
-            "<span class="codefrag">/site//</span>" prepended, and "<span class="codefrag">/@href</span>" appended, to
-            form the string "<span class="codefrag">/site//todo/@href</span>".  This is
-            then used as an XPath expression in <span class="codefrag">site.xml</span> to identify the string
+            So how does "<span class="codefrag">site:todo</span>" get resolved? A full answer is
+            provided in the <a href="#implementation">implementation</a>
+            section. Essentially, the "<span class="codefrag">todo</span>" part has
+            "<span class="codefrag">/site//</span>" prepended, and "<span class="codefrag">/@href</span>"
+            appended, to form the string "<span class="codefrag">/site//todo/@href</span>". This
+            is then used as an XPath expression in <span class="codefrag">site.xml</span> to identify the string
             replacement, in this case "<span class="codefrag">todo.html</span>"
           </p>
 <p>
-            Thus by modifying the XPath prefix and suffix, almost any XML
-            format can be accommodated.
+            Thus by modifying the XPath prefix and suffix, almost any XML format
+            can be accommodated.
           </p>
 <div class="note">
 <div class="label">Note</div>
 <div class="content">
             Actually, the XPath is applied to XML generated dynamically from
-            <span class="codefrag">site.xml</span>.  The generated XML has each "@href" fully expanded ("absolutized")
-            and dot-dots (..) added as needed ("relativized").
+            <span class="codefrag">site.xml</span>. The generated XML has each "@href" fully expanded
+            ("absolutized") and dot-dots (..) added as needed ("relativized").
           </div>
 </div>
 <p>
-            Notice that the "//" allows us any degree of specificity when linking.
-            In the sample <span class="codefrag">site.xml</span> above, both "<span class="codefrag">site:new_content_type</span>" and
+            Notice that the "//" allows us any degree of specificity when
+            linking. In the sample <span class="codefrag">site.xml</span> above, both
+            "<span class="codefrag">site:new_content_type</span>" and
             "<span class="codefrag">site:about/your-project/new_content_type</span>" identify the
-            same node.  It is up to you to decide how specific to make links.  One
+            same node. It is up to you to decide how specific to make links. One
             nice benefit of link "ambiguity" is that <span class="codefrag">site.xml</span> can be reorganized
-            without breaking links.  For example, "new_content_type" currently
-            identifies a node in "your-project".  By leaving that fact unspecified
-            in "<span class="codefrag">site:new_content_type</span>" we are free to make
-            "new_content_type" its own XML file, or a node in another file, in
-            another category.
+            without breaking links. For example, "new_content_type" currently
+            identifies a node in "your-project". By leaving that fact
+            unspecified in "<span class="codefrag">site:new_content_type</span>" we are free to
+            make "new_content_type" its own XML file, or a node in another file,
+            in another category.
           </p>
-<a name="N102FC"></a><a name="resolve-ext-uris"></a>
+<a name="N102FD"></a><a name="resolve-ext-uris"></a>
 <h4>ext: URIs: linking to external URLs</h4>
 <p>
             The "<span class="codefrag">ext:</span>" scheme was created partly to demonstrate the
             ease with which new schemes can be defined, and partly for practical
             use. The "<span class="codefrag">ext:</span>" URIs identify nodes in <span class="codefrag">site.xml</span> below the
-            &lt;external-refs&gt; node.  By convention, nodes here link to URLs
+            &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 <span class="codefrag">site.xml</span> file.
           </p>
-<p>Here is a <span class="codefrag">site.xml</span> snippet illustrating "<span class="codefrag">external-refs</span>":</p>
+<p>
+            Here is a <span class="codefrag">site.xml</span> snippet illustrating "<span class="codefrag">external-refs</span>":
+          </p>
 <pre class="code">
+
 &lt;site&gt;
   ...
   &lt;external-refs&gt;
@@ -927,52 +962,61 @@
     &lt;/xml.apache.org&gt;
     ...
   &lt;/external-refs&gt;
-&lt;/site&gt;</pre>
+&lt;/site&gt;
+          </pre>
 <p>
-            As an example, &lt;a href="ext:commons/resolver"&gt;
-            generates the link
+            As an example, &lt;a href="ext:commons/resolver"&gt; generates the
+            link
             <a href="http://xml.apache.org/commons/components/resolver/">http://xml.apache.org/commons/components/resolver/</a>
           
 </p>
 <p>
             The general rules of <span class="codefrag">site.xml</span> and "<span class="codefrag">site:</span>" linking apply.
-            Specifically, the "@href" aggregation makes defining large numbers of
-            related URLs easy.
+            Specifically, the "@href" aggregation makes defining large numbers
+            of related URLs easy.
           </p>
-<a name="N1032F"></a><a name="source-uris"></a>
+<a name="N10330"></a><a name="source-uris"></a>
 <h4>Theory: source URIs</h4>
 <p>
-            The "<span class="codefrag">site:</span>" URIs like "<span class="codefrag">site:todo</span>" are examples of
-            "<em>source</em>" URIs, in contrast to the more usual
+            The "<span class="codefrag">site:</span>" URIs like "<span class="codefrag">site:todo</span>" are
+            examples of "<em>source</em>" URIs, in contrast to the more usual
             <span class="codefrag">foo.html</span> 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 "<span class="codefrag">http:</span>" or relative URIs
-            in the destination URI space, just like exotic XML source formats are
-            translated into plain old HTML in the output.
+            "<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
+            "<span class="codefrag">http:</span>" or relative URIs in the destination URI space,
+            just like exotic XML source formats are translated into plain old
+            HTML in the output.
           </p>
-<a name="N1034E"></a><a name="future-schemes"></a>
+<a name="N1034F"></a><a name="future-schemes"></a>
 <h4>Future schemes</h4>
 <p>
-            So far, the "<span class="codefrag">site:</span>" and "<span class="codefrag">ext:</span>" 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.
+            So far, the "<span class="codefrag">site:</span>" and "<span class="codefrag">ext:</span>" 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 class="ForrestTable" cellspacing="1" cellpadding="4">
             
 <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>
+              
+<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"><span class="codefrag">../../apidocs/org/apache/proj/SomeClass.html</span></td>
+              <td colspan="1" rowspan="1"><span class="codefrag">../../apidocs/org/apache/proj/SomeClass.html</span>
+              </td>
               <td colspan="1" rowspan="1">
                 Links to documentation for a Java class (typically generated by
                 <span class="codefrag">javadoc</span>).
@@ -984,7 +1028,8 @@
               
 <td colspan="1" rowspan="1">mail</td>
               <td colspan="1" rowspan="1">mail::&lt;Message-Id&gt;</td>
-              <td colspan="1" rowspan="1"><span class="codefrag">http://marc.theaimsgroup.com?t=12345678</span></td>
+              <td colspan="1" rowspan="1"><span class="codefrag">http://marc.theaimsgroup.com?t=12345678</span>
+              </td>
               <td colspan="1" rowspan="1">
                 Links to an email, identified by its <span class="codefrag">Message-Id</span>
                 header. Any mail archive website could be used.
@@ -996,7 +1041,8 @@
               
 <td colspan="1" rowspan="1">search</td>
               <td colspan="1" rowspan="1">search:&lt;searchterm&gt;</td>
-              <td colspan="1" rowspan="1"><span class="codefrag">http://www.google.com/search?q=searchterm</span></td>
+              <td colspan="1" rowspan="1"><span class="codefrag">http://www.google.com/search?q=searchterm</span>
+              </td>
               <td colspan="1" rowspan="1">Link to set of results from a search engine</td>
             
 </tr>
@@ -1006,7 +1052,8 @@
 <td colspan="1" rowspan="1">person</td>
               <td colspan="1" rowspan="1">person:JT, person:JT/blog etc</td>
               <td colspan="1" rowspan="1"><span class="codefrag">mailto:jefft&lt;at&gt;apache.org</span>,
-                <span class="codefrag">http://www.webweavertech.com/jefft/weblog/</span></td>
+                <span class="codefrag">http://www.webweavertech.com/jefft/weblog/</span>
+              </td>
               <td colspan="1" rowspan="1">
                 A "<span class="codefrag">person:</span>" scheme could be used, say, to insert an
                 automatically obfuscated email address, or link to a URI in some
@@ -1017,39 +1064,41 @@
           
 </table>
 <p>
-            There are even more possibilities in specific environments.  In an
+            There are even more possibilities in specific environments. In an
             intranet, a "<span class="codefrag">project:XYZ</span>" scheme could identify company
-            project pages.  In a project like <a href="http://ant.apache.org/">Apache
-              Ant</a>, each Task could be identified with
-            <span class="codefrag">task:&lt;taskname&gt;</span>, e.g. <span class="codefrag">task:pathconvert</span>.
+            project pages. In a project like <a href="http://ant.apache.org/">Apache
+            Ant</a>, each Task could be identified with
+            <span class="codefrag">task:&lt;taskname&gt;</span>, e.g.
+            <span class="codefrag">task:pathconvert</span>.
           </p>
 </div>
     
-<a name="N103F1"></a><a name="concept"></a>
+<a name="N103FB"></a><a name="concept"></a>
 <h2 class="underlined_10">Concept</h2>
 <div class="section">
 <p>
         The "<span class="codefrag">site:</span>" scheme and associated ideas for <span class="codefrag">site.xml</span> were
         originally described in <a href="http://marc.theaimsgroup.com/?l=forrest-dev&m=103444028129281&w=2">the 'linkmap' RT
-          email</a> 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 <span class="codefrag">site.xml</span> (section 4).  However, what is currently implemented
-        gains most of the advantages of the system.
+        email</a> 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 <span class="codefrag">site.xml</span>
+        (section 4). However, what is currently implemented gains most of the
+        advantages of the system.
       </p>
 </div>
     
-<a name="N10408"></a><a name="implementation"></a>
+<a name="N10412"></a><a name="implementation"></a>
 <h2 class="underlined_10">Implementation</h2>
 <div class="section">
-<p>Full details on the implementation of
-      <a href="../docs_0_80/sitemap-ref.html#linkrewriting_impl">link rewriting</a> and
-      <a href="../docs_0_80/sitemap-ref.html#menu_generation_impl">menu generation</a> are available in
-      the <a href="../docs_0_80/sitemap-ref.html">Sitemap Reference</a>
+<p>
+        Full details on the implementation of
+        <a href="../docs_0_80/sitemap-ref.html#linkrewriting_impl">link rewriting</a> and
+        <a href="../docs_0_80/sitemap-ref.html#menu_generation_impl">menu generation</a> are
+        available in the <a href="../docs_0_80/sitemap-ref.html">Sitemap Reference</a>
+      
 </p>
 </div>
-
   
 </div>
 <!--+

Modified: forrest/site/docs_0_80/linking.pdf
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_80/linking.pdf?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
Binary files - no diff available.



Mime
View raw message