RE: Effort to simplifying our spec

Hmm .. i think there are risks in this kind of trickery - not least it 
involves extra effort for cross-browser support - this javascript
doesn't work in my Mozilla browser.
 
however i do find the boxing of the Infoset boiler-plate sections
useful!
 

 -----Original Message----- 
 From: www-ws-desc-request@w3.org on behalf of Jonathan Marsh 
 Sent: Tue 06/04/2004 01:43 
 To: David Booth; David Orchard 
 Cc: www-ws-desc@w3.org 
 Subject: RE: Effort to simplifying our spec
 
 

 Attached are my investigations as well.  I added "click to expand" for
 the XML representations (not the mappings) for the first half dozen
 components.  Try it out!
 
 My feeling is that this approach raises a lot of questions.  If we
 collapse the spec by default, someone who prints the spec might be in
 trouble.  Searching and linking to a hidden section is also likewise
 complemented.  If we expand by default, the initial reader of the spec
 isn't actually helped.  A reader that is investigating, and then
 searching, will want a global "collapse all" and "expand all".  These
 controls would be most useful if they were sprinkled throughout the spec
 (like any place that is collapsed).  All in all, seems like a slippery
 road to defining an application - which is much more complicated than a
 document.
 
 I don't think the approach represented here is substantially better than
 linking to a section containing all the infoset and mapping stuff, if we
 even decide to do that.
 
 > -----Original Message-----
 > From: David Booth [mailto:dbooth@w3.org]
 > Sent: Wednesday, March 17, 2004 2:21 PM
 > To: David Orchard; Jonathan Marsh
 > Cc: www-ws-desc@w3.org
 > Subject: Effort to simplifying our spec
 >
 > DaveO & Jonathan,
 >
 > SUMMARY
 > I don't think the style sheet approach will work.  I recommend we
 continue
 > as is.
 >
 > EXPLANATION
 > I've looked over our Part1 spec to think about how we might simplify
 the
 > presentation to the reader.
 >
 > At present, I don't think a style sheet approach that would expand or
 > contract the text is feasible.  The main issue is that each section
 has
 > both a subsection on the properties of that component, and a
 subsection on
 > the mapping from the XML infoset to those properties.  For example:
 >
 http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20.html#Defi

 ni
 > tions_XMLRep
 > and
 >
 http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20.html#Defi

 ni
 > tions_Mapping
 >
 > Much of the content of those subsections is fairly boilerplate, merely
 > repeating what is evident from the pseudo-schema above.  But the
 problem
 > is
 > that they aren't ENTIRELY boilerplate: both of these subsections have
 > meaningful, non-boilerplate text mixed in with (boring) boilerplate
 text.
 >
 > It might be possible to factor out the meaningful, non-boilerplate
 text,
 > but I'm not sure we could reliably ensure that no meaningful text ever
 > crept back in, so I'd be wary of using a style sheet to hide parts.
 >
 > I don't see an easy solution to this problem, so at this point I
 suggest
 > we
 > continue as is.
 >
 >
 > --
 > David Booth
 > W3C Fellow / Hewlett-Packard
 > Telephone: +1.617.253.1273

Received on Tuesday, 6 April 2004 03:06:51 UTC