Permalink
Browse files

Change README to Markdown and improve it.

  • Loading branch information...
1 parent ebb72e2 commit 67dab179196a31b17fee34ec5a5996fd7929138e @threedaymonk committed Mar 28, 2011
Showing with 96 additions and 44 deletions.
  1. +96 −0 README.md
  2. +0 −44 README.rdoc
View
@@ -0,0 +1,96 @@
+HTMLEntities
+============
+
+HTML entity encoding and decoding for Ruby
+
+HTMLEntities is a simple library to facilitate encoding and decoding of named
+(`ý` and so on) or numerical (`{` or `Ī`) entities in HTML
+and XHTML documents.
+
+## Usage
+
+HTMLEntities works with UTF-8 (or ASCII) strings only.
+
+Please ensure that your system is set to display UTF-8 before running these
+examples. In Ruby 1.8, you'll need to set `$KCODE = "u"`.
+
+### Decoding
+
+ require 'htmlentities'
+ coder = HTMLEntities.new
+ string = "élan"
+ coder.decode(string) # => "élan"
+
+### Encoding
+
+This is slightly more complicated, due to the various options. The encode
+method takes a variable number of parameters, which tell it which instructions
+to carry out.
+
+ require 'htmlentities'
+ coder = HTMLEntities.new
+ string = "<élan>"
+
+Escape unsafe codepoints only:
+
+ coder.encode(string) # => "&lt;élan&gt;"
+
+Or:
+
+ coder.encode(string, :basic) # => "&lt;élan&gt;"
+
+Escape all entities that have names:
+
+ coder.encode(string, :named) # => "&lt;&eacute;lan&gt;"
+
+Escape all non-ASCII/non-safe codepoints using decimal entities:
+
+ coder.encode(string, :decimal) # => "&#60;&#233;lan&#62;"
+
+As above, using hexadecimal entities:
+
+ coder.encode(string, :hexadecimal) # => "&#x3c;&#xe9;lan&#x3e;"
+
+You can also use several options, e.g. use named entitied for unsafe codepoints, then decimal for all other non-ASCII:
+
+ coder.encode(string, :basic, :decimal) # => "&lt;&#233;lan&gt;"
+
+### Flavours
+
+HTMLEntities knows about three different sets of entities:
+
+* `:xhtml1` – Entities from the XHTML1 doctype
+* `:html4` – Entities from the HTML4 doctype. Differs from +xhtml1+ only by the absence of +&apos+
+* `:expanded` – Entities from a variety of SGML sets
+
+The default is `:xhtml`, but you can override this:
+
+ coder = HTMLEntities.new(:expanded)
+
+## Licence
+
+This code is free to use under the terms of the MIT licence:
+
+Copyright (c) 2005-2009 Paul Battley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+
+## Contact
+
+Send email to `pbattley@gmail.com`.
View
@@ -1,44 +0,0 @@
-== HTMLEntities
-
-HTML entity encoding and decoding for Ruby
-
-The HTMLEntities module facilitates encoding and decoding of
-(X)HTML entities from/to their corresponding UTF-8 codepoints.
-
-To install (requires root/admin privileges):
-
- ruby setup.rb
-
-Alternatively, you can just use the gem.
-
-== Licence
-
-This code is free to use under the terms of the MIT licence:
-
- Copyright (c) 2005-2009 Paul Battley
-
- Permission is hereby granted, free of charge, to any person obtaining a copy
- of this software and associated documentation files (the "Software"), to
- deal in the Software without restriction, including without limitation the
- rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
- sell copies of the Software, and to permit persons to whom the Software is
- furnished to do so, subject to the following conditions:
-
- The above copyright notice and this permission notice shall be included in
- all copies or substantial portions of the Software.
-
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
- FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
- IN THE SOFTWARE.
-
-If you'd like to negotiate a different licence for a specific use, just
-contact me -- I'll almost certainly permit it.
-
-== Contact
-
-Comments are welcome. Send an email to pbattley@gmail.com.
-

0 comments on commit 67dab17

Please sign in to comment.