On Wed, May 13, 2009 at 4:04 PM, Michael Kay <mike(_at_)saxonica(_dot_)com>
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
--~------------------------------------------------------------------
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
To unsubscribe, go to: http://lists.mulberrytech.com/xsl-list/
or e-mail: <mailto:xsl-list-unsubscribe(_at_)lists(_dot_)mulberrytech(_dot_)com>
--~--