path: root/htdocs/docs/users.html

<!--#set var="revision" value="\$Id: users.html,v 1.32 2008-07-22 13:04:52 ot Exp $"
--><!--#set var="date" value="\$Date: 2008-07-22 13:04:52 $"
--><!--#set var="title" value="User Documentation for The W3C Markup Validation Service"
--><!--#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>

    <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>
	</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 a well known SGML
        parser called SP. SP will take your HTML and compare it to a set of
        objective syntax rules 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 SGML parser. If you upload a file it'll get
        fed directly into the SGML parser. We then take the output from the
        SGML parser and format it nicely as HTML and send it back to your web
        browser. 
      </p>
      <p>
        The W3C Markup Validation Service is not generating the error messages 
        - they are all generated by the underlying Parser -
        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.
      </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;<a
        href="http://validator.w3.org/check">http://validator.w3.org/check</a>&gt;.
      </p>
      <p>
        If you call the CGI program with extra path info matching "/referer"
        (i.e. &lt;<a href="http://validator.w3.org/check/referer">http://validator.w3.org/check/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://www.example.com/">http://validator.w3.org/check?uri=http://www.example.com/</a>&gt;
        will validate the www.example.com home page.
      </p>
      <p>
        The various options are listed above in the section
        "<a href="#Options">The Options</a>" in parenthesis after the long
        name. To add options to your links directly, append the options
        separated by a semi-colon. For example
        &lt;<a href="http://validator.w3.org/check?uri=http://www.example.com/;ss=1;outline=1;sp=1">http://validator.w3.org/check?uri=http://www.example.com/;ss=1;outline=1;sp=1</a>&gt;
        will validate the example.com home page with "Show Source", "Outline" and
        "Show Parse Tree" on, but "Exclude Attributes" off.
      </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>
    </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>
      <p>
	 These options are:
      </p>

      <dl>
	<dt><a id="option-charset" name="option-charset"></a>Encoding</dt>
	<dd>
	  <p>This allows you to <strong>override</strong> the character encoding
	  information about your document. You may use this option for test 
	  purposes, but you will eventually have to serve your document with the
	  correct character encoding, or the validator will <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>
	<dd>
	  <p>Uses the <a href="#option-charset">character encoding override</a> mechanism
	  described above, but only does it as a fall back mechanism if the actual document
	  is not served with character encoding information. Think of this as a gentler 
	  override mechanism.</p>
	</dd>
	<dt><a id="option-doctype" name="option-doctype"></a>Document Type (Doctype)</dt>
	<dd>
	  <p>This allows you to <strong>override</strong> the DOCTYPE declaration for you
	  document. You may use this option for test 
          purposes, but you will eventually have to serve your document with the
          correct DOCTYPE declaration, or the validator will <a href="help#faq-doctype">complain</a>
          about it and you document will not be valid.</p>
	</dd>
	<dt><a id="option-fbd" name="option-fbd"></a>Use Fallback instead of Override (Type) (<code>fbd</code>)</dt>
        <dd>
          <p>Uses the <a href="#option-doctype">Doctype override</a> mechanism
          described above, but only does it as a fall back mechanism if the actual document
          does not have a Doctype declaration. Think of this as a gentler override mechanism.</p>
        </dd>


        <dt><a id="option-ss" name="option-ss"></a>Show source input (<code>ss</code>)</dt>
        <dd>
          <p>Displays the HTML source of the document you validated and links
          error messages directly to lines in this output. Makes it easy to
          see what's wrong.</p>
        </dd>
        <dt><a id="option-outline" name="option-outline"></a>Show an outline of this document (<code>outline</code>)</dt>
        <dd>
          <p>Will generate an outline of your document from the H1 - H6 elements.
          For a properly formed document, this will be a nicely nested tree
          structure. The visualization of your document's structure makes it
          easier to see where you've skipped a heading.</p>
          <p>If you want to examine the semantic structure of your documents, beyond the outline, try the
            <a href="http://www.w3.org/2003/12/semantic-extractor.html">Semantic data extractor</a>.
          </p>
          
        </dd>

	<dt><a id="option-no200" name="option-no200"></a>Validate error pages (<code>no200</code>)</dt>
	<dd>
	  <p>The 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 option to use then.</p>
	</dd>
	<dt><a id="option-verbose" name="option-verbose"></a>Verbose Output (<code>verbose</code>)</dt>
	<dd>
	  <p>This option triggers verbose output. Verbose output adds more explanations 
          and suggestions to the validation results, and gives more information on the 
          resource validated. This makes it a useful option if you prefer to be given 
          as much help as possible; if you prefer more concise reports, leave this option
          unset.</p>
	</dd>
	<dt id="option-accept">For Content-Negotiated resources, set a specific <code>Accept</code> Header (<code>accept</code>)</dt>
	<dd>
	  <p>This option (<em>experimental, as of 0.8.2</em>) is useful if your Web server 
	  is set up to use format negotiation, serving different
	  content based on the preferred/accepted media types of the user-agent. The validator
	  can then emulate different HTTP <code>Accept</code> behaviors.</p>
	  <p>For example, append "<code>accept=application%2Fxhtml%2Bxml%2C*</code>" and the validator
	    will send the HTTP Header "<code>Accept: application/xhtml+xml,*</code>".</p>
	</dd>
	<dt id="option-accept-language">For Content-Negotiated resources, set a specific <code>Accept-Language</code> Header (<code>accept-language</code>)</dt>
	<dd>
	  <p>This option (<em>experimental, as of 0.8.2</em>) is useful if your Web server 
	  is set up to use language negotiation, serving content in different languages
	   based on the preferred/accepted language setup of the user-agent. The validator
	  can then emulate different HTTP <code>Accept-Language</code> behaviors.</p>
	  <p>For example, append "<code>accept-language=ja%2Cfr</code>" and the validator
	    will send the HTTP Header "<code>Accept-Language: ja,fr</code>".</p>
	</dd>
	<dt id="option-accept-charset">Set a specific <code>Accept-Charset</code> Header (<code>accept-charset</code>)</dt>
	<dd>
	  <p>This option (<em>experimental, as of 0.8.3</em>) makes the validator send 
	  a <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 <a href="http://www.w3.org/TR/mobileOK-basic10-tests/#http_request">Mobile Web Best Practices</a>
	  checking.</p>
	</dd>
	<dt id="option-user-agent">Set a specific <code>User-Agent</code> Header (<code>user-agent</code>)</dt>
	<dd>
	  <p>This option (<em>experimental, as of 0.8.3</em>) makes the validator send 
	  a custom <code>User-Agent</code> HTTP header instead of the usual <code>W3C_Validator/xx.xxxx</code>.
	  If the value of this parameter is <code>mobileok</code>, the validator will output a <code>User-Agent</code>
	  string as defined by the <a href="http://www.w3.org/TR/mobileOK-basic10-tests/#http_request">Mobile 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</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>. This API is <em>still under development</em>,
  	  and subject to change.</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>. <em>This output may change or be removed in the future</em>.</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>. <em>This output may change or be removed in the future</em>.</dd>
	  <dt id="output-json">JSON (<em>NEW</em> in version 0.8.3)</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-xml">XML</dt>
  	  <dd>This output option has been deprecated, and will be removed from subsequent versions of the validator. Can be called by using parameter <code>output=json</code>.</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.
        This includes 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>.
        </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 explanation</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, an 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>