/usr/share/w3c-markup-validator/html/docs/users.html is in w3c-markup-validator 1.3+dfsg-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 | <!--#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&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.
</p>
<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.
</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
<<a href="http://validator.w3.org/">http://validator.w3.org/</a>>
at the moment (and for the foreseeable future) and the CGI program can be
reached at <http://validator.w3.org/check>.
</p>
<p>
If you call the CGI program with the "uri=referer" query string parameter
(i.e. <<a href="http://validator.w3.org/check?uri=referer">http://validator.w3.org/check?uri=referer</a>>)
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
<<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>>
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
<<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>>
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>
</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) (<code>doctype</code>)</dt>
<dd>
<p>
This allows you to <strong>override</strong> the DOCTYPE declaration
for your 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 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
<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=<option></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>
|