From 56e75eace520a78cbee07570706519b0680b7d29 Mon Sep 17 00:00:00 2001
From: Peter G Kritikos <petergeorgekritikos@gmail.com>
Date: Wed, 4 Mar 2020 18:40:54 -0500
Subject: [PATCH 1/2] Move HTML escaping example back to Variable Rules.

Demonstration of markupsafe's escape function was in the Minimal
Application example, but the minimal example does not accept user
input.
---
 docs/quickstart.rst | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 71336a22..41cafdf4 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -15,13 +15,12 @@ A minimal Flask application looks something like this:
 .. code-block:: python
 
     from flask import Flask
-    from markupsafe import escape
 
     app = Flask(__name__)
 
     @app.route("/")
     def hello_world():
-        return f"<p>Hello, {escape(name)}!</p>"
+        return "<p>Hello, World!</p>"
 
 So what did that code do?
 
@@ -38,14 +37,6 @@ So what did that code do?
     browser. The default content type is HTML, so HTML in the string
     will be rendered by the browser.
 
-.. note:: HTML escaping
-
-    When returning HTML (the default response type in Flask), any user
-    input rendered in the output must be escaped to protect from
-    injection attacks. HTML templates in Jinja, introduced later, will
-    do this automatically. :func:`~markupsafe.escape`, shown above, can
-    be used manually. It's omitted for brevity in the examples below.
-
 Save it as :file:`hello.py` or something similar. Make sure to not call
 your application :file:`flask.py` because this would conflict with Flask
 itself.
@@ -210,17 +201,17 @@ of the argument like ``<converter:variable_name>``. ::
     @app.route('/user/<username>')
     def show_user_profile(username):
         # show the user profile for that user
-        return f'User {username}'
+        return f'User {escape(username)}'
 
     @app.route('/post/<int:post_id>')
     def show_post(post_id):
         # show the post with the given id, the id is an integer
-        return f'Post {post_id}'
+        return f'Post {escape(post_id)}'
 
     @app.route('/path/<path:subpath>')
     def show_subpath(subpath):
         # show the subpath after /path/
-        return f'Subpath {subpath}'
+        return f'Subpath {escape(subpath)}'
 
 Converter types:
 
@@ -232,6 +223,15 @@ Converter types:
 ``uuid``   accepts UUID strings
 ========== ==========================================
 
+.. note:: HTML escaping
+
+    When returning HTML (the default response type in Flask), any user
+    input rendered in the output must be escaped to protect from
+    injection attacks. HTML templates in Jinja, introduced later, will
+    do this automatically. :func:`~markupsafe.escape`, shown above, can
+    be used manually.
+
+
 Unique URLs / Redirection Behavior
 ``````````````````````````````````
 

From 57f9623b0835cbae06b25d7329cda480539049c3 Mon Sep 17 00:00:00 2001
From: David Lord <davidism@gmail.com>
Date: Thu, 2 Apr 2020 12:41:35 -0700
Subject: [PATCH 2/2] move html escaping to dedicated section

---
 docs/quickstart.rst | 42 +++++++++++++++++++++++++++++++-----------
 1 file changed, 31 insertions(+), 11 deletions(-)

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 41cafdf4..d3a481ee 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -168,6 +168,34 @@ documentation`_.
 Have another debugger in mind? See :ref:`working-with-debuggers`.
 
 
+HTML Escaping
+-------------
+
+When returning HTML (the default response type in Flask), any
+user-provided values rendered in the output must be escaped to protect
+from injection attacks. HTML templates rendered with Jinja, introduced
+later, will do this automatically.
+
+:func:`~markupsafe.escape`, shown here, can be used manually. It is
+omitted in most examples for brevity, but you should always be aware of
+how you're using untrusted data.
+
+.. code-block:: python
+
+    from markupsafe import escape
+
+    @app.route("/<name>")
+    def hello(name):
+        return f"Hello, {escape(name)}!"
+
+If a user managed to submit the name ``<script>alert("bad")</script>``,
+escaping causes it to be rendered as text, rather than running the
+script in the user's browser.
+
+``<name>`` in the route captures a value from the URL and passes it to
+the view function. These variable rules are explained below.
+
+
 Routing
 -------
 
@@ -201,17 +229,17 @@ of the argument like ``<converter:variable_name>``. ::
     @app.route('/user/<username>')
     def show_user_profile(username):
         # show the user profile for that user
-        return f'User {escape(username)}'
+        return f'User {username}'
 
     @app.route('/post/<int:post_id>')
     def show_post(post_id):
         # show the post with the given id, the id is an integer
-        return f'Post {escape(post_id)}'
+        return f'Post {post_id}'
 
     @app.route('/path/<path:subpath>')
     def show_subpath(subpath):
         # show the subpath after /path/
-        return f'Subpath {escape(subpath)}'
+        return f'Subpath {subpath}'
 
 Converter types:
 
@@ -223,14 +251,6 @@ Converter types:
 ``uuid``   accepts UUID strings
 ========== ==========================================
 
-.. note:: HTML escaping
-
-    When returning HTML (the default response type in Flask), any user
-    input rendered in the output must be escaped to protect from
-    injection attacks. HTML templates in Jinja, introduced later, will
-    do this automatically. :func:`~markupsafe.escape`, shown above, can
-    be used manually.
-
 
 Unique URLs / Redirection Behavior
 ``````````````````````````````````