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">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.</li>
  56   <li><a href="live/smoketests/printDefinition.php">Print
  57       Definition</a> &mdash; If you want to actually see what HTML Purifier's
  58       filtering rules are, look no further than to this page. You can even
  59       experiment with the configuration to see how things respond to different
  60       directives.</li>
  61 </ul>
  62
  63 <p>
  64   P.S. HTML Purifier's source code is well documented and very readable.
  65   If a question of your isn't answered by any of the above resources,
  66   go to the source! (Or ask in the forums.)
  67 </p>
  68
  69 <h2>Frequently Asked Questions</h2>
  70
  71 <h3>What does %HTML.Allowed mean?</h3>
  72
  73 <p>
  74   The percent-dot format is a shorthand for HTML Purifier's configuration
  75   directives. It takes the form of %Namespace.Directive. For
  76   practical purposes, %HTML.Allowed translates into the following PHP
  77   code:
  78 </p>
  79
  80 <pre>$config->set('HTML', 'Allowed', $value);</pre>
  81
  82 <h3>My attributes are mysteriously disappearing!</h3>
  83
  84 <p>
  85   You've probably got <a href="http://php.net/manual/en/security.magicquotes.php">magic quotes</a>
  86   turned on, which is interfering with the single and double-quotes in
  87   <abbr>HTML</abbr> attributes. The usual way to fix this is
  88   <a href="http://php.net/manual/en/security.magicquotes.disabling.php">with
  89   some runtime code or an ini tweak.</a> Be sure not to introduce any
  90   <abbr>SQL</abbr> injection vulnerabilities!
  91 </p>
  92
  93 <h3>How do I prevent foreign characters like ä and <code>&amp;nbsp;</code> from turning into Ã¤?</h3>
  94
  95 <p>
  96   This usually means that HTML Purifier is parsing your code as UTF-8, but
  97   your output encoding is something else. Read up <a href="docs/enduser-utf8.html">this
  98   document on UTF-8</a> to learn how to fix this. (Short answer: use
  99   %Core.Encoding or switch to UTF-8.)
 100 </p>
 101
 102 <h3>I can't use the <code>target</code> or <code>name</code> attribute in my <code>a</code> tags!</h3>
 103
 104 <p>
 105   The <code>target</code> attribute has been deprecated for a long time, so
 106   I highly recommend you look at other ways of, say, opening new windows
 107   when you click a link (my favorites are <q>Don't do it!</q> or, if you
 108   must, JavaScript) But if you must, the
 109   <a href="live/configdoc/plain.html#Attr.AllowedFrameTargets">%Attr.AllowedFrameTargets</a>
 110   directive is what you are looking for.
 111 </p>
 112
 113 <p>
 114   The <code>name</code> attribute is dependent on IDs being enabled.
 115   See <a href="docs/enduser-id.html">this document on enabling user IDs</a> for more information.
 116 </p>
 117
 118 <h3>Is HTML Purifier slow?</h3>
 119
 120 <p>
 121   HTML Purifier isn't exactly light or speedy; this is a tradeoff for the
 122   power and security the library affords. You can combat this by reading
 123   <a href="docs/enduser-slow.html">Speeding up HTML Purifier</a> or using
 124   the <a href="download#Standalone">standalone</a> version.
 125 </p>
 126
 127 <h2>Miscellaneous</h2>
 128
 129 <ul>
 130   <li><a href="live/smoketests/xssAttacks.php"><abbr>XSS</abbr>
 131       Attacks Smoketest</a> &mdash; Tests how well HTML Purifier fares
 132       against RSnake's famous cheatsheet of <abbr>XSS</abbr> attacks.</li>
 133   <li><a href="live/TODO">Roadmap</a>
 134       &mdash; Subject to lots of delays, but it's a glimpse of the future</li>
 135   <li><a href="live/art/">Artwork</a>
 136       &mdash; Extra media goodies.</li>
 137 </ul>
 138
 139 </div>
 140 </div>
 141
 142 </body>
 143 </html>