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