From 4a954cfd11a5d034491f87fcbc920eb97a302bb3 Mon Sep 17 00:00:00 2001
From: Tobias Kunze <r@rixx.de>
Date: Mon, 17 Jun 2019 16:54:55 +0200
Subject: Fixed #30573 -- Rephrased documentation to avoid words that minimise
 the involved difficulty.

This patch does not remove all occurrences of the words in question.
Rather, I went through all of the occurrences of the words listed
below, and judged if they a) suggested the reader had some kind of
knowledge/experience, and b) if they added anything of value (including
tone of voice, etc). I left most of the words alone. I looked at the
following words:

- simply/simple
- easy/easier/easiest
- obvious
- just
- merely
- straightforward
- ridiculous

Thanks to Carlton Gibson for guidance on how to approach this issue, and
to Tim Bell for providing the idea. But the enormous lion's share of
thanks go to Adam Johnson for his patient and helpful review.
---
 docs/ref/forms/api.txt        | 23 ++++++++---------
 docs/ref/forms/fields.txt     | 11 ++++-----
 docs/ref/forms/validation.txt | 57 +++++++++++++++++++++----------------------
 docs/ref/forms/widgets.txt    |  9 +++----
 4 files changed, 49 insertions(+), 51 deletions(-)

(limited to 'docs/ref/forms')

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 70f455fefe..23fbab9aff 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -25,7 +25,7 @@ A :class:`Form` instance is either **bound** to a set of data, or **unbound**.
 
 .. class:: Form
 
-To create an unbound :class:`Form` instance, simply instantiate the class::
+To create an unbound :class:`Form` instance, instantiate the class::
 
     >>> f = ContactForm()
 
@@ -158,8 +158,9 @@ By default, ``as_json()`` does not escape its output. If you are using it for
 something like AJAX requests to a form view where the client interprets the
 response and inserts errors into the page, you'll want to be sure to escape the
 results on the client-side to avoid the possibility of a cross-site scripting
-attack. It's trivial to do so using a JavaScript library like jQuery - simply
-use ``$(el).text(errorText)`` rather than ``.html()``.
+attack. You can do this in JavaScript with ``element.textContent = errorText``
+or with jQuery's ``$(el).text(errorText)`` (rather than its ``.html()``
+function).
 
 If for some reason you don't want to use client-side escaping, you can also
 set ``escape_html=True`` and error messages will be escaped so you can use them
@@ -185,7 +186,7 @@ should be added. If its value is ``None`` the error will be treated as
 a non-field error as returned by :meth:`Form.non_field_errors()
 <django.forms.Form.non_field_errors>`.
 
-The ``error`` argument can be a simple string, or preferably an instance of
+The ``error`` argument can be a string, or preferably an instance of
 ``ValidationError``. See :ref:`raising-validation-error` for best practices
 when defining form errors.
 
@@ -434,7 +435,7 @@ Outputting forms as HTML
 ========================
 
 The second task of a ``Form`` object is to render itself as HTML. To do so,
-simply ``print`` it::
+``print`` it::
 
     >>> f = ContactForm()
     >>> print(f)
@@ -563,7 +564,7 @@ errors. For example, you might want to present required form rows in bold and
 highlight errors in red.
 
 The :class:`Form` class has a couple of hooks you can use to add ``class``
-attributes to required rows or to rows with errors: simply set the
+attributes to required rows or to rows with errors: set the
 :attr:`Form.error_css_class` and/or :attr:`Form.required_css_class`
 attributes::
 
@@ -634,7 +635,7 @@ tags nor ``id`` attributes::
     <p>Cc myself: <input type="checkbox" name="cc_myself"></p>
 
 If ``auto_id`` is set to ``True``, then the form output *will* include
-``<label>`` tags and will simply use the field name as its ``id`` for each form
+``<label>`` tags and will use the field name as its ``id`` for each form
 field::
 
     >>> f = ContactForm(auto_id=True)
@@ -750,7 +751,7 @@ In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are
 displayed in the order in which you define them in your form class. For
 example, in the ``ContactForm`` example, the fields are defined in the order
 ``subject``, ``message``, ``sender``, ``cc_myself``. To reorder the HTML
-output, just change the order in which those fields are listed in the class.
+output, change the order in which those fields are listed in the class.
 
 There are several other ways to customize the order:
 
@@ -833,7 +834,7 @@ pass that in at construction time::
 More granular output
 ====================
 
-The ``as_p()``, ``as_ul()``, and ``as_table()`` methods are simply shortcuts --
+The ``as_p()``, ``as_ul()``, and ``as_table()`` methods are shortcuts --
 they're not the only way a form object can be displayed.
 
 .. class:: BoundField
@@ -1121,8 +1122,8 @@ form data)::
     # Bound form with an image field, data from the request
     >>> f = ContactFormWithMugshot(request.POST, request.FILES)
 
-Constructing an unbound form is the same as always -- just omit both
-form data *and* file data::
+Constructing an unbound form is the same as always -- omit both form data *and*
+file data::
 
     # Unbound form with an image field
     >>> f = ContactFormWithMugshot()
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index aa13d4f021..82d42e2ab9 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -1239,12 +1239,11 @@ method::
 Creating custom fields
 ======================
 
-If the built-in ``Field`` classes don't meet your needs, you can easily create
-custom ``Field`` classes. To do this, just create a subclass of
-``django.forms.Field``. Its only requirements are that it implement a
-``clean()`` method and that its ``__init__()`` method accept the core arguments
-mentioned above (``required``, ``label``, ``initial``, ``widget``,
-``help_text``).
+If the built-in ``Field`` classes don't meet your needs, you can create custom
+``Field`` classes. To do this, create a subclass of ``django.forms.Field``. Its
+only requirements are that it implement a ``clean()`` method and that its
+``__init__()`` method accept the core arguments mentioned above (``required``,
+``label``, ``initial``, ``widget``, ``help_text``).
 
 You can also customize how a field will be accessed by overriding
 :meth:`~django.forms.Field.get_bound_field()`.
diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt
index 72af31d907..188ccca736 100644
--- a/docs/ref/forms/validation.txt
+++ b/docs/ref/forms/validation.txt
@@ -19,10 +19,10 @@ for the best practice in raising ``ValidationError``. If no ``ValidationError``
 is raised, the method should return the cleaned (normalized) data as a Python
 object.
 
-Most validation can be done using `validators`_ - simple helpers that can be
-reused easily. Validators are simple functions (or callables) that take a single
-argument and raise ``ValidationError`` on invalid input. Validators are run
-after the field's ``to_python`` and ``validate`` methods have been called.
+Most validation can be done using `validators`_ - helpers that can be reused.
+Validators are functions (or callables) that take a single argument and raise
+``ValidationError`` on invalid input. Validators are run after the field's
+``to_python`` and ``validate`` methods have been called.
 
 Validation of a form is split into several steps, which can be customized or
 overridden:
@@ -65,9 +65,9 @@ overridden:
   For example, if you wanted to validate that the contents of a
   ``CharField`` called ``serialnumber`` was unique,
   ``clean_serialnumber()`` would be the right place to do this. You don't
-  need a specific field (it's just a ``CharField``), but you want a
-  formfield-specific piece of validation and, possibly,
-  cleaning/normalizing the data.
+  need a specific field (it's a ``CharField``), but you want a
+  formfield-specific piece of validation and, possibly, cleaning/normalizing
+  the data.
 
   The return value of this method replaces the existing value in
   ``cleaned_data``, so it must be the field's value from ``cleaned_data`` (even
@@ -218,16 +218,16 @@ previous features.
 Using validators
 ----------------
 
-Django's form (and model) fields support use of simple utility functions and
-classes known as validators. A validator is merely a callable object or
-function that takes a value and simply returns nothing if the value is valid or
-raises a :exc:`~django.core.exceptions.ValidationError` if not. These can be
-passed to a field's constructor, via the field's ``validators`` argument, or
-defined on the :class:`~django.forms.Field` class itself with the
-``default_validators`` attribute.
+Django's form (and model) fields support use of utility functions and classes
+known as validators. A validator is a callable object or function that takes a
+value and returns nothing if the value is valid or raises a
+:exc:`~django.core.exceptions.ValidationError` if not. These can be passed to a
+field's constructor, via the field's ``validators`` argument, or defined on the
+:class:`~django.forms.Field` class itself with the ``default_validators``
+attribute.
 
-Simple validators can be used to validate values inside the field, let's have
-a look at Django's ``SlugField``::
+Validators can be used to validate values inside the field, let's have a look
+at Django's ``SlugField``::
 
     from django.core import validators
     from django.forms import CharField
@@ -235,9 +235,9 @@ a look at Django's ``SlugField``::
     class SlugField(CharField):
         default_validators = [validators.validate_slug]
 
-As you can see, ``SlugField`` is just a ``CharField`` with a customized
-validator that validates that submitted text obeys to some character rules.
-This can also be done on field definition so::
+As you can see, ``SlugField`` is a ``CharField`` with a customized validator
+that validates that submitted text obeys to some character rules. This can also
+be done on field definition so::
 
     slug = forms.SlugField()
 
@@ -281,8 +281,7 @@ Every form that uses this field will have these methods run before anything
 else can be done with the field's data. This is cleaning that is specific to
 this type of field, regardless of how it is subsequently used.
 
-Let's create a simple ``ContactForm`` to demonstrate how you'd use this
-field::
+Let's create a ``ContactForm`` to demonstrate how you'd use this field::
 
     class ContactForm(forms.Form):
         subject = forms.CharField(max_length=100)
@@ -291,10 +290,10 @@ field::
         recipients = MultiEmailField()
         cc_myself = forms.BooleanField(required=False)
 
-Simply use ``MultiEmailField`` like any other form field. When the
-``is_valid()`` method is called on the form, the ``MultiEmailField.clean()``
-method will be run as part of the cleaning process and it will, in turn, call
-the custom ``to_python()`` and ``validate()`` methods.
+Use ``MultiEmailField`` like any other form field. When the ``is_valid()``
+method is called on the form, the ``MultiEmailField.clean()`` method will be
+run as part of the cleaning process and it will, in turn, call the custom
+``to_python()`` and ``validate()`` methods.
 
 Cleaning a specific field attribute
 -----------------------------------
@@ -403,7 +402,7 @@ work out what works effectively in your particular situation. Our new code
                 self.add_error('cc_myself', msg)
                 self.add_error('subject', msg)
 
-The second argument of ``add_error()`` can be a simple string, or preferably
-an instance of ``ValidationError``. See :ref:`raising-validation-error` for
-more details. Note that ``add_error()`` automatically removes the field
-from ``cleaned_data``.
+The second argument of ``add_error()`` can be a string, or preferably an
+instance of ``ValidationError``. See :ref:`raising-validation-error` for more
+details. Note that ``add_error()`` automatically removes the field from
+``cleaned_data``.
diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
index d649ece6ba..6b341620ee 100644
--- a/docs/ref/forms/widgets.txt
+++ b/docs/ref/forms/widgets.txt
@@ -34,8 +34,7 @@ which widget is used on which field, see the documentation about
 :ref:`built-in-fields`.
 
 However, if you want to use a different widget for a field, you can
-just use the :attr:`~Field.widget` argument on the field definition. For
-example::
+use the :attr:`~Field.widget` argument on the field definition. For example::
 
     from django import forms
 
@@ -127,7 +126,7 @@ need to specify additional attributes at the time when the widget object is
 instantiated and assigned to a form field (and perhaps add some rules to your
 CSS files).
 
-For example, take the following simple form::
+For example, take the following form::
 
     from django import forms
 
@@ -770,8 +769,8 @@ that specifies the template used to render each choice. For example, for the
         </label>
 
     If you decide not to loop over the radio buttons -- e.g., if your template
-    simply includes ``{{ myform.beatles }}`` -- they'll be output in a ``<ul>``
-    with ``<li>`` tags, as above.
+    includes ``{{ myform.beatles }}`` -- they'll be output in a ``<ul>`` with
+    ``<li>`` tags, as above.
 
     The outer ``<ul>`` container receives the ``id`` attribute of the widget,
     if defined, or :attr:`BoundField.auto_id` otherwise.
-- 
cgit v1.3