[XSL-LIST Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

RE: XSL - Documentation

Subject: RE: XSL - Documentation
From: "Lumley, John" <john.lumley@xxxxxx>
Date: Thu, 14 May 2009 06:52:46 +0000
RE:  XSL - Documentation
> 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

PURCHASE STYLUS STUDIO ONLINE TODAY!

Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced!

Buy Stylus Studio Now

Download The World's Best XML IDE!

Accelerate XML development with our award-winning XML IDE - Download a free trial today!

Don't miss another message! Subscribe to this list today.
Email
First Name
Last Name
Company
Subscribe in XML format
RSS 2.0
Atom 0.3
Site Map | Privacy Policy | Terms of Use | Trademarks
Free Stylus Studio XML Training:
W3C Member
Stylus Studio® and DataDirect XQuery ™are products from DataDirect Technologies, is a registered trademark of Progress Software Corporation, in the U.S. and other countries. © 2004-2013 All Rights Reserved.