[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] RE: "Clean Specs"
Paul raises some important points here. The question is as to what is the best way to write specs, best being efficient and clear. The namespace spec is often used as an example of an unclear spec. I do not agree with this. When I read the namespace spec it is very clear. My misunderstandings of the spec have come almost entirely from *every thing everyone else has been saying* about namespaces rather than the spec itself. Being somewhat of a neophyte, I assumed that there existed concepts within about namespaces that I missed from the very simple spec. The simplicity of the namespace spec was driven home by the examples James Clark has given. To me this is an excellent example of why a spec should be written in 3 parts: a formal specification (BNF or whatever), a plain english description, lots of good examples. Here is my plain english distillation of namespaces: Namespaces are a way to distinguish element and attribute names using URI's so that element and attribute names can be reused without causing problems for software. << formal description here >> For example ... Paul is correct that formalisms obfuscate specs for neophytes. The problem is that english is ambiguous. For those of us who can't read formalisms nor english a good set of examples are needed. The best RFCs contain these three parts. Jonathan Borden http://jabr.ne.mediaone.net > > > What is a "clean spec?" > > People in this discussion are mixing together a variety of things that I > do not consider the same. > > Uche Ogbuji wrote: > > I have worked on teams implementing DOM, XSL and parts of XLL. > Some users > > might grant that we have been "succeeding", but let me assure > you that if so, > > it is despite the W3C specs, not because of them. DOM, especially is > > unforgivably inconsistent, incomplete, and unclear for a > production-ready > > (1.0) specification. > > There is not a SINGLE person on this mailing list that would say that it > is right to create specifcations that are inconsistent, incomplete or > unclear. It is beyond doubt that specifications in the XML family, > including XML itself, have these problems. The question is how to avoid > that? > > * some people say that what the spec needs is "more English". But much of > the problem with the namespaces specification comes from ambiguity in the > English. > > * some people say that we need "more non-normative text" but once again, > it is a non-normative appendix that is confusing people. > > What almost nobody has suggested is that we need more formal notation. Now > if we look at James Clark's "clarifying" document what we see is *less* > English text and *more* notation. > > As David Megginson has pointed out, when a spec. invents a notation to > explain its abstract concepts the spec. becomes temporarily harder to read > because you have to learn the notation before the specification. This will > turn people off. I remember that Algebraic notation turned me off in my > first year math classes. But in the *long run* it makes life easier for > everyone. Implementors have precise definitions of what the hell they are > supposed to implement. End-users get software they can use. People reading > the specification for their own education and edification will understand > it better -- if they perservere through the task of learning the notation. > > I know that W3C spec. writers are under pressure to use more normative > English and less normative notation. This is not a vote for "clean" > specifications. It is a vote for messy, hard-to-implement ones. Where is > Dan Connolly when you need him? > xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev@i... Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1 To (un)subscribe, mailto:majordomo@i... the following message; (un)subscribe xml-dev To subscribe to the digests, mailto:majordomo@i... the following message; subscribe xml-dev-digest List coordinator, Henry Rzepa (mailto:rzepa@i...)
|
PURCHASE STYLUS STUDIO ONLINE TODAY!Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced! Download The World's Best XML IDE!Accelerate XML development with our award-winning XML IDE - Download a free trial today! Subscribe in XML format
|