From d8c17aa10c7f41e692fb6f5d0bf2fab7a90b9374 Mon Sep 17 00:00:00 2001
From: David Smith <smithdc@gmail.com>
Date: Fri, 14 May 2021 08:46:22 +0100
Subject: [PATCH] Refs #32338 -- Improved accessibility of RadioSelect examples
 in docs.

Co-authored-by: Thibaud Colas <thibaudcolas@gmail.com>
---
 docs/intro/tutorial04.txt  | 16 +++----
 docs/ref/forms/widgets.txt | 85 +++++++++++++++++++++-----------------
 2 files changed, 55 insertions(+), 46 deletions(-)

diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt
index 414156b56c..4dae8892ae 100644
--- a/docs/intro/tutorial04.txt
+++ b/docs/intro/tutorial04.txt
@@ -20,16 +20,16 @@ tutorial, so that the template contains an HTML ``<form>`` element:
 .. code-block:: html+django
     :caption: polls/templates/polls/detail.html
 
-    <h1>{{ question.question_text }}</h1>
-
-    {% if error_message %}<p><strong>{{ error_message }}</strong></p>{% endif %}
-
     <form action="{% url 'polls:vote' question.id %}" method="post">
     {% csrf_token %}
-    {% for choice in question.choice_set.all %}
-        <input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}">
-        <label for="choice{{ forloop.counter }}">{{ choice.choice_text }}</label><br>
-    {% endfor %}
+    <fieldset>
+        <legend><h1>{{ question.question_text }}</h1></legend>
+        {% if error_message %}<p><strong>{{ error_message }}</strong></p>{% endif %}
+        {% for choice in question.choice_set.all %}
+            <input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}">
+            <label for="choice{{ forloop.counter }}">{{ choice.choice_text }}</label><br>
+        {% endfor %}
+    </fieldset>
     <input type="submit" value="Vote">
     </form>
 
diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
index 3a930d298c..802ba0055e 100644
--- a/docs/ref/forms/widgets.txt
+++ b/docs/ref/forms/widgets.txt
@@ -718,28 +718,34 @@ that specifies the template used to render each choice. For example, for the
 
     .. code-block:: html+django
 
-        {% for radio in myform.beatles %}
-        <div class="myradio">
-            {{ radio }}
-        </div>
-        {% endfor %}
+        <fieldset>
+            <legend>{{ myform.beatles.label }}</legend>
+            {% for radio in myform.beatles %}
+            <div class="myradio">
+                {{ radio }}
+            </div>
+            {% endfor %}
+        </fieldset>
 
     This would generate the following HTML:
 
     .. code-block:: html
 
-        <div class="myradio">
-            <label for="id_beatles_0"><input id="id_beatles_0" name="beatles" type="radio" value="john" required> John</label>
-        </div>
-        <div class="myradio">
-            <label for="id_beatles_1"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required> Paul</label>
-        </div>
-        <div class="myradio">
-            <label for="id_beatles_2"><input id="id_beatles_2" name="beatles" type="radio" value="george" required> George</label>
-        </div>
-        <div class="myradio">
-            <label for="id_beatles_3"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required> Ringo</label>
-        </div>
+        <fieldset>
+            <legend>Radio buttons</legend>
+            <div class="myradio">
+                <label for="id_beatles_0"><input id="id_beatles_0" name="beatles" type="radio" value="john" required> John</label>
+            </div>
+            <div class="myradio">
+                <label for="id_beatles_1"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required> Paul</label>
+            </div>
+            <div class="myradio">
+                <label for="id_beatles_2"><input id="id_beatles_2" name="beatles" type="radio" value="george" required> George</label>
+            </div>
+            <div class="myradio">
+                <label for="id_beatles_3"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required> Ringo</label>
+            </div>
+        </fieldset>
 
     That included the ``<label>`` tags. To get more granular, you can use each
     radio button's ``tag``, ``choice_label`` and ``id_for_label`` attributes.
@@ -747,36 +753,39 @@ that specifies the template used to render each choice. For example, for the
 
     .. code-block:: html+django
 
-        {% for radio in myform.beatles %}
+        <fieldset>
+            <legend>{{ myform.beatles.label }}</legend>
+            {% for radio in myform.beatles %}
             <label for="{{ radio.id_for_label }}">
                 {{ radio.choice_label }}
                 <span class="radio">{{ radio.tag }}</span>
             </label>
-        {% endfor %}
+            {% endfor %}
+        </fieldset>
 
     ...will result in the following HTML:
 
     .. code-block:: html
 
-        <label for="id_beatles_0">
-            John
-            <span class="radio"><input id="id_beatles_0" name="beatles" type="radio" value="john" required></span>
-        </label>
-
-        <label for="id_beatles_1">
-            Paul
-            <span class="radio"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required></span>
-        </label>
-
-        <label for="id_beatles_2">
-            George
-            <span class="radio"><input id="id_beatles_2" name="beatles" type="radio" value="george" required></span>
-        </label>
-
-        <label for="id_beatles_3">
-            Ringo
-            <span class="radio"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required></span>
-        </label>
+        <fieldset>
+            <legend>Radio buttons</legend>
+            <label for="id_beatles_0">
+                John
+                <span class="radio"><input id="id_beatles_0" name="beatles" type="radio" value="john" required></span>
+            </label>
+            <label for="id_beatles_1">
+                Paul
+                <span class="radio"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required></span>
+            </label>
+            <label for="id_beatles_2">
+                George
+                <span class="radio"><input id="id_beatles_2" name="beatles" type="radio" value="george" required></span>
+            </label>
+            <label for="id_beatles_3">
+                Ringo
+                <span class="radio"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required></span>
+            </label>
+        </fieldset>
 
     If you decide not to loop over the radio buttons -- e.g., if your template
     includes ``{{ myform.beatles }}`` -- they'll be output in a ``<ul>`` with