Re: [Issues] W3C XML Specification Guide v2.1

Karl, thanks for doing this very useful and interesting analysis -- I 
have no objection to improving the documentation, though I'm in no 
position to do this myself at this point!  I think it would be great if 
you took on this project.

I wrote the existing guide in order to provide some kind of technical 
reference so that the design ideas and constraints didn't get totally 
lost, and knew it was inadequate even then...

Regarding your specific ideas:

Karl Dubost wrote:
> 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. :)))

At the time, I think I used DocBook-to-HTML because it was what I was 
used to, and I could work much more quickly.  I think XMLspec is 
definitely close enough in purpose to a general "XML vocabulary 
documentation guidebook" to be useful for this purpose, although -- 
unless W3C publishes it as a Note -- its available metadata fields won't 
be quite right and it's probably not worth customizing them for this 
self-documentation.

> * 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.

It's not really a tutorial as it stands, but I think it's a great idea 
to have multiple docs (or at least sections), with reference vs. 
friendly, example-filled material.

>     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.

That's a great idea.  The W3C pubrules have come a long way since this 
was published, and showing examples of officially produced output from 
correct markup will reinforce the rationale for using it.

> * 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.

It would be great to start with a full template example, then have small 
subsections explaining each part.

Another way to go might be something like this (the OASIS StarOffice 
template, which is self-referential and meant to approximate a tutorial):

Main page for OASIS "spectools":
http://www.oasis-open.org/spectools/
PDF output of StarOffice template:
http://www.oasis-open.org/spectools/docs/spectools-openoffice-sample-draft-03.pdf

> * 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.

Agreed that this should be added.

> * 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.

Great idea.  This was something I wanted to do a long time ago, but 
couldn't take enough time from my "day job" to manage it.

> * 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.

I managed to find the sources.  I will send them to you under separate 
cover.

> * 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?

I'll let Norm answer that one.

> * 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.

Yes, since I was primarily trying to document the design of the language 
rather than the usage, the main audience was stylesheet developers and 
customizers rather than users.  That's why the guide does such a poor 
job at helping users. :-)

> 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?

If a single reference document will serve all the different audiences, 
it makes sense to have all these fields.  Maybe some of the fields that 
Norm uses in his DocBook guide (sample here: 
http://www.oasis-open.org/docbook/documentation/reference/html/abbrev.html) 
would be useful, and most are automatically generated.

> * 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.

This one is actually answered in the guide!  See issue #6 here:

http://www.w3.org/XML/1998/06/xmlspec-report-v21.htm#intro

Dan Connolly commented on this very early, but we never got the energy 
or desire to convert over to HTML usage where it overlapped perfectly.

> [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

Thanks again for being interested in improving the documentation, and 
happy holidays!

	Eve
-- 
Eve Maler                                        +1 781 442 3190
Sun Microsystems                            cell +1 781 354 9441
Web Products, Technologies, and Standards    eve.maler @ sun.com

Received on Thursday, 23 December 2004 22:06:21 UTC