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>
--~--