path: root/htdocs/docs/users.html

<!--#set var="revision" value="\$Id: users.html,v 1.12 2002-11-07 05:02:58 ot Exp $"
--><!--#set var="date" value="\$Date: 2002-11-07 05:02:58 $"
--><!--#set var="title" value="User Documentation for The W3C MarkUp Validation Service"
--><!--#set var="relroot" value="../"
--><!--#include virtual="../header.html" -->
    <div id="toc">
      <h2 id="TableOfContents">Table of contents</h2>
	<ul>
	<li><a href="#Quickstart">Quick Start</a></li>
	<li><a href="#Introduction">Introduction</a></li>
	<li><a href="#Options">Validator's options</a></li>
	<li><a href="#Calling">Calling/Linking to the Validator</a></li>
	<li><a href="#Interpret">Interpreting the results</a></li>
	<li><a href="#CommaTools">Comma Tools</a></li>
	<li><a href="#Installing">Installing the Markup Validator Locally</a></li>
	</ul>
    </div>

    <div id="Quickstart">
      <h2 id="skip">Quick Start</h2>
      <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>
    </div>

    <div id="Introduction" class="stb">
      <h2>Introduction</h2>
      <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. The W3C MarkUp Validation Service isn't generating any of the
        error messages; they are all generated by the underlying SGML Parser
        which is checking your HTML against the actual standard for the version
        of HTML you are using.
      </p>
    </div>

    <div id="Options" class="stb">
      <h2>The Options</h2>
      <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. The options are:
      </p>

      <dl>
        <dt>Show source input (<code>ss</code>)</dt>
        <dd>
          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.
        </dd>
        <dt>Show an outline of this document (<code>outline</code>)</dt>
        <dd>
          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.
        </dd>
        <dt>Show parse tree (<code>sp</code>)</dt>
        <dd>
          Shows you exactly how the SGML Parser read your document. Probably
          best used only by advanced users as it deals with low-level SGML
          constructs.
        </dd>
        <dt>exclude attributes from the parse tree (<code>noatt</code>)</dt>
        <dd>Suppress attributes from the parse tree to make it more readable.</dd>
      </dl>
    </div>

    <div id="Calling" class="stb">
      <h2>Calling/Linking to the Validator</h2>
      <p>
        You can link directly to the Validator home page, or you can call the
        Validator CGI program. The home page is &lt;URL:<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;URL:<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;URL:<a href="http://validator.w3.org/check/referer">http://validator.w3.org/check/referer</a>&gt;)
        it will fetch the refering 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;URL:<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;URL:<a href="http://validator.w3.org/check?uri=http://www.example.com/;ss;outline;sp">http://validator.w3.org/check?uri=http://www.example.com/;ss;outline;sp</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 and equal-signs, but
        this usage is deprecated and support may be removed at some time in the
        future.
      </p>
    </div>

    <div id="Interpret" class="stb">
      <h2>Interpreting the results</h2>
      <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 then 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,
	feel free to email the 
	(<a href="http://lists.w3.org/Archives/Public/www-validator">publicly archived</a>)
        <a href="mailto:www-validator@w3.org">www-validator@w3.org</a>
        mailing list if you need help interpreting the results. 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="CommaTools">
      <h2>Comma Tools / Site Tools</h2>
      <p>
	This site uses "comma tools", as does <a href="http://www.w3.org/,tools">W3C</a>
	and other sites. This means you can append a string (starting with a comma, hence 
	the name) to the URI (address) of any page on the site and trigger 
	a few administrative or technical tools for this page.
      </p>

	<table class="comma">
	<tr class="comma">
	<th>What it does</th>
	<th>Tool used</th>
	<th>, shortcut</th>
	</tr>

	<tr class="comma">
  	<td class="comma-desc">
		A plain text version of the page.
	</td>
 	<td class="comma-tool">
		<a href="/Web/Tools/html2txt">HTML2Text</a>
	</td>
  	<td class="comma-shortcut">
		,text
	</td>
	</tr>

	<tr class="comma">
  	<td class="comma-desc">
		Validate the MarkUp.
	</td>
 	<td class="comma-tool">
		W3C Markup Validator
	</td>
  	<td class="comma-shortcut">
		,validate
	</td>
	</tr>


	<tr class="comma">
  	<td class="comma-desc">
		Check links (anchors).
	</td>
 	<td class="comma-tool">
		W3C Link Checker
	</td>
  	<td class="comma-shortcut">
		,checklink or ,checklinks
	</td>
	</tr>


	<tr class="comma">
  	<td class="comma-desc">
		Check links (recursively)
	</td>
 	<td class="comma-tool">
		W3C Link Checker
	</td>
  	<td class="comma-shortcut">
		,rchecklink or ,rchecklinks
	</td>
	</tr>


	<tr class="comma">
  	<td class="comma-desc">
		A version of the page with linearized tables.
	</td>
 	<td class="comma-tool">
		Tablin
	</td>
  	<td class="comma-shortcut">
		,tablin
	</td>
	</tr>

	<tr class="comma">
  	<td class="comma-desc">
		CVS history for the page or resource.
	</td>
 	<td class="comma-tool">
		CVSWeb
	</td>
  	<td class="comma-shortcut">
		,cvs or ,cvslog
	</td>
	</tr>

	</table>
</div>

    <div id="Installing" class="stb">
      <h2>Installing a local Validator</h2>
      <p>
        You can download the Validator to run on your own system, but it's not
        recommended for average users as the process is rather complex and
        involves obscure incantations on the command line. <tt>:-)</tt>
      </p>
      <p>
        If you feel you're up to the task, you can find the information you need
        in our <a href="devel.html">Developer Manual</a>.
      </p>
    </div>

<!--#include virtual="../footer.html" -->
  </body>
</html>