Release 2.0.0, merged in 1026 to HEAD.

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

configdoc/generate.php

@@ -2,216 +2,37 @@
 
 /**
  * Generates XML and HTML documents describing configuration.
+ * @note PHP 5 only!
  */
 
 /*
 TODO:
-- make XML format richer (see below)
+- make XML format richer (see XMLSerializer_ConfigSchema)
 - extend XSLT transformation (see the corresponding XSLT file)
 - allow generation of packaged docs that can be easily moved
 - multipage documentation
 - determine how to multilingualize
-- factor out code into classes
+- add blurbs to ToC
 */
 
-// ---------------------------------------------------------------------------
-// Check and configure environment
-
 if (version_compare('5', PHP_VERSION, '>')) exit('Requires PHP 5 or higher.');
-error_reporting(E_ALL);
-
-
-// ---------------------------------------------------------------------------
-// Include HTML Purifier library
+error_reporting(E_ALL); // probably not possible to use E_STRICT
 
+// load dual-libraries
 require_once '../library/HTMLPurifier.auto.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
+require_once 'library/ConfigDoc.auto.php';
 
 $schema = HTMLPurifier_ConfigSchema::instance();
-$purifier = new HTMLPurifier();
+$style = 'plain'; // use $_GET in the future
+$configdoc = new ConfigDoc();
+$output = $configdoc->generate($schema, $style);
 
-
-// ---------------------------------------------------------------------------
-// Generate types.xml, a document describing the constraint "type"
-
-$types_document = new DOMDocument('1.0', 'UTF-8');
-$types_root = $types_document->createElement('types');
-$types_document->appendChild($types_root);
-$types_document->formatOutput = true;
-foreach ($schema->types as $name => $expanded_name) {
-    $types_type = $types_document->createElement('type', $expanded_name);
-    $types_type->setAttribute('id', $name);
-    $types_root->appendChild($types_type);
-}
-$types_document->save('types.xml');
-
-
-// ---------------------------------------------------------------------------
-// Generate configdoc.xml, a document documenting configuration directives
-
-$dom_document = new DOMDocument('1.0', 'UTF-8');
-$dom_root = $dom_document->createElement('configdoc');
-$dom_document->appendChild($dom_root);
-$dom_document->formatOutput = true;
-
-// add the name of the application
-$dom_root->appendChild($dom_document->createElement('title', 'HTML Purifier'));
-
-/*
-TODO for XML format:
-- create a definition (DTD or other) once interface stabilizes
-*/
-
-foreach($schema->info as $namespace_name => $namespace_info) {
-    
-    $dom_namespace = $dom_document->createElement('namespace');
-    $dom_root->appendChild($dom_namespace);
-    
-    $dom_namespace->setAttribute('id', $namespace_name);
-    $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,
-        $schema->info_namespace[$namespace_name]->description);
-    
-    foreach ($namespace_info as $name => $info) {
-        
-        if ($info->class == 'alias') continue;
-        
-        $dom_directive = $dom_document->createElement('directive');
-        $dom_namespace->appendChild($dom_directive);
-        
-        $dom_directive->setAttribute('id', $namespace_name . '.' . $name);
-        $dom_directive->appendChild(
-            $dom_document->createElement('name', $name)
-        );
-        
-        $dom_constraints = $dom_document->createElement('constraints');
-        $dom_directive->appendChild($dom_constraints);
-        
-        $dom_type = $dom_document->createElement('type', $info->type);
-        if ($info->allow_null) {
-            $dom_type->setAttribute('allow-null', 'yes');
-        }
-        $dom_constraints->appendChild($dom_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)
-                );
-            }
-        }
-        
-        $raw_default = $schema->defaults[$namespace_name][$name];
-        if (is_bool($raw_default)) {
-            $default = $raw_default ? 'true' : 'false';
-        } elseif (is_string($raw_default)) {
-            $default = "\"$raw_default\"";
-        } elseif (is_null($raw_default)) {
-            $default = 'null';
-        } else {
-            $default = print_r(
-                    $schema->defaults[$namespace_name][$name], true
-                );
-        }
-        
-        $dom_default = $dom_document->createElement('default', $default);
-        
-        // remove this once we get a DTD
-        $dom_default->setAttribute('xml:space', 'preserve');
-        
-        $dom_constraints->appendChild($dom_default);
-        
-        $dom_descriptions = $dom_document->createElement('descriptions');
-        $dom_directive->appendChild($dom_descriptions);
-        
-        foreach ($info->descriptions as $file => $file_descriptions) {
-            foreach ($file_descriptions as $line => $description) {
-                $dom_description = $dom_document->createElement('description');
-                $dom_description->setAttribute('file', $file);
-                $dom_description->setAttribute('line', $line);
-                appendHTMLDiv($dom_document, $dom_description, $description);
-                $dom_descriptions->appendChild($dom_description);
-            }
-        }
-        
-    }
-    
-}
-
-// print_r($dom_document->saveXML());
-
-// save a copy of the raw XML
-$dom_document->save('configdoc.xml');
-
-
-// ---------------------------------------------------------------------------
-// Generate final output using XSLT
-
-// load the stylesheet
-$xsl_stylesheet_name = 'plain';
-$xsl_stylesheet = "styles/$xsl_stylesheet_name.xsl";
-$xsl_dom_stylesheet = new DOMDocument();
-$xsl_dom_stylesheet->load($xsl_stylesheet);
-
-// setup the XSLT processor
-$xsl_processor = new XSLTProcessor();
-
-// perform the transformation
-$xsl_processor->importStylesheet($xsl_dom_stylesheet);
-$html_output = $xsl_processor->transformToXML($dom_document);
-
-// some slight fudges to preserve backwards compatibility
-$html_output = str_replace('/>', ' />', $html_output); // <br /> not <br/>
-$html_output = str_replace(' xmlns=""', '', $html_output); // rm unnecessary xmlns
-
-if (class_exists('Tidy')) {
-    // cleanup output
-    $config = array(
-        'indent'        => true,
-        'output-xhtml'  => true,
-        'wrap'          => 80
-    );
-    $tidy = new Tidy;
-    $tidy->parseString($html_output, $config, 'utf8');
-    $tidy->cleanRepair();
-    $html_output = (string) $tidy;
-}
-
-// write it to a file (todo: parse into seperate pages)
-file_put_contents("$xsl_stylesheet_name.html", $html_output);
-
-
-// ---------------------------------------------------------------------------
-// Output for instant feedback
+// write out
+file_put_contents("$style.html", $output);
 
 if (php_sapi_name() != 'cli') {
-    echo $html_output;
+    // output = instant feedback
+    echo $output;
 } else {
     echo 'Files generated successfully.';
 }

configdoc/library/ConfigDoc.auto.php

@@ -0,0 +1,10 @@
+<?php
+
+/**
+ * This is a stub include that automatically configures the include path.
+ */
+
+set_include_path(dirname(__FILE__) . PATH_SEPARATOR . get_include_path() );
+require_once 'ConfigDoc.php';
+
+?>

configdoc/library/ConfigDoc.php

@@ -0,0 +1,39 @@
+<?php
+
+require_once 'ConfigDoc/HTMLXSLTProcessor.php';
+require_once 'ConfigDoc/XMLSerializer/Types.php';
+require_once 'ConfigDoc/XMLSerializer/ConfigSchema.php';
+
+class ConfigDoc
+{
+    
+    function generate($schema, $xsl_stylesheet_name = 'plain', $parameters = array()) {
+        // generate types document, describing type constraints
+        $types_serializer = new ConfigDoc_XMLSerializer_Types();
+        $types_document = $types_serializer->serialize($schema);
+        $types_document->save(dirname(__FILE__) . '/../types.xml'); // only ONE
+        
+        // generate configdoc.xml, documents configuration directives
+        $schema_serializer = new ConfigDoc_XMLSerializer_ConfigSchema();
+        $schema_document = $schema_serializer->serialize($schema);
+        $schema_document->save('configdoc.xml');
+        
+        // setup transformation
+        $xsl_stylesheet = dirname(__FILE__) . "/../styles/$xsl_stylesheet_name.xsl";
+        $xslt_processor = new ConfigDoc_HTMLXSLTProcessor();
+        $xslt_processor->setParameters($parameters);
+        $xslt_processor->importStylesheet($xsl_stylesheet);
+        
+        return $xslt_processor->transformToHTML($schema_document);
+    }
+    
+    /**
+     * Remove any generated files
+     */
+    function cleanup() {
+        unlink('configdoc.xml');
+    }
+    
+}
+
+?>

configdoc/library/ConfigDoc/HTMLXSLTProcessor.php

@@ -0,0 +1,62 @@
+<?php
+
+/**
+ * Special XSLTProcessor specifically for HTML documents. Loosely
+ * based off of XSLTProcessor, but not really
+ */
+class ConfigDoc_HTMLXSLTProcessor
+{
+    
+    protected $xsltProcessor;
+    
+    public function __construct() {
+        $this->xsltProcessor = new XSLTProcessor();
+    }
+    
+    /**
+     * Imports stylesheet for processor to use
+     * @param $xsl XSLT DOM tree, or filename of the XSL transformation
+     */
+    public function importStylesheet($xsl) {
+        if (is_string($xsl)) {
+            $xsl_file = $xsl;
+            $xsl = new DOMDocument();
+            $xsl->load($xsl_file);
+        }
+        return $this->xsltProcessor->importStylesheet($xsl);
+    }
+    
+    /**
+     * Transforms an XML file into HTML based on the stylesheet
+     * @param $xml XML DOM tree
+     */
+    public function transformToHTML($xml) {
+        $out = $this->xsltProcessor->transformToXML($xml);
+        
+        // fudges for HTML backwards compatibility
+        $out = str_replace('/>', ' />', $out); // <br /> not <br/>
+        $out = str_replace(' xmlns=""', '', $out); // rm unnecessary xmlns
+        if (class_exists('Tidy')) {
+            // cleanup output
+            $config = array(
+                'indent'        => true,
+                'output-xhtml'  => true,
+                'wrap'          => 80
+            );
+            $tidy = new Tidy;
+            $tidy->parseString($out, $config, 'utf8');
+            $tidy->cleanRepair();
+            $out = (string) $tidy;
+        }
+        return $out;
+    }
+    
+    public function setParameters($options) {
+        foreach ($options as $name => $value) {
+            $this->xsltProcessor->setParameter('', $name, $value);
+        }
+    }
+    
+}
+
+?>

configdoc/library/ConfigDoc/XMLSerializer.php

@@ -0,0 +1,26 @@
+<?php
+
+/**
+ * The XMLSerializer hierarchy of classes consist of classes that take
+ * objects and serialize them into XML, specifically DOM, form; this
+ * super-class contains convenience functions for those classes.
+ */
+class ConfigDoc_XMLSerializer
+{
+    
+    protected function appendHTMLDiv($document, $node, $html) {
+        $purifier = HTMLPurifier::getInstance();
+        $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);
+    }
+    
+}
+
+?>

configdoc/library/ConfigDoc/XMLSerializer/ConfigSchema.php

@@ -0,0 +1,118 @@
+<?php
+
+require_once 'ConfigDoc/XMLSerializer.php';
+
+class ConfigDoc_XMLSerializer_ConfigSchema extends ConfigDoc_XMLSerializer
+{
+    
+    /**
+     * Serializes a schema into DOM form
+     * @todo Split into sub-serializers
+     * @param $schema HTMLPurifier_ConfigSchema to serialize
+     */
+    public function serialize($schema) {
+        $dom_document = new DOMDocument('1.0', 'UTF-8');
+        $dom_root = $dom_document->createElement('configdoc');
+        $dom_document->appendChild($dom_root);
+        $dom_document->formatOutput = true;
+        
+        // add the name of the application
+        $dom_root->appendChild($dom_document->createElement('title', 'HTML Purifier'));
+        
+        /*
+        TODO for XML format:
+        - create a definition (DTD or other) once interface stabilizes
+        */
+        
+        foreach($schema->info as $namespace_name => $namespace_info) {
+            
+            $dom_namespace = $dom_document->createElement('namespace');
+            $dom_root->appendChild($dom_namespace);
+            
+            $dom_namespace->setAttribute('id', $namespace_name);
+            $dom_namespace->appendChild(
+                $dom_document->createElement('name', $namespace_name)
+            );
+            $dom_namespace_description = $dom_document->createElement('description');
+            $dom_namespace->appendChild($dom_namespace_description);
+            $this->appendHTMLDiv($dom_document, $dom_namespace_description,
+                $schema->info_namespace[$namespace_name]->description);
+            
+            foreach ($namespace_info as $name => $info) {
+                
+                if ($info->class == 'alias') continue;
+                
+                $dom_directive = $dom_document->createElement('directive');
+                $dom_namespace->appendChild($dom_directive);
+                
+                $dom_directive->setAttribute('id', $namespace_name . '.' . $name);
+                $dom_directive->appendChild(
+                    $dom_document->createElement('name', $name)
+                );
+                
+                $dom_constraints = $dom_document->createElement('constraints');
+                $dom_directive->appendChild($dom_constraints);
+                
+                $dom_type = $dom_document->createElement('type', $info->type);
+                if ($info->allow_null) {
+                    $dom_type->setAttribute('allow-null', 'yes');
+                }
+                $dom_constraints->appendChild($dom_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)
+                        );
+                    }
+                }
+                
+                $raw_default = $schema->defaults[$namespace_name][$name];
+                if (is_bool($raw_default)) {
+                    $default = $raw_default ? 'true' : 'false';
+                } elseif (is_string($raw_default)) {
+                    $default = "\"$raw_default\"";
+                } elseif (is_null($raw_default)) {
+                    $default = 'null';
+                } else {
+                    $default = print_r(
+                            $schema->defaults[$namespace_name][$name], true
+                        );
+                }
+                
+                $dom_default = $dom_document->createElement('default', $default);
+                
+                // remove this once we get a DTD
+                $dom_default->setAttribute('xml:space', 'preserve');
+                
+                $dom_constraints->appendChild($dom_default);
+                
+                $dom_descriptions = $dom_document->createElement('descriptions');
+                $dom_directive->appendChild($dom_descriptions);
+                
+                foreach ($info->descriptions as $file => $file_descriptions) {
+                    foreach ($file_descriptions as $line => $description) {
+                        $dom_description = $dom_document->createElement('description');
+                        // refuse to write $file if it's a full path
+                        if (str_replace('\\', '/', realpath($file)) != $file) {
+                            $dom_description->setAttribute('file', $file);
+                            $dom_description->setAttribute('line', $line);
+                        }
+                        $this->appendHTMLDiv($dom_document, $dom_description, $description);
+                        $dom_descriptions->appendChild($dom_description);
+                    }
+                }
+                
+            }
+            
+        }
+        
+        return $dom_document;
+        
+    }
+    
+}
+
+?>

configdoc/library/ConfigDoc/XMLSerializer/Types.php

@@ -0,0 +1,27 @@
+<?php
+
+require_once 'ConfigDoc/XMLSerializer.php';
+
+class ConfigDoc_XMLSerializer_Types extends ConfigDoc_XMLSerializer
+{
+    
+    /**
+     * Serializes the types in a schema into DOM form
+     * @param $schema HTMLPurifier_ConfigSchema owner of types to serialize
+     */
+    public function serialize($schema) {
+        $types_document = new DOMDocument('1.0', 'UTF-8');
+        $types_root = $types_document->createElement('types');
+        $types_document->appendChild($types_root);
+        $types_document->formatOutput = true;
+        foreach ($schema->types as $name => $expanded_name) {
+            $types_type = $types_document->createElement('type', $expanded_name);
+            $types_type->setAttribute('id', $name);
+            $types_root->appendChild($types_type);
+        }
+        return $types_document;
+    }
+    
+}
+
+?>

configdoc/styles/plain.xsl

@@ -12,19 +12,21 @@
         indent = "no"
         media-type = "text/html"
     />
+    <xsl:param name="css" select="'styles/plain.css'"/>
+    <xsl:param name="title" select="'Configuration Documentation'"/>
     
     <xsl:variable name="typeLookup" select="document('../types.xml')" />
     
     <xsl:template match="/">
         <html lang="en" xml:lang="en">
             <head>
-                <title>Configuration Documentation - <xsl:value-of select="/configdoc/title" /></title>
+                <title><xsl:value-of select="$title" /> - <xsl:value-of select="/configdoc/title" /></title>
                 <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
-                <link rel="stylesheet" type="text/css" href="styles/plain.css" />
+                <link rel="stylesheet" type="text/css" href="{$css}" />
             </head>
             <body>
                 <div id="library"><xsl:value-of select="/configdoc/title" /></div>
-                <h1>Configuration Documentation</h1>
+                <h1><xsl:value-of select="$title" /></h1>
                 <h2>Table of Contents</h2>
                 <ul id="toc">
                     <xsl:apply-templates mode="toc" />
@@ -76,15 +78,17 @@
         <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>
+            <xsl:if test="../descriptions/description[@file]">
+                <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>
+            </xsl:if>
         </table>
     </xsl:template>
     <xsl:template match="directive//description">