[3.1.0] Add support for deprecated and version in configdoc

- Hide deprecated elements from ToC
- %HTML.Doctype takes null instead of empty string; this shouldn't affect anyone

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

NEWS

@@ -46,6 +46,7 @@ NEWS ( CHANGELOG and HISTORY )                                     HTMLPurifier
 ! Experimental kses() wrapper introduced with HTMLPurifier.kses.php
 ! Finally %CSS.AllowedProperties for tweaking allowed CSS properties without
   mucking around with HTMLPurifier_CSSDefinition
+! ConfigDoc output has been enhanced with version and deprecation info.
 - Autoclose now operates iteratively, i.e. <span><span><div> now has
   both span tags closed.
 - Various HTMLPurifier_Config convenience functions now accept another parameter

TODO

@@ -27,8 +27,6 @@ IMPORTANT FEATURES
  - Figure out autoload and PEAR
 
 CONFIGDOC
- - Have configdoc use version and deprecated information (hide deprecated
-   info, for example)
  - Implement source code sniffing for configdoc, so we can easily figure out
    which files use what configuration (we'll rely on the $config convention)
 

configdoc/styles/plain.css

@@ -22,3 +22,6 @@ h2 {border-bottom:1px solid #CCC; font-family:sans-serif; font-weight:normal;
     font-size:1.3em;}
 h3 {font-family:sans-serif; font-size:1.1em; font-weight:bold; }
 h4 {font-family:sans-serif; font-size:0.9em; font-weight:bold; }
+
+.deprecated {color: #CCC;}
+.deprecated-notice {color: #000; text-align:center; margin-bottom: 1em;}

configdoc/styles/plain.xsl

@@ -48,7 +48,9 @@
         </xsl:if>
     </xsl:template>
     <xsl:template match="directive" mode="toc">
-        <li><a href="#{@id}"><xsl:value-of select="name" /></a></li>
+        <xsl:if test="not(deprecated)">
+            <li><a href="#{@id}"><xsl:value-of select="name" /></a></li>
+        </xsl:if>
     </xsl:template>
     
     <xsl:template match="title" />
@@ -69,7 +71,15 @@
     </xsl:template>
     
     <xsl:template match="directive">
-        <xsl:apply-templates />
+        <div>
+            <xsl:attribute name="class">
+                directive
+                <xsl:if test="deprecated">
+                    deprecated
+                </xsl:if>
+            </xsl:attribute>
+            <xsl:apply-templates />
+        </div>
     </xsl:template>
     <xsl:template match="directive/name">
         <xsl:apply-templates select="../aliases/alias" mode="anchor" />
@@ -106,7 +116,19 @@
             <xsl:copy-of xmlns:xhtml="http://www.w3.org/1999/xhtml" select="xhtml:div/node()" />
         </div>
     </xsl:template>
+    <xsl:template match="directive/deprecated">
+        <div class="deprecated-notice">
+            This directive was deprecated in version <xsl:value-of select="version" />.
+            <a href="#{use}">%<xsl:value-of select="use" /></a> should be used instead.
+        </div>
+    </xsl:template>
     
+    <xsl:template match="constraints/version">
+        <tr>
+            <th>Version:</th>
+            <td><xsl:value-of select="." /></td>
+        </tr>
+    </xsl:template>
     <xsl:template match="constraints/type">
         <tr>
             <th>Type:</th>

library/HTMLPurifier/ConfigSchema/Builder/Xml.php

@@ -70,6 +70,7 @@ class HTMLPurifier_ConfigSchema_Builder_Xml extends XMLWriter
         $this->endElement(); // aliases
         
         $this->startElement('constraints');
+            if ($directive->version) $this->writeElement('version', $directive->version);
             $this->writeElement('type', $directive->type);
             if ($directive->typeAllowsNull) $this->writeAttribute('allow-null', 'yes');
             if ($directive->allowed) {
@@ -81,6 +82,13 @@ class HTMLPurifier_ConfigSchema_Builder_Xml extends XMLWriter
             $this->writeAttribute('xml:space', 'preserve');
         $this->endElement(); // constraints
         
+        if ($directive->deprecatedVersion) {
+            $this->startElement('deprecated');
+                $this->writeElement('version', $directive->deprecatedVersion);
+                $this->writeElement('use', $directive->deprecatedUse->toString());
+            $this->endElement(); // deprecated
+        }
+        
         $this->startElement('description');
             $this->writeHTMLDiv($directive->description);
         $this->endElement(); // description

library/HTMLPurifier/ConfigSchema/schema/Core.RemoveScriptContents.txt

@@ -3,7 +3,7 @@ TYPE: bool/null
 DEFAULT: NULL
 VERSION: 2.0.0
 DEPRECATED-VERSION: 2.1.0
-DEPRECATED-USE: %Core.HiddenElements
+DEPRECATED-USE: Core.HiddenElements
 --DESCRIPTION--
 <p>
   This directive enables HTML Purifier to remove not only script tags

library/HTMLPurifier/ConfigSchema/schema/HTML.Doctype.txt

@@ -1,10 +1,10 @@
 HTML.Doctype
-TYPE: string
+TYPE: string/null
-DEFAULT: ''
+DEFAULT: NULL
 --DESCRIPTION--
 Doctype to use during filtering. Technically speaking this is not actually
 a doctype (as it does not identify a corresponding DTD), but we are using
 this name for sake of simplicity. When non-blank, this will override any
 older directives like %HTML.XHTML or %HTML.Strict.
 --ALLOWED--
-'', 'HTML 4.01 Transitional', 'HTML 4.01 Strict', 'XHTML 1.0 Transitional', 'XHTML 1.0 Strict', 'XHTML 1.1'
+'HTML 4.01 Transitional', 'HTML 4.01 Strict', 'XHTML 1.0 Transitional', 'XHTML 1.0 Strict', 'XHTML 1.1'

library/HTMLPurifier/ConfigSchema/schema/HTML.Strict.txt

@@ -2,6 +2,7 @@ HTML.Strict
 TYPE: bool
 VERSION: 1.3.0
 DEFAULT: false
+DEPRECATED-VERSION: 1.7.0
+DEPRECATED-USE: HTML.Doctype
 --DESCRIPTION--
 Determines whether or not to use Transitional (loose) or Strict rulesets.
-This directive is deprecated in favor of %HTML.Doctype. 

library/HTMLPurifier/ConfigSchema/schema/HTML.XHTML.txt

@@ -2,8 +2,9 @@ HTML.XHTML
 TYPE: bool
 DEFAULT: true
 VERSION: 1.1.0
+DEPRECATED-VERSION: 1.7.0
+DEPRECATED-USE: HTML.Doctype
 --DESCRIPTION--
-Determines whether or not output is XHTML 1.0 or HTML 4.01 flavor. This
+Determines whether or not output is XHTML 1.0 or HTML 4.01 flavor.
-directive is deprecated in favor of %HTML.Doctype.
 --ALIASES--
 Core.XHTML

tests/ConfigDoc/DOM/DocumentTest.php

@@ -1,11 +0,0 @@
-<?php
-
-class ConfigDoc_DOM_DocumentTest extends UnitTestCase
-{
-    
-    function testOverload() {
-        $dom = new ConfigDoc_DOM_Document();
-        $this->assertIsA($dom->createElement('a'), 'ConfigDoc_DOM_Element');
-    }
-    
-}

tests/test_files.php

@@ -20,7 +20,7 @@ if (!$AC['only-phpt']) {
     
     // ConfigDoc auxiliary library
     if (version_compare(PHP_VERSION, '5.2', '>=')) {
-        $test_dirs[] = 'ConfigDoc';
+        // $test_dirs[] = 'ConfigDoc'; // no test files currently!
     }
     
     // FSTools auxiliary library