Re: General comments/feelings about XPath/XSLT 2.0

> > What can the WGs do to stop us from walking away? I don't
> > know, but shorter and better-organized specs would be a
> > start. They should consider separating the implementation
> > details from what a user needs to know.
> >
> > I mean as an implementer, I can appreciate things like
> > spelling out what conditions create what type of errors, and
> > very detailed, accurate, verbose explanations with very
> > specific terminology to describe the minutia.
> >
> > But take, for example, the section on format-number(). As a
> > user just trying to remember the format of the arguments so I
> > can format a number in my stylesheet, I pore over the 3000
> > words(!) in that section only to come away
> > *still* scratching my head as to how the heck to use the
> > stupid function.
> 
> W3C specifications have never aimed at being a tutorial for users. The XSLT
> 1.0 specification of format-number() was a disaster: it didn't have enough
> detail for either implementors or users to predict the effects of a given
> call, without trying it out against a JDK 1.1 implementation to see what
> happened. The new specification is not ideal - it describes an algorithm,
> which is something we usually try hard to avoid - but at least it tells you
> what the function does for any given input.
> >
> > Another example, just a minor nit: explaining push vs pull
> > processing. That's all good for people to know, but it's a
> > design pattern, not something that needs to be wasting space
> > in the spec. "Why did I just read that" or "why is
> > that being explained here, in between that and this" should
> > not be questions I am tempted to ask.
> 
> We've had some difficulty getting the right level of introductory material,
> and organizing it to make it accessible. I certainly wouldn't claim that
> we've got it right yet. But there are two pressures: to explain things more
> clearly, and to stick to the normative facts. It's not easy to find the
> right balance.
> >
> > Scroll down a little bit and the sheer volume of terminology
> > being introduced is overwhelming. How is someone supposed to
> > read this and "get" it? XPath 1.0 wasn't arranged all that
> > well, but at least it was concise and requires little more
> > beyond the spec itself than a few more examples and diagrams
> > before someone can understand it -- "Here's your data types,
> > here's your tree model, here's your syntax and semantics,
> > here's your function library."
> 
> Well, there were things in XPath 1.0 that people had immense difficulty
> with, for example the notion of axis direction and "proximity order". I
> actually think the main XPath 2.0 language book is a vast improvement, both
> in terms of specifying the language accurately and precisely, and in terms
> of readability. I do agree that we have a problem of duplication and
> consistency across multiple specifications - this is largely a consequence
> of our internal processes, where we have tried to subdivide the task among
> different subgroups and editorial teams. I think we should perhaps review
> whether some reorganisation of the documents is possible now that the
> technical content has become reasonably stable. Any concrete suggestions
> along these lines would be welcome.
> >
> > These new specs are going to require *volumes* of
> > supplementary material written in the Common Tongue to get
> > even experienced XPath/XSLT 1.0 users up to speed with it. On
> > the other hand, I suppose it gives writers of articles and
> > books on these subjects something to do. SGML, anyone?
> >
> You seem to be expressing two separate concerns
> 
> (a) that the language is too big, and
> (b) that the document set is unwieldy

I haven't reviewed the document, so am only commenting on the post, but
why are you constrained to a single document?  You say it difficult to
maintain a balance between introductory material and normative facts;
I'd say it's impossible.  An (useful) introductory text tends to stick
to the fundamentals and core, most often/likely used features.  A good
reference has to describe all features/aspects.  Mixing them (as rule)
tends to mean we lose the signal for the noise on both sides of the
fence: the person who wishes the introduction is overwhelmed by the mass
of material, the person attempting to research a specific point/feature
is frustrated at all the excess material they have to go through.

Any reason why you're constrained to a single document (outside the
minor issues of additional work load, overhead of generating a second
document, and trying to set a new precedent)?  

Regards,
Ed Knoll

-- 
Edward L. Knoll   Phone (work)     : (719)484-2717
                  e-mail (work)    : ed.knoll@cosd.fedex.com
                  e-mail (business): eknoll@sf-inc.com
                  e-mail (personal): edward@elknoll.com

Received on Tuesday, 24 September 2002 03:24:29 UTC