From 72f1984229a29b6ee5801d9d97c3d07aed254f34 Mon Sep 17 00:00:00 2001
From: "Edward Z. Yang" <edwardzyang@thewritingpot.com>
Date: Mon, 12 Mar 2007 03:53:09 +0000
Subject: [PATCH] Add notes on "mode" to advanced API.

git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@801 48356398-32a2-884e-a903-53898d9a118a
---
 docs/dev-advanced-api.html | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/docs/dev-advanced-api.html b/docs/dev-advanced-api.html
index 695c49c4..56dbeb04 100644
--- a/docs/dev-advanced-api.html
+++ b/docs/dev-advanced-api.html
@@ -27,7 +27,8 @@ filtersets: therefore, users must be able to define their own sets of
     <dd><ul>
         <li>Doctype</li>
         <li>Filtersets: Rich / Plain / Full ...</li>
-        <li>Collections: Safe / Unsafe / Leniency(?) / Corrections(?) [advanced]</li>
+        <li>Mode: Lenient / Correctional</li>
+        <li>Collections (?): Safe / Unsafe</li>
         <li>Modules / Tags / Attributes</li>
     </ul></dd>
     <dt>Customize</dt>
@@ -88,6 +89,31 @@ other users to use.</p>
 
 <pre>$config->set('HTML', 'Filterset', 'Rich');</pre>
 
+<h3>Selecting Mode</h3>
+
+<p>Within filtersets, there are various <strong>modes</strong> of operation.
+These indicate variant behaviors that, while not strictly changing the
+allowed set of elements and attributes, will definitely affect the output.
+Currently, we have two modes, which may be used together:</p>
+
+<dl>
+    <dt>Lenient</dt>
+    <dd>Deprecated elements and attributes will be transformed into
+        standards-compliant alternatives when explicitly disallowed. For
+        example, in the XHTML 1.0 Strict doctype, a <code>center</code>
+        tag would be turned into a <code>div</code> with the CSS property
+        <code>text-align:center;</code>, but in XHTML 1.0 Transitional
+        the tag would be preserved. This mode is on by default.</dd>
+    <dt>Correctional</dt>
+    <dd>Deprecated elements and attributes will be transformed into
+        standards-compliant alternatives whenever possible. Referring
+        back to the previous example, the <code>center</code> tag would
+        be transformed in both cases. However, tags without a
+        reasonable standards-compliant alternative will be preserved
+        in their form. This mode is on by default. It may have
+        various levels of operation.</dd>
+</dl>
+
 <h3>Selecting Modules / Tags / Attributes</h3>
 
 <p>If this cookie cutter approach doesn't appeal to a user, they may