diff --git a/NEWS b/NEWS index 78ffcd7b..eb11193b 100644 --- a/NEWS +++ b/NEWS @@ -85,6 +85,7 @@ NEWS ( CHANGELOG and HISTORY ) HTMLPurifier . Reordered script calls in maintenance/flush.php . Command line scripts now honor exit codes . When --flush fails in unit testers, abort tests and print message +. Improved documentation in docs/dev-flush.html about the maintenance scripts 3.0.0, released 2008-01-06 # HTML Purifier is PHP 5 only! The 2.1.x branch will be maintained diff --git a/TODO b/TODO index 6aa5beb2..e2c771a7 100644 --- a/TODO +++ b/TODO @@ -22,7 +22,6 @@ DOCUMENTATION - Document new ConfigSchema setup and format; dev-includes.txt is a base but we need it in HTML - Update French translation of README - - Document which scripts need to be called when a change is made IMPORTANT FEATURES - Get everything into configuration objects (filters, I'm looking at you) diff --git a/docs/dev-flush.html b/docs/dev-flush.html new file mode 100644 index 00000000..6546ffa3 --- /dev/null +++ b/docs/dev-flush.html @@ -0,0 +1,67 @@ + + + + + + + + Flushing the Purifier - HTML Purifier + + + +

Flushing the Purifier

+ +
Filed under Development
+
Return to the index.
+
HTML Purifier End-User Documentation
+ +

+ If you've been poking around the various folders in HTML Purifier, + you may have noticed the maintenance directory. Almost + all of these scripts are devoted to flushing out the various caches + HTML Purifier uses. Normal users don't have to worry about this: + regular library usage is transparent. However, when doing development + work on HTML Purifier, you may find you have to flush one of the + caches. +

+ +

+ As a general rule of thumb, run flush.php whenever you make + any major changes, or when tests start mysteriously failing. + In more detail, run this script if: +

+ + + +

+ You can check out the corresponding scripts for more information on what they + do. +

+ +
$Id$
+ + diff --git a/docs/index.html b/docs/index.html index b50a7e65..e70c053f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -60,6 +60,9 @@ conventions.

Optimization
Discusses possible methods of optimizing HTML Purifier.
+
Flushing the Purifier
+
Discusses when to flush HTML Purifier's various caches.
+
Advanced API
Functional specification for HTML Purifier's advanced API for defining custom filtering behavior.
diff --git a/maintenance/flush-definition-cache.php b/maintenance/flush-definition-cache.php index d0ebaba5..558ff3af 100755 --- a/maintenance/flush-definition-cache.php +++ b/maintenance/flush-definition-cache.php @@ -6,7 +6,12 @@ require_once 'common.php'; assertCli(); /** - * Flushes the default HTMLDefinition serial cache + * @file + * Flushes the definition serial cache. This file should be + * called if changes to any subclasses of HTMLPurifier_Definition + * or related classes (such as HTMLPurifier_HTMLModule) are made. This + * may also be necessary if you've modified a customized version. + * * @param Accepts one argument, cache type to flush; otherwise flushes all * the caches. */ diff --git a/maintenance/generate-entity-file.php b/maintenance/generate-entity-file.php index 05244dd6..81872887 100755 --- a/maintenance/generate-entity-file.php +++ b/maintenance/generate-entity-file.php @@ -8,7 +8,9 @@ assertCli(); /** * @file * Parses *.ent files into an entity lookup table, and then serializes and - * writes the whole kaboodle to a file. The resulting file should be versioned. + * writes the whole kaboodle to a file. The resulting file is cached so + * that this script does not need to be run. This script should rarely, + * if ever, be run, since HTML's entities are fairly immutable. */ // here's where the entity files are located, assuming working directory diff --git a/maintenance/generate-includes.php b/maintenance/generate-includes.php index d8295bd0..a0249cf1 100644 --- a/maintenance/generate-includes.php +++ b/maintenance/generate-includes.php @@ -10,6 +10,8 @@ assertCli(); /** * @file * Generates an include stub for users who do not want to use the autoloader. + * When new files are added to HTML Purifier's main codebase, this file should + * be called. */ chdir(dirname(__FILE__) . '/../library/'); diff --git a/maintenance/generate-ph5p-patch.php b/maintenance/generate-ph5p-patch.php index ecd9fa3f..f30ac3ad 100644 --- a/maintenance/generate-ph5p-patch.php +++ b/maintenance/generate-ph5p-patch.php @@ -1,5 +1,12 @@