Linkmaps implemented

[Jeff Turner <je...@apache.org>]

On Thu, Dec 26, 2002 at 02:11:49PM -0000, jefft@apache.org wrote:
>   Log:
>   Linkmap, and a few test modifications demonstrating the site: scheme
...  
>      <section>
>       <title>Forrestbot - automated documentation building robot</title>
>   -    <p>See <link href="../forrestbot.html">Forrestbot Introduction</link>.
>   +    <p>See <link href="site:forrestbot">Forrestbot Introduction</link>.
>        </p>
>      </section>

As you can see, linkmaps are working in the branch.  Compared to the
original linkmap RT:

http://marc.theaimsgroup.com/?l=forrest-dev&m=103444028129281&w=2

I've implemented the section labeled "2) Mapping nodes to rendered (HTML)
files".



Linkmap Implementation
----------------------

The implementation is fairly straightforward.  We start with a 'linkmap',
content/xdocs/site.xml:

<site href="" label="Forrest">
  <about label="About">
    <index label="Index" href="index.html"/>
    <download label="Download" href="http://www.apache.org/dyn/closer.cgi/xml/forrest/"/>
    <license label="License" href="license.html"/>
    ...
  </about>
  <documentation label="Documentation">
    <primer label="Forrest Primer" href="primer.html">
      <cvs href="#cvs"/>
    </primer>
    <forrest-contract label="Our Contract" href="forrest-contract.html"/>
    <forrestbot label="The Forrestbot" href="forrestbot.html"/>
    ...
  </documentation>
  ...
</site>


Each XML node represents an addressible unit of site information.  The
@href points to its Destination URI location.

When we encounter a link like <link href="site:forrestbot">, we first
convert it to a simpler URI, <link
href="linkmap:/site//forrestbot/@href">, with a SimpleMappingMetaModule
configured in sitemap.xmap as follows:

  <input-module name="site">
    <input-module name="linkmap" src="{src}" reloadable="true"/>
    <prefix>/site//</prefix>
    <suffix>/@href</suffix>
  </input-module>


Then the 'linkmap' InputModule uses the '/site//forrestbot/@href' part as
an XPath address into site.xml, and returns the @href.

A small complication is that the @href must be relative to the directory
of the file doing the linking.  Eg community/index.html must have
'../forrestbot.html'.  This is done through sitemap rules which generate
a 'relativized' linkmap:

   <map:match pattern="abs-linkmap">
     <map:generate src="content/xdocs/site.xml"/>
     <map:transform src="library/xslt/absolutize-linkmap.xsl"/>
     <map:serialize type="xml"/>
   </map:match>
   
   <map:match pattern="**linkmap">
     <map:generate src="cocoon:/abs-linkmap"/>
     <map:transform src="library/xslt/relativize-linkmap.xsl">
       <map:parameter name="path" value="{0}"/>
     </map:transform>
     <map:serialize type="xml"/>
   </map:match>

This relativized linkmap is then fed to the InputModule.


Auto-generated book.xml
-----------------------

While I was doing this, it occurred to me that book.xml files can be
generated from a single suitably hierarchical site.xml file.  I've
implemented this such that if a hand-edited book.xml is not present, then
it will be auto-generated from site.xml.  This means that most sites can
get away with the auto-generated menus, while still having the option to
use a hand-generated book.xml for 'unusual' directories.  The option of
being able to use a hand-created book.xml makes the system fully
backwards-compatible.

One particularly nice possibility of generating book.xml from site.xml,
is that we can generate different book.xml's based on site metadata, like
language, or file datestamp:

1) It should be pretty trivial to implement a switch to read site_de.xml,
site_fr.xml etc, instead of site.xml, and thereby generate multi-langauge
sites.
2) Imagine if site.xml entry had a timestamp next to it, indicating when
that page was last edited:

<site href="" label="Forrest">
  <about label="About">
    <index label="Index" href="index.html" timestamp="2002-12-27"/>
    <license label="License" href="license.html" timestamp="2002-03-02"/>
    <who label="Who we are" href="who.html" timestamp="2002-12-02/>
    <dreams label="Dream list" href="dreams.html" timestamp="2002-07-01"/>
  </about>
</site>

We could then auto-generate a book.xml containing only pages edited, say,
within the last month.  Or we could implement an auto-expiry policy, to
eliminate docs over a year old.

There are lots of interesting possibilities here.  Eg, a
audience="{user,developer}" attribute could be used to implement 'views'
of a site for different user groups, @access to implement access control,
etc.  Useful stuff for implementing a CMS-like system.  In fact the
general idea comes from Robert Koberg's LiveStoryBoard CMS's site.xml
file, which is swimming in metadata (@status, @printer_friendly, lots of
presentation stuff).


All suggestions on this stuff welcome.  I thought I'd leave it in the
branch for a few days to get general feedback, and then if everyone seems
happy, move to CVS HEAD.


--Jeff