Add featured options, and include config list
This commit is contained in:
parent
00969b0631
commit
5fde57fcd4
2
build/documentation/.gitignore
vendored
2
build/documentation/.gitignore
vendored
|
@ -1,7 +1,7 @@
|
||||||
|
|
||||||
# file created during build_docs
|
# file created during build_docs
|
||||||
# = tidy5 -h > tidy5.cmd.txt
|
# = tidy5 -h > tidy5.cmd.txt
|
||||||
examples/tidy5.cmd.txt
|
examples/tidy5.*.txt
|
||||||
|
|
||||||
# The license file needs to copies to examples for \include
|
# The license file needs to copies to examples for \include
|
||||||
examples/LICENSE.md
|
examples/LICENSE.md
|
||||||
|
|
|
@ -108,7 +108,9 @@ if [ "$BUILD_API" -eq 1 ]; then
|
||||||
echo "The following is doxygen's stderr output. It doesn't indicate errors with this script:\n"
|
echo "The following is doxygen's stderr output. It doesn't indicate errors with this script:\n"
|
||||||
|
|
||||||
# echo the output of tidy5 --help so we can include
|
# echo the output of tidy5 --help so we can include
|
||||||
$TIDY_PATH -h > "./examples/tidy5.cmd.txt"
|
$TIDY_PATH -h > "./examples/tidy5.help.txt"
|
||||||
|
$TIDY_PATH -help-config > "./examples/tidy5.config.txt"
|
||||||
|
|
||||||
|
|
||||||
## copy license file to examples for includsing
|
## copy license file to examples for includsing
|
||||||
cp ../../LICENSE.md ./examples/
|
cp ../../LICENSE.md ./examples/
|
||||||
|
|
|
@ -24,20 +24,21 @@ is converted to
|
||||||
\endcode
|
\endcode
|
||||||
|
|
||||||
|
|
||||||
<h4>tidy and this project has two parts</h4>
|
<h4>This project has two parts:</h4>
|
||||||
|
|
||||||
- \ref tidylib
|
- \ref tidylib
|
||||||
- is a C static or dynamic library that developers can integrate into their applications
|
- a C static or dynamic library that developers can integrate into their applications
|
||||||
in order to bring all of Tidy’s power to your favorite tools.
|
in order to bring all of Tidy’s power to your favorite tools.
|
||||||
|
|
||||||
- \ref tidy5_cmd
|
- \ref tidy_cmd
|
||||||
- is a console application built on \ref tidylib for Mac OS X, Linux, Windows, UNIX, and more.
|
- a console application built on \ref tidylib for Mac OS X, Linux, Windows, UNIX, and more.
|
||||||
|
|
||||||
\section content Contents
|
\section content Contents
|
||||||
|
|
||||||
- \ref tidy5_cmd
|
- \ref tidy_cmd
|
||||||
- \ref tidy_quickstart
|
- \ref tidy_quickstart
|
||||||
- \ref tidy_config
|
- \ref tidy_config
|
||||||
|
- \ref featured_options
|
||||||
- \ref tidy_scripting
|
- \ref tidy_scripting
|
||||||
- \ref tidylib
|
- \ref tidylib
|
||||||
- <a href="modules.html">Modules</a>
|
- <a href="modules.html">Modules</a>
|
||||||
|
|
142
build/documentation/pages/page_featured_options.dox
Normal file
142
build/documentation/pages/page_featured_options.dox
Normal file
|
@ -0,0 +1,142 @@
|
||||||
|
/*!
|
||||||
|
|
||||||
|
|
||||||
|
\page featured_options Featured Options
|
||||||
|
|
||||||
|
\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.
|
||||||
|
|
||||||
|
|
||||||
|
*/
|
|
@ -1,14 +1,15 @@
|
||||||
/*!
|
/*!
|
||||||
|
|
||||||
|
|
||||||
\page tidy5_cmd `tidy5` command
|
\page tidy_cmd tidy command
|
||||||
|
|
||||||
- \subpage tidy_quickstart
|
- \subpage tidy_quickstart
|
||||||
- \subpage tidy_config
|
- \subpage tidy_config
|
||||||
|
- \subpage featured_options
|
||||||
- \subpage tidy_scripting
|
- \subpage tidy_scripting
|
||||||
|
|
||||||
<pre>
|
<pre>
|
||||||
\htmlinclude tidy5.cmd.txt
|
\htmlinclude tidy5.help.txt
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
\page tidy_config Configuration
|
\page tidy_config Configuration
|
||||||
|
|
||||||
To get a list of all configuration settings, use:
|
To get a list of all configuration settings, see \ref config_options below or use:
|
||||||
\code{.sh}
|
\code{.sh}
|
||||||
tidy -help-config
|
tidy -help-config
|
||||||
\endcode
|
\endcode
|
||||||
|
@ -34,6 +34,9 @@ You can find documentation for full set of configuration options on the <a href=
|
||||||
|
|
||||||
\include example_config.txt
|
\include example_config.txt
|
||||||
|
|
||||||
|
\section config_options Config Options
|
||||||
|
<pre>
|
||||||
|
\htmlinclude tidy5.config.txt
|
||||||
|
</pre>
|
||||||
|
|
||||||
*/
|
*/
|
Loading…
Reference in a new issue