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

Re: [xsl] XSL - Documentation

---

---

Ken,

Interestingly I saw the choice of DITA and DocBook as introducing simplicity because in both cases I use off-the-shelf stylesheets (included in the package) that render these vocabularies to HTML. No need to write one's own documentation vocabulary and then stylesheets for that vocabulary.

My point here was that writing/editing a comment may get more complicated, because the vocabulary was complicated. Of course, in terms of processing
it is much simpler to resort to something that's already there and just
re-use it.

Another argument for simplicity in writing and reading may be that comments
are not always intended to be processed or to appear in some document apart
from the code, but just for being read in place.

And I have a number of customers' stylesheets documented with lists, graphics, tables, program listings and other constructs that are all sitting there ready to use in the off-the-shelf vocabularies.

Given the case, the requirements are there and one can use DocBook etc. to
its full potential. The question is, how often is that the case? In my
experience - which surely doesn't compare to yours - not so often.

So I just asked myself if there was a need for a simple solution. This and
my experience as a Java developer lead me to thinking that using XML comments
with Java-style tags and the option to mix in XML markup was not such a bad
idea. GTK-doc seems to be quite close to what I had in mind (Thanks to Tony
Graham for mentioning it ;)).

The problem presents itself differently if you look beyond XSL and at
documenting XML in general. XSL processors are prepared to deal with non-XSL
elements and do safely ignore them if they appear at the top level. Using
element-based comments may cause validation problems with other XML documents
types. If you have no way of altering the schema or controlling the validation
process in order to avoid this, you are stuck with XML comments anyway. XML
comments are part of the XML syntax and therefore work everywhere you use
a decent XML processor. That's why I think they are good for modest and common
documentation purposes.

BTW: ac remarked that XML comments should be ruled out because they couldn't
be nested. If there was a standard XML documentation namespace it might just
provide an element for commenting things out that would not conflict with
inner XML comments, and one could use both in combination. In XSL one can
already achieve this at the top level by wrapping such a section in any
non-XSL element.

But you may find value in learning the basics of these two vocabularies, but you can do a lot knowing only that DocBook <para> and DITA <p> allow you to document every aspect of the stylesheet with paragraphs of prose.

I will sure look at least at DocBook. If there is away to add some semantics
to <para> (like a class attribute), I will probably be totally happy with it.

Anyway, thanks to you and the rest for your comments, I've learnt a lot, and
of course I'm pleased that some of you found that my idea was not so bad
at all.

Michael

---