- Finished documentation generation.

- Modified namespace definitions so that they cannot be redefined

git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@413 48356398-32a2-884e-a903-53898d9a118a

NEWS

@@ -5,6 +5,7 @@ NEWS ( CHANGELOG and HISTORY )                                     HTMLPurifier
 - Made URI validator more forgiving: will ignore leading and trailing
   quotes, apostrophes and less than or greater than signs.
 - Enforce alphanumeric namespace and directive names for configuration.
+- Directive documentation generation using XSLT
 
 1.0.2, unknown release date
 (bugfix release may be dropped if no bugs found)

TODO

@@ -6,7 +6,6 @@ Ongoing
  - Plugins for major CMSes (very tricky issue)
 
 1.1 release
- - Directive documentation generation
  - Rewrite table's child definition to be faster, smart, and regexp free
  - Allow HTML 4.01 output (cosmetic changes to the generator)
  - Formatters for plaintext

configdoc/generate.php

@@ -12,6 +12,7 @@ TODO:
 - multipage documentation
 - generate string XML file for types
 - determine how to multilingualize
+- factor out code into classes
 */
 
 
@@ -29,6 +30,23 @@ set_include_path('../library' . PATH_SEPARATOR . get_include_path());
 require_once 'HTMLPurifier.php';
 
 
+// ---------------------------------------------------------------------------
+// Setup convenience functions
+
+function appendHTMLDiv($document, $node, $html) {
+    global $purifier;
+    $html = $purifier->purify($html);
+    $dom_html = $document->createDocumentFragment();
+    $dom_html->appendXML($html);
+    
+    $dom_div = $document->createElement('div');
+    $dom_div->setAttribute('xmlns', 'http://www.w3.org/1999/xhtml');
+    $dom_div->appendChild($dom_html);
+    
+    $node->appendChild($dom_div);
+}
+
+
 // ---------------------------------------------------------------------------
 // Load copies of HTMLPurifier_ConfigDef and HTMLPurifier
 
@@ -79,6 +97,10 @@ foreach($definition->info as $namespace_name => $namespace_info) {
     $dom_namespace->appendChild(
         $dom_document->createElement('name', $namespace_name)
     );
+    $dom_namespace_description = $dom_document->createElement('description');
+    $dom_namespace->appendChild($dom_namespace_description);
+    appendHTMLDiv($dom_document, $dom_namespace_description,
+        $definition->info_namespace[$namespace_name]->description);
     
     foreach ($namespace_info as $name => $info) {
         
@@ -92,9 +114,19 @@ foreach($definition->info as $namespace_name => $namespace_info) {
         
         $dom_constraints = $dom_document->createElement('constraints');
         $dom_directive->appendChild($dom_constraints);
+        
         $dom_constraints->appendChild(
             $dom_document->createElement('type', $info->type)
         );
+        if ($info->allowed !== true) {
+            $dom_allowed = $dom_document->createElement('allowed');
+            $dom_constraints->appendChild($dom_allowed);
+            foreach ($info->allowed as $allowed => $bool) {
+                $dom_allowed->appendChild(
+                    $dom_document->createElement('value', $allowed)
+                );
+            }
+        }
         
         $dom_descriptions = $dom_document->createElement('descriptions');
         $dom_directive->appendChild($dom_descriptions);
@@ -104,16 +136,7 @@ foreach($definition->info as $namespace_name => $namespace_info) {
                 $dom_description = $dom_document->createElement('description');
                 $dom_description->setAttribute('file', $file);
                 $dom_description->setAttribute('line', $line);
-                
+                appendHTMLDiv($dom_document, $dom_description, $description);
-                $description = $purifier->purify($description);
-                $dom_html = $dom_document->createDocumentFragment();
-                $dom_html->appendXML($description);
-                
-                $dom_div = $dom_document->createElement('div');
-                $dom_div->setAttribute('xmlns', 'http://www.w3.org/1999/xhtml');
-                $dom_div->appendChild($dom_html);
-                
-                $dom_description->appendChild($dom_div);
                 $dom_descriptions->appendChild($dom_description);
             }
         }

configdoc/styles/plain.xsl

@@ -41,6 +41,11 @@
     <xsl:template match="namespace/name">
         <h2 id="{../@id}"><xsl:value-of select="text()" /></h2>
     </xsl:template>
+    <xsl:template match="namespace/description">
+        <div class="description">
+            <xsl:copy-of select="div/node()" />
+        </div>
+    </xsl:template>
     
     <xsl:template match="directive">
         <xsl:apply-templates />
@@ -51,6 +56,16 @@
     <xsl:template match="directive/constraints">
         <table class="constraints">
             <xsl:apply-templates />
+            <!-- Calculated other values -->
+            <tr>
+                <th>Used by:</th>
+                <td>
+                    <xsl:for-each select="../descriptions/description">
+                        <xsl:if test="position()&gt;1">, </xsl:if>
+                        <xsl:value-of select="@file" />
+                    </xsl:for-each>
+                </td>
+            </tr>
         </table>
     </xsl:template>
     <xsl:template match="directive//description">
@@ -69,5 +84,16 @@
             </td>
         </tr>
     </xsl:template>
+    <xsl:template match="constraints/allowed">
+        <tr>
+            <th>Allowed values:</th>
+            <td>
+                <xsl:for-each select="value"><!--
+                 --><xsl:if test="position()&gt;1">, </xsl:if>
+                    &quot;<xsl:value-of select="." />&quot;<!--
+             --></xsl:for-each>
+            </td>
+        </tr>
+    </xsl:template>
     
 </xsl:stylesheet>

library/HTMLPurifier/ConfigDef.php

@@ -155,10 +155,7 @@ class HTMLPurifier_ConfigDef {
         }
         $def->info[$namespace] = array();
         $def->info_namespace[$namespace] = new HTMLPurifier_ConfigEntity_Namespace();
-        $backtrace = debug_backtrace();
+        $def->info_namespace[$namespace]->description = $description;
-        $file = $def->mungeFilename($backtrace[0]['file']);
-        $line = $backtrace[0]['line'];
-        $def->info_namespace[$namespace]->addDescription($file,$line,$description);
         $def->defaults[$namespace] = array();
     }
     
@@ -282,27 +279,19 @@ class HTMLPurifier_ConfigDef {
 /**
  * Base class for configuration entity
  */
-class HTMLPurifier_ConfigEntity
+class HTMLPurifier_ConfigEntity {}
-{
-    /**
-     * Plaintext descriptions of the configuration entity is. Organized by
-     * file and line number, so multiple descriptions are allowed.
-     */
-    var $descriptions = array();
-    
-    /**
-     * Adds a description to the array
-     */
-    function addDescription($file, $line, $description) {
-        if (!isset($this->descriptions[$file])) $this->descriptions[$file] = array();
-        $this->descriptions[$file][$line] = $description;
-    }
-}
 
 /**
  * Structure object describing of a namespace
  */
-class HTMLPurifier_ConfigEntity_Namespace extends HTMLPurifier_ConfigEntity {}
+class HTMLPurifier_ConfigEntity_Namespace extends HTMLPurifier_ConfigEntity {
+    
+    /**
+     * String description of what kinds of directives go in this namespace.
+     */
+    var $description;
+    
+}
 
 /**
  * Structure object containing definition of a directive.
@@ -334,6 +323,19 @@ class HTMLPurifier_ConfigEntity_Directive extends HTMLPurifier_ConfigEntity
      *      - mixed (anything goes)
      */
     var $type = 'mixed';
+    /**
+     * Plaintext descriptions of the configuration entity is. Organized by
+     * file and line number, so multiple descriptions are allowed.
+     */
+    var $descriptions = array();
+    
+    /**
+     * Adds a description to the array
+     */
+    function addDescription($file, $line, $description) {
+        if (!isset($this->descriptions[$file])) $this->descriptions[$file] = array();
+        $this->descriptions[$file][$line] = $description;
+    }
     
 }
 

tests/HTMLPurifier/ConfigDefTest.php

@@ -33,7 +33,7 @@ class HTMLPurifier_ConfigDefTest extends UnitTestCase
         $description = 'Configuration that is always available.';
         HTMLPurifier_ConfigDef::defineNamespace(
             'Core', $description
-        ); $line = __LINE__;
+        );
         $this->assertIdentical($this->our_copy->defaults, array(
             'Core' => array()
         ));
@@ -41,7 +41,7 @@ class HTMLPurifier_ConfigDefTest extends UnitTestCase
             'Core' => array()
         ));
         $namespace = new HTMLPurifier_ConfigEntity_Namespace();
-        $namespace->addDescription($file, $line, $description);
+        $namespace->description = $description;
         $this->assertIdentical($this->our_copy->info_namespace, array(
             'Core' => $namespace
         ));