Re: proposed additions to the SOAP API of the markup validator

Hey olivier,

On 5/17/07, olivier Thereaux <ot@w3.org> wrote:
>
> Hello,
>
> Here are a couple proposed changes to the SOAP API of the Markup
> Validator.
>
> The two proposed changes are both additions, and should therefore be
> backward-compatible.
>
> 1) addition of source snippet display
>
> The HTML output of the validator displays a fragment of the
> (offending) markup code where the error/warning/etc was found. It
> would be useful to have this information delivered through the SOAP
> output too.
>
> Typical value of this source snippet is escaped markup, with some
> html markup (<strong>) to locate the exact location of the error. I
> assume that for this reason, it would be safe(r) to keep the value
> within a CDATA block, but that's open to discussion.
>
> e.g
>
>      <m:source>
>        <![CDATA[
>        <strong title="Position where error was detected.">&#60;</
> strong>html&#62;&#60;head&#62;&#60;meta http-equiv=&#34;content-
> type&#34; content=&#34;text/html; charset=Shift_JI
>        ]]>
>      </m:source>

This sounds good to me.

>
> 2) addition of error message explanation
>
> The value of the validator partly comes from the fact that almost
> each error message comes with some kind of explanation about the
> potential causes and fixes of the error.
>
> The HTML output of the validator displays that as HTML (duh), <p>s
> and <ul>s. I expect most tools to consume this for inclusion into
> HTML documents, so I think it's safe to keep it as an HTML snippet.
> Here too, I suggest using a CDATA block, but up for discussion.
>
> e.g
>
>                  <m:explanation>  <![CDATA[
>                        <p class="helpwanted">
>        <a
>          href="feedback.html?uri=http%3A%2F%2Fwww.google.co.jp%
> 2F;errmsg_id=82#errormsg"
> title="Suggest improvements on this error message through our
> feedback channels"
>        >&#x2709;</a>
>      </p>
>
>      <div class="ve mid-82">
>      <p>
>        You have used a character that is not considered a "name
> character" in an
>        attribute value. Which characters are considered "name
> characters" varies
>        between the different document types, but a good rule of thumb
> is that
>        unless the value contains <em>only</em> lower or upper case
> letters in the
>        range a-z you must put quotation marks around the value. In
> fact, unless
>        you have <em>extreme</em> file size requirements it is a very
> very good
>        idea to <em>always</em> put quote marks around your attribute
> values. It
>        is never wrong to do so, and very often it is absolutely
> necessary.
>      </p>
>    </div>
>
>                    ]]>
>                  </m:explanation>
>

Anyone validating x(html) should expect to get it back or at a minimum
know how to handle it - so I think you're safe providing the context
and explanation in a snippet of html.

I also think this would be best to implement, multiple formats would
just lead to more maintenance. Both changes sounds like a good way to
implement the new features for the SOAP output.

Thanks for your work!


-- 
-Brett Bieber

http:saltybeagle.com aim:ianswerq

Received on Thursday, 17 May 2007 13:08:59 UTC