Self documentation, my crude stab in that direction

[Apologies for coming to this discussion a bit late. My two cents
follows.]

One of the most significant failings (IMHO) of my DocBook DSSSL
Stylesheets is that they are poorly documented. One of my goals for my
XSL DocBook Stylesheets is that they be less poorly documented. To
that end, I want to combine documentation with the stylesheets in a
way roughly analagous to the JavaDoc system that seems to work fairly
well.

My crude stab in that direction is the following. For each
template/variable/etc., I have an element in the doc: namespace that
contains documentation for it. My goal (as yet only partially
achieved) is to write stylesheets that build (reference/API)
documentation from this system. (This system isn't meant to address
tutorial and end-user documentation.)

Here's a quick example, FWIW, you can see others in the stylesheets
themselves (nwalsh.com/docbook/xsl), particularly in the param.xsl
modules.

  <doc:template name="calc.column.width" xmlns="">
  <refpurpose>Calculate an XSL FO table column width specification from a
  CALS table column width specification.</refpurpose>

  <refdescription>
  <para>CALS expresses table column widths in the following basic
  forms:</para>
  <!-- ... -->
  </refdescription>

  <refparameter>
  <variablelist>
  <varlistentry><term>colwidth</term>
  <listitem>
  <para>The CALS column width specification.</para>
  </listitem>
  </varlistentry>
  </variablelist>
  </refparameter>

  <refreturn>
  <para>The XSL column width specification.</para>
  </refreturn>
  </doc:template>

This element documents the xsl:template named "calc.column.width".
(The content of the doc: elements is described in the jrefentry
DTD, http://nwalsh.com/docbook/jrefentry/.)

                                        Be seeing you,
                                          norm

-- 
Norman.Walsh@xxxxxxxxxxxx | Anything more than the truth would be too
XML Technology Center     | much.--Robert Frost
Sun Microsystems, Inc.    | 


 XSL-List info and archive:  http://www.mulberrytech.com/xsl/xsl-list