emelie/tidy-html5
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Add featured options, and include config list

Browse source
This commit is contained in:
Pedro 2015-03-06 01:01:22 +00:00
parent 00969b0631
commit 5fde57fcd4
6 changed files with 160 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
build/documentation/.gitignore vendored
View file

@ -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

4
build/documentation/build_docs.sh
View file

@ -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/

11
build/documentation/pages/main_page.dox
View file

@ -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
View 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&nbsp;\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.
*/

5
build/documentation/pages/page_tidy.dox
View file

@ -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>

7
build/documentation/pages/page_tidy_config.dox
View file

@ -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>
*/ */