xsl-list
[Top] [All Lists]

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

2010-05-09 07:16:08
Hi,

I was busy writing some xslt code after hitting the beach and was
wanting a means to add documentation directly into the following xsl
element something like this:

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

-

Q:: Would it be a good or bad idea to have a documentation doc or desc
attribute allowed within the attributes of xsl elements something like
this:?

 <xsl:analyze-string select="text()" regex="{$regex}"> xd:desc="documenting">
or
 <xsl:analyze-string select="text()" regex="{$regex}"> desc="documenting">


Which is an error and possibly unXSLethical in some way?

F [Saxon-PE 9.2.0.6] The prefix "xd" for attribute "xd:desc"
associated with an element type "xsl:analyze-string" is not bound.

-

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>

-

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

-

Googled:  "documenting xslt"

   Found: http://www.devx.com/getHelpOn/10MinuteSolution/20343/0/page/2

Waste of code real estate and time?

"<doc:summary>
    <doc:title>Text To Node Conversion</doc:title>
        <doc:filename>textToNodes.xsl</doc:filename>
        <doc:version>1.0</doc:version>
        <doc:dateCreated>2000-12-01</doc:dateCreated>
        <doc:lastModified>2001-01-02</doc:lastModified>
        <doc:description>
Lot of stuff around me
        </doc:description>
        </doc:summary>
        <!-- more code --> "

SVN should be able to tell you when a comment was made and how it
changed through time. A tool could even print an HTML page to view
history of comment changes. Maybe it already exists..


Let me know your thoughts


kind regards
--
Alex

An informal recording with one mic under a tree leads to some pretty
sweet acoustic sounds between Amadu Diabarte and Jali Bakary Konteh
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>
--~--

<Prev in Thread] Current Thread [Next in Thread>