Subject: RE: [xsl] XSL - Documentation From: "Lumley, John" <john.lumley@xxxxxx> Date: Thu, 14 May 2009 06:52:46 +0000 |
> 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.
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
Re: [xsl] XSL - Documentation, DavePawson | Thread | Re: [xsl] Placing an element in a v, Tony Graham |
Re: [xsl] XSL - Documentation, DavePawson | Date | Re: [xsl] XSL - Documentation, David Carlisle |
Month |