[Bug 5165] Editorial: numbering of rules and constraints

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