[XSL-LIST Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] Re: Are there stupid questions about documentation in
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"> 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
|
PURCHASE STYLUS STUDIO ONLINE TODAY!Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced! Download The World's Best XML IDE!Accelerate XML development with our award-winning XML IDE - Download a free trial today! Subscribe in XML format
|