hi,
Von: Wendell Piez [mailto:wapiez(_at_)mulberrytech(_dot_)com]
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