Re: Some suggestions for the SOAP api

olivier Thereaux wrote:
> On Oct 11, 2007, at 09:00 , Chris Parrish wrote:
>> Bummer.  Well, as a compromise, are the explanation messages (in HTML)
>> separate from the helpwanted links?
>
> Yes, they are, the helpwanted could indeed be removed altogether from soap
> output.

Yeah, I'd like to remove it from the explanation (although I'm fine to move
it elsewhere rather than just kill it -- as you'll see in my following
post).

>>  what if they change the messages and their markup?  If your app was
>> critical enough, you'd have a problem and maybe not even know it.
>
> If the soap markup is generated from the message, and the messages change,
> the soap output would change, too.
>

The point here Oliver, is that if you deliver me something in the form of:

  <p>
    Explanation element 1 text
  </p>
  <p>
    Explanation element 2 text
  </p>

And I write a routine to parse the <p>'s and then you guys change the
explanation messages to the format of:

  <div>
    <p>
      <ul>
        <li>Explanation element 1 text</li>
        <li>Explanation element 2 text</li>
      </ul>
    </p>
  </div>

Then my parsing code now would no longer work.  Worse still, I might not
know that my app is broken -- it might just be spitting out garbled output
to users.

However, Karim drew my attention to the fact that there is a bunch of
necessary markup inside your explanations (like internal bullet lists,
emphasis, even links) that I don't want to loose.  So, I'm OK with dropping
the request for plain-text only explanations.

That said, the goal should be to reduce the current explanation text to as
much of their core elements as possible.  For instance, the current text:

    <div class="ve mid-344">
    <p>
	The checked page did not contain a document type ("DOCTYPE") declaration.
	The Validator has tried to validate with a fallback DTD,
        but this is quite likely to be incorrect and will generate a large
number
        of incorrect error messages. It is highly recommended that you
insert the
	proper DOCTYPE declaration in your document -- instructions for doing this
	are given above -- and it is necessary to have this declaration before the
 	page can be declared to be valid.
    </p>
  </div>

should probably have the <div>'s stripped off.  
  * That way, I can stick the explanation in my own structure and apply my
own class and styles.
  * The semantic grouping of all the paragraphs together via <div>'s is
redundant -- the <m:explanation> already covers that.
  * Future changes to the message structure are less likely to cause any
issues with my code since I'm only dealing with the essentials of the
explanation and not formatting elements (in the message-change example
above, you'd change the SOAP output to only include the <ul>'s and their
content).

I'll post a follow-up message to this one outlining my suggestions for
revising the output (that way I can clarify what I'm saying here and address
some other issues I've found).

-Chris





-- 
View this message in context: http://www.nabble.com/Some-suggestions-for-the-SOAP-api-tf4532107.html#a13217622
Sent from the w3.org - www-validator mailing list archive at Nabble.com.

Received on Monday, 15 October 2007 17:25:24 UTC