- From: <bugzilla@wiggum.w3.org>
- Date: Mon, 08 Oct 2007 18:25:20 +0000
- To: www-xml-schema-comments@w3.org
- CC:
http://www.w3.org/Bugs/Public/show_bug.cgi?id=5152 Summary: tableau presentation difficult to understand Product: XML Schema Version: 1.1 only Platform: PC OS/Version: Windows XP Status: NEW Severity: normal Priority: P2 Component: Structures: XSD Part 1 AssignedTo: cmsmcq@w3.org ReportedBy: johnarwe@us.ibm.com QAContact: www-xml-schema-comments@w3.org 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.
Received on Monday, 8 October 2007 18:25:31 UTC