#2830: add html.escape() helper and move cgi.escape() uses in the standard library to it. It defaults to quote=True and also escapes single quotes, which makes casual use safer. The cgi.escape() interface is not touched, but emits a (silent) PendingDeprecationWarning.
diff --git a/Doc/library/html.rst b/Doc/library/html.rst
new file mode 100644
index 0000000..2c42cf8
--- /dev/null
+++ b/Doc/library/html.rst
@@ -0,0 +1,18 @@
+:mod:`html` --- HyperText Markup Language support
+=================================================
+
+.. module:: html
+ :synopsis: Helpers for manipulating HTML.
+
+.. versionadded:: 3.2
+
+
+This module defines utilities to manipulate HTML.
+
+.. function:: escape(s, quote=True)
+
+ Convert the characters ``&``, ``<`` and ``>`` in string *s* to HTML-safe
+ sequences. Use this if you need to display text that might contain such
+ characters in HTML. If the optional flag *quote* is true, the characters
+ (``"``) and (``'``) are also translated; this helps for inclusion in an HTML
+ attribute value delimited by quotes, as in ``<a href="...">``.