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 41bf5b39c6..8341278914 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -699,12 +699,18 @@ 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. + * ````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 57da4d1263..e504f529b5 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -68,6 +68,12 @@ 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 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. + Charged terminology to avoid ============================ 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.