Subject: Self documentation, my crude stab in that direction From: Norman Walsh <ndw@xxxxxxxxxx> Date: 07 Jul 2000 13:04:39 -0400 |
[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
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
Self documentation, tangle and weav, Pawson, David | Thread | asp assistance please, Pawson, David |
Re: XSL transforming XML to HTML, David_Marston | Date | Re: Accessing a node name from with, Paul Tchistopolskii |
Month |