Re: AW: AW: AW: AW: [xsl] commenting and documenting XSLT (small survey)
Subject: Re: AW: AW: AW: AW: [xsl] commenting and documenting XSLT (small survey)|
From: Wendell Piez <wapiez@xxxxxxxxxxxxxxxx>
Date: Fri, 09 Jul 2004 12:07:01 -0400
At 05:43 AM 7/9/2004, you wrote:
first, thanks for your input.
You are very welcome. (But: the thread is heading off topic. It's only on
topic -- arguably --- because you're talking about using your format to
document XSL. In that context it's on topic in that you presumably want to
gauge the sentiment among us XSL users: but the technical issues themselves
aren't directly XSL-related are they?)
> What happens when it contains glitches?
The problems you describe is exactly the reason why i did not develop
another format myself.
ReST is a format which I only chose. It seems to be one of the better wiki
like ML languages. It is currently in development but seems to be quite
usable already. From what I know about it it has some really good
developers which have much more experience doing such a thing that i ever
might have. (For more details see the docutils website.)
I will. It's encouraging that people are working on this kind of thing: I
hope it does well.
Learnable? Well, it certainly is another language to learn and that's also
a complaint I got from an xsldoc user. On the other hand it is quite a
simple format (if you stick to the basics which are probably only used for
the text in XML comments anyway) but *can* do complex things if you need them.
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
the process that generates XHTML out of the txt format does give quite
good error messages, so it does validate its format. But you are right,
that this still is an area which I have not really looked into.
Also consider whether you might ever want semantics beyond XHTML's. It's a
piece of cake to extend an XML tag set to include tags like
<parameter-type>, to give templates unique identifiers, or do almost
anything else you might dream up. People have already done useful things
with stylesheets to document stylesheets, which can take advantage of both
XML tagging and the native XSL itself. (Indeed, the promise of this feature
was an important one of several rationales for using XML syntax for XSL at
all, itself a decision that has not gone unquestioned.) Even without a
full-blown system it's sometimes very useful to write XSLT heuristics to
run over stylesheets (tell me all the modes with their matches, and that
kind of thing). Using XML as your documentation format allows you to
integrate your processes seamlessly with that kind of thing.
Heck, I bet you could just drop raw XHTML in there and get less grief from
your users, along with a simpler implementation.
> and how is it specified? If not, who owns, controls, and
> maintains the
> ur-process that controls everything?
> Also, I question how easy it is to process into XHTML
> afterwards. It may be
> easy to do the first 80% but I submit that the last 20% --
> and all the
> subsequent desiderata like "how do I make a list item with
> more than one
> line in it?" -- will probably drive you crazy.
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.
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.
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. :->
Wendell Piez mailto:wapiez@xxxxxxxxxxxxxxxx
Mulberry Technologies, Inc. http://www.mulberrytech.com
17 West Jefferson Street Direct Phone: 301/315-9635
Suite 207 Phone: 301/315-9631
Rockville, MD 20850 Fax: 301/315-8285
Mulberry Technologies: A Consultancy Specializing in SGML and XML