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

Hi Eve,
Norman: Something for you in the bottom ;)

Thank you for your help and your comments. I have started to look at  
the source you have sent me :)

Le 23 déc. 2004, à 17:07, Eve L. Maler a écrit :
> Karl Dubost wrote:
>> * 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.

Agreed, that would be interesting to identify what's missing.
XMLSpec should be a tool that helps to publish any kind of W3C TR  
documentation. I think a W3C Note could be a possibility, I'll have to  
discuss that with people inside the Team, because there's no WG to host  
it. Then it would become a Team publication. Topic to explore.

>> * Usability of the document
> 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.

Yes my idea is to make it both so people can develop tools. Right now  
there's no way for a new editor to be able to start something with it.

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

That's an excellent idea.

> 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

I will definitely look at that.

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

cool. :)

>> * DocBook at the origin?
>  managed to find the sources.  I will send them to you under separate  
> cover.

Done. Merci !!!

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


Norm.... ;) Here? :p

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


OK I will look at that.

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

OK I will explore that.

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

My pleasure. Thank you very much for your extensive comments.



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