Add docs and facilities for having separate directories of schemas.

Signed-off-by: Edward Z. Yang <edwardzyang@thewritingpot.com>

.gitignore

@@ -1,6 +1,7 @@
 tags
 conf/
 test-settings.php
+config-schema.php
 library/HTMLPurifier/DefinitionCache/Serializer/*/
 library/standalone/
 library/HTMLPurifier.standalone.php

NEWS

@@ -37,6 +37,9 @@ NEWS ( CHANGELOG and HISTORY )                                     HTMLPurifier
 ! Implement %Attr.AllowedClasses, which allows administrators to restrict
   classes users can use to a specified finite set of classes, and
   %Attr.ForbiddenClasses, which is the logical inverse.
+! You can now maintain your own configuration schema directories by
+  creating a config-schema.php file or passing an extra argument. Check
+  docs/dev-config-schema.html for more details.
 - Fix bug where URIDefinition would not get cleared if it's directives got
   changed.
 - Fix fatal error in HTMLPurifier_Encoder on certain platforms (probably NetBSD 5.0)

TODO

@@ -26,7 +26,6 @@ afraid to cast your vote for the next feature to be implemented!
 - Make it easy for people to cache their entire configuration (so that
   they have one script they run to change configuration, and then a stub
   loader to get that configuration)
- - Implement <area>
 
 FUTURE VERSIONS
 ---------------
@@ -35,6 +34,8 @@ FUTURE VERSIONS
  # Implement untrusted, dangerous elements/attributes
  # Implement IDREF support (harder than it seems, since you cannot have
    IDREFs to non-existent IDs)
+     - Implement <area> (client and server side image maps are blocking
+       on IDREF support)
  # Frameset XHTML 1.0 and HTML 4.01 doctypes
  - Figure out how to simultaneously set %CSS.Trusted and %HTML.Trusted (?)
 

configdoc/generate.php

@@ -18,22 +18,24 @@ TODO:
 if (version_compare(PHP_VERSION, '5.2', '<')) exit('PHP 5.2+ required.');
 error_reporting(E_ALL | E_STRICT);
 
-chdir(dirname(__FILE__));
-
 // load dual-libraries
-require_once '../extras/HTMLPurifierExtras.auto.php';
-require_once '../library/HTMLPurifier.auto.php';
+require_once dirname(__FILE__) . '/../extras/HTMLPurifierExtras.auto.php';
+require_once dirname(__FILE__) . '/../library/HTMLPurifier.auto.php';
 
 // setup HTML Purifier singleton
 HTMLPurifier::getInstance(array(
     'AutoFormat.PurifierLinkify' => true
 ));
 
-$interchange = HTMLPurifier_ConfigSchema_InterchangeBuilder::buildFromDirectory();
+$builder = new HTMLPurifier_ConfigSchema_InterchangeBuilder();
+$interchange = new HTMLPurifier_ConfigSchema_Interchange();
+$builder->buildDir($interchange);
+$loader = dirname(__FILE__) . '/../config-schema.php';
+if (file_exists($loader)) include $loader;
 $interchange->validate();
 
 $style = 'plain'; // use $_GET in the future, careful to validate!
-$configdoc_xml = 'configdoc.xml';
+$configdoc_xml = dirname(__FILE__) . '/configdoc.xml';
 
 $xml_builder = new HTMLPurifier_ConfigSchema_Builder_Xml();
 $xml_builder->openURI($configdoc_xml);
@@ -50,13 +52,13 @@ if (!$output) {
 }
 
 // write out
-file_put_contents("$style.html", $output);
+file_put_contents(dirname(__FILE__) . "/$style.html", $output);
 
 if (php_sapi_name() != 'cli') {
     // output (instant feedback if it's a browser)
     echo $output;
 } else {
-    echo 'Files generated successfully.';
+    echo "Files generated successfully.\n";
 }
 
 // vim: et sw=4 sts=4

docs/dev-config-schema.html

@@ -114,7 +114,7 @@ Test.Example</pre>
         </tr>
         <tr>
           <td>VALUE-ALIASES</td>
-          <td>'baz' => 'bar'</td>
+          <td>'baz' =&gt; 'bar'</td>
           <td><em>Optional</em>. Mapping of one value to another, and
           should be a comma separated list of keypair duples. This
           is only allowed string, istring, text and itext TYPEs.</td>
@@ -213,7 +213,7 @@ Test.Example</pre>
         </tr>
         <tr>
           <td>lookup</td>
-          <td>array('key' => true)</td>
+          <td>array('key' =&gt; true)</td>
           <td>Lookup array, used with <code>isset($var[$key])</code></td>
         </tr>
         <tr>
@@ -223,7 +223,7 @@ Test.Example</pre>
         </tr>
         <tr>
           <td>hash</td>
-          <td>array('key' => 'val')</td>
+          <td>array('key' =&gt; 'val')</td>
           <td>Associative array of keys to values</td>
         </tr>
         <tr>
@@ -267,6 +267,41 @@ Test.Example</pre>
       If you ever make changes to your configuration directives, you
       will need to run this script again.
     </p>
+    <h2>Adding in-house schema definitions</h2>
+
+    <p>
+      Placing stuff directly in HTML Purifier's source tree is generally not a
+      good idea, so HTML Purifier 4.0.0+ has some facilities in place to make your
+      life easier.
+    </p>
+
+    <p>
+      The first is to pass an extra parameter to <code>maintenance/generate-schema-cache.php</code>
+      with the location of your directory (relative or absolute path will do). For example,
+      if I'm storing my custom definitions in <em>/var/htmlpurifier/myschema</em>, run:
+      <code>php maintenance/generate-schema-cache.php /var/htmlpurifier/myschema</code>.
+    </p>
+
+    <p>
+      Alternatively, you can create a small loader PHP file in the HTML Purifier base
+      directory named <code>config-schema.php</code> (this is the same directory
+      you would place a <code>test-settings.php</code> file).  In this file, add
+      the following line for each directory you want to load:
+    </p>
+
+<pre>$builder-&gt;buildDir($interchange, '/var/htmlpurifier/myschema');</pre>
+
+    <p>You can even load a single file using:</p>
+
+<pre>$builder-&gt;buildFile($interchange, '/var/htmlpurifier/myschema/MyApp.Directive.txt');</pre>
+
+    <p>Storing custom definitions that you don't plan on sending back upstream in
+    a separate directory is <em>definitely</em> a good idea! Additionally, picking
+    a good namespace can go a long way to saving you grief if you want to use
+    someone else's change, but they picked the same name, or if HTML Purifier
+    decides to add support for a configuration directive that has the same name.</p>
+
+    <!-- TODO: how to name directives that rely on naming conventions -->
 
     <h2>Errors</h2>
 

docs/enduser-customize.html

@@ -18,12 +18,11 @@
 <div id="home"><a href="http://htmlpurifier.org/">HTML Purifier</a> End-User Documentation</div>
 
 <p>
-  You may have heard of the <a href="dev-advanced-api.html">Advanced API</a>.
-  If you're interested in reading dry prose and boring functional
-  specifications, feel free to click that link to get a no-nonsense overview
-  on the Advanced API. For the rest of us, there's this tutorial. By the time
-  you're finished reading this, you should have a pretty good idea on
-  how to implement custom tags and attributes that HTML Purifier may not have.
+  HTML Purifier has this quirk where if you try to allow certain elements or
+  attributes, HTML Purifier will tell you that it's not supported, and that
+  you should go to the forums to find out how to implement it. Well, this
+  document is how to implement elements and attributes which HTML Purifier
+  doesn't support out of the box.
 </p>
 
 <h2>Is it necessary?</h2>

library/HTMLPurifier/Config.php

@@ -216,6 +216,7 @@ class HTMLPurifier_Config
 
     /**
      * Retrieves all directives, organized by namespace
+     * @warning This is a pretty inefficient function, avoid if you can
      */
     public function getAll() {
         if (!$this->finalized) $this->autoFinalize();

library/HTMLPurifier/ConfigSchema/InterchangeBuilder.php

@@ -15,10 +15,15 @@ class HTMLPurifier_ConfigSchema_InterchangeBuilder
     public static function buildFromDirectory($dir = null) {
         $builder     = new HTMLPurifier_ConfigSchema_InterchangeBuilder();
         $interchange = new HTMLPurifier_ConfigSchema_Interchange();
+        return $builder->buildDir($interchange, $dir);
+    }
 
-        if (!$dir) $dir = HTMLPURIFIER_PREFIX . '/HTMLPurifier/ConfigSchema/schema/';
-        $info = parse_ini_file($dir . 'info.ini');
-        $interchange->name = $info['name'];
+    public function buildDir($interchange, $dir = null) {
+        if (!$dir) $dir = HTMLPURIFIER_PREFIX . '/HTMLPurifier/ConfigSchema/schema';
+        if (file_exists($dir . '/info.ini')) {
+            $info = parse_ini_file($dir . '/info.ini');
+            $interchange->name = $info['name'];
+        }
 
         $files = array();
         $dh = opendir($dir);
@@ -32,7 +37,7 @@ class HTMLPurifier_ConfigSchema_InterchangeBuilder
 
         sort($files);
         foreach ($files as $file) {
-            $builder->buildFile($interchange, $dir . $file);
+            $this->buildFile($interchange, $dir . '/' . $file);
         }
 
         return $interchange;

maintenance/common.php

@@ -17,6 +17,6 @@ function postfix_is($comp, $subject) {
 }
 
 // Load useful stuff like FSTools
-require_once '../extras/HTMLPurifierExtras.auto.php';
+require_once dirname(__FILE__) . '/../extras/HTMLPurifierExtras.auto.php';
 
 // vim: et sw=4 sts=4

maintenance/generate-schema-cache.php

@@ -1,9 +1,8 @@
 #!/usr/bin/php
 <?php
 
-chdir(dirname(__FILE__));
-require_once 'common.php';
-require_once '../library/HTMLPurifier.auto.php';
+require_once dirname(__FILE__) . '/common.php';
+require_once dirname(__FILE__) . '/../library/HTMLPurifier.auto.php';
 assertCli();
 
 /**
@@ -12,13 +11,28 @@ assertCli();
  * 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.
+ * HTML Purifier. A cached version is available via the repository
+ * so this does not normally have to be regenerated.
+ *
+ * If you have a directory containing custom configuration schema files,
+ * you can simple add a path to that directory as a parameter to
+ * this, and they will get included.
  */
 
-$target = '../library/HTMLPurifier/ConfigSchema/schema.ser';
+$target = dirname(__FILE__) . '/../library/HTMLPurifier/ConfigSchema/schema.ser';
+
+$builder = new HTMLPurifier_ConfigSchema_InterchangeBuilder();
+$interchange = new HTMLPurifier_ConfigSchema_Interchange();
+
+$builder->buildDir($interchange);
+
+$loader = dirname(__FILE__) . '/../config-schema.php';
+if (file_exists($loader)) include $loader;
+foreach ($_SERVER['argv'] as $i => $dir) {
+    if ($i === 0) continue;
+    $builder->buildDir($interchange, realpath($dir));
+}
 
-$interchange = HTMLPurifier_ConfigSchema_InterchangeBuilder::buildFromDirectory();
 $interchange->validate();
 
 $schema_builder = new HTMLPurifier_ConfigSchema_Builder_ConfigSchema();