update readme

1 files changed, 47 insertions, 91 deletions

diff --git a/README.rst b/README.rst
index 2510d53..c30be04 100644
--- a/README.rst
+++ b/README.rst
@@ -1,113 +1,69 @@
 MarkupSafe
 ==========
 
-Implements a unicode subclass that supports HTML strings:
+MarkupSafe implements a text object that escapes characters so it is
+safe to use in HTML and XML. Characters that have special meanings are
+replaced so that they display as the actual characters. This mitigates
+injection attacks, meaning untrusted user input can safely be displayed
+on a page.
 
-.. code-block:: python
 
-    >>> from markupsafe import Markup, escape
-    >>> escape("<script>alert(document.cookie);</script>")
-    Markup(u'&lt;script&gt;alert(document.cookie);&lt;/script&gt;')
-    >>> tmpl = Markup("<em>%s</em>")
-    >>> tmpl % "Peter > Lustig"
-    Markup(u'<em>Peter &gt; Lustig</em>')
-
-If you want to make an object unicode that is not yet unicode
-but don't want to lose the taint information, you can use the
-``soft_unicode`` function.  (On Python 3 you can also use ``soft_str`` which
-is a different name for the same function).
-
-.. code-block:: python
-
-    >>> from markupsafe import soft_unicode
-    >>> soft_unicode(42)
-    u'42'
-    >>> soft_unicode(Markup('foo'))
-    Markup(u'foo')
-
-HTML Representations
---------------------
-
-Objects can customize their HTML markup equivalent by overriding
-the ``__html__`` function:
+Installing
+----------
 
-.. code-block:: python
+Install and update using `pip`_:
 
-    >>> class Foo(object):
-    ...  def __html__(self):
-    ...   return '<strong>Nice</strong>'
-    ...
-    >>> escape(Foo())
-    Markup(u'<strong>Nice</strong>')
-    >>> Markup(Foo())
-    Markup(u'<strong>Nice</strong>')
+.. code-block:: none
 
-Silent Escapes
---------------
+    pip install -U MarkupSafe
 
-Since MarkupSafe 0.10 there is now also a separate escape function
-called ``escape_silent`` that returns an empty string for ``None`` for
-consistency with other systems that return empty strings for ``None``
-when escaping (for instance Pylons' webhelpers).
 
-If you also want to use this for the escape method of the Markup
-object, you can create your own subclass that does that:
+Examples
+--------
 
-.. code-block:: python
+.. code-block:: pycon
 
-    from markupsafe import Markup, escape_silent as escape
-
-    class SilentMarkup(Markup):
-        __slots__ = ()
-
-        @classmethod
-        def escape(cls, s):
-            return cls(escape(s))
-
-New-Style String Formatting
----------------------------
-
-Starting with MarkupSafe 0.21 new style string formats from Python 2.6 and
-3.x are now fully supported.  Previously the escape behavior of those
-functions was spotty at best.  The new implementations operates under the
-following algorithm:
-
-1.  if an object has an ``__html_format__`` method it is called as
-    replacement for ``__format__`` with the format specifier.  It either
-    has to return a string or markup object.
-2.  if an object has an ``__html__`` method it is called.
-3.  otherwise the default format system of Python kicks in and the result
-    is HTML escaped.
+    >>> from markupsafe import Markup, escape
+    >>> # escape replaces special characters and wraps in Markup
+    >>> escape('<script>alert(document.cookie);</script>')
+    Markup(u'&lt;script&gt;alert(document.cookie);&lt;/script&gt;')
+    >>> # wrap in Markup to mark text "safe" and prevent escaping
+    >>> Markup('<strong>Hello</strong>')
+    Markup('<strong>hello</strong>')
+    >>> escape(Markup('<strong>Hello</strong>'))
+    Markup('<strong>hello</strong>')
+    >>> # Markup is a text subclass (str on Python 3, unicode on Python 2)
+    >>> # methods and operators escape their arguments
+    >>> template = Markup("Hello <em>%s</em>")
+    >>> template % '"World"'
+    Markup('Hello <em>&#34;World&#34;</em>')
 
-Here is how you can implement your own formatting:
 
-.. code-block:: python
+Donate
+------
 
-    class User(object):
+The Pallets organization develops and supports MarkupSafe and other
+libraries that use it. In order to grow the community of contributors
+and users, and allow the maintainers to devote more time to the
+projects, `please donate today`_.
 
-        def __init__(self, id, username):
-            self.id = id
-            self.username = username
+.. _please donate today: https://psfmember.org/civicrm/contribute/transact?reset=1&id=20
 
-        def __html_format__(self, format_spec):
-            if format_spec == 'link':
-                return Markup('<a href="/user/{0}">{1}</a>').format(
-                    self.id,
-                    self.__html__(),
-                )
-            elif format_spec:
-                raise ValueError('Invalid format spec')
-            return self.__html__()
 
-        def __html__(self):
-            return Markup('<span class=user>{0}</span>').format(self.username)
+Links
+-----
 
-And to format that user:
+* Website: https://www.palletsprojects.com/p/markupsafe/
+* Documentation: https://markupsafe.readthedocs.io/
+* License: `BSD <https://github.com/pallets/markupsafe/blob/master/LICENSE.rst>`_
+* Releases: https://pypi.org/project/MarkupSafe/
+* Code: https://github.com/pallets/markupsafe
+* Issue tracker: https://github.com/pallets/markupsafe/issues
+* Test status:
 
-.. code-block:: python
+  * Linux, Mac: https://travis-ci.org/pallets/markupsafe
+  * Windows: https://ci.appveyor.com/project/pallets/markupsafe
 
-    >>> user = User(1, 'foo')
-    >>> Markup('<p>User: {0:link}').format(user)
-    Markup(u'<p>User: <a href="/user/1"><span class=user>foo</span></a>')
+* Test coverage: https://codecov.io/gh/pallets/markupsafe
 
-Markupsafe supports Python 2.7 and Python 3.4 and higher.
+.. _pip: https://pip.pypa.io/en/stable/quickstart/