xsl-list
[Top] [All Lists]

Re: [xsl] Are there stupid questions about documentation in xslt?

2010-05-09 14:06:21
At 2010-05-09 12:15 +0000, Alex Muir wrote:
 <xsl:analyze-string select="." regex="{$regex}" doc="documenting this
as an attribute because there is a really important reason why I'm
doing this which I will never remember which is directly related to
the analyze string function">

Clearly one cannot do this, well that I'm aware of but thought it
might make for an interesting discussion if one can't.

As David says, that is allowed when done properly.

I do document with xd:doc.. which is useful but not as localized as I
would like and really kind of heavy on the screen real estate
-- except for in the cases of documenting what a template or style
sheet does in general.
<xd:doc id="template" xmlns:xd="http://www.oxygenxml.com/ns/doc/xsl";
scope="component">
    <xd:desc>
      <xd:p>xsl:template match="conten".</xd:p>
    </xd:desc>
  </xd:doc>

In 2004 I published something similar:

  http://www.CraneSoftwrights.com/resources/#xslstyle

XSLStyle is also used for documenting all top-level constructs in an XSLT stylesheet. But the vocabulary is only scaffolding for the author's choice of the actual documentation constructs, in either DocBook, DITA or XHTML. This allows the stylesheet to be rendered in a browser using off-the-shelf stylesheets.

XSLStyle doesn't attempt to document what is inside each top-level construct.

It produces an alphabetized index of all named top-level constructs, indicating which fragment in the import/include tree it is found.

The latest version includes a number of CSS stylesheets, one of which includes the use of the oXygen icons for top-level constructs.

<!-- -->
             should only be used to comment out code
             that one does not want in a document.

Really? I don't agree, but I suppose someone may wish to follow that convention. I personally use a lot of comments in my code. There is a technique of using bogus extension elements and <xsl:fallback> to comment out a block of XSLT code that contains XML comments.

If you really don't want to use comments, then you could just as well choose to use a processing instruction:

  <?xslstyle documenting this as an attribute because there is a
             really important reason why I'm doing this which I
             will never remember which is directly related to the
             analyze string function?>

... and still be able to use comments to block out code.

But I personally don't do this because I can't perceive a way of presenting in a formatted result what the context is of an embedded comment. So I present the documentation for only the top-level constructs.

However, as processing instructions are ignored, they won't interfere with your stylesheet and they won't end up in your result, so you could use them.

Let me know your thoughts

You have a number of choices. Since I release the source code for XSLStyle, you can adapt it to recognize the embedded processing instructions and present them however you wish.

I hope this helps.

. . . . . . . . . . . . . Ken

--
XSLT/XQuery training:   after http://XMLPrague.cz 2011-03-28/04-01
Vote for your XML training:   http://www.CraneSoftwrights.com/s/i/
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/s/
G. Ken Holman                 mailto:gkholman(_at_)CraneSoftwrights(_dot_)com
Male Cancer Awareness Nov'07  http://www.CraneSoftwrights.com/s/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal


--~------------------------------------------------------------------
XSL-List info and archive:  http://www.mulberrytech.com/xsl/xsl-list
To unsubscribe, go to: http://lists.mulberrytech.com/xsl-list/
or e-mail: <mailto:xsl-list-unsubscribe(_at_)lists(_dot_)mulberrytech(_dot_)com>
--~--