Self documenting sitemaps

[Ross Gardler <rg...@apache.org>]

This snippet from a mail on Cocoon Dev will be interesting to those 
wishing to improve our sitemap documentation.

-------- Original Message --------
From: Bertrand Delacretaz <bd...@apache.org>
Subject: Re: [PlanetCocoon] 4 new ideas to discuss on Planet Cocoon
Date: Mon, 23 May 2005 20:44:06 +0200
To: dev@cocoon.apache.org

Le 23 mai 05, à 20:33, Sebastien Arbogast a écrit :
> ...finally it appears
> it's not as interesting as I thought at the beginning because current
> samples are code only whereas we think code-illustrated documentation
> is what we need most...

Sure. Note that I just applied a patch to both the 2.1 branch and the
trunk, which allows you to add annotation to sitemaps, like:

<map:match pattern="news.pdf">
    <n:explain>Get news in XML from server</n:explain>
    <map:generate src="http://newsserver/somestuff.xml"/>

    <n:explain>Convert to xsl-fo</n:explain>
    <map:transform src="news-to-fo.xsl"/>

    <n:explain>
      And let <a href="http://xml.apache.org/fop">FOP</a> generate PDF
    </n:explain>
    <map:serialize type="fo2pdf"/>
</map:match>

This could be very useful to create self-describing samples.

There's also stuff in the tour block that could be reused to extract
code excerpts from sitemaps, xml and text files.

-Bertrand