Release 1.4.0.

git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/branches/strict@682 48356398-32a2-884e-a903-53898d9a118a

CREDITS

@@ -2,6 +2,6 @@
 CREDITS
 
 Almost everything written by Edward Z. Yang (Ambush Commander).  Lots of thanks
-to the DevNetwork Community for their help (see docs/devnetwork.html for more
-details), Feyd especially (namely IPv6 and optimization).  Thanks to RSnake for
-letting me package his fantastic XSS cheatsheet for a smoketest.
+to the DevNetwork Community for their help (see docs/ref-devnetwork.html for
+more details), Feyd especially (namely IPv6 and optimization).  Thanks to RSnake
+for letting me package his fantastic XSS cheatsheet for a smoketest.

Doxyfile

@@ -3,8 +3,8 @@
 #---------------------------------------------------------------------------
 # Project related configuration options
 #---------------------------------------------------------------------------
-PROJECT_NAME           = HTMLPurifier
-PROJECT_NUMBER         = trunk
+PROJECT_NAME           = HTML Purifier
+PROJECT_NUMBER         = 1.4.0
 OUTPUT_DIRECTORY       = "C:/Documents and Settings/Edward/My Documents/My Webs/htmlpurifier/docs/doxygen"
 CREATE_SUBDIRS         = NO
 OUTPUT_LANGUAGE        = English
@@ -89,9 +89,12 @@ EXCLUDE                =
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       = */tests/* \
                          */benchmarks/* \
-                         */docs/phpdoc/* \
-                         */docs/doxygen/* \
-                         */test-settings.php
+                         */docs/* \
+                         */test-settings.php \
+                         */configdoc/* \
+                         */test-settings.php \
+                         */maintenance/* \
+                         */smoketests/*
 EXAMPLE_PATH           = 
 EXAMPLE_PATTERNS       = *
 EXAMPLE_RECURSIVE      = NO

INSTALL

@@ -2,89 +2,189 @@
 Install
     How to install HTML Purifier
 
-Being a library, there's no fancy GUI that will take you step-by-step through
-configuring database credentials and other mumbo-jumbo.  HTML Purifier is
-designed to run "out of the box."  Regardless, there are still a couple of
-things you should be mindful of.
+HTML Purifier is designed to run out of the box,  so actually using the library
+is extremely easy. (Although, if you were looking for a step-by-step
+installation GUI, you've come to the wrong place!)  The impatient can scroll
+down to the bottom of this INSTALL document to see the code, but you really
+should make sure a few things are properly done.
+
+Todo: Convert to using the array syntax for configuration.
+
+
+1.  Compatibility
+
+HTML Purifier works in both PHP 4 and PHP 5, from PHP 4.3.9 and up. It has no
+core dependencies with other libraries. (Whoopee!)
+
+Optional extensions are iconv (usually installed) and tidy (also common).
+If you use UTF-8 and don't plan on pretty-printing HTML, you can get away with
+not having either of these extensions.
 
 
 
-0.  Compatibility
+2.  Including the library
 
-HTML Purifier works in both PHP 4 and PHP 5.  I have run the test suite on
-these versions:
+Simply use:
 
-  - 4.3.9, 4.3.11
-  - 4.4.0, 4.4.4
-  - 5.0.0, 5.0.4
-  - 5.1.0, 5.1.5
+    require_once '/path/to/library/HTMLPurifier.auto.php';
 
-And can confidently say that HTML Purifier should work in all versions
-between and afterwards.  HTML Purifier definitely does not support PHP 4.2,
-and PHP 4.3 branch support may go further back than that, but I haven't tested
-any earlier versions.
+...and you're good to go.  Since HTML Purifier's codebase is fairly
+large, I recommend only including HTML Purifier when you need it.
 
-I have been unable to get PHP 5.0.5 working on my computer, so if someone
-wants to test that, be my guest.  All tests were done on Windows XP Home,
-but operating system is quite irrelevant in this particular case.
-
-
-
-1.  Including the proper files
-
-The library/ directory must be added to your path: HTML Purifier will not be
-able to find the necessary includes otherwise.  This is as simple as:
-
-    set_include_path('/path/to/htmlpurifier/library' . PATH_SEPARATOR . get_include_path());
-
-...replacing /path/to/htmlpurifier with the actual location of the folder. Don't
-worry, HTML Purifier is namespaced so unless you have another file named
-HTMLPurifier.php, the files won't collide with any of your includes.
-
-Then, it's a simple matter of including the base file:
+If you don't like your include_path to be fiddled around with, simply set
+HTML Purifier's library/ directory to the include path yourself and then:
 
     require_once 'HTMLPurifier.php';
 
-...and you're good to go.
+Only the contents in the library/ folder are necessary, so you can remove
+everything else when using HTML Purifier in a production environment.  
 
 
 
-2.  Preparing the proper environment
+3.  Preparing the proper output environment
 
-While no configuration is necessary, you first should take precautions regarding
-the other output HTML that the filtered content will be going along with.  Here
-is a (short) checklist:
+HTML Purifier is all about web-standards, so accordingly your webpages should
+be standards compliant.  HTML Purifier can deal with these doctypes:
 
- * Have I specified XHTML 1.0 Transitional as the doctype?
- * Have I specified UTF-8 as the character encoding?
+* XHTML 1.0 Transitional (default)
+* HTML 4.01 Transitional
 
-I cannot stress the importance of these two bullets enough.  Omitting either
-of them could have dire consequences not only for security but for plain
-old usability.  You can find a more in-depth discussion of why this is needed
-in docs/security.txt, in the meantime, try to change your output so this is
-the case.
+...and these character encodings:
 
-If, for some reason, you are unable to switch to UTF-8 immediately, you can
-switch HTML Purifier's encoding.  Note that the availability of encodings is
-dependent on iconv, and you'll be missing characters if the charset you
-choose doesn't have them.
+* UTF-8 (default)
+* Any encoding iconv supports (support is crippled for i18n though)
+
+The defaults are there for a reason: they are best-practice choices that
+should not be changed lightly.  For those of you in the dark, you can determine
+the doctype from this code in your HTML documents:
+
+    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+...and the character encoding from this code:
+
+    <meta http-equiv="Content-type" content="text/html;charset=ENCODING">
+
+For legacy codebases these declarations may be missing.  If that is the case,
+STOP, and read up on character encodings and doctypes (in that order).  Here
+are some links:
+
+* http://www.joelonsoftware.com/articles/Unicode.html
+* http://alistapart.com/stories/doctype/
+
+You may currently be vulnerable to XSS and other security threats, and HTML
+Purifier won't be able to fix that.
+
+
+
+4. Configuration
+
+HTML Purifier is designed to run out-of-the-box, but occasionally HTML
+Purifier needs to be told what to do.  If you answered no to any of these
+questions, read on, otherwise, you can skip to the next section (or, if you're
+into configuring things just for the heck of it, skip to 4.3).
+
+* Am I using UTF-8?
+* Am I using XHTML 1.0 Transitional?
+
+If you answered yes to any of these questions, instantiate a configuration
+object and read on:
 
     $config = HTMLPurifier_Config::createDefault();
-    $config->set('Core', 'Encoding', $encoding);
 
 
 
-3.   Using the code
+4.1. Setting a different character encoding
+
+You really shouldn't use any other encoding except UTF-8, especially if you
+plan to support multilingual websites (read section three for more details).
+However, switching to UTF-8 is not always immediately feasible, so we can
+adapt.
+
+HTML Purifier uses iconv to support other character encodings, as such,
+any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
+HTML Purifier supports with this code:
+
+    $config->set('Core', 'Encoding', /* put your encoding here */);
+
+An example usage for Latin-1 websites (the most common encoding for English
+websites):
+
+    $config->set('Core', 'Encoding', 'ISO-8859-1');
+
+Note that HTML Purifier's support for non-Unicode encodings is crippled by the
+fact that any character not supported by that encoding will be silently
+dropped, EVEN if it is ampersand escaped.  This is a current limitation of
+HTML Purifier that we are NOT actively working to fix.  Patches are welcome,
+but there are so many other gotchas and problems in I18N for non-Unicode
+encodings that this functionality is low priority.  See
+<http://ppewww.ph.gla.ac.uk/~flavell/charset/form-i18n.html> for a more
+detailed lowdown on the topic.
+
+
+
+4.2. Setting a different doctype
+
+For those of you stuck using HTML 4.01 Transitional, you can disable
+XHTML output like this:
+
+    $config->set('Core', 'XHTML', false);
+
+I recommend that you use XHTML, although not as much as I recommend UTF-8.  If
+your HTML 4.01 page validates, good for you!
+
+Currently, we can only guarantee transitional-complaint output, future
+versions will also allow strict-compliant output.
+
+
+
+4.3. Other settings
+
+There are more configuration directives which can be read about
+here: <http://hp.jpsband.org/live/configdoc/plain.html>  They're a bit boring,
+but they can help out for those of you who like to exert maximum control over
+your code.
+
+
+
+5.   Using the code
 
 The interface is mind-numbingly simple:
 
     $purifier = new HTMLPurifier();
-    $clean_html = $purifier->purify($dirty_html);
+    $clean_html = $purifier->purify( $dirty_html );
 
-Or, if you're using the configuration object:
+...or, if you're using the configuration object:
 
     $purifier = new HTMLPurifier($config);
-    $clean_html = $purifier->purify($dirty_html);
+    $clean_html = $purifier->purify( $dirty_html );
 
-That's it.  For more examples, check out docs/examples/.  Also, SLOW gives
-advice on what to do if HTML Purifier is slowing down your application.
+That's it!  For more examples, check out docs/examples/ (they aren't very
+different though).  Also, SLOW gives advice on what to do if HTML Purifier
+is slowing down your application.
+
+
+
+6.   Quick install
+
+If your website is in UTF-8 and XHTML Transitional, use this code:
+
+<?php
+    require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
+    
+    $purifier = new HTMLPurifier();
+    $clean_html = $purifier->purify($dirty_html);
+?>
+
+If your website is in a different encoding or doctype, use this code:
+
+<?php
+    require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
+    
+    $config = HTMLPurifier_Config::createDefault();
+    $config->set('Core', 'Encoding', 'ISO-8859-1'); //replace with your encoding
+    $config->set('Core', 'XHTML', true); //replace with false if HTML 4.01
+    $purifier = new HTMLPurifier($config);
+    
+    $clean_html = $purifier->purify($dirty_html);
+?>

NEWS

@@ -1,18 +1,173 @@
 NEWS ( CHANGELOG and HISTORY )                                     HTMLPurifier
 |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
 
+= KEY ====================
+    # Breaks back-compat
+    ! Feature
+    - Bugfix
+      + Sub-comment
+    . Internal change
+==========================
+
+1.4.0, released 2007-01-21
+! Implemented list-style-image, URIs now allowed in list-style
+! Implemented background-image, background-repeat, background-attachment
+  and background-position CSS properties. Shorthand property background
+  supports all of these properties.
+! Configuration documentation looks nicer
+! Added %Core.EscapeNonASCIICharacters to workaround loss of Unicode
+  characters while %Core.Encoding is set to a non-UTF-8 encoding.
+! Support for configuration directive aliases added
+! Config object can now be instantiated from ini files
+! YouTube preservation code added to the core, with two lines of code
+  you can add it as a filter to your code. See smoketests/preserveYouTube.php
+  for sample code.
+! Moved SLOW to docs/enduser-slow.html and added code examples
+- Replaced version check with functionality check for DOM (thanks Stephen
+  Khoo)
+. Added smoketest 'all.php', which loads all other smoketests via frames
+. Implemented AttrDef_CSSURI for url(http://google.com) style declarations
+. Added convenient single test selector form on test runner
+
+1.3.2, released 2006-12-25
+! HTMLPurifier object now accepts configuration arrays, no need to manually
+  instantiate a configuration object
+! Context object now accessible to outside
+! Added enduser-youtube.html, explains how to embed YouTube videos. See
+  also corresponding smoketest preserveYouTube.php.
+! Added purifyArray(), which takes a list of HTML and purifies it all
+! Added static member variable $version to HTML Purifier with PHP-compatible
+  version number string.
+- Fixed fatal error thrown by upper-cased language attributes
+- printDefinition.php: added labels, added better clarification
+. HTMLPurifier_Config::create() added, takes mixed variable and converts into
+  a HTMLPurifier_Config object.
+
+1.3.1, released 2006-12-06
+! Added HTMLPurifier.func.php stub for a convenient function to call the library
+- Fixed bug in RemoveInvalidImg code that caused all images to be dropped
+  (thanks to .mario for reporting this)
+. Standardized all attribute handling variables to attr, made it plural
+
+1.3.0, released 2006-11-26
+# Invalid images are now removed, rather than replaced with a dud
+  <img src="" alt="Invalid image" />. Previous behavior can be restored
+  with new directive %Core.RemoveInvalidImg set to false.
+! (X)HTML Strict now supported
+  + Transparently handles inline elements in block context (blockquote)
+! Added GET method to demo for easier validation, added 50kb max input size
+! New directive %HTML.BlockWrapper, for block-ifying inline elements
+! New directive %HTML.Parent, allows you to only allow inline content
+! New directives %HTML.AllowedElements and %HTML.AllowedAttributes to let
+  users narrow the set of allowed tags
+! <li value="4"> and <ul start="2"> now allowed in loose mode
+! New directives %URI.DisableExternalResources and %URI.DisableResources
+! New directive %Attr.DisableURI, which eliminates all hyperlinking
+! New directive %URI.Munge, munges URI so you can use some sort of redirector
+  service to avoid PageRank leaks or warn users that they are exiting your site.
+! Added spiffy new smoketest printDefinition.php, which lets you twiddle with
+  the configuration settings and see how the internal rules are affected.
+! New directive %URI.HostBlacklist for blocking links to bad hosts.
+  xssAttacks.php smoketest updated accordingly.
+- Added missing type to ChildDef_Chameleon
+- Remove Tidy option from demo if there is not Tidy available
+. ChildDef_Required guards against empty tags
+. Lookup table HTMLDefinition->info_flow_elements added
+. Added peace-of-mind variable initialization to Strategy_FixNesting
+. Added HTMLPurifier->info_parent_def, parent child processing made special
+. Added internal documents briefly summarizing future progression of HTML
+. HTMLPurifier_Config->getBatch($namespace) added
+. More lenient casting to bool from string in HTMLPurifier_ConfigSchema
+. Refactored ChildDef classes into their own files
+
+1.2.0, released 2006-11-19
+# ID attributes now disabled by default. New directives:
+  + %HTML.EnableAttrID - restores old behavior by allowing IDs
+  + %Attr.IDPrefix - %Attr.IDBlacklist alternative that munges all user IDs
+    so that they don't collide with your IDs
+  + %Attr.IDPrefixLocal - Same as above, but for when there are multiple
+    instances of user content on the page
+  + Profuse documentation on how to use these available in docs/enduser-id.txt
+! Added MODx plugin <http://modxcms.com/forums/index.php/topic,6604.0.html>
+! Added percent encoding normalization
+! XSS attacks smoketest given facelift
+! Configuration documentation now has table of contents
+! Added %URI.DisableExternal, which prevents links to external websites.  You
+  can also use %URI.Host to permit absolute linking to subdomains
+! Non-accessible resources (ex. mailto) blocked from embedded URIs (img src)
+- Type variable in HTMLDefinition was not being set properly, fixed
+- Documentation updated
+  + TODO added request Phalanger
+  + TODO added request Native compression
+  + TODO added request Remove redundant tags
+  + TODO added possible plaintext formatter for HTML Purifier documentation
+  + Updated ConfigDoc TODO
+  + Improved inline comments in AttrDef/Class.php, AttrDef/CSS.php
+    and AttrDef/Host.php
+  + Revamped documentation into HTML, along with misc updates
+- HTMLPurifier_Context doesn't throw a variable reference error if you attempt
+  to retrieve a non-existent variable
+. Switched to purify()-wide Context object registry
+. Refactored unit tests to minimize duplication
+. XSS attack sheet updated
+. configdoc.xml now has xml:space attached to default value nodes
+. Allow configuration directives to permit null values
+. Cleaned up test-cases to remove unnecessary swallowErrors()
+
+1.1.2, released 2006-09-30
+! Add HTMLPurifier.auto.php stub file that configures include_path
+- Documentation updated
+  + INSTALL document rewritten
+  + TODO added semi-lossy conversion
+  + API Doxygen docs' file exclusions updated
+  + Added notes on HTML versus XML attribute whitespace handling
+  + Noted that HTMLPurifier_ChildDef_Custom isn't being used
+  + Noted that config object's definitions are cached versions
+- Fixed lack of attribute parsing in HTMLPurifier_Lexer_PEARSax3
+- ftp:// URIs now have their typecodes checked
+- Hooked up HTMLPurifier_ChildDef_Custom's unit tests (they weren't being run)
+. Line endings standardized throughout project (svn:eol-style standardized)
+. Refactored parseData() to general Lexer class
+. Tester named "HTML Purifier" not "HTMLPurifier"
+
+1.1.1, released 2006-09-24
+! Configuration option to optionally Tidy up output for indentation to make up
+  for dropped whitespace by DOMLex (pretty-printing for the entire application
+  should be done by a page-wide Tidy)
+- Various documentation updates
+- Fixed parse error in configuration documentation script
+- Fixed fatal error in benchmark scripts, slightly augmented
+- As far as possible, whitespace is preserved in-between table children
+- Sample test-settings.php file included
+
+1.1.0, released 2006-09-16
+! Directive documentation generation using XSLT
+! XHTML can now be turned off, output becomes <br>
+- Made URI validator more forgiving: will ignore leading and trailing
+  quotes, apostrophes and less than or greater than signs.
+- Enforce alphanumeric namespace and directive names for configuration.
+- Table child definition made more flexible, will fix up poorly ordered elements
+. Renamed ConfigDef to ConfigSchema
+
+1.0.1, released 2006-09-04
+- Fixed slight bug in DOMLex attribute parsing
+- Fixed rejection of case-insensitive configuration values when there is a
+  set of allowed values.  This manifested in %Core.Encoding.
+- Fixed rejection of inline style declarations that had lots of extra
+  space in them.  This manifested in TinyMCE.
+
 1.0.0, released 2006-09-01
+! Shorthand CSS properties implemented: font, border, background, list-style
+! Basic color keywords translated into hexadecimal values
+! Table CSS properties implemented
+! Support for charsets other than UTF-8 (defined by iconv)
+! Malformed UTF-8 and non-SGML character detection and cleaning implemented
 - Fixed broken numeric entity conversion
-- Malformed UTF-8 and non-SGML character detection and cleaning implemented
 - API documentation completed
-- Shorthand CSS properties implemented: font, border, background, list-style
-- Basic color keywords translated into hexadecimal values
-- Table CSS properties implemented
-- (HTML|CSS)Definition de-singleton-ized
-- Support for charsets other than UTF-8 (defined by iconv)
+. (HTML|CSS)Definition de-singleton-ized
 
 1.0.0beta, released 2006-08-16
-- First public release, most functionality implemented. Notable omissions are:
-  . Shorthand CSS properties
-  . Table CSS properties
-  . Deprecated attribute transformations
+! First public release, most functionality implemented. Notable omissions are:
+  + Shorthand CSS properties
+  + Table CSS properties
+  + Deprecated attribute transformations

README

@@ -1,13 +1,22 @@
-
-README
-    All about HTMLPurifier
 
-HTMLPurifier is an HTML filtering solution.  It uses a unique combination of
-robust whitelists and agressive parsing to ensure that not only are XSS
-attacks thwarted, but the resulting HTML is standards compliant.
-
-See INSTALL on how to use the library.  See docs/ for more developer-oriented
-documentation as well as some code examples.  Users of TinyMCE or FCKeditor
-may be especially interested in WYSIWYG.
-
-HTMLPurifier can be found on the web at: http://hp.jpsband.org/
+README
+    All about HTML Purifier
+
+HTML Purifier is an HTML filtering solution that uses a unique combination 
+of robust whitelists and agressive parsing to ensure that not only are 
+XSS attacks thwarted, but the resulting HTML is standards compliant. 
+
+HTML Purifier is oriented towards richly formatted documents from 
+untrusted sources that require CSS and a full tag-set.  This library can 
+be configured to accept a more restrictive set of tags, but it won't be 
+as efficient as more bare-bones parsers. It will, however, do the job 
+right, which may be more important. 
+
+Places to go:
+
+* See INSTALL for a quick installation guide
+* See docs/ for developer-oriented documentation, code examples and
+  an in-depth installation guide.
+* See WYSIWYG for information on editors like TinyMCE and FCKeditor
+
+HTML Purifier can be found on the web at: http://hp.jpsband.org/

SLOW

@@ -1,34 +0,0 @@
-
-SLOW
-  also known as the HELP ME LIBRARY IS TOO SLOW MY PAGE TAKE TOO LONG LOAD page
-
-HTMLPurifier is a very powerful library.  But with power comes great
-responsibility, or, at least, longer execution times.  Remember, this
-library isn't lightly grazing over submitted HTML: it's deconstructing
-the whole thing, rigorously checking the parts, and then putting it
-back together.
-
-So, if it so turns out that HTMLPurifier is kinda too slow for outbound
-filtering, you've got a few options:
-
-1. Inbound filtering - perform filtering of HTML when it's submitted by the
-user.  Since the user is already submitting something, an extra half a
-second tacked on to the load time probably isn't going to be that huge of
-a problem.  Then, displaying the content is a simple a manner of outputting
-it directly from your database/filesystem.  The trouble with this method is
-that your user loses the original text, and when doing edits, will be
-handling the filtered text.  Of course, maybe that's a good thing.  If you
-don't mind a little extra complexity, you can try...
-
-2. Caching the filtered output - accept the submitted text and put it
-unaltered into the database, but then also generate a filtered version and
-stash that in the database.  Serve the filtered version to readers, and the
-unaltered version to editors.  If need be, you can invalidate the cache and
-have the cached filtered version be regenerated on the first page view.  Pros?
-Full data retention.  Cons?  It's more complicated.
-
-In short, inbound filtering is almost as simple as outbound filtering, but
-it has some drawbacks which cannot be fixed unless you save both the original
-and the filtered versions.
-
-There is a third option: profile and optimize HTMLPurifier yourself.  ;-)

TODO

@@ -1,50 +1,91 @@
 
 TODO List
 
-Ongoing
- - Lots of profiling, make it faster!
- - Plugins for major CMSes (very tricky issue)
+= KEY ====================
+    # Flagship
+    - Regular
+    ? At-risk
+==========================
 
-1.1 release
- - Directive documentation generation
- - Rewrite table's child definition to be faster, smart, and regexp free
- - Allow HTML 4.01 output (cosmetic changes to the generator)
+1.5 release
+ # Implement all non-essential attribute transforms, configurable
+ # URI validation routines tighter (see docs/dev-code-quality.html) (COMPLEX)
+ # Advanced URI filtering schemes (see docs/proposal-new-directives.txt)
+ # Error logging for filtering/cleanup procedures
+    - Requires I18N facilities to be created first (COMPLEX)
+ ? Configuration profiles: sets of directives that get set with one func call
+ - XSS-attempt detection
 
-1.2 release
- - Additional support for poorly written HTML
-    - Implement all non-essential attribute transforms
-    - Microsoft Word HTML cleaning (i.e. MsoNormal)
+1.6 release
+ # Add pre-packaged "levels" of cleaning (custom behavior already done)
+ - More fine-grained control over escaping behavior
+    - Silently drop content inbetween SCRIPT tags (can be generalized to allow
+      specification of elements that, when detected as foreign, trigger removal
+      of children, although unbalanced tags could wreck havoc (or at least
+      delete the rest of the document)).
+ - Allow specifying global attributes on a tag-by-tag basis in
+   %HTML.AllowAttributes
+ ? More user-friendly warnings when %HTML.Allow* attempts to specify a
+   tag or attribute that is not supported
+ - Parse TinyMCE whitelist into our %HTML.Allow* whitelists
 
-1.3 release
- - Make URI validation routines tighter (especially mailto)
- - More extensive URI filtering schemes
- - Allow for background-image and list-style-image (see above)
- - Distinguish between different types of URIs, for instance, a mailto URI
-   in IMG SRC is nonsensical
+1.7 release
+ # Additional support for poorly written HTML
+    - Microsoft Word HTML cleaning (i.e. MsoNormal, but research essential!)
+    - Friendly strict handling of <address> (block -> <br>)
+ - Remove redundant tags, ex. <u><u>Underlined</u></u>. Implementation notes:
+    1. Analyzing which tags to remove duplicants
+    2. Ensure attributes are merged into the parent tag
+    3. Extend the tag exclusion system to specify whether or not the
+    contents should be dropped or not (currently, there's code that could do
+    something like this if it didn't drop the inner text too.)
+ - Remove <span> tags that don't do anything (no attributes)
+ - Remove empty inline tags<i></i>
+ - Append something to duplicate IDs so they're still usable (impl. note: the
+   dupe detector would also need to detect the suffix as well)
 
 2.0 release
- - Add various "levels" of cleaning
-    - Related: Allow strict (X)HTML
-
-3.0 release
- - Extended HTML capabilities based on namespacing and tag transforms
-    - Hooks for adding custom processors to custom namespaced tags and
-      attributes, offer default implementation
+ # Legit token based CSS parsing (will require revamping almost every
+   AttrDef class)
+ # Formatters for plaintext (COMPLEX)
     - Auto-paragraphing (be sure to leverage fact that we know when things
       shouldn't be paragraphed, such as lists and tables).
-    - Lots of documentation and samples
+    - Linkify URLs
+    - Smileys
+    - Linkification for HTML Purifier docs: notably configuration and classes
 
-Unknown release (on a scratch-an-itch basis)
- - Silently drop content inbetween SCRIPT tags (can be generalized to allow
-   specification of elements that, when detected as foreign, trigger removal
-   of children, although unbalanced tags could wreck havoc (or at least delete
-   the rest of the document)).
+3.0 release
+ - Extended HTML capabilities based on namespacing and tag transforms (COMPLEX)
+    - Hooks for adding custom processors to custom namespaced tags and
+      attributes, offer default implementation
+    - Lots of documentation and samples
+ - Allow tags to be "armored", an internal flag that protects them
+   from validation and passes them out unharmed
+ - XHTML 1.1 support
  - Fixes for Firefox's inability to handle COL alignment props (Bug 915)
  - Automatically add non-breaking spaces to empty table cells when
    empty-cells:show is applied to have compatibility with Internet Explorer
- - Pretty-printing HTML (adds dependency of Generator to HTMLDefinition)
- - Non-lossy dumb alternate character encoding transformations, achieved by
-   numerically encoding all non-ASCII characters
+ - Convert RTL/LTR override characters to <bdo> tags, or vice versa on demand.
+   Also, enable disabling of directionality
+
+Ongoing
+ - Lots of profiling, make it faster!
+ - Plugins for major CMSes (COMPLEX)
+    - WordPress
+    - eFiction
+    - more! (look for ones that use WYSIWYGs)
+
+Unknown release (on a scratch-an-itch basis)
+ - Upgrade SimpleTest testing code to newest versions
+ - Have 'lang' attribute be checked against official lists
+ ? Semi-lossy dumb alternate character encoding transformations, achieved by
+   encoding all characters that have string entity equivalents
+
+Requested
+ ? Native content compression, whitespace stripping (don't rely on Tidy, make
+   sure we don't remove from <pre> or related tags)
 
 Wontfix
- - Non-lossy smart alternate character encoding transformations
+ - Non-lossy smart alternate character encoding transformations (unless
+   patch provided)
+ - Pretty-printing HTML, users can use Tidy on the output on entire page

WYSIWYG

@@ -1,6 +1,6 @@
 
 WYSIWYG - What You See Is What You Get
-    HTMLPurifier: A Pretty Good Fit for TinyMCE and FCKeditor
+    HTML Purifier: A Pretty Good Fit for TinyMCE and FCKeditor
 
 Javascript-based WYSIWYG editors, simply stated, are quite amazing.  But I've
 always been wary about using them due to security issues: they handle the
@@ -13,6 +13,10 @@ other markup languages still reign supreme.  Put simply: filtering HTML is
 hard work, and these WYSIWYG authors don't offer anything to alleviate that
 trouble.  Therein lies the solution:
 
-HTMLPurifier is perfect for filtering pure-HTML input from WYSIWYG editors.
+HTML Purifier is perfect for filtering pure-HTML input from WYSIWYG editors.
 
 Enough said.
+
+There is a proof-of-concept integration of HTML Purifier with the Mantis
+bugtracker at http://hp.jpsband.org/mantis/ You can see notes on how
+this integration was acheived at http://hp.jpsband.org/mantis_notes.txt

benchmarks/Lexer.php

@@ -3,15 +3,24 @@
 // emulates inserting a dir called HTMLPurifier into your class dir
 set_include_path(get_include_path() . PATH_SEPARATOR . '../library/');
 
-require_once 'HTMLPurifier/ConfigDef.php';
-require_once 'HTMLPurifier/Config.php';
-require_once 'HTMLPurifier/Lexer/DirectLex.php';
-require_once 'HTMLPurifier/Lexer/PEARSax3.php';
+@include_once '../test-settings.php';
 
-$LEXERS = array(
-    'DirectLex' => new HTMLPurifier_Lexer_DirectLex(),
-    'PEARSax3'  => new HTMLPurifier_Lexer_PEARSax3()
-);
+require_once 'HTMLPurifier/ConfigSchema.php';
+require_once 'HTMLPurifier/Config.php';
+
+$LEXERS = array();
+$RUNS = isset($GLOBALS['HTMLPurifierTest']['Runs'])
+    ? $GLOBALS['HTMLPurifierTest']['Runs'] : 2; 
+
+require_once 'HTMLPurifier/Lexer/DirectLex.php';
+$LEXERS['DirectLex'] = new HTMLPurifier_Lexer_DirectLex();
+
+if (!empty($GLOBALS['HTMLPurifierTest']['PEAR'])) {
+    require_once 'HTMLPurifier/Lexer/PEARSax3.php';
+    $LEXERS['PEARSax3'] = new HTMLPurifier_Lexer_PEARSax3();
+} else {
+    exit('PEAR required to perform benchmark.');
+}
 
 if (version_compare(PHP_VERSION, '5', '>=')) {
     require_once 'HTMLPurifier/Lexer/DOMLex.php';
@@ -56,9 +65,12 @@ class RowTimer extends Benchmark_Timer
             if ($standard == false) $standard = $v['diff'];
             
             $perc = $v['diff'] * 100 / $standard;
+            $bad_run = ($v['diff'] < 0);
             
-            $out .= '<td align="right">' . number_format($perc, 2, '.', '') .
-                   '%</td>';
+            $out .= '<td align="right"'.
+                   ($bad_run ? ' style="color:#AAA;"' : '').
+                   '>' . number_format($perc, 2, '.', '') .
+                   '%</td><td>'.number_format($v['diff'],4,'.','').'</td>';
             
         }
         
@@ -79,13 +91,13 @@ function print_lexers() {
 }
 
 function do_benchmark($name, $document) {
-    global $LEXERS;
+    global $LEXERS, $RUNS;
     
     $timer = new RowTimer($name);
     $timer->start();
     
     foreach($LEXERS as $key => $lexer) {
-        $tokens = $lexer->tokenizeHTML($document);
+        for ($i=0; $i<$RUNS; $i++) $tokens = $lexer->tokenizeHTML($document);
         $timer->setMarker($key);
     }
     
@@ -103,7 +115,7 @@ function do_benchmark($name, $document) {
 <table border="1">
 <tr><th>Case</th><?php
 foreach ($LEXERS as $key => $value) {
-    echo '<th>' . htmlspecialchars($key) . '</th>';
+    echo '<th colspan="2">' . htmlspecialchars($key) . '</th>';
 }
 ?></tr>
 <?php

benchmarks/ProfileDirectLex.php

@@ -2,7 +2,7 @@
 
 set_include_path(get_include_path() . PATH_SEPARATOR . '../library/');
 
-require_once 'HTMLPurifier/ConfigDef.php';
+require_once 'HTMLPurifier/ConfigSchema.php';
 require_once 'HTMLPurifier/Config.php';
 require_once 'HTMLPurifier/Lexer/DirectLex.php';
 

configdoc/generate.php

@@ -0,0 +1,220 @@
+<?php
+
+/**
+ * Generates XML and HTML documents describing configuration.
+ */
+
+/*
+TODO:
+- make XML format richer (see below)
+- extend XSLT transformation (see the corresponding XSLT file)
+- allow generation of packaged docs that can be easily moved
+- multipage documentation
+- determine how to multilingualize
+- factor out code into classes
+*/
+
+// ---------------------------------------------------------------------------
+// Check and configure environment
+
+if (version_compare('5', PHP_VERSION, '>')) exit('Requires PHP 5 or higher.');
+error_reporting(E_ALL);
+
+
+// ---------------------------------------------------------------------------
+// Include HTML Purifier library
+
+set_include_path('../library' . PATH_SEPARATOR . get_include_path());
+require_once 'HTMLPurifier.php';
+
+
+// ---------------------------------------------------------------------------
+// Setup convenience functions
+
+function appendHTMLDiv($document, $node, $html) {
+    global $purifier;
+    $html = $purifier->purify($html);
+    $dom_html = $document->createDocumentFragment();
+    $dom_html->appendXML($html);
+    
+    $dom_div = $document->createElement('div');
+    $dom_div->setAttribute('xmlns', 'http://www.w3.org/1999/xhtml');
+    $dom_div->appendChild($dom_html);
+    
+    $node->appendChild($dom_div);
+}
+
+
+// ---------------------------------------------------------------------------
+// Load copies of HTMLPurifier_ConfigDef and HTMLPurifier
+
+$schema = HTMLPurifier_ConfigSchema::instance();
+$purifier = new HTMLPurifier();
+
+
+// ---------------------------------------------------------------------------
+// Generate types.xml, a document describing the constraint "type"
+
+$types_document = new DOMDocument('1.0', 'UTF-8');
+$types_root = $types_document->createElement('types');
+$types_document->appendChild($types_root);
+$types_document->formatOutput = true;
+foreach ($schema->types as $name => $expanded_name) {
+    $types_type = $types_document->createElement('type', $expanded_name);
+    $types_type->setAttribute('id', $name);
+    $types_root->appendChild($types_type);
+}
+$types_document->save('types.xml');
+
+
+// ---------------------------------------------------------------------------
+// Generate configdoc.xml, a document documenting configuration directives
+
+$dom_document = new DOMDocument('1.0', 'UTF-8');
+$dom_root = $dom_document->createElement('configdoc');
+$dom_document->appendChild($dom_root);
+$dom_document->formatOutput = true;
+
+// add the name of the application
+$dom_root->appendChild($dom_document->createElement('title', 'HTML Purifier'));
+
+/*
+TODO for XML format:
+- create a definition (DTD or other) once interface stabilizes
+*/
+
+foreach($schema->info as $namespace_name => $namespace_info) {
+    
+    $dom_namespace = $dom_document->createElement('namespace');
+    $dom_root->appendChild($dom_namespace);
+    
+    $dom_namespace->setAttribute('id', $namespace_name);
+    $dom_namespace->appendChild(
+        $dom_document->createElement('name', $namespace_name)
+    );
+    $dom_namespace_description = $dom_document->createElement('description');
+    $dom_namespace->appendChild($dom_namespace_description);
+    appendHTMLDiv($dom_document, $dom_namespace_description,
+        $schema->info_namespace[$namespace_name]->description);
+    
+    foreach ($namespace_info as $name => $info) {
+        
+        if ($info->class == 'alias') continue;
+        
+        $dom_directive = $dom_document->createElement('directive');
+        $dom_namespace->appendChild($dom_directive);
+        
+        $dom_directive->setAttribute('id', $namespace_name . '.' . $name);
+        $dom_directive->appendChild(
+            $dom_document->createElement('name', $name)
+        );
+        
+        $dom_constraints = $dom_document->createElement('constraints');
+        $dom_directive->appendChild($dom_constraints);
+        
+        $dom_type = $dom_document->createElement('type', $info->type);
+        if ($info->allow_null) {
+            $dom_type->setAttribute('allow-null', 'yes');
+        }
+        $dom_constraints->appendChild($dom_type);
+        
+        if ($info->allowed !== true) {
+            $dom_allowed = $dom_document->createElement('allowed');
+            $dom_constraints->appendChild($dom_allowed);
+            foreach ($info->allowed as $allowed => $bool) {
+                $dom_allowed->appendChild(
+                    $dom_document->createElement('value', $allowed)
+                );
+            }
+        }
+        
+        $raw_default = $schema->defaults[$namespace_name][$name];
+        if (is_bool($raw_default)) {
+            $default = $raw_default ? 'true' : 'false';
+        } elseif (is_string($raw_default)) {
+            $default = "\"$raw_default\"";
+        } elseif (is_null($raw_default)) {
+            $default = 'null';
+        } else {
+            $default = print_r(
+                    $schema->defaults[$namespace_name][$name], true
+                );
+        }
+        
+        $dom_default = $dom_document->createElement('default', $default);
+        
+        // remove this once we get a DTD
+        $dom_default->setAttribute('xml:space', 'preserve');
+        
+        $dom_constraints->appendChild($dom_default);
+        
+        $dom_descriptions = $dom_document->createElement('descriptions');
+        $dom_directive->appendChild($dom_descriptions);
+        
+        foreach ($info->descriptions as $file => $file_descriptions) {
+            foreach ($file_descriptions as $line => $description) {
+                $dom_description = $dom_document->createElement('description');
+                $dom_description->setAttribute('file', $file);
+                $dom_description->setAttribute('line', $line);
+                appendHTMLDiv($dom_document, $dom_description, $description);
+                $dom_descriptions->appendChild($dom_description);
+            }
+        }
+        
+    }
+    
+}
+
+// print_r($dom_document->saveXML());
+
+// save a copy of the raw XML
+$dom_document->save('configdoc.xml');
+
+
+// ---------------------------------------------------------------------------
+// Generate final output using XSLT
+
+// load the stylesheet
+$xsl_stylesheet_name = 'plain';
+$xsl_stylesheet = "styles/$xsl_stylesheet_name.xsl";
+$xsl_dom_stylesheet = new DOMDocument();
+$xsl_dom_stylesheet->load($xsl_stylesheet);
+
+// setup the XSLT processor
+$xsl_processor = new XSLTProcessor();
+
+// perform the transformation
+$xsl_processor->importStylesheet($xsl_dom_stylesheet);
+$html_output = $xsl_processor->transformToXML($dom_document);
+
+// some slight fudges to preserve backwards compatibility
+$html_output = str_replace('/>', ' />', $html_output); // <br /> not <br>
+$html_output = str_replace(' xmlns=""', '', $html_output); // rm unnecessary xmlns
+
+if (class_exists('Tidy')) {
+    // cleanup output
+    $config = array(
+        'indent'        => true,
+        'output-xhtml'  => true,
+        'wrap'          => 80
+    );
+    $tidy = new Tidy;
+    $tidy->parseString($html_output, $config, 'utf8');
+    $tidy->cleanRepair();
+    $html_output = (string) $tidy;
+}
+
+// write it to a file (todo: parse into seperate pages)
+file_put_contents("$xsl_stylesheet_name.html", $html_output);
+
+
+// ---------------------------------------------------------------------------
+// Output for instant feedback
+
+if (php_sapi_name() != 'cli') {
+    echo $html_output;
+} else {
+    echo 'Files generated successfully.';
+}
+
+?>

configdoc/styles/plain.css

@@ -0,0 +1,24 @@
+
+body {margin:1em 4em;}
+
+table {border-collapse:collapse;}
+table td, table th {padding:0.2em;}
+
+table.constraints {margin:0 0 1em;}
+table.constraints th {text-align:left;padding-left:0.4em;}
+table.constraints td {padding-right:0.4em;}
+table.constraints td pre {margin:0;}
+
+#toc {list-style-type:none; font-weight:bold;}
+#toc ul {list-style-type:disc; font-weight:normal;}
+
+.description p {margin-top:0;margin-bottom:1em;}
+
+#library, h1 {text-align:center; font-family:Garamond, serif;
+  font-variant:small-caps;}
+#library {font-size:1em;}
+h1 {margin-top:0;}
+h2 {border-bottom:1px solid #CCC; font-family:sans-serif; font-weight:normal;
+    font-size:1.3em;}
+h3 {font-family:sans-serif; font-size:1.1em; font-weight:bold; }
+h4 {font-family:sans-serif; font-size:0.9em; font-weight:bold; }

configdoc/styles/plain.xsl

@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet
+    version     = "1.0"
+    xmlns       = "http://www.w3.org/1999/xhtml"
+    xmlns:xsl   = "http://www.w3.org/1999/XSL/Transform"
+>
+    <xsl:output
+        method      = "xml"
+        encoding    = "UTF-8"
+        doctype-public = "-//W3C//DTD XHTML 1.0 Transitional//EN"
+        doctype-system = "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
+        indent = "no"
+        media-type = "text/html"
+    />
+    
+    <xsl:variable name="typeLookup" select="document('../types.xml')" />
+    
+    <xsl:template match="/">
+        <html lang="en" xml:lang="en">
+            <head>
+                <title>Configuration Documentation - <xsl:value-of select="/configdoc/title" /></title>
+                <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
+                <link rel="stylesheet" type="text/css" href="styles/plain.css" />
+            </head>
+            <body>
+                <div id="library"><xsl:value-of select="/configdoc/title" /></div>
+                <h1>Configuration Documentation</h1>
+                <h2>Table of Contents</h2>
+                <ul id="toc">
+                    <xsl:apply-templates mode="toc" />
+                </ul>
+                <xsl:apply-templates />
+            </body>
+        </html>
+    </xsl:template>
+    
+    <xsl:template match="title" mode="toc" />
+    <xsl:template match="namespace" mode="toc">
+        <xsl:if test="count(directive)&gt;0">
+            <li>
+                <a href="#{@id}"><xsl:value-of select="name" /></a>
+                <ul>
+                    <xsl:apply-templates select="directive" mode="toc" />
+                </ul>
+            </li>
+        </xsl:if>
+    </xsl:template>
+    <xsl:template match="directive" mode="toc">
+        <li><a href="#{@id}"><xsl:value-of select="name" /></a></li>
+    </xsl:template>
+    
+    <xsl:template match="title" />
+    
+    <xsl:template match="namespace">
+        <xsl:apply-templates />
+        <xsl:if test="count(directive)=0">
+            <p>No configuration directives defined for this namespace.</p>
+        </xsl:if>
+    </xsl:template>
+    <xsl:template match="namespace/name">
+        <h2 id="{../@id}"><xsl:value-of select="." /></h2>
+    </xsl:template>
+    <xsl:template match="namespace/description">
+        <div class="description">
+            <xsl:copy-of select="div/node()" />
+        </div>
+    </xsl:template>
+    
+    <xsl:template match="directive">
+        <xsl:apply-templates />
+    </xsl:template>
+    <xsl:template match="directive/name">
+        <h3 id="{../@id}"><xsl:value-of select="../@id" /></h3>
+    </xsl:template>
+    <xsl:template match="directive/constraints">
+        <table class="constraints">
+            <xsl:apply-templates />
+            <!-- Calculated other values -->
+            <tr>
+                <th>Used by:</th>
+                <td>
+                    <xsl:for-each select="../descriptions/description">
+                        <xsl:if test="position()&gt;1">, </xsl:if>
+                        <xsl:value-of select="@file" />
+                    </xsl:for-each>
+                </td>
+            </tr>
+        </table>
+    </xsl:template>
+    <xsl:template match="directive//description">
+        <div class="description">
+            <xsl:copy-of select="div/node()" />
+        </div>
+    </xsl:template>
+    
+    <xsl:template match="constraints/type">
+        <tr>
+            <th>Type:</th>
+            <td>
+                <xsl:variable name="type" select="text()" />
+                <xsl:attribute name="class">type type-<xsl:value-of select="$type" /></xsl:attribute>
+                <xsl:value-of select="$typeLookup/types/type[@id=$type]/text()" />
+                <xsl:if test="@allow-null='yes'">
+                    (or null)
+                </xsl:if>
+            </td>
+        </tr>
+    </xsl:template>
+    <xsl:template match="constraints/allowed">
+        <tr>
+            <th>Allowed values:</th>
+            <td>
+                <xsl:for-each select="value"><!--
+                 --><xsl:if test="position()&gt;1">, </xsl:if>
+                    &quot;<xsl:value-of select="." />&quot;<!--
+             --></xsl:for-each>
+            </td>
+        </tr>
+    </xsl:template>
+    <xsl:template match="constraints/default">
+        <tr>
+            <th>Default:</th>
+            <td><pre><xsl:value-of select="." xml:space="preserve" /></pre></td>
+        </tr>
+    </xsl:template>
+    
+</xsl:stylesheet>

docs/code-quality.txt

@@ -1,40 +0,0 @@
-
-Code Quality Issues
-
-Okay, face it.  Programmers can get lazy, cut corners, or make mistakes. They
-also can do quick prototypes, and then forget to rewrite them later.  Well,
-while I can't list mistakes in here, I can list prototype-like segments
-of code that should be aggressively refactored after the beta is released.
-This does not list optimization issues, that needs to be done after intense
-profiling.
-
-Here we go:
-
-AttrDef
-    Class - doesn't support Unicode characters, uses regular expressions
-    Lang - code duplication, premature optimization, doesn't consult official
-        lists
-    Pixels/Length/MultiLength - implemented according to HTML spec (excludes
-        code reuse in CSS)
-    URI - multiple regular expressions, needs host validation routines factored
-        out for mailto scheme, IPv6 validation is broken (fringe), unintuitive
-        variable overwriting, missing validation for query, fragment and path,
-        no percent-encode fixing
-    CSS - parser doesn't accept advanced CSS (fringe)
-    Number - constructor interface is inconsistent with Integer
-AttrTransform - doesn't accept AttrContext, non-validating
-ChildDef - not-allowed nodes translated to text, likely invalid handling
-Config - "load configuration" hooks missing, rich set* accessors missing,
-    needs redefined relationship with the definitions
-Strategy
-    FixNesting - cannot bubble nodes out of structures
-    MakeWellFormed - insufficient automatic closing definitions (check HTML
-        spec for optional end tags).
-    RemoveForeignElements - should be run in parallel with MakeWellFormed
-URIScheme - needs to have callable generic checks
-    ftp - missing typecode check
-    mailto - doesn't validate emails
-    news - doesn't validate opaque path
-    nntp - doesn't constrain path
-EOL
-

docs/config-ideas.txt

@@ -1,46 +0,0 @@
-
-Configuration Ideas
-
-Here are some theoretical configuration ideas that we could implement some
-time.  Note the naming convention: %Namespace.Directive
-
-%Attr.IDPrefix - prefix all ids with this
-
-%Attr.RewriteFragments - if there's %Attr.IDPrefix we may want to transparently
-    rewrite the URLs we parse too.  However, we can only do it when it's a pure
-    anchor link, so it's not foolproof
-
-%Attr.ClassBlacklist,
-%Attr.ClassWhitelist,
-%Attr.ClassListMode - determines what classes are allowed. When
-    %Attr.ClassListMode is set to Blacklist, only allow those not in
-    %Attr.ClassBlacklist. When it's Whitelist, only allow those in
-    %Attr.ClassWhitelist.
-
-%Attr.LangAlphaOnly - designate whether or not to allow numerals in language
-    code subtags
-    * RFC 1766, the current standard referenced by XML, does not permit
-        numbers, but,
-    * RFC 3066, the superseding best practice standard since January 2001,
-        permits them.
-    We allow numbers by default, but you generally never see them
-    at all, which makes this a little more sane.
-
-%Attr.MaxWidth, 
-%Attr.MaxHeight - caps for width and height related checks.
-    (a hack in Pixels for an image crashing attack could be replaced by this)
-
-%URI.Munge - will munge all URIs to a different URI, which should redirect
-    the user to the applicable page. A urlencoded version of the URI
-    will replace any instances of %s in the string. One possible
-    string is 'http://www.google.com/url?q=%s'. Useful for preventing
-    pagerank from being sent to other sites
-
-%URI.AddRelNofollow - will add rel="nofollow" to all links, preventing the
-    spread of ill-gotten pagerank
-
-%URI.Host - host of website, for external link checks
-
-%URI.RelativeToAbsolute - transforms all relative URIs to absolute form
-
-%URI.DisableExternal - disable external links

docs/dev-code-quality.html

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="description" content="Discusses code quality issues and places that need to be refactored in HTML Purifier." />
+<link rel="stylesheet" type="text/css" href="./style.css" />
+
+<title>Code Quality Issues - HTML Purifier</title>
+
+</head><body>
+
+<h1>Code Quality Issues</h1>
+
+<div id="filing">Filed under Development</div>
+<div id="index">Return to the <a href="index.html">index</a>.</div>
+<div id="home"><a href="http://hp.jpsband.org/">HTML Purifier</a> End-User Documentation</div>
+
+<p>Okay, face it.  Programmers can get lazy, cut corners, or make mistakes. They
+also can do quick prototypes, and then forget to rewrite them later.  Well,
+while I can't list mistakes in here, I can list prototype-like segments
+of code that should be aggressively refactored.  This does not list
+optimization issues, that needs to be done after intense profiling.</p>
+
+<pre>
+docs/examples/demo.php - ad hoc HTML/PHP soup to the extreme
+
+AttrDef
+    Class - doesn't support Unicode characters (fringe); uses regular
+        expressions
+    Lang - code duplication; premature optimization
+    Length - easily mistaken for CSSLength
+    URI - multiple regular expressions; missing validation for parts (?)
+    CSS - parser doesn't accept advanced CSS (fringe)
+    Number - constructor interface inconsistent with Integer
+ConfigSchema - redefinition is a mess
+Strategy
+    FixNesting - cannot bubble nodes out of structures, duplicated checks
+        for special-case parent node
+    MakeWellFormed - insufficient automatic closing definitions (check HTML
+        spec for optional end tags, also, closing based on type (block/inline)
+        might be efficient).
+    RemoveForeignElements - should be run in parallel with MakeWellFormed
+URIScheme - needs to have callable generic checks
+    mailto - doesn't validate emails, doesn't validate querystring
+    news - doesn't validate opaque path
+    nntp - doesn't constrain path
+</pre>
+
+<div id="version">$Id$</div>
+
+</body></html>

docs/dev-naming.html

@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="description" content="Defines class naming conventions in HTML Purifier." />
+<link rel="stylesheet" type="text/css" href="./style.css" />
+
+<title>Naming Conventions - HTML Purifier</title>
+
+</head><body>
+
+<h1>Naming Conventions</h1>
+
+<div id="filing">Filed under Development</div>
+<div id="index">Return to the <a href="index.html">index</a>.</div>
+<div id="home"><a href="http://hp.jpsband.org/">HTML Purifier</a> End-User Documentation</div>
+
+<p>The classes in this library follow a few naming conventions, which may
+help you find the correct functionality more quickly.  Here they are:</p>
+
+<dl>
+
+<dt>All classes occupy the HTMLPurifier pseudo-namespace.</dt>
+    <dd>This means that all classes are prefixed with HTMLPurifier_.  As such, all
+    names under HTMLPurifier_ are reserved.  I recommend that you use the name
+    HTMLPurifierX_YourName_ClassName, especially if you want to take advantage
+    of HTMLPurifier_ConfigDef.</dd>
+
+<dt>All classes correspond to their path if library/ was in the include path</dt>
+    <dd>HTMLPurifier_AttrDef is located at HTMLPurifier/AttrDef.php; replace
+    underscores with slashes and append .php and you'll have the location of
+    the class.</dd>
+
+<dt>Harness and Test are reserved class names for unit tests</dt>
+    <dd>The suffix <code>Test</code> indicates that the class is a subclass of UnitTestCase
+    (of the Simpletest library) and is testable. "Harness" indicates a subclass
+    of UnitTestCase that is not meant to be run but to be extended into 
+    concrete test cases and contains custom test methods (i.e. assert*())</dd>
+
+<dt>Class names do not necessarily represent inheritance hierarchies</dt>
+    <dd>While we try to reflect inheritance in naming to some extent, it is not
+    guaranteed (for instance, none of the classes inherit from HTMLPurifier,
+    the base class).  However, all class files have the require_once
+    declarations to whichever classes they are tightly coupled to.</dd>
+
+<dt>Strategy has a meaning different from the Gang of Four pattern</dt>
+    <dd>In Design Patterns, the Gang of Four describes a Strategy object as
+    encapsulating an algorithm so that they can be switched at run-time.  While
+    our strategies are indeed algorithms, they are not meant to be substituted:
+    all must be present in order for proper functioning.</dd>
+
+<dt>Abbreviations are avoided</dt>
+    <dd>We try to avoid abbreviations as much as possible, but in some cases, 
+    abbreviated version is more readable than the full version. Here, we
+    list common abbreviations:
+    <ul>
+        <li>Attr to Attributes (note that it is plural, i.e. <code>$attr = array()</code>)</li>
+        <li>Def to Definition</li>
+        <li><code>$ret</code> is the value to be returned in a function</li>
+    </ul>
+    </dd>
+
+<dt>Ambiguity concerning the definition of Def/Definition</dt>
+    <dd>While a definition normally defines the structure/acceptable values of
+    an entity, most of the definitions in this application also attempt
+    to validate and fix the value.  I am unsure of a better name, as
+    "Validator" would exclude fixing the value, "Fixer" doesn't invoke
+    the proper image of "fixing" something, and "ValidatorFixer" is too long!
+    Some other suggestions were "Handler", "Reference", "Check", "Fix",
+    "Repair" and "Heal".</dd>
+
+<dt>Transform not Transformer</dt>
+    <dd>Transform is both a noun and a verb, and thus we define a "Transform" as
+    something that "transforms," leaving "Transformer" (which sounds like an
+    electrical device/robot toy).</dd>
+
+</dl>
+
+<div id="version">$Id$</div>
+
+</body></html>

docs/dev-optimization.html

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="description" content="Discusses possible methods of optimizing HTML Purifier." />
+<link rel="stylesheet" type="text/css" href="./style.css" />
+
+<title>Optimization - HTML Purifier</title>
+
+</head><body>
+
+<h1>Optimization</h1>
+
+<div id="filing">Filed under Development</div>
+<div id="index">Return to the <a href="index.html">index</a>.</div>
+<div id="home"><a href="http://hp.jpsband.org/">HTML Purifier</a> End-User Documentation</div>
+
+<p>Here are some possible optimization techniques we can apply to code sections if
+they turn out to be slow.  Be sure not to prematurely optimize: if you get
+that itch, put it here!</p>
+
+<ul>
+    <li>Make Tokens Flyweights (may prove problematic, probably not worth it)</li>
+    <li>Rewrite regexps into PHP code</li>
+    <li>Serialize the Definition object</li>
+    <li>Batch regexp validation (do as many per function call as possible)</li>
+    <li>Parallelize strategies</li>
+</ul>
+
+<div id="version">$Id$</div>
+
+</body></html>

docs/dev-progress.html

@@ -1,292 +1,302 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
-
-<title>HTMLPurifier Progress</title>
-
-<style type="text/css">
-
-td {padding-right:1em;border-bottom:1px solid #000;padding-left:0.5em;}
-th {text-align:left;padding-top:1.4em;font-size:13pt;
-    border-bottom:2px solid #000;background:#FFF;}
-thead th {text-align:left;padding:0.1em;background-color:#EEE;}
-
-.impl-yes {background:#9D9;}
-.impl-partial {background:#FFA;}
-.impl-no {background:#CCC;}
-
-.danger {color:#600;}
-.css1 {color:#060;}
-.required {font-weight:bold;}
-.feature {color:#999;}
-
-</style>
-
-</head><body>
-
-<h1>HTMLPurifier Progress</h1>
-
-<h2>Key</h2>
-
-<table cellspacing="0"><tbody>
-<tr><td class="impl-yes">Implemented</td></tr>
-<tr><td class="impl-partial">Partially implemented</td></tr>
-<tr><td class="impl-no">Will not implement</td></tr>
-<tr><td class="danger">Dangerous attribute/property</td></tr>
-<tr><td class="css1">Present in CSS1</td></tr>
-<tr><td class="feature">Feature, requires extra work</td></tr>
-</tbody></table>
-
-<h3>CSS</h3>
-
-<table cellspacing="0">
-
-<thead>
-<tr><th>Name</th><th>Notes</th></tr>
-</thead>
-
-<!--
-<tr><td>-</td><td>-</td></tr>
--->
-
-<tbody>
-<tr><th colspan="2">Standard</th></tr>
-<tr class="css1 impl-yes"><td>background-color</td><td>COMPOSITE(&lt;color&gt;, transparent)</td></tr>
-<tr class="css1 impl-yes"><td>background</td><td>SHORTHAND, only for color, see below for info on background-image and friends</td></tr>
-<tr class="css1 impl-yes"><td>border</td><td>SHORTHAND, MULTIPLE</td></tr>
-<tr class="css1 impl-yes"><td>border-color</td><td>MULTIPLE</td></tr>
-<tr class="css1 impl-yes"><td>border-style</td><td>MULTIPLE</td></tr>
-<tr class="css1 impl-yes"><td>border-width</td><td>MULTIPLE</td></tr>
-<tr class="css1 impl-yes"><td>border-*</td><td>SHORTHAND</td></tr>
-<tr class="impl-yes"><td>border-*-color</td><td>COMPOSITE(&lt;color&gt;, transparent)</td></tr>
-<tr class="impl-yes"><td>border-*-style</td><td>ENUM(none, hidden, dotted, dashed,
-    solid, double, groove, ridge, inset, outset)</td></tr>
-<tr class="css1 impl-yes"><td>border-*-width</td><td>COMPOSITE(&lt;length&gt;, thin, medium, thick)</td></tr>
-<tr class="css1 impl-yes"><td>clear</td><td>ENUM(none, left, right, both)</td></tr>
-<tr class="css1 impl-yes"><td>color</td><td>&lt;color&gt;</td></tr>
-<tr class="css1 impl-yes"><td>float</td><td>ENUM(left, right, none), May require layout
-    precautions with clear</td></tr>
-<tr class="css1 impl-yes"><td>font</td><td>SHORTHAND</td></tr>
-<tr class="css1 impl-yes"><td>font-family</td><td>CSS validator may complain if fallback font
-    family not specified</td></tr>
-<tr class="css1 impl-yes"><td>font-size</td><td>COMPOSITE(&lt;absolute-size&gt;,
-    &lt;relative-size&gt;, &lt;length&gt;, &lt;percentage&gt;)</td></tr>
-<tr class="css1 impl-yes"><td>font-style</td><td>ENUM(normal, italic, oblique)</td></tr>
-<tr class="css1 impl-yes"><td>font-variant</td><td>ENUM(normal, small-caps)</td></tr>
-<tr class="css1 impl-yes"><td>font-weight</td><td>ENUM(normal, bold, bolder, lighter,
-    100, 200, 300, 400, 500, 600, 700, 800, 900), maybe special code for
-    in-between integers</td></tr>
-<tr class="css1 impl-yes"><td>letter-spacing</td><td>COMPOSITE(&lt;length&gt;, normal)</td></tr>
-<tr class="css1 impl-yes"><td>line-height</td><td>COMPOSITE(&lt;number&gt;,
-    &lt;length&gt;, &lt;percentage&gt;, normal)</td></tr>
-<tr class="css1 impl-yes"><td>list-style-position</td><td>ENUM(inside, outside),
-    Strange behavior in browsers</td></tr>
-<tr class="css1 impl-yes"><td>list-style-type</td><td>ENUM(...),
-    Well-supported values are: disc, circle, square,
-    decimal, lower-roman, upper-roman, lower-alpha and upper-alpha. See also
-    CSS 3. Mostly IE lack of support.</td></tr>
-<tr class="css1 impl-yes"><td>list-style</td><td>SHORTHAND, target milestone 1.0</td></tr>
-<tr class="css1 impl-yes"><td>margin</td><td>MULTIPLE</td></tr>
-<tr class="css1 impl-yes"><td>margin-*</td><td>COMPOSITE(&lt;length&gt;,
-    &lt;percentage&gt;, auto)</td></tr>
-<tr class="css1 impl-yes"><td>padding</td><td>MULTIPLE</td></tr>
-<tr class="css1 impl-yes"><td>padding-*</td><td>COMPOSITE(&lt;length&gt;(positive),
-    &lt;percentage&gt;(positive))</td></tr>
-<tr class="css1 impl-yes"><td>text-align</td><td>ENUM(left, right,
-    center, justify)</td></tr>
-<tr class="css1 impl-yes"><td>text-decoration</td><td>No blink (argh my eyes), not
-    enum, can be combined (composite sorta): underline, overline,
-    line-through</td></tr>
-<tr class="css1 impl-yes"><td>text-indent</td><td>COMPOSITE(&lt;length&gt;,
-    &lt;percentage&gt;)</td></tr>
-<tr class="css1 impl-yes"><td>text-transform</td><td>ENUM(capitalize, uppercase,
-    lowercase, none)</td></tr>
-<tr class="css1 impl-yes"><td>width</td><td>COMPOSITE(&lt;length&gt;,
-    &lt;percentage&gt;, auto), Interesting</td></tr>
-<tr class="css1 impl-yes"><td>word-spacing</td><td>COMPOSITE(&lt;length&gt;, auto),
-    IE 5 no support</td></tr>
-</tbody>
-
-<tbody>
-<tr><th colspan="2">Table</th></tr>
-<tr class="impl-yes"><td>border-collapse</td><td>ENUM(collapse, seperate)</td></tr>
-<tr class="impl-yes"><td>caption-side</td><td>ENUM(top, bottom)</td></tr>
-<tr class="feature"><td>empty-cells</td><td>ENUM(show, hide), No IE support makes this useless,
-    possible fix with &amp;nbsp;? Unknown release milestone.</td></tr>
-<tr class="impl-yes"><td>table-layout</td><td>ENUM(auto, fixed)</td></tr>
-<tr class="impl-yes css1"><td>vertical-align</td><td>COMPOSITE(ENUM(baseline, sub,
-    super, top, text-top, middle, bottom, text-bottom), &lt;percentage&gt;,
-    &lt;length&gt;) Also applies to others with explicit height</td></tr>
-</tbody>
-
-<tbody>
-<tr><th colspan="2">Absolute positioning, unknown release milestone</th></tr>
-<tr class="danger"><td>bottom</td><td rowspan="4">Dangerous, must be non-negative</td></tr>
-<tr class="danger"><td>left</td></tr>
-<tr class="danger"><td>right</td></tr>
-<tr class="danger"><td>top</td></tr>
-<tr><td>clip</td><td>-</td></tr>
-<tr class="danger"><td>position</td><td>ENUM(static, relative, absolute, fixed), permit
-    relative not absolute?</td></tr>
-<tr class="danger"><td>z-index</td><td>Dangerous</td></tr>
-</tbody>
-
-<tbody>
-<tr><th colspan="2">Unknown</th></tr>
-<tr class="danger css1"><td>background-image</td><td>Dangerous, target milestone 1.3</td></tr>
-<tr class="css1"><td>background-attachment</td><td>ENUM(scroll, fixed),
-    Depends on background-image</td></tr>
-<tr class="css1"><td>background-position</td><td>Depends on background-image</td></tr>
-<tr class="danger impl-no"><td>cursor</td><td>Dangerous but fluffy</td></tr>
-<tr class="danger css1"><td>display</td><td>ENUM(...), Dangerous but interesting;
-    will not implement list-item, run-in (Opera only) or table (no IE);
-    inline-block has incomplete IE6 support and requires -moz-inline-box
-    for Mozilla. Unknown target milestone.</td></tr>
-<tr><td class="css1">height</td><td>Interesting, why use it? Unknown target milestone.</td></tr>
-<tr class="danger css1"><td>list-style-image</td><td>Dangerous? Target milestone 1.3</td></tr>
-<tr class="impl-no"><td>max-height</td><td rowspan="4">No IE 5/6</td></tr>
-<tr class="impl-no"><td>min-height</td></tr>
-<tr class="impl-no"><td>max-width</td></tr>
-<tr class="impl-no"><td>min-width</td></tr>
-<tr class="impl-no"><td>orphans</td><td>No IE support</td></tr>
-<tr class="impl-no"><td>widows</td><td>No IE support</td></tr>
-<tr><td>overflow</td><td>ENUM, IE 5/6 almost (remove visible if set). Unknown target milestone.</td></tr>
-<tr><td>page-break-after</td><td>ENUM(auto, always, avoid, left, right),
-    IE 5.5/6 and Opera. Unknown target milestone.</td></tr>
-<tr><td>page-break-before</td><td>ENUM(auto, always, avoid, left, right),
-    Mostly supported. Unknown target milestone.</td></tr>
-<tr><td>page-break-inside</td><td>ENUM(avoid, auto), Opera only. Unknown target milestone.</td></tr>
-<tr class="impl-no"><td>quotes</td><td>May be dropped from CSS2, fairly useless for inline context</td></tr>
-<tr class="impl-no"><td>visibility</td><td>ENUM(visible, hidden, collapse),
-    Dangerous</td></tr>
-<tr class="css1 feature"><td>white-space</td><td>ENUM(normal, pre, nowrap, pre-wrap,
-    pre-line), Spotty implementation:
-    pre (no IE 5/6), nowrap (no IE 5),
-    pre-wrap (only Opera), pre-line (no support). Fixable? Unknown target milestone.</td></tr>
-</tbody>
-
-<tbody class="impl-no">
-<tr><th colspan="2">Aural</th></tr>
-<tr><td>azimuth</td><td>-</td></tr>
-<tr><td>cue</td><td>-</td></tr>
-<tr><td>cue-after</td><td>-</td></tr>
-<tr><td>cue-before</td><td>-</td></tr>
-<tr><td>elevation</td><td>-</td></tr>
-<tr><td>pause-after</td><td>-</td></tr>
-<tr><td>pause-before</td><td>-</td></tr>
-<tr><td>pause</td><td>-</td></tr>
-<tr><td>pitch-range</td><td>-</td></tr>
-<tr><td>pitch</td><td>-</td></tr>
-<tr><td>play-during</td><td>-</td></tr>
-<tr><td>richness</td><td>-</td></tr>
-<tr><td>speak-header</td><td>Table related</td></tr>
-<tr><td>speak-numeral</td><td>-</td></tr>
-<tr><td>speak-punctuation</td><td>-</td></tr>
-<tr><td>speak</td><td>-</td></tr>
-<tr><td>speech-rate</td><td>-</td></tr>
-<tr><td>stress</td><td>-</td></tr>
-<tr><td>voice-family</td><td>-</td></tr>
-<tr><td>volume</td><td>-</td></tr>
-</tbody>
-
-<tbody class="impl-no">
-<tr><th colspan="2">Will not implement</th></tr>
-<tr><td>content</td><td>Not applicable for inline styles</td></tr>
-<tr><td>counter-increment</td><td>Needs content, Opera only</td></tr>
-<tr><td>counter-reset</td><td>Needs content, Opera only</td></tr>
-<tr><td>direction</td><td>No support</td></tr>
-<tr><td>outline-color</td><td rowspan="4">IE Mac and Opera on outside,
-Mozilla on inside and needs -moz-outline, no IE support.</td></tr>
-    <tr><td>outline-style</td></tr>
-    <tr><td>outline-width</td></tr>
-    <tr><td>outline</td></tr>
-<tr><td>unicode-bidi</td><td>No support</td></tr>
-</tbody>
-
-</table>
-
-<h2>Interesting Attributes</h2>
-
-<table cellspacing="0">
-
-<thead>
-<tr><th>Attribute</th><th>Tags</th><th>Notes</th></tr>
-</thead>
-
-<!--
-<tr><th></th></tr>
-<tbody>
-<tr><td>-</td><td>-</td><td>-</td></tr>
-</tbody>
--->
-
-<tbody>
-<tr><th colspan="3">CSS</th></tr>
-<tr class="impl-yes"><td>style</td><td>All</td><td>Not all properties may be implemented, parser is good though.</td></tr>
-</tbody>
-
-<tbody>
-<tr><th colspan="3">Questionable</th></tr>
-<tr class="impl-no"><td>accesskey</td><td>A</td><td>May interfere with main interface</td></tr>
-<tr class="impl-no"><td>tabindex</td><td>A</td><td>May interfere with main interface</td></tr>
-<tr><td>target</td><td>A</td><td>Config enabled, only useful for frame layouts</td></tr>
-</tbody>
-
-<tbody>
-<tr><th colspan="3">Miscellaneous</th></tr>
-<tr><td>datetime</td><td>DEL, INS</td><td>No visible effect, ISO format</td></tr>
-<tr><td>rel</td><td>A</td><td>Largely user-defined: nofollow, tag (see microformats)</td></tr>
-<tr><td>rev</td><td>A</td><td>Largely user-defined: vote-*</td></tr>
-<tr class="feature"><td>axis</td><td>TD, TH</td><td>W3C only: No browser implementation</td></tr>
-<tr class="feature"><td>char</td><td>COL, COLGROUP, TBODY, TD, TFOOT, TH, THEAD, TR</td><td>W3C only: No browser implementation</td></tr>
-<tr class="feature"><td>headers</td><td>TD, TH</td><td>W3C only: No browser implementation</td></tr>
-<tr class="feature"><td>scope</td><td>TD, TH</td><td>W3C only: No browser implementation</td></tr>
-</tbody>
-
-<tbody class="impl-yes">
-<tr><th colspan="3">URI</th></tr>
-<tr><td rowspan="2">cite</td><td>BLOCKQUOTE, Q</td><td>For attribution</td></tr>
-    <tr><td>DEL, INS</td><td>Link to explanation why it changed</td></tr>
-<tr><td>href</td><td>A</td><td>-</td></tr>
-<tr><td>longdesc</td><td>IMG</td><td>-</td></tr>
-<tr class="required"><td>src</td><td>IMG</td><td>Required</td></tr>
-</tbody>
-
-<tbody>
-<tr><th colspan="3">Transform, target milestone 1.2</th></tr>
-<tr><td rowspan="5">align</td><td>CAPTION</td><td>Near-equiv style 'caption-side', drop left and right</td></tr>
-    <tr><td>IMG</td><td rowspan="2">Margin-left and margin-right = auto or parent div</td></tr>
-    <tr><td>TABLE</td></tr>
-    <tr><td>HR</td><td>Equivalent style 'text-align' (IE tested)</td></tr>
-    <tr class="impl-yes"><td>H1, H2, H3, H4, H5, H6, P</td><td>Equivalent style 'text-align'</td></tr>
-<tr class="required impl-yes"><td>alt</td><td>IMG</td><td>Required, insert image filename if src is present or default invalid image text</td></tr>
-<tr><td rowspan="3">bgcolor</td><td>TABLE</td><td>Equivalent style 'background-color' (IE tested)</td></tr>
-    <tr><td>TR</td><td>Equivalent style 'background-color' (IE tested)</td></tr>
-    <tr><td>TD, TH</td><td>Equivalent style 'background-color'</td></tr>
-<tr><td>border</td><td>IMG</td><td>Equivalent style 'border-width', only applies when link present</td></tr>
-<tr><td>clear</td><td>BR</td><td>Near-equiv style 'clear', transform 'all' into 'both'</td></tr>
-<tr class="impl-no"><td>compact</td><td>DL, OL, UL</td><td>Boolean, needs custom CSS class; rarely used anyway</td></tr>
-<tr class="required impl-yes"><td>dir</td><td>BDO</td><td>Required, insert ltr (or configuration value) if none</td></tr>
-<tr><td>height</td><td>TD, TH</td><td>Near-equiv style 'height', needs px suffix if original was in pixels</td></tr>
-<tr><td>hspace</td><td>IMG</td><td>Near-equiv styles 'margin-top' and 'margin-bottom', needs px suffix</td></tr>
-<tr class="impl-yes"><td>lang</td><td>*</td><td>Copy value to xml:lang</td></tr>
-<tr><td rowspan="2">name</td><td>IMG</td><td>Turn into ID</td></tr>
-    <tr><td>A</td><td>Turn into ID? (not deprecated, though in which specs?)</td></tr>
-<tr><td>noshade</td><td>HR</td><td>Boolean, style 'border-style:solid;'</td></tr>
-<tr><td>nowrap</td><td>TD, TH</td><td>Boolean, style 'white-space:nowrap;' (not compat with IE5)</td></tr>
-<tr><td>size</td><td>HR</td><td>Near-equiv 'width', needs px suffix if original was pixels</td></tr>
-<tr class="required impl-yes"><td>src</td><td>IMG</td><td>Required, insert blank or default img if not set</td></tr>
-<tr><td>start</td><td>OL</td><td>Poorly supported 'counter-reset', transform may not be desirable</td></tr>
-<tr><td rowspan="3">type</td><td>LI</td><td rowspan="3">Equivalent style 'list-style-type', different allowed values though. (needs testing)</td></tr>
-    <tr><td>OL</td></tr>
-    <tr><td>UL</td></tr>
-<tr><td>value</td><td>LI</td><td>Poorly supported 'counter-reset', transform may not be desirable, see ol.start. Configurable.</td></tr>
-<tr><td>vspace</td><td>IMG</td><td>Near-equiv styles 'margin-left' and 'margin-right', needs px suffix, see hspace</td></tr>
-<tr><td rowspan="2">width</td><td>HR</td><td rowspan="2">Near-equiv style 'width', needs px suffix if original was pixels</td></tr>
-    <tr><td>TD, TH</td></tr>
-</tbody>
-
-</table>
-
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="description" content="Tables detailing HTML element and CSS property implementation coverage in HTML Purifier." />
+<link rel="stylesheet" type="text/css" href="./style.css" />
+
+<title>Implementation Progress - HTML Purifier</title>
+
+<style type="text/css">
+
+td {padding-right:1em;border-bottom:1px solid #000;padding-left:0.5em;}
+th {text-align:left;padding-top:1.4em;font-size:13pt;
+    border-bottom:2px solid #000;background:#FFF;}
+thead th {text-align:left;padding:0.1em;background-color:#EEE;}
+
+.impl-yes {background:#9D9;}
+.impl-partial {background:#FFA;}
+.impl-no {background:#CCC;}
+
+.danger {color:#600;}
+.css1 {color:#060;}
+.required {font-weight:bold;}
+.feature {color:#999;}
+
+</style>
+
+</head><body>
+
+<h1>Implementation Progress</h1>
+
+<div id="filing">Filed under Development</div>
+<div id="index">Return to the <a href="index.html">index</a>.</div>
+<div id="home"><a href="http://hp.jpsband.org/">HTML Purifier</a> End-User Documentation</div>
+
+<h2>Key</h2>
+
+<table cellspacing="0"><tbody>
+<tr><td class="impl-yes">Implemented</td></tr>
+<tr><td class="impl-partial">Partially implemented</td></tr>
+<tr><td class="impl-no">Will not implement</td></tr>
+<tr><td class="danger">Dangerous attribute/property</td></tr>
+<tr><td class="css1">Present in CSS1</td></tr>
+<tr><td class="feature">Feature, requires extra work</td></tr>
+</tbody></table>
+
+<h2>CSS</h2>
+
+<table cellspacing="0">
+
+<thead>
+<tr><th>Name</th><th>Notes</th></tr>
+</thead>
+
+<!--
+<tr><td>-</td><td>-</td></tr>
+-->
+
+<tbody>
+<tr><th colspan="2">Standard</th></tr>
+<tr class="css1 impl-yes"><td>background-color</td><td>COMPOSITE(&lt;color&gt;, transparent)</td></tr>
+<tr class="css1 impl-yes"><td>background</td><td>SHORTHAND, currently alias for background-color</td></tr>
+<tr class="css1 impl-yes"><td>border</td><td>SHORTHAND, MULTIPLE</td></tr>
+<tr class="css1 impl-yes"><td>border-color</td><td>MULTIPLE</td></tr>
+<tr class="css1 impl-yes"><td>border-style</td><td>MULTIPLE</td></tr>
+<tr class="css1 impl-yes"><td>border-width</td><td>MULTIPLE</td></tr>
+<tr class="css1 impl-yes"><td>border-*</td><td>SHORTHAND</td></tr>
+<tr class="impl-yes"><td>border-*-color</td><td>COMPOSITE(&lt;color&gt;, transparent)</td></tr>
+<tr class="impl-yes"><td>border-*-style</td><td>ENUM(none, hidden, dotted, dashed,
+    solid, double, groove, ridge, inset, outset)</td></tr>
+<tr class="css1 impl-yes"><td>border-*-width</td><td>COMPOSITE(&lt;length&gt;, thin, medium, thick)</td></tr>
+<tr class="css1 impl-yes"><td>clear</td><td>ENUM(none, left, right, both)</td></tr>
+<tr class="css1 impl-yes"><td>color</td><td>&lt;color&gt;</td></tr>
+<tr class="css1 impl-yes"><td>float</td><td>ENUM(left, right, none), May require layout
+    precautions with clear</td></tr>
+<tr class="css1 impl-yes"><td>font</td><td>SHORTHAND</td></tr>
+<tr class="css1 impl-yes"><td>font-family</td><td>CSS validator may complain if fallback font
+    family not specified</td></tr>
+<tr class="css1 impl-yes"><td>font-size</td><td>COMPOSITE(&lt;absolute-size&gt;,
+    &lt;relative-size&gt;, &lt;length&gt;, &lt;percentage&gt;)</td></tr>
+<tr class="css1 impl-yes"><td>font-style</td><td>ENUM(normal, italic, oblique)</td></tr>
+<tr class="css1 impl-yes"><td>font-variant</td><td>ENUM(normal, small-caps)</td></tr>
+<tr class="css1 impl-yes"><td>font-weight</td><td>ENUM(normal, bold, bolder, lighter,
+    100, 200, 300, 400, 500, 600, 700, 800, 900), maybe special code for
+    in-between integers</td></tr>
+<tr class="css1 impl-yes"><td>letter-spacing</td><td>COMPOSITE(&lt;length&gt;, normal)</td></tr>
+<tr class="css1 impl-yes"><td>line-height</td><td>COMPOSITE(&lt;number&gt;,
+    &lt;length&gt;, &lt;percentage&gt;, normal)</td></tr>
+<tr class="css1 impl-yes"><td>list-style-position</td><td>ENUM(inside, outside),
+    Strange behavior in browsers</td></tr>
+<tr class="css1 impl-yes"><td>list-style-type</td><td>ENUM(...),
+    Well-supported values are: disc, circle, square,
+    decimal, lower-roman, upper-roman, lower-alpha and upper-alpha. See also
+    CSS 3. Mostly IE lack of support.</td></tr>
+<tr class="css1 impl-yes"><td>list-style</td><td>SHORTHAND</td></tr>
+<tr class="css1 impl-yes"><td>margin</td><td>MULTIPLE</td></tr>
+<tr class="css1 impl-yes"><td>margin-*</td><td>COMPOSITE(&lt;length&gt;,
+    &lt;percentage&gt;, auto)</td></tr>
+<tr class="css1 impl-yes"><td>padding</td><td>MULTIPLE</td></tr>
+<tr class="css1 impl-yes"><td>padding-*</td><td>COMPOSITE(&lt;length&gt;(positive),
+    &lt;percentage&gt;(positive))</td></tr>
+<tr class="css1 impl-yes"><td>text-align</td><td>ENUM(left, right,
+    center, justify)</td></tr>
+<tr class="css1 impl-yes"><td>text-decoration</td><td>No blink (argh my eyes), not
+    enum, can be combined (composite sorta): underline, overline,
+    line-through</td></tr>
+<tr class="css1 impl-yes"><td>text-indent</td><td>COMPOSITE(&lt;length&gt;,
+    &lt;percentage&gt;)</td></tr>
+<tr class="css1 impl-yes"><td>text-transform</td><td>ENUM(capitalize, uppercase,
+    lowercase, none)</td></tr>
+<tr class="css1 impl-yes"><td>width</td><td>COMPOSITE(&lt;length&gt;,
+    &lt;percentage&gt;, auto), Interesting</td></tr>
+<tr class="css1 impl-yes"><td>word-spacing</td><td>COMPOSITE(&lt;length&gt;, auto),
+    IE 5 no support</td></tr>
+</tbody>
+
+<tbody>
+<tr><th colspan="2">Table</th></tr>
+<tr class="impl-yes"><td>border-collapse</td><td>ENUM(collapse, seperate)</td></tr>
+<tr class="impl-yes"><td>caption-side</td><td>ENUM(top, bottom)</td></tr>
+<tr class="feature"><td>empty-cells</td><td>ENUM(show, hide), No IE support makes this useless,
+    possible fix with &amp;nbsp;? Unknown release milestone.</td></tr>
+<tr class="impl-yes"><td>table-layout</td><td>ENUM(auto, fixed)</td></tr>
+<tr class="impl-yes css1"><td>vertical-align</td><td>COMPOSITE(ENUM(baseline, sub,
+    super, top, text-top, middle, bottom, text-bottom), &lt;percentage&gt;,
+    &lt;length&gt;) Also applies to others with explicit height</td></tr>
+</tbody>
+
+<tbody>
+<tr><th colspan="2">Absolute positioning, unknown release milestone</th></tr>
+<tr class="danger impl-no"><td>bottom</td><td rowspan="4">Dangerous, must be non-negative to even be considered,
+    but it's still possible to arbitrarily position by running over.</td></tr>
+<tr class="danger impl-no"><td>left</td></tr>
+<tr class="danger impl-no"><td>right</td></tr>
+<tr class="danger impl-no"><td>top</td></tr>
+<tr class="impl-no"><td>clip</td><td>-</td></tr>
+<tr class="danger impl-no"><td>position</td><td>ENUM(static, relative, absolute, fixed)
+    relative not absolute?</td></tr>
+<tr class="danger impl-no"><td>z-index</td><td>Dangerous</td></tr>
+</tbody>
+
+<tbody>
+<tr><th colspan="2">Unknown</th></tr>
+<tr class="danger css1 impl-yes"><td>background-image</td><td>Dangerous, target milestone 1.3</td></tr>
+<tr class="css1 impl-yes"><td>background-attachment</td><td>ENUM(scroll, fixed),
+    Depends on background-image</td></tr>
+<tr class="css1 impl-yes"><td>background-position</td><td>Depends on background-image</td></tr>
+<tr class="danger impl-no"><td>cursor</td><td>Dangerous but fluffy</td></tr>
+<tr class="danger css1"><td>display</td><td>ENUM(...), Dangerous but interesting;
+    will not implement list-item, run-in (Opera only) or table (no IE);
+    inline-block has incomplete IE6 support and requires -moz-inline-box
+    for Mozilla. Unknown target milestone.</td></tr>
+<tr class="css1"><td>height</td><td>Interesting, why use it? Unknown target milestone.</td></tr>
+<tr class="danger css1 impl-yes"><td>list-style-image</td><td>Dangerous?</td></tr>
+<tr class="impl-no"><td>max-height</td><td rowspan="4">No IE 5/6</td></tr>
+<tr class="impl-no"><td>min-height</td></tr>
+<tr class="impl-no"><td>max-width</td></tr>
+<tr class="impl-no"><td>min-width</td></tr>
+<tr class="impl-no"><td>orphans</td><td>No IE support</td></tr>
+<tr class="impl-no"><td>widows</td><td>No IE support</td></tr>
+<tr><td>overflow</td><td>ENUM, IE 5/6 almost (remove visible if set). Unknown target milestone.</td></tr>
+<tr><td>page-break-after</td><td>ENUM(auto, always, avoid, left, right),
+    IE 5.5/6 and Opera. Unknown target milestone.</td></tr>
+<tr><td>page-break-before</td><td>ENUM(auto, always, avoid, left, right),
+    Mostly supported. Unknown target milestone.</td></tr>
+<tr><td>page-break-inside</td><td>ENUM(avoid, auto), Opera only. Unknown target milestone.</td></tr>
+<tr class="impl-no"><td>quotes</td><td>May be dropped from CSS2, fairly useless for inline context</td></tr>
+<tr class="impl-no"><td>visibility</td><td>ENUM(visible, hidden, collapse),
+    Dangerous</td></tr>
+<tr class="css1 feature"><td>white-space</td><td>ENUM(normal, pre, nowrap, pre-wrap,
+    pre-line), Spotty implementation:
+    pre (no IE 5/6), nowrap (no IE 5),
+    pre-wrap (only Opera), pre-line (no support). Fixable? Unknown target milestone.</td></tr>
+</tbody>
+
+<tbody class="impl-no">
+<tr><th colspan="2">Aural</th></tr>
+<tr><td>azimuth</td><td>-</td></tr>
+<tr><td>cue</td><td>-</td></tr>
+<tr><td>cue-after</td><td>-</td></tr>
+<tr><td>cue-before</td><td>-</td></tr>
+<tr><td>elevation</td><td>-</td></tr>
+<tr><td>pause-after</td><td>-</td></tr>
+<tr><td>pause-before</td><td>-</td></tr>
+<tr><td>pause</td><td>-</td></tr>
+<tr><td>pitch-range</td><td>-</td></tr>
+<tr><td>pitch</td><td>-</td></tr>
+<tr><td>play-during</td><td>-</td></tr>
+<tr><td>richness</td><td>-</td></tr>
+<tr><td>speak-header</td><td>Table related</td></tr>
+<tr><td>speak-numeral</td><td>-</td></tr>
+<tr><td>speak-punctuation</td><td>-</td></tr>
+<tr><td>speak</td><td>-</td></tr>
+<tr><td>speech-rate</td><td>-</td></tr>
+<tr><td>stress</td><td>-</td></tr>
+<tr><td>voice-family</td><td>-</td></tr>
+<tr><td>volume</td><td>-</td></tr>
+</tbody>
+
+<tbody class="impl-no">
+<tr><th colspan="2">Will not implement</th></tr>
+<tr><td>content</td><td>Not applicable for inline styles</td></tr>
+<tr><td>counter-increment</td><td>Needs content, Opera only</td></tr>
+<tr><td>counter-reset</td><td>Needs content, Opera only</td></tr>
+<tr><td>direction</td><td>No support</td></tr>
+<tr><td>outline-color</td><td rowspan="4">IE Mac and Opera on outside,
+Mozilla on inside and needs -moz-outline, no IE support.</td></tr>
+    <tr><td>outline-style</td></tr>
+    <tr><td>outline-width</td></tr>
+    <tr><td>outline</td></tr>
+<tr><td>unicode-bidi</td><td>No support</td></tr>
+</tbody>
+
+</table>
+
+<h2>Interesting Attributes</h2>
+
+<table cellspacing="0">
+
+<thead>
+<tr><th>Attribute</th><th>Tags</th><th>Notes</th></tr>
+</thead>
+
+<!--
+<tr><th></th></tr>
+<tbody>
+<tr><td>-</td><td>-</td><td>-</td></tr>
+</tbody>
+-->
+
+<tbody>
+<tr><th colspan="3">CSS</th></tr>
+<tr class="impl-yes"><td>style</td><td>All</td><td>Parser is reasonably functional. Status here doesn't count individual properties.</td></tr>
+</tbody>
+
+<tbody>
+<tr><th colspan="3">Questionable</th></tr>
+<tr class="impl-no"><td>accesskey</td><td>A</td><td>May interfere with main interface</td></tr>
+<tr class="impl-no"><td>tabindex</td><td>A</td><td>May interfere with main interface</td></tr>
+<tr><td>target</td><td>A</td><td>Config enabled, only useful for frame layouts, disallowed in strict</td></tr>
+</tbody>
+
+<tbody>
+<tr><th colspan="3">Miscellaneous</th></tr>
+<tr><td>datetime</td><td>DEL, INS</td><td>No visible effect, ISO format</td></tr>
+<tr><td>rel</td><td>A</td><td>Largely user-defined: nofollow, tag (see microformats)</td></tr>
+<tr><td>rev</td><td>A</td><td>Largely user-defined: vote-*</td></tr>
+<tr class="feature"><td>axis</td><td>TD, TH</td><td>W3C only: No browser implementation</td></tr>
+<tr class="feature"><td>char</td><td>COL, COLGROUP, TBODY, TD, TFOOT, TH, THEAD, TR</td><td>W3C only: No browser implementation</td></tr>
+<tr class="feature"><td>headers</td><td>TD, TH</td><td>W3C only: No browser implementation</td></tr>
+<tr class="feature"><td>scope</td><td>TD, TH</td><td>W3C only: No browser implementation</td></tr>
+</tbody>
+
+<tbody class="impl-yes">
+<tr><th colspan="3">URI</th></tr>
+<tr><td rowspan="2">cite</td><td>BLOCKQUOTE, Q</td><td>For attribution</td></tr>
+    <tr><td>DEL, INS</td><td>Link to explanation why it changed</td></tr>
+<tr><td>href</td><td>A</td><td>-</td></tr>
+<tr><td>longdesc</td><td>IMG</td><td>-</td></tr>
+<tr class="required"><td>src</td><td>IMG</td><td>Required</td></tr>
+</tbody>
+
+<tbody>
+<tr><th colspan="3">Transform, target milestone 1.4</th></tr>
+<tr><td rowspan="5">align</td><td>CAPTION</td><td>Near-equiv style 'caption-side', drop left and right</td></tr>
+    <tr><td>IMG</td><td rowspan="2">Margin-left and margin-right = auto or parent div</td></tr>
+    <tr><td>TABLE</td></tr>
+    <tr><td>HR</td><td>Near-equivalent style 'text-align' (Works for IE and Opera, but not Firefox). Also try <code>margin-right:auto; margin-left:0;</code> for left or <code>margin-right:0; margin-left:auto;</code> for right (optionally replacing 0 with the original margin for that side)</td></tr>
+    <tr class="impl-yes"><td>H1, H2, H3, H4, H5, H6, P</td><td>Equivalent style 'text-align'</td></tr>
+<tr class="required impl-yes"><td>alt</td><td>IMG</td><td>Required, insert image filename if src is present or default invalid image text</td></tr>
+<tr><td rowspan="3">bgcolor</td><td>TABLE</td><td>Equivalent style 'background-color'</td></tr>
+    <tr><td>TR</td><td>Equivalent style 'background-color'</td></tr>
+    <tr><td>TD, TH</td><td>Equivalent style 'background-color'</td></tr>
+<tr><td>border</td><td>IMG</td><td>Near equivalent style 'border-width', as it only applies when link present</td></tr>
+<tr><td>clear</td><td>BR</td><td>Near-equiv style 'clear', transform 'all' into 'both'</td></tr>
+<tr class="impl-no"><td>compact</td><td>DL, OL, UL</td><td>Boolean, needs custom CSS class; rarely used anyway</td></tr>
+<tr class="required impl-yes"><td>dir</td><td>BDO</td><td>Required, insert ltr (or configuration value) if none</td></tr>
+<tr><td>height</td><td>TD, TH</td><td>Near-equiv style 'height', needs px suffix if original was in pixels</td></tr>
+<tr><td>hspace</td><td>IMG</td><td>Near-equiv styles 'margin-top' and 'margin-bottom', needs px suffix</td></tr>
+<tr class="impl-yes"><td>lang</td><td>*</td><td>Copy value to xml:lang</td></tr>
+<tr><td rowspan="2">name</td><td>IMG</td><td>Turn into ID</td></tr>
+    <tr><td>A</td><td>Turn into ID? (not deprecated, though in which specs?)</td></tr>
+<tr><td>noshade</td><td>HR</td><td>Boolean, style 'border-style:solid;'</td></tr>
+<tr><td>nowrap</td><td>TD, TH</td><td>Boolean, style 'white-space:nowrap;' (not compat with IE5)</td></tr>
+<tr><td>size</td><td>HR</td><td>Near-equiv 'width', needs px suffix if original was pixels</td></tr>
+<tr class="required impl-yes"><td>src</td><td>IMG</td><td>Required, insert blank or default img if not set</td></tr>
+<tr class="impl-yes"><td>start</td><td>OL</td><td>Poorly supported 'counter-reset', allowed in loose, dropped in strict</td></tr>
+<tr><td rowspan="3">type</td><td>LI</td><td rowspan="3">Equivalent style 'list-style-type', different allowed values though. (needs testing)</td></tr>
+    <tr><td>OL</td></tr>
+    <tr><td>UL</td></tr>
+<tr class="impl-yes"><td>value</td><td>LI</td><td>Poorly supported 'counter-reset', allowed in loose, dropped in strict</td></tr>
+<tr><td>vspace</td><td>IMG</td><td>Near-equiv styles 'margin-left' and 'margin-right', needs px suffix, see hspace</td></tr>
+<tr><td rowspan="2">width</td><td>HR</td><td rowspan="2">Near-equiv style 'width', needs px suffix if original was pixels</td></tr>
+    <tr><td>TD, TH</td></tr>
+</tbody>
+
+</table>
+
+<div id="version">$Id$</div>
+
 </body></html>

docs/dtd/xhtml1-purified.dtd

@@ -1,272 +0,0 @@
-<!-- Transform %TextAlign to align:value in style -->
-
-<!-- text alignment for p, div, h1-h6. The default is
-     align="left" for ltr headings, "right" for rtl
-     
-     Move to style! -->
-<!ENTITY % TextAlign "DEPRECATED align (left|center|right|justify) #IMPLIED">
-
-<!-- type and start should have CSS equivalents, but they'll need to
-be translated intelligently -->
-<!ENTITY % ULStyle "(disc|square|circle)">
-<!-- Ordered list numbering style
-
-    1   arabic numbers      1, 2, 3, ...
-    a   lower alpha         a, b, c, ...
-    A   upper alpha         A, B, C, ...
-    i   lower roman         i, ii, iii, ...
-    I   upper roman         I, II, III, ...
-
-    The style is applied to the sequence number which by default
-    is reset to 1 for the first list item in an ordered list.
--->
-<!ENTITY % OLStyle "CDATA">
-<!-- LIStyle is constrained to: "(%ULStyle;|%OLStyle;)" -->
-<!ENTITY % LIStyle "CDATA">
-
-<!ATTLIST ol
-  %attrs;
-  DEPRECATED type        %OLStyle;      #IMPLIED
-  DEPRECATED start       %Number;       #IMPLIED
-  >
-
-<!ATTLIST li
-  %attrs;
-  DEPRECATED type        %LIStyle;      #IMPLIED
-  DEPRECATED value       %Number;       #IMPLIED
-  >
-
-<!ATTLIST hr
-  %attrs;
-  DEPRECATED align       (left|center|right) #IMPLIED
-  DEPRECATED size        %Pixels;       #IMPLIED
-  DEPRECATED width       %Length;       #IMPLIED
-  >
-
-<!ATTLIST pre
-  %attrs;
-  DEPRECATED width       %Number;      #IMPLIED
-  >
-
-<!ATTLIST blockquote
-  %attrs;
-  cite        %URI;          #IMPLIED
-  >
-
-<!ATTLIST ins
-  %attrs;
-  cite        %URI;          #IMPLIED
-  datetime    %Datetime;     #IMPLIED
-  >
-<!ATTLIST del
-  %attrs;
-  cite        %URI;          #IMPLIED
-  datetime    %Datetime;     #IMPLIED
-  >
-
-<!ATTLIST a
-  %attrs;
-  name        NMTOKEN        #IMPLIED // ID
-  href        %URI;          #IMPLIED
-  rel         %LinkTypes;    #IMPLIED // needs policing
-  rev         %LinkTypes;    #IMPLIED // see rel
-  target      %FrameTarget;  #IMPLIED // usually not used, but might be
-  >
-
-<!ATTLIST bdo
-  %coreattrs; // !#!
-  lang        %LanguageCode; #IMPLIED
-  xml:lang    %LanguageCode; #IMPLIED
-  dir         (ltr|rtl)      #REQUIRED
-  >
-
-<!ATTLIST br
-  %coreattrs; // !#!
-  DEPRECATED clear       (left|all|right|none) "none"
-  >
-
-<!ELEMENT q %Inline;>   <!-- inlined quote -->
-<!ATTLIST q
-  %attrs;
-  cite        %URI;          #IMPLIED
-  >
-
-<!ATTLIST img
-  %attrs;
-  src         %URI;          #REQUIRED
-  alt         %Text;         #REQUIRED
-  DEPRECATED name        NMTOKEN        #IMPLIED // ID
-  longdesc    %URI;          #IMPLIED
-  height      %Length;       #IMPLIED // dubious, but we'll allow
-  width       %Length;       #IMPLIED //
-  DEPRECATED align       %ImgAlign;     #IMPLIED
-  DEPRECATED border      %Length;       #IMPLIED
-  DEPRECATED hspace      %Pixels;       #IMPLIED // left/right margin
-  DEPRECATED vspace      %Pixels;       #IMPLIED // up/down margin
-  >
-
-<!--
- The border attribute sets the thickness of the frame around the
- table. The default units are screen pixels.
-
- The frame attribute specifies which parts of the frame around
- the table should be rendered. The values are not the same as
- CALS to avoid a name clash with the valign attribute.
--->
-<!ENTITY % TFrame "(void|above|below|hsides|lhs|rhs|vsides|box|border)">
-
-<!--
- The rules attribute defines which rules to draw between cells:
-
- If rules is absent then assume:
-     "none" if border is absent or border="0" otherwise "all"
--->
-
-<!ENTITY % TRules "(none | groups | rows | cols | all)">
-  
-<!-- horizontal placement of table relative to document -->
-<!ENTITY % TAlign "(left|center|right)">
-
-<!-- horizontal alignment attributes for cell contents
-
-  char        alignment char, e.g. char=':'
-  charoff     offset for alignment char
--->
-<!ENTITY % cellhalign
-  "align      (left|center|right|justify|char) #IMPLIED
-   char       %Character;    #IMPLIED
-   charoff    %Length;       #IMPLIED"
-  >
-
-<!-- vertical alignment attributes for cell contents -->
-<!ENTITY % cellvalign
-  "valign     (top|middle|bottom|baseline) #IMPLIED"
-  >
-
-<!-- we may want to convert some of these nonetheless -->
-<!ATTLIST table
-  %attrs;
-  summary     %Text;         #IMPLIED
-  width       %Length;       #IMPLIED
-  border      %Pixels;       #IMPLIED
-  frame       %TFrame;       #IMPLIED
-  rules       %TRules;       #IMPLIED
-  cellspacing %Length;       #IMPLIED
-  cellpadding %Length;       #IMPLIED
-  DEPRECATED align       %TAlign;       #IMPLIED
-  DEPRECATED bgcolor     %Color;        #IMPLIED
-  >
-
-<!ENTITY % CAlign "(top|bottom|left|right)">
-
-<!ATTLIST caption
-  %attrs;
-DEPRECATED  align       %CAlign;       #IMPLIED // watch, it's a special set
-  >
-
-<!--
-colgroup groups a set of col elements. It allows you to group
-several semantically related columns together.
--->
-<!ATTLIST colgroup
-  %attrs;
-  span        %Number;       "1"
-  width       %MultiLength;  #IMPLIED
-  %cellhalign; // very interesting
-  %cellvalign;
-  >
-
-<!--
- col elements define the alignment properties for cells in
- one or more columns.
-
- The width attribute specifies the width of the columns, e.g.
-
-     width=64        width in screen pixels
-     width=0.5*      relative width of 0.5
-
- The span attribute causes the attributes of one
- col element to apply to more than one column.
--->
-<!ATTLIST col
-  %attrs;
-  span        %Number;       "1"
-  width       %MultiLength;  #IMPLIED
-  %cellhalign;
-  %cellvalign;
-  >
-
-<!--
-    Use thead to duplicate headers when breaking table
-    across page boundaries, or for static headers when
-    tbody sections are rendered in scrolling panel.
-
-    Use tfoot to duplicate footers when breaking table
-    across page boundaries, or for static footers when
-    tbody sections are rendered in scrolling panel.
-
-    Use multiple tbody sections when rules are needed
-    between groups of table rows.
--->
-<!ATTLIST thead
-  %attrs;
-  %cellhalign;
-  %cellvalign;
-  >
-
-<!ATTLIST tfoot
-  %attrs;
-  %cellhalign;
-  %cellvalign;
-  >
-
-<!ATTLIST tbody
-  %attrs;
-  %cellhalign;
-  %cellvalign;
-  >
-
-<!ATTLIST tr
-  %attrs;
-  %cellhalign;
-  %cellvalign;
-DEPRECATED  bgcolor     %Color;        #IMPLIED
-  >
-
-<!-- Scope is simpler than headers attribute for common tables -->
-<!ENTITY % Scope "(row|col|rowgroup|colgroup)">
-
-<!-- th is for headers, td for data and for cells acting as both -->
-
-<!ATTLIST th
-  %attrs;
-  abbr        %Text;         #IMPLIED
-  axis        CDATA          #IMPLIED
-  headers     IDREFS         #IMPLIED
-  scope       %Scope;        #IMPLIED
-  rowspan     %Number;       "1"
-  colspan     %Number;       "1"
-  %cellhalign;
-  %cellvalign;
-DEPRECATED  nowrap      (nowrap)       #IMPLIED
-DEPRECATED  bgcolor     %Color;        #IMPLIED
-DEPRECATED  width       %Length;       #IMPLIED
-DEPRECATED  height      %Length;       #IMPLIED
-  >
-
-<!ATTLIST td
-  %attrs;
-  abbr        %Text;         #IMPLIED
-  axis        CDATA          #IMPLIED
-  headers     IDREFS         #IMPLIED
-  scope       %Scope;        #IMPLIED
-  rowspan     %Number;       "1"
-  colspan     %Number;       "1"
-  %cellhalign;
-  %cellvalign;
-DEPRECATED  nowrap      (nowrap)       #IMPLIED
-DEPRECATED  bgcolor     %Color;        #IMPLIED
-DEPRECATED  width       %Length;       #IMPLIED
-DEPRECATED  height      %Length;       #IMPLIED
-  >
-

docs/enduser-id.html

@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="description" content="Explains various methods for allowing IDs in documents safely in HTML Purifier." />
+<link rel="stylesheet" type="text/css" href="./style.css" />
+
+<title>IDs - HTML Purifier</title>
+
+</head><body>
+
+<h1 class="subtitled">IDs</h1>
+<div class="subtitle">What they are, why you should(n't) wear them, and how to deal with it</div>
+
+<div id="filing">Filed under End-User</div>
+<div id="index">Return to the <a href="index.html">index</a>.</div>
+<div id="home"><a href="http://hp.jpsband.org/">HTML Purifier</a> End-User Documentation</div>
+
+<p>Prior to HTML Purifier 1.2.0, this library blithely accepted user input that
+looked like this:</p>
+
+<pre>&lt;a id=&quot;fragment&quot;&gt;Anchor&lt;/a&gt;</pre>
+
+<p>...presenting an attractive vector for those that would destroy standards
+compliance: simply set the ID to one that is already used elsewhere in the
+document and voila: validation breaks.  There was a half-hearted attempt to
+prevent this by allowing users to blacklist IDs, but I suspect that no one
+really bothered, and thus, with the release of 1.2.0, IDs are now <em>removed</em>
+by default.</p>
+
+<p>IDs, however, are quite useful functionality to have, so if users start
+complaining about broken anchors you'll probably want to turn them back on
+with %HTML.EnableAttrID. But before you go mucking around with the config
+object, it's probably worth to take some precautions to keep your page
+validating. Why?</p>
+
+<ol>
+   <li>Standards-compliant pages are good</li>
+   <li>Duplicated IDs interfere with anchors.  If there are two id="foobar"s in a
+   document, which spot does a browser presented with the fragment #foobar go
+   to? Most browsers opt for the first appearing ID, making it impossible
+   to references the second section. Similarly, duplicated IDs can hijack
+   client-side scripting that relies on the IDs of elements.</li>
+</ol>
+
+<p>You have (currently) four ways of dealing with the problem.</p>
+
+
+
+<h2 class="subtitled">Blacklisting IDs</h2>
+<div class="subsubtitle">Good for pages with single content source and stable templates</div>
+
+<p>Keeping in terms with the
+<acronym title="Keep It Simple, Stupid">KISS</acronym> principle, let us
+deal with the most obvious solution: preventing users from using any IDs that
+appear elsewhere on the document.  The method is simple:</p>
+
+<pre>$config->set('HTML', 'EnableAttrID', true);
+$config->set('Attr', 'IDBlacklist' array(
+    'list', 'of', 'attributes', 'that', 'are', 'forbidden'
+));</pre>
+
+<p>That being said, there are some notable drawbacks.  First of all, you have to
+know precisely which IDs are being used by the HTML surrounding the user code.
+This is easier said than done: quite often the page designer and the system
+coder work separately, so the designer has to constantly be talking with the
+coder whenever he decides to add a new anchor.  Miss one and you open yourself
+to possible standards-compliance issues.</p>
+
+<p>Furthermore, this position becomes untenable when a single web page must hold
+multiple portions of user-submitted content.  Since there's obviously no way
+to find out before-hand what IDs users will use, the blacklist is helpless.
+And even since HTML Purifier validates each segment seperately, perhaps doing
+so at different times, it would be extremely difficult to dynamically update
+the blacklist inbetween runs.</p>
+
+<p>Finally, simply destroying the ID is extremely un-userfriendly behavior: after
+all, they might have simply specified a duplicate ID by accident.</p>
+
+<p>Thus, we get to our second method.</p>
+
+
+
+<h2 class="subtitled">Namespacing IDs</h2>
+<div class="subsubtitle">Lazy developer's way, but needs user education</div>
+
+<p>This method, too, is quite simple: add a prefix to all user IDs. With this
+code:</p>
+
+<pre>$config->set('HTML', 'EnableAttrID', true);
+$config->set('Attr', 'IDPrefix', 'user_');</pre>
+
+<p>...this:</p>
+
+<pre>&lt;a id=&quot;foobar&quot;&gt;Anchor!&lt;/a&gt;</pre>
+
+<p>...turns into:</p>
+
+<pre>&lt;a id=&quot;user_foobar&quot;&gt;Anchor!&lt;/a&gt;</pre>
+
+<p>As long as you don't have any IDs that start with user_, collisions are
+guaranteed not to happen.  The drawback is obvious: if a user submits
+id=&quot;foobar&quot;, they probably expect to be able to reference their page with
+#foobar. You'll have to tell them, &quot;No, that doesn't work, you have to add
+user_ to the beginning.&quot;</p>
+
+<p>And yes, things get hairier.  Even with a nice prefix, we still have done
+nothing about multiple HTML Purifier outputs on one page.  Thus, we have
+a second configuration value to piggy-back off of: %Attr.IDPrefixLocal:</p>
+
+<pre>$config->set('Attr', 'IDPrefixLocal', 'comment' . $id . '_');</pre>
+
+<p>This new attributes does nothing but append on to regular IDPrefix, but is
+special in that it is volatile: it's value is determined at run-time and
+cannot possibly be cordoned into, say, a .ini config file.  As for what to
+put into the directive, is up to you, but I would recommend the ID number
+the text has been assigned in the database.  Whatever you pick, however, it
+has to be unique and stable for the text you are validating.  Note, however,
+that we require that %Attr.IDPrefix be set before you use this directive.</p>
+
+<p>And also remember: the user has to know what this prefix is too!</p>
+
+
+
+<h2>Abstinence</h2>
+
+<p>You may not want to bother. That's okay too, just don't enable IDs.</p>
+
+<p>Personally, I would take this road whenever user-submitted content would be
+possibly be shown together on one page.  Why a blog comment would need to use
+anchors is beyond me.</p>
+
+
+
+<h2>Denial</h2>
+
+<p>To revert back to pre-1.2.0 behavior, simply:</p>
+
+<pre>$config->set('HTML', 'EnableAttrID', true);</pre>
+
+<p>Don't come crying to me when your page mysteriously stops validating, though.</p>
+
+<div id="version">$Id$</div>
+
+</body>
+</html>

docs/enduser-overview.txt

@@ -54,4 +54,4 @@ HTML Purifier is best suited for documents that require a rich array of
 HTML tags.  Things like blog comments are, in all likelihood, most appropriately
 written in an extremely restrictive set of markup that doesn't require
 all this functionality (or not written in HTML at all), although this may
-be changing in the future.
+be changing in the future with the addition of levels of filtering.

docs/enduser-security.txt

@@ -6,35 +6,45 @@ through negligence of people. This class will do its job: no more, no less,
 and it's up to you to provide it the proper information and proper context
 to be effective. Things to remember:
 
-1. UTF-8. Currently, the parser runs under the assumption that it is dealing
+1. Character Encoding: UTF-8.
+    This segment will soon be obsoleted by enduser-utf8.html
+Currently, the parser runs under the assumption that it is dealing
 with UTF-8. Not ISO-8859-1 or Windows-1252, UTF-8. And definitely not "no
 character encoding explicitly stated" or UTF-7. If you're not using UTF-8 as
-your character encoding, you should switch. Now. Make sure any input is
-properly converted to UTF-8, or the parser will mangle it badly
-(though it won't be a security risk if you're outputting it as UTF-8 though).
-We will be adding out-of-the-box support for the other major character
-encodings shortly.
+your character encoding, make sure you configure HTML Purifier or switch
+to UTF-8. Now. Also, make sure any input is properly converted to UTF-8, or
+the parser will mangle it badly (though it won't be a security risk if you're
+outputting it as UTF-8 though).  Character encoding is, in general, a knotty
+issue, but do yourself a favor and learn about it:
+<http://www.joelonsoftware.com/articles/Unicode.html>
 
-2. XHTML 1.0 Transitional. This is what the parser is outputting. For the most
+2. Doctype: XHTML 1.0 Transitional
+This is what the parser is outputting. For the most
 part, it's compatible with HTML 4.01, but XHTML enforces some very nice things
 that all web developers should use. Regardless, NO DOCTYPE is a NO. Quirks mode
 has waaaay too many quirks for a little parser to handle.  We did not select
 strict in order to prevent ourselves from being too draconic on users, but
-this may be configurable in the future.
+this may be configurable in the future.  Do you want standards compliance?
+The doctype is a good place to start.
 
-3. IDs. They need to be unique, but without some knowledge of the
+3. IDs
+    This segment is obsoleted by enduser-id.html
+They need to be unique, but without some knowledge of the
 rest of the document, it's difficult to know what's unique. %Attr.IDBlacklist
 needs to be set: we may want to consider disallowing IDs by default to
 save lazy programmers.
 
-4. [PROJECTED] Links. We're not going to try for spam protection (although
+4. [PROJECTED] Links
+We're not going to try for spam protection (although
 some hooks for such a module might be nice) but we may offer the ability to
 only accept relative URLs. Pick the one that's right for you.
 
-5. CSS. While we can prevent the most flagrant cases from affecting your
+5. CSS
+While we can prevent the most flagrant cases from affecting your
 layout (such as absolutely positioned elements), no amount of code is going
 to protect your pages from being attacked by garish colors and plain old
 bad taste.  A neat feature would be the ability to define acceptable colors
 in a document, but that's not likely to be implemented for a while.  In the
 meantime, be sure to make sure that floated elements (permitted, since they
-can be quite useful) can't mess up your layout.
+can be quite useful) can't mess up your layout. Once again, we may want to
+disable this by default to protect lazy developers.

docs/enduser-slow.html

@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="description" content="Explains how to speed up HTML Purifier through caching or inbound filtering." />
+<link rel="stylesheet" type="text/css" href="./style.css" />
+
+<title>Speeding up HTML Purifier - HTML Purifier</title>
+
+</head><body>
+
+<h1 class="subtitled">Speeding up HTML Purifier</h1>
+<div class="subtitle">...also known as the HELP ME LIBRARY IS TOO SLOW MY PAGE TAKE TOO LONG page</div>
+
+<div id="filing">Filed under End-User</div>
+<div id="index">Return to the <a href="index.html">index</a>.</div>
+<div id="home"><a href="http://hp.jpsband.org/">HTML Purifier</a> End-User Documentation</div>
+
+<p>HTML Purifier is a very powerful library. But with power comes great 
+responsibility, in the form of longer execution times.  Remember, this 
+library isn't lightly grazing over submitted HTML: it's deconstructing 
+the whole thing, rigorously checking the parts, and then putting it back 
+together. </p>
+
+<p>So, if it so turns out that HTML Purifier is kinda too slow for outbound 
+filtering, you've got a few options: </p>
+
+<h2>Inbound filtering</h2>
+
+<p>Perform filtering of HTML when it's submitted by the user. Since the 
+user is already submitting something, an extra half a second tacked on 
+to the load time probably isn't going to be that huge of a problem.  
+Then, displaying the content is a simple a manner of outputting it 
+directly from your database/filesystem. The trouble with this method is 
+that your user loses the original text, and when doing edits, will be 
+handling the filtered text.  While this may be a good thing, especially 
+if you're using a WYSIWYG editor, it can also result in data-loss if a 
+user makes a typo. </p>
+
+<p>Example (non-functional):</p>
+
+<pre>&lt;?php
+    /**
+     * FORM SUBMISSION PAGE
+     * display_error($message) : displays nice error page with message
+     * display_success() : displays a nice success page
+     * display_form() : displays the HTML submission form
+     * database_insert($html) : inserts data into database as new row
+     */
+    if (!empty($_POST)) {
+        require_once '/path/to/library/HTMLPurifier.auto.php';
+        require_once 'HTMLPurifier.func.php';
+        $dirty_html = isset($_POST['html']) ? $_POST['html'] : false;
+        if (!$dirty_html) {
+            display_error('You must write some HTML!');
+        }
+        $html = HTMLPurifier($dirty_html);
+        database_insert($html);
+        display_success();
+        // notice that $dirty_html is *not* saved
+    } else {
+        display_form();
+    }
+?&gt;</pre>
+
+<h2>Caching the filtered output</h2>
+
+<p>Accept the submitted text and put it unaltered into the database, but 
+then also generate a filtered version and stash that in the database.  
+Serve the filtered version to readers, and the unaltered version to 
+editors.  If need be, you can invalidate the cache and have the cached 
+filtered version be regenerated on the first page view.  Pros? Full data 
+retention. Cons? It's more complicated, and opens other editors up to 
+XSS if they are using a WYSIWYG editor (to fix that, they'd have to be 
+able to get their hands on the *really* original text served in 
+plaintext mode). </p>
+
+<p>Example (non-functional):</p>
+
+<pre>&lt;?php
+    /**
+     * VIEW PAGE
+     * display_error($message) : displays nice error page with message
+     * cache_get($id) : retrieves HTML from fast cache (db or file)
+     * cache_insert($id, $html) : inserts good HTML into cache system
+     * database_get($id) : retrieves raw HTML from database
+     */
+    $id = isset($_GET['id']) ? (int) $_GET['id'] : false;
+    if (!$id) {
+        display_error('Must specify ID.');
+        exit;
+    }
+    $html = cache_get($id); // filesystem or database
+    if ($html === false) {
+        // cache didn't have the HTML, generate it
+        $raw_html = database_get($id);
+        require_once '/path/to/library/HTMLPurifier.auto.php';
+        require_once 'HTMLPurifier.func.php';
+        $html = HTMLPurifier($raw_html);
+        cache_insert($id, $html);
+    }
+    echo $html;
+?&gt;</pre>
+
+<h2>Summary</h2>
+
+<p>In short, inbound filtering is the simple option and caching is the
+robust option (albeit with bigger storage requirements). </p>
+
+<p>There is a third option, independent of the two we've discussed: profile 
+and optimize HTMLPurifier yourself. Be sure to report back your results 
+if you decide to do that! Especially if you port HTML Purifier to C++. 
+<tt>;-)</tt></p>
+
+</body>
+</html>

docs/enduser-utf8.html

@@ -0,0 +1,640 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"><head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="description" content="Describes the rationale for using UTF-8, the ramifications otherwise, and how to make the switch." />
+<link rel="stylesheet" type="text/css" href="./style.css" />
+<script defer="defer" type="text/javascript" src="./toc-gen.js"></script>
+<style type="text/css">
+    .minor td {font-style:italic;}
+</style>
+
+<title>UTF-8 - HTML Purifier</title>
+
+<!-- Note to users: this document, though professing to be UTF-8, attempts
+to use only ASCII characters, because most webservers are configured
+to send HTML as ISO-8859-1. So I will, many times, go against my
+own advice for sake of portability.  -->
+
+</head><body>
+
+<h1>UTF-8</h1>
+
+<div id="filing">Filed under End-User</div>
+<div id="index">Return to the <a href="index.html">index</a>.</div>
+<div id="home"><a href="http://hp.jpsband.org/">HTML Purifier</a> End-User Documentation</div>
+
+<p>Character encoding and character sets, in truth, are not that
+difficult to understand. But if you don't understand them, you are going
+to be caught by surprise by some of HTML Purifier's behavior, namely
+the fact that it operates UTF-8 or the limitations of the character
+encoding transformations it does. This document will walk you through
+determining the encoding of your system and how you should handle
+this information. It will stay away from excessive discussion on
+the internals of character encoding, but offer the information in
+asides that can easily be skipped.</p>
+
+<blockquote class="aside">
+<div class="label">Asides</div>
+    <p>Text in this formatting is an <strong>aside</strong>,
+    interesting tidbits for the curious but not strictly necessary material to
+    do the tutorial. If you read this text, you'll come out
+    with a greater understanding of the underlying issues.</p>
+</blockquote>
+
+<h2 id="findcharset">Finding the real encoding</h2>
+
+<p>In the beginning, there was ASCII, and things were simple. But they
+weren't good, for no one could write in Cryllic or Thai. So there
+exploded a proliferation of character encodings to remedy the problem
+by extending the characters ASCII could express. This ridiculously
+simplified version of the history of character encodings shows us that
+there are now many character encodings floating around.</p>
+
+<blockquote class="aside">
+    <p>A <strong>character encoding</strong> tells the computer how to
+    interpret raw zeroes and ones into real characters. It
+    usually does this by pairing numbers with characters.</p>
+    <p>There are many different types of character encodings floating
+    around, but the ones we deal most frequently with are ASCII, 
+    8-bit encodings, and Unicode-based encodings.</p>
+    <ul>
+        <li><strong>ASCII</strong> is a 7-bit encoding based on the
+            English alphabet.</li>
+        <li><strong>8-bit encodings</strong> are extensions to ASCII
+            that add a potpourri of useful, non-standard characters
+            like &eacute; and &aelig;. They can only add 127 characters,
+            so usually only support one script at a time. When you
+            see a page on the web, chances are it's encoded in one
+            of these encodings.</li>
+        <li><strong>Unicode-based encodings</strong> implement the
+            Unicode standard and include UTF-8, UCS-2 and UTF-16.
+            They go beyond 8-bits (the first two are variable length,
+            while the second one uses 16-bits), and support almost
+            every language in the world. UTF-8 is gaining traction
+            as the dominant international encoding of the web.</li>
+    </ul>
+</blockquote>
+
+<p>The first step of our journey is to find out what the encoding of
+your website is. The most reliable way is to ask your
+browser:</p>
+
+<dl>
+    <dt>Mozilla Firefox</dt>
+    <dd>Tools &gt; Page Info: Encoding</dd>
+    <dt>Internet Explorer</dt>
+    <dd>View &gt; Encoding: bulleted item is unofficial name</dd>
+</dl>
+
+<p>Internet Explorer won't give you the mime (i.e. useful/real) name of the
+character encoding, so you'll have to look it up using their description.
+Some common ones:</p>
+
+<table class="table">
+    <thead><tr>
+        <th>IE's Description</th>
+        <th>Mime Name</th>
+    </tr></thead>
+    <tbody>
+        <tr><th colspan="2">Windows</th></tr>
+        <tr><td>Arabic (Windows)</td><td>Windows-1256</td></tr>
+        <tr><td>Baltic (Windows)</td><td>Windows-1257</td></tr>
+        <tr><td>Central European (Windows)</td><td>Windows-1250</td></tr>
+        <tr><td>Cyrillic (Windows)</td><td>Windows-1251</td></tr>
+        <tr><td>Greek (Windows)</td><td>Windows-1253</td></tr>
+        <tr><td>Hebrew (Windows)</td><td>Windows-1255</td></tr>
+        <tr><td>Thai (Windows)</td><td>TIS-620</td></tr>
+        <tr><td>Turkish (Windows)</td><td>Windows-1254</td></tr>
+        <tr><td>Vietnamese (Windows)</td><td>Windows-1258</td></tr>
+        <tr><td>Western European (Windows)</td><td>Windows-1252</td></tr>
+    </tbody>
+    <tbody>
+        <tr><th colspan="2">ISO</th></tr>
+        <tr><td>Arabic (ISO)</td><td>ISO-8859-6</td></tr>
+        <tr><td>Baltic (ISO)</td><td>ISO-8859-4</td></tr>
+        <tr><td>Central European (ISO)</td><td>ISO-8859-2</td></tr>
+        <tr><td>Cyrillic (ISO)</td><td>ISO-8859-5</td></tr>
+        <tr class="minor"><td>Estonian (ISO)</td><td>ISO-8859-13</td></tr>
+        <tr class="minor"><td>Greek (ISO)</td><td>ISO-8859-7</td></tr>
+        <tr><td>Hebrew (ISO-Logical)</td><td>ISO-8859-8-l</td></tr>
+        <tr><td>Hebrew (ISO-Visual)</td><td>ISO-8859-8</td></tr>
+        <tr class="minor"><td>Latin 9 (ISO)</td><td>ISO-8859-15</td></tr>
+        <tr class="minor"><td>Turkish (ISO)</td><td>ISO-8859-9</td></tr>
+        <tr><td>Western European (ISO)</td><td>ISO-8859-1</td></tr>
+    </tbody>
+    <tbody>
+        <tr><th colspan="2">Other</th></tr>
+        <tr><td>Chinese Simplified (GB18030)</td><td>GB18030</td></tr>
+        <tr><td>Chinese Simplified (GB2312)</td><td>GB2312</td></tr>
+        <tr><td>Chinese Simplified (HZ)</td><td>HZ</td></tr>
+        <tr><td>Chinese Traditional (Big5)</td><td>Big5</td></tr>
+        <tr><td>Japanese (Shift-JIS)</td><td>Shift_JIS</td></tr>
+        <tr><td>Japanese (EUC)</td><td>EUC-JP</td></tr>
+        <tr><td>Korean</td><td>EUC-KR</td></tr>
+        <tr><td>Unicode (UTF-8)</td><td>UTF-8</td></tr>
+    </tbody>
+</table>
+
+<p>Internet Explorer does not recognize some of the more obscure
+character encodings, and having to lookup the real names with a table
+is a pain, so I recommend using Mozilla Firefox to find out your
+character encoding.</p>
+
+<h2 id="findmetacharset">Finding the embedded encoding</h2>
+
+<p>At this point, you may be asking, &quot;Didn't we already find out our
+encoding?&quot; Well, as it turns out, there are multiple places where
+a web developer can specify a character encoding, and one such place
+is in a <code>META</code> tag:</p>
+
+<pre>&lt;meta http-equiv=&quot;Content-Type&quot; content=&quot;text/html; charset=UTF-8&quot; /&gt;</pre>
+
+<p>You'll find this in the <code>HEAD</code> section of an HTML document.
+The text to the right of <code>charset=</code> is the &quot;claimed&quot;
+encoding: the HTML claims to be this encoding, but whether or not this
+is actually the case depends on other factors. For now, take note
+if your <code>META</code> tag claims that either:</p>
+
+<ol>
+    <li>The character encoding is the same as the one reported by the
+        browser,</li>
+    <li>The character encoding is different from the browser's, or</li>
+    <li>There is no <code>META</code> tag at all! (horror, horror!)</li>
+</ol>
+
+<h2 id="fixcharset">Fixing the encoding</h2>
+
+<p>If your <code>META</code> encoding and your real encoding match,
+savvy! You can skip this section. If they don't...</p>
+
+<h3 id="fixcharset-none">No embedded encoding</h3>
+
+<p>If this is the case, you'll want to add in the appropriate
+<code>META</code> tag to your website. It's as simple as copy-pasting
+the code snippet above and replacing UTF-8 with whatever is the mime name
+of your real encoding.</p>
+
+<blockquote class="aside">
+    <p>For all those skeptics out there, there is a very good reason
+    why the character encoding should be explicitly stated. When the
+    browser isn't told what the character encoding of a text is, it
+    has to guess: and sometimes the guess is wrong. Hackers can manipulate
+    this guess in order to slip XSS pass filters and then fool the
+    browser into executing it as active code. A great example of this
+    is the <a href="http://shiflett.org/archive/177">Google UTF-7
+    exploit</a>.</p>
+    <p>You might be able to get away with not specifying a character
+    encoding with the <code>META</code> tag as long as your webserver
+    sends the right Content-Type header, but why risk it? Besides, if
+    the user downloads the HTML file, there is no longer any webserver
+    to define the character encoding.</p>
+</blockquote>
+
+<h3 id="fixcharset-diff">Embedded encoding disagrees</h3>
+
+<p>This is an extremely common mistake: another source is telling
+the browser what the
+character encoding is and is overriding the embedded encoding. This
+source usually is the Content-Type HTTP header that the webserver (i.e.
+Apache) sends. A usual Content-Type header sent with a page might
+look like this:</p>
+
+<pre>Content-Type: text/html; charset=ISO-8859-1</pre>
+
+<p>Notice how there is a charset parameter: this is the webserver's
+way of telling a browser what the character encoding is, much like
+the <code>META</code> tags we touched upon previously.</p>
+
+<blockquote class="aside"><p>In fact, the <code>META</code> tag is
+designed as a substitute for the HTTP header for contexts where
+sending headers is impossible (such as locally stored files without
+a webserver). Thus the name <code>http-equiv</code> (HTTP equivalent).
+</p></blockquote>
+
+<p>There are two ways to go about fixing this: changing the <code>META</code>
+tag to match the HTTP header, or changing the HTTP header to match
+the <code>META</code> tag. How do we know which to do? It depends
+on the website's content: after all, headers and tags are only ways of
+describing the actual characters on the web page.</p>
+
+<p>If your website:</p>
+
+<dl>
+    <dt>...only uses ASCII characters,</dt>
+    <dd>Either way is fine, but I recommend switching both to
+        UTF-8 (more on this later).</dd>
+    <dt>...uses special characters, and they display
+        properly,</dt>
+    <dd>Change the embedded encoding to the server encoding.</dd>
+    <dt>...uses special characters, but users often complain that
+        they come out garbled,</dt>
+    <dd>Change the server encoding to the embedded encoding.</dd>
+</dl>
+
+<p>Changing a META tag is easy: just swap out the old encoding
+for the new. Changing the server (HTTP header) encoding, however,
+is slightly more difficult.</p>
+
+<h3 id="fixcharset-server">Changing the server encoding</h3>
+
+<h4 id="fixcharset-server-php">PHP header() function</h4>
+
+<p>The simplest way to handle this problem is to send the encoding
+yourself, via your programming language. Since you're using HTML
+Purifier, I'll assume PHP, although it's not too difficult to do
+similar things in
+<a href="http://www.w3.org/International/O-HTTP-charset#scripting">other
+languages</a>. The appropriate code is:</p>
+
+<pre><a href="http://php.net/function.header">header</a>('Content-Type:text/html; charset=UTF-8');</pre>
+
+<p>...replacing UTF-8 with whatever your embedded encoding is.
+This code must come before any output, so be careful about
+stray whitespace in your application.</p>
+
+<h4 id="fixcharset-server-phpini">PHP ini directive</h4>
+
+<p>PHP also has a neat little ini directive that can save you a
+header call: <code><a href="http://php.net/ini.core#ini.default-charset">default_charset</a></code>. Using this code:</p>
+
+<pre><a href="http://php.net/function.ini_set">ini_set</a>('default_charset', 'UTF-8');</pre>
+
+<p>...will also do the trick. If PHP is running as an Apache module (and
+not as FastCGI, consult
+<a href="http://php.net/phpinfo">phpinfo</a>() for details), you can even use htaccess do apply this property
+globally:</p>
+
+<pre><a href="http://php.net/configuration.changes#configuration.changes.apache">php_value</a> default_charset &quot;UTF-8&quot;</pre>
+
+<blockquote class="aside"><p>As with all INI directives, this can
+also go in your php.ini file. Some hosting providers allow you to customize
+your own php.ini file, ask your support for details. Use:</p>
+<pre>default_charset = &quot;utf-8&quot;</pre></blockquote>
+
+<h4 id="fixcharset-server-nophp">Non-PHP</h4>
+
+<p>You may, for whatever reason, may need to set the character encoding
+on non-PHP files, usually plain ol' HTML files. Doing this
+is more of a hit-or-miss process: depending on the software being
+used as a webserver and the configuration of that software, certain
+techniques may work, or may not work.</p>
+
+<h4 id="fixcharset-server-htaccess">.htaccess</h4>
+
+<p>On Apache, you can use an .htaccess file to change the character
+encoding. I'll defer to
+<a href="http://www.w3.org/International/questions/qa-htaccess-charset">W3C</a>
+for the in-depth explanation, but it boils down to creating a file
+named .htaccess with the contents:</p>
+
+<pre><a href="http://httpd.apache.org/docs/1.3/mod/mod_mime.html#addcharset">AddCharset</a> UTF-8 .html</pre>
+
+<p>Where UTF-8 is replaced with the character encoding you want to
+use and .html is a file extension that this will be applied to. This
+character encoding will then be set for any file directly in
+or in the subdirectories of directory you place this file in.</p>
+
+<p>If you're feeling particularly courageous, you can use:</p>
+
+<pre><a href="http://httpd.apache.org/docs/1.3/mod/core.html#adddefaultcharset">AddDefaultCharset</a> UTF-8</pre>
+
+<p>...which changes the character set Apache adds to any document that
+doesn't have any Content-Type parameters. This directive, which the
+default configuration file sets to iso-8859-1 for security
+reasons, is probably why your headers mismatch
+with the <code>META</code> tag. If you would prefer Apache not to be
+butting in on your character encodings, you can tell it not
+to send anything at all:</p>
+
+<pre><a href="http://httpd.apache.org/docs/1.3/mod/core.html#adddefaultcharset">AddDefaultCharset</a> Off</pre>
+
+<p>...making your <code>META</code> tags the sole source of
+character encoding information. In these cases, it is
+<em>especially</em> important to make sure you have valid <code>META</code>
+tags on your pages and all the text before them is ASCII.</p>
+
+<blockquote class="aside"><p>These directives can also be
+placed in httpd.conf file for Apache, but
+in most shared hosting situations you won't be able to edit this file.
+</p></blockquote>
+
+<h4 id="fixcharset-server-ext">File extensions</h4>
+
+<p>If you're not allowed to use .htaccess files, you can often
+piggy-back off of Apache's default AddCharset declarations to get
+your files in the proper extension. Here are Apache's default
+character set declarations:</p>
+
+<table class="table">
+    <thead><tr>
+        <th>Charset</th>
+        <th>File extension(s)</th>
+    </tr></thead>
+    <tbody>
+        <tr><td>ISO-8859-1</td><td>.iso8859-1 .latin1</td></tr>
+        <tr><td>ISO-8859-2</td><td>.iso8859-2 .latin2 .cen</td></tr>
+        <tr><td>ISO-8859-3</td><td>.iso8859-3 .latin3</td></tr>
+        <tr><td>ISO-8859-4</td><td>.iso8859-4 .latin4</td></tr>
+        <tr><td>ISO-8859-5</td><td>.iso8859-5 .latin5 .cyr .iso-ru</td></tr>
+        <tr><td>ISO-8859-6</td><td>.iso8859-6 .latin6 .arb</td></tr>
+        <tr><td>ISO-8859-7</td><td>.iso8859-7 .latin7 .grk</td></tr>
+        <tr><td>ISO-8859-8</td><td>.iso8859-8 .latin8 .heb</td></tr>
+        <tr><td>ISO-8859-9</td><td>.iso8859-9 .latin9 .trk</td></tr>
+        <tr><td>ISO-2022-JP</td><td>.iso2022-jp .jis</td></tr>
+        <tr><td>ISO-2022-KR</td><td>.iso2022-kr .kis</td></tr>
+        <tr><td>ISO-2022-CN</td><td>.iso2022-cn .cis</td></tr>
+        <tr><td>Big5</td><td>.Big5 .big5 .b5</td></tr>
+        <tr><td>WINDOWS-1251</td><td>.cp-1251 .win-1251</td></tr>
+        <tr><td>CP866</td><td>.cp866</td></tr>
+        <tr><td>KOI8-r</td><td>.koi8-r .koi8-ru</td></tr>
+        <tr><td>KOI8-ru</td><td>.koi8-uk .ua</td></tr>
+        <tr><td>ISO-10646-UCS-2</td><td>.ucs2</td></tr>
+        <tr><td>ISO-10646-UCS-4</td><td>.ucs4</td></tr>
+        <tr><td>UTF-8</td><td>.utf8</td></tr>
+        <tr><td>GB2312</td><td>.gb2312 .gb </td></tr>
+        <tr><td>utf-7</td><td>.utf7</td></tr>
+        <tr><td>EUC-TW</td><td>.euc-tw</td></tr>
+        <tr><td>EUC-JP</td><td>.euc-jp</td></tr>
+        <tr><td>EUC-KR</td><td>.euc-kr</td></tr>
+        <tr><td>shift_jis</td><td>.sjis</td></tr>
+    </tbody>
+</table>
+
+<p>So, for example, a file named <code>page.utf8.html</code> or
+<code>page.html.utf8</code> will probably be sent with the UTF-8 charset
+attached, the difference being that if there is an
+<code>AddCharset charset .html</code> declaration, it will override
+the .utf8 extension in <code>page.utf8.html</code> (precedence moves
+from right to left). By default, Apache has no such declaration.</p>
+
+<h4 id="fixcharset-server-iis">Microsoft IIS</h4>
+
+<p>If anyone can contribute information on how to configure Microsoft
+IIS to change character encodings, I'd be grateful.</p>
+
+<h3 id="fixcharset-xml">XML</h3>
+
+<p><code>META</code> tags are the most common source of embedded
+encodings, but they can also come from somewhere else: XML
+processing instructions. They look like:</p>
+
+<pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</pre>
+
+<p>...and are most often found in XML documents (including XHTML).</p>
+
+<p>For XHTML, this processing instruction theoretically
+overrides the <code>META</code> tag. In reality, this happens only when the
+XHTML is actually served as legit XML and not HTML, which is almost
+always never due to Internet Explorer's lack of support for 
+<code>application/xhtml+xml</code> (even though doing so is often
+argued to be <a href="http://www.hixie.ch/advocacy/xhtml">good practice</a>).</p>
+
+<p>For XML, however, this processing instruction is extremely important.
+Since most webservers are not configured to send charsets for .xml files,
+this is the only thing a parser has to go on. Furthermore, the default
+for XML files is UTF-8, which often butts heads with more common
+ISO-8859-1 encoding (you see this in garbled RSS feeds).</p>
+
+<p>In short, if you use XHTML and have gone through the
+trouble of adding the XML header, be sure to make sure it jives
+with your <code>META</code> tags and HTTP headers.</p>
+
+<h3>Inside the process</h3>
+
+<p>This section is not required reading,
+but may answer some of your questions on what's going on in all
+this character encoding hocus pocus. If you're interested in
+moving on to the next phase, skip this section.</p>
+
+<p>A logical question that follows all of our wheeling and dealing
+with multiple sources of character encodings is &quot;Why are there
+so many options?&quot; To answer this question, we have to turn
+back our definition of character encodings: they allow a program
+to interpret bytes into human-readable characters.</p>
+
+<p>Thus, a chicken-egg problem: a character encoding
+is necessary to interpret the
+text of a document. A <code>META</code> tag is in the text of a document.
+The <code>META</code> tag gives the character encoding. How can we
+determine the contents of a <code>META</code> tag, inside the text,
+if we don't know it's character encoding? And how do we figure out
+the character encoding, if we don't know the contents of the
+<code>META</code> tag?</p>
+
+<p>Fortunantely for us, the characters we need to write the
+<code>META</code> are in ASCII, which is pretty much universal
+over every character encoding that is in common use today. So,
+all the web-browser has to do is parse all the way down until
+it gets to the Content-Type tag, extract the character encoding
+tag, then re-parse the document according to this new information.</p>
+
+<p>Obviously this is complicated, so browsers prefer the simpler
+and more efficient solution: get the character encoding from a 
+somewhere other than the document itself, i.e. the HTTP headers,
+much to the chagrin of HTML authors who can't set these headers.</p>
+
+<h2 id="whyutf8">Why UTF-8?</h2>
+
+<p>So, you've gone through all the trouble of ensuring that your
+server and embedded characters all line up properly and are
+present.  Good job: at
+this point, you could quit and rest easy knowing that your pages
+are not vulnerable to character encoding style XSS attacks.
+However, just as having a character encoding is better than
+having no character encoding at all, having UTF-8 as your
+character encoding is better than having some other random
+character encoding, and the next step is to convert to UTF-8.
+But why?</p>
+
+<h3 id="whyutf8-i18n">Internationalization</h3>
+
+<p>Many software projects, at one point or another, suddenly realize
+that they should be supporting more than one language. Even regular
+usage in one language sometimes requires the occasional special character
+that, without surprise, is not available in your character set. Sometimes
+developers get around this by adding support for multiple encodings: when
+using Chinese, use Big5, when using Japanese, use Shift-JIS, when
+using Greek, etc. Other times, they use character entities with great
+zeal.</p>
+
+<p>UTF-8, however, obviates the need for any of these complicated
+measures. After getting the system to use UTF-8 and adjusting for
+sources that are outside the hand of the browser (more on this later),
+UTF-8 just works. You can use it for any language, even many languages
+at once, you don't have to worry about managing multiple encodings,
+you don't have to use those user-unfriendly entities.</p>
+
+<h3 id="whyutf8-user">User-friendly</h3>
+
+<p>Websites encoded in Latin-1 (ISO-8859-1) which ocassionally need
+a special character outside of their scope often will use a character
+entity to achieve the desired effect. For instance, &theta; can be
+written <code>&amp;theta;</code>, regardless of the character encoding's
+support of Greek letters.</p>
+
+<p>This works nicely for limited use of special characters, but
+say you wanted this sentence of Chinese text: &#28608;&#20809;,
+&#36889;&#20841;&#20491;&#23383;&#26159;&#29978;&#40636;&#24847;&#24605;.
+The entity-ized version would look like this:</p>
+
+<pre>&amp;#28608;&amp;#20809;, &amp;#36889;&amp;#20841;&amp;#20491;&amp;#23383;&amp;#26159;&amp;#29978;&amp;#40636;&amp;#24847;&amp;#24605;</pre>
+
+<p>Extremely inconvenient for those of us who actually know what
+character entities are, totally unintelligible to poor users who don't!
+Even the slightly more user-friendly, &quot;intelligible&quot; character
+entities like <code>&amp;theta;</code> will leave users who are
+uninterested in learning HTML scratching their heads. On the other
+hand, if they see &theta; in an edit box, they'll know that it's a
+special character, and treat it accordingly, even if they don't know
+how to write that character themselves.</p>
+
+<blockquote class="aside"><p>Wikipedia is a great case study for
+an application that originally used ISO-8859-1 but switched to UTF-8
+when it became far to cumbersome to support foreign languages. Bots
+will now actually go through articles and convert character entities
+to their corresponding real characters for the sake of user-friendliness
+and searcheability. See
+<a href="http://meta.wikimedia.org/wiki/Help:Special_characters">Meta's
+page on special characters</a> for more details.
+</p></blockquote>
+
+<h3 id="whyutf8-forms">Forms</h3>
+
+<p>While we're on the tack of users, how do non-UTF-8 web forms deal
+with characters that our outside of their character set? Rather than
+discuss what UTF-8 does right, we're going to show what could go wrong
+if you didn't use UTF-8 and people tried to use characters outside
+of your character encoding.</p>
+
+<p>The troubles are large, extensive, and extremely difficult to fix (or,
+at least, difficult enough that if you had the time and resources to invest
+in doing the fix, you would be probably better off migrating to UTF-8).
+There are two types of form submission: <code>application/x-www-form-urlencoded</code>
+which is used for GET and by default for POST, and <code>multipart/form-data</code>
+which may be used by POST, and is required when you want to upload
+files.</p>
+
+<p>The following is a summarization of notes from
+<a href="http://ppewww.physics.gla.ac.uk/~flavell/charset/form-i18n.html">
+<code>FORM</code> submission and i18n</a>. That document contains lots
+of useful information, but is written in a rambly manner, so
+here I try to get right to the point.</p>
+
+<h4 id="whyutf8-forms-urlencoded"><code>application/x-www-form-urlencoded</code></h4>
+
+<p>This is the Content-Type that GET requests must use, and POST requests
+use by default. It involves the ubiquituous percent encoding format that
+looks something like: <code>%C3%86</code>. There is no official way of
+determining the character encoding of such a request, since the percent
+encoding operates on a byte level, so it is usually assumed that it
+is the same as the encoding the page containing the form was submitted
+in. You'll run into very few problems if you only use characters in
+the character encoding you chose.</p>
+
+<p>However, once you start adding characters outside of your encoding
+(and this is a lot more common than you may think: take curly
+&quot;smart&quot; quotes from Microsoft as an example),
+a whole manner of strange things start to happen. Depending on the
+browser you're using, they might:</p>
+
+<ul>
+    <li>Replace the unsupported characters with useless question marks,</li>
+    <li>Attempt to fix the characters (example: smart quotes to regular quotes),</li>
+    <li>Replace the character with a character entity, or</li>
+    <li>Send it anyway as a different character encoding mixed in
+        with the original encoding (usually Windows-1252 rather than
+        iso-8859-1 or UTF-8 interspersed in 8-bit)</li>
+</ul>
+
+<p>To properly guard against these behaviors, you'd have to sniff out
+the browser agent, compile a database of different behaviors, and
+take appropriate conversion action against the string (disregarding
+a spate of extremely mysterious, random and devastating bugs Internet
+Explorer manifests every once in a while). Or you could
+use UTF-8 and rest easy knowing that none of this could possibly happen
+since UTF-8 supports every character.</p>
+
+<h4 id="whyutf8-forms-multipart"><code>multipart/form-data</code></h4>
+
+<p>Multipart form submission takes a way a lot of the ambiguity
+that percent-encoding had: the server now can explicitly ask for
+certain encodings, and the client can explicitly tell the server
+during the form submission what encoding the fields are in.</p>
+
+<p>There are two ways you go with this functionality: leave it
+unset and have the browser send in the same encoding as the page,
+or set it to UTF-8 and then do another conversion server-side.
+Each method has deficiencies, especially the former.</p>
+
+<p>If you tell the browser to send the form in the same encoding as
+the page, you still have the trouble of what to do with characters
+that are outside of the character encoding's range. The behavior, once
+again, varies: Firefox 2.0 entity-izes them while Internet Explorer
+7.0 mangles them beyond intelligibility. For serious I18N purposes,
+this is not an option.</p>
+
+<p>The other possibility is to set Accept-Encoding to UTF-8, which
+begs the question: Why aren't you using UTF-8 for everything then?
+This route is more palatable, but there's a notable caveat: your data
+will come in as UTF-8, so you will have to explicitly convert it into
+your favored local character encoding.</p>
+
+<p>I object to this approach on idealogical grounds: you're
+digging yourself deeper into
+the hole when you could have been converting to UTF-8
+instead. And, of course, you can't use this method for GET requests.</p>
+
+<h3 id="whyutf8-support">Well supported</h3>
+
+<p>Almost every modern browser in the wild today has full UTF-8 and Unicode
+support: the number of troublesome cases can be counted with the
+fingers of one hand, and these browsers usually have trouble with
+other character encodings too. Problems users usually encounter stem
+from the lack of appropriate fonts to display the characters (once
+again, this applies to all character encodings and HTML entities) or
+Internet Explorer's lack of intelligent font picking (which can be
+worked around).</p>
+
+<p>We will go into more detail about how to deal with edge cases in
+the browser world in the Migration section, but rest assured that
+converting to UTF-8, if done correctly, will not result in users
+hounding you about broken pages.</p>
+
+<h3 id="whyutf8-htmlpurifier">HTML Purifier</h3>
+
+<p>And finally, we get to HTML Purifier.</p>
+
+<h2 id="migrate">Migrate to UTF-8</h2>
+
+<h3 id="migrate-editor">Text editor</h3>
+
+<h3 id="migrate-db">Configuring your database</h3>
+
+<h3 id="migrate-convert">Convert old text</h3>
+
+<h3 id="migrate-bom">Byte Order Mark (headers already sent!)</h3>
+
+<h3 id="migrate-variablewidth">Dealing with variable width in functions</h3>
+
+<h2 id="externallinks">Further Reading</h2>
+
+<p>Many other developers have already discussed the subject of Unicode,
+UTF-8 and internationalization, and I would like to defer to them for
+a more in-depth look into character sets and encodings.</p>
+
+<ul>
+    <li><a href="http://www.joelonsoftware.com/articles/Unicode.html">
+        The Absolute Minimum Every Software Developer Absolutely,
+        Positively Must Know About Unicode and Character Sets
+        (No Excuses!)</a> by Joel Spolsky, provides a <em>very</em>
+        good high-level look at Unicode and character sets in general.</li>
+    <li><a href="http://en.wikipedia.org/wiki/UTF-8">UTF-8 on Wikipedia</a>,
+        provides a lot of useful details into the innards of UTF-8, although
+        it may be a little off-putting to people who don't know much
+        about Unicode to begin with.</li>
+</ul>
+
+</body>
+</html>

docs/enduser-youtube.html

@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="description" content="Explains how to safely allow the embedding of flash from trusted sites in HTML Purifier." />
+<link rel="stylesheet" type="text/css" href="./style.css" />
+
+<title>Embedding YouTube Videos - HTML Purifier</title>
+
+</head><body>
+
+<h1 class="subtitled">Embedding YouTube Videos</h1>
+<div class="subtitle">...as well as other dangerous active content</div>
+
+<div id="filing">Filed under End-User</div>
+<div id="index">Return to the <a href="index.html">index</a>.</div>
+<div id="home"><a href="http://hp.jpsband.org/">HTML Purifier</a> End-User Documentation</div>
+
+<p>Clients like their YouTube videos. It gives them a warm fuzzy feeling when
+they see a neat little embedded video player on their websites that can play
+the latest clips from their documentary &quot;Fido and the Bones of Spring&quot;.
+All joking aside, the ability to embed YouTube videos or other active
+content in their pages is something that a lot of people like.</p>
+
+<p>This is a <em>bad</em> idea. The moment you embed anything untrusted,
+you will definitely be slammed by a manner of nasties that can be
+embedded in things from your run of the mill Flash movie to
+<a href="http://blog.spywareguide.com/2006/12/myspace_phish_attack_leads_use.html">Quicktime movies</a>.
+Even <code>img</code> tags, which HTML Purifier allows by default, can be
+dangerous. Be distrustful of anything that tells a browser to load content
+from another website automatically.</p>
+
+<p>Luckily for us, however, whitelisting saves the day. Sure, letting users
+include any old random flash file could be dangerous, but if it's
+from a specific website, it probably is okay. If no amount of pleading will
+convince the people upstairs that they should just settle with just linking
+to their movies, you may find this technique very useful.</p>
+
+<h2>Sample</h2>
+
+<p>Below is custom code that allows users to embed
+YouTube videos. This is not favoritism: this trick can easily be adapted for
+other forms of embeddable content.</p>
+
+<p>Usually, websites like YouTube give us boilerplate code that you can insert
+into your documents. YouTube's code goes like this:</p>
+
+<pre>
+&lt;object width=&quot;425&quot; height=&quot;350&quot;&gt;
+  &lt;param name=&quot;movie&quot; value=&quot;http://www.youtube.com/v/AyPzM5WK8ys&quot; /&gt;
+  &lt;param name=&quot;wmode&quot; value=&quot;transparent&quot; /&gt;
+  &lt;embed src=&quot;http://www.youtube.com/v/AyPzM5WK8ys&quot;
+         type=&quot;application/x-shockwave-flash&quot;
+         wmode=&quot;transparent&quot; width=&quot;425&quot; height=&quot;350&quot; /&gt;
+&lt;/object&gt;
+</pre>
+
+<p>There are two things to note about this code:</p>
+
+<ol>
+    <li><code>&lt;embed&gt;</code> is not recognized by W3C, so if you want
+        standards-compliant code, you'll have to get rid of it.</li>
+    <li>The code is exactly the same for all instances, except for the
+        identifier <tt>AyPzM5WK8ys</tt> which tells us which movie file
+        to retrieve.</li>
+</ol>
+
+<p>What point 2 means is that if we have code like <code>&lt;span
+class=&quot;embed-youtube&quot;&gt;AyPzM5WK8ys&lt;/span&gt;</code> your
+application can reconstruct the full object from this small snippet that
+passes through HTML Purifier <em>unharmed</em>.</p>
+
+<pre>
+&lt;?php
+
+class HTMLPurifierX_PreserveYouTube extends HTMLPurifier
+{
+    function purify($html, $config = null) {
+        $pre_regex = '#&lt;object[^&gt;]+&gt;.+?'.
+            'http://www.youtube.com/v/([A-Za-z0-9]+).+?&lt;/object&gt;#';
+        $pre_replace = '&lt;span class=&quot;youtube-embed&quot;&gt;\1&lt;/span&gt;';
+        $html = preg_replace($pre_regex, $pre_replace, $html);
+        $html = parent::purify($html, $config);
+        $post_regex = '#&lt;span class=&quot;youtube-embed&quot;&gt;([A-Za-z0-9]+)&lt;/span&gt;#';
+        $post_replace = '&lt;object width=&quot;425&quot; height=&quot;350&quot; '.
+            'data=&quot;http://www.youtube.com/v/\1&quot;&gt;'.
+            '&lt;param name=&quot;movie&quot; value=&quot;http://www.youtube.com/v/\1&quot;&gt;&lt;/param&gt;'.
+            '&lt;param name=&quot;wmode&quot; value=&quot;transparent&quot;&gt;&lt;/param&gt;'.
+            '&lt;!--[if IE]&gt;'.
+            '&lt;embed src=&quot;http://www.youtube.com/v/\1&quot;'.
+            'type=&quot;application/x-shockwave-flash&quot;'.
+            'wmode=&quot;transparent&quot; width=&quot;425&quot; height=&quot;350&quot; /&gt;'.
+            '&lt;![endif]--&gt;'.
+            '&lt;/object&gt;';
+        $html = preg_replace($post_regex, $post_replace, $html);
+        return $html;
+    }
+}
+
+$purifier = new HTMLPurifierX_PreserveYouTube();
+$html_still_with_youtube = $purifier->purify($html_with_youtube);
+
+?&gt;
+</pre>
+
+<p>There is a bit going on here, so let's explain.</p>
+
+<ol>
+    <li>The class uses the prefix <code>HTMLPurifierX</code> because it's
+        userspace code. Don't use <code>HTMLPurifier</code> in front of your
+        class, since it might clobber another class in the library.</li>
+    <li>In order to keep the interface compatible, we've extended HTMLPurifier
+        into a new class that preserves the YouTube videos. This means that
+        all you have to do is replace all instances of
+        <code>new HTMLPurifier</code> to <code>new
+        HTMLPurifierX_PreserveYouTube</code>. There's other ways to go about
+        doing this: if you were calling a function that wrapped HTML Purifier,
+        you could paste the PHP right there. If you wanted to be really
+        fancy, you could make a decorator for HTMLPurifier.</li>
+    <li>The first preg_replace call replaces any YouTube code users may have
+        embedded into the benign span tag. Span is used because it is inline,
+        and objects are inline too. We are very careful to be extremely
+        restrictive on what goes inside the span tag, as if an errant code
+        gets in there it could get messy.</li>
+    <li>The HTML is then purified as usual.</li>
+    <li>Then, another preg_replace replaces the span tag with a fully fledged
+        object. Note that the embed is removed, and, in its place, a data
+        attribute was added to the object. This makes the tag standards
+        compliant! It also breaks Internet Explorer, so we add in a bit of
+        conditional comments with the old embed code to make it work again.
+        It's all quite convoluted but works.</li>
+</ol>
+
+<h2>Warning</h2>
+
+<p>There are a number of possible problems with the code above, depending
+on how you look at it.</p>
+
+<h3>Cannot change width and height</h3>
+
+<p>The width and height of the final YouTube movie cannot be adjusted. This
+is because I am lazy. If you really insist on letting users change the size
+of the movie, what you need to do is package up the attributes inside the
+span tag (along with the movie ID). It gets complicated though: a malicious
+user can specify an outrageously large height and width and attempt to crash
+the user's operating system/browser. You need to either cap it by limiting
+the amount of digits allowed in the regex or using a callback to check the
+number.</p>
+
+<h3>Trusts media's host's security</h3>
+
+<p>By allowing this code onto our website, we are trusting that YouTube has
+tech-savvy enough people not to allow their users to inject malicious
+code into the Flash files.  An exploit on YouTube means an exploit on your
+site.  Even though YouTube is run by the reputable Google, it
+<a href="http://ha.ckers.org/blog/20061213/google-xss-vuln/">doesn't</a>
+mean they are
+<a href="http://ha.ckers.org/blog/20061208/xss-in-googles-orkut/">invulnerable.</a>
+You're putting a certain measure of the job on an external provider (just as
+you have by entrusting your user input to HTML Purifier), and
+it is important that you are cognizant of the risk.</p>
+
+<h3>Poorly written adaptations compromise security</h3>
+
+<p>This should go without saying, but if you're going to adapt this code
+for Google Video or the like, make sure you do it <em>right</em>. It's
+extremely easy to allow a character too many in the final section and
+suddenly you're introducing XSS into HTML Purifier's XSS free output. HTML
+Purifier may be well written, but it cannot guard against vulnerabilities
+introduced after it has finished.</p>
+
+<h2>Future plans</h2>
+
+<p>This functionality is part of the core library, using the
+HTMLPurifier_Filter class to acheive the desired effect. Our implementation
+is slightly different, and this page will be updated to reflect that
+once 1.4.0 is released.</p>
+
+</body>
+</html>

docs/examples/basic.php

@@ -1,15 +1,14 @@
-<?php
+<?php exit;
 
 // This file demonstrates basic usage of HTMLPurifier.
 
-exit; // not to be called directly, it will fail fantastically!
-
-set_include_path('/path/to/htmlpurifier/library' . PATH_SEPARATOR . get_include_path());
-require_once 'HTMLPurifier.php';
+require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 
 $purifier = new HTMLPurifier();
 $html = '<b>Simple and short';
 
 $pure_html = $purifier->purify($html);
 
+echo $pure_html;
+
 ?>

docs/examples/demo.php

@@ -1,32 +1,66 @@
 <?php
 
-header('Content-type:text/html;charset=UTF-8');
+// using _REQUEST because we accept GET and POST requests
 
-?><!DOCTYPE html 
-     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+$content = empty($_REQUEST['xml']) ? 'text/html' : 'application/xhtml+xml';
+header("Content-type:$content;charset=UTF-8");
+
+// prevent PHP versions with shorttags from barfing
+echo '<?xml version="1.0" encoding="UTF-8" ?>
+';
+
+function getFormMethod() {
+    return (isset($_REQUEST['post'])) ? 'post' : 'get';
+}
+
+if (empty($_REQUEST['strict'])) {
+?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html>
+<?php
+} else {
+?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<?php
+}
+?>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
 <head>
-<title>HTMLPurifier Live Demo</title>
+<title>HTML Purifier Live Demo</title>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
 </head>
 <body>
-<h1>HTMLPurifier Live Demo</h1>
+<h1>HTML Purifier Live Demo</h1>
 <?php
 
-set_include_path('../../library' . PATH_SEPARATOR . get_include_path());
-require_once 'HTMLPurifier.php';
+require_once '../../library/HTMLPurifier.auto.php';
 
-if (!empty($_POST['html'])) {
+if (!empty($_REQUEST['html'])) { // start result
     
-    $html = get_magic_quotes_gpc() ? stripslashes($_POST['html']) : $_POST['html'];
+    if (strlen($_REQUEST['html']) > 50000) {
+        ?>
+        <p>Request exceeds maximum allowed text size of 50kb.</p>
+        <?php
+    } else { // start main processing
     
-    $purifier = new HTMLPurifier();
+    $html = get_magic_quotes_gpc() ? stripslashes($_REQUEST['html']) : $_REQUEST['html'];
+    
+    $config = HTMLPurifier_Config::createDefault();
+    $config->set('Core', 'TidyFormat', !empty($_REQUEST['tidy']));
+    $config->set('HTML', 'Strict',     !empty($_REQUEST['strict']));
+    $purifier = new HTMLPurifier($config);
     $pure_html = $purifier->purify($html);
     
 ?>
 <p>Here is your purified HTML:</p>
 <div style="border:5px solid #CCC;margin:0 10%;padding:1em;">
+<?php if(getFormMethod() == 'get') { ?>
+<div style="float:right;">
+    <a href="http://validator.w3.org/check?uri=referer"><img
+        src="http://www.w3.org/Icons/valid-xhtml10"
+        alt="Valid XHTML 1.0 Transitional" height="31" width="88" style="border:0;" /></a>
+</div>
+<?php } ?>
 <?php
 
 echo $pure_html;
@@ -41,23 +75,34 @@ echo htmlspecialchars($pure_html, ENT_COMPAT, 'UTF-8');
 
 ?></pre>
 <?php
-    
+if (getFormMethod() == 'post') { // start POST validation notice
+?>
+<p>If you would like to validate the code with
+<a href="http://validator.w3.org/#validate-by-input">W3C's
+validator</a>, copy and paste the <em>entire</em> demo page's source.</p>
+<?php
+} // end POST validation notice
+
+} // end main processing
+
+// end result
 } else {
 
 ?>
-<p>Welcome to the live demo.  Enter some HTML and see how HTMLPurifier
+<p>Welcome to the live demo.  Enter some HTML and see how HTML Purifier
 will filter it.</p>
 <?php
 
 }
 
 ?>
-<form name="filter" action="demo.php<?php
-if (isset($_GET['profile']) || isset($_GET['XDEBUG_PROFILE'])) {
-    echo '?XDEBUG_PROFILE=1';
-} ?>" method="post">
+<form id="filter" action="demo.php<?php
+echo '?' . getFormMethod();
+if (isset($_REQUEST['profile']) || isset($_REQUEST['XDEBUG_PROFILE'])) {
+    echo '&amp;XDEBUG_PROFILE=1';
+} ?>" method="<?php echo getFormMethod();  ?>">
     <fieldset>
-        <legend>HTML</legend>
+        <legend>HTML Purifier Input (<?php echo getFormMethod(); ?>)</legend>
         <textarea name="html" cols="60" rows="15"><?php
 
 if (isset($html)) {
@@ -65,11 +110,27 @@ if (isset($html)) {
             HTMLPurifier_Encoder::cleanUTF8($html), ENT_COMPAT, 'UTF-8');
 }
         ?></textarea>
+        <?php if (getFormMethod() == 'get') { ?>
+            <p><strong>Warning:</strong> GET request method can only hold
+                8129 characters (probably less depending on your browser).
+                If you need to test anything
+                larger than that, try the <a href="demo.php?post">POST form</a>.</p>
+        <?php } ?>
+        <?php if (extension_loaded('tidy')) { ?>
+            <div>Nicely format output with Tidy? <input type="checkbox" value="1"
+            name="tidy"<?php if (!empty($_REQUEST['tidy'])) echo ' checked="checked"'; ?> /></div>
+        <?php } ?>
+        <div>XHTML 1.0 Strict output? <input type="checkbox" value="1"
+        name="strict"<?php if (!empty($_REQUEST['strict'])) echo ' checked="checked"'; ?> /></div>
+        <div>Serve as application/xhtml+xml? (not for IE) <input type="checkbox" value="1"
+        name="xml"<?php if (!empty($_REQUEST['xml'])) echo ' checked="checked"'; ?> /></div>
         <div>
             <input type="submit" value="Submit" name="submit" class="button" />
         </div>
     </fieldset>
 </form>
-<p>Return to <a href="http://hp.jpsband.org/">HTMLPurifier's home page</a>.</p>
+<p>Return to <a href="http://hp.jpsband.org/">HTML Purifier's home page</a>.
+Try the form in <a href="demo.php?get">GET</a> and <a href="demo.php?post">POST</a> request
+flavors (GET is easy to validate with W3C, but POST allows larger inputs).</p>
 </body>
 </html>

docs/filter-levels.txt

@@ -1,67 +0,0 @@
-
-Filter Levels
-    When one size *does not* fit all
-
-The more I think about it, the less sense it makes for maintaining one huge
-monolithic HTMLDefinition class.  There's simply so much variation that
-could go into this definition: the set of HTML good for blog entries is
-definitely too large for HTML that would be allowed in blog comments. Going
-from Transitional to Strict requires changes to the definition.
-
-However, allowing users to specify their own whitelists was an idea I
-rejected from the start.  Simply put, the typical programmer is too lazy
-to actually go through the trouble of investigating which tags, attributes
-and properties to allow.  HTMLDefinition makes a big part of what HTMLPurifier
-is.
-
-The idea, then, is to setup fundamentally different set of definitions, which
-can further be customized using simpler configuration options.
-
-Here are some fuzzy levels you could set:
-
-1. Comments - Wordpress recommends a, abbr, acronym, b, blockquote, cite,
-    code, em, i, strike, strong; however, you could get away with only a, b and
-    i; also having p and pre tags would be helpful.
-2. Pages - As permissive as possible without allowing XSS.  No protection
-    against bad design sense, unfortunantely.  Suitable for wiki and page
-    environments.
-3. Lint - Accept everything in the spec, a Tidy wannabe.
-
-I've also decomposed tags into risk levels.  An asterisk indicates that no one
-really uses that tag, tilde indicates it's deprecated.
-
-1 - blockquote, code, em, i, p, tt / strong, sub, sup
-1* - abbr, acronym, bdo, cite, dfn, kbd, q, samp
-2 - b, br, del, div, pre, span / ins, s, strike ~ u
-3 - h2, h3, h4, h5, h6 ~ center
-4 - h1, big ~ font
-5 - a
-7 - area, map
-
-Lists - dd, dl, dt, li, ol, ul ~ menu, dir
-Tables - caption, table, td, th, tr / col, colgroup, tbody, tfoot, thead
-Forms - fieldset, form, input, lable, legend, optgroup, option, select, textarea
-XSS - noscript, object, script ~ applet
-
-Meta - base, basefont, body, head, html, link, meta, style, title
-Frames - frame, frameset, iframe
-
-And tag specific notes:
-
-a - general problems involving linkspam
-b - too much bold is bad, typographically speaking bold is discouraged
-br - often misused
-center - CSS, usually no legit use
-del - only useful in editing context
-div - little meaning in certain contexts i.e. blog comment
-h1 - usually no legit use, as header is already set by application
-h* - not needed in blog comments
-hr - usually not necessary in blog comments
-img - could be extremely undesirable if linking to external pics
-pre - could use formatting, only useful in code contexts
-q - very little support
-s - transform into span with styling or del?
-small - technically presentational
-span - depends on attribute allowances
-sub, sup - specialized
-u - little legit use, prefer class with text-decoration

docs/index.html

@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="description" content="Index to all HTML Purifier documentation." />
+<link rel="stylesheet" type="text/css" href="./style.css" />
+
+<title>Documentation - HTML Purifier</title>
+
+</head>
+<body>
+
+<h1>Documentation</h1>
+
+<p><strong><a href="http://hp.jpsband.org/">HTML Purifier</a></strong> has documentation for all types of people.
+Here is an index of all of them.</p>
+
+<h2>End-user</h2>
+<p>End-user documentation that contains articles, tutorials and useful
+information for casual developers using HTML Purifier.</p>
+
+<dl>
+
+<dt><a href="enduser-id.html">IDs</a></dt>
+<dd>Explains various methods for allowing IDs in documents safely.</dd>
+
+<dt><a href="enduser-youtube.html">Embedding YouTube videos</a></dt>
+<dd>Explains how to safely allow the embedding of flash from trusted sites.</dd>
+
+<dt><a href="enduser-slow.html">Speeding up HTML Purifier</a></dt>
+<dd>Explains how to speed up HTML Purifier through caching or inbound filtering.</dd>
+
+<dt><a href="enduser-utf8.html">UTF-8</a></dt>
+<dd>Describes the rationale for using UTF-8, the ramifications otherwise, and how to make the switch.</dd>
+
+</dl>
+
+<h2>Development</h2>
+<p>Developer documentation detailing code issues, roadmaps and project
+conventions.</p>
+
+<dl>
+
+<dt><a href="dev-code-quality.html">Code Quality Issues</a></dt>
+<dd>Discusses code quality issues and places that need to be refactored.</dd>
+
+<dt><a href="dev-progress.html">Implementation Progress</a></dt>
+<dd>Tables detailing HTML element and CSS property implementation coverage.</dd>
+
+<dt><a href="dev-naming.html">Naming Conventions</a></dt>
+<dd>Defines class naming conventions.</dd>
+
+<dt><a href="dev-optimization.html">Optimization</a></dt>
+<dd>Discusses possible methods of optimizing HTML Purifier.</dd>
+
+</dl>
+
+<h2>Proposals</h2>
+<p>Proposed features, as well as the associated rambling to get a clear
+objective in place before attempted implementation.</p>
+
+<dl>
+<dt><a href="proposal-colors.html">Colors</a></dt>
+<dd>Proposal to allow for color constraints.</dd>
+</dl>
+
+<h2>Reference</h2>
+<p>Miscellaneous essays, research pieces and other reference type material
+that may not directly discuss HTML Purifier.</p>
+
+<dl>
+<dt><a href="ref-devnetwork.html">DevNetwork Credits</a></dt>
+<dd>Credits and links to DevNetwork forum topics.</dd>
+</dl>
+
+<h2>Internal memos</h2>
+
+<p>Plaintext documents that are more for use by active developers of
+the code. They may be upgraded to HTML files or stay as TXT scratchpads.</p>
+
+<table class="table">
+
+<thead><tr>
+    <th width="10%">Type</th>
+    <th width="20%">Name</th>
+    <th>Description</th>
+</tr></thead>
+
+<tbody>
+
+<tr>
+    <td>End-user</td>
+    <td><a href="enduser-overview.txt">Overview</a></td>
+    <td>High level overview of the general control flow (mostly obsolete).</td>
+</tr>
+
+<tr>
+    <td>End-user</td>
+    <td><a href="enduser-security.txt">Security</a></td>
+    <td>Common security issues that may still arise (half-baked).</td>
+</tr>
+
+<tr>
+    <td>Proposal</td>
+    <td><a href="proposal-filter-levels.txt">Filter levels</a></td>
+    <td>Outlines details of projected configurable level of filtering.</td>
+</tr>
+
+<tr>
+    <td>Proposal</td>
+    <td><a href="proposal-language.txt">Language</a></td>
+    <td>Specification of I18N for error messages derived from MediaWiki (half-baked).</td>
+</tr>
+
+<tr>
+    <td>Proposal</td>
+    <td><a href="proposal-new-directives.txt">New directives</a></td>
+    <td>Assorted configuration options that could be implemented.</td>
+</tr>
+
+<tr>
+    <td>Reference</td>
+    <td><a href="ref-loose-vs-strict.txt">Loose vs.Strict</a></td>
+    <td>Differences between HTML Strict and Transitional versions.</td>
+</tr>
+
+<tr>
+    <td>Reference</td>
+    <td><a href="ref-proprietary-tags.txt">Proprietary tags</a></td>
+    <td>List of vendor-specific tags we may want to transform to W3C compliant markup.</td>
+</tr>
+
+<tr>
+    <td>Reference</td>
+    <td><a href="ref-strictness.txt">Strictness</a></td>
+    <td>Short essay on how loose definition isn't really loose.</td>
+</tr>
+
+<tr>
+    <td>Reference</td>
+    <td><a href="ref-xhtml-1.1.txt">XHTML 1.1</a></td>
+    <td>What we'd have to do to support XHTML 1.1.</td>
+</tr>
+
+<tr>
+    <td>Reference</td>
+    <td><a href="ref-whatwg.txt">WHATWG</a></td>
+    <td>How WHATWG plays into what we need to do.</td>
+</tr>
+
+</tbody>
+
+</table>
+
+<div id="version">$Id$</div>
+</body>
+</html>

docs/naming.txt

@@ -1,56 +0,0 @@
-
-Naming
-
-The classes in this library follow a few naming conventions, which may
-help you find the correct functionality more quickly.  Here they are:
-
-All classes occupy the HTMLPurifier pseudo-namespace.
-    This means that all classes are prefixed with HTMLPurifier_.  As such, all
-    names under HTMLPurifier_ are reserved.  I recommend that you use the name
-    HTMLPurifierX_YourName_ClassName, especially if you want to take advantage
-    of HTMLPurifier_ConfigDef.
-
-All classes correspond to their path if library/ was in the include path
-    HTMLPurifier_AttrDef is located at HTMLPurifier/AttrDef.php; replace
-    underscores with slashes and append .php and you'll have the location of
-    the class.
-
-Harness and Test are reserved class names for unit tests
-    The suffix "Test" indicates that the class is a subclass of UnitTestCase
-    (of the Simpletest library) and is testable. "Harness" indicates a subclass
-    of UnitTestCase that is not meant to be run but to be extended into 
-    concrete test cases and contains custom test methods (i.e. assert*())
-
-Class names do not necessarily represent inheritance hierarchies
-    While we try to reflect inheritance in naming to some extent, it is not
-    guaranteed (for instance, none of the classes inherit from HTMLPurifier,
-    the base class).  However, all class files have the require_once
-    declarations to whichever classes they are tightly coupled to.
-
-Strategy has a meaning different from the Gang of Four pattern
-    In Design Patterns, the Gang of Four describes a Strategy object as
-    encapsulating an algorithm so that they can be switched at run-time.  While
-    our strategies are indeed algorithms, they are not meant to be substituted:
-    all must be present in order for proper functioning.
-
-Abbreviations are avoided
-    We try to avoid abbreviations as much as possible, but in some cases, 
-    abbreviated version is more readable than the full version. Here, we
-    list common abbreviations:
-        Attr(s) -> Attribute(s)
-        Def -> Definition
-
-Ambiguity concerning the definition of Def/Definition
-    While a definition normally defines the structure/acceptable values of
-    an entity, most of the definitions in this application also attempt
-    to validate and fix the value.  I am unsure of a better name, as
-    "Validator" would exclude fixing the value, "Fixer" doesn't invoke
-    the proper image of "fixing" something, and "ValidatorFixer" is too long!
-    Some other suggestions were "Handler", "Reference", "Check", "Fix",
-    "Repair" and "Heal".
-
-Transform not Transformer
-    Transform is both a noun and a verb, and thus we define a "Transform" as
-    something that "transforms," leaving "Transformer" (which sounds like an
-    electrical device/robot toy).
-

docs/optimization.txt

@@ -1,11 +0,0 @@
-
-Optimization
-
-Here are some possible optimization techniques we can apply to code sections if
-they turn out to be slow.  Be sure not to prematurely optimize though!
-
- - Make Tokens Flyweights
- - Rewrite regexps into PHP code
- - Serialize the Definition object
- - Batch regexp validation (do as many per function call as possible)
- - Parallelize strategies

docs/proposal-colors.html

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="description" content="Proposal to allow for color constraints in HTML Purifier." />
+<link rel="stylesheet" type="text/css" href="./style.css" />
+
+<title>Proposal: Colors - HTML Purifier</title>
+
+</head><body>
+
+<h1 class="subtitled">Colors</h1>
+<div class="subtitle">Hammering some sense into those color-blind newbies</div>
+
+<div id="filing">Filed under Proposals</div>
+<div id="index">Return to the <a href="index.html">index</a>.</div>
+<div id="home"><a href="http://hp.jpsband.org/">HTML Purifier</a> End-User Documentation</div>
+
+<p>Your website probably has a color-scheme.
+<span style="color:#090; background:#FFF;">Green on white</span>,
+<span style="color:#A0F; background:#FF0;">purple on yellow</span>,
+whatever. When you give users the ability to style their content, you may
+want them to keep in line with your styling. If you're website is all
+about light colors, you don't want a user to come in and vandalize your
+page with a deep maroon.</p>
+
+<p>This is an extremely silly feature proposal, but I'm writing it down anyway.</p>
+
+<p>What if the user could constrain the colors specified in inline styles? You
+are only allowed to use these shades of dark green for text and these shades
+of light yellow for the background. At the very least, you could ensure
+that we did not have pale yellow on white text.</p>
+
+<h2>Implementation issues</h2>
+
+<ol>
+<li>Requires the color attribute definition to know, currently, what the text
+and background colors are. This becomes difficult when classes are thrown
+into the mix.</li>
+<li>The user still has to define the permissible colors, how does one do
+something like that?</li>
+</ol>
+
+<div id="version">$Id$</div>
+
+</body>
+</html>

docs/proposal-config.txt

@@ -10,31 +10,19 @@ Directives are divided into namespaces, indicating the major portion of
 functionality they cover (although there may be overlaps.  Please consult
 the documentation in ConfigDef for more information on these namespaces.
 
-Since configuration is dependent on context, most of the internal classes
-require a configuration object to be passed as a parameter.  However, a few
-make this optional: they will supply a default configuration object if none
-are passed.  These classes are: HTMLPurifier::*, Generator::generateFromTokens
-and Lexer::tokenizeHTML.  However, whenever a valid configuration object
-is defined, that object should be used.
+Since configuration is dependant on context, internal classes require a
+configuration object to be passed as a parameter.  (They also require a
+Context object).
 
--- the following is projected changes to the configuration system --
-
-In relation to HTMLDefinition and CSSDefinition, there are going to be some
-major structural changes to enable the easy configuration of these objects.
-Due to the intricacy of these objects, it's not feasible to ask an average
-user to twiddle around with an element and its 20 other dependencies.  However,
-these objects are the only possible point where change could occur in the
-context of configuration.
-
-The solution is to introduce a special class of directives that influence the
-*construction* of the Definition object.  A standard call pattern would look
-like:
+In relation to HTMLDefinition and CSSDefinition, there could be a special class
+of directives that influence the *construction* of the Definition object.
+A theoretical call pattern would look like:
 
 1. Client calls Config->getHTMLDefinition()
 2. Config calls HTMLDefinition->createNew(this)
 3. HTMLDefinition constructs itself with base configuration
-4. HTMLDefinition calls Config->get('HTMLDefinition')
-5. Config returns array of directives that later construction
+4. HTMLDefinition calls Config->get('HTML')
+5. Config returns array of directives
 6. HTMLDefinition performs operations and changes specified by directives
 7. HTMLPurifier returns constructed definition
 8. Config caches definition so it doesn't have to be generated again
@@ -45,3 +33,7 @@ custom copy, which OVERRIDES all directives.  Only the base, vanilla copy
 is the Singleton, the object actually interfaced with is a operated-upon
 clone of that object.  Also, if an update to the directives would update
 the definition, you'd have to force reconstruction.
+
+In practice, the pulling directives from the config object are
+solely need-based, and the flex points are littered throughout the
+setup() function.  Some sort of refactoring is likely in order.

docs/proposal-filter-levels.txt

@@ -0,0 +1,133 @@
+
+Filter Levels
+    When one size *does not* fit all
+
+The more I think about it, the less sense it makes for maintaining one huge
+monolithic HTMLDefinition class.  There's simply so much variation that
+could go into this definition: the set of HTML good for blog entries is
+definitely too large for HTML that would be allowed in blog comments. Going
+from Transitional to Strict requires changes to the definition.
+
+Allowing users to specify their own whitelists is one step (implemented, btw), 
+but I have doubts on only doing this. Simply put, the typical programmer is too 
+lazy to actually go through the trouble of investigating which tags, attributes 
+and properties to allow. HTMLDefinition makes a big part of what HTMLPurifier 
+is. 
+
+The idea, then, is to setup fundamentally different set of definitions, which
+can further be customized using simpler configuration options.  Alternatively,
+they could be implemented as configuration profiles, which simply load
+a set of recommended directives to acheive a desired affect (no simpler
+config options though).
+
+Here are some fuzzy levels you could set:
+
+1. Comments - Wordpress recommends a, abbr, acronym, b, blockquote, cite,
+    code, em, i, strike, strong; however, you could get away with only a, em and
+    p; also having blockquote and pre tags would be helpful.
+2. BBCode - Emulate the usual tagset for forums: b, i, img, a, blockquote,
+    pre, div, span and h[2-6] (the last three are for specially formatted
+    posts, div and span require associated classes or inline styling enabled
+    to be useful)
+3. Pages - As permissive as possible without allowing XSS.  No protection
+    against bad design sense, unfortunantely.  Suitable for wiki and page
+    environments. (probably what we have now)
+4. Lint - Accept everything in the spec, a Tidy wannabe. (This probably won't
+    get implemented as it would require routines for things like <object>
+    and friends to be implemented, which is a lot of work for not a lot of
+    benefit)
+
+One final note: when you start axing tags that are more commonly used, you
+run the risk of accidentally destroying user data, especially if the data
+is incoming from a WYSIWYG eidtor that hasn't been synced accordingly. This may
+make forbidden element to text transformations desirable (for example, images).
+
+
+
+== Element Risk Analysis ==
+
+Legend:
+    [danger level] - regular tags / uncommon tags ~ deprecated tags
+    [danger level]* - rare tags
+
+1 - blockquote, code, em, i, p, tt / strong, sub, sup
+1* - abbr, acronym, bdo, cite, dfn, kbd, q, samp
+2 - b, br, del, div, pre, span / ins, s, strike ~ u
+3 - h2, h3, h4, h5, h6 ~ center
+4 - h1, big ~ font
+5 - a
+7 - area, map
+
+These are special use tags, they should be enabled on a blanket basis.
+
+Lists - dd, dl, dt, li, ol, ul ~ menu, dir
+Tables - caption, table, td, th, tr / col, colgroup, tbody, tfoot, thead
+
+Forms - fieldset, form, input, lable, legend, optgroup, option, select, textarea
+XSS - noscript, object, script ~ applet
+Meta - base, basefont, body, head, html, link, meta, style, title
+Frames - frame, frameset, iframe
+
+And tag specific notes:
+
+a   - general problems involving linkspam
+b   - too much bold is bad, typographically speaking bold is discouraged
+br  - often misused
+center - CSS, usually no legit use
+del - only useful in editing context
+div - little meaning in certain contexts i.e. blog comment
+h1  - usually no legit use, as header is already set by application
+h*  - not needed in blog comments
+hr  - usually not necessary in blog comments
+img - could be extremely undesirable if linking to external pics (CSRF, goatse)
+pre - could use formatting, only useful in code contexts
+q   - very little support
+s   - transform into span with styling or del?
+small - technically presentational
+span - depends on attribute allowances
+sub, sup - specialized
+u   - little legit use, prefer class with text-decoration
+
+Based on the riskiness of the items, we may want to offer %HTML.DisableImages
+attribute and put URI filtering higher up on the priority list.
+
+
+== Attribute Risk Analysis ==
+
+We actually have a suprisingly small assortment of allowed attributes (the
+rest are deprecated in strict, and thus we opted not to allow them, even
+though our output is XHTML Transitional by default.)
+
+Required URI - img.alt, img.src, a.href
+Medium risk - *.class, *.dir
+High risk - img.height, img.width, *.id, *.style
+
+Table - colgroup/col.span, td/th.rowspan, td/th.colspan
+Uncommon - *.title, *.lang, *.xml:lang
+Rare - td/th.abbr, table.summary, {table}.charoff
+Rare URI - del.cite, ins.cite, blockquote.cite, q.cite, img.longdesc
+Presentational - {table}.align, {table}.valign, table.frame, table.rules,
+    table.border
+Partially presentational - table.cellpadding, table.cellspacing,
+    table.width, col.width, colgroup.width
+
+
+== CSS Risk Analysis ==
+
+There are certain CSS elements that are extremely useful inline, but then
+as you get to more presentation oriented styling it may not always be
+appropriate to inline them.
+
+Useful - clear, float, border-collapse, caption-side
+
+These CSS properties can break layouts if used improperly. We have excluded
+any CSS properties that are not currently implemented (such as position).
+
+Dangerous, can go outside container - float
+Easy to abuse - font-size, font-family (font), width
+Colored - background-color (background), border-color (border), color
+Dramatic - border, list-style-position (list-style), margin, padding,
+    text-align, text-indent, text-transform, vertical-align, line-height
+
+Dramatic elements substantially change the look of text in ways that should
+probably have been reserved to other areas.

docs/proposal-language.txt

@@ -0,0 +1,98 @@
+We are going to model our I18N/L10N off of MediaWiki's system.  Their's is
+obviously quite complicated, so we're going to simplify it a bit for our needs.
+
+== Structure ==
+
+First, you have a Language object.  This object contains all the localisable
+message strings, as well as other important language-specific settings and
+custom behavior (uppercasing, lowercasing, printing dates, formatting
+numbers, etc.)
+
+The object is constructed from two sources: subclassed versions of itself
+(classes) and Message files (messages).
+
+== General use ==
+
+You load a language object by calling the Language::factory() function. 
+This function the class file for the object (taking in account fallback 
+languages by using the fallback langauge's object but overloading the 
+language key) and returns that object. Nothing else happens.
+
+When a message/etc is requested, a lazy load initializor is called.  Now the
+real work starts.  We're first going to take the scenario that the language
+is not cached.  The system loads the Messages file by:
+
+    require( $filename );
+    $cache = compact( self::$mLocalisationKeys );	
+
+...where self::$mLocalisationKeys is the name of variables that could be used
+in the localization file. This lets you use things like:
+
+    $fallback = false;
+    $rtl = false;
+
+...and easily siphon them into arrays.
+
+Then, we load the $fallback language (if not set, English) to fill in the gaps in
+the messages.  There is specialized behavior for certain keys, as they can be
+mergeable maps, lists or alias lists (not sure what the last one is).
+
+== Caching ==
+
+MediaWiki has lots of caching mechanisms built in, which make the code somewhat
+more difficult to understand.  Before doing any loading, MediaWiki will check
+the following places to see if we can be lazy:
+
+1. $mLocalisationCache[$code] -  just a variable where it may have been stashed
+2. serialized/$code.ser -  compiled serialized language file
+3. Memcached version of file (with expiration checking)
+
+Expiration checking consists of by ensuring all dependencies have filemtime
+that match the ones bundled with the cached copy. Similar checking could be
+implemented for serialized versions, as it seems that they are not updated
+until manually recompiled.
+
+== Behavior ==
+
+Things that are localizable:
+
+-  Weekdays (and abbrev)
+-  Months (and abbrev)
+-  Bookstores
+-  Skin names
+-  Date preferences / Custom date format
+-  Default date format
+-  Default user option overrides
+-+ Language names
+-  Timezones
+-+ Character encoding conversion via iconv
+-  UpperLowerCase first (needs casemaps for some)
+-  UpperLowerCase
+-  Uppercase words
+-  Uppercase word breaks
+-  Case folding
+-  Strip punctuation for MySQL search
+-  Get first character
+-+ Alternate encoding
+-+ Recoding for edit (and then recode input)
+-+ RTL
+-+ Direction mark character depending on RTL
+-? Arrow depending on RTL
+-  Languages where italics cannot be used
+-+ Number formatting (commafy, transform digits, transform separators)
+-  Truncate (multibyte)
+-  Grammar conversions for inflected languages
+-  Plural transformations
+-  Formatting expiry times
+-  Segmenting for diffs (Chinese)
+-  Convert to variants of language
+-  Language specific user preference options
+-  Link trails [[foo]]bar
+-+ Language code (RFC 3066)
+
+Neat functionality:
+
+-  I18N sprintfDate
+-  Roman numeral formatting
+
+Items marked with a + likely need to be addressed by HTML Purifier

docs/proposal-new-directives.txt

@@ -0,0 +1,44 @@
+
+Configuration Ideas
+
+Here are some theoretical configuration ideas that we could implement some
+time.  Note the naming convention: %Namespace.Directive
+
+%Attr.RewriteFragments - if there's %Attr.IDPrefix we may want to transparently
+    rewrite the URLs we parse too.  However, we can only do it when it's a pure
+    anchor link, so it's not foolproof
+
+%Attr.ClassBlacklist,
+%Attr.ClassWhitelist,
+%Attr.ClassPolicy - determines what classes are allowed. When
+    %Attr.ClassPolicy is set to Blacklist, only allow those not in
+    %Attr.ClassBlacklist. When it's Whitelist, only allow those in
+    %Attr.ClassWhitelist.
+
+%Attr.MaxWidth, 
+%Attr.MaxHeight - caps for width and height related checks.
+    (the hack in Pixels for an image crashing attack could be replaced by this)
+
+%URI.AddRelNofollow - will add rel="nofollow" to all links, preventing the
+    spread of ill-gotten pagerank
+
+%URI.RelativeToAbsolute - transforms all relative URIs to absolute form
+
+%URI.HostBlacklistRegex - regexes that if matching the host are disallowed
+%URI.HostWhitelist - domain names that are excluded from the host blacklist
+%URI.HostPolicy - determines whether or not its reject all and then whitelist
+    or allow all in then do specific blacklists with whitelist intervening.
+    'DenyAll' or 'AllowAll' (default)
+
+%URI.DisableIPHosts - URIs that have IP addresses for hosts are disallowed.
+    Be sure to also grab unusual encodings (dword, hex and octal), which may
+    be currently be caught by regular DNS
+%URI.DisableIDN - Disallow raw internationalized domain names. Punycode
+    will still be permitted.
+
+%URI.ConvertUnusualIPHosts - transform dword/hex/octal IP addresses to the
+    regular form
+%URI.ConvertAbsoluteDNS - Remove extra dots after host names that trigger
+    absolute DNS.  While this is actually the preferred method according to
+    the RFC, most people opt to use a relative domain name relative to . (root).
+

docs/ref-devnetwork.html

@@ -1,31 +1,45 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
-
-<title>DevNetwork Forums</title>
-
-</head>
-<body>
-
-<p>Many thanks to the DevNetwork community for answering questions,
-theorizing about design, and offering encouragement during
-the development of this library in these forum threads:</p>
-
-<ul>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=52905">HTMLPurifier PHP Library hompeage</a></li>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53056">How much of CSS to implement?</a></li>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53083">Parsing URL only according to URI : Security Risk?</a></li>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53096">Gimme a name : URI and friends</a></li>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53415">How to document configuration directives</a></li>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53479">IPv6</a></li>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53539">http and ftp versus news and mailto</a></li>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53579">HTMLPurifier - Take your best shot</a></li>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53664">Need help optimizing a block of code</a>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53861">Non-SGML characters</a>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=54283">Wordpress makes me cry</a>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=54478">Parameter Object vs. Parameter Array vs. Parameter Functions</a>
-    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=54521">Convert encoding where output cannot represent characters</a>
-</ul>
-</body>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="description" content="Credits and links to DevNetwork forum topics on HTML Purifier." />
+<link rel="stylesheet" type="text/css" href="./style.css" />
+
+<title>DevNetwork Credits - HTML Purifier</title>
+
+</head>
+<body>
+
+<h1>DevNetwork Credits</h1>
+
+<div id="filing">Filed under Reference</div>
+<div id="index">Return to the <a href="index.html">index</a>.</div>
+<div id="home"><a href="http://hp.jpsband.org/">HTML Purifier</a> End-User Documentation</div>
+
+<p>Many thanks to the DevNetwork community for answering questions,
+theorizing about design, and offering encouragement during
+the development of this library in these forum threads:</p>
+
+<ul>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=52905">HTMLPurifier PHP Library hompeage</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53056">How much of CSS to implement?</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53083">Parsing URL only according to URI : Security Risk?</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53096">Gimme a name : URI and friends</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53415">How to document configuration directives</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53479">IPv6</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53539">http and ftp versus news and mailto</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53579">HTMLPurifier - Take your best shot</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53664">Need help optimizing a block of code</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=53861">Non-SGML characters</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=54283">Wordpress makes me cry</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=54478">Parameter Object vs. Parameter Array vs. Parameter Functions</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=54521">Convert encoding where output cannot represent characters</a></li>
+    <li><a href="http://forums.devnetwork.net/viewtopic.php?t=56411">Reporting errors in a document without line numbers</a></li>
+</ul>
+
+<p>...as well as any I may have forgotten.</p>
+
+<div id="version">$Id$</div>
+</body>
 </html>

docs/ref-loose-vs-strict.txt

@@ -0,0 +1,37 @@
+
+Loose versus Strict
+    Changes from one doctype to another
+
+There are changes.  Wow, how insightful.  Not everything changed is relevant
+to HTML Purifier, though, so let's take a look:
+
+== Major incompatibilities ==
+
+[done] BLOCKQUOTE changes from 'flow' to 'block'
+    current behavior: inline inner contents should not be nuked, block-ify as necessary
+[partially-done] U, S, STRIKE cut
+    current behavior: removed completely
+    projected behavior: replace with appropriate inline span + CSS
+[done] ADDRESS from potpourri to Inline (removes p tags)
+    current behavior: block tags silently dropped
+    ideal behavior: replace tags with something like <br>. (not high priority)
+
+== Things we can loosen up ==
+
+Tags DIR, MENU, CENTER, ISINDEX, FONT, BASEFONT? allowed in loose
+    current behavior: transform to strict-valid forms
+Attributes allowed in loose (see attribute transforms in 'dev-progress.html')
+    current behavior: projected to transform into strict-valid forms
+
+== Periphery issues ==
+
+A tag's attribute 'target' (for selecting frames) cut
+    current behavior: not allowed at all
+    projected behavior: use loose doctype if needed, needs valid values
+[done] OL/LI tag's attribute 'start'/'value' (for renumbering lists) cut
+    current behavior: no substitute, just delete when in strict, allow in loose
+Attribute 'name' deprecated in favor of 'id'
+    current behavior: dropped silently
+    projected behavior: create proper AttrTransform (currently not allowed at all)
+[done] PRE tag allows SUB/SUP? (strict dtd comment vs syntax, loose disallows)
+    current behavior: disallow as usual

docs/ref-proprietary-tags.txt

@@ -0,0 +1,22 @@
+
+Proprietary Tags
+    <nobr> and friends
+
+Here are some proprietary tags that W3C does not define but occasionally show
+up in the wild.  We have only included tags that would make sense in an
+HTML Purifier context.
+
+<align>, block element that aligns (extremely rare)
+<blackface>, inline that double-bolds text (extremely rare)
+<comment>, hidden comment for IE and WebTV
+<multicol cols=number gutter=pixels width=pixels>, multiple columns
+<nobr>, no linebreaks
+<spacer align=* type="vertical|horizontal|block">, whitespace in doc,
+    use width/height for block and size for vertical/horizontal (attributes)
+    (extremely rare)
+<wbr>, potential word break point: allows linebreaks. Only works in <nobr>
+
+<listing>, monospace pre-variant (extremely rare)
+<plaintext>, escapes all tags to the end of document
+<ruby> and friends, (more research needed, appears to be XHTML 1.1 markup)
+<xmp>, monospace, replace with pre

docs/ref-strictness.txt

@@ -0,0 +1,37 @@
+
+Is HTML Purifier Strict or Transitional?
+    A little bit of helpful guidance
+
+Despite the fact that HTML Purifier professes to support both transitional and
+strict HTML, it rejects a lot of attributes and elements that are actually, indeed,
+valid. You can investigate progress.html to find out precisely what we
+are doing to these *deprecated* attributes.
+
+However, users have found that Strict HTML imposes some quite unreasonable
+restrictions on certain things. The start and value attributes in ol and
+li (respectively) perhaps are the most contested. There's is currently no
+widely supported browser method short of JavaScript that can replace these
+two deprecated elements. It behooves us to allow these deprecated
+attributes when the output is transitional.
+
+Fortunantely, that's the only real bugger case. The others have near-perfect
+CSS equivalents, and were presentational anyway. However, the other question
+pops up: should we always convert these to the CSS forms when 1. the spec
+allows them anyway and 2. older browsers support them better? After all, the
+whole point about CSS is to seperate styling from content, so inline styling
+doesn't solve that problem.
+
+It's an icky question, and we'll have to deal with it as more and more 
+transforms get implemented.  As of right now, however, we currently support
+these loose-only constructs in loose mode:
+
+- <ul start="1">, <li value="1"> attributes
+- <u>, <strike>, <s> tags
+- flow children in <blockquote>
+- mixed children in <address>
+
+The changed child definitions as well as the ul.start li.value are the most
+compelling reasons why loose should be used.  We may want offer disabling <u>,
+<strike> and <s> by themselves. We may also want to offer no pre-emptive
+deprecated conversions. This all must be unified.
+

docs/ref-whatwg.txt

@@ -0,0 +1,9 @@
+
+Web Hypertext Application Technology Working Group
+    WHATWG
+
+I don't think we need to worry about them.  Untrusted users shouldn't be
+submitting applications, eh?  But if some interesting attribute pops up in
+their spec, and might be worth supporting, stick it here.
+
+(none so far, as you can see)

docs/ref-xhtml-1.1.txt

@@ -0,0 +1,21 @@
+
+Getting XHTML 1.1 Working
+
+It's quite simple, according to <http://www.w3.org/TR/xhtml11/changes.html>
+
+1. Scratch lang entirely in favor of xml:lang
+2. Scratch name entirely in favor of id (partially-done)
+3. Support Ruby <http://www.w3.org/TR/2001/REC-ruby-20010531/>
+
+...but that's only an informative section. More things to do:
+
+1. Scratch style attribute (it's deprecated)
+2. Be module-aware (this might entail intelligent grouping in the definition
+   and allowing users to specifically remove certain modules (see 5))
+3. Cross-reference minimal content models with existing DTDs and determine
+   changes (todo)
+4. Watch out for the Legacy Module
+<http://www.w3.org/TR/2001/REC-xhtml-modularization-20010410/abstract_modules.html#s_legacymodule>
+5. Let users specify their own custom modules
+6. Study Modularization document
+<http://www.w3.org/TR/2001/REC-xhtml-modularization-20010410/>

docs/style.css

@@ -0,0 +1,44 @@
+html {font-size:1em; font-family:serif; }
+body {margin-left:4em; margin-right:4em; }
+
+dt {font-weight:bold; }
+pre {margin-left:2em; }
+pre, code, tt {font-family:monospace; font-size:1em; }
+
+h1 {text-align:center; font-family:Garamond, serif;
+  font-variant:small-caps;}
+h2 {border-bottom:1px solid #CCC; font-family:sans-serif; font-weight:normal;
+    font-size:1.3em;}
+h3 {font-family:sans-serif; font-size:1.1em; font-weight:bold; }
+h4 {font-family:sans-serif; font-size:0.9em; font-weight:bold; }
+
+/* For witty quips */
+.subtitled {margin-bottom:0em;}
+.subtitle , .subsubtitle {font-size:.8em; margin-bottom:1em;
+    font-style:italic; margin-top:-.2em;text-align:center;}
+.subsubtitle {text-align:left;margin-left:2em;}
+
+/* Used for special "See also" links. */
+.reference {font-style:italic;margin-left:2em;}
+
+/* Marks off asides, discussions on why something is the way it is */
+.aside {margin-left:2em; font-family:sans-serif; font-size:0.9em; }
+blockquote .label {font-weight:bold; font-size:1em; margin:0 0 .1em;
+    border-bottom:1px solid #CCC;}
+
+/* A regular table */
+.table {border-collapse:collapse; border-bottom:2px solid #888; margin-left:2em; }
+.table thead th {margin:0; background:#888; color:#FFF; }
+.table thead th:first-child {-moz-border-radius-topleft:1em;}
+.table tbody td {border-bottom:1px solid #CCC; padding-right:0.6em;padding-left:0.6em;}
+
+/* Category of the file */
+#filing {font-weight:bold; font-size:smaller; }
+
+/* Contains, without exception, Return to index. */
+#index {font-size:smaller; }
+
+#home {font-size:smaller;}
+
+/* Contains, without exception, $Id$, for SVN version info. */
+#version {text-align:right; font-style:italic; margin:2em 0;}

library/HTMLPurifier.auto.php

@@ -0,0 +1,10 @@
+<?php
+
+/**
+ * This is a stub include that automatically configures the include path.
+ */
+
+set_include_path(dirname(__FILE__) . PATH_SEPARATOR . get_include_path() );
+require_once 'HTMLPurifier.php';
+
+?>

library/HTMLPurifier.func.php

@@ -0,0 +1,21 @@
+<?php
+
+/**
+ * Function wrapper for HTML Purifier for quick use.
+ * @note This function only includes the library when it is called. While
+ *       this is efficient for instances when you only use HTML Purifier
+ *       on a few of your pages, it murders bytecode caching. You still
+ *       need to add HTML Purifier to your path.
+ * @note ''HTMLPurifier()'' is NOT the same as ''new HTMLPurifier()''
+ */
+
+function HTMLPurifier($html, $config = null) {
+    static $purifier = false;
+    if (!$purifier) {
+        require_once 'HTMLPurifier.php';
+        $purifier = new HTMLPurifier();
+    }
+    return $purifier->purify($html, $config);
+}
+
+?>

library/HTMLPurifier.php

@@ -3,7 +3,7 @@
 /*!
  * @mainpage
  * 
- * HTMLPurifier is an HTML filter that will take an arbitrary snippet of
+ * HTML Purifier is an HTML filter that will take an arbitrary snippet of
  * HTML and rigorously test, validate and filter it into a version that
  * is safe for output onto webpages. It achieves this by:
  * 
@@ -18,11 +18,11 @@
  * However, most users will only need to interface with the HTMLPurifier
  * class, so this massive amount of infrastructure is usually concealed.
  * If you plan on working with the internals, be sure to include
- * HTMLPurifier_ConfigDef and HTMLPurifier_Config.
+ * HTMLPurifier_ConfigSchema and HTMLPurifier_Config.
  */
 
 /*
-    HTMLPurifier - Standards Compliant HTML Filtering
+    HTML Purifier 1.4.0 - Standards Compliant HTML Filtering
     Copyright (C) 2006 Edward Z. Yang
 
     This library is free software; you can redistribute it and/or
@@ -39,11 +39,14 @@
     License along with this library; if not, write to the Free Software
     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  */
- 
-require_once 'HTMLPurifier/ConfigDef.php';
+
+// almost every class has an undocumented dependency to these, so make sure
+// they get included
+require_once 'HTMLPurifier/ConfigSchema.php';
 require_once 'HTMLPurifier/Config.php';
+require_once 'HTMLPurifier/Context.php';
+
 require_once 'HTMLPurifier/Lexer.php';
-require_once 'HTMLPurifier/HTMLDefinition.php';
 require_once 'HTMLPurifier/Generator.php';
 require_once 'HTMLPurifier/Strategy/Core.php';
 require_once 'HTMLPurifier/Encoder.php';
@@ -61,51 +64,107 @@ require_once 'HTMLPurifier/Encoder.php';
 class HTMLPurifier
 {
     
+    var $version = '1.4.0';
+    
     var $config;
+    var $filters;
     
     var $lexer, $strategy, $generator;
     
+    /**
+     * Final HTMLPurifier_Context of last run purification. Might be an array.
+     * @public
+     */
+    var $context;
+    
     /**
      * Initializes the purifier.
      * @param $config Optional HTMLPurifier_Config object for all instances of
      *                the purifier, if omitted, a default configuration is
      *                supplied (which can be overridden on a per-use basis).
+     *                The parameter can also be any type that
+     *                HTMLPurifier_Config::create() supports.
      */
     function HTMLPurifier($config = null) {
         
-        $this->config = $config ? $config : HTMLPurifier_Config::createDefault();
+        $this->config = HTMLPurifier_Config::create($config);
         
         $this->lexer        = HTMLPurifier_Lexer::create();
         $this->strategy     = new HTMLPurifier_Strategy_Core();
         $this->generator    = new HTMLPurifier_Generator();
-        $this->encoder      = new HTMLPurifier_Encoder();
         
     }
     
+    /**
+     * Adds a filter to process the output. First come first serve
+     * @param $filter HTMLPurifier_Filter object
+     */
+    function addFilter($filter) {
+        $this->filters[] = $filter;
+    }
+    
     /**
      * Filters an HTML snippet/document to be XSS-free and standards-compliant.
      * 
      * @param $html String of HTML to purify
      * @param $config HTMLPurifier_Config object for this operation, if omitted,
      *                defaults to the config object specified during this
-     *                object's construction.
+     *                object's construction. The parameter can also be any type
+     *                that HTMLPurifier_Config::create() supports.
      * @return Purified HTML
      */
     function purify($html, $config = null) {
-        $config = $config ? $config : $this->config;
-        $html = $this->encoder->convertToUTF8($html, $config);
+        
+        $config = $config ? HTMLPurifier_Config::create($config) : $this->config;
+        
+        $context = new HTMLPurifier_Context();
+        $html = HTMLPurifier_Encoder::convertToUTF8($html, $config, $context);
+        
+        for ($i = 0, $size = count($this->filters); $i < $size; $i++) {
+            $html = $this->filters[$i]->preFilter($html, $config, $context);
+        }
+        
+        // purified HTML
         $html = 
             $this->generator->generateFromTokens(
+                // list of tokens
                 $this->strategy->execute(
-                    $this->lexer->tokenizeHTML($html, $config),
-                    $config
+                    // list of un-purified tokens
+                    $this->lexer->tokenizeHTML(
+                        // un-purified HTML
+                        $html, $config, $context
+                    ),
+                    $config, $context
                 ),
-                $config
+                $config, $context
             );
-        $html = $this->encoder->convertFromUTF8($html, $config);
+        
+        for ($i = $size - 1; $i >= 0; $i--) {
+            $html = $this->filters[$i]->postFilter($html, $config, $context);
+        }
+        
+        $html = HTMLPurifier_Encoder::convertFromUTF8($html, $config, $context);
+        $this->context =& $context;
         return $html;
     }
     
+    /**
+     * Filters an array of HTML snippets
+     * @param $config Optional HTMLPurifier_Config object for this operation.
+     *                See HTMLPurifier::purify() for more details.
+     * @return Array of purified HTML
+     */
+    function purifyArray($array_of_html, $config = null) {
+        $context_array = array();
+        foreach ($array_of_html as $key => $html) {
+            $array_of_html[$key] = $this->purify($html, $config);
+            $context_array[$key] = $this->context;
+        }
+        $this->context = $context_array;
+        return $array_of_html;
+    }
+    
+    
 }
 
 ?>

library/HTMLPurifier/AttrContext.php

@@ -1,26 +0,0 @@
-<?php
-
-/**
- * Internal data-structure used in attribute validation to accumulate state.
- * 
- * All it is is a data-structure that holds objects that accumulate state, like
- * HTMLPurifier_IDAccumulator.
- * 
- * @param Many functions that accept this object have it as a mandatory
- *        parameter, even when there is no use for it.  Though this is
- *        for the same reasons as why HTMLPurifier_Config is a mandatory
- *        parameter, it is also because you cannot assign a default value
- *        to a parameter passed by reference (passing by reference is essential
- *        for context to work in PHP 4).
- */
-
-class HTMLPurifier_AttrContext
-{
-    /**
-     * Contains an HTMLPurifier_IDAccumulator, which keeps track of used IDs.
-     * @public
-     */
-    var $id_accumulator;
-}
-
-?>

library/HTMLPurifier/AttrDef.php

@@ -1,7 +1,5 @@
 <?php
 
-require_once 'HTMLPurifier/AttrContext.php';
-
 /**
  * Base class for all validating attribute definitions.
  * 
@@ -16,10 +14,13 @@ class HTMLPurifier_AttrDef
 {
     
     /**
-     * Abstract function defined for functions that validate and clean strings.
-     * 
-     * This function forms the basis for all the subclasses: they must
-     * define this method.
+     * Tells us whether or not an HTML attribute is minimized. Only the
+     * boolean attribute vapourware would use this.
+     */
+    var $minimized = false;
+    
+    /**
+     * Validates and cleans passed string according to a definition.
      * 
      * @public
      * @param $string String to be validated and cleaned.
@@ -42,7 +43,16 @@ class HTMLPurifier_AttrDef
      * 
      * @note This method is not entirely standards compliant, as trim() removes
      *       more types of whitespace than specified in the spec. In practice,
-     *       this is rarely a problem.
+     *       this is rarely a problem, as those extra characters usually have
+     *       already been removed by HTMLPurifier_Encoder.
+     * 
+     * @warning This processing is inconsistent with XML's whitespace handling
+     *          as specified by section 3.3.3 and referenced XHTML 1.0 section
+     *          4.7.  Compliant processing requires all line breaks normalized
+     *          to "\n", so the fix is not as simple as fixing it in this
+     *          function.  Trim and whitespace collapsing are supposed to only
+     *          occur in NMTOKENs.  However, note that we are NOT necessarily
+     *          parsing XML, thus, this behavior may still be correct.
      * 
      * @public
      */

library/HTMLPurifier/AttrDef/Background.php

@@ -0,0 +1,87 @@
+<?php
+
+require_once 'HTMLPurifier/AttrDef.php';
+require_once 'HTMLPurifier/CSSDefinition.php';
+
+/**
+ * Validates shorthand CSS property background.
+ * @warning Does not support url tokens that have internal spaces.
+ */
+class HTMLPurifier_AttrDef_Background extends HTMLPurifier_AttrDef
+{
+    
+    /**
+     * Local copy of component validators.
+     * @note See HTMLPurifier_AttrDef_Font::$info for a similar impl.
+     */
+    var $info;
+    
+    function HTMLPurifier_AttrDef_Background($config) {
+        $def = $config->getCSSDefinition();
+        $this->info['background-color'] = $def->info['background-color'];
+        $this->info['background-image'] = $def->info['background-image'];
+        $this->info['background-repeat'] = $def->info['background-repeat'];
+        $this->info['background-attachment'] = $def->info['background-attachment'];
+        $this->info['background-position'] = $def->info['background-position'];
+    }
+    
+    function validate($string, $config, &$context) {
+        
+        // regular pre-processing
+        $string = $this->parseCDATA($string);
+        if ($string === '') return false;
+        
+        // assumes URI doesn't have spaces in it
+        $bits = explode(' ', strtolower($string)); // bits to process
+        
+        $caught = array();
+        $caught['color']    = false;
+        $caught['image']    = false;
+        $caught['repeat']   = false;
+        $caught['attachment'] = false;
+        $caught['position'] = false;
+        
+        $i = 0; // number of catches
+        $none = false;
+        
+        foreach ($bits as $bit) {
+            if ($bit === '') continue;
+            foreach ($caught as $key => $status) {
+                if ($key != 'position') {
+                    if ($status !== false) continue;
+                    $r = $this->info['background-' . $key]->validate($bit, $config, $context);
+                } else {
+                    $r = $bit;
+                }
+                if ($r === false) continue;
+                if ($key == 'position') {
+                    if ($caught[$key] === false) $caught[$key] = '';
+                    $caught[$key] .= $r . ' ';
+                } else {
+                    $caught[$key] = $r;
+                }
+                $i++;
+                break;
+            }
+        }
+        
+        if (!$i) return false;
+        if ($caught['position'] !== false) {
+            $caught['position'] = $this->info['background-position']->
+                validate($caught['position'], $config, $context);
+        }
+        
+        $ret = array();
+        foreach ($caught as $value) {
+            if ($value === false) continue;
+            $ret[] = $value;
+        }
+        
+        if (empty($ret)) return false;
+        return implode(' ', $ret);
+        
+    }
+    
+}
+
+?>

library/HTMLPurifier/AttrDef/BackgroundPosition.php

@@ -0,0 +1,130 @@
+<?php
+
+require_once 'HTMLPurifier/AttrDef.php';
+require_once 'HTMLPurifier/AttrDef/CSSLength.php';
+require_once 'HTMLPurifier/AttrDef/Percentage.php';
+
+/* W3C says:
+    [ // adjective and number must be in correct order, even if
+      // you could switch them without introducing ambiguity.
+      // some browsers support that syntax
+        [
+            <percentage> | <length> | left | center | right
+        ]
+        [ 
+            <percentage> | <length> | top | center | bottom
+        ]?
+    ] |
+    [ // this signifies that the vertical and horizontal adjectives
+      // can be arbitrarily ordered, however, there can only be two,
+      // one of each, or none at all
+        [
+            left | center | right
+        ] ||
+        [
+            top | center | bottom
+        ]
+    ]
+    top, left = 0%
+    center, (none) = 50%
+    bottom, right = 100%
+*/
+
+/* QuirksMode says:
+    keyword + length/percentage must be ordered correctly, as per W3C
+    
+    Internet Explorer and Opera, however, support arbitrary ordering. We
+    should fix it up.
+    
+    Minor issue though, not strictly necessary.
+*/
+
+// control freaks may appreciate the ability to convert these to
+// percentages or something, but it's not necessary
+
+/**
+ * Validates the value of background-position.
+ */
+class HTMLPurifier_AttrDef_BackgroundPosition extends HTMLPurifier_AttrDef
+{
+    
+    var $length;
+    var $percentage;
+    
+    function HTMLPurifier_AttrDef_BackgroundPosition() {
+        $this->length     = new HTMLPurifier_AttrDef_CSSLength();
+        $this->percentage = new HTMLPurifier_AttrDef_Percentage();
+    }
+    
+    function validate($string, $config, &$context) {
+        $string = $this->parseCDATA($string);
+        $bits = explode(' ', $string);
+        
+        $keywords = array();
+        $keywords['h'] = false; // left, right
+        $keywords['v'] = false; // top, bottom
+        $keywords['c'] = false; // center
+        $measures = array();
+        
+        $i = 0;
+        
+        $lookup = array(
+            'top' => 'v',
+            'bottom' => 'v',
+            'left' => 'h',
+            'right' => 'h',
+            'center' => 'c'
+        );
+        
+        foreach ($bits as $bit) {
+            if ($bit === '') continue;
+            
+            // test for keyword
+            $lbit = ctype_lower($bit) ? $bit : strtolower($bit);
+            if (isset($lookup[$lbit])) {
+                $status = $lookup[$lbit];
+                $keywords[$status] = $lbit;
+                $i++;
+            }
+            
+            // test for length
+            $r = $this->length->validate($bit, $config, $context);
+            if ($r !== false) {
+                $measures[] = $r;
+                $i++;
+            }
+            
+            // test for percentage
+            $r = $this->percentage->validate($bit, $config, $context);
+            if ($r !== false) {
+                $measures[] = $r;
+                $i++;
+            }
+            
+        }
+        
+        if (!$i) return false; // no valid values were caught
+        
+        
+        $ret = array();
+        
+        // first keyword
+        if     ($keywords['h'])     $ret[] = $keywords['h'];
+        elseif (count($measures))   $ret[] = array_shift($measures);
+        elseif ($keywords['c']) {
+            $ret[] = $keywords['c'];
+            $keywords['c'] = false; // prevent re-use: center = center center
+        }
+        
+        if     ($keywords['v'])     $ret[] = $keywords['v'];
+        elseif (count($measures))   $ret[] = array_shift($measures);
+        elseif ($keywords['c'])     $ret[] = $keywords['c'];
+        
+        if (empty($ret)) return false;
+        return implode(' ', $ret);
+        
+    }
+    
+}
+
+?>

library/HTMLPurifier/AttrDef/CSS.php

@@ -8,6 +8,11 @@ require_once 'HTMLPurifier/CSSDefinition.php';
  * @note We don't implement the whole CSS specification, so it might be
  *       difficult to reuse this component in the context of validating
  *       actual stylesheet declarations.
+ * @note If we were really serious about validating the CSS, we would
+ *       tokenize the styles and then parse the tokens. Obviously, we
+ *       are not doing that. Doing that could seriously harm performance,
+ *       but would make these components a lot more viable for a CSS
+ *       filtering solution.
  */
 class HTMLPurifier_AttrDef_CSS extends HTMLPurifier_AttrDef
 {
@@ -20,6 +25,9 @@ class HTMLPurifier_AttrDef_CSS extends HTMLPurifier_AttrDef
         
         // we're going to break the spec and explode by semicolons.
         // This is because semicolon rarely appears in escaped form
+        // Doing this is generally flaky but fast
+        // IT MIGHT APPEAR IN URIs, see HTMLPurifier_AttrDef_CSSURI
+        // for details
         
         $declarations = explode(';', $css);
         $propvalues = array();
@@ -28,6 +36,8 @@ class HTMLPurifier_AttrDef_CSS extends HTMLPurifier_AttrDef
             if (!$declaration) continue;
             if (!strpos($declaration, ':')) continue;
             list($property, $value) = explode(':', $declaration, 2);
+            $property = trim($property);
+            $value    = trim($value);
             if (!isset($definition->info[$property])) continue;
             // inefficient call, since the validator will do this again
             if (strtolower(trim($value)) !== 'inherit') {
@@ -41,6 +51,7 @@ class HTMLPurifier_AttrDef_CSS extends HTMLPurifier_AttrDef
             $propvalues[$property] = $result;
         }
         
+        // procedure does not write the new CSS simultaneously, so it's
         // slightly inefficient, but it's the only way of getting rid of
         // duplicates. Perhaps config to optimize it, but not now.
         

library/HTMLPurifier/AttrDef/CSSLength.php

@@ -40,6 +40,7 @@ class HTMLPurifier_AttrDef_CSSLength extends HTMLPurifier_AttrDef
         
         // we assume all units are two characters
         $unit = substr($length, $strlen - 2);
+        if (!ctype_lower($unit)) $unit = strtolower($unit);
         $number = substr($length, 0, $strlen - 2);
         
         if (!isset($this->units[$unit])) return false;

library/HTMLPurifier/AttrDef/CSSURI.php

@@ -0,0 +1,58 @@
+<?php
+
+require_once 'HTMLPurifier/AttrDef/URI.php';
+
+/**
+ * Validates a URI in CSS syntax, which uses url('http://example.com')
+ * @note While theoretically speaking we a URI in a CSS document could
+ *       be non-embedded, as of CSS2 there is no such usage so we're
+ *       generalizing it. This may need to be changed in the future.
+ * @warning Since HTMLPurifier_AttrDef_CSS blindly uses semicolons as
+ *          the separator, you cannot put a literal semicolon in
+ *          in the URI. Try percent encoding it, in that case.
+ */
+class HTMLPurifier_AttrDef_CSSURI extends HTMLPurifier_AttrDef_URI
+{
+    
+    function HTMLPurifier_AttrDef_CSSURI() {
+        $this->HTMLPurifier_AttrDef_URI(true); // always embedded
+    }
+    
+    function validate($uri_string, $config, &$context) {
+        // parse the URI out of the string and then pass it onto
+        // the parent object
+        
+        $uri_string = $this->parseCDATA($uri_string);
+        if (strpos($uri_string, 'url(') !== 0) return false;
+        $uri_string = substr($uri_string, 4);
+        $new_length = strlen($uri_string) - 1;
+        if ($uri_string[$new_length] != ')') return false;
+        $uri = trim(substr($uri_string, 0, $new_length));
+        
+        if (isset($uri[0]) && ($uri[0] == "'" || $uri[0] == '"')) {
+            $quote = $uri[0];
+            $new_length = strlen($uri) - 1;
+            if ($uri[$new_length] !== $quote) return false;
+            $uri = substr($uri, 1, $new_length - 1);
+        }
+        
+        $keys   = array(  '(',   ')',   ',',   ' ',   '"',   "'");
+        $values = array('\\(', '\\)', '\\,', '\\ ', '\\"', "\\'");
+        $uri = str_replace($values, $keys, $uri);
+        
+        $result = parent::validate($uri, $config, $context);
+        
+        if ($result === false) return false;
+        
+        // escape necessary characters according to CSS spec
+        // except for the comma, none of these should appear in the
+        // URI at all
+        $result = str_replace($keys, $values, $result);
+        
+        return "url($result)";
+        
+    }
+    
+}
+
+?>

library/HTMLPurifier/AttrDef/Class.php

@@ -24,13 +24,14 @@ class HTMLPurifier_AttrDef_Class extends HTMLPurifier_AttrDef
         // and plus it would complicate optimization efforts (you never
         // see that anyway).
         $matches = array();
-        $pattern = '/(?:(?<=\s)|\A)'.
+        $pattern = '/(?:(?<=\s)|\A)'. // look behind for space or string start
                    '((?:--|-?[A-Za-z_])[A-Za-z_\-0-9]*)'.
-                   '(?:(?=\s)|\z)/';
+                   '(?:(?=\s)|\z)/'; // look ahead for space or string end
         preg_match_all($pattern, $string, $matches);
         
         if (empty($matches[1])) return false;
         
+        // reconstruct class string
         $new_string = '';
         foreach ($matches[1] as $class_names) {
             $new_string .= $class_names . ' ';

library/HTMLPurifier/AttrDef/Email.php

@@ -0,0 +1,17 @@
+<?php
+
+require_once 'HTMLPurifier/AttrDef.php';
+
+class HTMLPurifier_AttrDef_Email extends HTMLPurifier_AttrDef
+{
+    
+    /**
+     * Unpacks a mailbox into its display-name and address
+     */
+    function unpack($string) {
+        // needs to be implemented
+    }
+    
+}
+
+?>

library/HTMLPurifier/AttrDef/Email/SimpleCheck.php

@@ -0,0 +1,23 @@
+<?php
+
+require_once 'HTMLPurifier/AttrDef/Email.php';
+
+/**
+ * Primitive email validation class based on the regexp found at 
+ * http://www.regular-expressions.info/email.html
+ */
+class HTMLPurifier_AttrDef_Email_SimpleCheck extends HTMLPurifier_AttrDef_Email
+{
+    
+    function validate($string, $config, &$context) {
+        // no support for named mailboxes i.e. "Bob <bob@example.com>"
+        // that needs more percent encoding to be done
+        if ($string == '') return false;
+        $string = trim($string);
+        $result = preg_match('/^[A-Z0-9._%-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i', $string);
+        return $result ? $string : false;
+    }
+    
+}
+
+?>

library/HTMLPurifier/AttrDef/Host.php

@@ -5,15 +5,20 @@ require_once 'HTMLPurifier/AttrDef/IPv4.php';
 require_once 'HTMLPurifier/AttrDef/IPv6.php';
 
 /**
- * Validates a host according to the IPv4, IPv6 and DNS specifications.
+ * Validates a host according to the IPv4, IPv6 and DNS (future) specifications.
  */
 class HTMLPurifier_AttrDef_Host extends HTMLPurifier_AttrDef
 {
     
     /**
-     * Instances of HTMLPurifier_AttrDef_IPv4 and HTMLPurifier_AttrDef_IPv6
+     * Instance of HTMLPurifier_AttrDef_IPv4 sub-validator
      */
-    var $ipv4, $ipv6;
+    var $ipv4;
+    
+    /**
+     * Instance of HTMLPurifier_AttrDef_IPv6 sub-validator
+     */
+    var $ipv6;
     
     function HTMLPurifier_AttrDef_Host() {
         $this->ipv4 = new HTMLPurifier_AttrDef_IPv4();
@@ -30,6 +35,8 @@ class HTMLPurifier_AttrDef_Host extends HTMLPurifier_AttrDef
             if ($valid === false) return false;
             return '['. $valid . ']';
         }
+        
+        // need to do checks on unusual encodings too
         $ipv4 = $this->ipv4->validate($string, $config, $context);
         if ($ipv4 !== false) return $ipv4;
         

library/HTMLPurifier/AttrDef/ID.php

@@ -3,6 +3,30 @@
 require_once 'HTMLPurifier/AttrDef.php';
 require_once 'HTMLPurifier/IDAccumulator.php';
 
+HTMLPurifier_ConfigSchema::define(
+    'Attr', 'IDPrefix', '', 'string',
+    'String to prefix to IDs.  If you have no idea what IDs your pages '.
+    'may use, you may opt to simply add a prefix to all user-submitted ID '.
+    'attributes so that they are still usable, but will not conflict with '.
+    'core page IDs. Example: setting the directive to \'user_\' will result in '.
+    'a user submitted \'foo\' to become \'user_foo\'  Be sure to set '.
+    '%HTML.EnableAttrID to true before using '.
+    'this.  This directive was available since 1.2.0.'
+);
+
+HTMLPurifier_ConfigSchema::define(
+    'Attr', 'IDPrefixLocal', '', 'string',
+    'Temporary prefix for IDs used in conjunction with %Attr.IDPrefix.  If '.
+    'you need to allow multiple sets of '.
+    'user content on web page, you may need to have a seperate prefix that '.
+    'changes with each iteration.  This way, seperately submitted user content '.
+    'displayed on the same page doesn\'t clobber each other. Ideal values '.
+    'are unique identifiers for the content it represents (i.e. the id of '.
+    'the row in the database). Be sure to add a seperator (like an underscore) '.
+    'at the end.  Warning: this directive will not work unless %Attr.IDPrefix '.
+    'is set to a non-empty value! This directive was available since 1.2.0.'
+);
+
 /**
  * Validates the HTML attribute ID.
  * @warning Even though this is the id processor, it
@@ -20,7 +44,19 @@ class HTMLPurifier_AttrDef_ID extends HTMLPurifier_AttrDef
         $id = trim($id); // trim it first
         
         if ($id === '') return false;
-        if (isset($context->id_accumulator->ids[$id])) return false;
+        
+        $prefix = $config->get('Attr', 'IDPrefix');
+        if ($prefix !== '') {
+            $prefix .= $config->get('Attr', 'IDPrefixLocal');
+            // prevent re-appending the prefix
+            if (strpos($id, $prefix) !== 0) $id = $prefix . $id;
+        } elseif ($config->get('Attr', 'IDPrefixLocal') !== '') {
+            trigger_error('%Attr.IDPrefixLocal cannot be used unless '.
+                '%Attr.IDPrefix is set', E_USER_WARNING);
+        }
+        
+        $id_accumulator =& $context->get('IDAccumulator');
+        if (isset($id_accumulator->ids[$id])) return false;
         
         // we purposely avoid using regex, hopefully this is faster
         
@@ -35,7 +71,7 @@ class HTMLPurifier_AttrDef_ID extends HTMLPurifier_AttrDef
             $result = ($trim === '');
         }
         
-        if ($result) $context->id_accumulator->add($id);
+        if ($result) $id_accumulator->add($id);
         
         // if no change was made to the ID, return the result
         // else, return the new id if stripping whitespace made it

library/HTMLPurifier/AttrDef/Lang.php

@@ -49,7 +49,7 @@ class HTMLPurifier_AttrDef_Lang extends HTMLPurifier_AttrDef
         if ($length == 0 || $length == 1 || $length > 8 || !ctype_alnum($subtags[1])) {
             return $new_string;
         }
-        if (!ctype_lower($subtags[1])) $subtags[1] = strotolower($subtags[1]);
+        if (!ctype_lower($subtags[1])) $subtags[1] = strtolower($subtags[1]);
         
         $new_string .= '-' . $subtags[1];
         if ($num_subtags == 2) return $new_string;
@@ -61,7 +61,7 @@ class HTMLPurifier_AttrDef_Lang extends HTMLPurifier_AttrDef
                 return $new_string;
             }
             if (!ctype_lower($subtags[$i])) {
-                $subtags[$i] = strotolower($subtags[$i]);
+                $subtags[$i] = strtolower($subtags[$i]);
             }
             $new_string .= '-' . $subtags[$i];
         }

library/HTMLPurifier/AttrDef/ListStyle.php

@@ -4,8 +4,7 @@ require_once 'HTMLPurifier/AttrDef.php';
 
 /**
  * Validates shorthand CSS property list-style.
- * @note This currently does not support list-style-image, as that functionality
- *       is not implemented yet elsewhere.
+ * @warning Does not support url tokens that have internal spaces.
  */
 class HTMLPurifier_AttrDef_ListStyle extends HTMLPurifier_AttrDef
 {
@@ -20,6 +19,7 @@ class HTMLPurifier_AttrDef_ListStyle extends HTMLPurifier_AttrDef
         $def = $config->getCSSDefinition();
         $this->info['list-style-type']     = $def->info['list-style-type'];
         $this->info['list-style-position'] = $def->info['list-style-position'];
+        $this->info['list-style-image'] = $def->info['list-style-image'];
     }
     
     function validate($string, $config, &$context) {
@@ -28,48 +28,50 @@ class HTMLPurifier_AttrDef_ListStyle extends HTMLPurifier_AttrDef
         $string = $this->parseCDATA($string);
         if ($string === '') return false;
         
+        // assumes URI doesn't have spaces in it
         $bits = explode(' ', strtolower($string)); // bits to process
         
-        $caught_type = false;
-        $caught_position = false;
-        $caught_none = false; // as in keyword none, which is in all of them
+        $caught = array();
+        $caught['type']     = false;
+        $caught['position'] = false;
+        $caught['image']    = false;
         
-        $ret = '';
+        $i = 0; // number of catches
+        $none = false;
         
         foreach ($bits as $bit) {
-            if ($caught_none && ($caught_type || $caught_position)) break;
-            if ($caught_type && $caught_position) break;
-            
+            if ($i >= 3) return; // optimization bit
             if ($bit === '') continue;
-            
-            if ($bit === 'none') {
-                if ($caught_none) continue;
-                $caught_none = true;
-                $ret .= 'none ';
-                continue;
-            }
-            
-            // if we add anymore, roll it into a loop
-            
-            $r = $this->info['list-style-type']->validate($bit, $config, $context);
-            if ($r !== false) {
-                if ($caught_type) continue;
-                $caught_type = true;
-                $ret .= $r . ' ';
-                continue;
-            }
-            
-            $r = $this->info['list-style-position']->validate($bit, $config, $context);
-            if ($r !== false) {
-                if ($caught_position) continue;
-                $caught_position = true;
-                $ret .= $r . ' ';
-                continue;
+            foreach ($caught as $key => $status) {
+                if ($status !== false) continue;
+                $r = $this->info['list-style-' . $key]->validate($bit, $config, $context);
+                if ($r === false) continue;
+                if ($r === 'none') {
+                    if ($none) continue;
+                    else $none = true;
+                    if ($key == 'image') continue;
+                }
+                $caught[$key] = $r;
+                $i++;
+                break;
             }
         }
         
-        $ret = rtrim($ret);
-        return $ret ? $ret : false;
+        if (!$i) return false;
+        
+        $ret = array();
+        
+        // construct type
+        if ($caught['type']) $ret[] = $caught['type'];
+        
+        // construct image
+        if ($caught['image']) $ret[] = $caught['image'];
+        
+        // construct position
+        if ($caught['position']) $ret[] = $caught['position'];
+        
+        if (empty($ret)) return false;
+        return implode(' ', $ret);
         
     }
     

library/HTMLPurifier/AttrDef/Percentage.php

@@ -4,14 +4,13 @@ require_once 'HTMLPurifier/AttrDef.php';
 require_once 'HTMLPurifier/AttrDef/Number.php';
 
 /**
- * Validates a Percentage as defined by the HTML spec.
- * @note This also allows integer pixel values.
+ * Validates a Percentage as defined by the CSS spec.
  */
 class HTMLPurifier_AttrDef_Percentage extends HTMLPurifier_AttrDef
 {
     
     /**
-     * Instance of HTMLPurifier_AttrDef_Number to defer pixel validation
+     * Instance of HTMLPurifier_AttrDef_Number to defer number validation
      */
     var $number_def;
     

library/HTMLPurifier/AttrDef/URI.php

@@ -4,13 +4,79 @@ require_once 'HTMLPurifier/AttrDef.php';
 require_once 'HTMLPurifier/URIScheme.php';
 require_once 'HTMLPurifier/URISchemeRegistry.php';
 require_once 'HTMLPurifier/AttrDef/Host.php';
+require_once 'HTMLPurifier/PercentEncoder.php';
 
-HTMLPurifier_ConfigDef::define(
+HTMLPurifier_ConfigSchema::define(
     'URI', 'DefaultScheme', 'http', 'string',
     'Defines through what scheme the output will be served, in order to '.
     'select the proper object validator when no scheme information is present.'
 );
 
+HTMLPurifier_ConfigSchema::define(
+    'URI', 'Host', null, 'string/null',
+    'Defines the domain name of the server, so we can determine whether or '.
+    'an absolute URI is from your website or not.  Not strictly necessary, '.
+    'as users should be using relative URIs to reference resources on your '.
+    'website.  It will, however, let you use absolute URIs to link to '.
+    'subdomains of the domain you post here: i.e. example.com will allow '.
+    'sub.example.com.  However, higher up domains will still be excluded: '.
+    'if you set %URI.Host to sub.example.com, example.com will be blocked. '.
+    'This directive has been available since 1.2.0.'
+);
+
+HTMLPurifier_ConfigSchema::define(
+    'URI', 'DisableExternal', false, 'bool',
+    'Disables links to external websites.  This is a highly effective '.
+    'anti-spam and anti-pagerank-leech measure, but comes at a hefty price: no'.
+    'links or images outside of your domain will be allowed.  Non-linkified '.
+    'URIs will still be preserved.  If you want to be able to link to '.
+    'subdomains or use absolute URIs, specify %URI.Host for your website. '.
+    'This directive has been available since 1.2.0.'
+);
+
+HTMLPurifier_ConfigSchema::define(
+    'URI', 'DisableExternalResources', false, 'bool',
+    'Disables the embedding of external resources, preventing users from '.
+    'embedding things like images from other hosts. This prevents '.
+    'access tracking (good for email viewers), bandwidth leeching, '.
+    'cross-site request forging, goatse.cx posting, and '.
+    'other nasties, but also results in '.
+    'a loss of end-user functionality (they can\'t directly post a pic '.
+    'they posted from Flickr anymore). Use it if you don\'t have a '.
+    'robust user-content moderation team. This directive has been '.
+    'available since 1.3.0.'
+);
+
+HTMLPurifier_ConfigSchema::define(
+    'URI', 'DisableResources', false, 'bool',
+    'Disables embedding resources, essentially meaning no pictures. You can '.
+    'still link to them though. See %URI.DisableExternalResources for why '.
+    'this might be a good idea. This directive has been available since 1.3.0.'
+);
+
+HTMLPurifier_ConfigSchema::define(
+    'URI', 'Munge', null, 'string/null',
+    'Munges all browsable (usually http, https and ftp) URI\'s into some URL '.
+    'redirection service. Pass this directive a URI, with %s inserted where '.
+    'the url-encoded original URI should be inserted (sample: '.
+    '<code>http://www.google.com/url?q=%s</code>). '.
+    'This prevents PageRank leaks, while being as transparent as possible '.
+    'to users (you may also want to add some client side JavaScript to '.
+    'override the text in the statusbar). Warning: many security experts '.
+    'believe that this form of protection does not deter spam-bots. '.
+    'You can also use this directive to redirect users to a splash page '.
+    'telling them they are leaving your website. '.
+    'This directive has been available since 1.3.0.'
+);
+
+HTMLPurifier_ConfigSchema::define(
+    'URI', 'HostBlacklist', array(), 'list',
+    'List of strings that are forbidden in the host of any URI. Use it to '.
+    'kill domain names of spam, etc. Note that it will catch anything in '.
+    'the domain, so <tt>moo.com</tt> will catch <tt>moo.com.example.com</tt>. '.
+    'This directive has been available since 1.3.0.'
+);
+
 /**
  * Validates a URI as defined by RFC 3986.
  * @note Scheme-specific mechanics deferred to HTMLPurifier_URIScheme
@@ -19,9 +85,16 @@ class HTMLPurifier_AttrDef_URI extends HTMLPurifier_AttrDef
 {
     
     var $host;
+    var $PercentEncoder;
+    var $embeds_resource;
     
-    function HTMLPurifier_AttrDef_URI() {
+    /**
+     * @param $embeds_resource_resource Does the URI here result in an extra HTTP request?
+     */
+    function HTMLPurifier_AttrDef_URI($embeds_resource = false) {
         $this->host = new HTMLPurifier_AttrDef_Host();
+        $this->PercentEncoder = new HTMLPurifier_PercentEncoder();
+        $this->embeds_resource = (bool) $embeds_resource;
     }
     
     function validate($uri, $config, &$context) {
@@ -32,17 +105,20 @@ class HTMLPurifier_AttrDef_URI extends HTMLPurifier_AttrDef
         // parse as CDATA
         $uri = $this->parseCDATA($uri);
         
+        // fix up percent-encoding
+        $uri = $this->PercentEncoder->normalize($uri);
+        
         // while it would be nice to use parse_url(), that's specifically
         // for HTTP and thus won't work for our generic URI parsing
         
         // according to the RFC... (but this cuts corners, i.e. non-validating)
-        $r_URI = '!^'.
-            '(([^:/?#<>]+):)?'. // 2. Scheme
-            '(//([^/?#<>]*))?'. // 4. Authority
-            '([^?#<>]*)'.       // 5. Path
-            '(\?([^#<>]*))?'.   // 7. Query
-            '(#([^<>]*))?'.     // 8. Fragment
-            '$!';
+        $r_URI = '!'.
+            '(([^:/?#<>\'"]+):)?'. // 2. Scheme
+            '(//([^/?#<>\'"]*))?'. // 4. Authority
+            '([^?#<>\'"]*)'.       // 5. Path
+            '(\?([^#<>\'"]*))?'.   // 7. Query
+            '(#([^<>\'"]*))?'.     // 8. Fragment
+            '!';
         
         $matches = array();
         $result = preg_match($r_URI, $uri, $matches);
@@ -63,18 +139,38 @@ class HTMLPurifier_AttrDef_URI extends HTMLPurifier_AttrDef
             // no need to validate the scheme's fmt since we do that when we
             // retrieve the specific scheme object from the registry
             $scheme = ctype_lower($scheme) ? $scheme : strtolower($scheme);
-            $scheme_obj =& $registry->getScheme($scheme, $config);
+            $scheme_obj = $registry->getScheme($scheme, $config, $context);
             if (!$scheme_obj) return false; // invalid scheme, clean it out
         } else {
-            $scheme_obj =& $registry->getScheme(
-                $config->get('URI', 'DefaultScheme'), $config
+            $scheme_obj = $registry->getScheme(
+                $config->get('URI', 'DefaultScheme'), $config, $context
             );
         }
         
         
+        // the URI we're processing embeds_resource a resource in the page, but the URI
+        // it references cannot be located
+        if ($this->embeds_resource && !$scheme_obj->browsable) {
+            return false;
+        }
+        
         
         if ($authority !== null) {
             
+            // remove URI if it's absolute and we disabled externals or
+            // if it's absolute and embedded and we disabled external resources
+            unset($our_host);
+            if (
+                $config->get('URI', 'DisableExternal') ||
+                (
+                    $config->get('URI', 'DisableExternalResources') &&
+                    $this->embeds_resource
+                )
+            ) {
+                $our_host = $config->get('URI', 'Host');
+                if ($our_host === null) return false;
+            }
+            
             $HEXDIG = '[A-Fa-f0-9]';
             $unreserved = 'A-Za-z0-9-._~'; // make sure you wrap with []
             $sub_delims = '!$&\'()'; // needs []
@@ -97,6 +193,19 @@ class HTMLPurifier_AttrDef_URI extends HTMLPurifier_AttrDef
             $host = $this->host->validate($host, $config, $context);
             if ($host === false) $host = null;
             
+            if ($this->checkBlacklist($host, $config, $context)) return false;
+            
+            // more lenient absolute checking
+            if (isset($our_host)) {
+                $host_parts = array_reverse(explode('.', $host));
+                // could be cached
+                $our_host_parts = array_reverse(explode('.', $our_host));
+                foreach ($our_host_parts as $i => $discard) {
+                    if (!isset($host_parts[$i])) return false;
+                    if ($host_parts[$i] != $our_host_parts[$i]) return false;
+                }
+            }
+            
             // userinfo and host are validated within the regexp
             
         } else {
@@ -120,7 +229,7 @@ class HTMLPurifier_AttrDef_URI extends HTMLPurifier_AttrDef
         // note that $fragment is omitted
         list($userinfo, $host, $port, $path, $query) = 
             $scheme_obj->validateComponents(
-                $userinfo, $host, $port, $path, $query, $config
+                $userinfo, $host, $port, $path, $query, $config, $context
             );
         
         
@@ -141,10 +250,37 @@ class HTMLPurifier_AttrDef_URI extends HTMLPurifier_AttrDef
         if ($query !== null) $result .= "?$query";
         if ($fragment !== null) $result .= "#$fragment";
         
+        // munge if necessary
+        $munge = $config->get('URI', 'Munge');
+        if (!empty($scheme_obj->browsable) && $munge !== null) {
+            if ($authority !== null) {
+                $result = str_replace('%s', rawurlencode($result), $munge);
+            }
+        }
+        
         return $result;
         
     }
     
+    /**
+     * Checks a host against an array blacklist
+     * @param $host Host to check
+     * @param $config HTMLPurifier_Config instance
+     * @param $context HTMLPurifier_Context instance
+     * @return bool Is spam?
+     */
+    function checkBlacklist($host, &$config, &$context) {
+        $blacklist = $config->get('URI', 'HostBlacklist');
+        if (!empty($blacklist)) {
+            foreach($blacklist as $blacklisted_host_fragment) {
+                if (strpos($host, $blacklisted_host_fragment) !== false) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    
 }
 
 ?>

library/HTMLPurifier/AttrTransform.php

@@ -21,11 +21,12 @@ class HTMLPurifier_AttrTransform
      * Abstract: makes changes to the attributes dependent on multiple values.
      * 
      * @param $attr Assoc array of attributes, usually from
-     *              HTMLPurifier_Token_Tag::$attributes
+     *              HTMLPurifier_Token_Tag::$attr
      * @param $config Mandatory HTMLPurifier_Config object.
+     * @param $context Mandatory HTMLPurifier_Context object
      * @returns Processed attribute array.
      */
-    function transform($attr, $config) {
+    function transform($attr, $config, &$context) {
         trigger_error('Cannot call abstract function', E_USER_ERROR);
     }
 }

library/HTMLPurifier/AttrTransform/BdoDir.php

@@ -4,13 +4,13 @@ require_once 'HTMLPurifier/AttrTransform.php';
 
 // this MUST be placed in post, as it assumes that any value in dir is valid
 
-HTMLPurifier_ConfigDef::define(
+HTMLPurifier_ConfigSchema::define(
     'Attr', 'DefaultTextDir', 'ltr', 'string',
     'Defines the default text direction (ltr or rtl) of the document '.
     'being parsed.  This generally is the same as the value of the dir '.
     'attribute in HTML, or ltr if that is not specified.'
 );
-HTMLPurifier_ConfigDef::defineAllowedValues(
+HTMLPurifier_ConfigSchema::defineAllowedValues(
     'Attr', 'DefaultTextDir', array( 'ltr', 'rtl' )
 );
 
@@ -20,7 +20,7 @@ HTMLPurifier_ConfigDef::defineAllowedValues(
 class HTMLPurifier_AttrTransform_BdoDir extends HTMLPurifier_AttrTransform
 {
     
-    function transform($attr, $config) {
+    function transform($attr, $config, &$context) {
         if (isset($attr['dir'])) return $attr;
         $attr['dir'] = $config->get('Attr', 'DefaultTextDir');
         return $attr;

library/HTMLPurifier/AttrTransform/ImgRequired.php

@@ -4,7 +4,7 @@ require_once 'HTMLPurifier/AttrTransform.php';
 
 // must be called POST validation
 
-HTMLPurifier_ConfigDef::define(
+HTMLPurifier_ConfigSchema::define(
     'Attr', 'DefaultInvalidImage', '', 'string',
     'This is the default image an img tag will be pointed to if it does '.
     'not have a valid src attribute.  In future versions, we may allow the '.
@@ -12,7 +12,7 @@ HTMLPurifier_ConfigDef::define(
     'not possible right now.'
 );
 
-HTMLPurifier_ConfigDef::define(
+HTMLPurifier_ConfigSchema::define(
     'Attr', 'DefaultInvalidImageAlt', 'Invalid image', 'string',
     'This is the content of the alt tag of an invalid image if the user '.
     'had not previously specified an alt attribute.  It has no effect when the '.
@@ -25,7 +25,7 @@ HTMLPurifier_ConfigDef::define(
 class HTMLPurifier_AttrTransform_ImgRequired extends HTMLPurifier_AttrTransform
 {
     
-    function transform($attr, $config) {
+    function transform($attr, $config, &$context) {
         
         $src = true;
         if (!isset($attr['src'])) {

library/HTMLPurifier/AttrTransform/Lang.php

@@ -10,7 +10,7 @@ require_once 'HTMLPurifier/AttrTransform.php';
 class HTMLPurifier_AttrTransform_Lang extends HTMLPurifier_AttrTransform
 {
     
-    function transform($attr, $config) {
+    function transform($attr, $config, &$context) {
         
         $lang     = isset($attr['lang']) ? $attr['lang'] : false;
         $xml_lang = isset($attr['xml:lang']) ? $attr['xml:lang'] : false;

library/HTMLPurifier/AttrTransform/TextAlign.php

@@ -8,7 +8,7 @@ require_once 'HTMLPurifier/AttrTransform.php';
 class HTMLPurifier_AttrTransform_TextAlign
     extends HTMLPurifier_AttrTransform {
 
-    function transform($attr, $config) {
+    function transform($attr, $config, &$context) {
         
         if (!isset($attr['align'])) return $attr;
         

library/HTMLPurifier/CSSDefinition.php

@@ -11,6 +11,9 @@ require_once 'HTMLPurifier/AttrDef/FontFamily.php';
 require_once 'HTMLPurifier/AttrDef/Font.php';
 require_once 'HTMLPurifier/AttrDef/Border.php';
 require_once 'HTMLPurifier/AttrDef/ListStyle.php';
+require_once 'HTMLPurifier/AttrDef/CSSURI.php';
+require_once 'HTMLPurifier/AttrDef/BackgroundPosition.php';
+require_once 'HTMLPurifier/AttrDef/Background.php';
 
 /**
  * Defines allowed CSS attributes and what their values are.
@@ -51,11 +54,19 @@ class HTMLPurifier_CSSDefinition
         $this->info['font-variant'] = new HTMLPurifier_AttrDef_Enum(
             array('normal', 'small-caps'), false);
         
+        $uri_or_none = new HTMLPurifier_AttrDef_Composite(
+            array(
+                new HTMLPurifier_AttrDef_Enum(array('none')),
+                new HTMLPurifier_AttrDef_CSSURI()
+            )
+        );
+        
         $this->info['list-style-position'] = new HTMLPurifier_AttrDef_Enum(
             array('inside', 'outside'), false);
         $this->info['list-style-type'] = new HTMLPurifier_AttrDef_Enum(
             array('disc', 'circle', 'square', 'decimal', 'lower-roman',
-            'upper-roman', 'lower-alpha', 'upper-alpha'), false);
+            'upper-roman', 'lower-alpha', 'upper-alpha', 'none'), false);
+        $this->info['list-style-image'] = $uri_or_none;
         
         $this->info['list-style'] = new HTMLPurifier_AttrDef_ListStyle($config);
         
@@ -63,14 +74,14 @@ class HTMLPurifier_CSSDefinition
             array('capitalize', 'uppercase', 'lowercase', 'none'), false);
         $this->info['color'] = new HTMLPurifier_AttrDef_Color();
         
-        // technically speaking, this one should get its own validator, but
-        // since we don't support background images, it effectively is
-        // equivalent to color.  The only trouble is that if the author
-        // specifies an image and a color, they'll both end up getting dropped,
-        // even though we ought to implement it and just discard the image
-        // info.  This will be fixed in a later version (see TODO) when
-        // better URI filtering is implemented.
-        $this->info['background'] = 
+        $this->info['background-image'] = $uri_or_none;
+        $this->info['background-repeat'] = new HTMLPurifier_AttrDef_Enum(
+            array('repeat', 'repeat-x', 'repeat-y', 'no-repeat')
+        );
+        $this->info['background-attachment'] = new HTMLPurifier_AttrDef_Enum(
+            array('scroll', 'fixed')
+        );
+        $this->info['background-position'] = new HTMLPurifier_AttrDef_BackgroundPosition();
         
         $border_color = 
         $this->info['border-top-color'] = 
@@ -82,6 +93,8 @@ class HTMLPurifier_CSSDefinition
             new HTMLPurifier_AttrDef_Color()
         ));
         
+        $this->info['background'] = new HTMLPurifier_AttrDef_Background($config);
+        
         $this->info['border-color'] = new HTMLPurifier_AttrDef_Multiple($border_color);
         
         $border_width = 

library/HTMLPurifier/ChildDef.php

@@ -5,14 +5,7 @@
 // false = delete parent node and all children
 // array(...) = replace children nodes with these
 
-// this is the hardest one to implement. We'll use fancy regexp tricks
-// right now, we only expect it to return TRUE or FALSE (it won't attempt
-// to fix the tree)
-
-// we may end up writing custom code for each HTML case
-// in order to make it self correcting
-
-HTMLPurifier_ConfigDef::define(
+HTMLPurifier_ConfigSchema::define(
     'Core', 'EscapeInvalidChildren', false, 'bool',
     'When true, a child is found that is not allowed in the context of the '.
     'parent element will be transformed into text as if it were ASCII. When '.
@@ -27,10 +20,9 @@ HTMLPurifier_ConfigDef::define(
 class HTMLPurifier_ChildDef
 {
     /**
-     * Type of child definition, usually right-most part of class name lowercase
-     * 
-     * Used occasionally in terms of context.  Possible values include
-     * custom, required, optional and empty.
+     * Type of child definition, usually right-most part of class name lowercase.
+     * Used occasionally in terms of context.
+     * @public
      */
     var $type;
     
@@ -39,272 +31,25 @@ class HTMLPurifier_ChildDef
      * 
      * This is necessary for redundant checking when changes affecting
      * a child node may cause a parent node to now be disallowed.
+     * 
+     * @public
      */
     var $allow_empty;
     
     /**
      * Validates nodes according to definition and returns modification.
      * 
-     * @warning $context is NOT HTMLPurifier_AttrContext
+     * @public
      * @param $tokens_of_children Array of HTMLPurifier_Token
      * @param $config HTMLPurifier_Config object
-     * @param $context String context indicating inline, block or unknown
+     * @param $context HTMLPurifier_Context object
      * @return bool true to leave nodes as is
      * @return bool false to remove parent node
      * @return array of replacement child tokens
      */
-    function validateChildren($tokens_of_children, $config, $context) {
+    function validateChildren($tokens_of_children, $config, &$context) {
         trigger_error('Call to abstract function', E_USER_ERROR);
     }
 }
 
-/**
- * Custom validation class, accepts DTD child definitions
- * 
- * @warning Currently this class is an all or nothing proposition, that is,
- *          it will only give a bool return value.  Table is the only
- *          child definition that uses this class, and we ought to give
- *          it a dedicated one.
- */
-class HTMLPurifier_ChildDef_Custom extends HTMLPurifier_ChildDef
-{
-    var $type = 'custom';
-    var $allow_empty = false;
-    /**
-     * Allowed child pattern as defined by the DTD
-     */
-    var $dtd_regex;
-    /**
-     * PCRE regex derived from $dtd_regex
-     * @private
-     */
-    var $_pcre_regex;
-    /**
-     * @param $dtd_regex Allowed child pattern from the DTD
-     */
-    function HTMLPurifier_ChildDef_Custom($dtd_regex) {
-        $this->dtd_regex = $dtd_regex;
-        $this->_compileRegex();
-    }
-    /**
-     * Compiles the PCRE regex from a DTD regex ($dtd_regex to $_pcre_regex)
-     */
-    function _compileRegex() {
-        $raw = str_replace(' ', '', $this->dtd_regex);
-        if ($raw{0} != '(') {
-            $raw = "($raw)";
-        }
-        $reg = str_replace(',', ',?', $raw);
-        $reg = preg_replace('/([#a-zA-Z0-9_.-]+)/', '(,?\\0)', $reg);
-        $this->_pcre_regex = $reg;
-    }
-    function validateChildren($tokens_of_children, $config, $context) {
-        $list_of_children = '';
-        $nesting = 0; // depth into the nest
-        foreach ($tokens_of_children as $token) {
-            if (!empty($token->is_whitespace)) continue;
-            
-            $is_child = ($nesting == 0); // direct
-            
-            if ($token->type == 'start') {
-                $nesting++;
-            } elseif ($token->type == 'end') {
-                $nesting--;
-            }
-            
-            if ($is_child) {
-                $list_of_children .= $token->name . ',';
-            }
-        }
-        $list_of_children = rtrim($list_of_children, ',');
-        
-        $okay =
-            preg_match(
-                '/^'.$this->_pcre_regex.'$/',
-                $list_of_children
-            );
-        
-        return (bool) $okay;
-    }
-}
-
-/**
- * Definition that allows a set of elements, but disallows empty children.
- */
-class HTMLPurifier_ChildDef_Required extends HTMLPurifier_ChildDef
-{
-    /**
-     * Lookup table of allowed elements.
-     */
-    var $elements = array();
-    /**
-     * @param $elements List of allowed element names (lowercase).
-     */
-    function HTMLPurifier_ChildDef_Required($elements) {
-        if (is_string($elements)) {
-            $elements = str_replace(' ', '', $elements);
-            $elements = explode('|', $elements);
-        }
-        $elements = array_flip($elements);
-        foreach ($elements as $i => $x) $elements[$i] = true;
-        $this->elements = $elements;
-        $this->gen = new HTMLPurifier_Generator();
-    }
-    var $allow_empty = false;
-    var $type = 'required';
-    function validateChildren($tokens_of_children, $config, $context) {
-        // if there are no tokens, delete parent node
-        if (empty($tokens_of_children)) return false;
-        
-        // the new set of children
-        $result = array();
-        
-        // current depth into the nest
-        $nesting = 0;
-        
-        // whether or not we're deleting a node
-        $is_deleting = false;
-        
-        // whether or not parsed character data is allowed
-        // this controls whether or not we silently drop a tag
-        // or generate escaped HTML from it
-        $pcdata_allowed = isset($this->elements['#PCDATA']);
-        
-        // a little sanity check to make sure it's not ALL whitespace
-        $all_whitespace = true;
-        
-        // some configuration
-        $escape_invalid_children = $config->get('Core', 'EscapeInvalidChildren');
-        
-        foreach ($tokens_of_children as $token) {
-            if (!empty($token->is_whitespace)) {
-                $result[] = $token;
-                continue;
-            }
-            $all_whitespace = false; // phew, we're not talking about whitespace
-            
-            $is_child = ($nesting == 0);
-            
-            if ($token->type == 'start') {
-                $nesting++;
-            } elseif ($token->type == 'end') {
-                $nesting--;
-            }
-            
-            if ($is_child) {
-                $is_deleting = false;
-                if (!isset($this->elements[$token->name])) {
-                    $is_deleting = true;
-                    if ($pcdata_allowed && $token->type == 'text') {
-                        $result[] = $token;
-                    } elseif ($pcdata_allowed && $escape_invalid_children) {
-                        $result[] = new HTMLPurifier_Token_Text(
-                            $this->gen->generateFromToken($token, $config)
-                        );
-                    }
-                    continue;
-                }
-            }
-            if (!$is_deleting || ($pcdata_allowed && $token->type == 'text')) {
-                $result[] = $token;
-            } elseif ($pcdata_allowed && $escape_invalid_children) {
-                $result[] =
-                    new HTMLPurifier_Token_Text(
-                        $this->gen->generateFromToken( $token, $config )
-                    );
-            } else {
-                // drop silently
-            }
-        }
-        if (empty($result)) return false;
-        if ($all_whitespace) return false;
-        if ($tokens_of_children == $result) return true;
-        return $result;
-    }
-}
-
-/**
- * Definition that allows a set of elements, and allows no children.
- * @note This is a hack to reuse code from HTMLPurifier_ChildDef_Required,
- *       really, one shouldn't inherit from the other.  Only altered behavior
- *       is to overload a returned false with an array.  Thus, it will never
- *       return false.
- */
-class HTMLPurifier_ChildDef_Optional extends HTMLPurifier_ChildDef_Required
-{
-    var $allow_empty = true;
-    var $type = 'optional';
-    function validateChildren($tokens_of_children, $config, $context) {
-        $result = parent::validateChildren($tokens_of_children, $config, $context);
-        if ($result === false) return array();
-        return $result;
-    }
-}
-
-/**
- * Definition that disallows all elements.
- * @warning validateChildren() in this class is actually never called, because
- *          empty elements are corrected in HTMLPurifier_Strategy_MakeWellFormed
- *          before child definitions are parsed in earnest by
- *          HTMLPurifier_Strategy_FixNesting.
- */
-class HTMLPurifier_ChildDef_Empty extends HTMLPurifier_ChildDef
-{
-    var $allow_empty = true;
-    var $type = 'empty';
-    function HTMLPurifier_ChildDef_Empty() {}
-    function validateChildren($tokens_of_children, $config, $context) {
-        return array();
-    }
-}
-
-/**
- * Definition that uses different definitions depending on context.
- * 
- * The del and ins tags are notable because they allow different types of
- * elements depending on whether or not they're in a block or inline context.
- * Chameleon allows this behavior to happen by using two different
- * definitions depending on context.  While this somewhat generalized,
- * it is specifically intended for those two tags.
- */
-class HTMLPurifier_ChildDef_Chameleon extends HTMLPurifier_ChildDef
-{
-    
-    /**
-     * Instance of the definition object to use when inline. Usually stricter.
-     */
-    var $inline;
-    /**
-     * Instance of the definition object to use when block.
-     */
-    var $block;
-    
-    /**
-     * @param $inline List of elements to allow when inline.
-     * @param $block List of elements to allow when block.
-     */
-    function HTMLPurifier_ChildDef_Chameleon($inline, $block) {
-        $this->inline = new HTMLPurifier_ChildDef_Optional($inline);
-        $this->block  = new HTMLPurifier_ChildDef_Optional($block);
-    }
-    
-    function validateChildren($tokens_of_children, $config, $context) {
-        switch ($context) {
-            case 'unknown':
-            case 'inline':
-                $result = $this->inline->validateChildren(
-                    $tokens_of_children, $config, $context);
-                break;
-            case 'block':
-                $result = $this->block->validateChildren(
-                    $tokens_of_children, $config, $context);
-                break;
-            default:
-                trigger_error('Invalid context', E_USER_ERROR);
-                return false;
-        }
-        return $result;
-    }
-}
-
-?>
+?>

library/HTMLPurifier/ChildDef/Chameleon.php

@@ -0,0 +1,60 @@
+<?php
+
+require_once 'HTMLPurifier/ChildDef.php';
+
+/**
+ * Definition that uses different definitions depending on context.
+ * 
+ * The del and ins tags are notable because they allow different types of
+ * elements depending on whether or not they're in a block or inline context.
+ * Chameleon allows this behavior to happen by using two different
+ * definitions depending on context.  While this somewhat generalized,
+ * it is specifically intended for those two tags.
+ */
+class HTMLPurifier_ChildDef_Chameleon extends HTMLPurifier_ChildDef
+{
+    
+    /**
+     * Instance of the definition object to use when inline. Usually stricter.
+     * @public
+     */
+    var $inline;
+    
+    /**
+     * Instance of the definition object to use when block.
+     * @public
+     */
+    var $block;
+    
+    var $type = 'chameleon';
+    
+    /**
+     * @param $inline List of elements to allow when inline.
+     * @param $block List of elements to allow when block.
+     */
+    function HTMLPurifier_ChildDef_Chameleon($inline, $block) {
+        $this->inline = new HTMLPurifier_ChildDef_Optional($inline);
+        $this->block  = new HTMLPurifier_ChildDef_Optional($block);
+    }
+    
+    function validateChildren($tokens_of_children, $config, &$context) {
+        $parent_type = $context->get('ParentType');
+        switch ($parent_type) {
+            case 'unknown':
+            case 'inline':
+                $result = $this->inline->validateChildren(
+                    $tokens_of_children, $config, $context);
+                break;
+            case 'block':
+                $result = $this->block->validateChildren(
+                    $tokens_of_children, $config, $context);
+                break;
+            default:
+                trigger_error('Invalid context', E_USER_ERROR);
+                return false;
+        }
+        return $result;
+    }
+}
+
+?>

library/HTMLPurifier/ChildDef/Custom.php

@@ -0,0 +1,75 @@
+<?php
+
+require_once 'HTMLPurifier/ChildDef.php';
+
+/**
+ * Custom validation class, accepts DTD child definitions
+ * 
+ * @warning Currently this class is an all or nothing proposition, that is,
+ *          it will only give a bool return value.
+ * @note This class is currently not used by any code, although it is unit
+ *       tested.
+ */
+class HTMLPurifier_ChildDef_Custom extends HTMLPurifier_ChildDef
+{
+    var $type = 'custom';
+    var $allow_empty = false;
+    /**
+     * Allowed child pattern as defined by the DTD
+     */
+    var $dtd_regex;
+    /**
+     * PCRE regex derived from $dtd_regex
+     * @private
+     */
+    var $_pcre_regex;
+    /**
+     * @param $dtd_regex Allowed child pattern from the DTD
+     */
+    function HTMLPurifier_ChildDef_Custom($dtd_regex) {
+        $this->dtd_regex = $dtd_regex;
+        $this->_compileRegex();
+    }
+    /**
+     * Compiles the PCRE regex from a DTD regex ($dtd_regex to $_pcre_regex)
+     */
+    function _compileRegex() {
+        $raw = str_replace(' ', '', $this->dtd_regex);
+        if ($raw{0} != '(') {
+            $raw = "($raw)";
+        }
+        $reg = str_replace(',', ',?', $raw);
+        $reg = preg_replace('/([#a-zA-Z0-9_.-]+)/', '(,?\\0)', $reg);
+        $this->_pcre_regex = $reg;
+    }
+    function validateChildren($tokens_of_children, $config, &$context) {
+        $list_of_children = '';
+        $nesting = 0; // depth into the nest
+        foreach ($tokens_of_children as $token) {
+            if (!empty($token->is_whitespace)) continue;
+            
+            $is_child = ($nesting == 0); // direct
+            
+            if ($token->type == 'start') {
+                $nesting++;
+            } elseif ($token->type == 'end') {
+                $nesting--;
+            }
+            
+            if ($is_child) {
+                $list_of_children .= $token->name . ',';
+            }
+        }
+        $list_of_children = rtrim($list_of_children, ',');
+        
+        $okay =
+            preg_match(
+                '/^'.$this->_pcre_regex.'$/',
+                $list_of_children
+            );
+        
+        return (bool) $okay;
+    }
+}
+
+?>

library/HTMLPurifier/ChildDef/Empty.php

@@ -0,0 +1,22 @@
+<?php
+
+require_once 'HTMLPurifier/ChildDef.php';
+
+/**
+ * Definition that disallows all elements.
+ * @warning validateChildren() in this class is actually never called, because
+ *          empty elements are corrected in HTMLPurifier_Strategy_MakeWellFormed
+ *          before child definitions are parsed in earnest by
+ *          HTMLPurifier_Strategy_FixNesting.
+ */
+class HTMLPurifier_ChildDef_Empty extends HTMLPurifier_ChildDef
+{
+    var $allow_empty = true;
+    var $type = 'empty';
+    function HTMLPurifier_ChildDef_Empty() {}
+    function validateChildren($tokens_of_children, $config, &$context) {
+        return array();
+    }
+}
+
+?>

library/HTMLPurifier/ChildDef/Optional.php

@@ -0,0 +1,23 @@
+<?php
+
+require_once 'HTMLPurifier/ChildDef/Required.php';
+
+/**
+ * Definition that allows a set of elements, and allows no children.
+ * @note This is a hack to reuse code from HTMLPurifier_ChildDef_Required,
+ *       really, one shouldn't inherit from the other.  Only altered behavior
+ *       is to overload a returned false with an array.  Thus, it will never
+ *       return false.
+ */
+class HTMLPurifier_ChildDef_Optional extends HTMLPurifier_ChildDef_Required
+{
+    var $allow_empty = true;
+    var $type = 'optional';
+    function validateChildren($tokens_of_children, $config, &$context) {
+        $result = parent::validateChildren($tokens_of_children, $config, $context);
+        if ($result === false) return array();
+        return $result;
+    }
+}
+
+?>

library/HTMLPurifier/ChildDef/Required.php

@@ -0,0 +1,104 @@
+<?php
+
+require_once 'HTMLPurifier/ChildDef.php';
+
+/**
+ * Definition that allows a set of elements, but disallows empty children.
+ */
+class HTMLPurifier_ChildDef_Required extends HTMLPurifier_ChildDef
+{
+    /**
+     * Lookup table of allowed elements.
+     * @public
+     */
+    var $elements = array();
+    /**
+     * @param $elements List of allowed element names (lowercase).
+     */
+    function HTMLPurifier_ChildDef_Required($elements) {
+        if (is_string($elements)) {
+            $elements = str_replace(' ', '', $elements);
+            $elements = explode('|', $elements);
+        }
+        $elements = array_flip($elements);
+        foreach ($elements as $i => $x) {
+            $elements[$i] = true;
+            if (empty($i)) unset($elements[$i]);
+        }
+        $this->elements = $elements;
+        $this->gen = new HTMLPurifier_Generator();
+    }
+    var $allow_empty = false;
+    var $type = 'required';
+    function validateChildren($tokens_of_children, $config, &$context) {
+        // if there are no tokens, delete parent node
+        if (empty($tokens_of_children)) return false;
+        
+        // the new set of children
+        $result = array();
+        
+        // current depth into the nest
+        $nesting = 0;
+        
+        // whether or not we're deleting a node
+        $is_deleting = false;
+        
+        // whether or not parsed character data is allowed
+        // this controls whether or not we silently drop a tag
+        // or generate escaped HTML from it
+        $pcdata_allowed = isset($this->elements['#PCDATA']);
+        
+        // a little sanity check to make sure it's not ALL whitespace
+        $all_whitespace = true;
+        
+        // some configuration
+        $escape_invalid_children = $config->get('Core', 'EscapeInvalidChildren');
+        
+        foreach ($tokens_of_children as $token) {
+            if (!empty($token->is_whitespace)) {
+                $result[] = $token;
+                continue;
+            }
+            $all_whitespace = false; // phew, we're not talking about whitespace
+            
+            $is_child = ($nesting == 0);
+            
+            if ($token->type == 'start') {
+                $nesting++;
+            } elseif ($token->type == 'end') {
+                $nesting--;
+            }
+            
+            if ($is_child) {
+                $is_deleting = false;
+                if (!isset($this->elements[$token->name])) {
+                    $is_deleting = true;
+                    if ($pcdata_allowed && $token->type == 'text') {
+                        $result[] = $token;
+                    } elseif ($pcdata_allowed && $escape_invalid_children) {
+                        $result[] = new HTMLPurifier_Token_Text(
+                            $this->gen->generateFromToken($token, $config)
+                        );
+                    }
+                    continue;
+                }
+            }
+            if (!$is_deleting || ($pcdata_allowed && $token->type == 'text')) {
+                $result[] = $token;
+            } elseif ($pcdata_allowed && $escape_invalid_children) {
+                $result[] =
+                    new HTMLPurifier_Token_Text(
+                        $this->gen->generateFromToken( $token, $config )
+                    );
+            } else {
+                // drop silently
+            }
+        }
+        if (empty($result)) return false;
+        if ($all_whitespace) return false;
+        if ($tokens_of_children == $result) return true;
+        return $result;
+    }
+}
+
+?>

library/HTMLPurifier/ChildDef/StrictBlockquote.php

@@ -0,0 +1,70 @@
+<?php
+
+require_once 'HTMLPurifier/ChildDef/Required.php';
+
+/**
+ * Takes the contents of blockquote when in strict and reformats for validation.
+ * 
+ * From XHTML 1.0 Transitional to Strict, there is a notable change where 
+ */
+class   HTMLPurifier_ChildDef_StrictBlockquote
+extends HTMLPurifier_ChildDef_Required
+{
+    var $allow_empty = true;
+    var $type = 'strictblockquote';
+    var $init = false;
+    function HTMLPurifier_ChildDef_StrictBlockquote() {}
+    function validateChildren($tokens_of_children, $config, &$context) {
+        
+        $def = $config->getHTMLDefinition();
+        if (!$this->init) {
+            // allow all inline elements
+            $this->elements = $def->info_flow_elements;
+            $this->elements['#PCDATA'] = true;
+            $this->init = true;
+        }
+        
+        $result = parent::validateChildren($tokens_of_children, $config, $context);
+        if ($result === false) return array();
+        if ($result === true) $result = $tokens_of_children;
+        
+        $block_wrap_start = new HTMLPurifier_Token_Start($def->info_block_wrapper);
+        $block_wrap_end   = new HTMLPurifier_Token_End(  $def->info_block_wrapper);
+        $is_inline = false;
+        $depth = 0;
+        $ret = array();
+        
+        // assuming that there are no comment tokens
+        foreach ($result as $i => $token) {
+            $token = $result[$i];
+            // ifs are nested for readability
+            if (!$is_inline) {
+                if (!$depth) {
+                     if (($token->type == 'text') ||
+                         ($def->info[$token->name]->type == 'inline')) {
+                        $is_inline = true;
+                        $ret[] = $block_wrap_start;
+                     }
+                }
+            } else {
+                if (!$depth) {
+                    // starting tokens have been inline text / empty
+                    if ($token->type == 'start' || $token->type == 'empty') {
+                        if ($def->info[$token->name]->type == 'block') {
+                            // ended
+                            $ret[] = $block_wrap_end;
+                            $is_inline = false;
+                        }
+                    }
+                }
+            }
+            $ret[] = $token;
+            if ($token->type == 'start') $depth++;
+            if ($token->type == 'end')   $depth--;
+        }
+        if ($is_inline) $ret[] = $block_wrap_end;
+        return $ret;
+    }
+}
+
+?>

library/HTMLPurifier/ChildDef/Table.php

@@ -0,0 +1,142 @@
+<?php
+
+require_once 'HTMLPurifier/ChildDef.php';
+
+/**
+ * Definition for tables
+ */
+class HTMLPurifier_ChildDef_Table extends HTMLPurifier_ChildDef
+{
+    var $allow_empty = false;
+    var $type = 'table';
+    function HTMLPurifier_ChildDef_Table() {}
+    function validateChildren($tokens_of_children, $config, &$context) {
+        if (empty($tokens_of_children)) return false;
+        
+        // this ensures that the loop gets run one last time before closing
+        // up. It's a little bit of a hack, but it works! Just make sure you
+        // get rid of the token later.
+        $tokens_of_children[] = false;
+        
+        // only one of these elements is allowed in a table
+        $caption = false;
+        $thead   = false;
+        $tfoot   = false;
+        
+        // as many of these as you want
+        $cols    = array();
+        $content = array();
+        
+        $nesting = 0; // current depth so we can determine nodes
+        $is_collecting = false; // are we globbing together tokens to package
+                                // into one of the collectors?
+        $collection = array(); // collected nodes
+        $tag_index = 0; // the first node might be whitespace,
+                            // so this tells us where the start tag is
+        
+        foreach ($tokens_of_children as $token) {
+            $is_child = ($nesting == 0);
+            
+            if ($token === false) {
+                // terminating sequence started
+            } elseif ($token->type == 'start') {
+                $nesting++;
+            } elseif ($token->type == 'end') {
+                $nesting--;
+            }
+            
+            // handle node collection
+            if ($is_collecting) {
+                if ($is_child) {
+                    // okay, let's stash the tokens away
+                    // first token tells us the type of the collection
+                    switch ($collection[$tag_index]->name) {
+                        case 'tr':
+                        case 'tbody':
+                            $content[] = $collection;
+                            break;
+                        case 'caption':
+                            if ($caption !== false) break;
+                            $caption = $collection;
+                            break;
+                        case 'thead':
+                        case 'tfoot':
+                            // access the appropriate variable, $thead or $tfoot
+                            $var = $collection[$tag_index]->name;
+                            if ($$var === false) {
+                                $$var = $collection;
+                            } else {
+                                // transmutate the first and less entries into
+                                // tbody tags, and then put into content
+                                $collection[$tag_index]->name = 'tbody';
+                                $collection[count($collection)-1]->name = 'tbody';
+                                $content[] = $collection;
+                            }
+                            break;
+                         case 'colgroup':
+                            $cols[] = $collection;
+                            break;
+                    }
+                    $collection = array();
+                    $is_collecting = false;
+                    $tag_index = 0;
+                } else {
+                    // add the node to the collection
+                    $collection[] = $token;
+                }
+            }
+            
+            // terminate
+            if ($token === false) break;
+            
+            if ($is_child) {
+                // determine what we're dealing with
+                if ($token->name == 'col') {
+                    // the only empty tag in the possie, we can handle it
+                    // immediately
+                    $cols[] = array_merge($collection, array($token));
+                    $collection = array();
+                    $tag_index = 0;
+                    continue;
+                }
+                switch($token->name) {
+                    case 'caption':
+                    case 'colgroup':
+                    case 'thead':
+                    case 'tfoot':
+                    case 'tbody':
+                    case 'tr':
+                        $is_collecting = true;
+                        $collection[] = $token;
+                        continue;
+                    default:
+                        if ($token->type == 'text' && $token->is_whitespace) {
+                            $collection[] = $token;
+                            $tag_index++;
+                        }
+                        continue;
+                }
+            }
+        }
+        
+        if (empty($content)) return false;
+        
+        $ret = array();
+        if ($caption !== false) $ret = array_merge($ret, $caption);
+        if ($cols !== false)    foreach ($cols as $token_array) $ret = array_merge($ret, $token_array);
+        if ($thead !== false)   $ret = array_merge($ret, $thead);
+        if ($tfoot !== false)   $ret = array_merge($ret, $tfoot);
+        foreach ($content as $token_array) $ret = array_merge($ret, $token_array);
+        if (!empty($collection) && $is_collecting == false){
+            // grab the trailing space
+            $ret = array_merge($ret, $collection);
+        }
+        
+        array_pop($tokens_of_children); // remove phantom token
+        
+        return ($ret === $tokens_of_children) ? true : $ret;
+        
+    }
+}
+
+?>

library/HTMLPurifier/Config.php

@@ -21,22 +21,22 @@ class HTMLPurifier_Config
     var $conf;
     
     /**
-     * Reference HTMLPurifier_ConfigDef for value checking
+     * Reference HTMLPurifier_ConfigSchema for value checking
      */
     var $def;
     
     /**
-     * Instance of HTMLPurifier_HTMLDefinition
+     * Cached instance of HTMLPurifier_HTMLDefinition
      */
     var $html_definition;
     
     /**
-     * Instance of HTMLPurifier_CSSDefinition
+     * Cached instance of HTMLPurifier_CSSDefinition
      */
     var $css_definition;
     
     /**
-     * @param $definition HTMLPurifier_ConfigDef that defines what directives
+     * @param $definition HTMLPurifier_ConfigSchema that defines what directives
      *                    are allowed.
      */
     function HTMLPurifier_Config(&$definition) {
@@ -44,12 +44,30 @@ class HTMLPurifier_Config
         $this->def  = $definition; // keep a copy around for checking
     }
     
+    /**
+     * Convenience constructor that creates a config object based on a mixed var
+     * @static
+     * @param mixed $config Variable that defines the state of the config
+     *                      object. Can be: a HTMLPurifier_Config() object,
+     *                      an array of directives based on loadArray(),
+     *                      or a string filename of an ini file.
+     * @return Configured HTMLPurifier_Config object
+     */
+    static function create($config) {
+        if ($config instanceof HTMLPurifier_Config) return $config;
+        $ret = HTMLPurifier_Config::createDefault();
+        if (is_string($config)) $ret->loadIni($config);
+        elseif (is_array($config)) $ret->loadArray($config);
+        return $ret;
+    }
+    
     /**
      * Convenience constructor that creates a default configuration object.
+     * @static
      * @return Default HTMLPurifier_Config object.
      */
-    function createDefault() {
-        $definition =& HTMLPurifier_ConfigDef::instance();
+    static function createDefault() {
+        $definition =& HTMLPurifier_ConfigSchema::instance();
         $config = new HTMLPurifier_Config($definition);
         return $config;
     }
@@ -59,27 +77,60 @@ class HTMLPurifier_Config
      * @param $namespace String namespace
      * @param $key String key
      */
-    function get($namespace, $key) {
-        if (!isset($this->conf[$namespace][$key])) {
+    function get($namespace, $key, $from_alias = false) {
+        if (!isset($this->def->info[$namespace][$key])) {
             trigger_error('Cannot retrieve value of undefined directive',
                 E_USER_WARNING);
             return;
         }
+        if ($this->def->info[$namespace][$key]->class == 'alias') {
+            trigger_error('Cannot get value from aliased directive, use real name',
+                E_USER_ERROR);
+            return;
+        }
         return $this->conf[$namespace][$key];
     }
     
+    /**
+     * Retreives an array of directives to values from a given namespace
+     * @param $namespace String namespace
+     */
+    function getBatch($namespace) {
+        if (!isset($this->def->info[$namespace])) {
+            trigger_error('Cannot retrieve undefined namespace',
+                E_USER_WARNING);
+            return;
+        }
+        return $this->conf[$namespace];
+    }
+    
     /**
      * Sets a value to configuration.
      * @param $namespace String namespace
      * @param $key String key
      * @param $value Mixed value
      */
-    function set($namespace, $key, $value) {
-        if (!isset($this->conf[$namespace][$key])) {
+    function set($namespace, $key, $value, $from_alias = false) {
+        if (!isset($this->def->info[$namespace][$key])) {
             trigger_error('Cannot set undefined directive to value',
                 E_USER_WARNING);
             return;
         }
+        if ($this->def->info[$namespace][$key]->class == 'alias') {
+            if ($from_alias) {
+                trigger_error('Double-aliases not allowed, please fix '.
+                    'ConfigSchema bug');
+            }
+            $this->set($this->def->info[$namespace][$key]->namespace,
+                       $this->def->info[$namespace][$key]->name,
+                       $value, true);
+            return;
+        }
+        $value = $this->def->validate(
+                    $value,
+                    $this->def->info[$namespace][$key]->type,
+                    $this->def->info[$namespace][$key]->allow_null
+                 );
         if (is_string($value)) {
             // resolve value alias if defined
             if (isset($this->def->info[$namespace][$key]->aliases[$value])) {
@@ -93,9 +144,7 @@ class HTMLPurifier_Config
                 }
             }
         }
-        $value = $this->def->validate($value,
-                                      $this->def->info[$namespace][$key]->type);
-        if ($value === null) {
+        if ($this->def->isError($value)) {
             trigger_error('Value is of invalid type', E_USER_WARNING);
             return;
         }
@@ -124,6 +173,37 @@ class HTMLPurifier_Config
         return $this->css_definition;
     }
     
+    /**
+     * Loads configuration values from an array with the following structure:
+     * Namespace.Directive => Value
+     * @param $config_array Configuration associative array
+     */
+    function loadArray($config_array) {
+        foreach ($config_array as $key => $value) {
+            $key = str_replace('_', '.', $key);
+            if (strpos($key, '.') !== false) {
+                // condensed form
+                list($namespace, $directive) = explode('.', $key);
+                $this->set($namespace, $directive, $value);
+            } else {
+                $namespace = $key;
+                $namespace_values = $value;
+                foreach ($namespace_values as $directive => $value) {
+                    $this->set($namespace, $directive, $value);
+                }
+            }
+        }
+    }
+    
+    /**
+     * Loads configuration values from an ini file
+     * @param $filename Name of ini file
+     */
+    function loadIni($filename) {
+        $array = parse_ini_file($filename, true);
+        $this->loadArray($array);
+    }
+    
 }
 
-?>
+?>

library/HTMLPurifier/ConfigSchema.php

@@ -1,10 +1,26 @@
 <?php
 
+require_once 'HTMLPurifier/Error.php';
+
 /**
  * Configuration definition, defines directives and their defaults.
- * @todo Build documentation generation capabilities.
+ * @todo The ability to define things multiple times is confusing and should
+ *       be factored out to its own function named registerDependency() or 
+ *       addNote(), where only the namespace.name and an extra descriptions
+ *       documenting the nature of the dependency are needed.  Since it's
+ *       possible that the dependency is registered before the configuration
+ *       is defined, deferring it to some sort of cache until it actually
+ *       gets defined would be wise, keeping it opaque until it does get
+ *       defined. We could add a finalize() method which would cause it to
+ *       error out if we get a dangling dependency.  It's difficult, however,
+ *       to know whether or not it's a dependency, or a codependency, that is
+ *       neither of them fully depends on it. Where does the configuration go
+ *       then?  This could be partially resolved by allowing blanket definitions
+ *       and then splitting them up into finer-grained versions, however, there
+ *       might be implementation difficulties in ini files regarding order of
+ *       execution.
  */
-class HTMLPurifier_ConfigDef {
+class HTMLPurifier_ConfigSchema {
     
     /**
      * Defaults of the directives and namespaces.
@@ -26,15 +42,15 @@ class HTMLPurifier_ConfigDef {
      * Lookup table of allowed types.
      */
     var $types = array(
-        'string'    => true,
-        'istring'   => true,
-        'int'       => true,
-        'float'     => true,
-        'bool'      => true,
-        'lookup'    => true,
-        'list'      => true,
-        'hash'      => true,
-        'mixed'     => true
+        'string'    => 'String',
+        'istring'   => 'Case-insensitive string',
+        'int'       => 'Integer',
+        'float'     => 'Float',
+        'bool'      => 'Boolean',
+        'lookup'    => 'Lookup array',
+        'list'      => 'Array list',
+        'hash'      => 'Associative array',
+        'mixed'     => 'Mixed'
     );
     
     /**
@@ -46,17 +62,19 @@ class HTMLPurifier_ConfigDef {
         $this->defineNamespace('URI', 'Features regarding Uniform Resource Identifiers.');
         $this->defineNamespace('HTML', 'Configuration regarding allowed HTML.');
         $this->defineNamespace('CSS', 'Configuration regarding allowed CSS.');
+        $this->defineNamespace('Test', 'Developer testing configuration for our unit tests.');
     }
     
     /**
      * Retrieves an instance of the application-wide configuration definition.
+     * @static
      */
-    function &instance($prototype = null) {
+    static function &instance($prototype = null) {
         static $instance;
         if ($prototype !== null) {
             $instance = $prototype;
         } elseif ($instance === null || $prototype === true) {
-            $instance = new HTMLPurifier_ConfigDef();
+            $instance = new HTMLPurifier_ConfigSchema();
             $instance->initialize();
         }
         return $instance;
@@ -64,10 +82,8 @@ class HTMLPurifier_ConfigDef {
     
     /**
      * Defines a directive for configuration
+     * @static
      * @warning Will fail of directive's namespace is defined
-     * @todo Collect information on description and allow redefinition
-     *       so that multiple files can register a dependency on a
-     *       configuration directive.
      * @param $namespace Namespace the directive is in
      * @param $name Key of directive
      * @param $default Default value of directive
@@ -75,16 +91,26 @@ class HTMLPurifier_ConfigDef {
      *      HTMLPurifier_DirectiveDef::$type for allowed values
      * @param $description Description of directive for documentation
      */
-    function define(
+    static function define(
         $namespace, $name, $default, $type, 
         $description
     ) {
-        $def =& HTMLPurifier_ConfigDef::instance();
+        $def =& HTMLPurifier_ConfigSchema::instance();
         if (!isset($def->info[$namespace])) {
             trigger_error('Cannot define directive for undefined namespace',
                 E_USER_ERROR);
             return;
         }
+        if (!ctype_alnum($name)) {
+            trigger_error('Directive name must be alphanumeric',
+                E_USER_ERROR);
+            return;
+        }
+        if (empty($description)) {
+            trigger_error('Description must be non-empty',
+                E_USER_ERROR);
+            return;
+        }
         if (isset($def->info[$namespace][$name])) {
             if (
                 $def->info[$namespace][$name]->type !== $type ||
@@ -94,12 +120,19 @@ class HTMLPurifier_ConfigDef {
                 return;
             }
         } else {
+            // process modifiers
+            $type_values = explode('/', $type, 2);
+            $type = $type_values[0];
+            $modifier = isset($type_values[1]) ? $type_values[1] : false;
+            $allow_null = ($modifier === 'null');
+            
             if (!isset($def->types[$type])) {
                 trigger_error('Invalid type for configuration directive',
                     E_USER_ERROR);
                 return;
             }
-            if ($def->validate($default, $type) === null) {
+            $default = $def->validate($default, $type, $allow_null);
+            if ($def->isError($default)) {
                 trigger_error('Default value does not match directive type',
                     E_USER_ERROR);
                 return;
@@ -107,6 +140,7 @@ class HTMLPurifier_ConfigDef {
             $def->info[$namespace][$name] =
                 new HTMLPurifier_ConfigEntity_Directive();
             $def->info[$namespace][$name]->type = $type;
+            $def->info[$namespace][$name]->allow_null = $allow_null;
             $def->defaults[$namespace][$name]   = $default;
         }
         $backtrace = debug_backtrace();
@@ -117,21 +151,29 @@ class HTMLPurifier_ConfigDef {
     
     /**
      * Defines a namespace for directives to be put into.
+     * @static
      * @param $namespace Namespace's name
      * @param $description Description of the namespace
      */
-    function defineNamespace($namespace, $description) {
-        $def =& HTMLPurifier_ConfigDef::instance();
+    static function defineNamespace($namespace, $description) {
+        $def =& HTMLPurifier_ConfigSchema::instance();
         if (isset($def->info[$namespace])) {
             trigger_error('Cannot redefine namespace', E_USER_ERROR);
             return;
         }
+        if (!ctype_alnum($namespace)) {
+            trigger_error('Namespace name must be alphanumeric',
+                E_USER_ERROR);
+            return;
+        }
+        if (empty($description)) {
+            trigger_error('Description must be non-empty',
+                E_USER_ERROR);
+            return;
+        }
         $def->info[$namespace] = array();
         $def->info_namespace[$namespace] = new HTMLPurifier_ConfigEntity_Namespace();
-        $backtrace = debug_backtrace();
-        $file = $def->mungeFilename($backtrace[0]['file']);
-        $line = $backtrace[0]['line'];
-        $def->info_namespace[$namespace]->addDescription($file,$line,$description);
+        $def->info_namespace[$namespace]->description = $description;
         $def->defaults[$namespace] = array();
     }
     
@@ -140,13 +182,14 @@ class HTMLPurifier_ConfigDef {
      * 
      * Directive value aliases are convenient for developers because it lets
      * them set a directive to several values and get the same result.
+     * @static
      * @param $namespace Directive's namespace
      * @param $name Name of Directive
      * @param $alias Name of aliased value
      * @param $real Value aliased value will be converted into
      */
-    function defineValueAliases($namespace, $name, $aliases) {
-        $def =& HTMLPurifier_ConfigDef::instance();
+    static function defineValueAliases($namespace, $name, $aliases) {
+        $def =& HTMLPurifier_ConfigSchema::instance();
         if (!isset($def->info[$namespace][$name])) {
             trigger_error('Cannot set value alias for non-existant directive',
                 E_USER_ERROR);
@@ -171,58 +214,129 @@ class HTMLPurifier_ConfigDef {
     
     /**
      * Defines a set of allowed values for a directive.
+     * @static
      * @param $namespace Namespace of directive
      * @param $name Name of directive
      * @param $allowed_values Arraylist of allowed values
      */
-    function defineAllowedValues($namespace, $name, $allowed_values) {
-        $def =& HTMLPurifier_ConfigDef::instance();
+    static function defineAllowedValues($namespace, $name, $allowed_values) {
+        $def =& HTMLPurifier_ConfigSchema::instance();
         if (!isset($def->info[$namespace][$name])) {
             trigger_error('Cannot define allowed values for undefined directive',
                 E_USER_ERROR);
             return;
         }
-        if ($def->info[$namespace][$name]->allowed === true) {
-            $def->info[$namespace][$name]->allowed = array();
+        $directive =& $def->info[$namespace][$name];
+        $type = $directive->type;
+        if ($type != 'string' && $type != 'istring') {
+            trigger_error('Cannot define allowed values for directive whose type is not string',
+                E_USER_ERROR);
+            return;
+        }
+        if ($directive->allowed === true) {
+            $directive->allowed = array();
         }
         foreach ($allowed_values as $value) {
-            $def->info[$namespace][$name]->allowed[$value] = true;
+            $directive->allowed[$value] = true;
         }
+        if ($def->defaults[$namespace][$name] !== null &&
+            !isset($directive->allowed[$def->defaults[$namespace][$name]])) {
+            trigger_error('Default value must be in allowed range of variables',
+                E_USER_ERROR);
+            $directive->allowed = true; // undo undo!
+            return;
+        }
+    }
+    
+    /**
+     * Defines a directive alias for backwards compatibility
+     * @static
+     * @param $namespace
+     * @param $name Directive that will be aliased
+     * @param $new_namespace
+     * @param $new_name Directive that the alias will be to
+     */
+    static function defineAlias($namespace, $name, $new_namespace, $new_name) {
+        $def =& HTMLPurifier_ConfigSchema::instance();
+        if (!isset($def->info[$namespace])) {
+            trigger_error('Cannot define directive alias in undefined namespace',
+                E_USER_ERROR);
+            return;
+        }
+        if (!ctype_alnum($name)) {
+            trigger_error('Directive name must be alphanumeric',
+                E_USER_ERROR);
+            return;
+        }
+        if (isset($def->info[$namespace][$name])) {
+            trigger_error('Cannot define alias over directive',
+                E_USER_ERROR);
+            return;
+        }
+        if (!isset($def->info[$new_namespace][$new_name])) {
+            trigger_error('Cannot define alias to undefined directive',
+                E_USER_ERROR);
+            return;
+        }
+        if ($def->info[$new_namespace][$new_name]->class == 'alias') {
+            trigger_error('Cannot define alias to alias',
+                E_USER_ERROR);
+            return;
+        }
+        $def->info[$namespace][$name] =
+            new HTMLPurifier_ConfigEntity_DirectiveAlias(
+                $new_namespace, $new_name);
     }
     
     /**
      * Validate a variable according to type. Return null if invalid.
      */
-    function validate($var, $type) {
+    function validate($var, $type, $allow_null = false) {
         if (!isset($this->types[$type])) {
             trigger_error('Invalid type', E_USER_ERROR);
             return;
         }
+        if ($allow_null && $var === null) return null;
         switch ($type) {
             case 'mixed':
                 return $var;
             case 'istring':
             case 'string':
-                if (!is_string($var)) return;
+                if (!is_string($var)) break;
                 if ($type === 'istring') $var = strtolower($var);
                 return $var;
             case 'int':
                 if (is_string($var) && ctype_digit($var)) $var = (int) $var;
-                elseif (!is_int($var)) return;
+                elseif (!is_int($var)) break;
                 return $var;
             case 'float':
                 if (is_string($var) && is_numeric($var)) $var = (float) $var;
-                elseif (!is_float($var)) return;
+                elseif (!is_float($var)) break;
                 return $var;
             case 'bool':
                 if (is_int($var) && ($var === 0 || $var === 1)) {
                     $var = (bool) $var;
-                } elseif (!is_bool($var)) return;
+                } elseif (is_string($var)) {
+                    if ($var == 'on' || $var == 'true' || $var == '1') {
+                        $var = true;
+                    } elseif ($var == 'off' || $var == 'false' || $var == '0') {
+                        $var = false;
+                    } else {
+                        break;
+                    }
+                } elseif (!is_bool($var)) break;
                 return $var;
             case 'list':
             case 'hash':
             case 'lookup':
-                if (!is_array($var)) return;
+                if (is_string($var)) {
+                    // simplistic string to array method that only works
+                    // for simple lists of tag names or alphanumeric characters
+                    $var = explode(',',$var);
+                    // remove spaces
+                    foreach ($var as $i => $j) $var[$i] = trim($j);
+                }
+                if (!is_array($var)) break;
                 $keys = array_keys($var);
                 if ($keys === array_keys($keys)) {
                     if ($type == 'list') return $var;
@@ -232,7 +346,7 @@ class HTMLPurifier_ConfigDef {
                             $new[$key] = true;
                         }
                         return $new;
-                    } else return;
+                    } else break;
                 }
                 if ($type === 'lookup') {
                     foreach ($var as $key => $value) {
@@ -241,8 +355,13 @@ class HTMLPurifier_ConfigDef {
                 }
                 return $var;
         }
+        $error = new HTMLPurifier_Error();
+        return $error;
     }
     
+    /**
+     * Takes an absolute path and munges it into a more manageable relative path
+     */
     function mungeFilename($filename) {
         $offset = strrpos($filename, 'HTMLPurifier');
         $filename = substr($filename, $offset);
@@ -250,32 +369,40 @@ class HTMLPurifier_ConfigDef {
         return $filename;
     }
     
+    /**
+     * Checks if var is an HTMLPurifier_Error object
+     */
+    function isError($var) {
+        if (!is_object($var)) return false;
+        if (!($var instanceof HTMLPurifier_Error)) return false;
+        return true;
+    }
 }
 
 /**
  * Base class for configuration entity
  */
-class HTMLPurifier_ConfigEntity
-{
-    /**
-     * Plaintext descriptions of the configuration entity is. Organized by
-     * file and line number, so multiple descriptions are allowed.
-     */
-    var $descriptions = array();
-    
-    /**
-     * Adds a description to the array
-     */
-    function addDescription($file, $line, $description) {
-        if (!isset($this->descriptions[$file])) $this->descriptions[$file] = array();
-        $this->descriptions[$file][$line] = $description;
-    }
+class HTMLPurifier_ConfigEntity {
+    var $class = false;
 }
 
 /**
  * Structure object describing of a namespace
  */
-class HTMLPurifier_ConfigEntity_Namespace extends HTMLPurifier_ConfigEntity {}
+class HTMLPurifier_ConfigEntity_Namespace extends HTMLPurifier_ConfigEntity {
+    
+    function HTMLPurifier_ConfigEntity_Namespace($description = null) {
+        $this->description = $description;
+    }
+    
+    var $class = 'namespace';
+    
+    /**
+     * String description of what kinds of directives go in this namespace.
+     */
+    var $description;
+    
+}
 
 /**
  * Structure object containing definition of a directive.
@@ -284,15 +411,21 @@ class HTMLPurifier_ConfigEntity_Namespace extends HTMLPurifier_ConfigEntity {}
 class HTMLPurifier_ConfigEntity_Directive extends HTMLPurifier_ConfigEntity
 {
     
-    /**
-     * Hash of value aliases, i.e. values that are equivalent.
-     */
-    var $aliases = array();
+    var $class = 'directive';
     
-    /**
-     * Lookup table of allowed values of the element, bool true if all allowed.
-     */
-    var $allowed = true;
+    function HTMLPurifier_ConfigEntity_Directive(
+        $type = null,
+        $descriptions = null,
+        $allow_null = null,
+        $allowed = null,
+        $aliases = null
+    ) {
+        if (        $type !== null)         $this->type = $type;
+        if ($descriptions !== null) $this->descriptions = $descriptions;
+        if (  $allow_null !== null)   $this->allow_null = $allow_null;
+        if (     $allowed !== null)      $this->allowed = $allowed;
+        if (     $aliases !== null)      $this->aliases = $aliases;
+    }
     
     /**
      * Allowed type of the directive. Values are:
@@ -308,6 +441,58 @@ class HTMLPurifier_ConfigEntity_Directive extends HTMLPurifier_ConfigEntity
      */
     var $type = 'mixed';
     
+    /**
+     * Plaintext descriptions of the configuration entity is. Organized by
+     * file and line number, so multiple descriptions are allowed.
+     */
+    var $descriptions = array();
+    
+    /**
+     * Is null allowed? Has no effect for mixed type.
+     * @bool
+     */
+    var $allow_null = false;
+    
+    /**
+     * Lookup table of allowed values of the element, bool true if all allowed.
+     */
+    var $allowed = true;
+    
+    /**
+     * Hash of value aliases, i.e. values that are equivalent.
+     */
+    var $aliases = array();
+    
+    /**
+     * Adds a description to the array
+     */
+    function addDescription($file, $line, $description) {
+        if (!isset($this->descriptions[$file])) $this->descriptions[$file] = array();
+        $this->descriptions[$file][$line] = $description;
+    }
+    
 }
 
-?>
+/**
+ * Structure object describing a directive alias
+ */
+class HTMLPurifier_ConfigEntity_DirectiveAlias extends HTMLPurifier_ConfigEntity
+{
+    var $class = 'alias';
+    
+    /**
+     * Namespace being aliased to
+     */
+    var $namespace;
+    /**
+     * Directive being aliased to
+     */
+    var $name;
+    
+    function HTMLPurifier_ConfigEntity_DirectiveAlias($namespace, $name) {
+        $this->namespace = $namespace;
+        $this->name = $name;
+    }
+}
+
+?>

library/HTMLPurifier/Context.php

@@ -0,0 +1,76 @@
+<?php
+
+/**
+ * Registry object that contains information about the current context.
+ */
+class HTMLPurifier_Context
+{
+    
+    /**
+     * Private array that stores the references.
+     * @private
+     */
+    var $_storage = array();
+    
+    /**
+     * Registers a variable into the context.
+     * @param $name String name
+     * @param $ref Variable to be registered
+     */
+    function register($name, &$ref) {
+        if (isset($this->_storage[$name])) {
+            trigger_error('Name collision, cannot re-register',
+                          E_USER_ERROR);
+            return;
+        }
+        $this->_storage[$name] =& $ref;
+    }
+    
+    /**
+     * Retrieves a variable reference from the context.
+     * @param $name String name
+     */
+    function &get($name) {
+        if (!isset($this->_storage[$name])) {
+            trigger_error('Attempted to retrieve non-existent variable',
+                          E_USER_ERROR);
+            $var = null; // so we can return by reference
+            return $var;
+        }
+        return $this->_storage[$name];
+    }
+    
+    /**
+     * Destorys a variable in the context.
+     * @param $name String name
+     */
+    function destroy($name) {
+        if (!isset($this->_storage[$name])) {
+            trigger_error('Attempted to destroy non-existent variable',
+                          E_USER_ERROR);
+            return;
+        }
+        unset($this->_storage[$name]);
+    }
+    
+    /**
+     * Checks whether or not the variable exists.
+     * @param $name String name
+     */
+    function exists($name) {
+        return isset($this->_storage[$name]);
+    }
+    
+    /**
+     * Loads a series of variables from an associative array
+     * @param $context_array Assoc array of variables to load
+     */
+    function loadArray(&$context_array) {
+        foreach ($context_array as $key => $discard) {
+            $this->register($key, $context_array[$key]);
+        }
+    }
+    
+}
+
+?>

library/HTMLPurifier/Encoder.php

@@ -2,41 +2,75 @@
 
 require_once 'HTMLPurifier/EntityLookup.php';
 
-HTMLPurifier_ConfigDef::define(
+HTMLPurifier_ConfigSchema::define(
     'Core', 'Encoding', 'utf-8', 'istring', 
     'If for some reason you are unable to convert all webpages to UTF-8, '. 
     'you can use this directive as a stop-gap compatibility change to '. 
-    'let HTMLPurifier deal with non UTF-8 input.  This technique has '. 
+    'let HTML Purifier deal with non UTF-8 input.  This technique has '. 
     'notable deficiencies: absolutely no characters outside of the selected '. 
     'character encoding will be preserved, not even the ones that have '. 
     'been ampersand escaped (this is due to a UTF-8 specific <em>feature</em> '.
     'that automatically resolves all entities), making it pretty useless '.
-    'for anything except the most I18N-blind applications.  This directive '.
+    'for anything except the most I18N-blind applications, although '.
+    '%Core.EscapeNonASCIICharacters offers fixes this trouble with '.
+    'another tradeoff. This directive '.
     'only accepts ISO-8859-1 if iconv is not enabled.'
 );
 
+HTMLPurifier_ConfigSchema::define(
+    'Core', 'EscapeNonASCIICharacters', false, 'bool',
+    'This directive overcomes a deficiency in %Core.Encoding by blindly '.
+    'converting all non-ASCII characters into decimal numeric entities before '.
+    'converting it to its native encoding. This means that even '.
+    'characters that can be expressed in the non-UTF-8 encoding will '.
+    'be entity-ized, which can be a real downer for encodings like Big5. '.
+    'It also assumes that the ASCII repetoire is available, although '.
+    'this is the case for almost all encodings. Anyway, use UTF-8! This '.
+    'directive has been available since 1.4.0.'
+);
+
 if ( !function_exists('iconv') ) {
     // only encodings with native PHP support
-    HTMLPurifier_ConfigDef::defineAllowedValues(
+    HTMLPurifier_ConfigSchema::defineAllowedValues(
         'Core', 'Encoding', array(
             'utf-8',
             'iso-8859-1'
         )
     );
+    HTMLPurifier_ConfigSchema::defineValueAliases(
+        'Core', 'Encoding', array(
+            'iso8859-1' => 'iso-8859-1'
+        )
+    );
 }
 
+HTMLPurifier_ConfigSchema::define(
+    'Test', 'ForceNoIconv', false, 'bool', 
+    'When set to true, HTMLPurifier_Encoder will act as if iconv does not '.
+    'exist and use only pure PHP implementations.'
+);
+
 /**
  * A UTF-8 specific character encoder that handles cleaning and transforming.
+ * @note All functions in this class should be static.
  */
 class HTMLPurifier_Encoder
 {
     
+    /**
+     * Constructor throws fatal error if you attempt to instantiate class
+     */
+    function HTMLPurifier_Encoder() {
+        trigger_error('Cannot instantiate encoder, call methods statically', E_USER_ERROR);
+    }
+    
     /**
      * Cleans a UTF-8 string for well-formedness and SGML validity
      * 
      * It will parse according to UTF-8 and return a valid UTF8 string, with
      * non-SGML codepoints excluded.
      * 
+     * @static
      * @note Just for reference, the non-SGML code points are 0 to 31 and
      *       127 to 159, inclusive.  However, we allow code points 9, 10
      *       and 13, which are the tab, line feed and carriage return
@@ -56,7 +90,7 @@ class HTMLPurifier_Encoder
      *       would need that, and I'm probably not going to implement them.
      *       Once again, PHP 6 should solve all our problems.
      */
-    function cleanUTF8($str, $force_php = false) {
+    static function cleanUTF8($str, $force_php = false) {
         
         static $non_sgml_chars = array();
         if (empty($non_sgml_chars)) {
@@ -77,7 +111,7 @@ class HTMLPurifier_Encoder
         if ($iconv && !$force_php) {
             // do the shortcut way
             $str = @iconv('UTF-8', 'UTF-8//IGNORE', $str);
-            return strtr($str, $non_sgml_chars);;
+            return strtr($str, $non_sgml_chars);
         }
         
         $mState = 0; // cached expected number of octets after the current octet
@@ -214,8 +248,32 @@ class HTMLPurifier_Encoder
     
     /**
      * Translates a Unicode codepoint into its corresponding UTF-8 character.
+     * @static
+     * @note Based on Feyd's function at
+     *       <http://forums.devnetwork.net/viewtopic.php?p=191404#191404>,
+     *       which is in public domain.
+     * @note While we're going to do code point parsing anyway, a good
+     *       optimization would be to refuse to translate code points that
+     *       are non-SGML characters.  However, this could lead to duplication.
+     * @note This is very similar to the unichr function in
+     *       maintenance/generate-entity-file.php (although this is superior,
+     *       due to its sanity checks).
      */
-    function unichr($code) {
+    
+    // +----------+----------+----------+----------+
+    // | 33222222 | 22221111 | 111111   |          |
+    // | 10987654 | 32109876 | 54321098 | 76543210 | bit
+    // +----------+----------+----------+----------+
+    // |          |          |          | 0xxxxxxx | 1 byte 0x00000000..0x0000007F
+    // |          |          | 110yyyyy | 10xxxxxx | 2 byte 0x00000080..0x000007FF
+    // |          | 1110zzzz | 10yyyyyy | 10xxxxxx | 3 byte 0x00000800..0x0000FFFF
+    // | 11110www | 10wwzzzz | 10yyyyyy | 10xxxxxx | 4 byte 0x00010000..0x0010FFFF
+    // +----------+----------+----------+----------+
+    // | 00000000 | 00011111 | 11111111 | 11111111 | Theoretical upper limit of legal scalars: 2097151 (0x001FFFFF)
+    // | 00000000 | 00010000 | 11111111 | 11111111 | Defined upper limit of legal scalar codes
+    // +----------+----------+----------+----------+ 
+    
+    static function unichr($code) {
         if($code > 1114111 or $code < 0 or
           ($code >= 55296 and $code <= 57343) ) {
             // bits are set outside the "valid" range as defined
@@ -254,34 +312,89 @@ class HTMLPurifier_Encoder
     
     /**
      * Converts a string to UTF-8 based on configuration.
+     * @static
      */
-    function convertToUTF8($str, $config) {
+    static function convertToUTF8($str, $config, &$context) {
         static $iconv = null;
         if ($iconv === null) $iconv = function_exists('iconv');
         $encoding = $config->get('Core', 'Encoding');
         if ($encoding === 'utf-8') return $str;
-        if ($iconv) {
+        if ($iconv && !$config->get('Test', 'ForceNoIconv')) {
             return @iconv($encoding, 'utf-8//IGNORE', $str);
-        } elseif ($encoding === 'iso-8895-1') {
+        } elseif ($encoding === 'iso-8859-1') {
             return @utf8_encode($str);
         }
+        trigger_error('Encoding not supported', E_USER_ERROR);
     }
     
     /**
      * Converts a string from UTF-8 based on configuration.
+     * @static
      * @note Currently, this is a lossy conversion, with unexpressable
      *       characters being omitted.
      */
-    function convertFromUTF8($str, $config) {
+    static function convertFromUTF8($str, $config, &$context) {
         static $iconv = null;
         if ($iconv === null) $iconv = function_exists('iconv');
         $encoding = $config->get('Core', 'Encoding');
         if ($encoding === 'utf-8') return $str;
-        if ($iconv) {
-            return @iconv('utf-8', $encoding . '//IGNORE', $str);
-        } elseif ($encoding === 'iso-8895-1') {
-            return @utf8_encode($str);
+        if ($config->get('Core', 'EscapeNonASCIICharacters')) {
+            $str = HTMLPurifier_Encoder::convertToASCIIDumbLossless($str);
         }
+        if ($iconv && !$config->get('Test', 'ForceNoIconv')) {
+            return @iconv('utf-8', $encoding . '//IGNORE', $str);
+        } elseif ($encoding === 'iso-8859-1') {
+            return @utf8_decode($str);
+        }
+        trigger_error('Encoding not supported', E_USER_ERROR);
+    }
+    
+    /**
+     * Lossless (character-wise) conversion of HTML to ASCII
+     * @static
+     * @param $str UTF-8 string to be converted to ASCII
+     * @returns ASCII encoded string with non-ASCII character entity-ized
+     * @warning Adapted from MediaWiki, claiming fair use: this is a common
+     *       algorithm. If you disagree with this license fudgery,
+     *       implement it yourself.
+     * @note Uses decimal numeric entities since they are best supported.
+     * @note This is a DUMB function: it has no concept of keeping
+     *       character entities that the projected character encoding
+     *       can allow. We could possibly implement a smart version
+     *       but that would require it to also know which Unicode
+     *       codepoints the charset supported (not an easy task).
+     * @note Sort of with cleanUTF8() but it assumes that $str is
+     *       well-formed UTF-8
+     */
+    static function convertToASCIIDumbLossless($str) {
+        $bytesleft = 0;
+        $result = '';
+        $working = 0;
+        $len = strlen($str);
+        for( $i = 0; $i < $len; $i++ ) {
+            $bytevalue = ord( $str[$i] );
+            if( $bytevalue <= 0x7F ) { //0xxx xxxx
+                $result .= chr( $bytevalue );
+                $bytesleft = 0;
+            } elseif( $bytevalue <= 0xBF ) { //10xx xxxx
+                $working = $working << 6;
+                $working += ($bytevalue & 0x3F);
+                $bytesleft--;
+                if( $bytesleft <= 0 ) {
+                    $result .= "&#" . $working . ";";
+                }
+            } elseif( $bytevalue <= 0xDF ) { //110x xxxx
+                $working = $bytevalue & 0x1F;
+                $bytesleft = 1;
+            } elseif( $bytevalue <= 0xEF ) { //1110 xxxx
+                $working = $bytevalue & 0x0F;
+                $bytesleft = 2;
+            } else { //1111 0xxx
+                $working = $bytevalue & 0x07;
+                $bytesleft = 3;
+            }
+        }
+        return $result;
     }
     
     

library/HTMLPurifier/EntityLookup.php

@@ -19,16 +19,17 @@ class HTMLPurifier_EntityLookup {
      */
     function setup($file = false) {
         if (!$file) {
-            $file = dirname(__FILE__) . '/EntityLookup/data.txt';
+            $file = dirname(__FILE__) . '/EntityLookup/entities.ser';
         }
         $this->table = unserialize(file_get_contents($file));
     }
     
     /**
      * Retrieves sole instance of the object.
+     * @static
      * @param Optional prototype of custom lookup table to overload with.
      */
-    function instance($prototype = false) {
+    static function instance($prototype = false) {
         // no references, since PHP doesn't copy unless modified
         static $instance = null;
         if ($prototype) {

library/HTMLPurifier/EntityParser.php

@@ -3,6 +3,10 @@
 require_once 'HTMLPurifier/EntityLookup.php';
 require_once 'HTMLPurifier/Encoder.php';
 
+// if want to implement error collecting here, we'll need to use some sort
+// of global data (probably trigger_error) because it's impossible to pass
+// $config or $context to the callback functions.
+
 /**
  * Handles referencing and derefencing character entities
  */
@@ -72,38 +76,12 @@ class HTMLPurifier_EntityParser
      * 
      * @warning Though this is public in order to let the callback happen,
      *          calling it directly is not recommended.
-     * @note Based on Feyd's function at
-     *       <http://forums.devnetwork.net/viewtopic.php?p=191404#191404>,
-     *       which is in public domain.
-     * @note While we're going to do code point parsing anyway, a good
-     *       optimization would be to refuse to translate code points that
-     *       are non-SGML characters.  However, this could lead to duplication.
-     * @note This function is heavily intimate with the inner workings of
-     *       UTF-8 and would also be well suited in the Encoder class (or at
-     *       least deferring some processing to it).  This is also very
-     *       similar to the unichr function in
-     *       maintenance/generate-entity-file.php (although this is superior,
-     *       due to its sanity checks).
      * @param $matches  PCRE matches array, with 0 the entire match, and
      *                  either index 1, 2 or 3 set with a hex value, dec value,
      *                  or string (respectively).
      * @returns Replacement string.
-     * @todo Implement string translations
      */
     
-    // +----------+----------+----------+----------+
-    // | 33222222 | 22221111 | 111111   |          |
-    // | 10987654 | 32109876 | 54321098 | 76543210 | bit
-    // +----------+----------+----------+----------+
-    // |          |          |          | 0xxxxxxx | 1 byte 0x00000000..0x0000007F
-    // |          |          | 110yyyyy | 10xxxxxx | 2 byte 0x00000080..0x000007FF
-    // |          | 1110zzzz | 10yyyyyy | 10xxxxxx | 3 byte 0x00000800..0x0000FFFF
-    // | 11110www | 10wwzzzz | 10yyyyyy | 10xxxxxx | 4 byte 0x00010000..0x0010FFFF
-    // +----------+----------+----------+----------+
-    // | 00000000 | 00011111 | 11111111 | 11111111 | Theoretical upper limit of legal scalars: 2097151 (0x001FFFFF)
-    // | 00000000 | 00010000 | 11111111 | 11111111 | Defined upper limit of legal scalar codes
-    // +----------+----------+----------+----------+ 
-    
     function nonSpecialEntityCallback($matches) {
         // replaces all but big five
         $entity = $matches[0];

library/HTMLPurifier/Error.php

@@ -0,0 +1,8 @@
+<?php
+
+/**
+ * Return object from functions that signifies error when null doesn't cut it
+ */
+class HTMLPurifier_Error {}
+
+?>

library/HTMLPurifier/Filter.php

@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * Represents a pre or post processing filter on HTML Purifier's output
+ * 
+ * Sometimes, a little ad-hoc fixing of HTML has to be done before
+ * it gets sent through HTML Purifier: you can use filters to acheive
+ * this effect. For instance, YouTube videos can be preserved using
+ * this manner. You could have used a decorator for this task, but
+ * PHP's support for them is not terribly robust, so we're going
+ * to just loop through the filters.
+ * 
+ * Filters should be exited first in, last out. If there are three filters,
+ * named 1, 2 and 3, the order of execution should go 1->preFilter,
+ * 2->preFilter, 3->preFilter, purify, 3->postFilter, 2->postFilter,
+ * 1->postFilter.
+ */
+
+class HTMLPurifier_Filter
+{
+    
+    /**
+     * Name of the filter for identification purposes
+     */
+    var $name;
+    
+    /**
+     * Pre-processor function, handles HTML before HTML Purifier 
+     */
+    function preFilter($html, $config, &$context) {}
+    
+    /**
+     * Post-processor function, handles HTML after HTML Purifier
+     */
+    function postFilter($html, $config, &$context) {}
+    
+}
+
+?>

library/HTMLPurifier/Filter/YouTube.php

@@ -0,0 +1,34 @@
+<?php
+
+require_once 'HTMLPurifier/Filter.php';
+
+class HTMLPurifier_Filter_YouTube extends HTMLPurifier_Filter
+{
+    
+    var $name = 'YouTube preservation';
+    
+    function preFilter($html, $config, &$context) {
+        $pre_regex = '#<object[^>]+>.+?'.
+            'http://www.youtube.com/v/([A-Za-z0-9]+).+?</object>#';
+        $pre_replace = '<span class="youtube-embed">\1</span>';
+        return preg_replace($pre_regex, $pre_replace, $html);
+    }
+    
+    function postFilter($html, $config, &$context) {
+        $post_regex = '#<span class="youtube-embed">([A-Za-z0-9]+)</span>#';
+        $post_replace = '<object width="425" height="350" '.
+            'data="http://www.youtube.com/v/\1">'.
+            '<param name="movie" value="http://www.youtube.com/v/\1"></param>'.
+            '<param name="wmode" value="transparent"></param>'.
+            '<!--[if IE]>'.
+            '<embed src="http://www.youtube.com/v/\1"'.
+            'type="application/x-shockwave-flash"'.
+            'wmode="transparent" width="425" height="350" />'.
+            '<![endif]-->'.
+            '</object>';
+        return preg_replace($post_regex, $post_replace, $html);
+    }
+    
+}
+
+?>

library/HTMLPurifier/Generator.php

@@ -1,10 +1,8 @@
 <?php
 
-// pretty-printing with indentation would be pretty cool
-
 require_once 'HTMLPurifier/Lexer.php';
 
-HTMLPurifier_ConfigDef::define(
+HTMLPurifier_ConfigSchema::define(
     'Core', 'CleanUTF8DuringGeneration', false, 'bool',
     'When true, HTMLPurifier_Generator will also check all strings it '.
     'escapes for UTF-8 well-formedness as a defense in depth measure. '.
@@ -15,6 +13,29 @@ HTMLPurifier_ConfigDef::define(
     'generateFromTokens.'
 );
 
+HTMLPurifier_ConfigSchema::define(
+    'Core', 'XHTML', true, 'bool',
+    'Determines whether or not output is XHTML or not.  When disabled, HTML '.
+    'Purifier goes into HTML 4.01 removes XHTML-specific markup constructs, '.
+    'such as boolean attribute expansion and trailing slashes in empty tags. '.
+    'This directive was available since 1.1.'
+);
+
+// extension constraints could be factored into ConfigSchema
+HTMLPurifier_ConfigSchema::define(
+    'Core', 'TidyFormat', false, 'bool',
+    '<p>Determines whether or not to run Tidy on the final output for pretty '.
+    'formatting reasons, such as indentation and wrap.</p><p>This can greatly '.
+    'improve readability for editors who are hand-editing the HTML, but is '.
+    'by no means necessary as HTML Purifier has already fixed all major '.
+    'errors the HTML may have had. Tidy is a non-default extension, and this directive '.
+    'will silently fail if Tidy is not available.</p><p>If you are looking to make '.
+    'the overall look of your page\'s source better, I recommend running Tidy '.
+    'on the entire page rather than just user-content (after all, the '.
+    'indentation relative to the containing blocks will be incorrect).</p><p>This '.
+    'directive was available since 1.1.1.</p>'
+);
+
 /**
  * Generates HTML from tokens.
  */
@@ -22,26 +43,56 @@ class HTMLPurifier_Generator
 {
     
     /**
-     * Bool cache of the CleanUTF8DuringGeneration directive.
+     * Bool cache of %Core.CleanUTF8DuringGeneration
      * @private
      */
     var $_clean_utf8 = false;
     
+    /**
+     * Bool cache of %Core.XHTML
+     * @private
+     */
+    var $_xhtml = true;
+    
     /**
      * Generates HTML from an array of tokens.
      * @param $tokens Array of HTMLPurifier_Token
      * @param $config HTMLPurifier_Config object
      * @return Generated HTML
-     * @note Only unit tests may omit configuration: internals MUST pass config
      */
-    function generateFromTokens($tokens, $config = null) {
+    function generateFromTokens($tokens, $config, &$context) {
         $html = '';
         if (!$config) $config = HTMLPurifier_Config::createDefault();
         $this->_clean_utf8 = $config->get('Core', 'CleanUTF8DuringGeneration');
+        $this->_xhtml = $config->get('Core', 'XHTML');
         if (!$tokens) return '';
         foreach ($tokens as $token) {
             $html .= $this->generateFromToken($token);
         }
+        if ($config->get('Core', 'TidyFormat') && extension_loaded('tidy')) {
+            
+            $tidy_options = array(
+               'indent'=> true,
+               'output-xhtml' => $this->_xhtml,
+               'show-body-only' => true,
+               'indent-spaces' => 2,
+               'wrap' => 68,
+            );
+            if (version_compare(PHP_VERSION, '5', '<')) {
+                tidy_set_encoding('utf8');
+                foreach ($tidy_options as $key => $value) {
+                    tidy_setopt($key, $value);
+                }
+                tidy_parse_string($html);
+                tidy_clean_repair();
+                $html = tidy_get_output();
+            } else {
+                $tidy = new Tidy;
+                $tidy->parseString($html, $tidy_options, 'utf8');
+                $tidy->cleanRepair();
+                $html = (string) $tidy;
+            }
+        }
         return $html;
     }
     
@@ -53,15 +104,17 @@ class HTMLPurifier_Generator
     function generateFromToken($token) {
         if (!isset($token->type)) return '';
         if ($token->type == 'start') {
-            $attr = $this->generateAttributes($token->attributes);
+            $attr = $this->generateAttributes($token->attr);
             return '<' . $token->name . ($attr ? ' ' : '') . $attr . '>';
             
         } elseif ($token->type == 'end') {
             return '</' . $token->name . '>';
             
         } elseif ($token->type == 'empty') {
-            $attr = $this->generateAttributes($token->attributes);
-             return '<' . $token->name . ($attr ? ' ' : '') . $attr . ' />';
+            $attr = $this->generateAttributes($token->attr);
+             return '<' . $token->name . ($attr ? ' ' : '') . $attr .
+                ( $this->_xhtml ? ' /': '' )
+                . '>';
             
         } elseif ($token->type == 'text') {
             return $this->escape($token->data);
@@ -80,6 +133,11 @@ class HTMLPurifier_Generator
     function generateAttributes($assoc_array_of_attributes) {
         $html = '';
         foreach ($assoc_array_of_attributes as $key => $value) {
+            if (!$this->_xhtml) {
+                // remove namespaced attributes
+                if (strpos($key, ':') !== false) continue;
+                // also needed: check for attribute minimization
+            }
             $html .= $key.'="'.$this->escape($value).'" ';
         }
         return rtrim($html);

library/HTMLPurifier/HTMLDefinition.php

@@ -18,10 +18,86 @@ require_once 'HTMLPurifier/AttrTransform.php';
     require_once 'HTMLPurifier/AttrTransform/BdoDir.php';
     require_once 'HTMLPurifier/AttrTransform/ImgRequired.php';
 require_once 'HTMLPurifier/ChildDef.php';
+    require_once 'HTMLPurifier/ChildDef/Chameleon.php';
+    require_once 'HTMLPurifier/ChildDef/Empty.php';
+    require_once 'HTMLPurifier/ChildDef/Required.php';
+    require_once 'HTMLPurifier/ChildDef/Optional.php';
+    require_once 'HTMLPurifier/ChildDef/Table.php';
+    require_once 'HTMLPurifier/ChildDef/StrictBlockquote.php';
 require_once 'HTMLPurifier/Generator.php';
 require_once 'HTMLPurifier/Token.php';
 require_once 'HTMLPurifier/TagTransform.php';
 
+HTMLPurifier_ConfigSchema::define(
+    'HTML', 'EnableAttrID', false, 'bool',
+    'Allows the ID attribute in HTML.  This is disabled by default '.
+    'due to the fact that without proper configuration user input can '.
+    'easily break the validation of a webpage by specifying an ID that is '.
+    'already on the surrounding HTML.  If you don\'t mind throwing caution to '.
+    'the wind, enable this directive, but I strongly recommend you also '.
+    'consider blacklisting IDs you use (%Attr.IDBlacklist) or prefixing all '.
+    'user supplied IDs (%Attr.IDPrefix).  This directive has been available '.
+    'since 1.2.0, and when set to true reverts to the behavior of pre-1.2.0 '.
+    'versions.'
+);
+
+HTMLPurifier_ConfigSchema::define(
+    'HTML', 'Strict', false, 'bool',
+    'Determines whether or not to use Transitional (loose) or Strict rulesets. '.
+    'This directive has been available since 1.3.0.'
+);
+
+HTMLPurifier_ConfigSchema::define(
+    'HTML', 'BlockWrapper', 'p', 'string',
+    'String name of element to wrap inline elements that are inside a block '.
+    'context.  This only occurs in the children of blockquote in strict mode. '.
+    'Example: by default value, <code>&lt;blockquote&gt;Foo&lt;/blockquote&gt;</code> '.
+    'would become <code>&lt;blockquote&gt;&lt;p&gt;Foo&lt;/p&gt;&lt;/blockquote&gt;</code>. The '.
+    '<code>&lt;p&gt;</code> tags can be replaced '.
+    'with whatever you desire, as long as it is a block level element. '.
+    'This directive has been available since 1.3.0.'
+);
+
+HTMLPurifier_ConfigSchema::define(
+    'HTML', 'Parent', 'div', 'string',
+    'String name of element that HTML fragment passed to library will be '.
+    'inserted in.  An interesting variation would be using span as the '.
+    'parent element, meaning that only inline tags would be allowed. '.
+    'This directive has been available since 1.3.0.'
+);
+
+HTMLPurifier_ConfigSchema::define(
+    'HTML', 'AllowedElements', null, 'lookup/null',
+    'If HTML Purifier\'s tag set is unsatisfactory for your needs, you '.
+    'can overload it with your own list of tags to allow.  Note that this '.
+    'method is subtractive: it does its job by taking away from HTML Purifier '.
+    'usual feature set, so you cannot add a tag that HTML Purifier never '.
+    'supported in the first place (like embed, form or head).  If you change this, you '.
+    'probably also want to change %HTML.AllowedAttributes. '.
+    '<strong>Warning:</strong> If another directive conflicts with the '.
+    'elements here, <em>that</em> directive will win and override. '.
+    'This directive has been available since 1.3.0.'
+);
+
+HTMLPurifier_ConfigSchema::define(
+    'HTML', 'AllowedAttributes', null, 'lookup/null',
+    'IF HTML Purifier\'s attribute set is unsatisfactory, overload it! '.
+    'The syntax is \'tag.attr\' or \'*.attr\' for the global attributes '.
+    '(style, id, class, dir, lang, xml:lang).'.
+    '<strong>Warning:</strong> If another directive conflicts with the '.
+    'elements here, <em>that</em> directive will win and override. For '.
+    'example, %HTML.EnableAttrID will take precedence over *.id in this '.
+    'directive.  You must set that directive to true before you can use '.
+    'IDs at all. This directive has been available since 1.3.0.'
+);
+
+HTMLPurifier_ConfigSchema::define(
+    'Attr', 'DisableURI', false, 'bool',
+    'Disables all URIs in all forms. Not sure why you\'d want to do that '.
+    '(after all, the Internet\'s founded on the notion of a hyperlink). '.
+    'This directive has been available since 1.3.0.'
+);
+
 /**
  * Defines the purified HTML type with large amounts of objects.
  * 
@@ -60,6 +136,20 @@ class HTMLPurifier_HTMLDefinition
      */
     var $info_parent = 'div';
     
+    /**
+     * Definition for parent element, allows parent element to be a
+     * tag that's not allowed inside the HTML fragment.
+     * @public
+     */
+    var $info_parent_def;
+    
+    /**
+     * String name of element used to wrap inline elements in block context
+     * @note This is rarely used except for BLOCKQUOTEs in strict mode
+     * @public
+     */
+    var $info_block_wrapper = 'p';
+    
     /**
      * Associative array of deprecated tag name to HTMLPurifier_TagTransform
      * @public
@@ -78,14 +168,25 @@ class HTMLPurifier_HTMLDefinition
      */
     var $info_attr_transform_post = array();
     
+    /**
+     * Lookup table of flow elements
+     * @public
+     */
+    var $info_flow_elements = array();
+    
+    /**
+     * Boolean is a strict definition?
+     * @public
+     */
+    var $strict;
+    
     /**
      * Initializes the definition, the meat of the class.
      */
     function setup($config) {
         
-        // emulates the structure of the DTD
-        // these are condensed, however, with bad stuff taken out
-        // screening process was done by hand
+        // some cached config values
+        $this->strict = $config->get('HTML', 'Strict');
         
         //////////////////////////////////////////////////////////////////////
         // info[] : initializes the definition objects
@@ -97,13 +198,19 @@ class HTMLPurifier_HTMLDefinition
             array(
                 'ins', 'del', 'blockquote', 'dd', 'li', 'div', 'em', 'strong',
                 'dfn', 'code', 'samp', 'kbd', 'var', 'cite', 'abbr', 'acronym',
-                'q', 'sub', 'tt', 'sup', 'i', 'b', 'big', 'small', 'u', 's',
-                'strike', 'bdo', 'span', 'dt', 'p', 'h1', 'h2', 'h3', 'h4',
+                'q', 'sub', 'tt', 'sup', 'i', 'b', 'big', 'small',
+                'bdo', 'span', 'dt', 'p', 'h1', 'h2', 'h3', 'h4',
                 'h5', 'h6', 'ol', 'ul', 'dl', 'address', 'img', 'br', 'hr',
                 'pre', 'a', 'table', 'caption', 'thead', 'tfoot', 'tbody',
                 'colgroup', 'col', 'td', 'th', 'tr'
             );
         
+        if (!$this->strict) {
+            $allowed_tags[] = 'u';
+            $allowed_tags[] = 's';
+            $allowed_tags[] = 'strike';
+        }
+        
         foreach ($allowed_tags as $tag) {
             $this->info[$tag] = new HTMLPurifier_ElementDef();
         }
@@ -111,12 +218,23 @@ class HTMLPurifier_HTMLDefinition
         //////////////////////////////////////////////////////////////////////
         // info[]->child : defines allowed children for elements
         
-        // entities: prefixed with e_ and _ replaces .
+        // emulates the structure of the DTD
+        // however, these are condensed, with bad stuff taken out
+        // screening process was done by hand
+        
+        // entities: prefixed with e_ and _ replaces . from DTD
+        // double underlines are entities we made up
         
         // we don't use an array because that complicates interpolation
         // strings are used instead of arrays because if you use arrays,
         // you have to do some hideous manipulation with array_merge()
         
+        // todo: determine whether or not having allowed children
+        //       that aren't allowed globally affects security (it shouldn't)
+        // if above works out, extend children definitions to include all
+        //       possible elements (allowed elements will dictate which ones
+        //       get dropped
+        
         $e_special_extra = 'img';
         $e_special_basic = 'br | span | bdo';
         $e_special = "$e_special_basic | $e_special_extra";
@@ -127,11 +245,9 @@ class HTMLPurifier_HTMLDefinition
         $e_phrase_basic = 'em | strong | dfn | code | q | samp | kbd | var'.
           ' | cite | abbr | acronym';
         $e_phrase = "$e_phrase_basic | $e_phrase_extra";
-        $e_inline_forms = ''; // humor the dtd
         $e_misc_inline = 'ins | del';
         $e_misc = "$e_misc_inline";
-        $e_inline = "a | $e_special | $e_fontstyle | $e_phrase".
-          " | $e_inline_forms";
+        $e_inline = "a | $e_special | $e_fontstyle | $e_phrase";
         // pseudo-property we created for convenience, see later on
         $e__inline = "#PCDATA | $e_inline | $e_misc_inline";
         // note the casing
@@ -140,24 +256,31 @@ class HTMLPurifier_HTMLDefinition
         $e_lists = 'ul | ol | dl';
         $e_blocktext = 'pre | hr | blockquote | address';
         $e_block = "p | $e_heading | div | $e_lists | $e_blocktext | table";
+        $e_Block = new HTMLPurifier_ChildDef_Optional($e_block);
         $e__flow = "#PCDATA | $e_block | $e_inline | $e_misc";
         $e_Flow = new HTMLPurifier_ChildDef_Optional($e__flow);
-        $e_a_content = new HTMLPurifier_ChildDef_Optional("#PCDATA | $e_special".
-          " | $e_fontstyle | $e_phrase | $e_inline_forms | $e_misc_inline");
+        $e_a_content = new HTMLPurifier_ChildDef_Optional("#PCDATA".
+          " | $e_special | $e_fontstyle | $e_phrase | $e_misc_inline");
         $e_pre_content = new HTMLPurifier_ChildDef_Optional("#PCDATA | a".
           " | $e_special_basic | $e_fontstyle_basic | $e_phrase_basic".
-          " | $e_inline_forms | $e_misc_inline");
-        $e_form_content = new HTMLPurifier_ChildDef_Optional(''); //unused
-        $e_form_button_content = new HTMLPurifier_ChildDef_Optional(''); // unused
+          " | $e_misc_inline");
+        $e_form_content = new HTMLPurifier_ChildDef_Optional('');//unused
+        $e_form_button_content = new HTMLPurifier_ChildDef_Optional('');//unused
         
         $this->info['ins']->child =
-        $this->info['del']->child = new HTMLPurifier_ChildDef_Chameleon($e__inline, $e__flow);
+        $this->info['del']->child =
+            new HTMLPurifier_ChildDef_Chameleon($e__inline, $e__flow);
         
-        $this->info['blockquote']->child=
         $this->info['dd']->child  =
         $this->info['li']->child  =
         $this->info['div']->child = $e_Flow;
         
+        if ($this->strict) {
+            $this->info['blockquote']->child = new HTMLPurifier_ChildDef_StrictBlockquote();
+        } else {
+            $this->info['blockquote']->child = $e_Flow;
+        }
+        
         $this->info['caption']->child   = 
         $this->info['em']->child   =
         $this->info['strong']->child    =
@@ -177,9 +300,6 @@ class HTMLPurifier_HTMLDefinition
         $this->info['b']->child    =
         $this->info['big']->child  =
         $this->info['small']->child=
-        $this->info['u']->child    =
-        $this->info['s']->child    =
-        $this->info['strike']->child    =
         $this->info['bdo']->child  =
         $this->info['span']->child =
         $this->info['dt']->child   =
@@ -191,15 +311,25 @@ class HTMLPurifier_HTMLDefinition
         $this->info['h5']->child   = 
         $this->info['h6']->child   = $e_Inline;
         
+        if (!$this->strict) {
+            $this->info['u']->child    =
+            $this->info['s']->child    =
+            $this->info['strike']->child    = $e_Inline;
+        }
+        
         // the only three required definitions, besides custom table code
         $this->info['ol']->child   =
         $this->info['ul']->child   = new HTMLPurifier_ChildDef_Required('li');
         
         $this->info['dl']->child   = new HTMLPurifier_ChildDef_Required('dt|dd');
         
-        $this->info['address']->child =
-          new HTMLPurifier_ChildDef_Optional("#PCDATA | p | $e_inline".
-              " | $e_misc_inline");
+        if ($this->strict) {
+            $this->info['address']->child = $e_Inline;
+        } else {
+            $this->info['address']->child =
+              new HTMLPurifier_ChildDef_Optional("#PCDATA | p | $e_inline".
+                  " | $e_misc_inline");
+        }
         
         $this->info['img']->child  =
         $this->info['br']->child   =
@@ -209,8 +339,7 @@ class HTMLPurifier_HTMLDefinition
         
         $this->info['a']->child    = $e_a_content;
         
-        $this->info['table']->child = new HTMLPurifier_ChildDef_Custom(
-            '(caption?, (col*|colgroup*), thead?, tfoot?, (tbody+|tr+))');
+        $this->info['table']->child = new HTMLPurifier_ChildDef_Table();
         
         // not a real entity, watch the double underscore
         $e__row = new HTMLPurifier_ChildDef_Required('tr');
@@ -226,17 +355,22 @@ class HTMLPurifier_HTMLDefinition
         //////////////////////////////////////////////////////////////////////
         // info[]->type : defines the type of the element (block or inline)
         
-        // reuses $e_Inline and $e_block
-        
-        foreach ($e_Inline->elements as $name) {
+        // reuses $e_Inline and $e_Block
+        foreach ($e_Inline->elements as $name => $bool) {
+            if ($name == '#PCDATA') continue;
+            if (!isset($this->info[$name])) continue;
             $this->info[$name]->type = 'inline';
         }
         
-        $e_Block = new HTMLPurifier_ChildDef_Optional($e_block);
-        foreach ($e_Block->elements as $name) {
+        foreach ($e_Block->elements as $name => $bool) {
+            if (!isset($this->info[$name])) continue;
             $this->info[$name]->type = 'block';
         }
         
+        foreach ($e_Flow->elements as $name => $bool) {
+            $this->info_flow_elements[$name] = true;
+        }
+        
         //////////////////////////////////////////////////////////////////////
         // info[]->excludes : defines elements that aren't allowed in here
         
@@ -244,7 +378,7 @@ class HTMLPurifier_HTMLDefinition
         
         $this->info['a']->excludes = array('a' => true);
         $this->info['pre']->excludes = array_flip(array('img', 'big', 'small',
-            // technically in spec, but we don't allow em anyway
+            // technically useless, but good to be indepth
             'object', 'applet', 'font', 'basefont'));
         
         //////////////////////////////////////////////////////////////////////
@@ -254,13 +388,14 @@ class HTMLPurifier_HTMLDefinition
         // by the transform classes. It will, however, do simple and slightly
         // complex attribute value substitution
         
+        // the question of varying allowed attributes is more entangling.
+        
         $e_Text = new HTMLPurifier_AttrDef_Text();
         
         // attrs, included in almost every single one except for a few,
         // which manually override these in their local definitions
         $this->info_global_attr = array(
             // core attrs
-            'id'    => new HTMLPurifier_AttrDef_ID(),
             'class' => new HTMLPurifier_AttrDef_Class(),
             'title' => $e_Text,
             'style' => new HTMLPurifier_AttrDef_CSS(),
@@ -270,6 +405,10 @@ class HTMLPurifier_HTMLDefinition
             'xml:lang' => new HTMLPurifier_AttrDef_Lang(),
             );
         
+        if ($config->get('HTML', 'EnableAttrID')) {
+            $this->info_global_attr['id'] = new HTMLPurifier_AttrDef_ID();
+        }
+        
         // required attribute stipulation handled in attribute transformation
         $this->info['bdo']->attr = array(); // nothing else
         
@@ -298,7 +437,8 @@ class HTMLPurifier_HTMLDefinition
         
         $this->info['table']->attr['summary'] = $e_Text;
         
-        $this->info['table']->attr['border'] = new HTMLPurifier_AttrDef_Pixels();
+        $this->info['table']->attr['border'] =
+            new HTMLPurifier_AttrDef_Pixels();
         
         $e_Length = new HTMLPurifier_AttrDef_Length();
         $this->info['table']->attr['cellpadding'] =
@@ -320,17 +460,26 @@ class HTMLPurifier_HTMLDefinition
         $this->info['td']->attr['colspan'] =
         $this->info['th']->attr['colspan'] = $e__NumberSpan;
         
-        $e_URI = new HTMLPurifier_AttrDef_URI();
-        $this->info['a']->attr['href'] =
-        $this->info['img']->attr['longdesc'] =
-        $this->info['img']->attr['src'] =
-        $this->info['del']->attr['cite'] =
-        $this->info['ins']->attr['cite'] =
-        $this->info['blockquote']->attr['cite'] =
-        $this->info['q']->attr['cite'] = $e_URI;
+        if (!$config->get('Attr', 'DisableURI')) {
+            $e_URI = new HTMLPurifier_AttrDef_URI();
+            $this->info['a']->attr['href'] =
+            $this->info['img']->attr['longdesc'] =
+            $this->info['del']->attr['cite'] =
+            $this->info['ins']->attr['cite'] =
+            $this->info['blockquote']->attr['cite'] =
+            $this->info['q']->attr['cite'] = $e_URI;
+            
+            // URI that causes HTTP request
+            $this->info['img']->attr['src'] = new HTMLPurifier_AttrDef_URI(true);
+        }
+        
+        if (!$this->strict) {
+            $this->info['li']->attr['value'] = new HTMLPurifier_AttrDef_Integer();
+            $this->info['ol']->attr['start'] = new HTMLPurifier_AttrDef_Integer();
+        }
         
         //////////////////////////////////////////////////////////////////////
-        // UNIMP : info_tag_transform : transformations of tags
+        // info_tag_transform : transformations of tags
         
         $this->info_tag_transform['font']   = new HTMLPurifier_TagTransform_Font();
         $this->info_tag_transform['menu']   = new HTMLPurifier_TagTransform_Simple('ul');
@@ -340,6 +489,9 @@ class HTMLPurifier_HTMLDefinition
         //////////////////////////////////////////////////////////////////////
         // info[]->auto_close : tags that automatically close another
         
+        // todo: determine whether or not SGML-like modeling based on
+        // mandatory/optional end tags would be a better policy
+        
         // make sure you test using isset() not !empty()
         
         // these are all block elements: blocks aren't allowed in P
@@ -382,6 +534,60 @@ class HTMLPurifier_HTMLDefinition
         
         $this->info_attr_transform_post[] = new HTMLPurifier_AttrTransform_Lang();
         
+        // protect against stdclasses floating around
+        foreach ($this->info as $key => $obj) {
+            if ($obj instanceof stdClass) {
+                unset($this->info[$key]);
+            }
+        }
+        
+        //////////////////////////////////////////////////////////////////////
+        // info_block_wrapper : wraps inline elements in block context
+        
+        $block_wrapper = $config->get('HTML', 'BlockWrapper');
+        if (isset($e_Block->elements[$block_wrapper])) {
+            $this->info_block_wrapper = $block_wrapper;
+        } else {
+            trigger_error('Cannot use non-block element as block wrapper.',
+                E_USER_ERROR);
+        }
+        
+        //////////////////////////////////////////////////////////////////////
+        // info_parent : parent element of the HTML fragment
+        
+        $parent = $config->get('HTML', 'Parent');
+        if (isset($this->info[$parent])) {
+            $this->info_parent = $parent;
+        } else {
+            trigger_error('Cannot use unrecognized element as parent.',
+                E_USER_ERROR);
+        }
+        $this->info_parent_def = $this->info[$this->info_parent];
+        
+        //////////////////////////////////////////////////////////////////////
+        // %HTML.Allowed(Elements|Attributes) : cut non-allowed elements
+        
+        $allowed_elements = $config->get('HTML', 'AllowedElements');
+        if (is_array($allowed_elements)) {
+            foreach ($this->info as $name => $d) {
+                if(!isset($allowed_elements[$name])) unset($this->info[$name]);
+            }
+        }
+        $allowed_attributes = $config->get('HTML', 'AllowedAttributes');
+        if (is_array($allowed_attributes)) {
+            foreach ($this->info_global_attr as $attr_key => $info) {
+                if (!isset($allowed_attributes["*.$attr_key"])) {
+                    unset($this->info_global_attr[$attr_key]);
+                }
+            }
+            foreach ($this->info as $tag => $info) {
+                foreach ($info->attr as $attr => $attr_info) {
+                    if (!isset($allowed_attributes["$tag.$attr"])) {
+                        unset($this->info[$tag]->attr[$attr]);
+                    }
+                }
+            }
+        }
     }
     
     function setAttrForTableElements($attr, $def) {
@@ -447,4 +653,4 @@ class HTMLPurifier_ElementDef
     
 }
 
-?>
+?>

library/HTMLPurifier/IDAccumulator.php

@@ -3,6 +3,9 @@
 /**
  * Component of HTMLPurifier_AttrContext that accumulates IDs to prevent dupes
  * @note In Slashdot-speak, dupe means duplicate.
+ * @note This class does not accept $config or $context, thus, it is the
+ *       burden of the callee to register the appropriate errors or
+ *       configuration.
  */
 class HTMLPurifier_IDAccumulator
 {

library/HTMLPurifier/Lexer.php

@@ -4,12 +4,11 @@ require_once 'HTMLPurifier/Token.php';
 require_once 'HTMLPurifier/Encoder.php';
 require_once 'HTMLPurifier/EntityParser.php';
 
-HTMLPurifier_ConfigDef::define(
+HTMLPurifier_ConfigSchema::define(
     'Core', 'AcceptFullDocuments', true, 'bool',
     'This parameter determines whether or not the filter should accept full '.
     'HTML documents, not just HTML fragments.  When on, it will '.
-    'drop all sections except the content between body.  Depending on '.
-    'the implementation in use, this may speed up document parse times.'
+    'drop all sections except the content between body.'
 );
 
 /**
@@ -57,11 +56,62 @@ class HTMLPurifier_Lexer
 {
     
     function HTMLPurifier_Lexer() {
-        $this->_encoder = new HTMLPurifier_Encoder();
         $this->_entity_parser = new HTMLPurifier_EntityParser();
     }
     
-    var $_encoder;
+    
+    /**
+     * Most common entity to raw value conversion table for special entities.
+     * @protected
+     */
+    var $_special_entity2str =
+            array(
+                    '"' => '"',
+                    '&'  => '&',
+                    '&lt;'   => '<',
+                    '&gt;'   => '>',
+                    '&#39;'  => "'",
+                    '&#039;' => "'",
+                    '&#x27;' => "'"
+            );
+    
+    /**
+     * Parses special entities into the proper characters.
+     * 
+     * This string will translate escaped versions of the special characters
+     * into the correct ones.
+     * 
+     * @warning
+     * You should be able to treat the output of this function as
+     * completely parsed, but that's only because all other entities should
+     * have been handled previously in substituteNonSpecialEntities()
+     * 
+     * @param $string String character data to be parsed.
+     * @returns Parsed character data.
+     */
+    function parseData($string) {
+        
+        // following functions require at least one character
+        if ($string === '') return '';
+        
+        // subtracts amps that cannot possibly be escaped
+        $num_amp = substr_count($string, '&') - substr_count($string, '& ') -
+            ($string[strlen($string)-1] === '&' ? 1 : 0);
+        
+        if (!$num_amp) return $string; // abort if no entities
+        $num_esc_amp = substr_count($string, '&amp;');
+        $string = strtr($string, $this->_special_entity2str);
+        
+        // code duplication for sake of optimization, see above
+        $num_amp_2 = substr_count($string, '&') - substr_count($string, '& ') -
+            ($string[strlen($string)-1] === '&' ? 1 : 0);
+        
+        if ($num_amp_2 <= $num_esc_amp) return $string;
+        
+        // hmm... now we have some uncommon entities. Use the callback.
+        $string = $this->_entity_parser->substituteSpecialEntities($string);
+        return $string;
+    }
     
     /**
      * Lexes an HTML string into tokens.
@@ -69,7 +119,7 @@ class HTMLPurifier_Lexer
      * @param $string String HTML.
      * @return HTMLPurifier_Token array representation of HTML.
      */
-    function tokenizeHTML($string, $config = null) {
+    function tokenizeHTML($string, $config, &$context) {
         trigger_error('Call to abstract class', E_USER_ERROR);
     }
     
@@ -85,6 +135,8 @@ class HTMLPurifier_Lexer
      * default with your own implementation.  A copy/reference of the prototype
      * lexer will now be returned when you request a new lexer.
      * 
+     * @static
+     * 
      * @note
      * Though it is possible to call this factory method from subclasses,
      * such usage is not recommended.
@@ -92,14 +144,14 @@ class HTMLPurifier_Lexer
      * @param $prototype Optional prototype lexer.
      * @return Concrete lexer.
      */
-    function create($prototype = null) {
+    static function create($prototype = null) {
         // we don't really care if it's a reference or a copy
         static $lexer = null;
         if ($prototype) {
             $lexer = $prototype;
         }
         if (empty($lexer)) {
-            if (version_compare(PHP_VERSION, '5', '>=')) {
+            if (class_exists('DOMDocument')) { // check for DOM support
                 require_once 'HTMLPurifier/Lexer/DOMLex.php';
                 $lexer = new HTMLPurifier_Lexer_DOMLex();
             } else {
@@ -113,11 +165,12 @@ class HTMLPurifier_Lexer
     /**
      * Translates CDATA sections into regular sections (through escaping).
      * 
+     * @static
      * @protected
      * @param $string HTML string to process.
      * @returns HTML with CDATA sections escaped.
      */
-    function escapeCDATA($string) {
+    static function escapeCDATA($string) {
         return preg_replace_callback(
             '/<!\[CDATA\[(.+?)\]\]>/',
             array('HTMLPurifier_Lexer', 'CDATACallback'),
@@ -128,13 +181,14 @@ class HTMLPurifier_Lexer
     /**
      * Callback function for escapeCDATA() that does the work.
      * 
+     * @static
      * @warning Though this is public in order to let the callback happen,
      *          calling it directly is not recommended.
      * @params $matches PCRE matches array, with index 0 the entire match
      *                  and 1 the inside of the CDATA section.
      * @returns Escaped internals of the CDATA section.
      */
-    function CDATACallback($matches) {
+    static function CDATACallback($matches) {
         // not exactly sure why the character set is needed, but whatever
         return htmlspecialchars($matches[1], ENT_COMPAT, 'UTF-8');
     }
@@ -143,7 +197,7 @@ class HTMLPurifier_Lexer
      * Takes a piece of HTML and normalizes it by converting entities, fixing
      * encoding, extracting bits, and other good stuff.
      */
-    function normalize($html, $config) {
+    function normalize($html, $config, &$context) {
         
         // extract body from document if applicable
         if ($config->get('Core', 'AcceptFullDocuments')) {
@@ -159,7 +213,7 @@ class HTMLPurifier_Lexer
         // clean into wellformed UTF-8 string for an SGML context: this has
         // to be done after entity expansion because the entities sometimes
         // represent non-SGML characters (horror, horror!)
-        $html = $this->_encoder->cleanUTF8($html);
+        $html = HTMLPurifier_Encoder::cleanUTF8($html);
         
         return $html;
     }

library/HTMLPurifier/Lexer/DOMLex.php

@@ -12,15 +12,19 @@ require_once 'HTMLPurifier/TokenFactory.php';
  * documents, it performs twenty times faster than
  * HTMLPurifier_Lexer_DirectLex,and is the default choice for PHP 5. 
  * 
- * @notice
- * Any empty elements will have empty tokens associated with them, even if
+ * @note Any empty elements will have empty tokens associated with them, even if
  * this is prohibited by the spec. This is cannot be fixed until the spec
  * comes into play.
  * 
- * @todo Determine DOM's entity parsing behavior, point to local entity files
- *       if necessary.
- * @todo Make div access less fragile, and refrain from preprocessing when
- *       HTML tag and friends are already present.
+ * @note PHP's DOM extension does not actually parse any entities, we use
+ *       our own function to do that.
+ * 
+ * @warning DOM tends to drop whitespace, which may wreak havoc on indenting.
+ *          If this is a huge problem, due to the fact that HTML is hand
+ *          edited and youa re unable to get a parser cache that caches the
+ *          the output of HTML Purifier while keeping the original HTML lying
+ *          around, you may want to run Tidy on the resulting output or use
+ *          HTMLPurifier_DirectLex
  */
 
 class HTMLPurifier_Lexer_DOMLex extends HTMLPurifier_Lexer
@@ -34,10 +38,9 @@ class HTMLPurifier_Lexer_DOMLex extends HTMLPurifier_Lexer
         $this->factory = new HTMLPurifier_TokenFactory();
     }
     
-    public function tokenizeHTML($string, $config = null) {
-        if (!$config) $config = HTMLPurifier_Config::createDefault();
+    public function tokenizeHTML($string, $config, &$context) {
         
-        $string = $this->normalize($string, $config);
+        $string = $this->normalize($string, $config, $context);
         
         // preprocess string, essential for UTF-8
         $string =
@@ -85,21 +88,27 @@ class HTMLPurifier_Lexer_DOMLex extends HTMLPurifier_Lexer
         } elseif ($node->nodeType === XML_COMMENT_NODE) {
             $tokens[] = $this->factory->createComment($node->data);
             return;
+        } elseif (
+            // not-well tested: there may be other nodes we have to grab
+            $node->nodeType !== XML_ELEMENT_NODE
+        ) {
+            return;
         }
         
+        $attr = $node->hasAttributes() ?
+            $this->transformAttrToAssoc($node->attributes) :
+            array();
+        
         // We still have to make sure that the element actually IS empty
         if (!$node->childNodes->length) {
             if ($collect) {
-                $tokens[] = $this->factory->createEmpty(
-                    $node->tagName,
-                    $this->transformAttrToAssoc($node->attributes)
-                );
+                $tokens[] = $this->factory->createEmpty($node->tagName, $attr);
             }
         } else {
             if ($collect) { // don't wrap on first iteration
                 $tokens[] = $this->factory->createStart(
                     $tag_name = $node->tagName, // somehow, it get's dropped
-                    $this->transformAttrToAssoc($node->attributes)
+                    $attr
                 );
             }
             foreach ($node->childNodes as $node) {

library/HTMLPurifier/Lexer/DirectLex.php

@@ -12,75 +12,21 @@ require_once 'HTMLPurifier/Lexer.php';
  * completely eventually.
  * 
  * @todo Reread XML spec and document differences.
- * @todo Add support for CDATA sections.
- * @todo Determine correct behavior in outputting comment data. (preserve dashes?)
- * @todo Optimize main function tokenizeHTML().
- * @todo Less than sign (<) being prohibited (even as entity) in attr-values?
+ * 
+ * @todo Determine correct behavior in transforming comment data. (preserve dashes?)
  */
 class HTMLPurifier_Lexer_DirectLex extends HTMLPurifier_Lexer
 {
     
-    /**
-     * Most common entity to raw value conversion table for special entities.
-     * @protected
-     */
-    var $_special_entity2str =
-            array(
-                    '&quot;' => '"',
-                    '&amp;'  => '&',
-                    '&lt;'   => '<',
-                    '&gt;'   => '>',
-                    '&#39;'  => "'",
-                    '&#039;' => "'",
-                    '&#x27;' => "'"
-            );
-    
-    /**
-     * Parses special entities into the proper characters.
-     * 
-     * This string will translate escaped versions of the special characters
-     * into the correct ones.
-     * 
-     * @warning
-     * You should be able to treat the output of this function as
-     * completely parsed, but that's only because all other entities should
-     * have been handled previously in substituteNonSpecialEntities()
-     * 
-     * @param $string String character data to be parsed.
-     * @returns Parsed character data.
-     */
-    function parseData($string) {
-        
-        // subtracts amps that cannot possibly be escaped
-        $num_amp = substr_count($string, '&') - substr_count($string, '& ') -
-            ($string[strlen($string)-1] === '&' ? 1 : 0);
-        
-        if (!$num_amp) return $string; // abort if no entities
-        $num_esc_amp = substr_count($string, '&amp;');
-        $string = strtr($string, $this->_special_entity2str);
-        
-        // code duplication for sake of optimization, see above
-        $num_amp_2 = substr_count($string, '&') - substr_count($string, '& ') -
-            ($string[strlen($string)-1] === '&' ? 1 : 0);
-        
-        if ($num_amp_2 <= $num_esc_amp) return $string;
-        
-        // hmm... now we have some uncommon entities. Use the callback.
-        $string = $this->_entity_parser->substituteSpecialEntities($string);
-        return $string;
-    }
-    
     /**
      * Whitespace characters for str(c)spn.
      * @protected
      */
     var $_whitespace = "\x20\x09\x0D\x0A";
     
-    function tokenizeHTML($html, $config = null) {
+    function tokenizeHTML($html, $config, &$context) {
         
-        if (!$config) $config = HTMLPurifier_Config::createDefault();
-        
-        $html = $this->normalize($html, $config);
+        $html = $this->normalize($html, $config, $context);
         
         $cursor = 0; // our location in the text
         $inside_tag = false; // whether or not we're parsing the inside of a tag
@@ -197,17 +143,18 @@ class HTMLPurifier_Lexer_DirectLex extends HTMLPurifier_Lexer
                         )
                     );
                 if ($attribute_string) {
-                    $attributes = $this->parseAttributeString(
-                                        $attribute_string
-                                  );
+                    $attr = $this->parseAttributeString(
+                                    $attribute_string
+                                  , $config, $context
+                              );
                 } else {
-                    $attributes = array();
+                    $attr = array();
                 }
                 
                 if ($is_self_closing) {
-                    $array[] = new HTMLPurifier_Token_Empty($type, $attributes);
+                    $array[] = new HTMLPurifier_Token_Empty($type, $attr);
                 } else {
-                    $array[] = new HTMLPurifier_Token_Start($type, $attributes);
+                    $array[] = new HTMLPurifier_Token_Start($type, $attr);
                 }
                 $cursor = $position_next_gt + 1;
                 $inside_tag = false;
@@ -233,7 +180,7 @@ class HTMLPurifier_Lexer_DirectLex extends HTMLPurifier_Lexer
      * @param $string Inside of tag excluding name.
      * @returns Assoc array of attributes.
      */
-    function parseAttributeString($string) {
+    function parseAttributeString($string, $config, &$context) {
         $string = (string) $string; // quick typecast
         
         if ($string == '') return array(); // no attributes

library/HTMLPurifier/Lexer/PEARSax3.php

@@ -18,6 +18,8 @@ require_once 'HTMLPurifier/Lexer.php';
  * whatever it does for poorly formed HTML is up to it.
  * 
  * @todo Generalize so that XML_HTMLSax is also supported.
+ * 
+ * @warning Entity-resolution inside attributes is broken.
  */
 
 class HTMLPurifier_Lexer_PEARSax3 extends HTMLPurifier_Lexer
@@ -29,18 +31,19 @@ class HTMLPurifier_Lexer_PEARSax3 extends HTMLPurifier_Lexer
      */
     var $tokens = array();
     
-    function tokenizeHTML($string, $config = null) {
+    function tokenizeHTML($string, $config, &$context) {
         
         $this->tokens = array();
         
-        if (!$config) $config = HTMLPurifier_Config::createDefault();
-        $string = $this->normalize($string, $config);
+        $string = $this->normalize($string, $config, $context);
         
-        $parser=& new XML_HTMLSax3();
+        $parser = new XML_HTMLSax3();
         $parser->set_object($this);
         $parser->set_element_handler('openHandler','closeHandler');
         $parser->set_data_handler('dataHandler');
         $parser->set_escape_handler('escapeHandler');
+        
+        // doesn't seem to work correctly for attributes
         $parser->set_option('XML_OPTION_ENTITIES_PARSED', 1);
         
         $parser->parse($string);
@@ -53,6 +56,10 @@ class HTMLPurifier_Lexer_PEARSax3 extends HTMLPurifier_Lexer
      * Open tag event handler, interface is defined by PEAR package.
      */
     function openHandler(&$parser, $name, $attrs, $closed) {
+        // entities are not resolved in attrs
+        foreach ($attrs as $key => $attr) {
+            $attrs[$key] = $this->parseData($attr);
+        }
         if ($closed) {
             $this->tokens[] = new HTMLPurifier_Token_Empty($name, $attrs);
         } else {

library/HTMLPurifier/PercentEncoder.php

@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * Class that handles operations involving percent-encoding in URIs.
+ */
+class HTMLPurifier_PercentEncoder
+{
+    
+    /**
+     * Fix up percent-encoding by decoding unreserved characters and normalizing
+     * @param $string String to normalize
+     */
+    function normalize($string) {
+        if ($string == '') return '';
+        $parts = explode('%', $string);
+        $ret = array_shift($parts);
+        foreach ($parts as $part) {
+            $length = strlen($part);
+            if ($length < 2) {
+                $ret .= '%25' . $part;
+                continue;
+            }
+            $encoding = substr($part, 0, 2);
+            $text     = substr($part, 2);
+            if (!ctype_xdigit($encoding)) {
+                $ret .= '%25' . $part;
+                continue;
+            }
+            $int = hexdec($encoding);
+            if (
+                ($int >= 48 && $int <= 57) || // digits
+                ($int >= 65 && $int <= 90) || // uppercase letters
+                ($int >= 97 && $int <= 122) || // lowercase letters
+                $int == 126 || $int == 45 || $int == 46 || $int == 95 // ~-._
+            ) {
+                $ret .= chr($int) . $text;
+                continue;
+            }
+            $encoding = strtoupper($encoding);
+            $ret .= '%' . $encoding . $text;
+        }
+        return $ret;
+    }
+    
+}
+
+?>

library/HTMLPurifier/Printer.php

@@ -0,0 +1,149 @@
+<?php
+
+require_once 'HTMLPurifier/Generator.php';
+require_once 'HTMLPurifier/Token.php';
+require_once 'HTMLPurifier/Encoder.php';
+
+class HTMLPurifier_Printer
+{
+    
+    /**
+     * Instance of HTMLPurifier_Generator for HTML generation convenience funcs
+     */
+    var $generator;
+    
+    /**
+     * Instance of HTMLPurifier_Config, for easy access
+     */
+    var $config;
+    
+    /**
+     * Initialize $generator.
+     */
+    function HTMLPurifier_Printer() {
+        $this->generator = new HTMLPurifier_Generator();
+    }
+    
+    /**
+     * Main function that renders object or aspect of that object
+     * @param $config Configuration object
+     */
+    function render($config) {}
+    
+    /**
+     * Returns a start tag
+     * @param $tag Tag name
+     * @param $attr Attribute array
+     */
+    function start($tag, $attr = array()) {
+        return $this->generator->generateFromToken(
+                    new HTMLPurifier_Token_Start($tag, $attr ? $attr : array())
+               );
+    }
+    
+    /**
+     * Returns an end teg
+     * @param $tag Tag name
+     */
+    function end($tag) {
+        return $this->generator->generateFromToken(
+                    new HTMLPurifier_Token_End($tag)
+               );
+    }
+    
+    /**
+     * Prints a complete element with content inside
+     * @param $tag Tag name
+     * @param $contents Element contents
+     * @param $attr Tag attributes
+     * @param $escape Bool whether or not to escape contents
+     */
+    function element($tag, $contents, $attr = array(), $escape = true) {
+        return $this->start($tag, $attr) .
+               ($escape ? $this->escape($contents) : $contents) .
+               $this->end($tag);
+    }
+    
+    /**
+     * Prints a simple key/value row in a table.
+     * @param $name Key
+     * @param $value Value
+     */
+    function row($name, $value) {
+        if (is_bool($value)) $value = $value ? 'On' : 'Off';
+        return
+            $this->start('tr') . "\n" .
+                $this->element('th', $name) . "\n" .
+                $this->element('td', $value) . "\n" .
+            $this->end('tr')
+        ;
+    }
+    
+    /**
+     * Escapes a string for HTML output.
+     * @param $string String to escape
+     */
+    function escape($string) {
+        $string = HTMLPurifier_Encoder::cleanUTF8($string);
+        $string = htmlspecialchars($string, ENT_COMPAT, 'UTF-8');
+        return $string;
+    }
+    
+    /**
+     * Takes a list of strings and turns them into a single list
+     * @param $array List of strings
+     * @param $polite Bool whether or not to add an end before the last
+     */
+    function listify($array, $polite = false) {
+        if (empty($array)) return 'None';
+        $ret = '';
+        $i = count($array);
+        foreach ($array as $value) {
+            $i--;
+            $ret .= $value;
+            if ($i > 0 && !($polite && $i == 1)) $ret .= ', ';
+            if ($polite && $i == 1) $ret .= 'and ';
+        }
+        return $ret;
+    }
+    
+    /**
+     * Retrieves the class of an object without prefixes, as well as metadata
+     * @param $obj Object to determine class of
+     * @param $prefix Further prefix to remove
+     */
+    function getClass($obj, $sec_prefix = '') {
+        static $five = null;
+        if ($five === null) $five = version_compare(PHP_VERSION, '5', '>=');
+        $prefix = 'HTMLPurifier_' . $sec_prefix;
+        if (!$five) $prefix = strtolower($prefix);
+        $class = str_replace($prefix, '', get_class($obj));
+        $lclass = strtolower($class);
+        $class .= '(';
+        switch ($lclass) {
+            case 'enum':
+                $values = array();
+                foreach ($obj->valid_values as $value => $bool) {
+                    $values[] = $value;
+                }
+                $class .= implode(', ', $values);
+                break;
+            case 'composite':
+                $values = array();
+                foreach ($obj->defs as $def) {
+                    $values[] = $this->getClass($def, $sec_prefix);
+                }
+                $class .= implode(', ', $values);
+                break;
+            case 'multiple':
+                $class .= $this->getClass($obj->single, $sec_prefix) . ', ';
+                $class .= $obj->max;
+                break;
+        }
+        $class .= ')';
+        return $class;
+    }
+    
+}
+
+?>

library/HTMLPurifier/Printer/CSSDefinition.php

@@ -0,0 +1,40 @@
+<?php
+
+require_once 'HTMLPurifier/Printer.php';
+
+class HTMLPurifier_Printer_CSSDefinition extends HTMLPurifier_Printer
+{
+    
+    var $def;
+    
+    function render($config) {
+        $this->def = $config->getCSSDefinition();
+        $ret = '';
+        
+        $ret .= $this->start('div', array('class' => 'HTMLPurifier_Printer'));
+        $ret .= $this->start('table');
+        
+        $ret .= $this->element('caption', 'Properties ($info)');
+        
+        $ret .= $this->start('thead');
+        $ret .= $this->start('tr');
+        $ret .= $this->element('th', 'Property', array('class' => 'heavy'));
+        $ret .= $this->element('th', 'Definition', array('class' => 'heavy', 'style' => 'width:auto;'));
+        $ret .= $this->end('tr');
+        $ret .= $this->end('thead');
+        
+        ksort($this->def->info);
+        foreach ($this->def->info as $property => $obj) {
+            $name = $this->getClass($obj, 'AttrDef_');
+            $ret .= $this->row($property, $name);
+        }
+        
+        $ret .= $this->end('table');
+        $ret .= $this->end('div');
+        
+        return $ret;
+    }
+    
+}
+
+?>

library/HTMLPurifier/Printer/HTMLDefinition.php

@@ -0,0 +1,206 @@
+<?php
+
+require_once 'HTMLPurifier/Printer.php';
+
+class HTMLPurifier_Printer_HTMLDefinition extends HTMLPurifier_Printer
+{
+    
+    /**
+     * Instance of HTMLPurifier_HTMLDefinition, for easy access
+     */
+    var $def;
+    
+    function render($config) {
+        $ret = '';
+        $this->config =& $config;
+        $this->def = $config->getHTMLDefinition();
+        $def =& $this->def;
+        
+        $ret .= $this->start('div', array('class' => 'HTMLPurifier_Printer'));
+        $ret .= $this->start('table');
+        $ret .= $this->element('caption', 'Environment');
+        
+        $ret .= $this->row('Parent of fragment', $def->info_parent);
+        $ret .= $this->row('Strict mode', $def->strict);
+        if ($def->strict) $ret .= $this->row('Block wrap name', $def->info_block_wrapper);
+        
+        $ret .= $this->start('tr');
+            $ret .= $this->element('th', 'Global attributes');
+            $ret .= $this->element('td', $this->listifyAttr($def->info_global_attr),0,0);
+        $ret .= $this->end('tr');
+        
+        $ret .= $this->renderChildren($def->info_parent_def->child);
+        
+        $ret .= $this->start('tr');
+            $ret .= $this->element('th', 'Tag transforms');
+            $list = array();
+            foreach ($def->info_tag_transform as $old => $new) {
+                $new = $this->getClass($new, 'TagTransform_');
+                $list[] = "<$old> with $new";
+            }
+            $ret .= $this->element('td', $this->listify($list));
+        $ret .= $this->end('tr');
+        
+        $ret .= $this->start('tr');
+            $ret .= $this->element('th', 'Pre-AttrTransform');
+            $ret .= $this->element('td', $this->listifyObjectList($def->info_attr_transform_pre));
+        $ret .= $this->end('tr');
+        
+        $ret .= $this->start('tr');
+            $ret .= $this->element('th', 'Post-AttrTransform');
+            $ret .= $this->element('td', $this->listifyObjectList($def->info_attr_transform_post));
+        $ret .= $this->end('tr');
+        
+        $ret .= $this->end('table');
+        
+        
+        $ret .= $this->renderInfo();
+        
+        
+        $ret .= $this->end('div');
+        
+        return $ret;
+    }
+    
+    /**
+     * Renders the Elements ($info) table
+     */
+    function renderInfo() {
+        $ret = '';
+        $ret .= $this->start('table');
+        $ret .= $this->element('caption', 'Elements ($info)');
+        ksort($this->def->info);
+        $ret .= $this->start('tr');
+        $ret .= $this->element('th', 'Allowed tags', array('colspan' => 2, 'class' => 'heavy'));
+        $ret .= $this->end('tr');
+        $ret .= $this->start('tr');
+        $ret .= $this->element('td', $this->listifyTagLookup($this->def->info), array('colspan' => 2));
+        $ret .= $this->end('tr');
+        foreach ($this->def->info as $name => $def) {
+            $ret .= $this->start('tr');
+                $ret .= $this->element('th', "<$name>", array('class'=>'heavy', 'colspan' => 2));
+            $ret .= $this->end('tr');
+            $ret .= $this->start('tr');
+                $ret .= $this->element('th', 'Type');
+                $ret .= $this->element('td', ucfirst($def->type));
+            $ret .= $this->end('tr');
+            if (!empty($def->excludes)) {
+                $ret .= $this->start('tr');
+                    $ret .= $this->element('th', 'Excludes');
+                    $ret .= $this->element('td', $this->listifyTagLookup($def->excludes));
+                $ret .= $this->end('tr');
+            }
+            if (!empty($def->attr_transform_pre)) {
+                $ret .= $this->start('tr');
+                    $ret .= $this->element('th', 'Pre-AttrTransform');
+                    $ret .= $this->element('td', $this->listifyObjectList($def->attr_transform_pre));
+                $ret .= $this->end('tr');
+            }
+            if (!empty($def->attr_transform_post)) {
+                $ret .= $this->start('tr');
+                    $ret .= $this->element('th', 'Post-AttrTransform');
+                    $ret .= $this->element('td', $this->listifyObjectList($def->attr_transform_post));
+                $ret .= $this->end('tr');
+            }
+            if (!empty($def->auto_close)) {
+                $ret .= $this->start('tr');
+                    $ret .= $this->element('th', 'Auto closed by');
+                    $ret .= $this->element('td', $this->listifyTagLookup($def->auto_close));
+                $ret .= $this->end('tr');
+            }
+            $ret .= $this->start('tr');
+                $ret .= $this->element('th', 'Allowed attributes');
+                $ret .= $this->element('td',$this->listifyAttr($def->attr),0,0);
+            $ret .= $this->end('tr');
+            
+            $ret .= $this->renderChildren($def->child);
+        }
+        $ret .= $this->end('table');
+        return $ret;
+    }
+    
+    /** 
+     * Renders a row describing the allowed children of an element
+     * @param $def HTMLPurifier_ChildDef of pertinent element
+     */
+    function renderChildren($def) {
+        $context = new HTMLPurifier_Context();
+        $ret = '';
+        $ret .= $this->start('tr');
+            $elements = array();
+            $attr = array();
+            if (isset($def->elements)) {
+                if ($def->type == 'strictblockquote') $def->validateChildren(array(), $this->config, $context);
+                $elements = $def->elements;
+            } elseif ($def->type == 'chameleon') {
+                $attr['rowspan'] = 2;
+            } elseif ($def->type == 'empty') {
+                $elements = array();
+            } elseif ($def->type == 'table') {
+                $elements = array('col', 'caption', 'colgroup', 'thead',
+                    'tfoot', 'tbody', 'tr');
+            }
+            $ret .= $this->element('th', 'Allowed children', $attr);
+            
+            if ($def->type == 'chameleon') {
+                
+                $ret .= $this->element('td',
+                    '<em>Block</em>: ' .
+                    $this->escape($this->listifyTagLookup($def->block->elements)),0,0);
+                $ret .= $this->end('tr');
+                $ret .= $this->start('tr');
+                $ret .= $this->element('td',
+                    '<em>Inline</em>: ' .
+                    $this->escape($this->listifyTagLookup($def->inline->elements)),0,0);
+                
+            } else {
+                $ret .= $this->element('td',
+                    '<em>'.ucfirst($def->type).'</em>: ' .
+                    $this->escape($this->listifyTagLookup($elements)),0,0);
+            }
+        $ret .= $this->end('tr');
+        return $ret;
+    }
+    
+    /** 
+     * Listifies a tag lookup table.
+     * @param $array Tag lookup array in form of array('tagname' => true)
+     */
+    function listifyTagLookup($array) {
+        $list = array();
+        foreach ($array as $name => $discard) {
+            if ($name !== '#PCDATA' && !isset($this->def->info[$name])) continue;
+            $list[] = $name;
+        }
+        return $this->listify($list);
+    }
+    
+    /**
+     * Listifies a list of objects by retrieving class names and internal state
+     * @param $array List of objects
+     * @todo Also add information about internal state
+     */
+    function listifyObjectList($array) {
+        $list = array();
+        foreach ($array as $discard => $obj) {
+            $list[] = $this->getClass($obj, 'AttrTransform_');
+        }
+        return $this->listify($list);
+    }
+    
+    /**
+     * Listifies a hash of attributes to AttrDef classes
+     * @param $array Array hash in form of array('attrname' => HTMLPurifier_AttrDef)
+     */
+    function listifyAttr($array) {
+        $list = array();
+        foreach ($array as $name => $obj) {
+            if ($obj === false) continue;
+            $list[] = "$name&nbsp;=&nbsp;<i>" . $this->getClass($obj, 'AttrDef_') . '</i>';
+        }
+        return $this->listify($list);
+    }
+    
+}
+
+?>

library/HTMLPurifier/Strategy.php

@@ -8,7 +8,7 @@
  * features, such as custom tags, custom parsing of text, etc.
  */
 
-HTMLPurifier_ConfigDef::define(
+HTMLPurifier_ConfigSchema::define(
     'Core', 'EscapeInvalidTags', false, 'bool',
     'When true, invalid tags will be written back to the document as plain '.
     'text.  Otherwise, they are silently dropped.'
@@ -24,7 +24,7 @@ class HTMLPurifier_Strategy
      * @param $config Configuration options
      * @returns Processed array of token objects.
      */
-    function execute($tokens, $config = null) {
+    function execute($tokens, $config, &$context) {
         trigger_error('Cannot call abstract function', E_USER_ERROR);
     }