Thanks much,, I'll try out the XSLStyle and start to document within
elements using a different namespace.
When I was trying to use the xd: prefix I forgot that the namespace
had only been declared not at the top level in my document but within
a xd:doc element thus not being global.
Regards
Alex
On Sun, May 9, 2010 at 7:02 PM, G. Ken Holman
<gkholman(_at_)cranesoftwrights(_dot_)com> wrote:
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>
--~--
--
Alex
An informal recording with one mic under a tree leads to some pretty
sweet acoustic sounds.
https://sites.google.com/site/greigconteh/albums/diabarte-and-sons
--~------------------------------------------------------------------
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>
--~--