Add featured options, and include config list
This commit is contained in:
Pedro
parent
00969b0631
commit
5fde57fcd4
2
build/documentation/.gitignore
vendored
2
build/documentation/.gitignore
vendored
|
|
@ -1,7 +1,7 @@
|
|||
|
||||
# file created during build_docs
|
||||
# = tidy5 -h > tidy5.cmd.txt
|
||||
examples/tidy5.cmd.txt
|
||||
examples/tidy5.*.txt
|
||||
|
||||
# The license file needs to copies to examples for \include
|
||||
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 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
|
||||
cp ../../LICENSE.md ./examples/
|
||||
|
|
|
|||
|
|
@ -24,20 +24,21 @@ is converted to
|
|||
\endcode
|
||||
|
||||
|
||||
<h4>tidy and this project has two parts</h4>
|
||||
<h4>This project has two parts:</h4>
|
||||
|
||||
- \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.
|
||||
|
||||
- \ref tidy5_cmd
|
||||
- is a console application built on \ref tidylib for Mac OS X, Linux, Windows, UNIX, and more.
|
||||
- \ref tidy_cmd
|
||||
- a console application built on \ref tidylib for Mac OS X, Linux, Windows, UNIX, and more.
|
||||
|
||||
\section content Contents
|
||||
|
||||
- \ref tidy5_cmd
|
||||
- \ref tidy_cmd
|
||||
- \ref tidy_quickstart
|
||||
- \ref tidy_config
|
||||
- \ref featured_options
|
||||
- \ref tidy_scripting
|
||||
- \ref tidylib
|
||||
- <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_config
|
||||
- \subpage featured_options
|
||||
- \subpage tidy_scripting
|
||||
|
||||
<pre>
|
||||
\htmlinclude tidy5.cmd.txt
|
||||
\htmlinclude tidy5.help.txt
|
||||
</pre>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
\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}
|
||||
tidy -help-config
|
||||
\endcode
|
||||
|
|
@ -34,6 +34,9 @@ You can find documentation for full set of configuration options on the <a href=
|
|||
|
||||
\include example_config.txt
|
||||
|
||||
|
||||
\section config_options Config Options
|
||||
<pre>
|
||||
\htmlinclude tidy5.config.txt
|
||||
</pre>
|
||||
|
||||
*/
|
||||
Loading…
Reference in a new issue