docs.xhtml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   3     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   4 <html
   5   xmlns="http://www.w3.org/1999/xhtml"
   6   xmlns:xi="http://www.w3.org/2001/XInclude"
   7   xml:lang="en">
   8 <head>
   9   <title>Documentation - HTML Purifier</title>
  10   <xi:include href="common-meta.xml" xpointer="xpointer(/*/node())" />
  11   <meta name="description" content="Documentation for HTML Purifier." />
  12   <meta name="keywords" content="HTMLPurifier, HTML Purifier, HTML, filter, filtering, standards, compliant, documentation, docs, manual" />
  13 </head>
  14 <body>
  15
  16 <xi:include href="common-header.xml" xpointer="xpointer(/*/node())" />
  17 <h1 id="title">Documentation</h1>
  18
  19 <div id="content">
  20
  21 <p>
  22   HTML Purifier's documentation is organized by topic. New users should
  23   read the <a href="live/INSTALL">INSTALL</a> file that comes with your
  24   HTML Purifier download. Any questions about HTML Purifier can be asked
  25   at the <a href="http://htmlpurifier.org/phorum/">support forums</a> (no
  26   registration required!)
  27 </p>
  28
  29 <h2>For Advanced Users</h2>
  30
  31 <ul>
  32   <li><a href="docs/">End-User
  33       Documentation</a> &mdash; In-depth documents on how to get
  34       the most out of HTML Purifier. These are located in the <code>docs/</code>
  35       folder of your HTML Purifier installation.</li>
  36   <li><a href="live/configdoc/plain.html">Configuration
  37       documentation</a> &mdash; These are various configuration directives
  38       that can be used to customize HTML Purifier's behavior.</li>
  39   <li><a href="http://htmlpurifier.org/doxygen/html/">Doxygen-generated
  40       Documentation</a> &mdash; No class left undocumented!  Cross-referenced
  41       code!  A must-read for any prospective HTML Purifier hacker.
  42       (close by, <a href="http://htmlpurifier.org/phpdoc/">PHPDoc-generated
  43       Documentation.</a>)</li>
  44   <li><a href="live/smoketests/printDefinition.php">Print
  45       Definition</a> &mdash; If you want to actually see what HTML Purifier's
  46       filtering rules are, look no further than to this page. You can even
  47       experiment with the configuration to see how things respond to different
  48       directives.</li>
  49 </ul>
  50
  51 <p>
  52   P.S. HTML Purifier's source code is well documented and very readable.
  53   If a question of your isn't answered by any of the above resources,
  54   go to the source! (Or ask in the forums.)
  55 </p>
  56
  57 <h2>Frequently Asked Questions</h2>
  58
  59 <h3>What does %HTML.Allowed mean?</h3>
  60
  61 <p>
  62   The percent-dot format is a shorthand for HTML Purifier's configuration
  63   directives. It takes the form of %Namespace.Directive. For
  64   practical purposes, %HTML.Allowed translates into the following PHP
  65   code:
  66 </p>
  67
  68 <pre>$config->set('HTML', 'Allowed', $value);</pre>
  69
  70 <h3>My attributes are mysteriously disappearing!</h3>
  71
  72 <p>
  73   You've probably got <a href="http://php.net/manual/en/security.magicquotes.php">magic quotes</a>
  74   turned on, which is interfering with the single and double-quotes in
  75   <abbr>HTML</abbr> attributes. The usual way to fix this is
  76   <a href="http://php.net/manual/en/security.magicquotes.disabling.php">with
  77   some runtime code or an ini tweak.</a> Be sure not to introduce any
  78   <abbr>SQL</abbr> injection vulnerabilities!
  79 </p>
  80
  81 <h3>How do I prevent foreign characters like ä and <code>&amp;nbsp</code> from turning into Ã¤?</h3>
  82
  83 <p>
  84   This usually means that HTML Purifier is parsing your code as UTF-8, but
  85   your output encoding is something else. Read up <a href="docs/enduser-utf8.html">this
  86   document on UTF-8</a> to learn how to fix this. (Short answer: use
  87   %Core.Encoding or switch to UTF-8.)
  88 </p>
  89
  90 <h3>I can't use the <code>target</code> or <code>name</code> attribute in my <code>a</code> tags!</h3>
  91
  92 <p>
  93   The <code>target</code> attribute has been deprecated for a long time, so
  94   I highly recommend you look at other ways of, say, opening new windows
  95   when you click a link (my favorites are <q>Don't do it!</q> or, if you
  96   must, JavaScript) But if you must, the
  97   <a href="live/configdoc/plain.html#Attr.AllowedFrameTargets">%Attr.AllowedFrameTargets</a>
  98   directive is what you are looking for.
  99 </p>
 100
 101 <p>
 102   The <code>name</code> attribute is dependent on IDs being enabled.
 103   See <a href="docs/enduser-id.html">this document on enabling user IDs</a> for more information.
 104 </p>
 105
 106 <h3>Is HTML Purifier slow?</h3>
 107
 108 <p>
 109   HTML Purifier isn't exactly light or speedy; this is a tradeoff for the
 110   power and security the library affords. You can combat this by reading
 111   <a href="docs/enduser-slow.html">Speeding up HTML Purifier</a> or using
 112   the <a href="download.html#Standalone">standalone</a> version.
 113 </p>
 114
 115 <h2>Miscellaneous</h2>
 116
 117 <ul>
 118   <li><a href="live/smoketests/xssAttacks.php"><abbr>XSS</abbr>
 119       Attacks Smoketest</a> &mdash; Tests how well HTML Purifier fares
 120       against RSnake's famous cheatsheet of <abbr>XSS</abbr> attacks.</li>
 121   <li><a href="live/TODO">Roadmap</a>
 122       &mdash; Subject to lots of delays, but it's a glimpse of the future</li>
 123   <li><a href="live/art/">Artwork</a>
 124       &mdash; Extra media goodies.</li>
 125 </ul>
 126
 127 </div>
 128
 129 </body>
 130 </html>