Permalink
Browse files

more readme, detailing usage.

  • Loading branch information...
1 parent 80a1ecf commit e6931abbec2b9397bc900c843a8d9906d4a86f5f @flavorjones flavorjones committed Feb 10, 2009
Showing with 36 additions and 2 deletions.
  1. +36 −2 README.markdown
View
@@ -21,6 +21,36 @@ Oooh, that could be bad. Here's how to fix it:
Yeah, it's that easy.
+In this example, <tt>safe\_html\_snippet</tt> will have all of its __broken markup fixed__ by libxml2, and it will also be completely __sanitized of harmful tags and attributes__. That's twice as clean!
+
+
+More Usage
+-----
+
+You're still here? Ok, let me tell you a little something about the two different methods of sanitizing the Dryopteris offers.
+
+### Fragments
+
+The first method is for _html fragments_, which are small snippets of markup such as those used in forum posts, emails and homework assignments.
+
+Usage is the same as above:
+
+ safe_html_snippet = Dryopteris.sanitize(dangerous_html_snippet)
+
+Generally speaking, unless you expect to have &lt;html&gt; and &lt;body&gt; tags in your HTML, this is the sanitizing method to use.
+
+The only real limitation on this method is that the snippet must be a string object. (Support for IO objects was sacrificed at the altar of fixer-uppery-ness. If you need to sanitize data that's coming from an IO object, either socket or file, check out the next section on __Documents__).
+
+### Documents
+
+Sometimes you need to sanitize an entire HTML document. (Well, maybe not _you_, but other people, certainly.)
+
+ safe_html_document = Dryopteris.sanitize_document(dangerous_html_document)
+
+The returned string will contain exactly one (1) well-formed HTML document, with all broken HTML fixed and all harmful tags and attributes removed.
+
+Coolness: <tt>dangerous\_html\_document</tt> can be a string OR an IO object (a file, or a socket, or ...). Which makes it particularly easy to sanitize large numbers of docs.
+
Standing on the Shoulders of Giants
-----
@@ -33,11 +63,15 @@ Dryopteris also takes its tag and tag attribute whitelists and its CSS sanitizer
Authors
-----
* [Bryan Helmkamp](http://www.brynary.com/)
-* [Mike Dalessio](http://mike.daless.io/) [(twitter)](http://twitter.com/flavorjones)
+* [Mike Dalessio](http://mike.daless.io/) ([twitter](http://twitter.com/flavorjones))
-Quotes About
+Quotes About Dryopteris
-----
> "dryopteris shields you from xss attacks using nokogiri and NY attitude"
> - [hasmanyjosh](http://blog.hasmanythrough.com/)
+
+> "I just wanted to say thank you for your dryopteris plugin. It is by far the best sanitization I've found."
+> - [catalystmediastudios](http://github.com/catalystmediastudios)
+

0 comments on commit e6931ab

Please sign in to comment.