[XSL-LIST Mailing List Archive Home]
[By Thread]
[By Date]
At 2010-05-09 12:15 +0000, Alex Muir wrote:
As David says, that is allowed when done properly.
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.
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:
... 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.
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
Re: [xsl] Are there stupid questions about documentation in xslt?
Subject: Re: [xsl] Are there stupid questions about documentation in xslt? From: "G. Ken Holman" <gkholman@xxxxxxxxxxxxxxxxxxxx> Date: Sun, 09 May 2010 15:02:15 -0400 |
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@xxxxxxxxxxxxxxxxxxxx Male Cancer Awareness Nov'07 http://www.CraneSoftwrights.com/s/bc Legal business disclaimers: http://www.CraneSoftwrights.com/legal
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
Re: [xsl] Are there stupid question, Dimitre Novatchev | Thread | Re: [xsl] Are there stupid question, Alex Muir |
Re: [xsl] Are there stupid question, Dimitre Novatchev | Date | Re: [xsl] Are there stupid question, Alex Muir |
Month |