RE: Effort to simplifying our spec

Jonathan,

I like what you've done, but unfortunately, it only worked on IE, not 
Mozilla. In response to your concern about this turning into an 
application, I have a suggestion:

1. Use two normal HTML documents (no Javascript), one fully expanded 
(wsdl20.html), and one fully collapsed (wsdl20-c.html), i.e. the infoset 
text is collapsed. The collapsed document can be generated from the 
expanded document via an XSLT.
2. The expanded document is normative since it contains everything in a 
printable, searchable format.
3. Each infoset section of the expanded document links ("Hide infoset") to 
the corresponding collapsed section of the collapsed document.
4. Each collapsed infoset section of the fully collapsed document links 
("Show infoset") to the corresponding expanded section of the fully 
expanded document.

The advantage of the above is that you get the illusion of expanding and 
collapsing the infoset sections but there is no Javascript. The normative 
document is still verbose, but the reader who wants a simpler view can 
easily link to the collapsed version.

Arthur Ryman,
Rational Desktop Tools Development

phone: +1-905-413-3077, TL 969-3077
assistant: +1-905-413-2411, TL 969-2411
fax: +1-905-413-4920, TL 969-4920
mobile: +1-416-939-5063
intranet: http://w3.torolab.ibm.com/DRY6/



"Jonathan Marsh" <jmarsh@microsoft.com> 
Sent by: www-ws-desc-request@w3.org
04/05/2004 08:43 PM

To
"David Booth" <dbooth@w3.org>, "David Orchard" <david.orchard@bea.com>
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

[attachment "wsdl20.html" deleted by Arthur Ryman/Toronto/IBM]