
                        icon Clean up your Web pages
                               with HTML TIDY
                                      
           Copyright  1999 W3C, see tidy.c for copyright notice.
   
     With many thanks to Hewlett Packard for financial support during
     the development of this software!
     
                        This version 15th April 1999
   
   See the release notes for information on recent changes.
   
   To get the latest version of Tidy please visit the original version of
   this page at: http://www.w3.org/People/Raggett/tidy. Courtesy of
   Netmind, you can register for email reminders when new versions of
   tidy become available.
   
                           Press Here to Register
          ________________________________________________________
   
             How to use Tidy | Downloading Tidy | Release Notes
             Integration with other Software | Acknowledgements
          ________________________________________________________
   
  Introduction to TIDY
  
   When editing HTML it's easy to make mistakes. Wouldn't it be nice if
   there was a simple way to fix these mistakes automatically and tidy up
   sloppy editing into nicely layed out markup? Well now there is! Dave
   Raggett's HTML TIDY is a free utility for doing just that. It also
   works great on the atrociously hard to read markup generated by
   specialized HTML editors and conversion tools, and can help you
   identify where you need to pay further attention on making your pages
   more accessible to people with disabilities.
   
   Tidy is able to fix up a wide range of problems and to bring to your
   attention things that you need to work on yourself. Each item found is
   listed with the line number and column so that you can see where the
   problem lies in your markup. Tidy won't generate a cleaned up version
   when there are problems that it can't be sure of how to handle. These
   are logged as "errors" rather than "warnings".
   
  Examples of TIDY at work
  
   Tidy corrects the markup in a way that matches where possible the
   observed rendering in popular browsers from Netscape and Microsoft.
   Here are just a few examples of how TIDY perfects your HTML for you:
     * Missing or mismatched end tags are detected and corrected
   <h1>heading
   <h2>subheading</h3>
       is mapped to
   <h1>heading</h1>
   <h2>subheading</h2>
     * End tags in the wrong order are corrected:
   <p>here is a para <b>bold <i>bold italic</b> bold?</i> normal?
       is mapped to
   <p>here is a para <b>bold <i>bold italic</i> bold?</b> normal?
     * Fixes problems with heading emphasis
   <h1><i>italic heading</h1>
   <p>new paragraph
       In Netscape and Internet Explorer this causes everything following
       the heading to be in the heading font size, not the desired effect
       at all!
       Tidy maps the example to
   <h1><i>italic heading</i></h1>
   <p>new paragraph
     * Recovers from mixed up tags
   <i><h1>heading</h1></i>
   <p>new paragraph <b>bold text
   <p>some more bold text
       Tidy maps this to
   <h1><i>heading</i></h1>
   <p>new paragraph <b>bold text</b>
   <p><b>some more bold text</b>
     * Getting the <hr> in the right place:
   <h1><hr>heading</h1>
   <h2>sub<hr>heading</h2>
       Tidy maps this to
   <hr>
   <h1>heading</h1>
   <h2>sub</h2>
   <hr>
   <h2>heading</h2>
     * Adding the missing "/" in end tags for anchors:
   <a href="#refs">References<a>
       Tidy maps this to
   <a href="#refs">References</a>
     * Perfecting lists by putting in tags missed out:
   <body>
   <li>1st list item
   <li>2nd list item
       is mapped to
   <body>
   <ul>
   <li>1st list item</li>
   <li>2nd list item</li>
   </ul>
     * Missing quotes around attribute values are added
       Tidy inserts quote marks around all attribute values for you. It
       can also detect when you have forgotten the closing quote mark,
       although this is something you will have to fix yourself.
     * Unknown/Proprietary attributes are reported
       Tidy has a comprehensive knowledge of the attributes defined in
       the HTML 4.0 recommendation from W3C. This often allows you to
       spot where you have mistyped an attribute or value.
     * Proprietary elements are recognized and reported as such.
       Tidy will even work out which version of HTML you are using and
       insert the appropriate DOCTYPE element, as per the W3C
       recommendations.
     * Tags lacking a terminating '>' are spotted
       This is something you then have to fix yourself as Tidy is unsure
       of where the > should be inserted.
       
  Layout style
  
   You can choose which style you want Tidy to use when it generates the
   cleaned up markup: for instance whether you like elements to indent
   their contents or not.
   
  Internationalization issues
  
   Tidy offers you a choice of character encodings: US ASCII, ISO
   Latin-1, UTF-8 and the ISO 2022 family of 7 bit encodings. The full
   set of HTML 4.0 entities are defined. Cleaned up output uses HTML
   entity names for characters when appropriate. Otherwise characters
   outside the normal range are output as numeric character entities.
   
  Accessibility
  
   Tidy offers advice on accessibility problems for people using
   non-graphical browsers. The most common thing you will see is the
   suggestion you add a summary attribute to table elements. The idea is
   to provide a summary of the table's role and structure suitable for
   use with aural browsers.
   
  Cleaning up presentational markup
  
   Many tools generate HTML with an excess of FONT, NOBR and CENTER tags.
   Tidy's -clean option will replace them by style properties and rules
   using CSS. This makes the markup easier to read and maintain as well
   as reducing the file size! Tidy is expected to get smarter at this in
   the future.
   
  Support for XML
  
   XML processors compliant with W3C's XML 1.0 recommendation are very
   picky about which files they will accept. Tidy can help you to fix
   errors that cause your XML files to be rejected. Tidy doesn't yet
   recognize all XML features though, e.g. it doesn't yet understand
   CDATA sections or DTD subsets.
   
  Creating Slides
  
   The -slides option allows you to burst a single HTML file into a
   number of linked slides. Each H2 element in the input file is treated
   as delimiting the start of the next slide. The slides are named
   slide1.html, slide2.html, slide3.html etc. This is a relatively new
   feature and ideas are welcomed as to how to improve it. In particular,
   I plan to add support to the configuration file for setting the style
   sheet for slides and for customizing the slides via a template.
   
   I would be interested in hearing from anyone who can offer help with
   using Javascript for adding dynamic effects to slides, for instance
   similar to those available in Microsoft PowerPoint.
   
  Indenting text for a better layout
  
 <html>
   <head>
   </head>
   <body>
     <p>
       para which has enough text to cause a line break, and so test
       the wrapping mechanism for long lines.
     </p>
 <pre>This is
 <em>genuine
       preformatted</em>
    text
 </pre>
     <ul>
       <li>
         1st list item
       </li>
       <li>
         2nd list item
       </li>
     </ul>
     <!-- end comment -->
   </body>
 </html>

   and this is the default style:
 <html>
 <head>
 </head>
 <body>
 <p>para which has enough text to cause a line break, and so test
 the wrapping mechanism for long lines.</p>

 <pre>This is
 <em>genuine
       preformatted</em>
    text
 </pre>

 <ul>
 <li>1st list item </li>

 <li>2nd list item</li>
 </ul>

 <!-- end comment -->
 </body>
 </html>

  How to run tidy
  
   tidy [[options] filename]*

   HTML tidy is not (yet) a windows program. If you run tidy without any
   arguments, it will just sit there waiting to read markup on the stdin
   stream. Tidy's input and output default to stdin and stdout
   respectively. Errors are written to stderr but can be redirected to a
   file with the -f filename option.
   
   I generally use the -m option to get tidy to update the original file,
   and if the file is particularly bad I also use the -f option to write
   the errors to a file to make it easier to review them. Tidy supports a
   small set of character encoding options. The default is ASCII, which
   makes it easy to edit markup in regular text editors.
   
   For instance:
   tidy -f errs.txt -m index.html

   which runs tidy on the file "index.html" updating it in place and
   writing the error messages to the file "errs.txt". Its a good idea to
   save your work before tidying it, as with all complex software, tidy
   may have bugs. If you find any please let me know!
   
   Users running in Microsoft Windows should be aware that Dos doesn't
   expand wild cards in filenames. This means that if you have several
   html files in the same directory and want to tidy all of them:
   tidy *.html

   won't work. You will see an error message: "can't open file *.html".
   Instead you need to run tidy separately on each one. I will look into
   a fix for this for a future release. A work around is to use the DOS
   for command, as in:
        for %i in (*.html) do tidy %i

   Note: in a batch file that needs to be %%i instead of %i
   
    Tidy's Options
    
   To get a list of available options use:
   tidy -help

   You should see something like this:
   options for tidy vers: 14th April 1999

   -config file        read config file
   -indent or -i       indent element content
   -omit or -o         omit optional endtags
   -wrap 72            wrap text at column 72 (default is 68)
   -upper or -u        force tags to upper case
   -clean or -c        replace font, nobr &amp; center tags by CSS
   -raw                don't o/p entities for chars 128 to 255
   -ascii              use ASCII for output, Latin-1 for input
   -latin1             use Latin-1 for both input and output
   -utf8               use UTF-8 for both input and output
   -iso2022            use ISO2022 for both input and output
   -numeric or -n      output numeric rather than named entities
   -modify or -m       to modify original files
   -errors or -e       show only error messages
   -f file             write errors to file
   -xml                use this when input is in XML
   -asxml              to convert HTML to XML
   -slides             to burst into slides on h2 elements
   -help               list command line options

   Input and Output default to stdin/stdout respectively. Single letter
   options apart from -f may be combined as in: tidy -f errs.txt -imu
   foo.html
   
  Using a Configuration File
  
   Tidy now supports a configuration file, and this is now much the most
   convenient way to configure Tidy. Assuming you have created a config
   file named "config.txt" (the name doesn't matter), you can instruct
   Tidy to use it via the command line option -config config.txt, e.g.
   tidy -config config.txt file1.html file2.html

   Alternatively, you can name the default config file via the
   environment variable named "HTML_TIDY". Note this should be the
   absolute path since you are likely to want to run Tidy in different
   directories.
   
   The following options are supported:
   
   markup: bool
          Determines whether Tidy generates a pretty printed version of
          the markup. Bool values are either yes or no. Note that Tidy
          won't generate a pretty printed version if it finds unknown
          tags, or missing trailing quotes on attribute values, or
          missing trailing '>' on tags. The default is no.
          
   wrap: number
          Sets the right margin beyond which Tidy attempts to wrap lines
          so as to get them to fit within this margin. The default is
          column 66.
          
   tab-size: number
          Sets the number of columns between successive tab stops. The
          default is 4. It is used to map tabs to spaces when reading
          files. Tidy never outputs files with tabs.
          
   indent: no, yes or auto
          If set to yes Tidy will indent block-level tags. The default is
          no. If set to auto Tidy will decide whether or not to indent
          the content of tags such as h1-h6, li, or p depending on
          whether or not the content includes a block-level element.
          
   indent-spaces: number
          Sets the number of spaces to indent content when indentation is
          enabled. The default is 2 spaces.
          
   hide-endtags: bool
          If set to yes, optional end-tags will be omitted when
          generating the pretty printed markup. This option is ignored if
          you are outputting to XML. The default is no.
          
   input-xml: bool
          If set to yes, Tidy will use the XML parser rather than the
          error correcting HTML parser. The default is no.
          
   output-xml: bool
          If set to yes, Tidy will use generate the pretty printed output
          writing it as well-formed XML. Any entities not defined in XML
          1.0 will be written as numeric entities to allow them to be
          parsed by an XML parser. The default is no.
          
   output-xhtml: bool
          If set to yes, Tidy will use generate the pretty printed output
          writing it as extensible HTML. The default is no. This option
          causes Tidy to set the doctype and default namespace as
          appropriate to XHTML. If a doctype or namespace is given they
          will checked for consistency with the content of the document.
          In the case of an inconsistency, the corrected values will
          appear in the output. For XHTML, entities can be written as
          named or numeric entities according to the value of the
          "numeric-entities" property.
          
   char-encoding: raw, ascii, latin1, utf8 or iso2022
          Determines how Tidy interprets character streams. For ascii,
          Tidy will accept Latin-1 character values, but will use
          entities for all characters whose value > 127. For raw, Tidy
          will output values above 127 without translating them into
          entities. For latin1 characters above 255 will be written as
          entities. For utf8, Tidy assumes that both input and output is
          encoded as UTF-8. You can use iso2022 for files encoded using
          the ISO2022 family of encodings e.g. ISO 2022-JP. The default
          is ascii
          
   numeric-entities: bool
          Causes entities other than the basic XML 1.0 named entities to
          be written in the numeric rather than the named entity form.
          The default is no
          
   quote-marks: bool
          If set, this causes " characters to be written out as
          &amp;quot; as is preferred by some editing environments. The
          default is no.
          
   quote-nbsp: bool
          If set, this causes non-breaking space characters to be written
          out as enities. The default is yes.
          
   quote-marks: bool
          If set, this causes unadorned &amp; characters to be written
          out as &amp;. The default is yes.
          
   wrap-script-literals: bool
          If set, this allows lines to be wrapped within string literals
          that appear in script attributes. The default is no. The
          example shows how Tidy wraps a really really long script string
          literal inserting a backslash character before the linebreak:
          
<a href="somewhere.html" onmouseover="document.status = '...some \
really, really, really, really, really, really, really, really, \
really, really long string..';">test</a>

   break-before-br: bool
          If set, Tidy will output a line break before each <br> element.
          The default is no.
          
   uppercase-tags: bool
          Causes tag names to be output in upper case. The default is no.
          
   uppercase-attributes: bool
          Causes attribute names to be output in upper case. The default
          is no.
          
   clean: bool
          If set, causes Tidy to strip out surplus presentational tags
          and attributes replacing them by style rules and structural
          markup as appropriate. It works well on the html saved from
          Microsoft Office'97. I hope to work on cleaning up after Office
          2000 in a future release. The default is no.
          
   write-back: bool
          If set, Tidy will write back the tidied markup to the same file
          it read from. The default is no. You are advised to keep copies
          of important files before tidying them as on rare occasions the
          result may not always be what you expect.
          error-file: filename
          Writes errors and warnings to the specified file rather than to
          stderr.
          
   show-warnings: bool
          If set to no, warnings are suppressed. This can be useful when
          a few errors are hidden in a flurry of warnings. The default is
          yes.
          
   split: bool
          If set to yes Tidy will use the input file to create a sequence
          of slides, splitting the markup prior to each successive <h2>.
          You can see an example of the results in a recent talk I made
          on XHTML. The slides are written to "slide1.html",
          "slide2.html" etc. The default is no.
          
   new-inline-tags: tag1, tag2, tag3
          Use this to declare new inline tags. The option takes a space
          or comma separated list of tag names. Unless you declare new
          tags, Tidy will refuse to generate a tidied file if the input
          includes previously unknown tags.
          
   new-blocklevel-tags: tag1, tag2, tag3
          Use this to declare new block-level tags. The option takes a
          space or comma separated list of tag names. Unless you declare
          new tags, Tidy will refuse to generate a tidied file if the
          input includes previously unknown tags.
          
    Sample Config File
    
// sample config file for HTML tidy
indent: auto
indent-spaces: 2
wrap: 72
markup: yes
clean: yes
output-xml: no
input-xml: no
show-warnings: yes
numeric-entities: yes
quote-marks: yes
quote-nbsp: yes
quote-ampersand: no
break-before-br: no
uppercase-tags: no
uppercase-attributes: no
output-xhtml: yes
char-encoding: latin1

  Downloadable Binaries
  
   If you are prepared to maintain a public URL for HTML Tidy compiled
   for a specific platform, please let me know so that I can add a link
   to your page. This will avoid the need for me to update this page
   whenether you recompile.
   
   Windows users! A free graphical user interface (HTML-Kit) for HTML
   Tidy is now available for windows 95/98/NT. Alternatively, you can get
   tidy in its native form as a Windows console program: tidy.exe, with
   the command options as per above.
   
   Mac users! You can now run HTML Tidy with FilterTop ( Screenshot), or
   as a command line interface application. My thanks to Terry Teague for
   this port.
   
   Amiga users! Keith Blakemore-Noble has compiled Tidy for the Amiga.
   
   AIX executable for Tidy! Compiled by Ciaran Deignan. The link is to a
   general download page. The executable is available for AIX 4.3.2 and
   later.
   
  Integrating Tidy as part of other Software
  
   You can also incorporate Tidy as part of a larger program, for
   instance in HTML editors or HTML transformation tools used for import
   filters, or for when you want to customize Web content to get the best
   out of different kinds of browsers. Imagine authoring clean HTML with
   CSS and at a touch of a button producing variants that look great and
   work reliably on a large variety of different browsers, taking into
   account the quirks of each. For instance, providing the ability to
   tune content for different versions of Netscape and Internet Explorer,
   and for browsers running on set-top boxes for televisions, handheld
   and palmtop devices, cellphones, and voice browsers. I am happy to
   quote for software development for such tools.
   
  Implementation details
  
   The code is in ANSI C and uses the C standard library for i/o. The
   parser is thread-safe although the code for pretty printing the parse
   tree is not (yet). The parser works top down, building a complete
   parse tree in memory. Document text is held as Unicode represented as
   UTF-8 in a character buffer that expands as needed. The code has so
   far been tested on Windows'95, Windows'98, Windows NT, Linux, FreeBSD,
   NetBSD, Ultrix, OSF, OS/MP, IRIX, NeXtStep, MacOS, BeOS, OS2, AIX,
   Amiga, SunOS, Solaris, IRIX and HP-UX, amongst others.
   
   tidy15apr99.tgz
          gzipped tar file for source code (Unix line ends)
          
   tidy15apr99.zip
          zipped source code (Windows line ends)
          
   tidy.exe
          Windows 95/NT executable (32-bit Windows console-mode program)
          
   tidy17dec98.ppc.tgz
          Gzipped archive of the binary for BeOS PPC R4. It also contains
          complete tidy distribution and Makefile.BeOS file for BeOS
          (from 17dec98 release of tidy).
          
   Tidy on OS/2
          Zipped archive of the OS/2 release of tidy, as compiled by Kaz
          SHiMZ <kshimz@sfc.co.jp>
          
   platform.h, html.h
          the include files with common definitions
          
   config.c
          support for customizing Tidy via config files
          
   lexer.c
          lexical analysis and buffer management
          
   parser.c
          HTML and XML parsers
          
   tags.c
          dictionary of tags and their properties
          
   attrs.c
          dictionary of attributes and their properties
          
   istack.c
          stack of active inline elements
          
   entities.c
          dictionary of entities
          
   clean.c
          smarts for cleaning up presentational markup
          
   pprint.c
          pretty printing for HTML and XML
          
   localize.c
          Change this file to localize tidy's messages
          
   tidy.c
          main() and error reporting routines
          
   Makefile
          Makefile for gcc
          
   Conventions for whether lines end with CRLF, LF or CR vary from one
   system to another. I have included the C source for a utility
   tab2space which can be used to ensure that files use the line end
   convention of your choice, and to expand tabs to spaces.
   tab2space -t4 -unix *.h *.c
   tab2space -tabs -unix Makefile

   Note use of "-tabs" to ensure that tabs are preserved in the Makefile
   (it won't work without them!).
   
   For those of you on Unix, here is a script you can use to strip
   carriage returns:
#!/bin/sh
echo Stripping Carriage Returns from files...
for i
do
        # If a writable file
        if [ -f $i ]
        then
                if [ -w $i ]
                then
                        echo $i
                        # strip CRs from input and output to temp file
                        tr -d '\015' < $i > toix.tmp
                        mv toix.tmp $i
                else
                        echo $i: write-protected
                fi
        else
                echo $i: not a file
        fi
done

   Save this script to a file, e.g. "scripcr" and use "chmod +x stripcr"
   to make it executable. You can then run it as "stripcr *.c *.h
   Overview.html Makefile"
   
Acknowledgements

   I would like to thank the many people who have written to me with
   suggestions for improvements or reporting bugs. Your help has been
   invaluable.
   
     Drew Adams, Jacob Sparre Andersen, Osma Ahvenlampi, Joe D'Andrea,
     Jerry Andrews, Chang Hyun Baek, Chuck Baslock, Christer Bernerus,
     Keith Blakemore-Noble, Eric Blossom, David Brooke, Andy Brown,
     Keith B. Brown, Andreas Buchholz, Maurice Buxton, Jelks Cabaniss,
     Trevor Carden, Terry Cassidy, Mathew Cepl, Kendall Clark, Jeremy
     Clulow, Dan Connolly, Keith Davies, Claus Andr Frber, Stephanie
     Foott, Rene Fritz, Francisco Guardiola David Getchell, Michael
     Giroux, Guus Goos, La Gris, Francisco Guardiola, Juha Hiki, G.
     Ken Holman, Craig Horman, Jack Horsfield, Rick Jelliffe, Craig
     Johnson, Charles LaFountain, Steven Lobo, Zdenek Kabelac, Michael
     Kay, Johannes Koch, Rudy Kohut, Allan Kuchinsky, Nick Leverton,
     Dietmar Lippold, Gert-Jan C. Lokhorst, Anton Marsden, Shane
     McCarron, Ian McKellar, Chris Nappin, Ann Navarro, Allan Odgaard,
     Matt Oshry, Gerald Oskoboiny, Ernst Paalvast, Christian Pantel,
     Steven Pemberton, Xavier Plantefeve, Ross L. Richardson, Philip
     Riebold, Erik Rossen, Dan Rudman, Christian Ruetgers, Klaus
     Johannes Rusch, Eric Schindler, J. Schlauch, Christian Schler, Jim
     Seymour, Kazuyoshi Shimizu, Geoff Sinclair, Jo Smith, Rafi Stern,
     Michael J. Suzio, Oren Tirosh, John Tobler, Stuart Updegrave,
     Charles A. Upsdell, Larry W. Virden, Daniel Vogelheim, Jez Wain,
     Paul Ward, Jeff Young
     
   Dave Raggett <dsr@w3.org> is an engineer from Hewlett Packard's UK
   Laboratories, and works on assignment to the World Wide Web
   Consortium, where he is the W3C lead for HTML, Math and Voice
   Browsers.
