Re: [xsl] XSL - Documentation

[Tony Graham <Tony.Graham@xxxxxxxxxxxxxxxxxxxxxx>]

On Wed, May 13 2009 13:09:56 +0100, gkholman@xxxxxxxxxxxxxxxxxxxx wrote:
> At 2009-05-13 11:57 +0200, Michael SchC$fer wrote:
>>I've given this subject some thoughts I'd like to share. They centre on two
>> central aspects: a possible requirement for a general approach to
>> standardising
>>XML documentation and simple XML comments vs. structured, namespace-based
>>comments.
>>...
>>  * XSLStyle supports DITA and DocBook. I have practically no experience
>>    with these document types, but from the little I know I'd say that
>>    in the vast majority of cases they go far beyond the requirements for
>>    documenting XSLT, XSD and so on.
>>
>>    When generating documentation from an XSL document, one gets most of
the
>>    information by analysing the code, so in a comment one would add
>> maybe some
>>    descriptive text, change and state information and a hyperlink here and
>>    there, or an image. The same probably applies to XSD.
>>
>>    So I think that allowing the full set of DITA and DocBook features for
>>    use in comments may introduce unnecessary complexity.
>
> Interestingly I saw the choice of DITA and DocBook as introducing
> simplicity because in both cases I use off-the-shelf stylesheets
> (included in the package) that render these vocabularies to HTML.  No
> need to write one's own documentation vocabulary and then stylesheets
> for that vocabulary.
...

I got to this point in Michael's message and, like Ken, was thinking
that using DocBook or DITA made things simpler; not so much because you
can get from them to HTML, but because you can merge the documentation
for your XSLT with other documentation in DocBook or DITA and produce
unified documentation for a whole system.

>>    If one looks at Wiki text formatting like it's supported in Trac, one
>>    can do impressively much with little effort and complexity, including
>>    tables, images and hyperlinks, and the learning curve is flat. If more
>>    was needed, one could mix in XML islands as one does with HTML in Java
>>    comments.

Then I got to this point in Michael's message and light dawned.

There is or could be a role for simplified, non-XML markup for
documenting the common things like the description of the template or
the function or the descriptions of the function's parameters.

Something like a Javadoc or a GTK-Doc for XSLT that also allows XML for
the parts that are too complex to express in the simplified syntax (as
GTK-Doc, for example, does).

I'll talk about GTK-Doc because I know where to find the documentation [1]
and because it produces DocBook on the way to HTML.

With GTK-Doc, structured comments in C code get turned into HTML
documentation.  Here's an example lifted from xmlroff [2]:

------------------------------------------------------------
/**
 * xml_doc_to_fo_and_area_trees:
 * @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.
 **/
------------------------------------------------------------

The '@' and '#' are significant to GTK-Doc, as is the line with no text,
and there's a lot of Perl munging that goes on to turn that into DocBook
and also, for example, produce DocBook markup linking the two '@res' and
linking '#FoDoc' to the FoDoc documentation as well as an <indexterm>
for the function.

The DocBook generated from the structured comments gets merged with some
static DocBook chapters to produce the complete xmlroff manual.

When you need more, you can add real DocBook [4].  This example is from
Xacerbate [3]:

------------------------------------------------------------
/**
 * SECTION:xac-extensions
 * @short_description: Custom extension functions
 *
 * Registers extension functions written in C for use with the libxslt
 * library.  Functions are registered in the #XAC_NAMESPACE_XACF_URI
 * namespace and conventionally use the #XAC_NAMESPACE_XACF_PREFIX
 * prefix.
 *
 * <itemizedlist>
 * <listitem><para>
 * <funcsynopsis><funcprototype><funcdef><type>string</type>
<function>xacf:epoch_time</function></funcdef><void/></funcprototype></funcsy
nopsis>
 * </para>
 * <para>Returns the time since the Epoch (00:00:00 UTC, January 1, 1970),
measured in seconds.</para>
 * </listitem>
...
------------------------------------------------------------

To do something similar for XSLT, you'd probably rely on proximity to
associate documentation with its template or function.  I.e., the
documentation element documents its following sibling element unless the
documentation starts with a keyword (as 'SECTION:', above, is a keyword
for GTK-Doc).

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.

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


[1]
http://library.gnome.org/devel/gtk-doc-manual/stable/documenting_syntax.html.
en
[2] http://xmlroff.org
[3] http://www.xcruciate.co.uk/xacerbate-server-intro
[4]
http://library.gnome.org/devel/gtk-doc-manual/stable/documenting_docbook.html
.en