Re: XSL - Documentation

On Wed, May 13 2009 15:04:23 +0100, 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?

That depends on a lot of imponderables such as who the user is, what
their experience is, and how often they'd be using it.  As Ken said at
least three messages ago in this thread: different strokes for different
folks.

> 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"/>

Well, yes.  Though I'm sure we could find someone who thinks it's worse
than the alternative (for any given value of 'alternative').

Even if you documented parameters that way, I expect you'd still want
some narrative description of the function as a whole.  If that extends
to, say, a couple of paragraphs and a list, then there'll be some people
who would prefer wiki-style/Trac-style inferred or simplified markup
over putting in every <para> and </para>, etc.  There'll be others who'd
like the option of mixing simplified markup and those <para> and </para>
as it suits them.

If you, or anyone, went for only XML markup for the documentation, would
you also require the user to add DocBook <indexterm> elements for the
sake of producing an index later?  If you leave adding indexterms up to
the processing, that's the first step on the slippery slope towards
letting the software infer all the markup.  Where's the best place to
draw the line depends on the person, their experiences, and their
preferences (and their IDE).

Regards,


Tony Graham                         Tony.Graham@xxxxxxxxxxxxxxxxxxxxxx
Director                                  W3C XSL FO SG Invited Expert
Menteith Consulting Ltd
XML, XSL and XSLT consulting, programming and training
Registered Office: 13 Kelly's Bay Beach, Skerries, Co. Dublin, Ireland
Registered in Ireland - No. 428599   http://www.menteithconsulting.com
  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --
xmlroff XSL Formatter                               http://xmlroff.org
xslide Emacs mode                  http://www.menteith.com/wiki/xslide
Unicode: A Primer                               urn:isbn:0-7645-4625-2