Return-Path: Delivered-To: apmail-forrest-svn-archive@www.apache.org Received: (qmail 5879 invoked from network); 9 Feb 2006 00:28:40 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 9 Feb 2006 00:28:40 -0000 Received: (qmail 62759 invoked by uid 500); 9 Feb 2006 00:28:16 -0000 Delivered-To: apmail-forrest-svn-archive@forrest.apache.org Received: (qmail 62485 invoked by uid 500); 9 Feb 2006 00:28:15 -0000 Mailing-List: contact svn-help@forrest.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: "Forrest Developers List" List-Id: Delivered-To: mailing list svn@forrest.apache.org Received: (qmail 62001 invoked by uid 99); 9 Feb 2006 00:28:12 -0000 Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 08 Feb 2006 16:28:11 -0800 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194) by apache.org (qpsmtpd/0.29) with SMTP; Wed, 08 Feb 2006 16:27:38 -0800 Received: (qmail 3268 invoked by uid 65534); 9 Feb 2006 00:27:17 -0000 Message-ID: <20060209002717.3263.qmail@minotaur.apache.org> Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: svn commit: r376128 [20/34] - in /forrest/site: ./ docs_0_60/ docs_0_60/howto/ docs_0_60/howto/bugzilla-patch/ docs_0_60/howto/multi/ docs_0_70/ docs_0_70/howto/ docs_0_70/howto/cvs-ssh/ docs_0_70/howto/multi/ docs_0_80/ docs_0_80/howto/ docs_0_80/howt... Date: Thu, 09 Feb 2006 00:26:32 -0000 To: svn@forrest.apache.org From: crossley@apache.org X-Mailer: svnmailer-1.0.6 X-Virus-Checked: Checked by ClamAV on apache.org X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N Added: forrest/site/docs_0_80/libre-intro.source.xml URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/libre-intro.source.xml?rev=376128&view=auto ============================================================================== --- forrest/site/docs_0_80/libre-intro.source.xml (added) +++ forrest/site/docs_0_80/libre-intro.source.xml Wed Feb 8 16:26:20 2006 @@ -0,0 +1,584 @@ + + +
+ Libre QuickStart + This document is the current full documentation on the "libre" + generator that was implanted into xml-forrest. +
+ +
+ Intro + 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". + +

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.

+

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:

+
    +
  • 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.
    • +
  • 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.
    • +
+
+
+ Using Libre now (0.0 alfa) + 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.
In other words: + don't expect a thing unless you've seen it work. (at this time) +
+ Generated Output +

The XML output that comes out of the generator largely follows this + example:

+ <?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> +

And it's not getting any harder in fact: only 2 elements, + <collection> and <item> and that should + do. The first maps to a menu-group in the navigation, guess what the second + maps to?

+

The number and value (and its meaning) of the attributes on these + elements are specified in the libre.xml file.

+
+
+ <code>libre.xml</code> Contents +

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.)

+

The dtd:

+ <!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 +> +
+ Building Blocks +

The following elements get the following meaning when interpreted + by the LibreConfigBuilder

+ <libre xmlns="http://outerx.org/libre/config/0.1"> +
    +
  • This is one of those libre.xml files, that will configure how + items are filteres, sorted and attributed
    • +
+ <entry location="[relative location path]" /> +
    +
  • Allows to manually sort out specific files or directories.
    • + +
  • Comparable to standard book.xml behaviour, except for the fact + that
    • +
      +
    • libre doesn't yet support external hrefs (should be easy + though)
      • +
    • there is no difference between <menu> and + <menu-item>, there just is <entry>. It + will become a <collection> or <item> in + the output based on the fact if the location points to a directory resp. a + file.
      • +
    • For locations that point to a filter it doesn't make sense, but + when it points to a directory it is nested <filter> and + <sort> elements get inherited down to the next level.
      • +
    +
+ This last remarks actually means (1) I need to + update the DTD to reflect this and (2) check the code for actually doing + this. + <auto> +
    +
  • Automatically generates more <collection> + and <item> elements in the output, based on the + specifications of the nested elements: <filter> (which + resources?) and <sort> (in which order?).
    • +
+ <filter logic="inverse" clear="no"> +
    +
  • This element wraps a so-called AttributeReader (there are + currently two of them: <xpath> and + <property>)
    • +
  • 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.
    • +
  • This wrapping filter element allows to inverse the + acceptance-logic (accept what normally should be rejected and vice versa).
    • + +
  • Using the clear="yes" 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.
    • +
+ <sort order="descending" clear="no"> +
    +
  • This element wraps a so called AttributeReader (there are + currently two of them: <xpath> and + <property>).
    • +
  • 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 <collection> and <item> + elements in the output will appear in the order defined by the alphabetic + sorting of these keys.
    • +
  • This wrapping sort element allows to reverse the order. + (z->a instead of a->z)
    • +
  • Using the clear="yes" 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.
    • +
+ <label>, <href>, <YOURTAG>.... {AttributeDefinitions} +
    +
  • The remainder of the elements inside the + <auto> tag specify the attributes that need to be applied to + the generated <collection> and <item> + elements in the output: <item label=".." href=".." YOURTAG=".." + />
    • +
  • There is currently only support for adding attributes, not + nested elements.
    • +
  • These elements all wrap a so called AttributeReader (there are + currently two of them: <xpath> and <property>)
    • +
  • 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.
    • +
+ <xpath expression="/document/header/title/text()"> +
    +
  • This element specifies an xpath AttributeReader to use inside + <filter>, <sort> or + {AttributeDefinitions}.
    • +
  • 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 (<sort> usage) or to fill in the + specified attribute (<label>, <href>... + use). When inside a <filter>: the presence of the node + results in passing the test.
    • +
+ This currently breaks for non xml (*.gif) + files, so get your filter right please, and in the mean time: sorry for not + being able to use it in the filter yet :-(. + <property name="path" regex="(\.[\\/])*(.*)" substitute="$2"/> +<property name="name" mask="CVS"/> +
    +
  • This element specifies an xpath AttributeReader to use inside + <filter>, <sort> or + {AttributeDefinitions}.
    • +
  • 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 (<sort> usage) or to fill in the specified attribute + (<label>, <href>... use). When inside a + <filter>, the test passes if the read property is not null + or "".
    • +
  • Furthermore this element allows to express more elaborate + true-false tests (filter use) or regex substitution (other use) + attributes:
    • +
      +
    • combination of @regex with @substitute accounts for a + s/{regex}/{substitute}/ kind of operation on the string property.
      • +
    • while @mask or @regex by their own (filter use) allow for a + glob-mask or regex test to be applied on the read property.
      • +
    +
+
+
+
+ Important Side Effects +

There are some things that libre is doing that you should be aware of.

+
+ No libre.xml +

When using an <auto> section, the filter will + NEVER accept the libre.xml file to be in the generated output. You + can however include a manual <entry> to point to the + libre.xml file if needed.

+
+
+ No Duplicates +

You can combine multiple <entry> and + <auto> elements after each other. The system will make sure + that the resulting list of <collection> and + <item> will not contain duplicates. So the filters in + <auto> sections lower down the libre.xml file + can include already accepted files or directories, they will only show up once + in the output.

+
+
+
+ Example Constructs +

Adding sorting and filtering to the filesystem with libre becomes a + subtle play with editable filesystem properties, smart XML content and + libre.xml 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 libre.xml files.

+
+ Sorting your files or your menu entries? +

In every case the very pragmatic approach can become something + like this:

+ + content + + xdocs + + 010Topic + + 010Foo + + 111Bar + + 050Aspect + + NotInList +

In combination with something that lives by the introduced + alphabetic order, but yet hides the ugly number-prefixes:

+ <?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> +

Will produce an automatic list of entries (collections and items + in the output) that

+
    +
  • <filter>: only resources which name starts + with a 3-digit pattern
    • +
  • No <sort>: in their natural filesystem order + assured by the digit-prefix
    • +
  • <label>: hold a label attribute that strips + of the ugly number prefix
    • +
+

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.

+
+
+ Naming your files or asking them their name? +

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.

+ <?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> +
+
+
+
+ Next Libre (0.1) + Next libre is in fact largely in your hands... just drop + the forrest-dev mail list + a line, and see what happens... +
+ Itches +

There is quite a number of fast code patches that can/need to + happen

+
    +
  • package renaming and restructuring (ideas welcome, but not top of + mind)
    • +
  • on same level: possible xmlns and/or elms/atts renaming on the + generated output and the libre.xml file
    • +
  • when compiling you currently get 4 stupid deprecation warnings + that should be removed, in fact:
    • +
  • 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.)
    • +
  • xpath property reader needs to survive working on a non-xml + document (by returning nothing rather then breaking on the exception)
    • +
  • general robustness and resilience towards + mis-configurations
    • +
  • filestreams need to get closed and avalon resources need to be + released properly
    • +
  • caching at the level of the generator needs to be set up
    • +
  • in fact general performance has not been subject to loads of + early optimizations :-P
    • +
+
+
+ Upcoming Features +

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:

+
+ Combinations of filter logic +

Some itching stuff:

+
    +
  • logic="inverse" on the <filter> element seems a bit + awkward
    • +
  • nth degree of slickness in the regexes will only bring + us so far, combinatory filter logic seems to be the way to go...:
    • +
+ <!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)+> +

So we can make up some richer:

+ +<filter> + <not> + <and> + <xpath .../> + <not><property ..../></not> + <or> + ... + </or> + </and> + </not> +</filter> + +
+
+ Separating property-retrieval from formatting and + testing +

Playing around with the attributes in + <property>:

+
    +
  • 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)
    • +
  • which in fact are hard (if not impossible) to rule out by + modifying the DTD
    • +
  • makes you wonder why it's not available on the <xpath> + ?
    • +
+

So maybe an example more down the lines of the following would be + easier to use:

+ <label><!-- same applies for the sort context --> + <regexformatter exp="..." substitute="...."> + <property name="absoluteLocation" /> + </regexformatter> +</label> +

Allowing the formatter to be used around the xpath reader as well. + And opening up the possibility to maybe format other stuff than Strings: + <dateformat format="dd/mmm/yy">

+

It would also clearly distinguish the semantical difference of + applying a test in the <filter> context:

+ <filter> + <regextest match="..."> + <property ... /> + </regextest> +</filter> +

And more logically introduce other tests like <globtest + match="..."> or <availabletest> or...

+
+
+ Replace the introspection with semantically richer named + properties to read. +

Currently the <property + name="someJavaBeanProp"> is applied in a java introspection for the + getSomeJavaBeanProp() on the java.io.File 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:

+
    +
  • lead to a lesser user guidance for the libre.xml writer using + an XML (and DTD) savvy editor
    • +
  • leads to assuming the libre.xml editor has access + to and knows how to interpret jdk javadoc
    • +
  • 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.
    • +
  • leads to confusion for all, since who actually knows the subtle + difference between all the get*Path methods on java.io.File?
    • +
+

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:

+
    +
  • name
    • +
  • isDirectory (isCollection?)
    • +
  • abs and relPath (or abs/rel Location? why would we need + abs?)
    • +
  • canRead
    • +
  • canWrite
    • +
  • lastModified
    • +
  • length
    • +
+

The DTD would then list the possible attributeValues.

+
+
+
+ Avalonising +

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...

+
    +
  • 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.
    • +
  • Some investigation/feedback on the current hacker-way of using + the Composables could be nice
    • +
  • 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.
    • +
+
+
+ Unresolved Discussions +
    +
  • do we need support for nested elements inside + <item> output (retrieved by e.g. xpath expressions)?
    • +
  • do we need an extra <constant> like + attributereader that would allow like book.xml to add fixed values for + expressed attributes
    • +
  • clear set out inheritance rules, just doing 'something' now + :-(
    • +
  • votes on needed file properties to replace the current (limiting + and semantically poor) Java-introspection
    • +
+
+
+
+ Libre Design +

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.

+

So reflecting the current packagenames we kind of have these sets of + responsibilities

+
    +
  • *.yer.hierarchy: describe in a formal way how hierarchies + should be built up in order to have them dumped to XML using the + HierarchyReader.
    • +
  • *.yer.use.cocoon: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.
    • +
  • *.yer.impl: hold the different implementations of the + *.yer.hierarchy API
    • +
  • *.yer.impl.fs: (only current impl) Build the described + filesystem oriented implementation of the hierarchy. It is using the libre + configuration strategy.
    • +
  • *.yer.libre: 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)
    • +
+

... hope this somewhat clarifies how things have been setup for + now.

+
+ Dependencies +
    +
  • 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.
    • +
  • 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)
    • +
  • 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.
    • +
+
+
+ + \ No newline at end of file Propchange: forrest/site/docs_0_80/libre-intro.source.xml ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_80/linking.source.xml URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/linking.source.xml?rev=376128&view=auto ============================================================================== --- forrest/site/docs_0_80/linking.source.xml (added) +++ forrest/site/docs_0_80/linking.source.xml Wed Feb 8 16:26:20 2006 @@ -0,0 +1,602 @@ + + +
+ Menus and Linking +
+ + +
+ Introduction +

+ This document describes Forrest's internal URI space; how it is managed + with the "site.xml" configuration file, how menus are generated, + and how various link schemes (site: and ext:) operate. + An overview of the implementation is also provided. +

+
+ +
+ site.xml +

+ The "site.xml" configuration file is what we would call a "site map" + if Cocoon hadn't already claimed that term. + The "site.xml" is a loosely structured XML file, acting as a map of the + site's contents. It provides a unique identifier (an XPath address) + for "nodes" of information in the website. A "node" of site information + can be: +

+
    +
  • A category of information, like "the user guide". A category may + correspond to a directory, but that is not required.
    • +
  • A specific page, e.g. "the FAQ page"
    • +
  • A specific section in a page, e.g. the "general" section of the FAQ + page (identified by id="general" attribute)
    • +
+

+ In addition to providing fine-grained addressing of site info, the site.xml + allows metadata to be associated with each node, using + attributes or child elements. Most commonly, a label + attribute is used to provide a text description of the node. +

+

+ There are currently two applications of site.xml +

+
+
Menu generation
+
site.xml is used to generate the menus for the HTML website.
+
Indirect linking
+
site.xml provides a basic aliasing mechanism for linking, e.g. one + can write <link href="site:v0.80//changes"> from anywhere in the site, and + link to the "changes" information node (translated to changes.html). + More on this below.
+
+

+ Here is a sample site.xml ... +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> +

As you can see, things are quite free-form. The rules are as follows:

+
    +
  • The root element must be "site", and normal content should be in the + namespace http://apache.org/forrest/linkmap/1.0 (Feel + free to mix in your own content (RDF, dublin core, etc) under new + namespaces)
    • +
  • Element names are used as identifiers. The "foo" in + "site:foo" must therefore be a valid NMTOKEN.
    • +
  • Elements with href attributes can be used as identifiers + in "site:" URIs
    • +
  • Relative href attribute contents are "accumulated" by prepending hrefs + from ancestor nodes
    • +
  • Elements without label attributes (and their children) + are not displayed in the menu.
    • +
  • Elements below external-refs are mapped to the + "ext:" scheme. So "ext:commons/resolver/" becomes + "http://xml.apache.org/commons/resolver/"
    • +
+

+ See another explained example. +

+
+ + + +
+ Table of Contents Generation +

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 src/documentation/skinconf.xml using the + "toc" element.

+ + + ]]> + +
    +
  • level - is the depth to which you + want your table of contents to go. Setting it to "3" will therefore + include sections nested to 3 levels. Setting this to "0" will result in + no table of contents being generated.
    • +
  • location - indicates where you + want the table of contents to be rendered. It can be set to one of + three values: +
      +
    • page - the table of contents will be rendered + at the top of the body of your page
      • +
    • menu - the table of contents will be rendered + in the menu to the left of the body of the page
      • +
    • menu, page - table of contents will be rendered + in both the page and the menu positions
      • +
    +
    • +
+
+ +
+ Linking systems + +
+ Direct linking +

+ In earlier versions of Forrest (and in similar systems), there has + been only one URI space: that of the generated site. If index.xml wants to + link to todo.xml then index.xml would use +

+ + <a href="todo.html">to-do list<a> + +

+ The theoretical problem with this is that the content producer should + not know or care how Forrest is going to render the source. A URI + should only identify a resource, not specify it's type + [mail ref] and + [cool URIs]. 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. +

+
+ +
+ Indirect linking +

+ Forrest's solution is simple: instead of <a href="todo.html">, + write <a href="site:v0.80//todo"> where: +

+
+
site
+
is a URI "scheme"; a namespace that restricts + the syntax and semantics of the rest of the URI + [rfc2396]. The semantics of "site" are + "this identifier locates something in the site's XML sources".
+
todo
+
identifies the content in todo.xml by reference to a + "node" of content declared in site.xml
+
+

+ We call this indirect, or semantic 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. +

+ +
+ Resolving site: URIs + +

+ So how does "site:v0.80//todo" get resolved? A full answer + is provided in the implementation + section. Essentially, the "todo" part has + "/site//" prepended, and "/@href" appended, to + form the string "/site//todo/@href". This is + then used as an XPath expression in site.xml to identify the string + replacement, in this case "todo.html" +

+

+ Thus by modifying the XPath prefix and suffix, almost any XML + format can be accommodated. +

+ + Actually, the XPath is applied to XML generated dynamically from + site.xml. The generated XML has each "@href" fully expanded ("absolutized") + and dot-dots (..) added as needed ("relativized"). + + +

+ Notice that the "//" allows us any degree of specificity when linking. + In the sample site.xml above, both "site:v0.80//new_content_type" and + "site:about/your-project/new_content_type" identify the + same node. It is up to you to decide how specific to make links. One + nice benefit of link "ambiguity" is that site.xml can be reorganized + without breaking links. For example, "new_content_type" currently + identifies a node in "your-project". By leaving that fact unspecified + in "site:new_content_type" we are free to make + "new_content_type" its own XML file, or a node in another file, in + another category. +

+
+ +
+ ext: URIs: linking to external URLs +

+ The "ext:" scheme was created partly to demonstrate the + ease with which new schemes can be defined, and partly for practical + use. The "ext:" URIs identify nodes in site.xml below the + <external-refs> node. By convention, nodes here link to URLs + outside the website, and are not listed in the menu generated from + the site.xml file. +

+

Here is a site.xml snippet illustrating "external-refs":

+ + ... + + + + + + + + ... + +]]> +

+ As an example, <a href="ext:commons/resolver"> + generates the link + http://xml.apache.org/commons/components/resolver/ +

+

+ The general rules of site.xml and "site:" linking apply. + Specifically, the "@href" aggregation makes defining large numbers of + related URLs easy. +

+
+ +
+ Theory: source URIs +

+ The "site:" URIs like "site:v0.80//todo" are examples of + "source" URIs, in contrast to the more usual + foo.html style URIs, which we here call + "destination" URIs. This introduces an important concept: that + the "source" 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 "http:" or relative URIs + in the destination URI space, just like exotic XML source formats are + translated into plain old HTML in the output. +

+
+ + +
+ Future schemes +

+ So far, the "site:" and "ext:" 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. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
SchemeExample "From"Example "To"Description
javajava:org.apache.proj.SomeClass../../apidocs/org/apache/proj/SomeClass.html + Links to documentation for a Java class (typically generated by + javadoc). +
mailmail::<Message-Id>http://marc.theaimsgroup.com?t=12345678 + Links to an email, identified by its Message-Id + header. Any mail archive website could be used. +
searchsearch:<searchterm>http://www.google.com/search?q=searchtermLink to set of results from a search engine
personperson:JT, person:JT/blog etcmailto:jefft<at>apache.org, + http://www.webweavertech.com/jefft/weblog/ + A "person:" scheme could be used, say, to insert an + automatically obfuscated email address, or link to a URI in some + way associated with that person. +
+

+ There are even more possibilities in specific environments. In an + intranet, a "project:XYZ" scheme could identify company + project pages. In a project like Apache + Ant, each Task could be identified with + task:<taskname>, e.g. task:pathconvert. +

+
+
+
+
+ Concept +

+ The "site:" scheme and associated ideas for site.xml were + originally described in the 'linkmap' RT + email to the forrest-dev list (RT means 'random thought'; a + Cocoon invention). Only section 2 has been implemented, and there is + still significant work required to implement the full system + described. In particular, there is much scope for automating the + creation of site.xml (section 4). However, what is currently implemented + gains most of the advantages of the system. +

+
+
+ Implementation +

Full details on the implementation of + link rewriting and + menu generation are available in + the Sitemap Reference

+
+ + + \ No newline at end of file Propchange: forrest/site/docs_0_80/linking.source.xml ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_80/locationmap.source.xml URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/locationmap.source.xml?rev=376128&view=auto ============================================================================== --- forrest/site/docs_0_80/locationmap.source.xml (added) +++ forrest/site/docs_0_80/locationmap.source.xml Wed Feb 8 16:26:20 2006 @@ -0,0 +1,280 @@ + +
+ Locationmaps +
+ +
+ About Locationmaps +

A locationmap defines a mapping from requests to location strings.

+ +

It was conceived to:

+ +
    +
  • Provide a more powerful means for semantic linking.
    • +
  • Enable Forrest with a standard configuration override mechanism.
    • +
  • Decouple the conceptual source space used by Cocoon from + the concrete source space, so that a change in the concrete sources + does not impact on the sitemap.
    • +
+ +

In other words, the locationmap enables content to be retrieved from a location + that is defined in a locationmap file (located at + PROJECT_HOME/src/documentation/content/locationmap.xml file. The + advantage of this is that the URL seen by the user need bear no relation to the location + of the source document, thus Forrest can separate the client URL space from the source + document URL space. Thus, using the locationmap it is possible to pull together + documents from many different locations into a single uniform site.

+ +

In addition, since the user URL space is now not connected to the source URL space + it is possible to move source documents without breaking any existing user links.

+ +

The syntax of a locationmap resembles that of the sitemap, in that it also makes use + of Matchers and Selectors to traverse a tree of nodes towards a leaf. In the case of + the locationmap however the leaf does not identify a pipeline, but instead identifies + a location string.

+ +

Apache Forrest looks in the standard location for the source file first (by default + PROJECT_HOME/src/documentation/content/...), if a file is found in this + location then the locationmap is not consulted. However, if one is not found then the + locationmap is used to resolve the source file. The locationmap is resolved via the + core sitemap, this means that you can generate it dynamically if you so wish. Simply + add a match that looks something like this to your projects sitemap:

+ + + <map:match pattern="locationmap-project.xml"> + <map:generate src="..."/> + <map:transform src="..."/> + <map:serialize type="xml"/> + </map:match> + + +
+ +
+ Naming Convention +

For those that are familiar with name + resolution servers or the Handles Service, it might be easier to think of the + locationmap as a name resolution module or sort of a handle resolution module + that it accepts "names" or whatever you desire to call these "hints" and + returns the location.

+ +

The thought is that by using hints that look a little like a + file name it disguises what locationmaps are really doing for us. + By using URN-style names, we are truly + disassociating the name/hint from the physical location.

+ +

For example, here is a locationmap entry based purely on filename:

+ + +<map:transform src="{lm:xhtml2html.xsl}"/> + + +

and here is that same entry using a "name" style. One implies + a certain physical location where as the one below is truly a name that + needs to be resolved to a physical location.

+ + +<map:transform src="{lm:transform.xhtml2.html}"/> + + +

Where the resource is provided by a plugin rather than Forrest itself + this is prefixed with the last part of the plugin name. For example:

+ + +<map:transform src="{lm:projectInfo.transform.doap.html}"/> + + +

The format is essentially one of:

+ + +[PLUGIN_NAME.]resource-type(dot)from-format(dot)to-format + +

or

+ +[PLUGIN_NAME.]resource-type(dot)type(dot)name + + +

Examples of these two:

+ +transform.transform.xthml2.html +graphic.png.project-logo +projectInfo.transform.changes.rss + +
+ +
+ Multiple Location Selectors +

You can define multiple possble locations for a file in the locationmap + with the following code:

+ + +<match pattern="tabs.xml"> + <select type="exists"> + <location src="{project:content.xdocs}tabs1.xml"/> + <location src="{project:content.xdocs}tabs2.xml"/> + </select> +</match> + + +

Each location will be tested in turn, if the file exists then it will be returned + as a match, otherwise testing will continue.

+
+ +
+ Locationmap Examples +
+ Retrieving an XDoc via HTTP + + +

Normally files are generated from {project:content.xdocs}. + Using the Locationmap it is possible to make these files come from elsewhere. + This is useful if you want to pull files from different directory structures, + or even remote repositories. For example, the following location match + will match any request for a document below "remoteDemo" and will retrieve + the source file from the Apache Forrest SVN repository (directly from the + ASF's SVN webserver). This + is an ideal way to ensure that your published docs are always up-to-date.

+ + + <match pattern="remoteDemo/**.xml"> + <location src="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/xdocs/{1}.xml" /> + </match> + + +

Note that because this is a wildcard matcher you can request any page + from the svn server simply by requesting + /remoteDemo/PATH/TO/FILE/FILENAME.html. In addition, we + can request any other output format available via Forrest plugins.

+ +

When including resources from remote repositories one has to + be careful about things like site and ext + linking. If the targets are not defined in the local + site.xml file then these links will be broken.

+ + Because of the above limitation many of the links in the + page generated from the above example are broken. + +
+ +
+ Retrieving HTML from a CMS + +

Using the locationmap you can use Forrest to retrieve data from a + Content Management System (CMS), wither local or remote. + As an example we will consider Apache Lenya.

+ +

Apache Lenya is a Java Open-Source Content Management System based + on open standards such as XML and XSLT and the Apache Software Stack, in particular the XML publishing + framework Apache Cocoon.

+ +

The following locationmap matcher will instruct Forrest to retrieve content from + http://lenya.zones.apache.org:8888/default/live/*.html?raw=true, whenever a local URL of + lenya/** is encountered.

+ + + <match pattern="lenya/**.xml"> + <location src="http://lenya.zones.apache.org:8888/default/live/{1}.html?raw=true" /> + </match> + + +

However, since the source returned by this match is HTML and not XDoc we must convert this + to our internal XDoc format before we can use it. We do this by adding the match below to our + project's sitemap.xmap file.

+ + +<map:match pattern="lenya/**.xml"> + <map:generate type="html" src="{lm:{0}}" /> + <map:transform src="{forrest:stylesheets}/html2document.xsl" /> + <map:serialize type="xml"/> +</map:match> + + +

Since this snippet uses the HTML generator you must also ensure that your sitemap has the HTML generator + component defined. That is, your sitemap must also include:

+ + +<map:components> + <map:generators default="file"> + <map:generator name="html" + src="org.apache.cocoon.generation.HTMLGenerator"> + <jtidy-config>WEB-INF/jtidy.properties</jtidy-config> + </map:generator> + </map:generators> +</map:components> + + +

Since the HTML generator uses JTidy we need to make available a JTidy configuration file. + This is placed in PROJECT_HOME/src/documentation/WEB-INF/jtidy.properties (the + location can be changed in the above sitemap snippet). A sample config file is given below:

+ + +indent=yes +indent-spaces=8 +wrap=72 +markup=no +output-xml=no +input-xml=no +show-warnings=yes +numeric-entities=yes +quote-marks=yes +quote-nbsp=yes +quote-ampersand=yes +break-before-br=yes +uppercase-tags=no +uppercase-attributes=no +char-encoding=latin1 + + + This requirement to add items to your project sitemap will be removed in a future version either by Lenya + outputting XDoc, or by Forrest switching to using XHTML as its internal format, or through the development of a + plugin for Lenya that will include the necessary processing (whichever comes first). + + This demo is an example only, it does not fully work at this time. For example, absolute URLs + in the source document need to be rewritten to ensure that they are matched by the locationmap. + +
+ +
+ Source Resolving +

As well as being able to use the locationmap as a parameter in the sitemap, + it is also possible to use it as a psuedo-protocol within resources processed + by Forrest. For example, you can use it to import an XSL provided by one plugin + within another plugin:

+ + + <xsl:import src="lm://OOo.transform.write.xdoc"/> + + +
+ +
+ Link Rewriting +

The locationmap can be used to rewrite URLs when the page is generated. + For example, when the locationmap has:

+ + <match pattern="rewriteDemo/**"> + <location src="http://www.domain.org/{1}.xml" /> + </match> + +

With the above match in the locationmap, a link which has href="lm:rewriteDemo/index" + will be rewritten to an offsite address at domain.org

+
+ +
+ + \ No newline at end of file Propchange: forrest/site/docs_0_80/locationmap.source.xml ------------------------------------------------------------------------------ svn:eol-style = native