Subject: Re: [xsl] XSL - Documentation From: James Fuller <james.fuller.2007@xxxxxxxxx> Date: Wed, 13 May 2009 16:17:32 +0200 |
On Wed, May 13, 2009 at 4:04 PM, Michael Kay <mike@xxxxxxxxxxxx> wrote: >> If you pretended that the C function documented above was a >> XSLT function and invented some simplified syntax on the fly >> (as I'm about to do), you'd end up with something like: >> >> ------------------------------------------------------------ >> <x:doc xmlns:x="http://example.org/documentation"> >> $res:: Result tree. >> $fo_doc:: #FoDoc to which to write output. >> $fo_tree:: Pointer to generated FO tree. >> $area_tree:: Pointer to generated area tree. >> $continue_after_error:: Whether to continue after a formatting error. >> $debug_level:: What debugging output to generate. >> $error:: Indication of any error that occurred. >> >> Generates FO and area trees from $res result tree. >> </x:doc> >> ------------------------------------------------------------ >> >> which is a lot easier to write, read, and update than putting >> DocBook or DITA into the stylesheet and is still sufficiently >> structured that, with some XSLT munging this time, you can >> get from there to DocBook or DITA and from thence to HTML or >> to whatever. > > 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"/> but placing this kind of stuff in an attribute means we might run into I18N issues at some point ... I think all successful code documentation systems (perldoc, javadoc, etc) were a dsl so I have no probs with learning another very small language. cheers, Jim Fuller
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
RE: [xsl] XSL - Documentation, Michael Kay | Thread | Re: [xsl] XSL - Documentation, Andrew Welch |
RE: [xsl] XSL - Documentation, Michael Kay | Date | Re: [xsl] XSL - Documentation, DavePawson |
Month |