[3.1.0] Improve maintenance script documentation

git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@1644 48356398-32a2-884e-a903-53898d9a118a
2024-12-22 08:21:52 +00:00 · 2008-04-03 22:39:50 +00:00 · 2008-04-03 22:39:50 +00:00 · 9676e8580e
commit 9676e8580e
parent dac98cdb06
10 changed files with 97 additions and 5 deletions
--- a/1
+++ b/1
@ -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
--- a/1
+++ b/1
@ -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)
--- a/docs/dev-flush.html
+++ b/docs/dev-flush.html
@ -0,0 +1,67 @@
+<?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 when to flush HTML Purifier's various caches." />
+    <link rel="stylesheet" type="text/css" href="./style.css" />
+    <title>Flushing the Purifier - HTML Purifier</title>
+</head>
+<body>
+
+<h1>Flushing the Purifier</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>
+    If you've been poking around the various folders in HTML Purifier,
+    you may have noticed the <code>maintenance</code> 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.
+</p>
+
+<p>
+    As a general rule of thumb, run <code>flush.php</code> whenever you make
+    any <em>major</em> changes, or when tests start mysteriously failing.
+    In more detail, run this script if:
+</p>
+
+<ul>
+    <li>
+        You added new source files to HTML Purifier's main library.
+        (see <code>generate-includes.php</code>)
+    </li>
+    <li>
+        You modified the configuration schema (see
+        <code>generate-schema-cache.php</code>). This usually means
+        adding or modifying files in <code>HTMLPurifier/ConfigSchema/schema/</code>,
+        although in rare cases modifying <code>HTMLPurifier/ConfigSchema.php</code>
+        will also require this.
+    </li>
+    <li>
+        You modified a Definition, or its subsystems. The most usual candidate
+        is <code>HTMLPurifier/HTMLDefinition.php</code>, which also encompasses
+        the files in <code>HTMLPurifier/HTMLModule/</code> as well as if you've
+        <a href="enduser-customize.html">customizing definitions</a> without
+        the cache disabled. (see <code>flush-generation-cache.php</code>)
+    </li>
+    <li>
+        You modified source files, and have been using the standalone
+        version from the full installation. (see <code>generate-standalone.php</code>)
+    </li>
+</ul>
+
+<p>
+    You can check out the corresponding scripts for more information on what they
+    do.
+</p>
+
+<div id="version">$Id$</div>
+
+</body></html>
--- a/docs/index.html
+++ b/docs/index.html
@ -60,6 +60,9 @@ conventions.</p>
 <dt><a href="dev-optimization.html">Optimization</a></dt>
 <dd>Discusses possible methods of optimizing HTML Purifier.</dd>

+<dt><a href="dev-flush.html">Flushing the Purifier</a></dt>
+<dd>Discusses when to flush HTML Purifier's various caches.</dd>
+
 <dt><a href="dev-advanced-api.html">Advanced API</a></dt>
 <dd>Functional specification for HTML Purifier's advanced API for defining
 custom filtering behavior.</dd>
--- 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.
 */
--- 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
--- 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/');
--- a/maintenance/generate-ph5p-patch.php
+++ b/maintenance/generate-ph5p-patch.php
@ -1,5 +1,12 @@
 <?php

+/**
+ * @file
+ * This file compares our version of PH5P with Jero's original version, and
+ * generates a patch of the differences. This script should be run whenever
+ * library/HTMLPurifier/Lexer/PH5P.php is modified.
+ */
+
 $orig = realpath(dirname(__FILE__) . '/PH5P.php');
 $new  = realpath(dirname(__FILE__) . '/../library/HTMLPurifier/Lexer/PH5P.php');
 $newt = dirname(__FILE__) . '/PH5P.new.php'; // temporary file
--- a/maintenance/generate-schema-cache.php
+++ b/maintenance/generate-schema-cache.php
@ -9,7 +9,11 @@ assertCli();
 /**
 * @file
 * Generates a schema cache file from the contents of
- * library/HTMLPurifier/ConfigSchema/schema.ser
+ * library/HTMLPurifier/ConfigSchema/schema.ser.
+ * 
+ * This should be run when new configuration options are added to
+ * HTML Purifier. A cached version is available via SVN so this does not
+ * normally have to be regenerated.
 */

 $target = '../library/HTMLPurifier/ConfigSchema/schema.ser';
--- a/maintenance/generate-standalone.php
+++ b/maintenance/generate-standalone.php
@ -6,8 +6,10 @@ require_once 'common.php';
 assertCli();

 /**
+ * @file
 * Compiles all of HTML Purifier's library files into one big file
- * named HTMLPurifier.standalone.php.
+ * named HTMLPurifier.standalone.php. This is usually called during the
+ * release process.
 */

 /**