- From: <bugzilla@wiggum.w3.org>
- Date: Fri, 04 Jan 2008 10:15:31 +0000
- To: www-xml-schema-comments@w3.org
- CC:
http://www.w3.org/Bugs/Public/show_bug.cgi?id=5165 ------- Comment #2 from mike@saxonica.com 2008-01-04 10:15 ------- >Just to make sure I follow correctly: the proposal is that, effectively, wherever the document now has a validation rule, constraint on schema, etc., we should wrap it in a subsection? Yes, in essence. Though I haven't tried to work out what difficulties it might cause. The problem with the conventional subsection structure of 2.1, 2.1.1, 2.1.2 etc is that the only place for text that belongs at the 2.1 level, because it doesn't relate to a particular subsection, is before all the subsections. There are two ways that one can get around this: one is to make the subsidiary components "boxed components" (like figures, tables, equations, boxed notes) that allow a return to the parent level of hierarchic structure when they finish. The other way is by using out-of-line constructs (footnotes, endnotes, appendices) Both of these might be viable here: in reading the document, one so often arrives at a rule or constraint definition via a remote cross-reference that it wouldn't do much harm to have all the rules and constraints appear together in a chapter of their own. This isn't that dissimilar from the ISO convention of putting all the definitions together in one chapter. In effect we are currently using "boxed components", but without a clear typographical indication of where the box ends, and without any mechanism for identifying the component other that a (usually rather long-winded) name, which gives you no clue whereabouts in the document the component is to be found. The lack of structure can actually cause confusion. Looking at 3.4.6 which you cite, the introductory prose refers to "the following constraints". Which constraints is it referring to? All those in section 3.4.6? Or only those up to the next prose introduction, which occurs before Type Derivation OK (Complex)? One advantage (and cost) of moving the constraints out-of-line would be that it would force a clearer definition of the parameters of each constraint. At the moment there are a number of styles. Look again at 3.4.6: Complex Type Definition Properties Correct starts by talking of "the properties of a complex type definition" (which one?). Derivation Valid (Extension) starts by talking about "the {derivation method}" (of what?) Type Derivation OK (Complex) uses the style "For a complex type definition (call it D, for derived) to be validly derived" Behind these stylistic differences there is actually something more fundamental: some of the constraints are merely definitions of properties that a component may or may not have (These are often introduced with the phrase "The following constraints define relations appealed to elsewhere in this specification."), while some of them describe rules that components must satisfy in order to be valid. Having rambled around this, I think I would try to go for the "subsection" style as you suggest. Try to make the subsections free-standing, so their meaning doesn't depend on context: constraints should be in the form "Every complex type definition T must satisfy all of the following", or "Definition: a complex type P is a _valid restriction_ of a complex type Q if all the following conditions are true"
Received on Friday, 4 January 2008 10:15:39 UTC