[XSL-LIST Mailing List Archive Home] [By Thread] [By Date]

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

---

---

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@xxxxxxxxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxxx
> Male Cancer Awareness Nov'07  http://www.CraneSoftwrights.com/s/bc
> Legal business disclaimers:  http://www.CraneSoftwrights.com/legal
>
>



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

---