[1.4.X] Replaced documentation snippets using "gender" with less sens…

…itive examples.

Backport of [7edf231] from master.

docs/howto/custom-model-fields.txt

@@ -334,7 +334,6 @@ Once you have ``MytypeField``, you can use it in any model, just like any other
 
     class Person(models.Model):
         name = models.CharField(max_length=80)
-        gender = models.CharField(max_length=1)
         something_else = MytypeField()
 
 If you aim to build a database-agnostic application, you should account for

docs/ref/forms/widgets.txt

@@ -47,14 +47,12 @@ widget on the field. In the following example, the
     from django.forms.extras.widgets import SelectDateWidget
 
     BIRTH_YEAR_CHOICES = ('1980', '1981', '1982')
-    GENDER_CHOICES = (('m', 'Male'), ('f', 'Female'))
     FAVORITE_COLORS_CHOICES = (('blue', 'Blue'),
                                 ('green', 'Green'),
                                 ('black', 'Black'))
 
     class SimpleForm(forms.Form):
         birth_year = DateField(widget=SelectDateWidget(years=BIRTH_YEAR_CHOICES))
-        gender = ChoiceField(widget=RadioSelect, choices=GENDER_CHOICES)
         favorite_colors = forms.MultipleChoiceField(required=False,
             widget=CheckboxSelectMultiple, choices=FAVORITE_COLORS_CHOICES)
 

docs/ref/models/fields.txt

@@ -103,20 +103,26 @@ element is the human-readable name for the option.
 The choices list can be defined either as part of your model class::
 
     class Foo(models.Model):
-        GENDER_CHOICES = (
-            ('M', 'Male'),
-            ('F', 'Female'),
+        YEAR_IN_SCHOOL_CHOICES = (
+            ('FR', 'Freshman'),
+            ('SO', 'Sophomore'),
+            ('JR', 'Junior'),
+            ('SR', 'Senior'),
+            ('GR', 'Graduate'),
         )
-        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
+        year_in_school = models.CharField(max_length=2, choices=YEAR_IN_SCHOOL_CHOICES)
 
 or outside your model class altogether::
 
-    GENDER_CHOICES = (
-        ('M', 'Male'),
-        ('F', 'Female'),
+    YEAR_IN_SCHOOL_CHOICES = (
+        ('FR', 'Freshman'),
+        ('SO', 'Sophomore'),
+        ('JR', 'Junior'),
+        ('SR', 'Senior'),
+        ('GR', 'Graduate'),
     )
     class Foo(models.Model):
-        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
+        year_in_school = models.CharField(max_length=2, choices=YEAR_IN_SCHOOL_CHOICES)
 
 You can also collect your available choices into named groups that can
 be used for organizational purposes::

docs/ref/models/instances.txt

@@ -550,25 +550,29 @@ might have some of the following methods:
 
 For every field that has :attr:`~django.db.models.Field.choices` set, the
 object will have a ``get_FOO_display()`` method, where ``FOO`` is the name of
-the field. This method returns the "human-readable" value of the field. For
-example, in the following model::
+the field. This method returns the "human-readable" value of the field.
 
-    GENDER_CHOICES = (
-        ('M', 'Male'),
-        ('F', 'Female'),
-    )
-    class Person(models.Model):
-        name = models.CharField(max_length=20)
-        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
-
-...each ``Person`` instance will have a ``get_gender_display()`` method. Example::
+For example::
 
-    >>> p = Person(name='John', gender='M')
-    >>> p.save()
-    >>> p.gender
-    'M'
-    >>> p.get_gender_display()
-    'Male'
+        from django.db import models
+
+        class Person(models.Model):
+            SHIRT_SIZES = (
+                (u'S', u'Small'),
+                (u'M', u'Medium'),
+                (u'L', u'Large'),
+            )
+            name = models.CharField(max_length=60)
+            shirt_size = models.CharField(max_length=2, choices=SHIRT_SIZES)
+
+    ::
+
+        >>> p = Person(name="Fred Flintstone", shirt_size="L")
+        >>> p.save()
+        >>> p.shirt_size
+        u'L'
+        >>> p.get_shirt_size_display()
+        u'Large'
 
 .. method:: Model.get_next_by_FOO(\**kwargs)
 .. method:: Model.get_previous_by_FOO(\**kwargs)

docs/ref/templates/builtins.txt

@@ -771,48 +771,41 @@ regroup
 
 Regroups a list of alike objects by a common attribute.
 
-This complex tag is best illustrated by use of an example: say that ``people``
-is a list of people represented by dictionaries with ``first_name``,
-``last_name``, and ``gender`` keys:
+This complex tag is best illustrated by way of an example: say that "places" is a list of cities represented by dictionaries containing ``"name"``, ``"population"``, and ``"country"`` keys:
 
 .. code-block:: python
 
-    people = [
-        {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
-        {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
-        {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
-        {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
-        {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
+    cities = [
+        {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
+        {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
+        {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
+        {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
+        {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
     ]
 
-...and you'd like to display a hierarchical list that is ordered by gender,
-like this:
+...and you'd like to display a hierarchical list that is ordered by country, like this:
 
-* Male:
+* India
+    * Mumbai: 19,000,000
+    * Calcutta: 15,000,000
+* USA
+    * New York: 20,000,000
+    * Chicago: 7,000,000
+* Japan
+    * Tokyo: 33,000,000
 
-  * George Bush
-  * Bill Clinton
 
-* Female:
-
-  * Margaret Thatcher
-  * Condoleezza Rice
-
-* Unknown:
-
-  * Pat Smith
-
-You can use the ``{% regroup %}`` tag to group the list of people by gender.
+You can use the ``{% regroup %}`` tag to group the list of cities by country.
 The following snippet of template code would accomplish this::
 
-    {% regroup people by gender as gender_list %}
+    {% regroup cities by country as country_list %}
 
     <ul>
-    {% for gender in gender_list %}
-        <li>{{ gender.grouper }}
+    {% for country in country_list %}
+        <li>{{ country.grouper }}
         <ul>
-            {% for item in gender.list %}
-            <li>{{ item.first_name }} {{ item.last_name }}</li>
+            {% for item in country.list %}
+              <li>{{ item.name }}: {{ item.population }}</li>
             {% endfor %}
         </ul>
         </li>
@@ -821,84 +814,72 @@ The following snippet of template code would accomplish this::
 
 Let's walk through this example. ``{% regroup %}`` takes three arguments: the
 list you want to regroup, the attribute to group by, and the name of the
-resulting list. Here, we're regrouping the ``people`` list by the ``gender``
-attribute and calling the result ``gender_list``.
+resulting list. Here, we're regrouping the ``cities`` list by the ``country``
+attribute and calling the result ``country_list``.
 
-``{% regroup %}`` produces a list (in this case, ``gender_list``) of
+``{% regroup %}`` produces a list (in this case, ``country_list``) of
 **group objects**. Each group object has two attributes:
 
-* ``grouper`` -- the item that was grouped by (e.g., the string "Male" or
-  "Female").
-* ``list`` -- a list of all items in this group (e.g., a list of all people
-  with gender='Male').
+* ``grouper`` -- the item that was grouped by (e.g., the string "India" or
+  "Japan").
+* ``list`` -- a list of all items in this group (e.g., a list of all cities
+  with country='India').
 
 Note that ``{% regroup %}`` does not order its input! Our example relies on
-the fact that the ``people`` list was ordered by ``gender`` in the first place.
-If the ``people`` list did *not* order its members by ``gender``, the
-regrouping would naively display more than one group for a single gender. For
-example, say the ``people`` list was set to this (note that the males are not
+the fact that the ``cities`` list was ordered by ``country`` in the first place.
+If the ``cities`` list did *not* order its members by ``country``, the
+regrouping would naively display more than one group for a single country. For
+example, say the ``cities`` list was set to this (note that the countries are not
 grouped together):
 
 .. code-block:: python
 
-    people = [
-        {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
-        {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
-        {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
-        {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
-        {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
+    cities = [
+        {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
+        {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
+        {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
+        {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
+        {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
     ]
 
-With this input for ``people``, the example ``{% regroup %}`` template code
+With this input for ``cities``, the example ``{% regroup %}`` template code
 above would result in the following output:
 
-* Male:
-
-  * Bill Clinton
-
-* Unknown:
-
-  * Pat Smith
-
-* Female:
-
-  * Margaret Thatcher
-
-* Male:
-
-  * George Bush
-
-* Female:
-
-  * Condoleezza Rice
+* India
+    * Mumbai: 19,000,000
+* USA
+    * New York: 20,000,000
+* India
+    * Calcutta: 15,000,000
+* Japan
+    * Tokyo: 33,000,000
 
 The easiest solution to this gotcha is to make sure in your view code that the
 data is ordered according to how you want to display it.
 
 Another solution is to sort the data in the template using the
 :tfilter:`dictsort` filter, if your data is in a list of dictionaries::
 
-    {% regroup people|dictsort:"gender" by gender as gender_list %}
-
+    {% regroup cities|dictsort:"country" by country as country_list %}
 
 Grouping on other properties
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Any valid template lookup is a legal grouping attribute for the regroup
 tag, including methods, attributes, dictionary keys and list items. For
-example, if the "gender" field is a foreign key to a class with
+example, if the "country" field is a foreign key to a class with
 an attribute "description," you could use::
 
-    {% regroup people by gender.description as gender_list %}
+    {% regroup cities by country.description as country_list %}
 
-Or, if ``gender`` is a field with ``choices``, it will have a
+Or, if ``country`` is a field with ``choices``, it will have a
 :meth:`^django.db.models.Model.get_FOO_display` method available as an
 attribute, allowing  you to group on the display string rather than the
 ``choices`` key::
 
-    {% regroup people by get_gender_display as gender_list %}
+    {% regroup cities by get_country_display as country_list %}
 
-``{{ gender.grouper }}`` will now display the value fields from the
+``{{ country.grouper }}`` will now display the value fields from the
 ``choices`` set rather than the keys.
 
 .. templatetag:: spaceless

docs/topics/db/models.txt

@@ -172,21 +172,22 @@ ones:
         from django.db import models
 
         class Person(models.Model):
-            GENDER_CHOICES = (
-                (u'M', u'Male'),
-                (u'F', u'Female'),
+            SHIRT_SIZES = (
+                (u'S', u'Small'),
+                (u'M', u'Medium'),
+                (u'L', u'Large'),
             )
             name = models.CharField(max_length=60)
-            gender = models.CharField(max_length=2, choices=GENDER_CHOICES)
+            shirt_size = models.CharField(max_length=2, choices=SHIRT_SIZES)
 
     ::
 
-        >>> p = Person(name="Fred Flintstone", gender="M")
+        >>> p = Person(name="Fred Flintstone", shirt_size="L")
         >>> p.save()
-        >>> p.gender
-        u'M'
-        >>> p.get_gender_display()
-        u'Male'
+        >>> p.shirt_size
+        u'L'
+        >>> p.get_shirt_size_display()
+        u'Large'
 
 :attr:`~Field.default`
     The default value for the field. This can be a value or a callable