Ubuntu Manpage: tidy - check, correct, and pretty-print HTML(5) files

NAME

       tidy - check, correct, and pretty-print HTML(5) files

SYNOPSIS

       tidy [option ...] [file ...] [option ...] [file ...]

DESCRIPTION

       Tidy reads HTML, XHTML, and XML files and writes cleaned-up markup.  For HTML variants, it detects,
       reports, and corrects many common coding errors and strives to produce visually equivalent markup that is
       both conformant to the HTML specifications and that works in most browsers.

       A common use of Tidy is to convert plain HTML to XHTML.  For generic XML files, Tidy is limited to
       correcting basic well-formedness errors and pretty printing.

       If no input file is specified, Tidy reads the standard input.  If no output file is specified, Tidy
       writes the tidied markup to the standard output.  If no error file is specified, Tidy writes messages to
       the standard error.  For command line options that expect a numerical argument, a default is assumed if
       no meaningful value can be found.

OPTIONS

   File manipulation
       -output <%s>, -o <%s>
              write output to the specified <file> (output-file: <%s>)

       -config <%s>
              set configuration options from the specified <file>

       -file <%s>, -f <%s>
              write errors and warnings to the specified <file> (error-file: <%s>)

       -modify, -m
              modify the original input files (write-back: yes)

   Processing directives
       -indent, -i
              indent element content (indent: auto)

       -wrap <%s>, -w <%s>
              wrap  text  at  the  specified  <column>. 0 is assumed if <column> is missing. When this option is
              omitted, the default of the configuration option 'wrap' applies.  (wrap: <%s>)

       -upper, -u
              force tags to upper case (uppercase-tags: yes)

       -clean, -c
              replace FONT, NOBR and CENTER tags with CSS (clean: yes)

       -bare, -b
              strip out smart quotes and em dashes, etc.  (bare: yes)

       -gdoc, -g
              produce clean version of html exported by Google Docs (gdoc: yes)

       -numeric, -n
              output numeric rather than named entities (numeric-entities: yes)

       -errors, -e
              show only errors and warnings (markup: no)

       -quiet, -q
              suppress nonessential output (quiet: yes)

       -omit  omit optional start tags and end tags (omit-optional-tags: yes)

       -xml   specify the input is well formed XML (input-xml: yes)

       -asxml, -asxhtml
              convert HTML to well formed XHTML (output-xhtml: yes)

       -ashtml
              force XHTML to well formed HTML (output-html: yes)

       -access <%s>
              do additional accessibility checks (<level> = 0, 1, 2, 3). 0 is assumed  if  <level>  is  missing.
              (accessibility-check: <%s>)

   Character encodings
       -raw   output values above 127 without conversion to entities

       -ascii use ISO-8859-1 for input, US-ASCII for output

       -latin0
              use ISO-8859-15 for input, US-ASCII for output

       -latin1
              use ISO-8859-1 for both input and output

       -iso2022
              use ISO-2022 for both input and output

       -utf8  use UTF-8 for both input and output

       -mac   use MacRoman for input, US-ASCII for output

       -win1252
              use Windows-1252 for input, US-ASCII for output

       -ibm858
              use IBM-858 (CP850+Euro) for input, US-ASCII for output

       -utf16le
              use UTF-16LE for both input and output

       -utf16be
              use UTF-16BE for both input and output

       -utf16 use UTF-16 for both input and output

       -big5  use Big5 for both input and output

       -shiftjis
              use Shift_JIS for both input and output

   Miscellaneous
       -version, -v
              show the version of Tidy

       -help, -h, -?
              list the command line options

       -help-config
              list all configuration options

       -show-config
              list the current configuration settings

       -help-option <%s>
              show a description of the <option>

       -language <%s>
              set  Tidy's  output language to <lang>. Specify '-language help' for more help. Use before output-
              causing arguments  to  ensure  the  language  takes  effect,  e.g.,`tidy  -lang  es  -lang  help`.
              (language: <%s>)

   XML
       -xml-help
              list the command line options in XML format

       -xml-config
              list all configuration options in XML format

       -xml-strings
              output all of Tidy's strings in XML format

       -xml-error-strings
              output error constants and strings in XML format

       -xml-options-strings
              output option descriptions in XML format

USAGE

       Use  --optionX  valueX  for the detailed configuration option "optionX" with argument "valueX".  See also
       below under Detailed Configuration Options as to how to conveniently group all such options in  a  single
       config file.

       Input/Output  default  to  stdin/stdout  respectively.  Single letter options apart from -f and -o may be
       combined as in:

          tidy -f errs.txt -imu foo.html

ENVIRONMENT

       HTML_TIDY
              Name of the default configuration file.  This should be an absolute path, since you will  probably
              invoke tidy from different directories.  The value of HTML_TIDY will be parsed after the compiled-
              in default (defined with -DTIDY_CONFIG_FILE), but before any of the files specified using -config.

EXIT STATUS

       0      All input files were processed successfully.

       1      There were warnings.

       2      There were errors.

______________________________

DETAILED CONFIGURATION OPTIONS

       This  section describes the Detailed (i.e., "expanded") Options, which may be specified by preceding each
       option with -- at the command line, followed by its desired value, OR by placing the options  and  values
       in a configuration file, and telling tidy to read that file with the -config standard option.

SYNOPSIS

       tidy --option1 value1 --option2 value2 [standard options ...]
       tidy -config config-file [standard options ...]

WARNING

       The  options  detailed here do not include the "standard" command-line options (i.e., those preceded by a
       single '-') described above in the first section of this man page.

DESCRIPTION

A list of options for configuring the behavior of Tidy, which can be passed either on the command line,
or specified in a configuration file.

A Tidy configuration file is simply a text file, where each option is listed on a separate line in the
form

option1: value1
option2: value2
etc.

The permissible values for a given option depend on the option's Type. There are five types: Boolean,
AutoBool, DocType, Enum, and String. Boolean types allow any of yes/no, y/n, true/false, t/f, 1/0.
AutoBools allow auto in addition to the values allowed by Booleans. Integer types take non-negative
integers. String types generally have no defaults, and you should provide them in non-quoted form
(unless you wish the output to contain the literal quotes).

Enum, Encoding, and DocType "types" have a fixed repertoire of items; consult the Example[s] provided
below for the option[s] in question.

You only need to provide options and values for those whose defaults you wish to override, although you
may wish to include some already-defaulted options and values for the sake of documentation and
explicitness.

Here is a sample config file, with at least one example of each of the five Types:

// sample Tidy configuration options
output-xhtml: yes
add-xml-decl: no
doctype: strict
char-encoding: ascii
indent: auto
wrap: 76
repeated-attributes: keep-last
error-file: errs.txt

Below is a summary and brief description of each of the options. They are listed alphabetically within
each category. There are five categories: HTML, XHTML, XML options, Diagnostics options, Pretty Print
options, Character Encoding options, and Miscellaneous options.

OPTIONS

HTML, XHTML, XML options:

add-xml-decl

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should add the XML declaration when outputting XML or XHTML.

Note that if the input already includes an <?xml ... ?> declaration then this option will be
ignored.

If the encoding for the output is different from ascii, one of the utf* encodings, or raw, then
the declaration is always added as required by the XML standard.

See also: char-encoding, output-encoding

add-xml-space

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should add xml:space="preserve" to elements such as <pre>, <style>
and <script> when generating XML.

This is needed if the whitespace in such elements is to be parsed appropriately without having
access to the DTD.

alt-text

Type: String
Default: -
Default: -

This option specifies the default alt= text Tidy uses for <img> attributes when the alt= attribute
is missing.

Use with care, as it is your responsibility to make your documents accessible to people who cannot
see the images.

anchor-as-name

Type: Boolean
Default: yes
Example: y/n, yes/no, t/f, true/false, 1/0

This option controls the deletion or addition of the name attribute in elements where it can serve
as anchor.

If set to yes a name attribute, if not already existing, is added along an existing id attribute
if the DTD allows it.

If set to no any existing name attribute is removed if an id attribute exists or has been added.

assume-xml-procins

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should change the parsing of processing instructions to require ?>
as the terminator rather than >.

This option is automatically set if the input is in XML.

bare

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should strip Microsoft specific HTML from Word 2000 documents, and
output spaces rather than non-breaking spaces where they exist in the input.

clean

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should perform cleaning of some legacy presentational tags
(currently <i>, <b>, <center> when enclosed within appropriate inline tags, and <font>). If set to
yes then legacy tags will be replaced with CSS <style> tags and structural markup as appropriate.

coerce-endtags

Type: Boolean
Default: yes
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should coerce a start tag into an end tag in cases where it looks
like an end tag was probably intended; for example, given

Tidy will output

css-prefix

Type: String
Default: -
Default: -

This option specifies the prefix that Tidy uses for styles rules.

By default, c will be used.

decorate-inferred-ul

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should decorate inferred <ul> elements with some CSS markup to avoid
indentation to the right.

doctype

Type: DocType
Default: auto
Example: html5, omit, auto, strict, transitional, user

This option specifies the DOCTYPE declaration generated by Tidy.

If set to omit the output won't contain a DOCTYPE declaration. Note this this also implies
numeric-entities is set to yes.

If set to html5 the DOCTYPE is set to <!DOCTYPE html>.

If set to auto (the default) Tidy will use an educated guess based upon the contents of the
document.

If set to strict, Tidy will set the DOCTYPE to the HTML4 or XHTML1 strict DTD.

If set to loose, the DOCTYPE is set to the HTML4 or XHTML1 loose (transitional) DTD.

Alternatively, you can supply a string for the formal public identifier (FPI).

For example:

doctype: "-//ACME//DTD HTML 3.14159//EN"

If you specify the FPI for an XHTML document, Tidy will set the system identifier to an empty
string. For an HTML document, Tidy adds a system identifier only if one was already present in
order to preserve the processing mode of some browsers. Tidy leaves the DOCTYPE for generic XML
documents unchanged.

This option does not offer a validation of document conformance.

drop-empty-elements

Type: Boolean
Default: yes
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should discard empty elements.

drop-empty-paras

Type: Boolean
Default: yes
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should discard empty paragraphs.

drop-font-tags

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

Deprecated; do not use. This option is destructive to <font> tags, and it will be removed from
future versions of Tidy. Use the clean option instead.

If you do set this option despite the warning it will perform as clean except styles will be
inline instead of put into a CSS class. <font> tags will be dropped completely and their styles
will not be preserved.

If both clean and this option are enabled, <font> tags will still be dropped completely, and other
styles will be preserved in a CSS class instead of inline.

See clean for more information.

drop-proprietary-attributes

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should strip out proprietary attributes, such as Microsoft data
binding attributes. Additionally attributes that aren't permitted in the output version of HTML
will be dropped if used with strict-tags-attributes.

enclose-block-text

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should insert a <p> element to enclose any text it finds in any
element that allows mixed content for HTML transitional but not HTML strict.

enclose-text

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should enclose any text it finds in the body element within a <p>
element.

This is useful when you want to take existing HTML and use it with a style sheet.

escape-cdata

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should convert <![CDATA[]]> sections to normal text.

fix-backslash

Type: Boolean
Default: yes
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should replace backslash characters \ in URLs with forward slashes
/.

fix-bad-comments

Type: Boolean
Default: yes
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should replace unexpected hyphens with = characters when it comes
across adjacent hyphens.

The default is yes.

This option is provided for users of Cold Fusion which uses the comment syntax: .

fix-uri

Type: Boolean
Default: yes
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should check attribute values that carry URIs for illegal characters
and if such are found, escape them as HTML4 recommends.

gdoc

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should enable specific behavior for cleaning up HTML exported from
Google Docs.

hide-comments

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should print out comments.

hide-endtags

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option is an alias for omit-optional-tags.

indent-cdata

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should indent <![CDATA[]]> sections.

input-xml

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should use the XML parser rather than the error correcting HTML
parser.

join-classes

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should combine class names to generate a single, new class name if
multiple class assignments are detected on an element.

join-styles

Type: Boolean
Default: yes
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should combine styles to generate a single, new style if multiple
style values are detected on an element.

literal-attributes

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies how Tidy deals with whitespace characters within attribute values.

If the value is no Tidy normalizes attribute values by replacing any newline or tab with a single
space, and further by replacing any contiguous whitespace with a single space.

To force Tidy to preserve the original, literal values of all attributes and ensure that
whitespace within attribute values is passed through unchanged, set this option to yes.

logical-emphasis

Type: Boolean
Default: no
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should replace any occurrence of <i> with <em> and any occurrence of
<b> with <strong>. Any attributes are preserved unchanged.

This option can be set independently of the clean option.

lower-literals

Type: Boolean
Default: yes
Example: y/n, yes/no, t/f, true/false, 1/0

This option specifies if Tidy should convert the value of an attribute that takes a list of
predefined values to lower case.

This is required for XHTML documents.

merge-divs

Type: AutoBool
Default: auto
Example: auto, y/n, yes/no, t/f, true/false, 1/0

This option can be used to modify the behavior of clean when set to yes.

This option specifies if Tidy should merge nested <div> such as <div><div>...</div></div>.

If set to auto the attributes of the inner <div> are moved to the outer one. Nested <div> with id
attributes are not merged.

If set to yes the attributes of the inner <div> are discarded with the exception of class and
style.

AUTHOR

       Tidy  was  written  by  Dave  Raggett  <dsr@w3.org>,  and  subsequently   maintained   by   a   team   at
       http://tidy.sourceforge.net/, and now maintained by HTACG (http://www.htacg.org).

       The sources for HTML Tidy are available at https://github.com/htacg/tidy-html5/ under the MIT Licence.

HTML Tidy                                             5.2.0                                              TIDY(1)

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

USAGE

ENVIRONMENT

EXIT STATUS

______________________________

DETAILED CONFIGURATION OPTIONS

SYNOPSIS

WARNING

DESCRIPTION

OPTIONS

SEE ALSO

AUTHOR