Update the docs, particularly with regard to API.origin/sideshowbarker/docs-api

10 files changed, 545 insertions, 641 deletions

diff --git a/htdocs/docs/api.html b/htdocs/docs/api.html
index 3e863c9..5cd288c 100755
--- a/htdocs/docs/api.html
+++ b/htdocs/docs/api.html
@@ -3,351 +3,13 @@
 --><!--#include virtual="../header.html" -->
 
 <div class="doc">
-<h2>Markup Validator Web Service API<br />
-SOAP 1.2 validation interface documentation</h2>
-
-<p>Interface applications with the Markup Validator through its <strong>experimental</strong> API. This is version 0.2, dated May 2007. For a history of the format, see <a href="#changelog">Change Log</a>.</p>
-<p><strong>Note</strong>: Please be considerate in using this shared, free resource. 
-	Consider <a href="install.html">Installing your own instance of the validator</a>
-	for smooth and fast operation. Excessive use of the W3C Validation Service
-	will be blocked.</p>
-
-
-<h3 id="TableOfContents">Table of Contents</h3>
-
-    <div id="toc">
-      <ul>
-        <li><a href="#requestformat">Validation Request Format</a></li>
-        <li><a href="#soap12format">SOAP format description</a>
-         <ul>
-          <li><a href="#soap12_sample">sample SOAP 1.2 validation response</a></li>
-          <li><a href="#soap12response">SOAP1.2 response format reference</a></li>
-          <li><a href="#soap12message">SOAP1.2 atomic message (error or warning) format reference</a></li>
-          <li><a href="#changelog">Change Log</a></li>
-         </ul>
-        </li>
-        <li><a href="#libs">Libraries</a></li>
-        <li><a href="#http_headers">Using HTTP headers to know validation results</a></li>
-      </ul>
-    </div>
-    
-    <p id="skip"></p>
-
-<h3 id="requestformat">Validation Request Format</h3>
-
+<h2>Markup Validator Web Service API</h2>
+<!--#include virtual="../htmlchecker_api.html" -->
 <p>
-  Below is a table of the parameter you can use to send a query to the W3C
-  Markup Validator. All parameter values except data in
-  <code>uploaded_file</code> are expected to be encoded in the UTF-8 character
-  encoding.
+  Also available is historical documentation about the
+  <a href="obsolete-api.html">obsolete SOAP 1.2 API for the Markup Validator</a>
+  (which you should no longer use).
 </p>
-<p>If you want to use W3C's public validation server, use the parameters below
- in conjunction with the following base URI:<br />
-<kbd>http://validator.w3.org/check</kbd> <br />
-(replace with the address of your own server if you want to call a private instance of the validator)</p>
-
-<p><strong>Note</strong>: If you wish to call the validator programmatically for a batch of documents,
-please make sure that your script will <code>sleep</code> for <strong>at least 1 second</strong> 
-between requests. The Markup Validation service is a free, public service for all, your respect
-is appreciated. thanks.</p>
-
-<table class="refdoc">
-<tr>
-<th>Parameter</th><th>Description</th><th>Default value</th>
-</tr>
-<tr>
-  <th>uri</th>
-  <td>The <acronym title="Universal Resource Locator">URL</acronym> of the document to validate</td>
-  <td>None, but either this parameter, or <code>uploaded_file</code>, 
-  or <code>fragment</code> must be given.</td>
-</tr>
-<tr>
-  <th>uploaded_file</th>
-  <td>The document to validate, POSTed as multipart/form-data</td>
-  <td>None, but either this parameter, or <code>uri</code>,   
-  or <code>fragment</code> must be given.</td>
-</tr>
-<tr>
-  <th>fragment</th>
-  <td>The source of the document to validate. Full documents only.</td>
-  <td>None, but either this parameter, or <code>uri</code>,
-  or <code>uploaded_file</code> must be given.</td>
-</tr>
-<tr>
-  <th>output</th>
-  <td>triggers the various outputs formats of the validator. If unset, the usual
-  Web format will be sent. If set to <code>soap12</code>, the SOAP1.2 interface will 
-  be triggered. See <a href="#soap12format">below for the SOAP 1.2 response format description</a>.</td>
-  <td>unset</td>
-</tr>
-<tr>
-  <th>charset</th>
-  <td>Character encoding override: 
-  Specify the character encoding to use when parsing the document. When used with
-  the auxiliary parameter <code>fbc</code> set to 1, the given encoding will only be used as 
-  a fallback value, in case the charset is absent or unrecognized. Note that this parameter
-  is ignored if validating a <code>fragment</code> with the direct input interface.</td>
-  <td>None, by default the validator detects the charset of the document automatically.</td>
-</tr>
-<tr>
-  <th>doctype</th>
-  <td>Document Type override:
-  Specify the Document Type (DOCTYPE) to use when parsing the document. When used 
-  with  the auxiliary parameter <code>fbd</code> set to 1, the given document type will only be used
-  as a fallback value, in case the document's DOCTYPE declaration is missing or unrecognized.</td>
-  <td>None, by default the validator detects the document type of the document automatically.</td>
-</tr>
-<tr>
-  <th>verbose</th>
-  <td>In the web interface, when set to 1, will make error messages, explanations 
-  and other diagnostics more verbose. In SOAP output, does not have any impact.</td>
-  <td>0 (unset)</td>
-</tr>
-<tr>
-  <th>debug</th>
-  <td>When set to 1, will output some extra debugging information on the validated resource (such as HTTP headers) and validation process (such as parser used, parse mode etc.). In the SOAP output, this information will be given in &lt;m:debug&gt; elements.</td>
-  <td>0 (unset)</td>
-</tr>
-<tr>
-  <th>ss</th>
-  <td> as <em>show source</em>. In the web interface, triggers the display of the source
-  after the validation results. In SOAP output, does not have any impact.</td>
-  <td>0 (unset)</td>
-</tr>
-<tr>
-  <th>outline</th>
-  <td>In the web interface, when set to 1, triggers the display of the document outline 
-  after the validation results. In SOAP output, does not have any impact.</td>  
-  <td>0 (unset)</td>
-</tr>
-</table>
-<h3 id="soap12format">SOAP format description</h3>
-
-<p>When called with parameter <code>output=soap12</code>, the validator will switch
-to its SOAP 1.2 interface (experimental for now). Below is a sample response, as well as
-a description of the most important elements of the response.</p>
-
-
-
-<h4 id="soap12_sample">sample SOAP 1.2 validation response</h4>
-<p>A SOAP response for the validation of a document (invalid) will look like this:</p>
-<pre style="font-size: smaller"> 
-&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
-&lt;env:Envelope xmlns:env=&quot;http://www.w3.org/2003/05/soap-envelope&quot;&gt;
-&lt;env:Body&gt;
-&lt;<a href="#soap12_markupvalidationresponse">m:markupvalidationresponse</a>
-env:encodingStyle=&quot;http://www.w3.org/2003/05/soap-encoding&quot; 
-xmlns:m=&quot;http://www.w3.org/2005/10/markup-validator&quot;&gt;
-    &lt;<a href="#soap12_uri">m:uri</a>&gt;http://qa-dev.w3.org/wmvs/HEAD/dev/tests/xhtml1-bogus-element.html&lt;/m:uri&gt;
-    &lt;<a href="#soap12_checkedby">m:checkedby</a>&gt;http://validator.w3.org/&lt;/m:checkedby&gt;
-    &lt;<a href="#soap12_doctype">m:doctype</a>&gt;-//W3C//DTD XHTML 1.0 Transitional//EN&lt;/m:doctype&gt;
-    &lt;<a href="#soap12_charset">m:charset</a>&gt;utf-8&lt;/m:charset&gt;
-    &lt;<a href="#soap12_validity">m:validity</a>&gt;false&lt;/m:validity&gt;
-    &lt;<a href="#soap12_errors">m:errors</a>&gt;
-        &lt;<a href="#soap12_errorcount">m:errorcount</a>&gt;1&lt;/m:errorcount&gt;
-        &lt;<a href="#soap12_errorlist">m:errorlist</a>&gt;
-          
-            &lt;<a href="#soap12_error">m:error</a>&gt;
-                &lt;<a href="#soap12_line">m:line</a>&gt;13&lt;/m:line&gt;
-                &lt;<a href="#soap12_col">m:col</a>&gt;6&lt;/m:col&gt;                                           
-                &lt;<a href="#soap12_source">m:source</a>&gt;  
-                &lt;![CDATA[
-                  &amp;#60;foo&lt;strong title=&quot;Position where error was detected.&quot;&gt;&amp;#62;&lt;/strong&gt;This phrase is enclosed in a bogus FOO element.&amp;#60;/foo&amp;#62;
-                  ]]&gt;
-                &lt;/m:source&gt;                                           
-                &lt;<a href="#soap12_explanation">m:explanation</a>&gt;
-                  &lt;![CDATA[
-                    &lt;p&gt; ... &lt;/p&lt;p&gt;
-                  ]]&gt;
-                &lt;/m:explanation&gt;                                           
-                &lt;<a href="#soap12_messageid">m:messageid</a>&gt;76&lt;/m:messageid&gt;                                           
-                &lt;<a href="#soap12_message">m:message</a>&gt;element &quot;foo&quot; undefined&lt;/m:message&gt;
-            &lt;/m:error&gt;
-           
-        &lt;/m:errorlist&gt;
-    &lt;/m:errors&gt;
-    &lt;m:warnings&gt;
-        &lt;m:warningcount&gt;0&lt;/m:warningcount&gt;
-        &lt;m:warninglist&gt;
-        
-        
-        &lt;/m:warninglist&gt;
-    &lt;/m:warnings&gt;
-&lt;/m:markupvalidationresponse&gt;
-&lt;/env:Body&gt;
-&lt;/env:Envelope&gt;
-</pre>
-<h4 id="soap12response">SOAP1.2 response format reference</h4>
-
-<table class="refdoc">
-<tr><th>element</th><th>description</th></tr>
-<tr>
-  <th id="soap12_markupvalidationresponse">markupvalidationresponse</th>
-  <td>The main element of the validation response. Encloses all other information about the validation results.</td>
-</tr>
-<tr>
-  <th id="soap12_uri">uri</th>
-  <td>the address of the document validated. Will (likely?) be <kbd>upload://Form Submission</kbd>
-  if an uploaded document or fragment was validated.
-  In <a href="http://www.w3.org/WAI/ER/">EARL</a> terms, this is the <kbd>TestSubject</kbd>.
-  </td>
-</tr>
-<tr>
-  <th id="soap12_checkedby">checkedby</th>
-  <td>Location of the service which provided the validation result. 
-  In <a href="http://www.w3.org/WAI/ER/">EARL</a> terms, this is the <kbd>Assertor</kbd>.
-  </td>
-</tr>
-<tr>
-  <th id="soap12_doctype">doctype</th>
-  <td>Detected (or forced) Document Type for the validated document</td>
-</tr>
-<tr>
-  <th id="soap12_charset">charset</th>
-  <td>Detected (or forced) Character Encoding for the validated document</td>
-</tr>
-<tr>
-  <th id="soap12_validity">validity</th>
-  <td>Whether or not the document validated passed or not formal validation (true|false boolean)</td>
-</tr>
-<tr>
-  <th id="soap12_errors">errors</th>
-  <td>Encapsulates all data about errors encountered through the validation process</td>
-</tr>
-<tr>
-  <th id="soap12_errorcount">errorcount</th>
-  <td>a child of <a href="#soap12_errors">errors</a>, counts the number of errors listed</td>
-</tr>
-<tr>
-  <th id="soap12_errorlist">errorlist</th>
-  <td>a child of <a href="#soap12_errors">errors</a>, contains the list of errors (surprise!)</td>
-</tr>
-<tr>
-  <th id="soap12_error">error</th>
-  <td>a child of <a href="#soap12_errorlist">errorlist</a>, contains the information on a single 
-  validation error. </td>
-</tr>
-</table>
-<p><strong>Note</strong>: <code>warnings</code>, <code>warningcount</code>, 
-<code>warninglist</code> and <code>warning</code> are similar to, respectively,
-<code><a href="#soap12_errors">errors</a></code>, 
-<code><a href="#soap12_errorcount">errorcount</a></code>, 
-<code><a href="#soap12_errorlist">errorlist</a></code> and 
-<code><a href="#soap12_error">error</a></code>.
-</p>
-<h4 id="soap12message">SOAP1.2 atomic message (error or warning) format reference</h4>
-<p>As seen as the example above, the children of the <code><a href="#soap12_error">error</a></code>
-element, but also the <code>warning</code> element are <code>line</code>, <code>col</code> and
-<code>message</code>, defined below:</p>
-<table class="refdoc">
-<tr><th>element</th><th>description</th></tr>
-<tr>
-  <th id="soap12_line">line</th>
-  <td>Within the source code of the validated document, refers to the line where the error was detected.</td>
-</tr>
-<tr>
-  <th id="soap12_col">col</th>
-  <td>Within the source code of the validated document, refers to the column of the line where the error was detected.</td>
-</tr>
-<tr>
-  <th id="soap12_message">message</th>
-  <td>The actual error message</td>
-</tr>
-<tr>
-  <th id="soap12_messageid">messageid</th>
-  <td>The number/identifier of the error, as addressed internally by the validator</td>
-</tr>
-<tr>
-  <th id="soap12_explanation">explanation</th>
-  <td>Explanation for the error. Given as HTML fragment within CDATA block.</td>
-</tr>
-<tr>
-  <th id="soap12_source">source</th>
-  <td>Snippet of the source where the error was found. Given as HTML fragment within CDATA block.</td>
-</tr>
-</table>
-
-<h4 id="changelog">Change Log</h4>
-<p>Up to version 0.2, all changes are backward-compatible.</p>
-<dl>
-  <dt>v 0.2 (June 2007)</dt>
-  <dd><ul>
-    <li><code>debug</code> parameter now has an effect on both HTML and SOAP outputs</li>
-    <li><code>messageid</code> is now implemented</li>
-    <li>added <code>source</code> and <code>explanation</code> elements.</li>
-    </ul>
-  </dd>
-  <dt>v 0.1</dt>
-  <dd><p>Initial revision</p></dd>
-</dl>
-
-<h3 id="libs">Libraries</h3>
-<p>Building of libraries used to interact with the validator's API is <a href="http://www.w3.org/QA/2006/10/validator_api.html">encouraged</a>. If you are the 
-    maintainer of such a library, <a href="../feedback.html">contact
-us</a> and we will list it here.</p>
-<p>W3C has not reviewed, verified nor endorses these
-implementations.</p>
-
-<h4>Known libraries for the W3C Markup Validator API</h4>
-
-<ul>
-   <li><a href="http://search.cpan.org/dist/WebService-Validator-HTML-W3C/">WebService::Validator::HTML::W3C</a> in Perl, 
-       by Struan Donald.</li>
-   <li><a href="http://pear.php.net/package/Services_W3C_HTMLValidator" title="PEAR Package : Services_W3C_HTMLValidator">Services_W3C_HTMLValidator</a> in PHP, a PEAR library by Brett Bieber.</li>
-   <li><a href="http://www.clickfind.com.au/developers-directory/code.cfm">ColdFusion (MX7) class</a> by the clickfind team.</li>
-   <li><a href="http://sourceforge.net/projects/w3cmarkupvalida/">C# library</a> by María Eugenia Fernández Menéndez.</li>
-   <li><a href="http://www.rexsl.com/rexsl-w3c/">Java client</a> by the ReXSL.com team.</li>
-   <li><a href="http://pypi.python.org/pypi/py_w3c/">Python library</a> by Kazbek Byasov.</li>
-</ul>
-
-<h3 id="http_headers">Using HTTP headers to know validation results</h3>
-
-<p>Every validation result is served via the HTTP protocol, with custom headers giving a simple, quick way
-    to get validation results without having to parse the results body. This is a simple (but poorer) alternative to using 
-    the full API described above.</p>
-    
-<p>The HTTP headers for a validation results page will generally look like:</p>
-<pre>
-    HEAD 'http://validator.localhost/check?uri=http%3A%2F%2Fwww.w3.org'
-    
-    200 OK
-    [...]
-    Content-Language: en
-    Content-Type: text/html; charset=utf-8
-    X-W3C-Validator-Errors: 0
-    X-W3C-Validator-Warnings: 0
-    X-W3C-Validator-Recursion: 1
-    X-W3C-Validator-Status: Valid
-</pre>
-
-<p>The headers and their values are as follows:</p>
-<table>
-    <tr><th>Header</th><th>Value</th><th>Notes</th></tr>
-    <tr>
-        <td>X-W3C-Validator-Status</td>
-        <td><code>Valid</code> or <code>Invalid</code> if validation was performed.<br />
-          value will be <code>Abort</code> if a fatal error (decoding, 404 not found, etc) 
-          was encountered and validation could not be performed</td>
-        <td>Note: <code>Abort</code> value was added in version 0.8.0</td>
-    </tr>
-    <tr>
-        <td>X-W3C-Validator-Errors</td>
-        <td>Number of Errors found during validation. <code>0</code> if no errors found.</td>
-        <td>0 does not necessarily mean "valid" (it may mean that validation could not be performed)</td>
-    </tr>
-    <tr>
-        <td>X-W3C-Validator-Warnings</td>
-        <td>Number of Warnings found during validation. <code>0</code> if no errors found.</td>
-        <td>The warnings include validation warning, as well as pre-parsing warnings (such as character encoding mismatch, doctype override, etc.)</td>
-    </tr>
-    <tr>
-        <td>X-W3C-Validator-Recursion</td>
-        <td>Integer. Generally, <code>1</code>. More if recursively validating validation results. 
-           </td>
-        <td>    The validator will use this in conjunction with its <code>Max Recursion</code> setup to avoid
-               abusive recursion (Denial of Service attack).</td>
-    </tr>
-</table>
 </div>
 <!--#include virtual="../footer.html" -->
   </body>
diff --git a/htdocs/docs/install.html b/htdocs/docs/install.html
index 4ce3e19..ae0f565 100755
--- a/htdocs/docs/install.html
+++ b/htdocs/docs/install.html
@@ -3,14 +3,16 @@
 --><!--#include virtual="../header.html" -->
 
 <div class="doc">
-<h2>Installation information <br />for the W3C Markup Validator</h2>
-
-<h3 id="TableOfContents">Table of Contents</h3>
+  <h2>Installation information <br />for the W3C Markup Validator</h2>
+<!--#include virtual="../htmlchecker.html" -->
+  <p>
+    If for some reason you'd rather install and run a service based on the same source as
+    the W3C Markup Validator, this page provides the following information:
+  </p>
 
     <div id="toc">
       <ul>
             <li><a href="#install-package">Installing on packaged systems</a></li>
-            <li><a href="#otherguides">This guide, and other guides</a></li>
             <li><a href="#install-fromsource">Install from source</a> (generic case)
 	     <ul>
 			<li><a href="#install-prereq">Step 0: Prerequisites</a></li>
@@ -31,17 +33,8 @@
     
 
     <div id="install" class="stb">
-    <a name="skip" id="skip"> </a>
-
-    <h3 id="install-package">Installing on packaged systems</h3>
-    
-    <p>The easiest way to install released versions of the Markup Validator is to use the packages created
-    for some platforms by contributors: Mac OS X, openSUSE/SUSE Linux, Debian GNU/Linux and Fedora/Red Hat packages are 
-    <a href="../source/">available</a>.</p>
-
+    <a id="skip"> </a>
 
-    <h3 id="otherguides">This guide, and other guides</h3>    
-    <h4>Other installation guides</h4>
     <p>The installation guide we provide here is a rather generic set of instructions, 
     which should work on most systems. To our knowledge, the following platform-specific 
     guides are also available and can be of interest :</p>
@@ -53,12 +46,19 @@
         by Nick Talbott</li>
     </ul>
     <h4>Related documentation</h4>
-    <p>This installation guides presumes knowledge of the <a href="../source/">Source availability</a> for the
+    <p>This installation guides presumes knowledge of the <a href="../source/">source availability</a> for the
     Markup Validator.</p>
     <p>We recommend that <a href="devel.html">developers</a> wishing to contribute on the Markup Validator or modify it
     go through this installation procedure once, to get familiar with the system.</p>
 
     
+    <h3 id="install-package">Installing on packaged systems</h3>
+    
+    <p>The easiest way to install released versions of the Markup Validator is to use the packages created
+    for some platforms by contributors: Mac OS X, openSUSE/SUSE Linux, Debian GNU/Linux and Fedora/Red Hat packages are 
+    <a href="../source/">available</a>.</p>
+
+
     <h3 id="install-fromsource">Installing from source (generic case)</h3>
     <p>These instructions are strongly inspired from Nick Talbott's guide for Slackware Linux. Thanks Nick!</p>
 
@@ -325,8 +325,7 @@ HTML5 = http://localhost:8888/html5/
               </p>
               <p>
                 This can be done by inserting the contents of the
-                <code>httpd/conf/httpd.conf</code> file (from where you
-                unpacked the validator's tarball above) in your
+                <code>httpd/conf/httpd.conf</code> file in your
                 <code>httpd.conf</code>, or by copying the file somewhere
                 and including it like:
               </p>
diff --git a/htdocs/docs/obsolete-api.html b/htdocs/docs/obsolete-api.html
new file mode 100644
index 0000000..54253cf
--- /dev/null
+++ b/htdocs/docs/obsolete-api.html
@@ -0,0 +1,361 @@
+<!--#set var="title" value="Documentation of the Programmatic Interface (API) to The W3C Markup Validation Service"
+--><!--#set var="relroot" value="../"
+--><!--#include virtual="../header.html" -->
+
+<div class="doc">
+<h2>Obsolete SOAP 1.2 Markup Validator Web Service API</h2>
+
+<p>
+  This page provides historical documentation on the obsolete SOAP 1.2 API
+  for the Markup Validator.
+</p>
+
+<p>
+  <b>You should no longer use this API for any purpose.</b>
+</p>
+
+<p><strong>Note</strong>: Please be considerate in using this shared, free resource.
+	Consider <a href="install.html">Installing your own instance of the validator</a>
+	for smooth and fast operation. Excessive use of the W3C Validation Service
+	will be blocked.</p>
+
+
+<h3 id="TableOfContents">Table of Contents</h3>
+
+    <div id="toc">
+      <ul>
+        <li><a href="#requestformat">Validation Request Format</a></li>
+        <li><a href="#soap12format">SOAP format description</a>
+         <ul>
+          <li><a href="#soap12_sample">sample SOAP 1.2 validation response</a></li>
+          <li><a href="#soap12response">SOAP1.2 response format reference</a></li>
+          <li><a href="#soap12message">SOAP1.2 atomic message (error or warning) format reference</a></li>
+          <li><a href="#changelog">Change Log</a></li>
+         </ul>
+        </li>
+        <li><a href="#libs">Libraries</a></li>
+        <li><a href="#http_headers">Using HTTP headers to know validation results</a></li>
+      </ul>
+    </div>
+    
+    <p id="skip"></p>
+
+<h3 id="requestformat">Validation Request Format</h3>
+
+<p>
+  Below is a table of the parameter you can use to send a query to the W3C
+  Markup Validator. All parameter values except data in
+  <code>uploaded_file</code> are expected to be encoded in the UTF-8 character
+  encoding.
+</p>
+<p>If you want to use W3C's public validation server, use the parameters below
+ in conjunction with the following base URI:<br />
+<kbd>http://validator.w3.org/check</kbd> <br />
+(replace with the address of your own server if you want to call a private instance of the validator)</p>
+
+<p><strong>Note</strong>: If you wish to call the validator programmatically for a batch of documents,
+please make sure that your script will <code>sleep</code> for <strong>at least 1 second</strong> 
+between requests. The Markup Validation service is a free, public service for all, your respect
+is appreciated. thanks.</p>
+
+<table class="refdoc">
+<tr>
+<th>Parameter</th><th>Description</th><th>Default value</th>
+</tr>
+<tr>
+  <th>uri</th>
+  <td>The <acronym title="Universal Resource Locator">URL</acronym> of the document to validate</td>
+  <td>None, but either this parameter, or <code>uploaded_file</code>, 
+  or <code>fragment</code> must be given.</td>
+</tr>
+<tr>
+  <th>uploaded_file</th>
+  <td>The document to validate, POSTed as multipart/form-data</td>
+  <td>None, but either this parameter, or <code>uri</code>,   
+  or <code>fragment</code> must be given.</td>
+</tr>
+<tr>
+  <th>fragment</th>
+  <td>The source of the document to validate. Full documents only.</td>
+  <td>None, but either this parameter, or <code>uri</code>,
+  or <code>uploaded_file</code> must be given.</td>
+</tr>
+<tr>
+  <th>output</th>
+  <td>triggers the various outputs formats of the validator. If unset, the usual
+  Web format will be sent. If set to <code>soap12</code>, the SOAP1.2 interface will 
+  be triggered. See <a href="#soap12format">below for the SOAP 1.2 response format description</a>.</td>
+  <td>unset</td>
+</tr>
+<tr>
+  <th>charset</th>
+  <td>Character encoding override: 
+  Specify the character encoding to use when parsing the document. When used with
+  the auxiliary parameter <code>fbc</code> set to 1, the given encoding will only be used as 
+  a fallback value, in case the charset is absent or unrecognized. Note that this parameter
+  is ignored if validating a <code>fragment</code> with the direct input interface.</td>
+  <td>None, by default the validator detects the charset of the document automatically.</td>
+</tr>
+<tr>
+  <th>doctype</th>
+  <td>Document Type override:
+  Specify the Document Type (DOCTYPE) to use when parsing the document. When used 
+  with  the auxiliary parameter <code>fbd</code> set to 1, the given document type will only be used
+  as a fallback value, in case the document's DOCTYPE declaration is missing or unrecognized.</td>
+  <td>None, by default the validator detects the document type of the document automatically.</td>
+</tr>
+<tr>
+  <th>verbose</th>
+  <td>In the web interface, when set to 1, will make error messages, explanations 
+  and other diagnostics more verbose. In SOAP output, does not have any impact.</td>
+  <td>0 (unset)</td>
+</tr>
+<tr>
+  <th>debug</th>
+  <td>When set to 1, will output some extra debugging information on the validated resource (such as HTTP headers) and validation process (such as parser used, parse mode etc.). In the SOAP output, this information will be given in &lt;m:debug&gt; elements.</td>
+  <td>0 (unset)</td>
+</tr>
+<tr>
+  <th>ss</th>
+  <td> as <em>show source</em>. In the web interface, triggers the display of the source
+  after the validation results. In SOAP output, does not have any impact.</td>
+  <td>0 (unset)</td>
+</tr>
+<tr>
+  <th>outline</th>
+  <td>In the web interface, when set to 1, triggers the display of the document outline 
+  after the validation results. In SOAP output, does not have any impact.</td>  
+  <td>0 (unset)</td>
+</tr>
+</table>
+<h3 id="soap12format">SOAP format description</h3>
+
+<p>When called with parameter <code>output=soap12</code>, the validator will switch
+to its SOAP 1.2 interface (experimental for now). Below is a sample response, as well as
+a description of the most important elements of the response.</p>
+
+
+
+<h4 id="soap12_sample">sample SOAP 1.2 validation response</h4>
+<p>A SOAP response for the validation of a document (invalid) will look like this:</p>
+<pre style="font-size: smaller"> 
+&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
+&lt;env:Envelope xmlns:env=&quot;http://www.w3.org/2003/05/soap-envelope&quot;&gt;
+&lt;env:Body&gt;
+&lt;<a href="#soap12_markupvalidationresponse">m:markupvalidationresponse</a>
+env:encodingStyle=&quot;http://www.w3.org/2003/05/soap-encoding&quot; 
+xmlns:m=&quot;http://www.w3.org/2005/10/markup-validator&quot;&gt;
+    &lt;<a href="#soap12_uri">m:uri</a>&gt;http://qa-dev.w3.org/wmvs/HEAD/dev/tests/xhtml1-bogus-element.html&lt;/m:uri&gt;
+    &lt;<a href="#soap12_checkedby">m:checkedby</a>&gt;http://validator.w3.org/&lt;/m:checkedby&gt;
+    &lt;<a href="#soap12_doctype">m:doctype</a>&gt;-//W3C//DTD XHTML 1.0 Transitional//EN&lt;/m:doctype&gt;
+    &lt;<a href="#soap12_charset">m:charset</a>&gt;utf-8&lt;/m:charset&gt;
+    &lt;<a href="#soap12_validity">m:validity</a>&gt;false&lt;/m:validity&gt;
+    &lt;<a href="#soap12_errors">m:errors</a>&gt;
+        &lt;<a href="#soap12_errorcount">m:errorcount</a>&gt;1&lt;/m:errorcount&gt;
+        &lt;<a href="#soap12_errorlist">m:errorlist</a>&gt;
+          
+            &lt;<a href="#soap12_error">m:error</a>&gt;
+                &lt;<a href="#soap12_line">m:line</a>&gt;13&lt;/m:line&gt;
+                &lt;<a href="#soap12_col">m:col</a>&gt;6&lt;/m:col&gt;                                           
+                &lt;<a href="#soap12_source">m:source</a>&gt;  
+                &lt;![CDATA[
+                  &amp;#60;foo&lt;strong title=&quot;Position where error was detected.&quot;&gt;&amp;#62;&lt;/strong&gt;This phrase is enclosed in a bogus FOO element.&amp;#60;/foo&amp;#62;
+                  ]]&gt;
+                &lt;/m:source&gt;                                           
+                &lt;<a href="#soap12_explanation">m:explanation</a>&gt;
+                  &lt;![CDATA[
+                    &lt;p&gt; ... &lt;/p&lt;p&gt;
+                  ]]&gt;
+                &lt;/m:explanation&gt;                                           
+                &lt;<a href="#soap12_messageid">m:messageid</a>&gt;76&lt;/m:messageid&gt;                                           
+                &lt;<a href="#soap12_message">m:message</a>&gt;element &quot;foo&quot; undefined&lt;/m:message&gt;
+            &lt;/m:error&gt;
+           
+        &lt;/m:errorlist&gt;
+    &lt;/m:errors&gt;
+    &lt;m:warnings&gt;
+        &lt;m:warningcount&gt;0&lt;/m:warningcount&gt;
+        &lt;m:warninglist&gt;
+        
+        
+        &lt;/m:warninglist&gt;
+    &lt;/m:warnings&gt;
+&lt;/m:markupvalidationresponse&gt;
+&lt;/env:Body&gt;
+&lt;/env:Envelope&gt;
+</pre>
+<h4 id="soap12response">SOAP1.2 response format reference</h4>
+
+<table class="refdoc">
+<tr><th>element</th><th>description</th></tr>
+<tr>
+  <th id="soap12_markupvalidationresponse">markupvalidationresponse</th>
+  <td>The main element of the validation response. Encloses all other information about the validation results.</td>
+</tr>
+<tr>
+  <th id="soap12_uri">uri</th>
+  <td>the address of the document validated. Will (likely?) be <kbd>upload://Form Submission</kbd>
+  if an uploaded document or fragment was validated.
+  In <a href="http://www.w3.org/WAI/ER/">EARL</a> terms, this is the <kbd>TestSubject</kbd>.
+  </td>
+</tr>
+<tr>
+  <th id="soap12_checkedby">checkedby</th>
+  <td>Location of the service which provided the validation result. 
+  In <a href="http://www.w3.org/WAI/ER/">EARL</a> terms, this is the <kbd>Assertor</kbd>.
+  </td>
+</tr>
+<tr>
+  <th id="soap12_doctype">doctype</th>
+  <td>Detected (or forced) Document Type for the validated document</td>
+</tr>
+<tr>
+  <th id="soap12_charset">charset</th>
+  <td>Detected (or forced) Character Encoding for the validated document</td>
+</tr>
+<tr>
+  <th id="soap12_validity">validity</th>
+  <td>Whether or not the document validated passed or not formal validation (true|false boolean)</td>
+</tr>
+<tr>
+  <th id="soap12_errors">errors</th>
+  <td>Encapsulates all data about errors encountered through the validation process</td>
+</tr>
+<tr>
+  <th id="soap12_errorcount">errorcount</th>
+  <td>a child of <a href="#soap12_errors">errors</a>, counts the number of errors listed</td>
+</tr>
+<tr>
+  <th id="soap12_errorlist">errorlist</th>
+  <td>a child of <a href="#soap12_errors">errors</a>, contains the list of errors (surprise!)</td>
+</tr>
+<tr>
+  <th id="soap12_error">error</th>
+  <td>a child of <a href="#soap12_errorlist">errorlist</a>, contains the information on a single 
+  validation error. </td>
+</tr>
+</table>
+<p><strong>Note</strong>: <code>warnings</code>, <code>warningcount</code>, 
+<code>warninglist</code> and <code>warning</code> are similar to, respectively,
+<code><a href="#soap12_errors">errors</a></code>, 
+<code><a href="#soap12_errorcount">errorcount</a></code>, 
+<code><a href="#soap12_errorlist">errorlist</a></code> and 
+<code><a href="#soap12_error">error</a></code>.
+</p>
+<h4 id="soap12message">SOAP1.2 atomic message (error or warning) format reference</h4>
+<p>As seen as the example above, the children of the <code><a href="#soap12_error">error</a></code>
+element, but also the <code>warning</code> element are <code>line</code>, <code>col</code> and
+<code>message</code>, defined below:</p>
+<table class="refdoc">
+<tr><th>element</th><th>description</th></tr>
+<tr>
+  <th id="soap12_line">line</th>
+  <td>Within the source code of the validated document, refers to the line where the error was detected.</td>
+</tr>
+<tr>
+  <th id="soap12_col">col</th>
+  <td>Within the source code of the validated document, refers to the column of the line where the error was detected.</td>
+</tr>
+<tr>
+  <th id="soap12_message">message</th>
+  <td>The actual error message</td>
+</tr>
+<tr>
+  <th id="soap12_messageid">messageid</th>
+  <td>The number/identifier of the error, as addressed internally by the validator</td>
+</tr>
+<tr>
+  <th id="soap12_explanation">explanation</th>
+  <td>Explanation for the error. Given as HTML fragment within CDATA block.</td>
+</tr>
+<tr>
+  <th id="soap12_source">source</th>
+  <td>Snippet of the source where the error was found. Given as HTML fragment within CDATA block.</td>
+</tr>
+</table>
+
+<h4 id="changelog">Change Log</h4>
+<p>Up to version 0.2, all changes are backward-compatible.</p>
+<dl>
+  <dt>v 0.2 (June 2007)</dt>
+  <dd><ul>
+    <li><code>debug</code> parameter now has an effect on both HTML and SOAP outputs</li>
+    <li><code>messageid</code> is now implemented</li>
+    <li>added <code>source</code> and <code>explanation</code> elements.</li>
+    </ul>
+  </dd>
+  <dt>v 0.1</dt>
+  <dd><p>Initial revision</p></dd>
+</dl>
+
+<h3 id="libs">Libraries</h3>
+<p>Building of libraries used to interact with the validator's API is <a href="http://www.w3.org/QA/2006/10/validator_api.html">encouraged</a>. If you are the 
+    maintainer of such a library, <a href="../feedback.html">contact
+us</a> and we will list it here.</p>
+<p>W3C has not reviewed, verified nor endorses these
+implementations.</p>
+
+<h4>Known libraries for the W3C Markup Validator API</h4>
+
+<ul>
+   <li><a href="http://search.cpan.org/dist/WebService-Validator-HTML-W3C/">WebService::Validator::HTML::W3C</a> in Perl, 
+       by Struan Donald.</li>
+   <li><a href="http://pear.php.net/package/Services_W3C_HTMLValidator" title="PEAR Package : Services_W3C_HTMLValidator">Services_W3C_HTMLValidator</a> in PHP, a PEAR library by Brett Bieber.</li>
+   <li><a href="http://www.clickfind.com.au/developers-directory/code.cfm">ColdFusion (MX7) class</a> by the clickfind team.</li>
+   <li><a href="http://sourceforge.net/projects/w3cmarkupvalida/">C# library</a> by María Eugenia Fernández Menéndez.</li>
+   <li><a href="http://www.rexsl.com/rexsl-w3c/">Java client</a> by the ReXSL.com team.</li>
+   <li><a href="http://pypi.python.org/pypi/py_w3c/">Python library</a> by Kazbek Byasov.</li>
+</ul>
+
+<h3 id="http_headers">Using HTTP headers to know validation results</h3>
+
+<p>Every validation result is served via the HTTP protocol, with custom headers giving a simple, quick way
+    to get validation results without having to parse the results body. This is a simple (but poorer) alternative to using 
+    the full API described above.</p>
+    
+<p>The HTTP headers for a validation results page will generally look like:</p>
+<pre>
+    HEAD 'http://validator.localhost/check?uri=http%3A%2F%2Fwww.w3.org'
+    
+    200 OK
+    [...]
+    Content-Language: en
+    Content-Type: text/html; charset=utf-8
+    X-W3C-Validator-Errors: 0
+    X-W3C-Validator-Warnings: 0
+    X-W3C-Validator-Recursion: 1
+    X-W3C-Validator-Status: Valid
+</pre>
+
+<p>The headers and their values are as follows:</p>
+<table>
+    <tr><th>Header</th><th>Value</th><th>Notes</th></tr>
+    <tr>
+        <td>X-W3C-Validator-Status</td>
+        <td><code>Valid</code> or <code>Invalid</code> if validation was performed.<br />
+          value will be <code>Abort</code> if a fatal error (decoding, 404 not found, etc) 
+          was encountered and validation could not be performed</td>
+        <td>Note: <code>Abort</code> value was added in version 0.8.0</td>
+    </tr>
+    <tr>
+        <td>X-W3C-Validator-Errors</td>
+        <td>Number of Errors found during validation. <code>0</code> if no errors found.</td>
+        <td>0 does not necessarily mean "valid" (it may mean that validation could not be performed)</td>
+    </tr>
+    <tr>
+        <td>X-W3C-Validator-Warnings</td>
+        <td>Number of Warnings found during validation. <code>0</code> if no errors found.</td>
+        <td>The warnings include validation warning, as well as pre-parsing warnings (such as character encoding mismatch, doctype override, etc.)</td>
+    </tr>
+    <tr>
+        <td>X-W3C-Validator-Recursion</td>
+        <td>Integer. Generally, <code>1</code>. More if recursively validating validation results. 
+           </td>
+        <td>    The validator will use this in conjunction with its <code>Max Recursion</code> setup to avoid
+               abusive recursion (Denial of Service attack).</td>
+    </tr>
+</table>
+</div>
+<!--#include virtual="../footer.html" -->
+  </body>
+</html>
diff --git a/htdocs/docs/users.html b/htdocs/docs/users.html
index 27c7d67..d968f91 100755
--- a/htdocs/docs/users.html
+++ b/htdocs/docs/users.html
@@ -1,146 +1,62 @@
-<!--#set var="title" value="User Documentation for The W3C Markup Validation Service"
+<!--#set var="title" value="User Documentation for The W3C Markup Validator"
 --><!--#set var="relroot" value="../"
 --><!--#include virtual="../header.html" -->
 
 <div class="doc">
 
-  <h2>User's guide for the W3C Markup Validator</h2>
-
-  <h3 id="TableOfContents">Table of contents</h3>
+  <h2>A user guide for the W3C Markup Validator</h2>
+<!--#include virtual="../htmlchecker.html" -->
+  <p>
+    If for some reason rather than using the W3C HTML Checker, you want to
+    use the W3C Markup Validator, this page provides the following information:
+  </p>
 
   <div id="toc">
     <ul>
-      <li><a href="#Quickstart">Quick Start</a></li>
-      <li><a href="#Introduction">Introduction</a></li>
-      <li><a href="#Calling">Calling/Linking to the Validator</a>
-        <ul>
-	  <li><a href="#API">Calling the validator's API</a></li>
-        </ul>
-      </li>
-      <li><a href="#Options_Params">Validator's options and output formats</a>
-        <ul>
-	  <li><a href="#Options">Options and Parameters</a></li>
-          <li><a href="#Output">Output Formats</a></li>
-          <li><a href="api.html#http_headers">Using HTTP headers to know
-              validation results</a></li>
-	  <li><a href="#deprecated_options">Deprecated options</a></li>
-        </ul>
-      </li>
-      <li><a href="#Interpret">Interpreting the results</a></li>
-      <li><a href="#Installing">Installing the Markup Validator Locally</a></li>
+      <li><a href="#Installing">Running your own instance of the W3C Markup Validator</a></li>
+      <li><a href="#Calling">Using the W3C Markup Validator API</a></li>
+      <li><a href="#Options">Controlling the behavior of the W3C Markup Validator</a></li>
+      <li><a href="api.html#http_headers">Using HTTP headers to check validation results</a></li>
     </ul>
   </div>
 
-  <div id="Quickstart">
-    <h3><a id="skip" name="skip"></a>Quick Start</h3>
-    <p>
-      Just type (or Cut&amp;Paste) the URL for the page you want to validate
-      into the text field on the form and press the "Validate this page"
-      button.
-    </p>
-    <p>
-      If you have a local file you want to validate, choose the "File Upload"
-      link from the navigation menu. Select the button labeled "Browse..." (or
-      something like that, depending on your browser) and choose the file you
-      want to upload in the usual manner for your OS.
-    </p>
-    <p>
-      Alternatively, you can also copy and paste the <em>complete</em> markup
-      (including a <a href="help.html#faq-doctype">DOCTYPE declaration</a>) for
-      a document in the "direct input" box.
-    </p>
-  </div>
-
-  <div id="Introduction" class="stb">
-    <h3>Introduction</h3>
-    <p>
-      The W3C Markup Validation Service is a web gateway to SGML and XML parsers,
-      and various other specialized validation services. The underlying
-      implementations will take your document and compare it to a set of
-      objective syntax rules for the submitted document.  For example for HTML
-      documents this set of rules is called a "DTD", a Document Type Definition.
-      This way you can be sure your HTML is really valid and not just that it
-      conforms to some random programmer's idea of "nice" HTML. Note that valid
-      HTML does not guarantee that your pages will work OK in all browsers.
-      Most of them are severely broken and you may need to find alternate ways
-      of achieving your goal.
-    </p>
-    <p>
-      When you send an URL to the W3C Markup Validation Service, it will fetch
-      that URL and feed it to the underlying parsers. If you upload a file it'll
-      get fed directly into the parsers. We then take the output produced by the
-      parsers and format it nicely as HTML and send it back to your web browser.
+  <div id="Installing" class="stb">
+    <h3>Running your own instance of the W3C Markup Validator</h3>
+    <p>To provide your own service for checking HTML documents, you probably
+      want to run an instance of the
+      <a href="https://validator.w3.org/nu/">W3C HTML Checker</a>.
+      Instructions on how to do that are available in the following guide:
     </p>
+    <ul>
+      <li><a href="http://validator.github.io/validator/">The Nu Html Checker: Usage, Options, and Web-based checking</a>
+    </ul>
     <p>
-      The W3C Markup Validation Service is not generating the error messages -
-      they are all generated by the underlying parsers - but it is appending
-      short explanations and suggested fixes for each error. We provide a
-      <a href="../feedback.html#errormsg">feedback channel</a> for users to
-      suggest better explanations and more accurate solutions.
+      To instead run an instance of the W3C Markup Validator, you can find
+      out more by reading about its
+      <a href="../source">source code and package availability</a></li>,
+      along with its
+      <a href="install.html">installation manual</a></li>
+      and
+      <a href="devel.html">an additional guide that provides more information for developers</a></li>.
     </p>
   </div>
 
   <div id="Calling" class="stb">
-    <h3>Calling/Linking to the Validator</h3>
-    <p>
-      You can link directly to the Validator home page, or you can call the
-      Validator CGI program. The home page is
-      &lt;<a href="http://validator.w3.org/">http://validator.w3.org/</a>&gt;
-      at the moment (and for the foreseeable future) and the CGI program can be
-      reached at &lt;http://validator.w3.org/check&gt;.
-    </p>
-    <p>
-      If you call the CGI program with the "uri=referer" query string parameter
-      (i.e. &lt;<a href="http://validator.w3.org/check?uri=referer">http://validator.w3.org/check?uri=referer</a>&gt;)
-      it will fetch the referring document and validate that. This means that
-      if you embed a link to that URL in your pages, following on that link
-      will send you the validation results for that page.
-    </p>
-    <p>
-      You can also link to the validation results for a specific page. You do
-      this by giving "check" an "uri" parameter pointing at the page you want
-      to validate. For example
-      &lt;<a href="http://validator.w3.org/check?uri=http%3A%2F%2Fwww.example.com%2F">http://validator.w3.org/check?uri=http%3A%2F%2Fwww.example.com%2F</a>&gt;
-      will validate the www.example.com home page.
-    </p>
-    <p>
-      The various options are listed below in the section
-      "<a href="#Options">Options and Parameters</a>" in parenthesis after the
-      long name. To add options to your links directly, append the options
-      separated by a semicolon. For example
-      &lt;<a href="http://validator.w3.org/check?uri=http%3A%2F%2Fwww.example.com%2F;ss=1;outline=1">http://validator.w3.org/check?uri=http%3A%2F%2Fwww.example.com%2F;ss=1;outline=1</a>&gt;
-      will validate the example.com home page with "Show Source", and "Outline"
-      on, but "Verbose" off.
-    </p>
-    <p>
-      All parameter values should be encoded in the UTF-8 character encoding
-      (before URI escaping them).
-    </p>
-    <p>
-      You may also see these separated by ampersands, but this usage is
-      deprecated and support may be removed at some time in the future.
-    </p>
-
-    <h4 id="API">Calling the validator's API</h4>
-    <p>
-      The Validator can also be called by programs through its
-      <a href="api.html">API</a>. See full documentation for details.
-    </p>
+    <h3>Using the W3C Markup Validator API</h3>
+<!--#include virtual="../htmlchecker_api.html" -->
   </div>
 
-  <div id="Options_Params" class="stb">
-    <h3>Options and output formats</h3>
-    <h4 id="Options">Options and Parameters</h4>
-    <p>
-      In addition to the text field where you enter an URL -- or the file
-      selection field if you are uploading files -- there are a few checkboxes
-      that alter the behaviour of the validator.</p>
+  <div id="Options" class="stb">
+    <h3>Controlling the behavior of the W3C Markup Validator</h3>
     <p>
-      These options are:
+      This section describes the behavior of each of the options exposed in the
+      W3C Markup Validator user interface, and names of the corresponding
+      query parameters (shown in parentheses) you can use with the W3C Markup
+      Validator API.
     </p>
 
     <dl>
-      <dt><a id="option-charset" name="option-charset"></a>Encoding</dt>
+      <dt><a id="option-charset" name="option-charset"></a>Encoding (<code>charset</code>)</dt>
       <dd>
         <p>This allows you to <strong>override</strong> the character encoding
 	  information about your document. You may use this option for test
@@ -149,8 +65,8 @@
           <a href="help#faq-charset">complain</a> about it and you document
           will not be valid.</p>
       </dd>
-      <dt><a id="option-fbc" name="option-fbc"></a>Use Fallback instead of
-        Override (Encoding) (<code>fbc</code>)</dt>
+      <dt><a id="option-fbc" name="option-fbc"></a>Use Fallback instead of Override
+       (<code>fbc</code>)</dt>
       <dd>
         <p>Uses the <a href="#option-charset">character encoding override</a>
           mechanism described above, but only does it as a fall back mechanism
@@ -159,7 +75,7 @@
         </p>
       </dd>
       <dt><a id="option-doctype" name="option-doctype"></a>Document Type
-        (Doctype) (<code>doctype</code>)</dt>
+       (<code>doctype</code>)</dt>
       <dd>
         <p>
           This allows you to <strong>override</strong> the DOCTYPE declaration
@@ -171,7 +87,7 @@
         </p>
       </dd>
       <dt><a id="option-fbd" name="option-fbd"></a>Use Fallback instead of
-        Override (Type) (<code>fbd</code>)</dt>
+        Override (<code>fbd</code>)</dt>
       <dd>
         <p>
           Uses the <a href="#option-doctype">Doctype override</a> mechanism
@@ -181,7 +97,7 @@
         </p>
       </dd>
 
-      <dt><a id="option-ss" name="option-ss"></a>Show source input
+      <dt><a id="option-ss" name="option-ss"></a>Show Source
         (<code>ss</code>)</dt>
       <dd>
         <p>
@@ -190,8 +106,8 @@
           what's wrong.
         </p>
       </dd>
-      <dt><a id="option-outline" name="option-outline"></a>Show an outline of
-        this document (<code>outline</code>)</dt>
+      <dt><a id="option-outline" name="option-outline"></a>Show Outline
+        (<code>outline</code>)</dt>
       <dd>
         <p>
           Will generate an outline of your document from the H1 - H6 elements.
@@ -210,7 +126,7 @@
         (<code>No200</code>)</dt>
       <dd>
         <p>
-          The Markup Validator will usually tell you if the page you tried to
+          The W3C Markup Validator will usually tell you if the page you tried to
           validate could not be retrieved (for example, if the server gave a
           "404 not found" message. In some circumstances you may want to be
           able to validate the error page sent by the server. This is the
@@ -268,7 +184,7 @@
           This option (<em>experimental, as of 0.8.3</em>) makes the validator
           send an <code>Accept-Charset</code> HTTP header, specifying the
           character encodings which it will accept from server. This option is
-          mainly used to interface the Markup Validator for
+          mainly used to interface the W3C Markup Validator for
           <a href="http://www.w3.org/TR/mobileOK-basic10-tests/#http_request">Mobile
             Web Best Practices</a> checking.</p>
       </dd>
@@ -285,99 +201,8 @@
             Web Best Practices</a> spec.</p>
       </dd>
     </dl>
-
-    <h4 id="Output">Output Options</h4>
-    <p>
-      In addition to the HTML output intended for human consumption in a
-      browser, the Validator has some experimental features to generate machine
-      parseable output in a few different forms. To enable these output
-      options, append "<code>;output=&lt;option&gt;</code>" to the URL of the
-      validation results (an interface for these options will be provided when
-      they exit the beta stage).
-    </p>
-    <dl>
-      <dt id="output-soap12">Web Service API (<code>output=soap12</code>)</dt>
-      <dd>
-        Using the SOAP1.2 language over HTTP, this defines a web service with
-        an output similar to the API for the W3C CSS validator and Feed
-        Validator. The <a href="api">Full documentation</a> for this API is
-        available. This API is <em>still under development</em>, and subject to
-        change.
-      </dd>
-      <dt id="output-json">JSON (<code>output=json</code>)</dt>
-      <dd>
-        Produces output using a JSON (JavaScript Object Notation) formatting
-        equivalent to the
-        <a href="http://wiki.whatwg.org/wiki/Validator.nu_JSON_Output">JSON
-          output for validator.nu</a>.
-      </dd>
-      <dt id="output-earl">EARL/RDF (<code>output=earl</code>)</dt>
-      <dd>
-        Produces output in the
-        <a href="http://www.w3.org/TR/EARL10-Schema/">EARL 1.0 RDF</a> syntax.
-        <em>This output may change or be removed in the future</em>.
-      </dd>
-      <dt id="output-n3">Notation3 (<code>output=n3</code>)</dt>
-      <dd>
-        Produces output in the Notation3 RDF syntax.
-        <em>This output is currently outdated and may change or be removed
-          in the future</em>.
-      </dd>
-    </dl>
-
-    <h4 id="deprecated_options">Deprecated options</h4>
-    <p>
-      A number of options once available  have been deprecated and are not
-      available any more. These include the <em>Show parse tree</em> and
-      <em>exclude attributes from the parse tree</em>, as well as
-      <em>Show ESIS</em> and <em>Show raw errors</em> options, and the
-      <code>xml</code> output option.
-    </p>
-  </div>
-
-
-  <div id="Interpret" class="stb">
-    <h3>Interpreting the results</h3>
-    <p>
-      In spite of our efforts,  interpreting the Markup Validator's error
-      messages isn't quite what you'd call easy. The error messages are
-      generated in the context of a full SGML environment which demands a
-      somewhat higher level of technical detail than your average HTML
-      document. We have set up a page listing <a href="errors.html">errors and
-        their explanations</a>, which should help you find out what meaning
-      lies behind the cryptic messages, and fix your markup.
-    </p>
-    <p>
-      We're working on ways to make the error messages more friendly, but for
-      now, if the <a href="errors.html">errors explanation page</a> doesn't
-      work for you, or if you wish to suggest a better explanation, our
-      <a href="../feedback.html#errormsg">feedback page</a> will help you send
-      your ideas to our public mailing list. This will have the added benefit
-      of letting us know which error messages are causing the most trouble so
-      we can fix those first. Please be as specific as possible and include the
-      <em>exact</em> error message and, preferably, a URL we can validate to
-      see for ourselves.
-    </p>
-  </div>
-
-  <div id="Installing" class="stb">
-    <h3>Installing a local Validator</h3>
-    <p>
-      You can download the Validator to run on your own system. For Web design
-      departments or agencies it can be a very good idea, saving time and
-      allowing you to not send documents under work or confidential pages over
-      the wire, but it is a complex operation, and is not recommended for
-      average users, for which the free online service at W3C should suffice.
-    </p>
-    <p>
-      We have created a simple <a href="install.html">Installation manual</a>,
-      which, along with the <a href="devel.html">Developer's information</a>,
-      should help you install a local instance of the Markup Validator in your
-      own network easily.
-    </p>
   </div>
 </div>
-
 <!--#include virtual="../footer.html" -->
   </body>
 </html>
diff --git a/htdocs/htmlchecker.html b/htdocs/htmlchecker.html
new file mode 100644
index 0000000..37d1e9f
--- /dev/null
+++ b/htdocs/htmlchecker.html
@@ -0,0 +1,16 @@
+  <p>
+    The W3C Markup Validator provides Perl/CGI/SGML/XML/DTD-based
+    validation of a variety of document types.
+    SGML and DTDs are older technologies that never found wide use on
+    the Web, so for checking of HTML documents using modern
+    technologies, you probably want to instead use the
+    <a href="https://validator.w3.org/nu/">W3C HTML Checker</a>.
+    To do that,
+  </p>
+  <img src="../images/HTML5_Badge_32.png" alt="HTML5" class="html5_logo_32">
+  <ul>
+    <li>Download the
+      <a href="https://github.com/validator/validator/releases/latest">latest release version</a>.</li>
+    <li>Read the
+      <a href="http://validator.github.io/validator/">usage guide</a>.</li>
+  </ul>
diff --git a/htdocs/htmlchecker_api.html b/htdocs/htmlchecker_api.html
new file mode 100644
index 0000000..9abe147
--- /dev/null
+++ b/htdocs/htmlchecker_api.html
@@ -0,0 +1,39 @@
+    <p>
+      For programmatic checking of modern HTML documents, you probably want
+      to instead use the API provided by the
+      <a href="https://validator.w3.org/nu/">W3C HTML Checker</a>. To do
+      that, call
+      <a href="https://validator.w3.org/nu/">https://validator.w3.org/nu/</a>
+      or the URL for another instance of the W3C HTML Checker, and consult
+      the following documentation:
+    </p>
+
+    <img src="/images/HTML5_Badge_128.png" alt="HTML5" class="html5_logo_128">
+    <ul>
+      <li><a href="https://github.com/validator/validator/wiki/Service:-Input:-GET">W3C HTML Checker GET interface</a></li>
+      <li><a href="https://github.com/validator/validator/wiki/Service:-Input:-POST-body">W3C HTML Checker POST interface</a></li>
+      <li><a href="https://github.com/validator/validator/wiki/Service:-Common-parameters">W3C HTML Checker parameters</a></li>
+      <li><a href="https://github.com/validator/validator/wiki/Output%3A-JSON">W3C HTML Checker out=json format</a></li>
+      <li><a href="https://github.com/validator/validator/wiki/Output:-XML">W3C HTML Checker out=xml format</a></li>
+      <li><a href="https://github.com/validator/validator/wiki/Output:-GNU">W3C HTML Checker out=gnu format</a></li>
+    </ul>
+    <p>
+      If for some reason rather than using the W3C HTML Checker API, you
+      want to use the W3C Markup Validator API, the simplest way to
+      do that is just to call <code>https://validator.w3.org/check?</code>
+      with a query string that includes the "<code>uri</code>" parameter
+      and the URL for the document to check, and with the
+      "<code>output=json</code>" parameter appended; for example:
+      <a href="https://validator.w3.org/check?uri=https://example.com/&amp;output=json">https://validator.w3.org/check?uri=https://example.com/&amp;output=json</a>.
+      The W3C Markup Validator will return the results as JSON, in
+      <a href="https://github.com/validator/validator/wiki/Output:-JSON">the same JSON format used by the W3C HTML Checker</a>.
+      You can specify other W3C Markup Validator options as additional query
+      parameters. The names of the query parameters are listed in the section
+      <a href="/docs/users.html#Options">Controlling the behavior of the W3C Markup Validator</a>,
+      in parentheses after the name of each option described.
+      All values for query parameters should be encoded in UTF-8 (before
+      percent-encoding them).
+      Separate the query parameters with either "<code>;</code>"
+      (semicolon) characters or with "<code>&amp;</code>" (ampersand)
+      characters.
+    </p>
diff --git a/htdocs/images/HTML5_Badge_128.png b/htdocs/images/HTML5_Badge_128.png
new file mode 100644
index 0000000..6b0f0be
--- /dev/null
+++ b/htdocs/images/HTML5_Badge_128.png
diff --git a/htdocs/images/HTML5_Badge_32.png b/htdocs/images/HTML5_Badge_32.png
new file mode 100644
index 0000000..42e1091
--- /dev/null
+++ b/htdocs/images/HTML5_Badge_32.png
diff --git a/htdocs/source/index.html b/htdocs/source/index.html
index a10007b..8d05a27 100755
--- a/htdocs/source/index.html
+++ b/htdocs/source/index.html
@@ -2,54 +2,34 @@
 --><!--#set var="relroot" value="../"
 --><!--#include virtual="../header.html" -->
 <div class="doc">
-  <h2>Source code availability<br />for the W3C Markup Validator</h2>
-  <h3 id="TableOfContents">Table of Contents</h3>
+  <h2>Source code and package availability<br />for the W3C Markup Validator</h2>
+<!--#include virtual="../htmlchecker.html" -->
+  <p>
+    If for some reason you'd rather run a service based on the same source as
+    the W3C Markup Validator, this page provides the following information:
+  </p>
 
   <div id="toc">
     <ul>
-      <li><a href="#getting">Retrieving and browsing the Code</a>
-       <ul>	
-	<li><a href="#browse">Browsing the code</a></li>
-	<li><a href="#rpm">Fedora/Red Hat RPM package</a></li>
+      <li><a href="#packages">Installing from packages</a>
+        <ul>
+          <li><a href="#rpm">Fedora/Red Hat RPM package</a></li>
           <li><a href="#suse">openSUSE/SUSE Linux RPM package</a></li>
-	<li><a href="#deb">Debian GNU/Linux package</a></li>
-	<li><a href="#mac">Mac OS X Application</a></li>
-	<li><a href="#gh">Github repository</a></li>
-       </ul>
+          <li><a href="#deb">Debian GNU/Linux package</a></li>
+          <li><a href="#mac">Mac OS X Application</a></li>
+        </ul>
       </li>
-      <li><a href="#using">Using the code</a></li>
+      <li><a href="#getting">Getting the source</a></li>
     </ul>
   </div>
 
-  <h3><a name="getting" id="getting"></a>Retrieving and browsing the Code</h3>
-
-    <p><a id="skip" name="skip"></a>
-    The source code for the <a href="../"><acronym title="World Wide Web Consortium">W3C</acronym>
-    Markup Validation Service</a> is available under the terms of the
-    <a href="http://www.w3.org/Consortium/Legal/copyright-software"><acronym title="World Wide Web Consortium">W3C</acronym>
-	Software License</a>. 
-    </p>
-
-          <h4><a id="browse" name="browse"></a>Browsing the code</h4>
+  <h3><a id="packages"></a>Installing from packages</h3>
+    <p>Rather than trying to install and run an instance of the W3C from
+      the sources, it's much easier to install one of a variety of
+      pre-built packages. The sections below provide information about
+      packages available for various systems.
 
-  <p>
-    If you just want to glance at the code, or see its revision
-    history, you can
-    <a href="https://github.com/w3c/markup-validator/">browse it
-    directly in Github</a>.
-  </p>
-  <p>
-    The most interesting files are currently
-    <a href="https://github.com/w3c/markup-validator/blob/master/httpd/cgi-bin/check">a
-    CGI script called "check"</a> that does pretty much everything,
-    and possibly also <a
-    href="https://github.com/w3c/markup-validator/blob/master/httpd/conf/httpd.conf">the
-    httpd.conf configuration file snippet for Apache</a>.
-    Select the topmost revision numbers on these
-    pages to see the most recent revision of each file.
-    </p>
-  
-        <h4><a id="rpm" name="rpm"></a>Fedora/Red Hat RPM package</h4>
+        <h4><a id="rpm"></a>Fedora/Red Hat RPM package</h4>
 
           <p>
             Fedora RPM packages of the validator are included in Fedora.
@@ -64,7 +44,7 @@
             <a href="http://fedoraproject.org/wiki/EPEL">EPEL</a>.
           </p>
   
-  <h4><a id="suse" name="suse"></a>openSUSE/SUSE Linux RPM package</h4>
+  <h4><a id="suse"></a>openSUSE/SUSE Linux RPM package</h4>
 
           <p>
     openSUSE/SUSE Linux RPM packages of the validator are available,
@@ -84,7 +64,7 @@
     &lt;<a href="http://software.opensuse.org/package/w3c-markup-validator">http://software.opensuse.org/package/w3c-markup-validator</a>&gt;
           </p>
   
-        <h4><a name="deb" id="deb"></a>Debian GNU/Linux package</h4>
+        <h4><a id="deb"></a>Debian GNU/Linux package</h4>
 
           <p>
             <a href="https://packages.debian.org/search?keywords=w3c-markup-validator">A Debian package is available</a>, courtesy of Fr&eacute;d&eacute;ric
@@ -102,23 +82,34 @@
           The Validator is also packaged as a standalone Mac OS X Application,
           called <a href="http://habilis.net/validator-sac/">Validator <abbr title="[Stand Alone Complex]">S.A.C.</abbr></a>, courtesy of <a href="http://habilis.net/chuck/" title="Chuck Houpt's Home Page">Chuck Houpt</a>.</p>
 
-        <h4><a id="gh" name="gh"></a>Github repository</h4>
+  <h3><a id="getting"></a>Getting the source</h3>
 
-	<p>
-            For instructions on how to retrieve the code using Github, 
-            see our <a href="https://github.com/w3c/markup-validator/">web-based
-              interface to the repository</a>.
-          </p>
-            
-  <h3><a id="using" name="using"></a>Using the code</h3>
+    <p><a id="skip"></a>
+    The source code for the <a href="../"><acronym title="World Wide Web Consortium">W3C</acronym>
+    Markup Validation Service</a> is available under the terms of the
+    <a href="http://www.w3.org/Consortium/Legal/copyright-software"><acronym title="World Wide Web Consortium">W3C</acronym>
+	Software License</a>. 
+    </p>
 
-     <p>
-      The purpose of making the source code available is partly to allow
-      others to set up mirrors of the service (either publicly or within
-      an intranet behind a firewall), but also to allow us to collaborate
-      on making the service better! If you are interested in helping with 
-      the development, we suggest you  first <a href="../docs/install.html">install</a>
-      the code and <a href="../docs/devel.html">read our instructions for developers</a>.
+  <p>
+    If you just want to glance at the code, or see its revision
+    history, you can
+    <a href="https://github.com/w3c/markup-validator/">browse it
+    directly in Github</a>.
+  </p>
+  <p>
+    The most interesting files are currently
+    <a href="https://github.com/w3c/markup-validator/blob/master/httpd/cgi-bin/check">a
+    CGI script called "check"</a> that does pretty much everything,
+    and possibly also <a
+    href="https://github.com/w3c/markup-validator/blob/master/httpd/conf/httpd.conf">the
+    httpd.conf configuration file snippet for Apache</a>.
+    Select the topmost revision numbers on these
+    pages to see the most recent revision of each file.
+  </p>
+  <p>To actually install and run an instance of the W3C Markup Validator from
+    the sources, see the
+    <a href="../docs/install.html">installation manual</a>.
   </p>
 
 </div>
diff --git a/htdocs/style/base.css b/htdocs/style/base.css
index e272255..abf80fa 100644
--- a/htdocs/style/base.css
+++ b/htdocs/style/base.css
@@ -574,11 +574,8 @@ div.doc ul li {
 }
 
 /* documentation - table of contents */
-#toc { /* making the toc a bit more compact and standing out */
-    font-size: .85em;
-    font-weight: bold;
-    margin-bottom: 2em;
-    margin-left: 3em;
+#toc {
+    margin-left: 40px;
 }
 
 div.doc div#toc ol, div.doc ol {
@@ -741,6 +738,20 @@ div.intro p { margin-bottom: .5em;}
     vertical-align: middle;
 }
 
+.html5_logo_32 {
+    float: left;
+    padding-top: 8px;
+    padding-right: 20px;
+    padding-left: 28px;
+}
+
+.html5_logo_128 {
+    float: left;
+    padding-top: 9px;
+    padding-right: 20px;
+    padding-left: 18px;
+}
+
 /* donation and sponsorship program */
 
 #w3c-include {}