Forms docs: More emphasis in 'id' value customizability.

1 files changed, 19 insertions, 13 deletions

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 977da4b7be..14092512dc 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -408,21 +408,27 @@ classes, as needed. The HTML will look something like::
 
 .. _ref-forms-api-configuring-label:
 
-Configuring HTML ``<label>`` tags
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Configuring form elements' HTML ``id`` attributes and ``<label>`` tags
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: Form.auto_id
+
+By default, the form rendering methods include:
+
+* HTML ``id`` attributes on the form elements.
 
-An HTML ``<label>`` tag designates which label text is associated with which
-form element. This small enhancement makes forms more usable and more accessible
-to assistive devices. It's always a good idea to use ``<label>`` tags.
+* The corresponding ``<label>`` tags around the labels. An HTML ``<label>`` tag
+  designates which label text is associated with which form element. This small
+  enhancement makes forms more usable and more accessible to assistive devices.
+  It's always a good idea to use ``<label>`` tags.
 
-By default, the form rendering methods include HTML ``id`` attributes on the
-form elements and corresponding ``<label>`` tags around the labels. The ``id``
-attribute values are generated by prepending ``id_`` to the form field names.
-This behavior is configurable, though, if you want to change the ``id``
-convention or remove HTML ``id`` attributes and ``<label>`` tags entirely.
+The ``id`` attribute values are generated by prepending ``id_`` to the form
+field names.  This behavior is configurable, though, if you want to change the
+``id`` convention or remove HTML ``id`` attributes and ``<label>`` tags
+entirely.
 
-Use the ``auto_id`` argument to the ``Form`` constructor to control the label
-and ``id`` behavior. This argument must be ``True``, ``False`` or a string.
+Use the ``auto_id`` argument to the ``Form`` constructor to control the ``id``
+and label behavior. This argument must be ``True``, ``False`` or a string.
 
 If ``auto_id`` is ``False``, then the form output will not include ``<label>``
 tags nor ``id`` attributes::
@@ -503,7 +509,7 @@ appended after any label name when a form is rendered.
     The default ``label_suffix`` is translatable.
 
 It's possible to customize that character, or omit it entirely, using the
- ``label_suffix`` parameter::
+``label_suffix`` parameter::
 
     >>> f = ContactForm(auto_id='id_for_%s', label_suffix='')
     >>> print(f.as_ul())