documenting sitemaps (was Re: Fixing a Howto)

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

Ferdinand Soethe wrote:
> Ross Gardler wrote:

...

[concerning the refdoc project in Cocoon]

>>>And once that documentation is added, that would be easy enough to
>>>read w/o having to extract it into html-documents. So I'd consider
>>>that stuff nice to have but nothing to put much effort into.
> 
> 
>>Fair enough. Thanks.
> 
> 
> That said I'm very much in favour of adding documentation there (the
> documentation of the html-pipeline should really be the only extensive
> document of that kind) and will do so where I come across useful
> pieces of info.

As you know I'm visiting all sitemaps at the moment, and will do so 
again in the near future as I clean them up (actually, I'm thinking of 
starting from the very beginning again, rebuilding as defined in our TR 
- but that's a whole different story).

Anyway, the point is. If you can point me at a document describing how 
to write this embedded documentation, or provide some examples of the 
kind of thing you want to see, or write a how-to on it (whichever is 
appropriate), then I will do my best to add comments as I go through.

Ross