porting all documentation and style (htdocs/...) changes from 0.7.3 to HEAD

3 files changed, 39 insertions, 125 deletions

diff --git a/htdocs/docs/api.html b/htdocs/docs/api.html
index ed48ee4..0176a78 100755
--- a/htdocs/docs/api.html
+++ b/htdocs/docs/api.html
@@ -1,5 +1,5 @@
-<!--#set var="revision" value="\$Id: api.html,v 1.3 2006-02-23 15:45:05 ot Exp $"
---><!--#set var="date" value="\$Date: 2006-02-23 15:45:05 $"
+<!--#set var="revision" value="\$Id: api.html,v 1.4 2006-10-24 06:43:24 ot Exp $"
+--><!--#set var="date" value="\$Date: 2006-10-24 06:43:24 $"
 --><!--#set var="title" value="Documentation of the Programmatic Interface (API) to The W3C Markup Validation Service"
 --><!--#set var="relroot" value="../"
 --><!--#include virtual="../header.html" -->
@@ -8,6 +8,13 @@
 <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. </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">
@@ -31,7 +38,7 @@ SOAP 1.2 validation interface documentation</h2>
 <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>
+(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> 
@@ -208,9 +215,9 @@ xmlns:m=&quot;http://www.w3.org/2005/10/markup-validator&quot;&gt;
 <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>.
+<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>
diff --git a/htdocs/docs/index.html b/htdocs/docs/index.html
index 22e746f..6a75d95 100755
--- a/htdocs/docs/index.html
+++ b/htdocs/docs/index.html
@@ -1,5 +1,5 @@
-<!--#set var="revision" value="\$Id: index.html,v 1.13 2005-07-12 06:07:09 ot Exp $"
---><!--#set var="date" value="\$Date: 2005-07-12 06:07:09 $"
+<!--#set var="revision" value="\$Id: index.html,v 1.14 2006-10-24 06:43:24 ot Exp $"
+--><!--#set var="date" value="\$Date: 2006-10-24 06:43:24 $"
 --><!--#set var="title" value="Documentation Index for The W3C Markup Validation Service"
 --><!--#set var="relroot" value="../"
 --><!--#include virtual="../header.html" -->
@@ -49,20 +49,22 @@
 
 <h3 id="docs_experts">Experts only</h3>
 <dl>
-      <dt id="doc_sgml"><a href="sgml.html">SGML (basics) and the Markup Validator</a></dt>
-      <dd>
-        <p>
-          A quick introduction to SGML concepts as they apply to the
-          Validator with links to further information.
-        </p>
-      </dd>
       <dt id="doc_source"><a href="../source/">Download / Source</a></dt>
       <dd><p>Information on source code availability and download instructions for the Markup Validator.</p></dd>
       <dt id="doc_install"><a href="install.html">Installation Guide</a></dt>
       <dd><p>Step-by step guide for the installation of the Markup Validator
       on <em>your</em> server.</p></dd>
+	  <dt id="api"><a href="api.html">Markup Validator Web Service API</a></dt>
+	  <dd><p>Use the validator from your applications with the <em>experimental</em> Markup Validator Web service, and its open API.</p></dd>
       <dt id="doc_devel"><a href="devel.html">Developer Information</a></dt>
       <dd><p>Information for programmers wanting to play with the validator's code, and/or contribute to its development.</p></dd>
+      <dt id="doc_sgml"><a href="sgml.html">SGML, Validation and the Markup Validator</a></dt>
+      <dd>
+        <p>
+          An introduction to concepts of SGML, DTDs and formal validation, and how they apply to the
+          Validator, with links to further information.
+        </p>
+      </dd>
     </dl>
 
 </div>
diff --git a/htdocs/docs/users.html b/htdocs/docs/users.html
index eba24f1..e4ce89c 100755
--- a/htdocs/docs/users.html
+++ b/htdocs/docs/users.html
@@ -1,5 +1,5 @@
-<!--#set var="revision" value="\$Id: users.html,v 1.23 2006-03-31 05:48:02 ot Exp $"
---><!--#set var="date" value="\$Date: 2006-03-31 05:48:02 $"
+<!--#set var="revision" value="\$Id: users.html,v 1.24 2006-10-24 06:43:24 ot Exp $"
+--><!--#set var="date" value="\$Date: 2006-10-24 06:43:24 $"
 --><!--#set var="title" value="User Documentation for The W3C Markup Validation Service"
 --><!--#set var="relroot" value="../"
 --><!--#include virtual="../header.html" -->
@@ -230,117 +230,22 @@
         </p>
         <p class="shout" id="api-warning">
 	  <strong>These options are experimental!</strong>
-	  The API and output format is subject to change without notice and
-	  may well be removed or disabled at any time. They are provided now
-	  to garner public feedback to determine how best to support this
-	  functionality in the future. One particularly likely option being
-	  considered is removing these features altogether in favor of a
-	  full-blown SOAP interface. <em>You have been warned!</em>
+	  The API and output formats are still subject to change without notice and
+	  may well be removed or disabled at any time. <em>You have been warned!</em>
 	</p>
         <dl>
-          <dt id="output-earl">EARL/RDF (<code>earl</code>)</dt>
-          <dd>Produces output in the EARL RDF syntax.</dd>
-	  <dt id="output-n3">Notation3 (<code>n3</code>)</dt>
-	  <dd>Produces output in the Notation3 RDF syntax</dd>
+      <dt id="output-soap12">Web Service API (<em>NEW</em> in version 0.7.3)</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.
+	  Can be called by using parameter <code>output=soap12</code></dd>
+      <dt id="output-earl">EARL/RDF</dt>
+      <dd>Produces output in the EARL RDF syntax.
+	  		Can be called by using parameter <code>output=earl</code>.</dd>
+	  <dt id="output-n3">Notation3 </dt>
+	  <dd>Produces output in the Notation3 RDF syntax. 
+		Can be called by using parameter <code>output=n3</code>.</dd>
 	  <dt id="output-xml">XML (<code>xml</code>)</dt>
-	  <dd>
-            <p>Produces output in a homegrown XML format (yes, we know...).</p>
-            <p>The DTD for this format is as follows:</p>
-	    <pre>
-	      <code>
-&lt;!DOCTYPE result [
-  &lt;!ELEMENT result (meta, warnings?, messages?)&gt;
-  &lt;!ATTLIST result
-    version CDATA #FIXED '0.9'
-  &gt;
-
-  &lt;!ELEMENT meta (uri, modified, server, size, encoding, doctype)&gt;
-  &lt;!ELEMENT uri      (#PCDATA)&gt;
-  &lt;!ELEMENT modified (#PCDATA)&gt;
-  &lt;!ELEMENT server   (#PCDATA)&gt;
-  &lt;!ELEMENT size     (#PCDATA)&gt;
-  &lt;!ELEMENT encoding (#PCDATA)&gt;
-  &lt;!ELEMENT doctype  (#PCDATA)&gt;
-
-  &lt;!ELEMENT warnings (warning)+&gt;
-  &lt;!ELEMENT warning  (#PCDATA)&gt;
-
-  &lt;!ELEMENT messages (msg)*&gt;
-  &lt;!ELEMENT msg      (#PCDATA)&gt;
-  &lt;!ATTLIST msg
-    line   CDATA #IMPLIED
-    col    CDATA #IMPLIED
-    offset CDATA #IMPLIED
-  &gt;
-]&gt;
-              </code>
-            </pre>
-            <p>
-	      Each element except the containers (<code>result</code>,
-              <code>meta</code>, <code>warnings</code>, <code>messages</code>)
-              and the free-form text fields (<code>warning</code>,
-              <code>msg</code>) will take a single value of a specific type.
-            </p>
-            <p>
-              The base document element is <code>result</code>. The only
-              elements allowed to be directly contained at the first level are
-              <code>meta</code>, <code>warnings</code>, and
-              <code>messages</code>. <code>warnings</code>, and
-              <code>messages</code> may be omitted if empty, and no first-level
-              elements may appear more then once.
-            </p>
-            <div id="dtd-meta">
-	      <h5>The <code>meta</code> element</h5>
-	      <p>
-                The <code>meta</code> element contains various metadata about
-	        about the Validated document. It contains further elements
-	        describing each value.
-	      </p>
-	      <dl>
-	        <dt><code>uri</code></dt>
-	        <dd>The URL of the document validated.</dd>
-	        <dt><code>modified</code></dt>
-	        <dd>The Last-Modified header field of the document as free-form text.</dd>
-	        <dt><code>server</code></dt>
-	        <dd>The Server header field of the document as free-form text.</dd>
-	        <dt><code>size</code></dt>
-	        <dd>The size in bytes of the document.</dd>
-	        <dt><code>encoding</code></dt>
-	        <dd>The Character Encoding used for Validation.</dd>
-	        <dt><code>doctype</code></dt>
-	        <dd>A text string describing the DOCTYPE used for Validation.</dd>
-	      </dl>
-	      <p>
-	        Currently, the type of these fields is free-form text, but it
-                is intended that a future revision will switch to less opaque
-                data types so these values can be reliably machine-parsed.
-              </p>
-            </div>
-	    <div id="dtd-warnings">
-	      <h5>The <code>warnings</code> element</h5>
-	      <p>
-	        The <code>warnings</code> element can contain only one sub-element;
-	        the <code>warning</code> element. Multiple <code>warning</code>
-	        elements may appear and each one contains free-form text
-                corresponding to a warning of the type found in the "Warnings"
-	        section of the HTML output (e.g. "DOCTYPE override in effect!").
-	      </p>
-	    </div>
-	    <div id="dtd-messages">
-	      <h5>The <code>messages</code> element.</h5>
-	      <p>
-	        The <code>messages</code> element can contain only one sub-element;
-	        the <code>msg</code> element. Multiple <code>msg</code> elements
-	        may appear and each contains free-form text representing one
-	        detected error. The <code>msg</code> element has three attributes;
-	        <code>line</code>, <code>col</code>, <code>offset</code>.
-	        These contain a number representing the line and column on which
-	        the error was detected, and the offset in characters from the
-	        beginning of the document (as opposed to <code>col</code> which
-	        can be said to be the offset from the beginning of the line).
-	      </p>
-	    </div>
-	  </dd>
+	  <dd>This output option has been deprecated, and will be removed from subsequent versions of the validator. </dd>
 	</dl>
       </div>