Re: Some suggestions for the SOAP api

Ok, so after all this discussion, I have some recommendations for
significantly improving the output of your SOAP engine.  The improvements
include:

1.)  Current error <m:explanation> text includes the core explanation
bundled with other "stuff" -- this should be separated into its core
elements.

2.)  The <m:warning> elements don't include any <m:explanation> (even though
the web API uses this).  This should be added

3.)  The web API includes a summary message for all warnings: "The following
missing or conflicting information caused the validator to perform guesswork
prior to validation. If the guess or fallback is incorrect, it may make
validation results entirely incoherent. It is highly recommended to check
these potential issues, and, if necessary, fix them and re-validate the
document."  I have no idea whether there is only one version of this message
but it should be included in the SOAP output.  It gives context to the
warnings and if the w3 sees fit to revise this message with future validator
versions, I want the revised text.

4.)  The web API includes 'info' elements.  So far, I have noticed them
woven in with the errors but I "think" I might have seen one once in the
warnings section.  I am not including these in my example because I don't
know if they are their own category or just a "type" of error and warning
(Oliver -- I could use some help here).  Anyway, if they're useful to web
API users, I want 'em too.

So, excluding #4 above -- until I know more, here's what I recommend:

  <m:errors>
    <m:errorcount>2</m:errorcount>
    <m:errorlist>
      <m:error>
        <m:line>1</m:line>
        <m:col>0</m:col>
        <m:message>no document type declaration; implying &quot;&lt;!DOCTYPE
HTML SYSTEM&gt;&quot;</m:message>
        <m:messageid>344</m:messageid>
+      
<m:feedbackurl>http://validator.w3.org/feedback.html?uri=;errmsg_id=344#errormsg</m:feedbackurl>
+       <m:feedbacktext>Suggest improvements on this error message through
our feedback channels</m:feedbacktext>
        <m:explanation>
          <![CDATA[
~           <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>
          ]]>
        </m:explanation>
        <m:source><![CDATA[<strong title="Position where error was
detected.">&#60;</strong>html&#62;]]></m:source>
      </m:error>
  
        ...
  
    </m:errorlist>
  </m:errors>
  
  <m:warnings>
    <m:warningcount>2</m:warningcount>
+   <m:warningoverview>
+     <![CDATA[
+       <p>
+         The following missing or conflicting information caused the
validator to perform
+         guesswork prior to validation. If the guess or fallback is
incorrect, it may make
+         validation results entirely incoherent. It is <em>highly
recommended</em> to
+         check these potential issues, and, if necessary, fix them and
re-validate the
+         document.
+       </p>
+     ]]>
+   </m:warningoverview>
    <m:warninglist>
      <m:warning>
        <m:messageid>W06</m:messageid>
        <m:message>Unable to Determine Parse Mode!</m:message>
+       <m:explanation>
+         <![CDATA[
+           <p>The validator can process documents either as XML (for
document types such as XHTML, SVG, etc.) or SGML (for HTML 4.01 and prior
versions). For this document, the information available was not sufficient
to determine the parsing mode unambiguously, because:</p>
+           <ul>
+             <li>in <em>Direct Input</em> mode, no MIME Media Type is
served to the validator</li>
+             <li>No known Document Type could be detected</li>
+             <li>No XML declaration (<abbr>e.g</abbr> <code>&lt;?xml
version="1.0"?&gt;</code>) could be found at the beginning of the
document.</li>
+           </ul>
+           <p>As a default, the validator is falling back to SGML mode.</p>
+         ]]>
+       </m:explanation>
      </m:warning>
  
        ...
  
    </m:warninglist>
  </m:warnings>

Lines marked with (+) are new, lines marked with (~) are changed.  The
remaining question is: Where do the info notices go?

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

Received on Monday, 15 October 2007 17:46:51 UTC