replace latin abbreviations with english phrases & updated docs guidelines

- added sub-section to language part of general_guidelines.md
- fixes #8860

CHANGELOG.txt

@@ -2204,6 +2204,7 @@ Changelog
  * Added a system check to warn if Pillow is compiled without JPEG / PNG support
  * Page chooser now prevents users from selecting the root node where this would be invalid
  * New translations for Dutch (Netherlands), Georgian, Swedish and Turkish (Turkey)
+ * Replace latin abbreviations (i.e. / e.g.) with common English phrases so that documentation is easier to understand (Dominik Lech)
  * Fix: Page slugs are no longer auto-updated from the page title if the page is already published
  * Fix: Deleting a page permission from the groups admin UI does not immediately submit the form
  * Fix: Wagtail userbar is shown on pages that do not pass a `page` variable to the template (e.g. because they override the `serve` method)

CONTRIBUTORS.rst

@@ -613,6 +613,7 @@ Contributors
 * Bernd de Ridder
 * Stefano Silvestri
 * Alexander Rogovskyy
+* Dominik Lech
 
 
 Translators

client/src/entrypoints/admin/core.js

@@ -313,7 +313,7 @@ $(() => {
       // eslint-disable-next-line @typescript-eslint/no-use-before-define
       const currentQuery = getURLParam('q');
       // only do the query if it has changed for trimmed queries
-      // eg. " " === "" and "firstword " ==== "firstword"
+      // for example - " " === "" and "firstword " ==== "firstword"
       if (currentQuery.trim() !== newQuery.trim()) {
         $inputContainer.addClass(workingClasses);
         searchNextIndex++;

client/src/entrypoints/admin/telepath/blocks.js

@@ -47,11 +47,11 @@ wagtailStreamField.blocks = {
 function initBlockWidget(id) {
   /*
   Initialises the top-level element of a BlockWidget
-  (i.e. the form widget for a StreamField).
+  (the form widget for a StreamField).
   Receives the ID of a DOM element with the attributes:
     data-block: JSON-encoded block definition to be passed to telepath.unpack
       to obtain a Javascript representation of the block
-      (i.e. an instance of one of the Block classes below)
+      (an instance of one of the Block classes below)
     data-value: JSON-encoded value for this block
   */
 

docs/_templates/layout.html

@@ -17,7 +17,7 @@
         /**
          * Get version of the currently served docs.
          *
-         * PR builds have their version set to the PR ID (e.g. "6753").
+         * PR builds have their version set to the PR ID (for example "6753").
          * If the docs are built for a PR, use the "latest" search index.
          * Otherwise, use the search index for the current version.
          */

docs/advanced_topics/api/v2/configuration.md

@@ -63,7 +63,7 @@ from wagtail.documents.api.v2.views import DocumentsAPIViewSet
 api_router = WagtailAPIRouter('wagtailapi')
 
 # Add the three endpoints using the "register_endpoint" method.
-# The first parameter is the name of the endpoint (eg. pages, images). This
+# The first parameter is the name of the endpoint (such as pages, images). This
 # is used in the URL of the endpoint
 # The second parameter is the endpoint class that handles the requests
 api_router.register_endpoint('pages', PagesAPIViewSet)

docs/advanced_topics/boundblocks_and_values.md

@@ -108,7 +108,7 @@ In summary, interactions between BoundBlocks and plain values work according to
 1. When iterating over the value of a StreamField or StreamBlock (as in `{% for block in page.body %}`), you will get back a sequence of BoundBlocks.
 2. If you have a BoundBlock instance, you can access the plain value as `block.value`.
 3. Accessing a child of a StructBlock (as in `value.heading`) will return a plain value; to retrieve the BoundBlock instead, use `value.bound_blocks.heading`.
-4. Likewise, accessing children of a ListBlock (e.g. `for item in value`) will return plain values; to retrieve BoundBlocks instead, use `value.bound_blocks`.
+4. Likewise, accessing children of a ListBlock (for example `for item in value`) will return plain values; to retrieve BoundBlocks instead, use `value.bound_blocks`.
 5. StructBlock and StreamBlock values always know how to render their own templates, even if you only have the plain value rather than the BoundBlock.
 
 ```{versionchanged} 2.16

docs/advanced_topics/deploying.md

@@ -49,7 +49,7 @@ If you have successfully installed Wagtail on your platform or infrastructure, p
 ### Static files
 
 As with all Django projects, static files are not served by the Django application server in production
-(i.e. outside of the `manage.py runserver` command); these need to be handled separately at the web server level.
+Outside of the `manage.py runserver` command these need to be handled separately at the web server level.
 See [Django's documentation on deploying static files](django:howto/static-files/deployment).
 
 The JavaScript and CSS files used by the Wagtail admin frequently change between releases of Wagtail - it's important to avoid serving outdated versions of these files due to browser or server-side caching, as this can cause hard-to-diagnose issues.

docs/advanced_topics/embeds.md

@@ -298,7 +298,7 @@ class ExampleFinder(EmbedFinder):
         return {
             'title': "Title of the content",
             'author_name': "Author name",
-            'provider_name': "Provider name (eg. YouTube, Vimeo, etc)",
+            'provider_name': "Provider name (such as YouTube, Vimeo, etc)",
             'type': "Either 'photo', 'video', 'link' or 'rich'",
             'thumbnail_url': "URL to thumbnail image",
             'width': width_in_pixels,

docs/advanced_topics/i18n.md

@@ -274,7 +274,7 @@ urlpatterns += i18n_patterns(
 
 ##### Bypass language prefix for the default language
 
-If you want your default language to have URLs that resolve normally without a language prefix, 
+If you want your default language to have URLs that resolve normally without a language prefix,
 you can set the `prefix_default_language` parameter of `i18n_patterns` to `False`.
 For example, if you have your languages configured like this:
 
@@ -289,7 +289,7 @@ WAGTAIL_CONTENT_LANGUAGES = LANGUAGES = [
     ('fr', "French"),
 ]
 
-# ... 
+# ...
 ```
 
 And your `urls.py` configured like this:
@@ -298,7 +298,7 @@ And your `urls.py` configured like this:
 # myproject/urls.py
 # ...
 
-# These URLs will be available under a language code prefix only for languages that 
+# These URLs will be available under a language code prefix only for languages that
 # are not set as default in LANGUAGE_CODE.
 
 urlpatterns += i18n_patterns(
@@ -308,7 +308,7 @@ urlpatterns += i18n_patterns(
 )
 ```
 
-Your URLs will now be prefixed only for the French version of your website, e.g.
+Your URLs will now be prefixed only for the French version of your website, for example:
 
 ```
 - /search/

docs/advanced_topics/images/custom_image_model.md

@@ -22,7 +22,7 @@ from wagtail.images.models import Image, AbstractImage, AbstractRendition
 class CustomImage(AbstractImage):
     # Add any extra fields to image here
 
-    # eg. To add a caption field:
+    # To add a caption field:
     # caption = models.CharField(max_length=255, blank=True)
 
     admin_form_fields = Image.admin_form_fields + (

docs/advanced_topics/images/feature_detection.md

@@ -90,7 +90,7 @@ For example, in an app's [AppConfig.ready](https://docs.djangoproject.com/en/2.2
 
 The face detection algorithm produces a focal area that is tightly cropped to the face rather than the whole head.
 
-For images with a single face this can be okay in some cases, e.g. thumbnails, it might be overly tight for "headshots".
+For images with a single face this can be okay in some cases (thumbnails for example), it might be overly tight for "headshots".
 Image renditions can encompass more of the head by reducing the crop percentage (`-c<percentage>`), at the end of the resize-rule, down to as low as 0%:
 
 ```html+django

docs/advanced_topics/images/image_serve_view.md

@@ -152,7 +152,7 @@ class MySendFileView(SendFileView):
 ```
 
 You can also customise it to serve private files. For example, if the only need
-is to be authenticated (e.g. for Django >= 1.9):
+is to be authenticated (Django >= 1.9):
 
 ```python
 from django.contrib.auth.mixins import LoginRequiredMixin

docs/conf.py

@@ -213,7 +213,7 @@ html_use_index = False
 # base URL from which the finished HTML is served.
 # html_use_opensearch = ''
 
-# This is the file name suffix for HTML files (e.g. ".xhtml").
+# This is the file name suffix for HTML files (for example ".xhtml").
 # html_file_suffix = None
 
 # Output file base name for HTML help builder.

docs/contributing/general_guidelines.md

@@ -4,6 +4,19 @@
 
 British English is preferred for user-facing text; this text should also be marked for translation (using the `django.utils.translation.gettext` function and `{% trans %}` template tag, for example). However, identifiers within code should use American English if the British or international spelling would conflict with built-in language keywords; for example, CSS code should consistently use the spelling `color` to avoid inconsistencies like `background-color: $colour-red`.
 
+### Latin phrases and abbreviations
+
+Try to avoid Latin phrases (such as `ergo` or `de facto`) and abbreviations (such as `i.e.` or `e.g.`), and use common English phrases instead. Alternatively find a simpler way to communicate the concept or idea to the reader. The exception is `etc.` which can be used when space is limited.
+
+Examples:
+
+| Don't use this | Use this instead     |
+| -------------- | -------------------- |
+| e.g.           | for example, such as |
+| i.e.           | that is              |
+| viz.           | namely               |
+| ergo           | therefore            |
+
 ## File names
 
 Where practical, try to adhere to the existing convention of file names within the folder where added.

docs/contributing/issue_tracking.md

@@ -16,8 +16,8 @@ The possible milestones that it might be assigned to are as follows:
 
 -   **invalid** (closed): this issue doesn't identify a specific action to be taken, or the action is not one that we want to take. For example - a bug report for something that's working as designed, or a feature request for something that's actively harmful.
 -   **real-soon-now**: no-one on the core team has resources allocated to work on this right now, but we know it's a pain point, and it will be prioritised whenever we next get a chance to choose something new to work on. In practice, that kind of free choice doesn't happen very often - there are lots of pressures determining what we work on from day to day - so if this is a feature or fix you need, we encourage you to work on it and contribute a pull request, rather than waiting for the core team to get round to it!
--   A specific version number (eg. **1.6**): the issue is important enough that it needs to be fixed in this version. There are resources allocated and/or plans to work on the issue in the given version.
--   No milestone: the issue is accepted as valid once the `status:Unconfirmed` label is removed (i.e. it's a bug report for a legitimate bug, or a useful feature request) but is not deemed a priority to work on (in the opinion of the core team). For example - a bug that's only cosmetic, or a feature that would be kind of neat but not really essential. There are no resources allocated to it - feel free to take it on!
+-   A specific version number (for example **1.6**): the issue is important enough that it needs to be fixed in this version. There are resources allocated and/or plans to work on the issue in the given version.
+-   No milestone: the issue is accepted as valid once the `status:Unconfirmed` label is removed (when it's confirmed as a report for a legitimate bug, or a useful feature request) but is not deemed a priority to work on (in the opinion of the core team). For example - a bug that's only cosmetic, or a feature that would be kind of neat but not really essential. There are no resources allocated to it - feel free to take it on!
 
 On some occasions it may take longer for the core team to classify an issue into a milestone. For example:
 

docs/contributing/release_process.md

@@ -199,10 +199,10 @@ in the `A.B+1` cycle.
 
 ### Bug-fix releases
 
-After a feature release (e.g. A.B), the previous release will go into bugfix
+After a feature release `A.B`, the previous release will go into bugfix
 mode.
 
-The branch for the previous feature release (e.g. `stable/A.B-1.x`) will
+The branch for the previous feature release `stable/A.B-1.x` will
 include bugfixes. Critical bugs fixed on `main` must _also_ be fixed on the
 bugfix branch; this means that commits need to cleanly separate bug fixes from
 feature additions. The developer who commits a fix to `main` will be

docs/editor_manual/copying_aliasing_existing_pages.md

@@ -47,6 +47,6 @@ Here is how to create an alias to an existing page:
 
 ![The aliased page appearing under the new parent page in the Explorer page.](../_static/images/screen12.7_3_alias_page_new_parent.png)
 
--   When you try to edit the aliased page, you are notified that it is an alias of another page. You will then be offered two options: edit the original page (with changes appearing in both places) or convert the alias page into an ordinary page (i.e. a conventional copy, not updated when the original changes).
+-   When you try to edit the aliased page, you are notified that it is an alias of another page. You will then be offered two options: edit the original page (with changes appearing in both places) or convert the alias page into an ordinary page (a conventional copy, not updated when the original changes).
 
 ![Editing an alias page notifies it is an alias and offers to either edit the original page or change the alias to an ordinary page.](../_static/images/screen12.7_4_alias_page_edit_notification.png)

docs/editor_manual/getting_started.md

@@ -9,7 +9,7 @@ For the purposes of this documentation we will be using the URL, **www.example.c
 ## Logging in
 
 -   The first port of call for an editor is the login page for the administrator interface.
--   Access this by adding **/admin** onto the end of your root URL (e.g. `www.example.com/admin`).
+-   Access this by adding **/admin** onto the end of your root URL (for example `www.example.com/admin`).
 -   Enter your username and password and click **Sign in**.
 
 ![](../_static/images/screen01_login.png)

docs/editor_manual/new_pages/inserting_images.md

@@ -37,7 +37,7 @@ The image below demonstrates finding and inserting an image that is already pres
 
 1. You must include an image title for your uploaded image
 2. Click the _Choose file_ button to choose an image from your computer.
-3. _Tags_ allows you to associate tags with the image you are uploading. This allows them to be more easily found when searching. Each tag should be separated by a space. Good practice for creating multiple word tags is to use an underscore between each word (e.g. western_yellow_wagtail).
+3. _Tags_ allows you to associate tags with the image you are uploading. This allows them to be more easily found when searching. Each tag should be separated by a space. Good practice for creating multiple word tags is to use an underscore between each word (for example western_yellow_wagtail).
 4. Click _Upload_ to insert the uploaded image into the carousel. The image will also be added to the main CMS image library for reuse in other content.
 
 ## Inserting images using the rich text field

docs/editor_manual/new_pages/the_promote_tab.md

@@ -8,7 +8,7 @@ The Promote tab is where you can configure a page's metadata, to help search eng
 
 **For Search Engines**
 
--   **Slug:** The section of the URL that appears after your website's domain e.g. `http://domain.com/blog/[my-slug]/`. This is automatically generated from the main page title, which is set in the Content tab. Slugs should be entirely lowercase, with words separated by hyphens (-). It is recommended that you don't change a page's slug once a page is published.
+-   **Slug:** The section of the URL that appears after your website's domain, for example `http://domain.com/blog/[my-slug]/`. This is automatically generated from the main page title, which is set in the Content tab. Slugs should be entirely lowercase, with words separated by hyphens (-). It is recommended that you don't change a page's slug once a page is published.
 -   **Title tag:** This is the bold headline that often shows up search engine results. This is one of the most significant elements of how search engines rank the page. The keywords used here should align with the keywords you wish to be found for. If you don't think this field is working, ask your developers to check they have configured the site to output the appropriate tags on the frontend.
 -   **Meta description:** This is the descriptive text displayed underneath a headline in search engine results. It is designed to explain what this page is about. It has no impact on how search engines rank your content, but it can impact on the likelihood that a user will click your result. Ideally 140 to 155 characters in length. If you don't think this field is working, ask your developers to check they have configured the site to output the appropriate tags on the frontend.
 

docs/extending/audit_log.md

@@ -23,7 +23,7 @@ The `wagtail.log_actions.log` function can be used to add logging to your own co
    :param instance: The model instance that the action is performed on
    :param action: The code name for the action being performed. This can be one of the names listed below, or a custom action defined through the :ref:`register_log_actions` hook.
    :param user: Optional - the user initiating the action. For actions logged within an admin view, this defaults to the logged-in user.
-   :param uuid: Optional - log entries given the same UUID indicates that they occurred as part of the same user action (e.g. a page being immediately published on creation).
+   :param uuid: Optional - log entries given the same UUID indicates that they occurred as part of the same user action (for example a page being immediately published on creation).
    :param title: The string representation of the instance being logged. By default, Wagtail will attempt to use the instance's ``str`` representation, or ``get_admin_display_title`` for page objects.
    :param data: Optional - a dictionary of additional JSON-serialisable data to store against the log entry
 ```

docs/extending/custom_tasks.md

@@ -172,7 +172,7 @@ Returns the name of a custom template to be used in rendering the data entry mod
 
 `Task.on_action(task_state, user, action_name, **kwargs)`:
 
-This performs the actions specified in `Task.get_actions(page, user)`: it is passed an action name, eg `approve`, and the relevant task state. By default, it calls `approve` and `reject` methods on the task state when the corresponding action names are passed through. Any additional data entered in a modal (see `get_form_for_action` and `get_actions`) is supplied as kwargs.
+This performs the actions specified in `Task.get_actions(page, user)`: it is passed an action name, for example `approve`, and the relevant task state. By default, it calls `approve` and `reject` methods on the task state when the corresponding action names are passed through. Any additional data entered in a modal (see `get_form_for_action` and `get_actions`) is supplied as kwargs.
 
 For example, let's say we wanted to add an additional option: cancelling the entire workflow:
 
@@ -237,7 +237,7 @@ class BaseUserApprovalTaskStateEmailNotifier(EmailNotificationMixin, Notifier):
 
     def can_handle(self, instance, **kwargs):
         if super().can_handle(instance, **kwargs) and isinstance(instance.task.specific, UserApprovalTask):
-            # Don't send notifications if a Task has been cancelled and then resumed - ie page was updated to a new revision
+            # Don't send notifications if a Task has been cancelled and then resumed - when page was updated to a new revision
             return not TaskState.objects.filter(workflow_state=instance.workflow_state, task=instance.task, status=TaskState.STATUS_CANCELLED).exists()
         return False
 

docs/extending/customising_group_views.md

@@ -86,7 +86,7 @@ Add the field to the group 'edit'/'create' templates:
 {% endblock extra_fields %}
 ```
 
-Finally we configure the `wagtail.users` application to use the custom viewset, by setting up a custom `AppConfig` class. Within your project folder (i.e. the package containing the top-level settings and urls modules), create `apps.py` (if it does not exist already) and add:
+Finally we configure the `wagtail.users` application to use the custom viewset, by setting up a custom `AppConfig` class. Within your project folder (which will be the package containing the top-level settings and urls modules), create `apps.py` (if it does not exist already) and add:
 
 ```python
 from wagtail.users.apps import WagtailUsersAppConfig

docs/extending/extending_draftail.md

@@ -4,9 +4,9 @@ Wagtail’s rich text editor is built with [Draftail](https://www.draftail.org/)
 
 Plugins come in three types:
 
--   Inline styles – To format a portion of a line, eg. `bold`, `italic`, `monospace`.
--   Blocks – To indicate the structure of the content, eg. `blockquote`, `ol`.
--   Entities – To enter additional data/metadata, eg. `link` (with a URL), `image` (with a file).
+-   Inline styles – To format a portion of a line, for example `bold`, `italic`, `monospace`.
+-   Blocks – To indicate the structure of the content, for example `blockquote`, `ol`.
+-   Entities – To enter additional data/metadata, for example `link` (with a URL), `image` (with a file).
 
 All of these plugins are created with a similar baseline, which we can demonstrate with one of the simplest examples – a custom feature for an inline style of `mark`. Place the following in a `wagtail_hooks.py` file in any installed app:
 
@@ -64,7 +64,7 @@ For detailed configuration options, head over to the [Draftail documentation](ht
 
 -   The `type` is the only mandatory piece of information.
 -   To display the control in the toolbar, combine `icon`, `label` and `description`.
--   The controls’ `icon` can be a string to use an icon font with CSS classes, say `'icon': 'fas fa-user',`. It can also be an array of strings, to use SVG paths, or SVG symbol references eg. `'icon': ['M100 100 H 900 V 900 H 100 Z'],`. The paths need to be set for a 1024x1024 viewbox.
+-   The controls’ `icon` can be a string to use an icon font with CSS classes, say `'icon': 'fas fa-user',`. It can also be an array of strings, to use SVG paths, or SVG symbol references for example `'icon': ['M100 100 H 900 V 900 H 100 Z'],`. The paths need to be set for a 1024x1024 viewbox.
 
 ## Creating new inline styles
 
@@ -145,7 +145,7 @@ To go further, please look at the [Draftail documentation](https://www.draftail.
 
 Here is a detailed example to showcase how those tools are used in the context of Wagtail.
 For the sake of our example, we can imagine a news team working at a financial newspaper.
-They want to write articles about the stock market, refer to specific stocks anywhere inside of their content (eg. "$TSLA" tokens in a sentence), and then have their article automatically enriched with the stock’s information (a link, a number, a sparkline).
+They want to write articles about the stock market, refer to specific stocks anywhere inside of their content (for example "$TSLA" tokens in a sentence), and then have their article automatically enriched with the stock’s information (a link, a number, a sparkline).
 
 The editor toolbar could contain a "stock chooser" that displays a list of available stocks, then inserts the user’s selection as a textual token. For our example, we will just pick a stock at random:
 

docs/extending/rich_text_internals.md

@@ -53,7 +53,7 @@ A number of additional constraints apply to `<a linktype="...">` and `<embed emb
 
 -   The tag name and attributes must be lower-case
 -   Attribute values must be quoted with double-quotes
--   `embed` elements must use XML self-closing tag syntax (i.e. end in `/>` instead of a closing `</embed>` tag)
+-   `embed` elements must use XML self-closing tag syntax (those that end in `/>` instead of a closing `</embed>` tag)
 -   The only HTML entities permitted in attribute values are `&lt;`, `&gt;`, `&amp;` and `&quot;`
 
 ## The feature registry
@@ -178,7 +178,7 @@ def register_external_link(features):
     features.register_link_type(NoFollowExternalLinkHandler)
 ```
 
-Similarly you can use `email` linktype to add a custom rewrite handler for email links (e.g. to obfuscate emails in rich text).
+Similarly you can use `email` linktype to add a custom rewrite handler for email links (for example to obfuscate emails in rich text).
 
 ```{eval-rst}
 .. method:: FeatureRegistry.register_embed_type(handler)

docs/getting_started/tutorial.md

@@ -47,7 +47,7 @@ $ source mysite/env/bin/activate
 **For other shells** see the [`venv` documentation](https://docs.python.org/3/library/venv.html).
 
 ```{note}
-If you're using version control (e.g. git), `mysite` will be the directory for your project.
+If you're using version control (such as git), `mysite` will be the directory for your project.
 The `env` directory inside of it should be excluded from any version control.
 ```
 
@@ -97,7 +97,7 @@ If you haven't updated the project settings, this will be a SQLite database file
 $ python manage.py migrate
 ```
 
-This command ensures that the tables in your database are matched to the models in your project. Every time you alter your model (eg. you may add a field to a model) you will need to run this command in order to update the database.
+This command ensures that the tables in your database are matched to the models in your project. Every time you alter your model (for example you may add a field to a model) you will need to run this command in order to update the database.
 
 ### Create an admin user
 
@@ -159,7 +159,7 @@ the page by selecting _Publish_ at the bottom of the page editor, rather than _S
 The page template now needs to be updated to reflect the changes made
 to the model. Wagtail uses normal Django templates to render each page
 type. By default, it will look for a template filename formed from the app and model name,
-separating capital letters with underscores (e.g. HomePage within the 'home' app becomes
+separating capital letters with underscores (for example HomePage within the 'home' app becomes
 `home/home_page.html`). This template file can exist in any location recognised by
 [Django's template rules](https://docs.djangoproject.com/en/stable/intro/tutorial03/#write-views-that-actually-do-something); conventionally it is placed under a `templates` folder within the app.
 
@@ -600,7 +600,7 @@ This method is now available from our templates. Update `blog_index_page.html` t
 
 ### Tagging Posts
 
-Let's say we want to let editors "tag" their posts, so that readers can, e.g.,
+Let's say we want to let editors "tag" their posts, so that readers can, for example,
 view all bicycle-related content together. For this, we'll need to invoke
 the tagging system bundled with Wagtail, attach it to the `BlogPage`
 model and content panels, and render linked tags on the blog post template.

docs/reference/contrib/forms/customisation.md

@@ -630,7 +630,7 @@ class FormPage(AbstractEmailForm):
 First, make the new field type available in the page editor by changing your `FormField` model.
 
 -   Create a new set of choices which includes the original `FORM_FIELD_CHOICES` along with new field types you want to make available.
--   Each choice must contain a unique key and a human readable name of the field, e.g. `('slug', 'URL Slug')`
+-   Each choice must contain a unique key and a human readable name of the field, for example `('slug', 'URL Slug')`
 -   Override the `field_type` field in your `FormField` model with `choices` attribute using these choices.
 -   You will need to run `./manage.py makemigrations` and `./manage.py migrate` after this step.
 
@@ -638,7 +638,7 @@ Then, create and use a new form builder class.
 
 -   Define a new form builder class that extends the `FormBuilder` class.
 -   Add a method that will return a created Django form field for the new field type.
--   Its name must be in the format: `create_<field_type_key>_field`, e.g. `create_slug_field`
+-   Its name must be in the format: `create_<field_type_key>_field`, for example `create_slug_field`
 -   Override the `form_builder` attribute in your form page model to use your new form builder class.
 
 Example:

docs/reference/contrib/frontendcache.rst

@@ -131,7 +131,7 @@ In case you run multiple sites with Wagtail and each site has its CloudFront dis
     }
 
 .. note::
-    In most cases, absolute URLs with ``www`` prefixed domain names should be used in your mapping. Only drop the ``www`` prefix if you're absolutely sure you're not using it (e.g. a subdomain).
+    In most cases, absolute URLs with ``www`` prefixed domain names should be used in your mapping. Only drop the ``www`` prefix if you're absolutely sure you're not using it (for example a subdomain).
 
 Azure CDN
 ^^^^^^^^^

docs/reference/contrib/modeladmin/create_edit_delete_views.md

@@ -1,7 +1,7 @@
 # Customising `CreateView`, `EditView` and `DeleteView`
 
 ```{note}
-**NOTE:** `modeladmin` only provides 'create', 'edit' and 'delete' functionality for non page type models (i.e. models that do not extend `wagtailcore.models.Page`). If your model is a 'page type' model, customising any of the following will not have any effect:
+**NOTE:** `modeladmin` only provides 'create', 'edit' and 'delete' functionality for non page type models (models that do not extend `wagtailcore.models.Page`). If your model is a 'page type' model, customising any of the following will not have any effect:
 ```
 
 (modeladmin_edit_handler_customisation)=
@@ -157,7 +157,7 @@ When using CreateView or EditView to create or update model instances, this valu
 
 **Expected value**: A dict mapping prepopulated fields to a tuple of fields to prepopulate from
 
-When using CreateView or EditView to create or update model instances, the fields corresponding to the keys in the dict are prepopulated using the fields in the corresponding tuple. The main use for this functionality is to automatically generate the value for SlugField fields from one or more other fields. The generated value is produced by concatenating the values of the source fields, and then by transforming that result into a valid slug (e.g. substituting dashes for spaces; lowercasing ASCII letters; and removing various English stop words such as ‘a’, ‘an’, ‘as’, and similar).
+When using CreateView or EditView to create or update model instances, the fields corresponding to the keys in the dict are prepopulated using the fields in the corresponding tuple. The main use for this functionality is to automatically generate the value for SlugField fields from one or more other fields. The generated value is produced by concatenating the values of the source fields, and then by transforming that result into a valid slug (for example substituting dashes for spaces; lowercasing ASCII letters; and removing various English stop words such as ‘a’, ‘an’, ‘as’, and similar).
 
 Prepopulated fields aren’t modified by JavaScript after a value has been saved. It’s usually undesired that slugs change (which would cause an object’s URL to change if the slug is used in it).
 

docs/reference/contrib/modeladmin/tips_and_tricks/reversing_urls.md

@@ -69,7 +69,7 @@ to allow a single author to be specified for each post.
 
 As you can see from the example above, when using `get_action_url()` to
 generate object-specific URLs, the target object's primary key value must be supplied
-so that it can be included in the resulting URL (e.g. `"/admin/my-app/author/edit/2/"`).
+so that it can be included in the resulting URL (for example `"/admin/my-app/author/edit/2/"`).
 The following object-specific action names are supported by `get_action_url()`:
 
 -   `'edit'` Returns a URL for updating a specific object.
@@ -115,7 +115,7 @@ For example:
 ```
 
 ```{note}
-If you have registered a page type with `modeladmin` (e.g. `BlogPage`), and pages
+If you have registered a page type with `modeladmin` (for example `BlogPage`), and pages
 of that type can be added to more than one place in the page tree, when a user visits
 the `create` URL, they'll be automatically redirected to another view to choose a
 parent for the new page. So, this isn't something you need to check or cater for in

docs/reference/contrib/settings.md

@@ -1,7 +1,7 @@
 # Settings
 
 The `wagtail.contrib.settings` module allows you to define models that hold
-settings which are either generic (i.e. the same) across all `Site`s or
+settings which are either generic (that is the same) across all `Site`s or
 specific to each `Site`.
 
 Settings are editable by administrators within the Wagtail admin, and can be
@@ -24,8 +24,8 @@ update your `TEMPLATES` settings (discussed later in this page).
 
 Create a model that inherits from either:
 
-* `BaseGenericSetting` for generic settings across all sites
-* `BaseSiteSetting` for site-specific settings
+-   `BaseGenericSetting` for generic settings across all sites
+-   `BaseSiteSetting` for site-specific settings
 
 and register it using the `register_setting` decorator:
 
@@ -290,7 +290,7 @@ Or, alternately, using the `set` tag:
 
 ## Utilising `select_related` to improve efficiency
 
-For models with foreign key relationships to other objects (e.g. pages),
+For models with foreign key relationships to other objects (for example pages),
 which are very often needed to output values in templates, you can set
 the `select_related` attribute on your model to have Wagtail utilise
 Django's [QuerySet.select_related()](https://docs.djangoproject.com/en/stable/ref/models/querysets/#select-related)
@@ -358,7 +358,7 @@ Using the `page_url` shortcut has a few of advantages over using the tag:
     so you don't have to worry about doing this (or forgetting to do this)
     yourself.
 2.  The results are cached, so if you need to access the same page URL
-    in more than one place (e.g. in a form and in footer navigation), using
+    in more than one place (for example in a form and in footer navigation), using
     the `page_url` shortcut will be more efficient.
 3.  It's more concise, and the syntax is the same whether using it in templates
     or views (or other Python code), allowing you to write more consistent
@@ -375,4 +375,4 @@ When using the `page_url` shortcut, there are a couple of points worth noting:
     is not an attribute on the settings object.
 3.  If the settings object DOES have the attribute, but the attribute returns
     a value of `None` (or something that is not a `Page`), the shortcut
-    will return an empty string.
+    will return an empty string.

docs/reference/hooks.md

@@ -25,7 +25,7 @@ Alternatively, `hooks.register` can be called as an ordinary function, passing i
 hooks.register('name_of_hook', my_hook_function)
 ```
 
-If you need your hooks to run in a particular order, you can pass the `order` parameter. If order is not specified then the hooks proceed in the order given by `INSTALLED_APPS`. Wagtail uses hooks internally, too, so you need to be aware of order when overriding built-in Wagtail functionality (i.e. removing default summary items):
+If you need your hooks to run in a particular order, you can pass the `order` parameter. If order is not specified then the hooks proceed in the order given by `INSTALLED_APPS`. Wagtail uses hooks internally, too, so you need to be aware of order when overriding built-in Wagtail functionality (such as removing default summary items):
 
 ```python
 @hooks.register('name_of_hook', order=1)  # This will run after every hook in the wagtail core

docs/reference/pages/model_reference.rst

@@ -260,7 +260,7 @@ In addition to the model fields provided, ``Page`` has many properties and metho
             class HiddenPage(Page):
                 parent_page_types = []
 
-        To allow for a page to be only created under the root page (e.g. for ``HomePage`` models) set the ``parent_page_type`` to ``['wagtailcore.Page']``.
+        To allow for a page to be only created under the root page (for example for ``HomePage`` models) set the ``parent_page_type`` to ``['wagtailcore.Page']``.
 
         .. code-block:: python
 
@@ -401,7 +401,7 @@ Methods and properties
 
         - 80 = ``http://``
         - 443 = ``https://``
-        - Everything else will use the ``http://`` scheme and the port will be appended to the end of the hostname (eg. ``http://mysite.com:8000/``)
+        - Everything else will use the ``http://`` scheme and the port will be appended to the end of the hostname (for example ``http://mysite.com:8000/``)
 
     .. automethod:: get_site_root_paths
 
@@ -1045,7 +1045,7 @@ Database fields
         (dict)
 
         The JSON representation of any additional details for each action.
-        e.g. source page id and title when copying from a page. Or workflow id/name and next step id/name on a workflow transition
+        For example source page id and title when copying from a page. Or workflow id/name and next step id/name on a workflow transition
 
         .. versionchanged:: 3.0
 

docs/reference/settings.md

@@ -146,7 +146,7 @@ This would mean that your site will respond on the `https://www.mysite.com/es/`
 ```{note}
 ``WAGTAIL_CONTENT_LANGUAGES`` must be a subset of ``LANGUAGES``
 
-Note that all languages that exist in ``WAGTAIL_CONTENT_LANGUAGES`` must also exist in your ``LANGUAGES`` setting. This is so that Wagtail can generate a live URL to these pages from an untranslated context (e.g. the admin interface).
+Note that all languages that exist in ``WAGTAIL_CONTENT_LANGUAGES`` must also exist in your ``LANGUAGES`` setting. This is so that Wagtail can generate a live URL to these pages from an untranslated context (such as the admin interface).
 ```
 
 ## Embeds
@@ -219,7 +219,7 @@ You can use it to specify or override the widgets to use in the admin form.
 ### `WAGTAILIMAGES_MAX_UPLOAD_SIZE`
 
 ```python
-WAGTAILIMAGES_MAX_UPLOAD_SIZE = 20 * 1024 * 1024  # i.e. 20MB
+WAGTAILIMAGES_MAX_UPLOAD_SIZE = 20 * 1024 * 1024  # 20MB
 ```
 
 This setting lets you override the maximum upload size for images (in bytes). If omitted, Wagtail will fall back to using its 10MB default value.
@@ -227,7 +227,7 @@ This setting lets you override the maximum upload size for images (in bytes). If
 ### `WAGTAILIMAGES_MAX_IMAGE_PIXELS`
 
 ```python
-WAGTAILIMAGES_MAX_IMAGE_PIXELS = 128000000  # i.e. 128 megapixels
+WAGTAILIMAGES_MAX_IMAGE_PIXELS = 128000000  # 128 megapixels
 ```
 
 This setting lets you override the maximum number of pixels an image can have. If omitted, Wagtail will fall back to using its 128 megapixels default value. The pixel count takes animation frames into account - for example, a 25-frame animation of size 100x100 is considered to have 100 _ 100 _ 25 = 250000 pixels.
@@ -307,11 +307,11 @@ Determines how document downloads will be linked to and served. Normally, reques
 
 For this reason, Wagtail provides a number of serving methods which trade some of the strictness of the permission check for performance:
 
--   `'direct'` - links to documents point directly to the URL provided by the underlying storage, bypassing the Django view that provides the permission check. This is most useful when deploying sites as fully static HTML (e.g. using [wagtail-bakery](https://github.com/wagtail/wagtail-bakery) or [Gatsby](https://www.gatsbyjs.org/)).
+-   `'direct'` - links to documents point directly to the URL provided by the underlying storage, bypassing the Django view that provides the permission check. This is most useful when deploying sites as fully static HTML (for example using [wagtail-bakery](https://github.com/wagtail/wagtail-bakery) or [Gatsby](https://www.gatsbyjs.org/)).
 -   `'redirect'` - links to documents point to a Django view which will check the user's permission; if successful, it will redirect to the URL provided by the underlying storage to allow the document to be downloaded. This is most suitable for remote storage backends such as S3, as it allows the document to be served independently of the Django server. Note that if a user is able to guess the latter URL, they will be able to bypass the permission check; some storage backends may provide configuration options to generate a random or short-lived URL to mitigate this.
 -   `'serve_view'` - links to documents point to a Django view which both checks the user's permission, and serves the document. Serving will be handled by [django-sendfile](https://github.com/johnsensible/django-sendfile), if this is installed and supported by your server configuration, or as a streaming response from Django if not. When using this method, it is recommended that you configure your webserver to _disallow_ serving documents directly from their location under `MEDIA_ROOT`, as this would provide a way to bypass the permission check.
 
-If `WAGTAILDOCS_SERVE_METHOD` is unspecified or set to `None`, the default method is `'redirect'` when a remote storage backend is in use (i.e. one that exposes a URL but not a local filesystem path), and `'serve_view'` otherwise. Finally, some storage backends may not expose a URL at all; in this case, serving will proceed as for `'serve_view'`.
+If `WAGTAILDOCS_SERVE_METHOD` is unspecified or set to `None`, the default method is `'redirect'` when a remote storage backend is in use (one that exposes a URL but not a local filesystem path), and `'serve_view'` otherwise. Finally, some storage backends may not expose a URL at all; in this case, serving will proceed as for `'serve_view'`.
 
 (wagtaildocs_content_types)=
 
@@ -740,7 +740,7 @@ WAGTAILADMIN_RICH_TEXT_EDITORS = {
 }
 ```
 
-Customise the behaviour of rich text fields. By default, `RichTextField` and `RichTextBlock` use the configuration given under the `'default'` key, but this can be overridden on a per-field basis through the `editor` keyword argument, e.g. `body = RichTextField(editor='secondary')`. Within each configuration block, the following fields are recognised:
+Customise the behaviour of rich text fields. By default, `RichTextField` and `RichTextBlock` use the configuration given under the `'default'` key, but this can be overridden on a per-field basis through the `editor` keyword argument, for example `body = RichTextField(editor='secondary')`. Within each configuration block, the following fields are recognised:
 
 -   `WIDGET`: The rich text widget implementation to use. Wagtail provides `wagtail.admin.rich_text.DraftailRichTextArea` (a modern extensible editor which enforces well-structured markup). Other widgets may be provided by third-party packages.
 -   `OPTIONS`: Configuration options to pass to the widget. Recognised options are widget-specific, but `DraftailRichTextArea` accept a `features` list indicating the active rich text features (see [](rich_text_features)).

docs/reference/streamfield/blocks.md

@@ -46,7 +46,7 @@ All block definitions accept the following optional keyword arguments:
 -   `template`
     -   The path to a Django template that will be used to render this block on the front end. See [Template rendering](streamfield_template_rendering)
 -   `group`
-    -   The group used to categorize this block, i.e. any blocks with the same group name will be shown together in the editor interface with the group name as a heading.
+    -   The group used to categorize this block. Any blocks with the same group name will be shown together in the editor interface with the group name as a heading.
 
 ## Field block types
 
@@ -413,7 +413,7 @@ All block definitions accept the following optional keyword arguments:
    :param form_template: Path to a Django template to use to render this block's form. See :ref:`custom_editing_interfaces_for_structblock`.
    :param value_class: A subclass of ``wagtail.blocks.StructValue`` to use as the type of returned values for this block. See :ref:`custom_value_class_for_structblock`.
    :param label_format:
-     Determines the label shown when the block is collapsed in the editing interface. By default, the value of the first sub-block in the StructBlock is shown, but this can be customised by setting a string here with block names contained in braces - e.g. ``label_format = "Profile for {first_name} {surname}"``
+     Determines the label shown when the block is collapsed in the editing interface. By default, the value of the first sub-block in the StructBlock is shown, but this can be customised by setting a string here with block names contained in braces - for example ``label_format = "Profile for {first_name} {surname}"``
 
 
 .. class:: wagtail.blocks.ListBlock

docs/releases/4.0.md

@@ -96,6 +96,7 @@ Wagtail’s page preview is now available in a side panel within the page editor
  * Add an extra confirmation prompt when deleting pages with a large number of child pages (Jaspreet Singh)
  * Adopt the slim header in page listing views, with buttons moved under the "Actions" dropdown (Paarth Agarwal)
  * Improve help block styles in Windows High Contrast Mode with less reliance on communication via colour alone (Anuja Verma)
+ * Replace latin abbreviations (i.e. / e.g.) with common English phrases so that documentation is easier to understand (Dominik Lech)
 
 ### Bug fixes
 

docs/topics/images.md

@@ -25,7 +25,7 @@ For example:
 {% image page.photo fill-80x80 %}
 ```
 
-In the above syntax example `[image]` is the Django object referring to the image. If your page model defined a field called "photo" then `[image]` would probably be `page.photo`. The `[resize-rule]` defines how the image is to be resized when inserted into the page. Various resizing methods are supported, to cater to different use cases (e.g. lead images that span the whole width of the page, or thumbnails to be cropped to a fixed size).
+In the above syntax example `[image]` is the Django object referring to the image. If your page model defined a field called "photo" then `[image]` would probably be `page.photo`. The `[resize-rule]` defines how the image is to be resized when inserted into the page. Various resizing methods are supported, to cater to different use cases (for example lead images that span the whole width of the page, or thumbnails to be cropped to a fixed size).
 
 Note that a space separates `[image]` and `[resize-rule]`, but the resize rule must not contain spaces. The width is always specified before the height. Resized images will maintain their original aspect ratio unless the `fill` rule is used, which may result in some pixels being cropped.
 
@@ -59,7 +59,7 @@ Example: The image will keep its proportions but fit within the max (green line)
 
 **Cover** the given dimensions.
 
-This may result in an image slightly **larger** than the dimensions you specify. A square image of width 2000 and height 2000, treated with the `min-500x200` rule would have its height and width changed to 500, i.e matching the _width_ of the resize-rule, but greater than the height.
+This may result in an image slightly **larger** than the dimensions you specify. A square image of width 2000 and height 2000, treated with the `min-500x200` rule would have its height and width changed to 500, that is matching the _width_ of the resize-rule, but greater than the height.
 
 ![Example of min filter on an image](../_static/images/image_filter_min.png)
 
@@ -115,13 +115,13 @@ Example: The image is scaled and also cropped (red line) to fit as much of the i
 
 **On images that won't upscale**
 
-It's possible to request an image with `fill` dimensions that the image can't support without upscaling. e.g. an image of width 400 and height 200 requested with `fill-400x400`. In this situation the _ratio of the requested fill_ will be matched, but the dimension will not. So that example 400x200 image (a 2:1 ratio) could become 200x200 (a 1:1 ratio, matching the resize-rule).
+It's possible to request an image with `fill` dimensions that the image can't support without upscaling. For example an image of width 400 and height 200 requested with `fill-400x400`. In this situation the _ratio of the requested fill_ will be matched, but the dimension will not. So that example 400x200 image (a 2:1 ratio) could become 200x200 (a 1:1 ratio, matching the resize-rule).
 
 **Cropping closer to the focal point**
 
 By default, Wagtail will only crop enough to change the aspect ratio of the image to match the ratio in the resize-rule.
 
-In some cases (e.g. thumbnails), it may be preferable to crop closer to the focal point, so that the subject of the image is more prominent.
+In some cases (for example thumbnails), it may be preferable to crop closer to the focal point, so that the subject of the image is more prominent.
 
 You can do this by appending `-c<percentage>` at the end of the resize-rule. For example, if you would like the image to be cropped as closely as possible to its focal point, add `-c100`:
 
@@ -186,7 +186,7 @@ Wagtail can assign the image data to another variable using Django's `as` syntax
 The image property used for the `src` attribute is `image.url`, not `image.src`.
 ```
 
-This syntax exposes the underlying image Rendition (`tmp_photo`) to the developer. A "Rendition" contains the information specific to the way you've requested to format the image using the resize-rule, i.e. dimensions and source URL. The following properties are available:
+This syntax exposes the underlying image Rendition (`tmp_photo`) to the developer. A "Rendition" contains the information specific to the way you've requested to format the image using the resize-rule, dimensions and source URL. The following properties are available:
 
 ### `url`
 
@@ -222,7 +222,7 @@ This is useful for images that will be re-used outside of the current site, such
 <meta name="twitter:image" content="{{ tmp_photo.full_url }}">
 ```
 
-If your site defines a custom image model using `AbstractImage`, any additional fields you add to an image (e.g. a copyright holder) are **not** included in the rendition.
+If your site defines a custom image model using `AbstractImage`, any additional fields you add to an image (such as a copyright holder) are **not** included in the rendition.
 
 Therefore, if you'd added the field `author` to your AbstractImage in the above example, you'd access it using `{{ page.photo.author }}` rather than `{{ tmp_photo.author }}`.
 
@@ -280,7 +280,7 @@ Creates an image rendition using `width-500`, giving the <img> tag the CSS class
 Creates an image rendition using `width-500`, giving the <img> tag the CSS class `right`.
 
 ```{note}
-The CSS classes added to images do **not** come with any accompanying stylesheets, or inline styles. e.g. the `left` class will do nothing, by default. The developer is expected to add these classes to their front end CSS files, to define exactly what they want `left`, `right` or `full-width` to mean.
+The CSS classes added to images do **not** come with any accompanying stylesheets, or inline styles. For example the `left` class will do nothing, by default. The developer is expected to add these classes to their front end CSS files, to define exactly what they want `left`, `right` or `full-width` to mean.
 ```
 
 For more information about image formats, including creating your own, see [](rich_text_image_formats).

docs/topics/pages.md

@@ -193,7 +193,7 @@ When overriding `get_url_parts()`, you should accept `*args, **kwargs`:
 def get_url_parts(self, *args, **kwargs):
 ```
 
-and pass those through at the point where you are calling `get_url_parts` on `super` (if applicable), e.g.:
+and pass those through at the point where you are calling `get_url_parts` on `super` (if applicable), for example:
 
 ```python
 super().get_url_parts(*args, **kwargs)
@@ -424,7 +424,7 @@ You can convert a `Page` object to its more specific user-defined equivalent usi
 
 ### Friendly model names
 
-You can make your model names more friendly to users of Wagtail by using Django's internal `Meta` class with a `verbose_name`, e.g.:
+You can make your model names more friendly to users of Wagtail by using Django's internal `Meta` class with a `verbose_name`, for example:
 
 ```python
 class HomePage(Page):

docs/topics/search/backends.md

@@ -101,7 +101,7 @@ WAGTAILSEARCH_BACKENDS = {
 }
 ```
 
-Other than `BACKEND`, the keys are optional and default to the values shown. Any defined key in `OPTIONS` is passed directly to the Elasticsearch constructor as case-sensitive keyword argument (e.g. `'max_retries': 1`).
+Other than `BACKEND`, the keys are optional and default to the values shown. Any defined key in `OPTIONS` is passed directly to the Elasticsearch constructor as case-sensitive keyword argument (for example `'max_retries': 1`).
 
 A username and password may be optionally be supplied to the `URL` field to provide authentication credentials for the Elasticsearch service:
 

docs/topics/writing_templates.md

@@ -33,7 +33,7 @@ For more information, see the Django documentation for the [application director
 
 ### Page content
 
-The data/content entered into each page is accessed/output through Django's `{{ double-brace }}` notation. Each field from the model must be accessed by prefixing `page.`. e.g the page title `{{ page.title }}` or another field `{{ page.author }}`.
+The data/content entered into each page is accessed/output through Django's `{{ double-brace }}` notation. Each field from the model must be accessed by prefixing `page.`. For example the page title `{{ page.title }}` or another field `{{ page.author }}`.
 
 A custom variable name can be configured on the page model {attr}`wagtail.models.Page.context_object_name`. If a custom name is defined, `page` is still available for use in shared templates.
 
@@ -41,7 +41,7 @@ Additionally `request.` is available and contains Django's request object.
 
 ## Static assets
 
-Static files e.g CSS, JS and images are typically stored here:
+Static files (such as CSS, JS and images) are typically stored here:
 
 ```
 name_of_project/
@@ -64,7 +64,7 @@ Images uploaded to a Wagtail site by its users (as opposed to a developer's stat
 
 Unlike other CMSs, adding images to a page does not involve choosing a "version" of the image to use. Wagtail has no predefined image "formats" or "sizes". Instead the template developer defines image manipulation to occur _on the fly_ when the image is requested, via a special syntax within the template.
 
-Images from the library must be requested using this syntax, but a developer's static images can be added via conventional means e.g `img` tags. Only images from the library can be manipulated on the fly.
+Images from the library must be requested using this syntax, but a developer's static images can be added via conventional means like `img` tags. Only images from the library can be manipulated on the fly.
 
 Read more about the image manipulation syntax here: [](image_tag).
 
@@ -179,7 +179,7 @@ A `fallback` keyword argument can be provided - this can be a URL string, a name
 
 Takes any `slug` as defined in a page's "Promote" tab and returns the URL for the matching Page. If multiple pages exist with the same slug, the page chosen is undetermined.
 
-Like `pageurl`, this will try to provide a relative link if possible, but will default to an absolute link if the Page is on a different Site. This is most useful when creating shared page furniture, e.g. top level navigation or site-wide links.
+Like `pageurl`, this will try to provide a relative link if possible, but will default to an absolute link if the Page is on a different Site. This is most useful when creating shared page furniture, for example top level navigation or site-wide links.
 
 ```html+django
 {% load wagtailcore_tags %}

wagtail/admin/forms/collections.py

@@ -324,7 +324,7 @@ def collection_member_permission_formset_factory(
         """
         For a given model with CollectionMember behaviour,
         defines the permissions that are assigned to an entity
-        (i.e. group or user) for a specific collection
+        (such as a group or user) for a specific collection
         """
 
         collection = CollectionChoiceField(

wagtail/admin/tests/pages/test_edit_page.py

@@ -972,7 +972,7 @@ class TestPageEdit(TestCase, WagtailTestUtils):
 
     def test_editor_page_shows_live_url_in_status_when_draft_edits_exist(self):
         # If a page has draft edits (ie. page has unpublished changes)
-        # that affect the URL (eg. slug) we  should still ensure the
+        # that affect the URL (slug) we  should still ensure the
         # status button at the top of the page links to the live URL
 
         self.child_page.content = "Some content with a draft edit"

wagtail/admin/tests/test_widgets.py

@@ -350,7 +350,7 @@ class TestAdminDateTimeInput(TestCase):
 class TestAdminTagWidget(TestCase):
     def get_js_init_params(self, html):
         """Returns a list of the params passed in to initTagField from the supplied HTML"""
-        # Eg. ["test_id", "/admin/tag-autocomplete/", {'allowSpaces': True}]
+        # example - ["test_id", "/admin/tag-autocomplete/", {'allowSpaces': True}]
         start = "initTagField("
         end = ");"
         items_after_init = html.split(start)[1]

wagtail/coreutils.py

@@ -108,7 +108,7 @@ def cautious_slugify(value):
     that any non-ASCII alphanumeric characters (that cannot be ASCIIfied under Unicode
     normalisation) are escaped into codes like 'u0421' instead of being deleted entirely.
 
-    This ensures that the result of slugifying e.g. Cyrillic text will not be an empty
+    This ensures that the result of slugifying (for example - Cyrillic) text will not be an empty
     string, and can thus be safely used as an identifier (albeit not a human-readable one).
     """
     value = force_str(value)
@@ -121,7 +121,7 @@ def cautious_slugify(value):
 
     # Strip out characters that aren't letterlike, underscores or hyphens,
     # using the same regexp that slugify uses. This ensures that non-ASCII non-letters
-    # (e.g. accent modifiers, fancy punctuation) get stripped rather than escaped
+    # (accent modifiers, fancy punctuation) get stripped rather than escaped
     value = SLUGIFY_RE.sub("", value)
 
     # Encode as ASCII, escaping non-ASCII characters with backslashreplace, then convert

wagtail/whitelist.py

@@ -37,8 +37,8 @@ def attribute_rule(allowed_attrs):
     up in the 'allowed_attrs' dict defined here:
     * if the lookup fails, drop the attribute
     * if the lookup returns a callable, replace the attribute with the result of calling
-      it - e.g. {'title': uppercase} will replace 'title' with the result of uppercasing
-      the title. If the callable returns None, the attribute is dropped
+      it - for example `{'title': uppercase}` will replace 'title' with the result of
+      uppercasing the title. If the callable returns None, the attribute is dropped.
     * if the lookup returns a truthy value, keep the attribute; if falsy, drop it
     """