PEP 1, 12: Update to reflect guidance for correct syntax highlighting (#2445)

* PEP 1, 12: Use apppropriate syntax highlighting languages in code blocks

* PEP 12: Update literal guidance for syntax highligting & simplify

pep-0001.txt

@@ -610,17 +610,21 @@ optional and are described below.  All other headers are required.
 
 The Author header lists the names, and optionally the email addresses
 of all the authors/owners of the PEP.  The format of the Author header
-value must be
+values must be:
 
-    Random J. User <address@dom.ain>
+.. code-block:: text
 
-if the email address is included, and just
+    Random J. User <random@example.com>
+
+if the email address is included, and just:
+
+.. code-block:: text
 
     Random J. User
 
 if the address is not given.  For historical reasons the format
-"address@dom.ain (Random J. User)" may appear in a PEP, however new
-PEPs must use the mandated format above, and it is acceptable to
+``random@example.com (Random J. User)`` may appear in a PEP;
+however, new PEPs must use the mandated format above, and it is acceptable to
 change to this format when PEPs are updated.
 
 If there are multiple authors, each should be on a separate line

pep-0012.rst

@@ -10,6 +10,8 @@ Created: 05-Aug-2002
 Post-History: `30-Aug-2002 <https://mail.python.org/archives/list/python-dev@python.org/thread/KX3AS7QAY26QH3WIUAEOCCNXQ4V2TGGV/>`__
 
 
+.. highlight:: rst
+
 .. note::
     For those who have written a PEP before, there is a template_
     (which is included as a file in the `PEPs repository`_).
@@ -303,33 +305,52 @@ Literal Blocks
 
     By the way, this is a comment, described in "Comments" below.
 
-Literal blocks are used for code samples or preformatted ASCII art. To
-indicate a literal block, preface the indented text block with
-"``::``" (two colons).  The literal block continues until the end of
-the indentation.  Indent the text block by 4 spaces.  For example::
+Literal blocks are used for code samples and other preformatted text.
+To indicate a literal block, preface the indented text block with
+"``::``" (two colons), or use the ``.. code-block::`` directive.
+Indent the text block by 4 spaces; the literal block continues until the end
+of the indentation. For example::
 
     This is a typical paragraph.  A literal block follows.
 
     ::
 
-        for a in [5,4,3,2,1]:   # this is program code, shown as-is
-            print a
-        print "it's..."
-        # a literal block continues until the indentation ends
+        for a in [5, 4, 3, 2, 1]:  # this is program code, shown as-is
+            print(a)
+        print("it's...")
 
-The paragraph containing only "``::``" will be completely removed from
-the output; no empty paragraph will remain.  "``::``" is also
-recognized at the end of any paragraph.  If immediately preceded by
-whitespace, both colons will be removed from the output.  When text
-immediately precedes the "``::``", *one* colon will be removed from
-the output, leaving only one colon visible (i.e., "``::``" will be
-replaced by "``:``").  For example, one colon will remain visible
-here::
+"``::``" is also recognized at the end of any paragraph; if not immediately
+preceded by whitespace, one colon will remain visible in the final output::
 
-    Paragraph::
+    This is an example::
 
         Literal block
 
+By default, literal blocks will be syntax-highlighted as Python code.
+For specific blocks that contain code or data in other languages/formats,
+use the ``.. code-block:: language`` directive, substituting the "short name"
+of the appropriate `Pygments lexer <https://pygments.org/docs/lexers/>`_
+(or ``text`` to disable highlighting) for ``language``. For example::
+
+    .. code-block:: rst
+
+        An example of the ``rst`` lexer (i.e. *reStructuredText*).
+
+For PEPs that predominantly contain literal blocks of a specific language,
+use the ``.. highlight:: language`` directive with the appropriate ``language``
+at the top of the PEP body (below the headers and above the Abstract).
+All literal blocks will then be treated as that language,
+unless specified otherwise in the specific ``.. code-block``. For example::
+
+    .. highlight:: c
+
+    Abstract
+    ========
+
+    Here's some C code::
+
+        printf("Hello, World!\n");
+
 
 Lists
 -----
@@ -630,7 +651,9 @@ Habits to Avoid
 ===============
 
 Many programmers who are familiar with TeX often write quotation marks
-like this::
+like this:
+
+.. code-block:: text
 
     `single-quoted' or ``double-quoted''
 
@@ -651,7 +674,7 @@ Various sections are found to be common across PEPs and are outlined in
 .. _template:
 
 .. include:: pep-0012/pep-NNNN.rst
-   :literal:
+   :code: rst
 
 
 Resources