RE: Updated WSDL EI

 

> -----Original Message-----
> From: public-ws-policy-request@w3.org 
> [mailto:public-ws-policy-request@w3.org] On Behalf Of David Orchard
> Sent: Wednesday, Nov 15, 2006 9:37 AM
> To: public-ws-policy@w3.org
> Subject: Updated WSDL EI
> 
> 
> http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/wsdl11eleme
> ntidentifi
> ers.html?rev=1.5&content-type=text/html;%20charset=utf-8
> 
> Cheers,
> Dave
> 
> 

Hi David, 

As stated in the concall today, I am less keen on the current
representation of element identifiers represented as embedded in the
example. It seems to me where we ended up is more confusing for a
reader. However,  this may be a formatting issue. 

Firstly, the fragment identifiers are above each WSDL element in a
comment. However, their representation spans two lines as follows: 

<!-- http://example.org/TicketAgent.wsdl11#
         wsdl11.message(listFlightsRequest) -->

Thus, the idea that it is "one" identifier is somewhat lost. This
formatting must be fixed regardless of what we do. It should into one
line. Honestly, it threw me off when I first looked at the document. 

I also prefer to use a slightly different format, put the identifier
AFTER the element that it identifies. 

Example: 

Instead of

{<!-- http://example.org/TicketAgent.wsdl11#
         wsdl11.message(listFlightsRequest) -->
    <wsdl:message name="listFlightsRequest">
} 

Sth along the lines of like a documentation about that particular
element that has just been defined. 

   <wsdl:message name="listFlightsRequest">
       <!--
ElementId="http://example.org/TicketAgent.wsdl11.message(listFlightsRequ
est)" -->

I am guessing that you were probably trying to avoid the long lines by
splitting. Perhaps shortening the identifier by replacing the tns
"http://example.org/TicketAgent/wsdl11" with "http://..." may also help.
Text prior to the example can clarify that. 

IMO, if we were to present a separate table that lists all the
permissable element identifiers based on the sample WSDL would be more
preferable to avoid the hassle of formatting restrictions, such as line
lengths, etc. Further, the utility of element identifiers is to
introduce referenceability. Thus, it would be more illustrative for why
we have identifiers. 

However, all I want to do is to clarify the example for the reader. So
if we were to solve the problem with formatting, it also would be fine. 

Thanks again for doing all this work. And thanks Ashok for putting us
into this track, 

--umit

Received on Wednesday, 15 November 2006 22:02:59 UTC