[jdom-interest] META: Children of a lesser spec

[Peter V. Gadjokov]

>Now, if it was only correct. But it isn't, and a cursory reading of _any_
>XML specification makes it confusing, especially getChildren()...
  - Brett McLaughlin, during a JDOM API design discussion, emphasis mine

When we speak of spec conformance in the context of API design discussions,
what spec are we talking about? What spec, if any, _should_ we be talking
about? If we could settle this philosophical issue, some of the ongoing API
discussions could become somewhat clearer. 

So, to get this going, the classes of specification and my view of their
applicability: 

*] Core 'syntax-oriented' specs, e.g., The XML spec, the Namespace spec.

These specifications both define core features and their syntactical
representation in a well-formed, serialized XML document. Since a useful API
would do well to stay as syntax-independent as possible, I'd argue these
should not drive API-level decisions. Obviously, since they contain
information that goes beyond syntax, they should be consulted and taken into
serious consideration - the hard requirements of conformance, though, are
constrained to Builders and Outputers, not the core API. 

*] Other API specs, most notably DOM

Since one of the driving motivations behind JDOM is to be better (and not as
cumbersomeas ) than DOM, DOM should not be a significant driver of API
decisions. It should certainly serve as a source of ideas (both good and
bad) but familiarity with DOM and DOM-inspired expectations should be
secondary constraints during API design - the primary ones being usefulness,
clarity and elegance. 

*] Core 'syntax-independent' specs, e.g., the XML Infoset (any others?) 

These, I think, are a lot more relevant to in API discussions than the
previous ones. They describe XML documents and their components in terms of
logical structure as opposed to syntax (or serialization format). Such specs
should carry more weight in discussion than any other factor with the
exception of the ones directly related to creating a sensible, OO, Java API
- i.e. only the needs of API usefulness, clarity and elegance should
override the requirements of conceptual specs (e.g. JDOM could chose to hide
some of the conceptual complexity as mentioned in the JDOM philosophy FAQ).
In the appropriate places, the API design and usage documentation should
refer to concepts of such specs, describing how JDOM maps to and differs
from the concepts outlined in those specs. In a word, this is the task of
making the M in JDOM meaningful.

*] The JDOM spec

This mythical entity would be the result of the work described at the end of
the last item (and the ranting on mailing lists and the writing and using of
code, of course). We do want JDOM to grow up to become a standard, after all
- at the very least, it's worth agreeing to have or not to have one for 1.0.


Comments welcome. 

-pvg