This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.
3.2.2 XML Rep of Attribute Declaration Schema Components is the first context in which the tableau format is really being pushed as far as it can go while still being at all comprehensible, and it's not the worst. I am suggesting as small a set of changes as I can that I think will really improve readability. - move the paragraph (or even just its first sentence) that enumerates the cases covered in the tableau from after it to before it ("Attribute declarations can appear at the top level of a schema document, or within complex type definitions") - replicate the logic embedded between the tableau's divisions ("otherwise if the <attribute> element information item has <complexType> or <attributeGroup> as an ancestor...") as text before the tableau so the reader gets an overview before diving into the bits - add a sample in 1.5 where the tableau format is introduced showing this type of "code interspersed with nested tables" - add a reference to "attribute use" (or any other distantly defined entity when it is first used if it has not yet been introduced in the beginning to end flow), e.g. in "otherwise if the <attribute> element information item has <complexType> or <attributeGroup> as an ancestor..." If larger scale changes are possible, I would reorganize it further so that in place of each single tableau (one dealing with all cases) is a series of them (one per case). The beginning of the section would aggregate just the current logic, what you currently have as separators between sections, and point to a specific heading with the tableau for each leaf case, containing the (restricted to this case) XML and all the downstream properties. The property descriptions would come between the logic/list of cases and the first leaf case's details.
Another change which I would find very helpful when discussing the specification is for the tableaux to be individually numbered (like figures or equations).
This bug is from the SML workgroup as a whole, decided at 2007-10-25 telecon.
I'm marking this editorial, since it's not a substantive issue. But the WG may need to discuss it. See the email message at http://lists.w3.org/Archives/Member/w3c-xml-schema-ig/2008Jan/0000.html (member-only link) for some discussion of possible principles for revising the presentation of the XML mapping rules (among other things).
Taking into accout Mike's comments in Bug #5152, a variation on John's last proposal would be to include alternative schema components in separate sections. For example, a document structure could be: 3.2.2 XML Representation of Attribute Declaration Schema Components XML Representation Summary table 3.2.2.1 Global Attribute Schema Component Para: If the <attribute> element information item has <schema> ... then table 3.2.2.2 Local Attribute Schema Component Para: If the <attribute> element information item has <complexType> as... (I've removed the initial 'Otherwise'.) then table 3.2.2.3 Referenced Attribute Schema Component Para: If the <attribute> ... has <complexType> ... and the ref then table Note that I've intentionally used the section heading to give a little clue as to what the particular sub-section is about. BTW I think the structure here is easiest to understand if it has the form: if(...) { } if(...) { } if(...) { } i.e. each condition is stand-alone, rather than: if(...) { } else if(...) { } else { }
proposal in comment 4 sounds fine. I am assuming that the summary table would include a brief text-based description of the reason for each subsection, leaving the syntax requirements (i.e. the if condition) to the sub-section so the syntax is not duplicated. Duplicating the syntax would be fine for a reader, but likely make the spec harder to keep self-consistent (self-INconsistencies have their own price for readers as well).
A wording proposal showing changes intended to resolve this issue has been sent to the XML Schema WG; it can be seen at http://www.w3.org/XML/Group/2004/06/xmlschema-1/structures.b5152.html http://www.w3.org/XML/Group/2004/06/xmlschema-1/structures.b5152.movement-colored.html (member-only links) I'm marking this issue as needsReview accordingly. The details of the change proposal are described in some detail in the Status of This Document section. As noted there, the changes involve some movement of text to different locations; the first form of the proposal performs these movements silently, so that the only text coloring shown in the diff is changes to the words used in a particular paragraph or rule. The second shows the text movement as 'non-status-quo' text; text moved from one place to another is shown in its old location as a non-status-quo deletion and in its new location as a non-status-quo insertion. The brighter colors are used for the other changes (and should be the same in both forms of the proposal).
I like the draft - a LOT. This looks like a huge improvement, my compliments to the chefs. It seems like a bit of an odd choice to interleave attribute uses and attribute wildcard material in 3.4.2.4. Seems like it would be clearer to split it into 2 sections. 3.4.2.4, XML Mapping, attrib wildcard: link "Mapping from <any> to a Wildcard Component (ยง3.10.2.2)" has something apparently wrong w/ it. <a> only covers "mapping from". FYI, there is a formatting issue with several of the boxes, e.g. 3.16.2.2 where the property name overlaps the border.
Thank you for the comments. The common thread that unites the {attribute uses} and {attribute wildcard} properties is that they both entail looking at any <xs:attributeGroup> elements present in the relevant location(s). If we can't find a way to make that clearer, perhaps you're right that it would be best to split the section, referring from the second to the first for the XML syntax of <attributeGroup>, just as we now refer elsewhere for <attribute>. The hyperlink "Mapping from <any> to a Wildcard Component" is, I think, an illustration of the peril of placing an HTML 'a' element within an 'a' element. The reference to <any> is a hyperlink, and since HTML browsers are not really at ease with nested hyperlinks this fact seems to cause them to force the "Mapping from ... to ..." link to end after the space following "to". If the editors have leisure, we'll revise the markup or the stylesheet; if we don't, my plan is to blame HTML. In a perfect world, I would revise the CSS of the output to avoid the problem you point to in 3.16.2.2. But I remember fighting with the CSS styling of these tableaux in the past, and I know this world to be an imperfect vale of tears, especially for those working with CSS. There is a hack we can use to fix the places where the problem occurs, if only I can remember what the hack is. [Pause.] No, that hack doesn't actually work in the place where I used it. [Pause.] OK, I've found a better hack and attempted to make the XSLT stylesheet generate it whenever it's needed. I think it's working. [I am here speaking only for myself, not for the WG.]
At its call today, the XML Schema WG adopted the proposal mentioned in comment #6, with one amendment: section 3.4.2.4 is split, as suggested in comment #7, into 3.4.2.4 Mapping Rule for Attribute Uses Property 3.4.2.5 Mapping Rule for Attribute Wildcard Property Cross-references pointing to the old 3.4.2.4 have been updated. The new text is integrated into the current status quo document at http://www.w3.org/XML/Group/2004/06/xmlschema-1/structures.html (member-only link) With that change, we believe this issue has been resolved, and I'm changing the Bugzilla status accordingly. Thanks to both John Arwe and Pete Cordell for the comments. John, if you are satisfied with this resolution (judging by comment #7 I guess you are, but that's for you to say), please indicate so by changing the bug's status to CLOSED. If for some reason you're not happy, please say why and REOPEN it instead. Thanks.