RE: [xsl] XSL - Documentation

["Lumley, John" <john.lumley@xxxxxx>]

> But do we want users to have to learn yet another markup language?
>
> It seems to me that the obvious place to document a function parameter is
an
> extension attribute on the xsl:param element:
>
> <xsl:param name="fo_tree" x:doc="Pointer to generated FO tree"/>
>
> Michael Kay

Exactly the technique I use, with additional use of x:doc=".." on function and
template heads to carry out the same purpose. Then a simple script can
generate Javadoc-like HTML reference material (including of course the
'Javadoc' for the script that generates the 'Javadoc' ;-) It you want some
sort of styling in the attribute-borne comments, then you can build some
simple encoding scheme.

For more complex structures, they'll have to be in a foreign ('documentation')
namespace at stylesheet toplevel and you'll have to use adjacency to associate
deeper comments and functions/templates, or cross-ref through some form of
id.

A similar technique can be used to embed examples and testcases. In some of my
work on document layout <ex:example>layout declaration tree</ex:example>
structures can be placed as top-level children and then picked up by a
stylesheet to generate code and result 'atlases' of layouts available.

It all drives towards placing all relevant information as close together as
possible and *not* in hosts of separate files that need to be kept in strict
coherence.


--------------------------------------------------------------
John Lumley CEng FIEE        |
Hewlett-Packard Laboratories | Phone:  +44 117 312 8743
Long Down Avenue             | E-mail: John.Lumley@xxxxxx
Stoke Gifford                |  Fax:    +44 117 312 9937
BRISTOL BS34 8QZ,   U.K.     |


------------------------------------------------------
Hewlett-Packard Limited registered Office: Cain Road, Bracknell, Berks RG12
1HN Registered No: 690597 England.