Re: spec-prod, xmlspec, docbook and Co.

I agree with this analysis.  More below:

At 10:57 AM 10/17/01 -0400, Norman Walsh wrote:
>/ Philippe Le Hegaret <plh@w3.org> was heard to say:
>| OASIS is leading towards the XML version of DocBook. The W3C started to use
>| xmlspec in 1996/1997 with the XML specification itself. I didn't look
>| closely at DocBook and I'm still wondering how far we go into producing
>| a common schema for specifications, but is there any chance that we can 
>merge
>| both somehow (or use a correct extension mechanism)?
>
>Considering <article> in DocBook to be roughly equivalent to <spec>,
>I arrive at the following comparison (off the top of my head):
>
>DocBook Articles vs. XMLSpec
>
>- The "meta" is quite different, XMLSpec has a whole bunch of W3C-specific
>   metadata. This could (should?) be addressed by creating an XML namespace
>   for the W3C metadata. The DocBook TC is evaluating what to do with meta
>   and allowing namespaced meta seems like a good idea.

It would need to allow it "wholesale" (you'd want to be able to pop in the 
whole W3C structure).  This would also be useful if we wanted to 
accommodate IETF documents (an idea mentioned in my message on RFEs).

I just saw Dan's mail about using dc: metadata, which sounds like a fine 
idea too, as long as (a) W3C's pubrules are adhered to and (b) there's 
enough flexibility to add new types of header information, which XMLspec 
has had problems with in the past.

>- XMLSpec tag names are often HTML-derived so they tend to be shorter.
>   (e.g. <p> vs. <para>, <att> vs. <sgmltag class='attribute'>.)
>
>- DocBook probably has more "wrappers".
>
>- DocBook uses the CALS table model, XMLSpec uses HTML. (But they aren't
>   that far apart, really.)

I think DocBook should begin to allow HTML tables anyway...

>- XMLSpec has more "special purpose" elements (e.g., <specref/>,
>   <bibref/>, etc.  where DocBook has just <xref/>).
>
>I think working towards some common format would be a really good
>idea.
>
>Q1: Are we willing to break legacy in significant ways? Could the
>     XMLSpec doctype be made more DocBook-like and vice versa?

If we had buy-in from the community for the project, and if most/all of the 
changes could be accommodated with an XSLT transformation, and if 
stylesheets were available quickly for the new format...I bet there 
wouldn't be any problem.

>Q2: Assuming that neither community is willing to accept all the
>     suggestions of the other :-), should we define an isomorphic set
>     of tags?
>
>Q3: Can this be addressed organizationally? Could the W3C be persuaded
>     to accept DocBook documents as specs? Could OASIS be persuaded to
>     accept XMLSpec?

As long as there's a stylesheet to produce acceptable HTML (as Dan noted), 
there shouldn't be a problem.

>| I'm personnally not favoring xmlspec or docbook. Using an XML format is
>| a sufficient reason for me as long as I can describe well enough the DOM
>| specifications (i.e. an XML format without support for interface would be
>| useless).
>
>Adding markup to DocBook, if there are justifiable use cases in the
>computer documentation domain, is pretty straightforward.

I see great promise in a merged schema.  But a harmonization project would 
need real resources to be done properly.

         Eve
--
Eve Maler                                    +1 781 442 3190
Sun Microsystems XML Technology Center   eve.maler @ sun.com

Received on Wednesday, 17 October 2001 12:36:41 UTC