configdoc/generate.php

   1 <?php
   2
   3 /**
   4  * Generates XML and HTML documents describing configuration.
   5  */
   6
   7 /*
   8 TODO:
   9 - make XML format richer (see below)
  10 - extend XSLT transformation (see the corresponding XSLT file)
  11 - allow generation of packaged docs that can be easily moved
  12 - multipage documentation
  13 - determine how to multilingualize
  14 - factor out code into classes
  15 - generate a table of contents
  16 */
  17
  18
  19 // ---------------------------------------------------------------------------
  20 // Check and configure environment
  21
  22 if (version_compare('5', PHP_VERSION, '>')) exit('Requires PHP 5 or higher.');
  23 error_reporting(E_ALL);
  24
  25
  26 // ---------------------------------------------------------------------------
  27 // Include HTML Purifier library
  28
  29 set_include_path('../library' . PATH_SEPARATOR . get_include_path());
  30 require_once 'HTMLPurifier.php';
  31
  32
  33 // ---------------------------------------------------------------------------
  34 // Setup convenience functions
  35
  36 function appendHTMLDiv($document, $node, $html) {
  37     global $purifier;
  38     $html = $purifier->purify($html);
  39     $dom_html = $document->createDocumentFragment();
  40     $dom_html->appendXML($html);
  41
  42     $dom_div = $document->createElement('div');
  43     $dom_div->setAttribute('xmlns', 'http://www.w3.org/1999/xhtml');
  44     $dom_div->appendChild($dom_html);
  45
  46     $node->appendChild($dom_div);
  47 }
  48
  49
  50 // ---------------------------------------------------------------------------
  51 // Load copies of HTMLPurifier_ConfigDef and HTMLPurifier
  52
  53 $schema = HTMLPurifier_ConfigSchema::instance();
  54 $purifier = new HTMLPurifier();
  55
  56
  57 // ---------------------------------------------------------------------------
  58 // Generate types.xml, a document describing the constraint "type"
  59
  60 $types_document = new DOMDocument('1.0', 'UTF-8');
  61 $types_root = $types_document->createElement('types');
  62 $types_document->appendChild($types_root);
  63 $types_document->formatOutput = true;
  64 foreach ($schema->types as $name => $expanded_name) {
  65     $types_type = $types_document->createElement('type', $expanded_name);
  66     $types_type->setAttribute('id', $name);
  67     $types_root->appendChild($types_type);
  68 }
  69 $types_document->save('types.xml');
  70
  71
  72 // ---------------------------------------------------------------------------
  73 // Generate configdoc.xml, a document documenting configuration directives
  74
  75 $dom_document = new DOMDocument('1.0', 'UTF-8');
  76 $dom_root = $dom_document->createElement('configdoc');
  77 $dom_document->appendChild($dom_root);
  78 $dom_document->formatOutput = true;
  79
  80 // add the name of the application
  81 $dom_root->appendChild($dom_document->createElement('title', 'HTML Purifier'));
  82
  83 /*
  84 TODO for XML format:
  85 - namespace descriptions
  86 - enumerated values
  87 - default values
  88 - create a definition (DTD or other) once interface stabilizes
  89 */
  90
  91 foreach($schema->info as $namespace_name => $namespace_info) {
  92
  93     $dom_namespace = $dom_document->createElement('namespace');
  94     $dom_root->appendChild($dom_namespace);
  95
  96     $dom_namespace->setAttribute('id', $namespace_name);
  97     $dom_namespace->appendChild(
  98         $dom_document->createElement('name', $namespace_name)
  99     );
 100     $dom_namespace_description = $dom_document->createElement('description');
 101     $dom_namespace->appendChild($dom_namespace_description);
 102     appendHTMLDiv($dom_document, $dom_namespace_description,
 103         $schema->info_namespace[$namespace_name]->description);
 104
 105     foreach ($namespace_info as $name => $info) {
 106
 107         $dom_directive = $dom_document->createElement('directive');
 108         $dom_namespace->appendChild($dom_directive);
 109
 110         $dom_directive->setAttribute('id', $namespace_name . '.' . $name);
 111         $dom_directive->appendChild(
 112             $dom_document->createElement('name', $name)
 113         );
 114
 115         $dom_constraints = $dom_document->createElement('constraints');
 116         $dom_directive->appendChild($dom_constraints);
 117
 118         $dom_constraints->appendChild(
 119             $dom_document->createElement('type', $info->type)
 120         );
 121         if ($info->allowed !== true) {
 122             $dom_allowed = $dom_document->createElement('allowed');
 123             $dom_constraints->appendChild($dom_allowed);
 124             foreach ($info->allowed as $allowed => $bool) {
 125                 $dom_allowed->appendChild(
 126                     $dom_document->createElement('value', $allowed)
 127                 );
 128             }
 129         }
 130
 131         $raw_default = $schema->defaults[$namespace_name][$name];
 132         if (is_bool($raw_default)) {
 133             $default = $raw_default ? 'true' : 'false';
 134         } elseif (is_string($raw_default)) {
 135             $default = "\"$raw_default\"";
 136         } else {
 137             $default = print_r(
 138                     $schema->defaults[$namespace_name][$name], true
 139                 );
 140         }
 141         $dom_constraints->appendChild(
 142             $dom_document->createElement('default', $default)
 143         );
 144
 145         $dom_descriptions = $dom_document->createElement('descriptions');
 146         $dom_directive->appendChild($dom_descriptions);
 147
 148         foreach ($info->descriptions as $file => $file_descriptions) {
 149             foreach ($file_descriptions as $line => $description) {
 150                 $dom_description = $dom_document->createElement('description');
 151                 $dom_description->setAttribute('file', $file);
 152                 $dom_description->setAttribute('line', $line);
 153                 appendHTMLDiv($dom_document, $dom_description, $description);
 154                 $dom_descriptions->appendChild($dom_description);
 155             }
 156         }
 157
 158     }
 159
 160 }
 161
 162 // print_r($dom_document->saveXML());
 163
 164 // save a copy of the raw XML
 165 $dom_document->save('configdoc.xml');
 166
 167
 168 // ---------------------------------------------------------------------------
 169 // Generate final output using XSLT
 170
 171 // load the stylesheet
 172 $xsl_stylesheet_name = 'plain';
 173 $xsl_stylesheet = "styles/$xsl_stylesheet_name.xsl";
 174 $xsl_dom_stylesheet = new DOMDocument();
 175 $xsl_dom_stylesheet->load($xsl_stylesheet);
 176
 177 // setup the XSLT processor
 178 $xsl_processor = new XSLTProcessor();
 179
 180 // perform the transformation
 181 $xsl_processor->importStylesheet($xsl_dom_stylesheet);
 182 $html_output = $xsl_processor->transformToXML($dom_document);
 183
 184 // some slight fudges to preserve backwards compatibility
 185 $html_output = str_replace('/>', ' />', $html_output); // <br /> not <br>
 186 $html_output = str_replace(' xmlns=""', '', $html_output); // rm unnecessary xmlns
 187
 188 if (class_exists('Tidy')) {
 189     // cleanup output
 190     $config = array(
 191         'indent'        => true,
 192         'output-xhtml'  => true,
 193         'wrap'          => 80
 194     );
 195     $tidy = new Tidy;
 196     $tidy->parseString($html_output, $config, 'utf8');
 197     $tidy->cleanRepair();
 198     $html_output = (string) $tidy;
 199 }
 200
 201 // write it to a file (todo: parse into seperate pages)
 202 file_put_contents("$xsl_stylesheet_name.html", $html_output);
 203
 204
 205 // ---------------------------------------------------------------------------
 206 // Output for instant feedback
 207
 208 if (php_sapi_name() != 'cli') {
 209     echo $html_output;
 210 } else {
 211     echo 'Files generated successfully.';
 212 }
 213
 214 ?>