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

AW: AW: AW: AW: AW: [xsl] commenting and documenting XSLT (small survey)

---

---

hi,

> Von: Wendell Piez [mailto:wapiez@xxxxxxxxxxxxxxxx]
> But: the thread is heading off topic.

it is going a bit offtopic, yeah.

just to sum up a bit, my original question actually was:  Use javadoc style
text (html and @tags) or wikiML syntax (ReST) text in XSLT comments? (I guess
I did not made myself too clear about that).

I did not expect (should have though) that of course people of this list
(notably David, thanks for that) pointing out that not anyone of the above is
a prefered solution to the overall question "how to document XSL", which
indeed would be to use XML directly whether with XHTML elements not used for
output but for documentation only or any other custom or standard XML dialect.
(Maybe my current choice of ReST gets a bit clearer in my following
comments).

But the whole discussion did help clearing up (and also messing up a bit ;) my
thinking about some issues about markup in general and I do include some
thoughts about Wendell's last post.
Maybe it's better to close these topics here to let the list focus on its real
topics. but if anyone is interested, read on. Or of course if anyone has
opinions about the original question, please do send them.

thanks
chris



> I submit that another issue, related to learnability, is
> tools support. An
> XML tag set layered into your stylesheet can (as someone else
> remarked)
> take advantage of XML-editing support, which is widely and generally
> available, in various forms, to XSL authors. Tools support
> for a custom
> language (even if open source) is going to have to be in an entirely
> different layer.
>

valid point. although a wikiML style language I guess is more or less meant to
be writable without tools support. Even XML seems to be written with a simple
text editor quite often which IMHO is not ideal but people seem to like it.

> >that is not the scope of my app as i only use the docutils
> format and
> >their developers have sorted out the main things already. I
> am just a user
> >of the format and so have to hope that the docutils project
> does what they
> >say it should (which i think they do btw).
>
> Ah, so you're content to ride in the back seat. This could be
> fine for you
> -- it can be an excellent way to get places without too much
> trouble --
> although it does mean you don't get to drive or to decide
> where to go or
> when to take rest stops or detours.
>

Markup is too complicated to be developed anew for each project (I could not
do that anyway), so using a format (be it ReST, XML or whatever) definitely is
the best thing one can do I think.

In the case of an xsldoc the format of the XSL comments and even the comments
themselves are not the only focus, as the actual comments of XSL are certainly
important for an xsldoc but not all there is to get a useful XSLT
documentation. That at least needs the overall structure, template/params/etc
names, default values, an index etc. which the xsldoc app does anyway and I
hope is useful even without any additional comments.


> >XML is just not very suitable for the area I need an ML
> language for. a
> >wiki style ML is much better for that as it is much more
> readable and
> >writable and IMHO is learnable with neglectable effort.
>
> It's funny that you asked us what we think, but seem to have
> prejudged this
> issue. What makes XML unsuitable for stylesheet writers to
> use to document
> their stylesheets? For better or worse, stylesheet authors
> are already used
> to wading through tags -- and these days any of us who are
> still writing
> tags by hand, are mainly doing so out of choice. If you were
> talking about
> a markup language for complete neophytes who would never need
> or want to
> learn how XML tagging works (a kind of XHTML-authoring-light
> for web forms
> or whatever), I could see the argument here. Maybe there's
> something you
> haven't told us about why your users are different from the
> large number of
> XSL authors who read this list -- none of whom, so far, have
> spoken up in
> favor of a non-XML syntax.
>

Being a "tagging" expert or not is not the point I think. Simplicity/Usability
is IMHO *always* very important. I think that wikiML *is* simpler to read and
write compared to XML (maybe not for complex documents like books but for
short ones like emails and in this case text in XSLT comments). It does not
really matter if one is used to use XML tagging a lot as simpler still is
simpler (sorry, sounds like a dumb statement) and therefor more usable for
anyone.

Maybe to illustrate my point, compare the writing of Java code to Python code
(I do not want to start a whole new discussion for which I do not know enough
about both, but just to illustrate what I mean with "simple". And of course I
totally ignore other issues like if there is Python support in a certain
environment, compile time validation etc. I concentrate solely on the writing
of the code itself.):

Writing Python code is simpler just as it is much more readable, writable and
maintainable as e.g. it is shorter, without the "noise" of casts, variable
declaration etc. Even an experienced Java programmer would have to acknowledge
this I guess. There of course is a learning curve namely to learn another
language but after a while the time and effort saved would compensate for
that.


I see the use of comments in XSLT to help a programmer to understand his or a
coworkers code and to build an official documentation. And a simple and easy
way to read, write and maintain these comments seems preferable to one which
has a certain "noise" (XML elements). Be it that this would then be done on a
more regular basis (and therefore sometimes at all as I guess it is not common
in most projects  as documentation mostly comes last) or to be able to just
read it easier.

A simpler solution is therefore always preferable, also for an experienced XML
writer. (I do use XML a lot but prefer to use at least a simple XMLIDE to a
text editor with no XML support even for basic XML files. To write comments in
e.g. XHTML is no problem but to use a wikiML is even easier).

So maybe the simplest might be plain text but I do believe structure is
necessary so plain text is not enough and too simple...
A wikiML like format like ReST has the best of both: Simple to appear almost
as "markupless" but at the same time capable to express structure in a
thoughtful way.


> But -- finally, and FWIW -- were I designing a syntax such as
> you describe,
> I'd make the first processing phase into a transparent XML
> representation
> of that syntax, suitable for downstream conversion into
> anything at all,
> not just XHTML. Not that they asked ... and that *is* off-topic. :->
>
> Cheers,
> Wendell

In my app I currently do process all XSLT stylesheets to a simple format and
do a 2nd step converting this to XHTML (So it theroretically is capable of
transformation in other formats than XHTML).
I do process all comments to XHTML in the first step though although ReST does
support -what you propose- a conversion of its text format to a custom XML
format.

I may use this in the future but I started the project mainly as a way to
learn Python (and to practice my XSLT knowledge) and kind of plugged in ReST
at a later stage...


thanks
chris

---