docutils-develop

[Docutils-develop] Documentation policy change suggestion

[Guenter M. <mi...@us...>]

Dear Docutils developers,

I suggest the following change to the "Docutils Project Policies":

diff --git a/docutils/docs/dev/policies.txt b/docutils/docs/dev/policies.txt
index f46c143d2..6be340155 100644
--- a/docutils/docs/dev/policies.txt
+++ b/docutils/docs/dev/policies.txt
@@ -110,8 +110,7 @@ Documentation Conventions
 
 * Docutils documentation is written using reStructuredText, of course.
 
-* Use 7-bit ASCII if at all possible, and Unicode substitutions when
-  necessary.
+* The encoding of the documentation files is UTF-8. 
 
 * Use the following section title adornment styles::
 

Rationale:

Adapt the Policies to the state of the art in 2022:

* Unicode and UTF-8 are now mainstream, no longer an obstacle to
  easy viewing and editing of the source files.
  
* Unicode substitutions, while 7-bit ASCII save, are harder to read and
  understand than literal Unicode characters.
  
  The use of substitutions for "exotic" characters that are hard to reach at
  the keyboard or missing in many fixed-width fonts is up to the discretion
  of the individual authors/editors.
  
.. include:: <isolat1.txt>
  
G|uuml|nter  

[Docutils-develop] Proposal: Documentation policy change on Unicode use

[Guenter M. <mi...@us...>]

Dear Docutils developers,

an update: while we are at it, I propose to allow literal Unicode in both,
documentation and source code (except for identifiers).

If there is no objection or alternative, I would commit the patch below
in a months time.

.. include:: <isolat1.txt>

G|uuml|nter


>From 5eb431cc0a4fd3f4f5c1581f9ca74653768b020e Mon Sep 17 00:00:00 2001
From: milde <mi...@us...>
Date: Mon, 28 Nov 2022 22:22:17 +0100
Subject: [PATCH] Policy change: accept literal Unicode characters except for
 identifiers.

With UTF-8 as default encoding for Python source code and widespread
Unicode support in todays editors on all platforms,
there is no need to be more restrictive than PEP 8 any more.
---
 docutils/docs/dev/policies.txt | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/docutils/docs/dev/policies.txt b/docutils/docs/dev/policies.txt
index f46c143d2..e95c33389 100644
--- a/docutils/docs/dev/policies.txt
+++ b/docutils/docs/dev/policies.txt
@@ -60,13 +60,13 @@ don't be surprised if the "offending" code gets fiddled over time to
 conform to these conventions.
 
 The Docutils project shall follow the generic coding conventions as
-specified in the `Style Guide for Python Code`_ and `Docstring
-Conventions`_ PEPs, summarized, clarified, and extended as follows:
+specified in the `Style Guide for Python Code` (:PEP:`8`) and `Docstring
+Conventions` (:PEP:`257`), summarized, clarified, and extended as follows:
 
 * 4 spaces per indentation level.  No hard tabs.
 
-* Use only 7-bit ASCII, no 8-bit strings.  See `Docutils
-  Internationalization`_.
+* Use UTF-8 encoding (no encoding declaration).
+  Identifiers must use ASCII only.
 
 * No one-liner compound statements (i.e., no ``if x: return``: use two
   lines & indentation), except for degenerate class or method
@@ -99,9 +99,6 @@ Conventions`_ PEPs, summarized, clarified, and extended as follows:
 * Use 'single quotes' for string literals, and """triple double
   quotes""" for docstrings.
 
-.. _Style Guide for Python Code:
-   https://peps.python.org/pep-0008
-.. _Docstring Conventions: https://peps.python.org/pep-0257
 .. _Docutils Internationalization: ../howto/i18n.html#python-code
 
 
@@ -110,8 +107,7 @@ Documentation Conventions
 
 * Docutils documentation is written using reStructuredText, of course.
 
-* Use 7-bit ASCII if at all possible, and Unicode substitutions when
-  necessary.
+* The encoding of the documentation files is UTF-8.
 
 * Use the following section title adornment styles::
 
-- 
2.30.2