147 lines
5.8 KiB
Plaintext
147 lines
5.8 KiB
Plaintext
|
/*!
|
|||
|
|
|
|||
|
|
|
|||
|
|
\page featured_options Featured Options
|
|||
|
|
|
|||
|
|
Overview of popular features and problems
|
|||
|
|
|
|||
|
|
\tableofcontents
|
|||
|
|
|
|||
|
|
\section indenting Indenting output for readability
|
|||
|
|
|
|||
|
|
Indenting the source markup of an HTML document makes the markup easier to read. Tidy can indent the
|
|||
|
|
markup for an HTML document while recognizing elements whose contents should not be indented. In the
|
|||
|
|
example below, Tidy indents the output while preserving the formatting of the `<pre>` element:
|
|||
|
|
|
|||
|
|
Input:
|
|||
|
|
\code{.html}
|
|||
|
|
<html>
|
|||
|
|
<head>
|
|||
|
|
<title>Test document</title>
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<p>This example shows how Tidy can indent output while preserving
|
|||
|
|
formatting of particular elements.</p>
|
|||
|
|
|
|||
|
|
<pre>This is
|
|||
|
|
<em>genuine
|
|||
|
|
preformatted</em>
|
|||
|
|
text
|
|||
|
|
</pre>
|
|||
|
|
</body>
|
|||
|
|
</html>
|
|||
|
|
\endcode
|
|||
|
|
|
|||
|
|
Output:
|
|||
|
|
\code{.html}
|
|||
|
|
<html>
|
|||
|
|
<head>
|
|||
|
|
<title>Test document</title>
|
|||
|
|
</head>
|
|||
|
|
|
|||
|
|
<body>
|
|||
|
|
<p>This example shows how Tidy can indent output while preserving
|
|||
|
|
formatting of particular elements.</p>
|
|||
|
|
<pre>
|
|||
|
|
This is
|
|||
|
|
<em>genuine
|
|||
|
|
preformatted</em>
|
|||
|
|
text
|
|||
|
|
</pre>
|
|||
|
|
</body>
|
|||
|
|
</html>
|
|||
|
|
\endcode
|
|||
|
|
|
|||
|
|
Tidy’s indenting behavior is not perfect and can sometimes cause your output to be rendered by browsers in a different way than the input. You can
|
|||
|
|
avoid unexpected indenting-related rendering problems by setting `indent:no` or `indent:auto` in a config file.
|
|||
|
|
|
|||
|
|
\note
|
|||
|
|
<b>Preserving original indenting not possible</b><br><br>
|
|||
|
|
Tidy is not capable of preserving the original indenting of the markup from the input it receives. That’s because Tidy starts by
|
|||
|
|
building a clean parse tree from the input, and that parse tree doesn’t contain any information about the original indenting. Tidy then
|
|||
|
|
pretty-prints the parse tree using the current config settings. Trying to preserve the original
|
|||
|
|
indenting from the input would interact badly with the repair operations needed to build a clean parse tree, and would considerably complicate the code.
|
|||
|
|
|
|||
|
|
|
|||
|
|
\section encodings Encodings and character references
|
|||
|
|
|
|||
|
|
Tidy defaults to assuming you want output to be encoded in `UTF-8`. But Tidy offers you a choice of other
|
|||
|
|
character encodings: `US ASCII`, `ISO Latin-1`, and the `ISO 2022` family of 7 bit encodings.
|
|||
|
|
|
|||
|
|
Tidy doesn’t yet recognize the use of the HTML `<meta>` element for specifying the character encoding.
|
|||
|
|
|
|||
|
|
The full set of HTML character references are defined. Cleaned-up output uses named character references for characters when appropriate. Otherwise,
|
|||
|
|
characters outside the normal range are output as numeric character references.
|
|||
|
|
|
|||
|
|
\section accessibility Accessibility
|
|||
|
|
|
|||
|
|
Tidy offers advice on potential accessibility problems for people using non-graphical browsers.
|
|||
|
|
|
|||
|
|
\section cleaning_presentational Cleaning up presentational markup
|
|||
|
|
|
|||
|
|
Some tools generate HTML with presentational elements such as `<font>`, `<nobr>`, and `<center>`. Tidy’s -clean option will replace those elements with `<style>` elements and CSS.
|
|||
|
|
|
|||
|
|
Some HTML documents rely on the presentational effects of `<p>` start tags that are not followed by any content. Tidy deletes
|
|||
|
|
such `<p>` tags (as well as any headings that don’t have content). So do not use `<p>` tags simply for
|
|||
|
|
adding vertical whitespace; instead use CSS, or the `<br>` element. However, note that
|
|||
|
|
Tidy won’t discard `<p>` tags that are followed by any non-breaking space (that is, the \code \endcode named character reference).
|
|||
|
|
|
|||
|
|
\section new_tags Teaching Tidy about new tags
|
|||
|
|
|
|||
|
|
You can teach Tidy about new tags by declaring them in the configuration file, the syntax is:
|
|||
|
|
\code
|
|||
|
|
new-inline-tags: tag1, tag2, tag3
|
|||
|
|
new-empty-tags: tag1, tag2, tag3
|
|||
|
|
new-blocklevel-tags: tag1, tag2, tag3
|
|||
|
|
new-pre-tags: tag1, tag2, tag3
|
|||
|
|
\endcode
|
|||
|
|
The same tag can be defined as \b empty and as \b inline, or as \b empty and as \b block.
|
|||
|
|
|
|||
|
|
These declarations can be combined to define a new empty inline or empty block element, but you are not advised to
|
|||
|
|
declare tags as being both \b inline and \b block.
|
|||
|
|
|
|||
|
|
Note that the new tags can only appear where Tidy expects inline or block-level tags respectively. That means you can’t place new
|
|||
|
|
tags within the document head or other contexts with restricted content models.
|
|||
|
|
|
|||
|
|
|
|||
|
|
\section ignoring_scripting Ignoring PHP, ASP, and JSTE instructions
|
|||
|
|
|
|||
|
|
Tidy will gracefully ignore many cases of PHP, ASP, and JSTE instructions within element content and as replacements for attributes,
|
|||
|
|
and preserve them as-is in output; for example:
|
|||
|
|
|
|||
|
|
\code{.php}
|
|||
|
|
<option <% if rsSchool.Fields("ID").Value
|
|||
|
|
= session("sessSchoolID")
|
|||
|
|
then Response.Write("selected") %>
|
|||
|
|
value='<%=rsSchool.Fields("ID").Value%>'>
|
|||
|
|
<%=rsSchool.Fields("Name").Value%>
|
|||
|
|
(<%=rsSchool.Fields("ID").Value%>)
|
|||
|
|
</option>
|
|||
|
|
\endcode
|
|||
|
|
|
|||
|
|
But note that Tidy may report missing attributes when those are “hidden” within the PHP, ASP, or JSTE code. If you use
|
|||
|
|
PHP, ASP, or JSTE code to create a start tag, but place the end tag explicitly in the HTML markup, Tidy
|
|||
|
|
won’t be able to match them up, and will delete the end tag. In that case you are advised to make the
|
|||
|
|
start tag explicit and to use PHP, ASP, or JSTE code for just the attributes; for example:
|
|||
|
|
\code{.php}
|
|||
|
|
<a href="<%=random.site()%>">do you feel lucky?</a>
|
|||
|
|
\endcode
|
|||
|
|
|
|||
|
|
Tidy can also get things wrong if the PHP, ASP, or JSTE code includes quotation marks; for example:
|
|||
|
|
\code{.php}
|
|||
|
|
value="<%=rsSchool.Fields("ID").Value%>"
|
|||
|
|
\endcode
|
|||
|
|
|
|||
|
|
Tidy will see the quotation mark preceding ID as ending the attribute value, and proceed to complain about what follows.
|
|||
|
|
|
|||
|
|
Tidy allows you to control whether line wrapping on spaces within PHP, ASP, and JSTE instructions is
|
|||
|
|
enabled; see the `wrap-php`, `wrap-asp`, and `wrap-jste` config options.
|
|||
|
|
|
|||
|
|
|
|||
|
|
\section correcting_xml Correcting well-formedness errors in XML markup
|
|||
|
|
Tidy can help you to correct well-formedness errors in XML markup. Tidy doesn’t yet recognize all XML features,
|
|||
|
|
though; for example, it doesn’t understand CDATA sections or DTD subsets.
|
|||
|
|
|
|||
|
|
|
|||
|
|
*/
|