RE: General comments/feelings about XPath/XSLT 2.0

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

I would prefer to avoid splitting XSLT into multiple documents: I think
people generally find a single document less unwieldy than a collection of
documents that cross-refer to each other. I don't think we need to write
tutorial material in the XSLT 2.0 specification, because it exists
elsewhere. We do need to define the concepts and terminology, and in the
case of new features, I think we owe the reader a brief explanation of what
purpose the features are intended to serve.

In the current draft, I have pulled together a lot of the explanatory
material that was previously scattered around the document into the first
couple of sections, and I have tried to balance it so that a similar style
of explanation is used for all the main concepts: previously some concepts
like keys and patterns received lengthy justification in the spec, while
other concepts were dealt with very tersely. But other people have also made
negative comments on these sections and more work is clearly needed.

Michael Kay

Received on Monday, 23 September 2002 12:38:26 UTC