From a365d4c688803f534b87ed68a8de4b530b097667 Mon Sep 17 00:00:00 2001 From: "Edward Z. Yang" Date: Wed, 13 Sep 2006 00:59:20 +0000 Subject: [PATCH] - 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 | 1 + TODO | 1 - configdoc/generate.php | 43 ++++++++++++++++++++------- configdoc/styles/plain.xsl | 26 ++++++++++++++++ library/HTMLPurifier/ConfigDef.php | 44 +++++++++++++++------------- tests/HTMLPurifier/ConfigDefTest.php | 4 +-- 6 files changed, 85 insertions(+), 34 deletions(-) diff --git a/NEWS b/NEWS index dbf28ca9..60eda910 100644 --- a/NEWS +++ b/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) diff --git a/TODO b/TODO index 62f223a0..3bd98579 100644 --- a/TODO +++ b/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 diff --git a/configdoc/generate.php b/configdoc/generate.php index 7ea5c526..87841be2 100644 --- a/configdoc/generate.php +++ b/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); - - $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); + appendHTMLDiv($dom_document, $dom_description, $description); $dom_descriptions->appendChild($dom_description); } } diff --git a/configdoc/styles/plain.xsl b/configdoc/styles/plain.xsl index c33f78a1..6f795774 100644 --- a/configdoc/styles/plain.xsl +++ b/configdoc/styles/plain.xsl @@ -41,6 +41,11 @@

+ +
+ +
+ @@ -51,6 +56,16 @@ + + + + +
Used by: + + , + + +
@@ -69,5 +84,16 @@ + + + Allowed values: + + , + "" + + + \ No newline at end of file diff --git a/library/HTMLPurifier/ConfigDef.php b/library/HTMLPurifier/ConfigDef.php index dabe554a..86cf264e 100644 --- a/library/HTMLPurifier/ConfigDef.php +++ b/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(); - $file = $def->mungeFilename($backtrace[0]['file']); - $line = $backtrace[0]['line']; - $def->info_namespace[$namespace]->addDescription($file,$line,$description); + $def->info_namespace[$namespace]->description = $description; $def->defaults[$namespace] = array(); } @@ -282,27 +279,19 @@ class HTMLPurifier_ConfigDef { /** * Base class for configuration entity */ -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; - } -} +class HTMLPurifier_ConfigEntity {} /** * 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; + } } diff --git a/tests/HTMLPurifier/ConfigDefTest.php b/tests/HTMLPurifier/ConfigDefTest.php index 401690ff..e574dc1d 100644 --- a/tests/HTMLPurifier/ConfigDefTest.php +++ b/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 ));