Remove phpdoc link, and fix grammar mistake in 3.2.0 release text.
[htmlpurifier-web.git] / docs.xhtml
blobeea4b40de54541302e8e83068cc8bd7ca5eea88b
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>
16 <xi:include href="common-header.xml" xpointer="xpointer(/*/node())" />
18 <div id="main">
19 <h1 id="title">Documentation</h1>
21 <div id="content">
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>
31 <div id="toc" class="floated" />
33 <h2>For Contributors</h2>
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>
43 <h2>For Advanced Users</h2>
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>
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>
69 <h2>Frequently Asked Questions</h2>
71 <h3>What does %HTML.Allowed mean?</h3>
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>
80 <pre>$config->set('HTML', 'Allowed', $value);</pre>
82 <h3>My attributes are mysteriously disappearing!</h3>
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>
93 <h3>How do I prevent foreign characters like ä and <code>&amp;nbsp;</code> from turning into ä?</h3>
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>
102 <h3>I can't use the <code>target</code> or <code>name</code> attribute in my <code>a</code> tags!</h3>
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>
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>
118 <h3>Is HTML Purifier slow?</h3>
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.html#Standalone">standalone</a> version.
125 </p>
127 <h2>Miscellaneous</h2>
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>
139 </div>
140 </div>
142 </body>
143 </html>