proposed additions to the SOAP API of the markup validator

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>


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>

Opinions and thoughts welcome.


-- 
olivier

Received on Thursday, 17 May 2007 05:57:27 UTC