Re: XSL - Documentation

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