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

Re: [xsl] XSL - Documentation

---

---

Hi,

While a documentation namespace could easily support both attribute and element documentation, and their processing, the documentation nodes are still part of the document. How about using processing instructions for stylesheet documentation?

Thanks,
ac

On Wed, May 13 2009 15:28:05 +0100, davep@xxxxxxxxxxxxx wrote:
...

I can see where you're going Tony, but aren't you just re-inventing
Tangle and weave? With the added complexity of your perl munging?

More of an alternative than a re-invention, I think.  To go back to the
post that started this thread:

On Fri, May 01 2009 11:23:07 +0100, stf@xxxxxxxx wrote:
| I was looking for the most common way to document XSL-Stylesheets and
| found a lot of small solutions in the web, which belongs to one of these
| groups:
|
| 1) use of comments, similar to JavaDoc
| 2) use of an extension namespace
| 3) literate programming

If you're using an XML editor, why not stick to XML for the
documentation. Seems simpler - and as Ken says, use as much (or
as little) docbook|Dita as you need.

But you may not know any DocBook or DITA.  If you spend your working
hours writing firstly Java code and secondly XSLT stylesheets to work on
OpenTravel XML, what exposure do you have to either DocBook or DITA and
what exposure do you have to structured comments?

And as Michael SchC$fer says:

On Wed, May 13 2009 10:57:13 +0100, michael.schaefer@xxxxxxxxxxx wrote:
]  * Namespace-based comments clearly have their benefits, but some
]    disadvantages as well. In a text editor, they do not set off from
]    the XML "payload" as well as do simple comments and so blur to some
]    extend the distinction between comments and the rest. In other words,
]    they make the document less readable.

The key is surely the pre-pass to pull documentation out and
then merge it (as you've done) with a shell to produce the finished
documentation? I guess that's why I'm frowning at the comment lines :-)

I haven't done it for XSLT, nor did I write the GTK-Doc tools, though
some of my XSLT comments do come out looking a lot like GTK-Doc or
JavaDoc comments.

I started the day in the just-use-DocBook camp, then something dawned,
so I'm now favouring the idea of a simplified syntax into which you can
mix proper XML, and I seem to have stumbled into the position of
championing it though I'll freely admit it wasn't even my idea.

Regards,

Tony Graham                         Tony.Graham@xxxxxxxxxxxxxxxxxxxxxx
Director                                  W3C XSL FO SG Invited Expert
Menteith Consulting Ltd
XML, XSL and XSLT consulting, programming and training
Registered Office: 13 Kelly's Bay Beach, Skerries, Co. Dublin, Ireland
Registered in Ireland - No. 428599   http://www.menteithconsulting.com
  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --
xmlroff XSL Formatter                               http://xmlroff.org
xslide Emacs mode                  http://www.menteith.com/wiki/xslide
Unicode: A Primer                               urn:isbn:0-7645-4625-2

---