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
Hi Chris,

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 different layer.

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. 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 ======================================================================

Current Thread