[1.7.0] Add documentation for the Tidy functionality

- Make specifying the child property for ElementDef unnecessary when overloading content_model or content_model_type - Add necessary includes to Tidy module files - Move div@align fix to Tidy_Proprietary - Future proof attrTransform.php by setting doctype to strict git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@1071 48356398-32a2-884e-a903-53898d9a118a
2024-09-18 18:25:18 +00:00 · 2007-05-20 02:12:01 +00:00 · 2007-05-20 02:12:01 +00:00 · 086dc9177b
commit 086dc9177b
parent 4d38c02932
10 changed files with 290 additions and 9 deletions
--- a/docs/enduser-tidy.html
+++ b/docs/enduser-tidy.html
@ -0,0 +1,230 @@
+<?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="Tutorial for tweaking HTML Purifier's Tidy-like behavior." />
+<link rel="stylesheet" type="text/css" href="style.css" />
+
+<title>Tidy - HTML Purifier</title>
+
+</head><body>
+
+<h1>Tidy</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://htmlpurifier.org/">HTML Purifier</a> End-User Documentation</div>
+
+<p>You've probably heard of HTML Tidy, Dave Raggett's little piece
+of software that cleans up poorly written HTML.  Let me say it straight
+out:</p>
+
+<p class="emphasis">This ain't HTML Tidy!</p>
+
+<p>Rather, Tidy stands for a cool set of Tidy-inspired in HTML Purifier
+that allows users to submit deprecated elements and attributes and get
+valid strict markup back. For example:</p>
+
+<pre>&lt;center&gt;Centered&lt;/center&gt;</pre>
+
+<p>...becomes:</p>
+
+<pre>&lt;div style=&quot;text-align:center;&quot;&gt;Centered&lt;/div&gt;</pre>
+
+<p>...when this particular fix is run on the HTML. This tutorial will give
+you down the lowdown of what exactly HTML Purifier will do when Tidy
+is on, and how to fine tune this behavior. Once again, <strong>you do
+not need Tidy installed on your PHP to use these features!</strong></p>
+
+<h2>What does it do?</h2>
+
+<p>Tidy will do several things to your HTML:</p>
+
+<ul>
+    <li>Convert deprecated elements and attributes to standards-compliant
+        alternatives</li>
+    <li>Enforce XHTML compatibility guidelines and other best practices</li>
+    <li>Preserve data that would normally be removed as per W3C</li>
+</ul>
+
+<h2>What are levels?</h2>
+
+<p>Levels describe how aggressive the Tidy module should be when 
+cleaning up HTML. There are four levels to pick: none, light, medium
+and heavy. Each of these levels has a well-defined set of behavior
+associated with it, although it may change depending on your doctype.</p>
+
+<dl>
+    <dt>light</dt>
+    <dd>This is the <strong>lenient</strong> level. If a tag or attribute
+        is about to be removed because it isn't supported by the
+        doctype, Tidy will step in and change into an alternative that
+        is supported.</dd>
+    <dt>medium</dt>
+    <dd>This is the <strong>correctional</strong> level. At this level,
+        all the functions of light are performed, as well as some extra,
+        non-essential best practices enforcement. Changes made on this
+        level are very benign and are unlikely to cause problems.</dd>
+    <dt>heavy</dt>
+    <dd>This is the <strong>aggressive</strong> level. If a tag or
+        attribute is deprecated, it will be converted into a non-deprecated
+        version, no ifs ands or buts.</dd>
+</dl>
+
+<p>By default, Tidy operates on the <strong>medium</strong> level. You can
+change the level of cleaning by setting the %HTML.TidyLevel configuration
+directive:</p>
+
+<pre>$config->set('HTML', 'TidyLevel', 'heavy'); // burn baby burn!</pre>
+
+<h2>Is the light level really light?</h2>
+
+<p>It depends on what doctype you're using. If your documents are HTML
+4.01 <em>Transitional</em>, HTML Purifier will be lazy
+and won't clean up your <code>center</code>
+or <code>font</code> tags. But if you're using HTML 4.01 <em>Strict</em>,
+HTML Purifier has no choice: it has to convert them, or they will
+be nuked out of existence. So while light on Transitional will result
+in little to no changes, light on Strict will still result in quite
+a lot of fixes.</p>
+
+<p>This is different behavior from 1.6 or before, where deprecated
+tags in transitional documents would
+always be cleaned up regardless. This is also better behavior.</p>
+
+<h2>My pages look different!</h2>
+
+<p>HTML Purifier is tasked with converting deprecated tags and
+attributes to standards-compliant alternatives, which usually
+need copious amounts of CSS. It's also not foolproof: sometimes
+things do get lost in the translation. This is why when HTML Purifier
+can get away with not doing cleaning, it won't; this is why
+the default value is <strong>medium</strong> and not heavy.</p>
+
+<p>Fortunately, only a few attributes have problems with the switch
+over. They are described below:</p>
+
+<table class="table">
+    <thead><tr>
+        <th>Element@Attr</th>
+        <th>Changes</th>
+    </tr></thead>
+    <tbody>
+        <tr>
+            <td>caption@align</td>
+            <td>Firefox supports stuffing the caption on the
+                left and right side of the table, a feature that
+                Internet Explorer, understandably, does not have.
+                When align equals right or left, the text will simply
+                be aligned on the left or right side.</td>
+        </tr>
+        <tr>
+            <td>img@align</td>
+            <td>The implementation for align bottom is good, but not
+            perfect. There are a few pixel differences.</td>
+        </tr>
+        <tr>
+            <td>br@clear</td>
+            <td>Clear both gets a little wonky in Internet Explorer. Haven't
+                really been able to figure out why.</td>
+        </tr>
+        <tr>
+            <td>hr@noshade</td>
+            <td>All browsers implement this slightly differently: we've
+                chosen to make noshade horizontal rules gray.</td>
+        </tr>
+    </tbody>
+</table>
+
+<p>There are a few more minor, although irritating, bugs.
+Some older browsers support deprecated attributes,
+but not CSS. Transformed elements and attributes will look unstyled
+to said browsers. Also, CSS precedence is slightly different for
+inline styles versus presentational markup. In increasing precedence:</p>
+
+<ol>
+    <li>Presentational attributes</li>
+    <li>External style sheets</li>
+    <li>Inline styling</li>
+</ol>
+
+<p>This means that styling that may have been masked by external CSS
+declarations will start showing up (a good thing, perhaps). Finally,
+if you've turned off the style attribute, almost all of
+these transformations will not work. Sorry mates.</p>
+
+<p>You can review the rendering before and after of these transformations
+by consulting the <a
+href="http://htmlpurifier.org/live/smoketests/attrTransform.php">attrTransform.php
+smoketest</a>.</p>
+
+<h2>I like the general idea, but the specifics bug me!</h2>
+
+<p>So you want HTML Purifier to clean up your HTML, but you're not
+so happy about the br@clear implementation. That's perfectly fine!
+HTML Purifier will make accomodations:</p>
+
+<pre>$config->set('HTML', 'Doctype', 'XHTML 1.0 Transitional');
+$config->set('HTML', 'TidyLevel', 'heavy'); // all changes, minus...
+<strong>$config->set('HTML', 'TidyRemove', 'br@clear');</strong></pre>
+
+<p>That third line does the magic, removing the br@clear fix
+from the module, ensuring that <code>&lt;br clear="both" /&gt;</code>
+will pass through unharmed. The reverse is possible too:</p>
+
+<pre>$config->set('HTML', 'Doctype', 'XHTML 1.0 Transitional');
+$config->set('HTML', 'TidyLevel', 'none'); // no changes, plus...
+<strong>$config->set('HTML', 'TidyAdd', 'p@align');</strong></pre>
+
+<p>In this case, all transformations are shut off, except for the p@align
+one, which you found handy.</p>
+
+<p>To find out what the names of fixes you want to turn on or off are,
+you'll have to consult the source code, specifically the files in
+<code>HTMLPurifier/HTMLModule/Tidy/</code>. There is, however, a
+general syntax:</p>
+
+<table class="table">
+    <thead>
+        <tr>
+            <th>Name</th>
+            <th>Example</th>
+            <th>Interpretation</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>element</td>
+            <td>font</td>
+            <td>Tag transform for <em>element</em></td>
+        </tr>
+        <tr>
+            <td>element@attr</td>
+            <td>br@clear</td>
+            <td>Attribute transform for <em>attr</em> on <em>element</em></td>
+        </tr>
+        <tr>
+            <td>@attr</td>
+            <td>@lang</td>
+            <td>Global attribute transform for <em>attr</em></td>
+        </tr>
+        <tr>
+            <td>e#content_model_type</td>
+            <td>blockquote#content_model_type</td>
+            <td>Change of child processing implementation for <em>e</em></td>
+        </tr>
+    </tbody>
+</table>
+
+<h2>So... what's the lowdown?</h2>
+
+<p>The lowdown is, quite frankly, HTML Purifier's default settings are
+probably good enough. The next step is to bump the level up to heavy,
+and if that still doesn't satisfy your appetite, do some fine tuning.
+Other than that, don't worry about it: this all works silently and
+effectively in the background.</p>
+
+<div id="version">$Id: $</div>
+
+</body></html>
--- a/docs/index.html
+++ b/docs/index.html
@ -34,6 +34,9 @@ information for casual developers using HTML Purifier.</p>
 <dt><a href="enduser-utf8.html">UTF-8: The Secret of Character Encoding</a></dt>
 <dd>Describes the rationale for using UTF-8, the ramifications otherwise, and how to make the switch.</dd>

+<dt><a href="enduser-tidy.html">Tidy</a></dt>
+<dd>Tutorial for tweaking HTML Purifier's Tidy-like behavior.</dd>
+
 </dl>

 <h2>Development</h2>
--- a/docs/style.css
+++ b/docs/style.css
@ -25,6 +25,7 @@ h4 {font-family:sans-serif; font-size:0.9em; font-weight:bold; }
 .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;}
+.emphasis {font-weight:bold; text-align:center; font-size:1.3em;}

 /* A regular table */
 .table {border-collapse:collapse; border-bottom:2px solid #888; margin-left:2em; }
--- a/library/HTMLPurifier/ElementDef.php
+++ b/library/HTMLPurifier/ElementDef.php
@ -141,9 +141,15 @@ class HTMLPurifier_ElementDef
        $this->_mergeAssocArray($this->auto_close, $def->auto_close);
        $this->_mergeAssocArray($this->excludes, $def->excludes);
        
+        if(!empty($def->content_model)) {
+            $this->content_model .= ' | ' . $def->content_model;
+            $this->child = false;
+        }
+        if(!empty($def->content_model_type)) {
+            $this->content_model_type = $def->content_model_type;
+            $this->child = false;
+        }
        if(!is_null($def->child)) $this->child = $def->child;
-        if(!empty($def->content_model)) $this->content_model .= ' | ' . $def->content_model;
-        if(!empty($def->content_model_type)) $this->content_model_type = $def->content_model_type;
        if(!is_null($def->descendants_are_inline)) $this->descendants_are_inline = $def->descendants_are_inline;
        if(!is_null($def->safe)) $this->safe = $def->safe;
        
--- a/library/HTMLPurifier/HTMLModule/Tidy/Proprietary.php
+++ b/library/HTMLPurifier/HTMLModule/Tidy/Proprietary.php
@ -0,0 +1,27 @@
+<?php
+
+require_once 'HTMLPurifier/HTMLModule/Tidy.php';
+
+class HTMLPurifier_HTMLModule_Tidy_Proprietary extends
+      HTMLPurifier_HTMLModule_Tidy
+{
+    
+    var $name = 'Tidy_Proprietary';
+    var $defaultLevel = 'light';
+    
+    function makeFixes() {
+        $r = array();
+        
+        // {{{ // duplicated from XHTMLAndHTML4: not sure how to factor out
+            $align_lookup = array();
+            $align_values = array('left', 'right', 'center', 'justify');
+            foreach ($align_values as $v) $align_lookup[$v] = "text-align:$v;";
+        // }}}
+        $r['div@align'] = new HTMLPurifier_AttrTransform_EnumToCSS('align', $align_lookup);
+        
+        return $r;
+    }
+    
+}
+
+?>
--- a/library/HTMLPurifier/HTMLModule/Tidy/XHTML.php
+++ b/library/HTMLPurifier/HTMLModule/Tidy/XHTML.php
@ -1,6 +1,7 @@
 <?php

 require_once 'HTMLPurifier/HTMLModule/Tidy.php';
+require_once 'HTMLPurifier/AttrTransform/Lang.php';

 class HTMLPurifier_HTMLModule_Tidy_XHTML extends
      HTMLPurifier_HTMLModule_Tidy
--- a/library/HTMLPurifier/HTMLModule/Tidy/XHTMLAndHTML4.php
+++ b/library/HTMLPurifier/HTMLModule/Tidy/XHTMLAndHTML4.php
@ -2,6 +2,18 @@

 require_once 'HTMLPurifier/HTMLModule/Tidy.php';

+require_once 'HTMLPurifier/TagTransform/Simple.php';
+require_once 'HTMLPurifier/TagTransform/Center.php';
+require_once 'HTMLPurifier/TagTransform/Font.php';
+
+require_once 'HTMLPurifier/AttrTransform/BgColor.php';
+require_once 'HTMLPurifier/AttrTransform/BoolToCSS.php';
+require_once 'HTMLPurifier/AttrTransform/Border.php';
+require_once 'HTMLPurifier/AttrTransform/Name.php';
+require_once 'HTMLPurifier/AttrTransform/Length.php';
+require_once 'HTMLPurifier/AttrTransform/ImgSpace.php';
+require_once 'HTMLPurifier/AttrTransform/EnumToCSS.php';
+
 class HTMLPurifier_HTMLModule_Tidy_XHTMLAndHTML4 extends
      HTMLPurifier_HTMLModule_Tidy
 {
@ -74,7 +86,6 @@ class HTMLPurifier_HTMLModule_Tidy_XHTMLAndHTML4 extends
        $r['h5@align'] =
        $r['h6@align'] =
        $r['p@align']  =
-        $r['div@align'] =
            new HTMLPurifier_AttrTransform_EnumToCSS('align', $align_lookup);
        
        // @bgcolor for table, tr, td, th ---------------------------------
--- a/library/HTMLPurifier/HTMLModule/Tidy/XHTMLStrict.php
+++ b/library/HTMLPurifier/HTMLModule/Tidy/XHTMLStrict.php
@ -1,6 +1,7 @@
 <?php

 require_once 'HTMLPurifier/HTMLModule/Tidy.php';
+require_once 'HTMLPurifier/ChildDef/StrictBlockquote.php';

 class HTMLPurifier_HTMLModule_Tidy_XHTMLStrict extends
      HTMLPurifier_HTMLModule_Tidy
@ -11,7 +12,6 @@ class HTMLPurifier_HTMLModule_Tidy_XHTMLStrict extends
    
    function makeFixes() {
        $r = array();
-        $r['blockquote#child'] = false;
        $r['blockquote#content_model_type'] = 'strictblockquote';
        return $r;
    }
--- a/library/HTMLPurifier/HTMLModuleManager.php
+++ b/library/HTMLPurifier/HTMLModuleManager.php
@ -34,6 +34,7 @@ require_once 'HTMLPurifier/HTMLModule/Tidy.php';
 require_once 'HTMLPurifier/HTMLModule/Tidy/XHTMLAndHTML4.php';
 require_once 'HTMLPurifier/HTMLModule/Tidy/XHTML.php';
 require_once 'HTMLPurifier/HTMLModule/Tidy/XHTMLStrict.php';
+require_once 'HTMLPurifier/HTMLModule/Tidy/Proprietary.php';

 HTMLPurifier_ConfigSchema::define(
    'HTML', 'Doctype', null, 'string/null',
@ -123,31 +124,31 @@ class HTMLPurifier_HTMLModuleManager
        $this->doctypes->register(
            'HTML 4.01 Transitional', false,
            array_merge($common, $transitional, $non_xml),
-            array('Tidy_Transitional')
+            array('Tidy_Transitional', 'Tidy_Proprietary')
        );
        
        $this->doctypes->register(
            'HTML 4.01 Strict', false,
            array_merge($common, $non_xml),
-            array('Tidy_Strict')
+            array('Tidy_Strict', 'Tidy_Proprietary')
        );
        
        $this->doctypes->register(
            'XHTML 1.0 Transitional', true,
            array_merge($common, $transitional, $xml, $non_xml),
-            array('Tidy_Transitional', 'Tidy_XHTML')
+            array('Tidy_Transitional', 'Tidy_XHTML', 'Tidy_Proprietary')
        );
        
        $this->doctypes->register(
            'XHTML 1.0 Strict', true,
            array_merge($common, $xml, $non_xml),
-            array('Tidy_Strict', 'Tidy_XHTML', 'Tidy_XHTMLStrict')
+            array('Tidy_Strict', 'Tidy_XHTML', 'Tidy_XHTMLStrict', 'Tidy_Proprietary')
        );
        
        $this->doctypes->register(
            'XHTML 1.1', true,
            array_merge($common, $xml),
-            array('Tidy_Strict', 'Tidy_XHTML') // Tidy_XHTML1_1
+            array('Tidy_Strict', 'Tidy_XHTML', 'Tidy_Proprietary') // Tidy_XHTML1_1
        );
        
    }
--- a/smoketests/attrTransform.php
+++ b/smoketests/attrTransform.php
@ -42,6 +42,7 @@ $xml = simplexml_load_file('attrTransform.xml');

 // attr transform enabled HTML Purifier
 $config = HTMLPurifier_Config::createDefault();
+$config->set('HTML', 'Doctype', 'XHTML 1.0 Strict');
 $purifier = new HTMLPurifier($config);

 $title = isset($_GET['title']) ? $_GET['title'] : true;