301 lines
11 KiB
HTML
301 lines
11 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta name="generator" content=
|
|
"HTML Tidy for Mac OS X (vers 1st June 2003), see www.w3.org" />
|
|
<link type="text/css" rel="stylesheet" href="tidy.css" />
|
|
<title>HTML Tidy - Frequently Asked Questions</title>
|
|
<style type="text/css">
|
|
code { font-weight: bold; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<h1>HTML Tidy - Frequently Asked Questions</h1>
|
|
|
|
<h2>Overview</h2>
|
|
|
|
<p class="abstract">Certain questions about Tidy come up on a
|
|
regular basis. These are some that have been culled from postings
|
|
to the html-tidy@w3.org and tidy-develop@lists.sourceforge.net
|
|
mailing lists. If you don't see your question addressed here, see
|
|
<a href="#support">How To Get Support</a> below.</p>
|
|
|
|
<ul>
|
|
<li><a href="#what-now">What Now?</a></li>
|
|
|
|
<li><a href="#support">How to Get Support?</a></li>
|
|
|
|
<li><a href="#bug">How to Submit A Bug Report</a></li>
|
|
|
|
<li><a href="#feature">How to Submit A Feature Request</a></li>
|
|
|
|
<li><a href="#layout">How Do I Control the Output Layout?</a></li>
|
|
|
|
<li><a href="#version">What Version of Tidy Should I Use?</a></li>
|
|
|
|
<li><a href="#regression">How Do I Run A Regression Test?</a></li>
|
|
</ul>
|
|
|
|
<hr />
|
|
<dl>
|
|
<dt><a name="what-now" id="what-now"></a>What Now?</dt>
|
|
|
|
<dd><p>If you have a popup screen that reads as follows:
|
|
<pre>
|
|
HTML Tidy for Windows <vers 1st August 2002; built on Aug 8 2002, at 15:41:13>
|
|
Parsing Console input <stdin>
|
|
</pre>
|
|
|
|
<p>and do not know what to do next, read on.</p>
|
|
|
|
<p>Tidy is waiting for your HTML to come in, so it can parse it.
|
|
Tidy is fundamentally a tool that reads in HTML cleans it up and
|
|
writes it out again. It was developed as a program you run from the
|
|
console prompt, but there are GUI encapsulations available, e.g.
|
|
HTML-Kit, which you might prefer.</p>
|
|
|
|
<p>If you are using Windows, the first step is to unzip the zip file
|
|
and place the tidy.exe file in a folder somewhere on your executables
|
|
path. You may also want to set up a config file to save having to type
|
|
lots of options each time you run Tidy. From the console prompt you can
|
|
run Tidy like this:</p>
|
|
|
|
<pre>
|
|
C> tidy -m mywebpage.html
|
|
</pre>
|
|
|
|
<p>In this case, the <code>-m</code> option requests Tidy to write
|
|
the tidied file back to the same filename as it read from
|
|
(mywebpage.html). Tidy will give you a breakdown of the problems it
|
|
found and the version of HTML the file appears to be using.</p>
|
|
|
|
<p>To get a listing of Tidy command line options, just type
|
|
<code>tidy -?</code>. To see a listing on configuration options,
|
|
try <code>tidy -help-config</code>. To get more info on the
|
|
config options, see the <a
|
|
href="http://tidy.sourceforge.net/docs/quickref.html">Quick Reference</a>.</p>
|
|
|
|
<p>See also Dave Raggett's <a href="http://tidy.sourceforge.net/docs/Overview.html#help">User Guide</a>.</p>
|
|
|
|
<p>If you're not comfortable with the DOS command line, you should
|
|
try one of the <a href="http://tidy.sourceforge.net/#tidylibapps">GUI
|
|
Applications</a>.</p>
|
|
</dd>
|
|
|
|
<dt><a name="support" id="support"></a>How To Get Support</dt>
|
|
|
|
<dd>
|
|
<p>For general HTML Tidy support, the original mailing list
|
|
html-tidy@w3.org is best. Sometimes developers are the last to
|
|
know... Also, this list covers both Java and C versions, not to
|
|
mention various value-added products such as GUI front ends, Perl
|
|
and Python integration, etc. If you don't get a response after a
|
|
couple tries or if you have a bug fix, bump it over to the
|
|
developer list at tidy-develop@lists.sourceforge.net. It's not a
|
|
hard line, but that is the general arrangement.</p>
|
|
</dd>
|
|
|
|
<dt><a name="bug" id="bug"></a>How to Submit A Bug Report</dt>
|
|
|
|
<dd>
|
|
<p>You are encouraged to report bugs you found to the Tidy
|
|
developer team. Tidy's quality depends on your feedback. You can
|
|
either file your bug report in the Sourceforge <a
|
|
href="http://sourceforge.net/tracker/?func=add&group_id=27659&atid=390963">
|
|
bug tracker</a> for HTML Tidy (<em>recommended</em>) or send a mail
|
|
to the mailing list at html-tidy@w3.org. Note you do <em>not</em>
|
|
have to have a Sourceforge account in order to file bug reports, or
|
|
be subscribed to html-tidy@w3.org in order to post messages to the
|
|
list.</p>
|
|
|
|
<p>Prior to submitting a bug report, please check that the bug is
|
|
not already known. Many are. If you are not sure, just ask. If it
|
|
is new bug, make sure to include at least the following information
|
|
in your report:</p>
|
|
|
|
<ul>
|
|
<li>A desciption of what you think went wrong.</li>
|
|
|
|
<li>The HTML Tidy version (find it out by running <code>tidy
|
|
-v</code>) and operating system you are running.</li>
|
|
|
|
<li>The input, that exposes the bug.<br />
|
|
A small HTML document that reproduces the problem is best.</li>
|
|
|
|
<li>The configuration options you've used. Command line options
|
|
like<br />
|
|
<code>-asxml</code>, configuration files, etc. You may use
|
|
<code>tidy -show-config</code> to get an overview of the active
|
|
Tidy settings.</li>
|
|
|
|
<li>Your e-mail address for further questions and comments.</li>
|
|
</ul>
|
|
|
|
<p>These information are necessary to reproduce whatever is
|
|
failing, without them we cannot help you. Additional information -
|
|
and patches - are very welcome!</p>
|
|
|
|
<p><em>Please include only one bug per report.</em> Reports with
|
|
multiple bugs are less easy to track and some bugs may get
|
|
missed.</p>
|
|
</dd>
|
|
|
|
<dt><a name="feature" id="feature"></a>How to Submit A Feature
|
|
Request</dt>
|
|
|
|
<dd>
|
|
<p>If you want Tidy to do something new that it doesn't do today
|
|
(or stop doing something), then it is probably a feature
|
|
request.</p>
|
|
|
|
<p>The process for submitting a feature request is very similar to
|
|
bug requests. A different <a
|
|
href="http://sourceforge.net/tracker/?atid=390966&group_id=27659">
|
|
tracker</a> is used on SourceForge to denote the difference in
|
|
subject matter.</p>
|
|
|
|
<p>As with bugs, please be sure that the feature has not already
|
|
been requested. If the feature has already requested, you can add
|
|
your comments to the feature request tracker, or send mail to the
|
|
<a href="mailto:html-tidy@w3.org">mailing list</a> indicating your
|
|
wish to also have the feature implemented. If the feature has not
|
|
already been requested, send the same information as for a bug
|
|
report, but place special emphasis on the desired output for a
|
|
given input, desired options, etc. - please be as specific as
|
|
possible about what you want Tidy to <em>do</em>.</p>
|
|
</dd>
|
|
|
|
<dt><a name="layout" id="layout"></a>How Do I Control the Output Layout?</dt>
|
|
|
|
<dd>
|
|
<p>There are three primary options that control how Tidy
|
|
formats your markup:</p>
|
|
<ul>
|
|
<li><a class="code"
|
|
href="quickref.html#indent">indent</a></li>
|
|
<li><a class="code"
|
|
href="quickref.html#indent-attributes">indent-attributes</a></li>
|
|
<li><a class="code"
|
|
href="quickref.html#vertical-space">vertical-space</a></li>
|
|
</ul>
|
|
|
|
<p>Briefly, <code>indent</code> sets the level of left-to-right indenting
|
|
and, somewhat, how often elements are put onto a new line. The options
|
|
are <code>yes</code>, <code>no</code>, and <code>auto</code>.
|
|
<code>indent-attributes</code> is a flag that, when set, tells Tidy to
|
|
put each attribute on a new line. <code>vertical-space</code> is a flag
|
|
that, when set, tells Tidy to add some empty lines for readability. The
|
|
default for all three is <code>no</code>. These options may be used in
|
|
any combination to control you you want your markup to look. The best
|
|
thing is to experiment a bit to see what you like. Be aware that
|
|
<code>indent yes</code> is deprecated for production use as it will
|
|
cause visual changes in most browsers.</p>
|
|
|
|
<p>To get Tidy <em>Classic</em> <code>--indent auto</code> layout, use the following options:</p>
|
|
|
|
<pre>
|
|
indent: auto
|
|
indent-attributes: no
|
|
vertical-space: yes
|
|
</pre>
|
|
|
|
<p>You can read about more <em>Pretty Print</em> options
|
|
<a href="quickref.html#PrettyPrintHeader">here</a>.</p>
|
|
</dd>
|
|
|
|
<dt><a name="version" id="version"></a>What Version of Tidy Should
|
|
I Use?</dt>
|
|
|
|
<dd>
|
|
<p>The current Source Forge builds are recommended. You can find these at
|
|
<a href="http://tidy.sourceforge.net">http://tidy.sourceforge.net</a>.
|
|
People continue to report examples where Tidy does not catch some
|
|
ill-formed HTML or, worse, generates ill-formed HTML. These cases have
|
|
been significantly reduced. That said, be sure to test Tidy with some
|
|
representative files from your environment.</p>
|
|
|
|
<p>For development work, use CVS directly on your development
|
|
system. For information on how to pull Tidy sources from <a
|
|
href="http://sourceforge.net/cvs/?group_id=27659">CVS</a>. This way
|
|
you can keep abreast of changes to Tidy and quickly resolve
|
|
conflicts.</p>
|
|
|
|
<p>For building a front end (e.g. GUI or language binding), the
|
|
simplest approach is to use TidyLib. For more information
|
|
about building and coding with TidyLib, see the <a
|
|
href="http://tidy.sourceforge.net/libintro.html">Introduction To TidyLib</a>.</p>
|
|
</dd>
|
|
|
|
<dt><a name="regression" id="regression">How Do I Run A
|
|
Regression Test?</a></dt>
|
|
<dd>
|
|
<p>You might ask, "Why should I run a regression test?". If you
|
|
are a Tidy user, you might want to compare a new version of Tidy
|
|
to the version you are currently running. This is a good idea
|
|
if you are using Tidy in production applications such as web
|
|
publishing. If you are a Tidy developer, it is a good idea to
|
|
run the regression test suite to make sure your fix or enhancement
|
|
doesn't add new bugs.</p>
|
|
|
|
<p>Detecting new bugs is easier said than done, because sometimes
|
|
they are subtle and can only be seen in browsers (or one particular
|
|
browser you don't even have). But you can catch most crashes and
|
|
many layout problems by running the test suite as described here.</p>
|
|
|
|
<p>The basic process is simple: run the test suite <strong>before</strong>
|
|
and <strong>after</strong> making changes to TidyLib and compare the output
|
|
markup and messages. Be aware that the test scripts for WinNT/2K/XP
|
|
(alltest.cmd) and Linux/Unix (testall.sh) place the output files in
|
|
<code>tidy/test/tmp</code>. If you forget to run the <strong>before</strong>
|
|
test, you can always download a binary from the <a
|
|
href="http://tidy.sourceforge.net/#binaries">Project Page</a>. If you
|
|
are not a TidyLib developer, you can download the <a
|
|
href="http://tidy.sourceforge.net/test/tidy_test.tgz">Test Suite</a>
|
|
directly. Here are the steps to evaluate the impact of a TidyLib change.</p>
|
|
|
|
<h3>For Windows</h3>
|
|
<p><strong>Before</strong> making changes:</p>
|
|
<pre>
|
|
C:\tidy\test> alltest.cmd
|
|
C:\tidy\test> ren tmp baseline
|
|
</pre>
|
|
|
|
<p><strong>After</strong> making changes and building Tidy:</p>
|
|
<pre>
|
|
C:\tidy\test> alltest.cmd
|
|
C:\tidy\test> windiff tmp baseline
|
|
</pre>
|
|
|
|
<h3>For Linux/Unix</h3>
|
|
<p><strong>Before</strong> making changes:</p>
|
|
<pre>
|
|
~/tidy/test$ ./testall.sh
|
|
~/tidy/test$ mv tmp baseline
|
|
</pre>
|
|
|
|
<p><strong>After</strong> making changes and building Tidy:</p>
|
|
<pre>
|
|
~/tidy/test$ ./testall.sh
|
|
~/tidy/test$ diff -u tmp baseline > diff.txt
|
|
</pre>
|
|
</dd>
|
|
|
|
<!--
|
|
<dt><a name="" id=""></a></dt>
|
|
<dd>
|
|
</dd>
|
|
|
|
<dt><a name="" id=""></a></dt>
|
|
<dd>
|
|
</dd>
|
|
-->
|
|
<!-- Save for future questions
|
|
<dt><a name="" id=""></a></dt>
|
|
<dd>
|
|
</dd>
|
|
-->
|
|
</dl>
|
|
</body>
|
|
</html>
|