[Issues] W3C XML Specification Guide v2.1

All people here, (and, Eve and Norman)

Following the discussion started at
http://www.w3.org/mid/7D09AF4C-493B-11D9-BE1B-0003934BEBF0@w3.org

OK. I have read the guide to W3C XML Specification, Version 2.1 [1]. 
I'm sorry for any inappropriate comments, as I don't have the full 
history of the development and the rationales which have driven to 
certain choices.

* Recursivity

Does it seems illogical to use XMLSpec to edit “XMLSpec Guide” itself? 
because “XMLSpec Guide” is a specification. :)))

* Usability of the document

	I found the document going through a lot of details (chapter 1) on how 
to modify and create the DTDs for XMLSpec. This information is upfront. 
If I was a specification editor discovering the document, I would run 
away :) A suggestion would be to either:
	- Put the details about modifying, managing XMLSpec in an Appendix
	- Make it a separate document that really explain how to hack XMLSpec 
and leave the document itself as a tutorial.
	
	I would also add links to the Manual of Style [2] and QA Specification 
Guidelines [3] when it helps to understand the benefits of using this 
precise markup.

* Kickstart Guide

Chapter 2 is starting out of the blue about common attributes topic. 
And I said to myself: “huh? yes errr… and how do I start my editing?”

I believe that the Chapter 1 should be something explaining the 
different steps to start editing with XMLSpec.
	- What are the constraints?
	- What do I have to think?
	- What are my tools?
	- How do I organize the work?
	- One or multiple editors?

Someone could enlighten me with a kind of basic steps to start editing 
with XMLSpec?  I'm not asking for a detailed explanation, but what do 
you do when you start.

* Linkage between markup.

When a concept is explained, there are missing links. For example “id” 
attribute is explained and then there's a list of constraints on issue, 
wfcnote, vcnote, etc but without link to the definition of these markup 
elements.

* Style sheet of “XMLSpec Guide”

hmmmm a lot to do ;) but that I can do easily. And if we use XMLSpec to 
edit “XMLSpec Guide”, it could be styled as a W3C Note or something 
similar.

* DocBook at the origin?

It seems from the header

<meta name="GENERATOR"
       content="Modular DocBook HTML Stylesheet Version 2.0
                (derived from 1.41) " />

in the “XMLSpec Guide” document that it has been created from a docbook 
document but the source is not is not available in 
http://www.w3.org/XML/1998/06/

I guess Eve might have it? That would help to restart the document.

* Diff between the Guide version and now

Norman, is it possible to have a diff version of the DTD or XSLT or XML 
Schema between the version 2.1 and the version actually used?

* Users versus Developers

If I understood for Attributes the outline is
	+ attribute_name
		- Description: explain the semantics
                        and giving dependencies
                        on elements
		- Processing expectations: how to handle
                        this with a processor
		- Rationale: explain why the element has
                        been created, the design
                        choices.

for element is basically the same, plus the list of attributes and a 
graph showing the hierarchy of elements.

Comments: I think the Description part is missing a real explanation of 
the purpose sometimes and examples in XML and the possible output in 
XHTML for the user. The Processing expectations and rationale are 
really for XMLSpec tools developers.

Then I would do for each part something with this kind of outline:
	
+Element/Attribute
	- Description
	- Graph
	- Benefits (context of Manual of style and/or SpecGL or something else)
	- Example
		- XML Input
		- XHTML Output?
	- Tools Developer
		- Processing expectations:
		- Rationale:
		- XSLT example?

* XHTML semantics
	I have seen elements, like "emph", which have the same semantics than 
XHTML ones but with a different name. Wouldn't it be easier or too late 
to use XHTML semantics when it exits? :) just a naive question.


[1] http://www.w3.org/XML/1998/06/xmlspec-report-v21.htm
[2] http://www.w3.org/2001/06/manual
[3] http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/
[4] http://www.w3.org/XML/1998/06/xmlspec-report-v21.htm#AEN2305

-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager
*** Be Strict To Be Cool ***