Added: forrest/site/docs_0_90/libre-intro.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/libre-intro.html?view=auto&rev=529910 ============================================================================== --- forrest/site/docs_0_90/libre-intro.html (added) +++ forrest/site/docs_0_90/libre-intro.html Wed Apr 18 01:10:58 2007 @@ -0,0 +1,1180 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<meta content="Apache Forrest" name="Generator"> +<meta name="Forrest-version" content="0.9-dev"> +<meta name="Forrest-skin-name" content="pelt"> +<title>Libre QuickStart (v0.9-dev)</title> +<link type="text/css" href="../skin/basic.css" rel="stylesheet"> +<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet"> +<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet"> +<link type="text/css" href="../skin/profile.css" rel="stylesheet"> +<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script> +<link rel="shortcut icon" href="../favicon.ico"> +</head> +<body onload="init()"> +<script type="text/javascript">ndeSetTextSize();</script> +<div id="top"> +<!--+ + |breadtrail + +--> +<div class="breadtrail"> +<a href="http://www.apache.org/">apache</a> > <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script> +</div> +<!--+ + |header + +--> +<div class="header"> +<!--+ + |start group logo + +--> +<div class="grouplogo"> +<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a> +</div> +<!--+ + |end group logo + +--> +<!--+ + |start Project Logo + +--> +<div class="projectlogo"> +<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a> +</div> +<!--+ + |end Project Logo + +--> +<!--+ + |start Search + +--> +<div class="searchbox"> +<form action="http://www.google.com/search" method="get" class="roundtopsmall"> +<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google"> + <input name="Search" value="Search" type="submit"> +</form> +</div> +<!--+ + |end search + +--> +<!--+ + |start Tabs + +--> +<ul id="tabs"> +<li> +<a class="unselected" href="../index.html">Welcome</a> +</li> +<li> +<a class="unselected" href="../contrib.html">Developers</a> +</li> +<li class="current"> +<a class="selected" href="../versions/index.html">Versioned Docs</a> +</li> +<li> +<a class="unselected" href="../pluginDocs/index.html">Plugins</a> +</li> +<li> +<a class="unselected" href="../tools/index.html">Tools</a> +</li> +</ul> +<!--+ + |end Tabs + +--> +</div> +</div> +<div id="main"> +<div id="publishedStrip"> +<!--+ + |start Subtabs + +--> +<div id="level2tabs"> +<a class="unselected" href="../docs_0_80/index.html">0.80 (current)</a><a class="selected" href="../docs_0_90/index.html">0.90-dev (under development)</a><a class="unselected" href="../docs_0_70/index.html">0.70 (past)</a> +</div> +<!--+ + |end Endtabs + +--> +<script type="text/javascript"><!-- +document.write("Last Published: " + document.lastModified); +// --></script> +</div> +<!--+ + |breadtrail + +--> +<div class="breadtrail"> + + + </div> +<!--+ + |start Menu, mainarea + +--> +<!--+ + |start Menu + +--> +<div id="menu"> +<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.90-dev</div> +<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;"> +<div class="menuitem"> +<a href="../docs_0_90/index.html">Overview</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/your-project.html">Using Forrest</a> +</div> +<div onclick="SwitchMenu('menu_1.1.3', '../skin/')" id="menu_1.1.3Title" class="menutitle">How-To</div> +<div id="menu_1.1.3" class="menuitemgroup"> +<div class="menuitem"> +<a href="../docs_0_90/howto/index.html">Overview</a> +</div> +<div onclick="SwitchMenu('menu_1.1.3.2', '../skin/')" id="menu_1.1.3.2Title" class="menutitle">Install Forrest</div> +<div id="menu_1.1.3.2" class="menuitemgroup"> +<div class="menuitem"> +<a href="../docs_0_90/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a> +</div> +</div> +<div class="menuitem"> +<a href="../docs_0_90/upgrading_09.html">Upgrading to 0.9</a> +</div> +<div class="menuitem"> +<a href="">Use Forrest</a> +</div> +<div onclick="SwitchMenu('menu_1.1.3.5', '../skin/')" id="menu_1.1.3.5Title" class="menutitle">Customize Forrest</div> +<div id="menu_1.1.3.5" class="menuitemgroup"> +<div class="menuitem"> +<a href="../docs_0_90/sitemap-explain.html">Sitemaps explained</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/howto/howto-custom-html-source.html">Custom html source</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/project-sitemap.html">Project sitemap</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/howto/howto-pdf-tab.html" title="Generate one pdf-document for all pages of a tab">Create tab PDF</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/howto/howto-corner-images.html">CSS corner SVG</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.1.3.6', '../skin/')" id="menu_1.1.3.6Title" class="menutitle">Integrate Forrest with tools</div> +<div id="menu_1.1.3.6" class="menuitemgroup"> +<div class="menuitem"> +<a href="../docs_0_90/howto/howto-forrest-from-maven.html">Maven Integration</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/catalog.html">Using DTD Catalogs</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.1.3.7', '../skin/')" id="menu_1.1.3.7Title" class="menutitle">Extend Forrest</div> +<div id="menu_1.1.3.7" class="menuitemgroup"> +<div class="menuitem"> +<a href="../docs_0_90/howto/howto-buildPlugin.html">Build a Plugin</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/skin-package.html">Package new Skins</a> +</div> +</div> +<div class="menuitem"> +<a href="../docs_0_90/howto/howto-asf-mirror.html">Download mirror</a> +</div> +<div onclick="SwitchMenu('menu_1.1.3.9', '../skin/')" id="menu_1.1.3.9Title" class="menutitle">Adding Documentation</div> +<div id="menu_1.1.3.9" class="menuitemgroup"> +<div class="menuitem"> +<a href="../howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a> +</div> +<div onclick="SwitchMenu('menu_1.1.3.9.2', '../skin/')" id="menu_1.1.3.9.2Title" class="menutitle">Multipage HowTo</div> +<div id="menu_1.1.3.9.2" class="menuitemgroup"> +<div class="menuitem"> +<a href="../docs_0_90/howto/multi/howto-multi.html">Introduction</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/howto/multi/step1.html">Step 1</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/howto/multi/step2.html">Step 2</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/howto/multi/step3.html">Step 3</a> +</div> +</div> +</div> +</div> +<div class="menuitem"> +<a href="../docs_0_90/faq.html">FAQs</a> +</div> +<div onclick="SwitchMenu('menu_1.1.5', '../skin/')" id="menu_1.1.5Title" class="menutitle">Background</div> +<div id="menu_1.1.5" class="menuitemgroup"> +<div class="menuitem"> +<a href="../docs_0_90/linking.html">Menus and Linking</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/searching.html">Search Options in Forrest</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/locationmap.html">Locationmap</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/sitemap-ref.html">Sitemap Reference</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/skins.html" title="About default skins, their naming and features">Skins</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/status-themes.html">Dispatcher versus Skins</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/cap.html">Sourcetype Action</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/validation.html">XML validation and entity resolution</a> +</div> +</div> +<div class="menuitem"> +<a href="../docs_0_90/changes.html">Changes</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/glossary.html">Glossary</a> +</div> +<div onclick="SwitchMenu('menu_1.1.8', '../skin/')" id="menu_1.1.8Title" class="menutitle">Reference docs</div> +<div id="menu_1.1.8" class="menuitemgroup"> +<div onclick="SwitchMenu('menu_1.1.8.1', '../skin/')" id="menu_1.1.8.1Title" class="menutitle">DTD documentation</div> +<div id="menu_1.1.8.1" class="menuitemgroup"> +<div class="menuitem"> +<a href="../dtdx/dtd-docs.html">Overview</a> +</div> +<div class="menuitem"> +<a href="../dtdx/document-v20.dtdx.html">document-v20</a> +</div> +<div class="menuitem"> +<a href="../dtdx/howto-v20.dtdx.html">howto-v20</a> +</div> +<div class="menuitem"> +<a href="../dtdx/faq-v20.dtdx.html">faq-v20</a> +</div> +<div class="menuitem"> +<a href="../dtdx/document-v13.dtdx.html">document-v13</a> +</div> +<div class="menuitem"> +<a href="../dtdx/howto-v13.dtdx.html">howto-v13</a> +</div> +<div class="menuitem"> +<a href="../dtdx/faq-v13.dtdx.html">faq-v13</a> +</div> +</div> +<div onclick="SwitchMenu('menu_1.1.8.2', '../skin/')" id="menu_1.1.8.2Title" class="menutitle">Doc samples</div> +<div id="menu_1.1.8.2" class="menuitemgroup"> +<div class="menuitem"> +<a href="../dtdx/document-v13.html">document-v13</a> +</div> +<div class="menuitem"> +<a href="../dtdx/document-v20.html">document-v20</a> +</div> +</div> +</div> +<div onclick="SwitchMenu('menu_selected_1.1.9', '../skin/')" id="menu_selected_1.1.9Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Older Docs</div> +<div id="menu_selected_1.1.9" class="selectedmenuitemgroup" style="display: block;"> +<div class="menuitem"> +<a href="../docs_0_90/primer.html">Forrest Primer</a> +</div> +<div class="menupage"> +<div class="menupagetitle">Libre</div> +</div> +<div class="menuitem"> +<a href="../docs_0_90/dreams.html">Dream list</a> +</div> +<div class="menuitem"> +<a href="../docs_0_90/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a> +</div> +</div> +</div> +<div id="credit"> +<hr> + This is documentation for development version v0.9-dev + (<a href="http://forrest.apache.org/versions/">More</a>)</div> +<div id="roundbottom"> +<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div> +<!--+ + |alternative credits + +--> +<div id="credit2"> +<a href="http://apachecon.com/2007/EU/"><img border="0" title="ApacheCon Europe 2007" alt="ApacheCon Europe 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-europe-125x125.png" style="width: 125px;height: 125px;"></a><a href="http://people.apache.org/calendar.html#200711"><img border="0" title="ApacheCon US 2007" alt="ApacheCon US 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-usa-125x125.png" style="width: 125px;height: 125px;"></a> +</div> +</div> +<!--+ + |end Menu + +--> +<!--+ + |start content + +--> +<div id="content"> +<div title="Portable Document Format" class="pdflink"> +<a class="dida" href="libre-intro.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br> + PDF</a> +</div> +<div class="trail">Font size: + <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button"> + <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button"> + <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 id="motd-area"> + This is documentation for development version v0.9-dev + (<a href="http://forrest.apache.org/versions/">More</a>)</div> +<div id="minitoc-area"> +<ul class="minitoc"> +<li> +<a href="#Intro">Intro</a> +</li> +<li> +<a href="#Using+Libre+now+%280.0+alfa%29">Using Libre now (0.0 alfa)</a> +<ul class="minitoc"> +<li> +<a href="#Generated+Output">Generated Output</a> +</li> +<li> +<a href="#Contents">libre.xml Contents</a> +<ul class="minitoc"> +<li> +<a href="#Building+Blocks">Building Blocks</a> +</li> +</ul> +</li> +<li> +<a href="#Important+Side+Effects">Important Side Effects</a> +<ul class="minitoc"> +<li> +<a href="#No+libre.xml">No libre.xml</a> +</li> +<li> +<a href="#No+Duplicates">No Duplicates</a> +</li> +</ul> +</li> +<li> +<a href="#Example+Constructs">Example Constructs</a> +<ul class="minitoc"> +<li> +<a href="#Sorting+your+files+or+your+menu+entries%3F">Sorting your files or your menu entries?</a> +</li> +<li> +<a href="#Naming+your+files+or+asking+them+their+name%3F">Naming your files or asking them their name?</a> +</li> +</ul> +</li> +</ul> +</li> +<li> +<a href="#Next+Libre+%280.1%29">Next Libre (0.1)</a> +<ul class="minitoc"> +<li> +<a href="#Itches">Itches</a> +</li> +<li> +<a href="#Upcoming+Features">Upcoming Features</a> +<ul class="minitoc"> +<li> +<a href="#Combinations+of+filter+logic">Combinations of filter logic</a> +</li> +<li> +<a href="#Separating+property-retrieval+from+formatting+and%0A++++++++++++testing">Separating property-retrieval from formatting and + testing</a> +</li> +<li> +<a href="#Replace+the+introspection+with+semantically+richer+named%0A++++++++++++properties+to+read.">Replace the introspection with semantically richer named + properties to read.</a> +</li> +</ul> +</li> +<li> +<a href="#Avalonising">Avalonising</a> +</li> +<li> +<a href="#Unresolved+Discussions">Unresolved Discussions</a> +</li> +</ul> +</li> +<li> +<a href="#Libre+Design">Libre Design</a> +<ul class="minitoc"> +<li> +<a href="#Dependencies">Dependencies</a> +</li> +</ul> +</li> +</ul> +</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> +</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 + 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> +</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> +<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> +<pre class="code"><?xml version="1.0" encoding="UTF-8"?> +<collection xmlns="http://outerx.org/yer/hierarchy/0.1"> + <collection label="content"> + <collection label="xdocs"> + <item label="dreams.xml" + href="src/documentation/content/xdocs/dreams.xml" + title="Forrest dream list"/> + <item label="faq.xml" + href="src/documentation/content/xdocs/faq.xml"/> + <item label="book.xml" + href="src/documentation/content/xdocs/book.xml"/> + <item label="contrib.xml" + href="src/documentation/content/xdocs/contrib.xml" + title="Contribution to Forrest"/> + <item label="mail-archives.xml" + href="src/documentation/content/xdocs/mail-archives.xml" + title="Mail Archives"/> + <item label="mail-lists.xml" + href="src/documentation/content/xdocs/mail-lists.xml" + title="Mailing Lists"/> + <item label="license.xml" + href="src/documentation/content/xdocs/license.xml" + title="The Apache Software License"/> + <item label="index.xml" + href="src/documentation/content/xdocs/index.xml" + title="Welcome to Forrest"/> + <item label="who.xml" + href="src/documentation/content/xdocs/who.xml" + title="Who we are"/> + </collection> + </collection> +</collection></pre> +<p> + And it's not getting any harder in fact: only 2 elements, + <span class="codefrag"><collection></span> and <span class="codefrag"><item></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> +<pre class="code"><!ELEMENT libre (entry | auto)*> +<!ELEMENT entry (label?, href?)> +<!ATTLIST entry + location CDATA #REQUIRED +> +<!ELEMENT auto (filter?, sorter?, label?, href?)> +<!ELEMENT label (xpath | property)> +<!ELEMENT href (xpath | property)> +<!ELEMENT filter (xpath | property)> +<!ATTLIST filter + logic (inverse | normal) "normal" + clear (yes | no) "no" +> +<!ELEMENT sorter (xpath | property)> +<!ATTLIST sorter + order (ascending | descending) "ascending" + clear (yes | no) "no" +> +<!ELEMENT xpath EMPTY> +<!ATTLIST xpath + expression CDATA #REQUIRED +> +<!ELEMENT property EMPTY> +<!ATTLIST property + name CDATA #REQUIRED + mask CDATA #IMPLIED + regex CDATA #IMPLIED + substitute CDATA #IMPLIED +></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> +<pre class="code"><libre xmlns="http://outerx.org/libre/config/0.1"></pre> +<ul> + +<li>This is one of those libre.xml files, that will configure how + items are filteres, sorted and attributed</li> + +</ul> +<pre class="code"><entry location="[relative location path]" /></pre> +<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 <span class="codefrag"><menu></span> and + <span class="codefrag"><menu-item></span>, there just is <span class="codefrag"><entry></span>. It + will become a <span class="codefrag"><collection></span> or <span class="codefrag"><item></span> 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 <span class="codefrag"><filter></span> and + <span class="codefrag"><sort></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> +<pre class="code"><auto></pre> +<ul> + +<li>Automatically generates more <span class="codefrag"><collection></span> + and <span class="codefrag"><item></span> elements in the output, based on the + specifications of the nested elements: <span class="codefrag"><filter></span> (which + resources?) and <span class="codefrag"><sort></span> (in which order?).</li> + +</ul> +<pre class="code"><filter logic="inverse" clear="no"></pre> +<ul> + +<li>This element wraps a so-called AttributeReader (there are + currently two of them: <span class="codefrag"><xpath></span> and + <span class="codefrag"><property></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> + +<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> + +</ul> +<pre class="code"><sort order="descending" clear="no"></pre> +<ul> + +<li>This element wraps a so called AttributeReader (there are + currently two of them: <span class="codefrag"><xpath></span> and + <span class="codefrag"><property></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"><collection></span> and <span class="codefrag"><item></span> + elements in the output will appear in the order defined by the alphabetic + sorting of these keys.</li> + +<li>This wrapping sort element allows to reverse the order. + (z->a instead of a->z)</li> + +<li>Using the <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> + +</ul> +<pre class="code"><label>, <href>, <YOURTAG>.... {AttributeDefinitions}</pre> +<ul> + +<li>The remainder of the elements inside the + <span class="codefrag"><auto></span> tag specify the attributes that need to be applied to + the generated <span class="codefrag"><collection></span> and <span class="codefrag"><item></span> + elements in the output: <span class="codefrag"><item label=".." href=".." YOURTAG=".." + /></span> +</li> + +<li>There is currently only support for adding attributes, not + nested elements.</li> + +<li>These elements all wrap a so called AttributeReader (there are + currently two of them: <xpath> and <property>)</li> + +<li>In these cases the wrapped AttributeReader is going to specify + which information-element is going to be retrieved from the file or directory + it is pointing at. This information element will be considered to be a simple + String-value that gets slided in as the corresponding output attribute + value.</li> + +</ul> +<pre class="code"><xpath expression="/document/header/title/text()"></pre> +<ul> + +<li>This element specifies an xpath AttributeReader to use inside + <span class="codefrag"><filter></span>, <span class="codefrag"><sort></span> 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 (<span class="codefrag"><sort></span> usage) or to fill in the + specified attribute (<span class="codefrag"><label></span>, <span class="codefrag"><href></span>... + use). When inside a <span class="codefrag"><filter></span>: the presence of the node + 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> +<pre class="code"><property name="path" regex="(\.[\\/])*(.*)" substitute="$2"/> +<property name="name" mask="CVS"/></pre> +<ul> + +<li>This element specifies an xpath AttributeReader to use inside + <span class="codefrag"><filter></span>, <span class="codefrag"><sort></span> 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 (<span class="codefrag"><sort></span> usage) or to fill in the specified attribute + (<span class="codefrag"><label></span>, <span class="codefrag"><href></span>... use). When inside a + <span class="codefrag"><filter></span>, 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> +<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> +<a name="N10175"></a><a name="No+libre.xml"></a> +<h4>No libre.xml</h4> +<p> + When using an <span class="codefrag"><auto> </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"><entry></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"><entry></span> and + <span class="codefrag"><auto></span> elements after each other. The system will + make sure that the resulting list of <span class="codefrag"><collection></span> + and <span class="codefrag"><item></span> will not contain duplicates. So the + filters in <span class="codefrag"><auto></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 + 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> +<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> +<pre class="code">+ content + + xdocs + + 010Topic + + 010Foo + + 111Bar + + 050Aspect + + NotInList</pre> +<p> + In combination with something that lives by the introduced + alphabetic order, but yet hides the ugly number-prefixes: + </p> +<pre class="code"><?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE libre PUBLIC "-//Outerthought//DTD Libre Configuration V0.1//EN" "libre-v01.dtd" > +<libre xmlns="http://outerx.org/libre/config/0.1"> + <auto> + <filter logic="normal"> + <property name="name" regex="\d{3}(.*)"/> + </filter> + <label> + <property name="name" regex="\d{3}(.*)" substitute="$1"/> + </label> + </auto> +</libre></pre> +<p> + Will produce an automatic list of entries (collections and items in + the output) that + </p> +<ul> + +<li> +<span class="codefrag"><filter></span>: only resources which name starts + with a 3-digit pattern</li> + +<li>No <span class="codefrag"><sort></span>: in their natural filesystem order + assured by the digit-prefix</li> + +<li> +<span class="codefrag"><label></span>: 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> +<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> +<pre class="code"><?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE libre PUBLIC "-//Outerthought//DTD Libre Configuration V0.1//EN" "libre-v01.dtd" > +<libre xmlns="http://outerx.org/libre/config/0.1"> + <entry location="dreams.xml" > + <label> + <xpath expression="/document/header/title/text()"/> + </label> + </entry> + <auto> + <filter> + <property name="name" regex="\.xml$" /> + </filter> + <sorter> + <xpath expression="/document/header/title/text()"/> + </sorter> + <label> + <xpath expression="/document/header/title/text()"/> + </label> + </auto> +</libre></pre> +</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> +<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> + +<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> +<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> +<a name="N10233"></a><a name="Combinations+of+filter+logic"></a> +<h4>Combinations of filter logic</h4> +<p> + Some itching stuff: + </p> +<ul> + +<li>logic="inverse" on the <filter> element seems a bit + awkward</li> + +<li> +<em>n</em>th degree of slickness in the regexes will only bring + us so far, combinatory filter logic seems to be the way to go...:</li> + +</ul> +<pre class="code"><!ELEMENT filter (xpath | property | and | or | not)> +<!ELEMENT not (xpath | property | and | or | not)> +<!ELEMENT and (xpath | property | and | or | not)+> +<!ELEMENT or (xpath | property | and | or | not)+></pre> +<p> + So we can make up some richer: + </p> +<pre class="code"> +<filter> + <not> + <and> + <xpath .../> + <not><property ..../></not> + <or> + ... + </or> + </and> + </not> +</filter> + </pre> +<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"><property></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 <filter>== test or <sort>==formatting)</li> + +<li>which in fact are hard (if not impossible) to rule out by + modifying the DTD</li> + +<li>makes you wonder why it's not available on the <xpath> + ?</li> + +</ul> +<p> + So maybe an example more down the lines of the following would be + easier to use: + </p> +<pre class="code"><label><!-- same applies for the sort context --> + <regexformatter exp="..." substitute="...."> + <property name="absoluteLocation" /> + </regexformatter> +</label></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"><dateformat format="dd/mmm/yy"> </span> + +</p> +<p> + It would also clearly distinguish the semantical difference of + applying a test in the <span class="codefrag"><filter></span> context: + </p> +<pre class="code"><filter> + <regextest match="..."> + <property ... /> + </regextest> +</filter></pre> +<p> + And more logically introduce other tests like <span class="codefrag"><globtest + match="..."></span> or <span class="codefrag"><availabletest></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"><property name="someJavaBeanProp"></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> + +<li>leads to assuming the <span class="codefrag">libre.xml</span> 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> +<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> + +<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> +<a name="N102E6"></a><a name="Unresolved+Discussions"></a> +<h3 class="underlined_5">Unresolved Discussions</h3> +<ul> + +<li>do we need support for nested elements inside + <span class="codefrag"><item></span> output (retrieved by e.g. xpath expressions)?</li> + +<li>do we need an extra <span class="codefrag"><constant></span> 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> +</div> + +<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> + +<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> +<a name="N1032E"></a><a name="Dependencies"></a> +<h3 class="underlined_5">Dependencies</h3> +<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> +</div> + +</div> +<!--+ + |end content + +--> +<div class="clearboth"> </div> +</div> +<div id="footer"> +<!--+ + |start bottomstrip + +--> +<div class="lastmodified"> +<script type="text/javascript"><!-- +document.write("Last Published: " + document.lastModified); +// --></script> +</div> +<div class="copyright"> + Copyright © + 2002-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a> +</div> +<!--+ + |end bottomstrip + +--> +</div> +</body> +</html>
Propchange: forrest/site/docs_0_90/libre-intro.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_90/libre-intro.pdf URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/libre-intro.pdf?view=auto&rev=529910 ============================================================================== Binary file - no diff available. Propchange: forrest/site/docs_0_90/libre-intro.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf