From 5e900e337e21d1d5d39d35e3701035a3387058ea Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Thu, 25 Jun 2026 20:40:30 -0500 Subject: [PATCH 1/6] Add a note to the style guide about abbreviations resolves #1824 After the section on specific terms, but before "simple language", add a section that explains that documentation should spell out acronyms, preferring the " ()" format. --- documentation/style-guide.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 73618f9aec..125658126e 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -116,6 +116,17 @@ Unix 1970s. +Spell out acronyms +================== + +The first time an acronym is used on a page, spell it out. +Prefer to write out the full term and follow it with the acronym in parentheses. +For example, write "JavaScript Object Notation (JSON)". + +Avoid using the ``:abbr:`` role, as it generates HTML which is not accessible to +some forms of assistive technology and mobile users. + + Use simple language =================== From 3b5d5b581512e2d11022517d64c500db1dcec333 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Fri, 26 Jun 2026 12:08:12 -0500 Subject: [PATCH 2/6] Split `:abbr:` vs "acronym howto" docs go The role is documented in with other sphinx roles. In order for the rst to read easily, one line of non-semantic whitespace was added to a list. The acronym usage note is moved to the end of "Use simple language" --- documentation/markup.rst | 6 ++++++ documentation/style-guide.rst | 15 ++++----------- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index 41bf5b39c6..e36aeaa84b 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -703,8 +703,14 @@ In the CPython documentation, there are a couple common cases where simpler markup should be used: * ``*arg*`` (rendered as *arg*) for function and method arguments. + * ````True````/````False````/````None```` for ``True``/``False``/``None``. +* ``Full Spelling (abbreviation)`` for abbreviations and acronyms. + + The ``:abbr:`` role generates HTML which is not accessible to some forms of + assistive technology and mobile users. + In addition, the CPython documentation defines a few custom roles: * ``:gh:`ID```: link to a GitHub issue. diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 125658126e..f19ce300b5 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -116,17 +116,6 @@ Unix 1970s. -Spell out acronyms -================== - -The first time an acronym is used on a page, spell it out. -Prefer to write out the full term and follow it with the acronym in parentheses. -For example, write "JavaScript Object Notation (JSON)". - -Avoid using the ``:abbr:`` role, as it generates HTML which is not accessible to -some forms of assistive technology and mobile users. - - Use simple language =================== @@ -136,6 +125,10 @@ be native English speakers. Don't use Latin abbreviations like "e.g." or "i.e." where English words will do, such as "for example" or "that is." +The first time an acronym is used on a page, spell it out. +Prefer to write out the full term and follow it with the acronym in parentheses. +For example, write "JavaScript Object Notation (JSON)". + Charged terminology to avoid ============================ From d53162553c35064b8a6b2da607bfd552a0460fea Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Fri, 24 Jul 2026 16:08:49 -0500 Subject: [PATCH 3/6] Add "In general, ..." to soften acronym note Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- documentation/style-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index fae170aed2..95b089c7a4 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -68,7 +68,7 @@ be native English speakers. Don't use Latin abbreviations like "e.g." or "i.e." where English words will do, such as "for example" or "that is." -The first time an acronym is used on a page, spell it out. +In general, the first time an acronym is used on a page, spell it out. Prefer to write out the full term and follow it with the acronym in parentheses. For example, write "JavaScript Object Notation (JSON)". From 0cf86182da8f945618d326a7c9dd28408fe79af9 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Sat, 25 Jul 2026 18:07:41 -0500 Subject: [PATCH 4/6] Update documentation/style-guide.rst Co-authored-by: Stan Ulbrych --- documentation/style-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 95b089c7a4..115cfe6349 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -70,7 +70,7 @@ such as "for example" or "that is." In general, the first time an acronym is used on a page, spell it out. Prefer to write out the full term and follow it with the acronym in parentheses. -For example, write "JavaScript Object Notation (JSON)". +For example, write "Basic Multilingual Plane (BMP)". Charged terminology to avoid From d0cdf9eb2c8d9eea29bb4873e35fee23cf6c7a61 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Tue, 28 Jul 2026 11:06:46 -0500 Subject: [PATCH 5/6] Add a small note on acronyms not to expand Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com> --- documentation/style-guide.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 115cfe6349..3bbd929306 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -71,6 +71,7 @@ such as "for example" or "that is." In general, the first time an acronym is used on a page, spell it out. Prefer to write out the full term and follow it with the acronym in parentheses. For example, write "Basic Multilingual Plane (BMP)". +Commonly understood acronyms, such as "HTML" and "UTF-8", should not be expanded. Charged terminology to avoid From 7ac2c8f0306ebfc81779f770f087cc0df6ad71d0 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Tue, 28 Jul 2026 13:20:35 -0500 Subject: [PATCH 6/6] Apply fixes per review s/couple/few/ Add "abbreviation" alongside "acronym" in style guide. Remove all existing uses of `:abbr:`. Where trivial, the text is reflowed to wrap more naturally. Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- developer-workflow/development-cycle.rst | 2 +- developer-workflow/stdlib.rst | 4 ++-- development-tools/clinic/index.rst | 2 +- documentation/markup.rst | 2 +- documentation/style-guide.rst | 3 ++- getting-started/pull-request-lifecycle.rst | 9 ++++----- getting-started/setup-building.rst | 3 +-- testing/coverage.rst | 2 +- 8 files changed, 13 insertions(+), 14 deletions(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index bcc78d842f..17bd8c2111 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -146,7 +146,7 @@ Stages Based on what stage the :ref:`in-development ` version of Python is in, the responsibilities of a core team member change in regards to commits -to the :abbr:`VCS (version control system)`. +to the VCS (version control system). Pre-alpha diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index ec10977221..691fd8e4bd 100644 --- a/developer-workflow/stdlib.rst +++ b/developer-workflow/stdlib.rst @@ -109,7 +109,7 @@ Python). This prevents a divergence between the code that is included in the stdlib and that which is released outside the stdlib (typically done to provide the module to older versions of Python). It also removes the burden of forcing the core team to have to redirect bug reports or changes to an external issue -tracker and :abbr:`VCS (version control system)`. +tracker and VCS (version control system). Someone involved with the development of the module must promise to help maintain the module in the stdlib for two years. @@ -124,7 +124,7 @@ Proposal process If the module you want to propose adding to the stdlib meets the requirements, you may propose its inclusion -by following the :abbr:`PEP (Python Enhancement Proposal)` process. +by following the PEP (Python Enhancement Proposal) process. See :pep:`1` for details, and the :pep:`PEP index <0>` for previously accepted PEPs that have proposed a module for inclusion. diff --git a/development-tools/clinic/index.rst b/development-tools/clinic/index.rst index a6ddd5c721..20a834e2d8 100644 --- a/development-tools/clinic/index.rst +++ b/development-tools/clinic/index.rst @@ -148,7 +148,7 @@ Terminology Command-line interface ---------------------- -The Argument Clinic :abbr:`CLI (Command-Line Interface)` is typically used to +The Argument Clinic CLI (Command-Line Interface) is typically used to process a single source file, like this: .. code-block:: shell-session diff --git a/documentation/markup.rst b/documentation/markup.rst index e36aeaa84b..8341278914 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -699,7 +699,7 @@ As :ref:`previously mentioned `, Sphinx uses interpreted text roles of the form ``:rolename:`content``` to insert semantic markup in documents. -In the CPython documentation, there are a couple common cases +In the CPython documentation, there are a few common cases where simpler markup should be used: * ``*arg*`` (rendered as *arg*) for function and method arguments. diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 3bbd929306..e504f529b5 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -68,7 +68,8 @@ be native English speakers. Don't use Latin abbreviations like "e.g." or "i.e." where English words will do, such as "for example" or "that is." -In general, the first time an acronym is used on a page, spell it out. +In general, the first time an acronym or abbreviation is used on a page, spell +it out. Prefer to write out the full term and follow it with the acronym in parentheses. For example, write "Basic Multilingual Plane (BMP)". Commonly understood acronyms, such as "HTML" and "UTF-8", should not be expanded. diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 351a99dbe5..5cba5f233e 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -710,11 +710,10 @@ do not take it personally! Your work is still appreciated regardless of whether your pull request is merged. Balancing what *does* and *does not* go into Python is tricky and we simply cannot accept everyone's contributions. -But if your pull request is merged it will then go into Python's -:abbr:`VCS (version control system)` to be released -with the next feature release of Python. It may also be backported to older -versions of Python as a bugfix if the core team member doing the merge believes -it is warranted. +But if your pull request is merged it will then go into Python's VCS (version +control system) to be released with the next feature release of Python. +It may also be backported to older versions of Python as a bugfix if the core +team member doing the merge believes it is warranted. Crediting diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index d1616fa023..8e35f8a646 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1107,8 +1107,7 @@ every rule. See also :ref:`building-doc`. ``Grammar`` - Contains the :abbr:`PEG (Parser Expression Grammar)` grammar file for - Python. + Contains the PEG (Parser Expression Grammar) grammar file for Python. ``Include`` Contains all interpreter-wide header files. diff --git a/testing/coverage.rst b/testing/coverage.rst index 48c2efc985..54782caf11 100644 --- a/testing/coverage.rst +++ b/testing/coverage.rst @@ -7,7 +7,7 @@ Increase test coverage .. include:: /include/activate-tab.rst Python development follows a practice that all semantic changes and additions -to the language and :abbr:`stdlib (standard library)` are accompanied by +to the language and stdlib (standard library) are accompanied by appropriate unit tests. Unfortunately Python was in existence for a long time before the practice came into effect. This has left chunks of the stdlib untested which is not a desirable situation to be in.