PEP 7: Remove Python 2.2 advice, add C syntax highlighting and green/red sidebars (#3702)

peps/pep-0007.rst

@@ -1,14 +1,12 @@
 PEP: 7
 Title: Style Guide for C Code
-Version: $Revision$
-Last-Modified: $Date$
 Author: Guido van Rossum <guido@python.org>, Barry Warsaw <barry@python.org>
 Status: Active
 Type: Process
-Content-Type: text/x-rst
 Created: 05-Jul-2001
 Post-History:
 
+.. highlight:: c
 
 Introduction
 ============
@@ -77,7 +75,10 @@ Code lay-out
 
 * Function definition style: function name in column 1, outermost
   curly braces in column 1, blank line after local variable
-  declarations.  ::
+  declarations.
+
+  .. code-block::
+     :class: good
 
      static int
      extra_ivars(PyTypeObject *type, PyTypeObject *base)
@@ -94,7 +95,10 @@ Code lay-out
   the following left paren; no spaces inside the paren; braces are
   required everywhere, even where C permits them to be omitted, but do
   not add them to code you are not otherwise modifying.  All new C
-  code requires braces.  Braces should be formatted as shown::
+  code requires braces.  Braces should be formatted as shown:
+
+  .. code-block::
+     :class: good
 
      if (mro != NULL) {
          ...
@@ -103,10 +107,19 @@ Code lay-out
          ...
      }
 
-* The return statement should *not* get redundant parentheses::
+* The return statement should *not* get redundant parentheses:
+
+  .. code-block::
+     :class: bad
+
+     return(albatross); /* incorrect */
+
+  Instead:
+
+  .. code-block::
+     :class: good
 
      return albatross; /* correct */
-      return(albatross); /* incorrect */
 
 * Function and macro call style: ``foo(a, b, c)`` -- no space before
   the open paren, no spaces inside the parens, no spaces before
@@ -118,7 +131,10 @@ Code lay-out
 
 * Breaking long lines: if you can, break after commas in the outermost
   argument list.  Always indent continuation lines appropriately,
-  e.g.::
+  e.g.:
+
+  .. code-block::
+     :class: good
 
      PyErr_Format(PyExc_TypeError,
                   "cannot create '%.100s' instances",
@@ -126,7 +142,10 @@ Code lay-out
 
 * When you break a long expression at a binary operator, the
   operator goes at the end of the previous line, and braces should be
-  formatted as shown.  E.g.::
+  formatted as shown.  E.g.:
+
+  .. code-block::
+     :class: good
 
      if (type->tp_dictoffset != 0 && base->tp_dictoffset == 0 &&
          type->tp_dictoffset == b_size &&
@@ -140,7 +159,10 @@ Code lay-out
 * Macros intended to be used as a statement should use the
   ``do { ... } while (0)`` macro idiom,
   without a final semicolon.
-  Example::
+  Example:
+
+  .. code-block::
+     :class: good
 
      #define ADD_INT_MACRO(MOD, INT)                                   \
          do {                                                          \
@@ -160,11 +182,14 @@ Code lay-out
 * Comments go before the code they describe.
 
 * All functions and global variables should be declared static unless
-  they are to be part of a published interface
+  they are to be part of a published interface.
 
 * For external functions and variables, we always have a declaration
   in an appropriate header file in the "Include" directory, which uses
-  the ``PyAPI_FUNC()`` macro and ``PyAPI_DATA()`` macro, like this::
+  the ``PyAPI_FUNC()`` macro and ``PyAPI_DATA()`` macro, like this:
+
+  .. code-block::
+     :class: good
 
      PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
 
@@ -200,18 +225,12 @@ Documentation Strings
   to support building Python without docstrings (``./configure
   --without-doc-strings``).
 
-  For C code that needs to support versions of Python older than 2.3,
-  you can include this after including ``Python.h``::
-
-      #ifndef PyDoc_STR
-      #define PyDoc_VAR(name)         static char name[]
-      #define PyDoc_STR(str)          (str)
-      #define PyDoc_STRVAR(name, str) PyDoc_VAR(name) = PyDoc_STR(str)
-      #endif
-
 * The first line of each function docstring should be a "signature
   line" that gives a brief synopsis of the arguments and return value.
-  For example::
+  For example:
+
+  .. code-block::
+     :class: good
 
      PyDoc_STRVAR(myfunction__doc__,
      "myfunction(name, value) -> bool\n\n\
@@ -220,19 +239,25 @@ Documentation Strings
   Always include a blank line between the signature line and the text
   of the description.
 
-  If the return value for the function is always None (because there
+  If the return value for the function is always ``None`` (because there
   is no meaningful return value), do not include the indication of the
   return type.
 
 * When writing multi-line docstrings, be sure to always use backslash
   continuations, as in the example above, or string literal
-  concatenation::
+  concatenation:
+
+  .. code-block::
+     :class: good
 
      PyDoc_STRVAR(myfunction__doc__,
      "myfunction(name, value) -> bool\n\n"
      "Determine whether name and value make a valid pair.");
 
-  Though some C compilers accept string literals without either::
+  Though some C compilers accept string literals without either:
+
+  .. code-block::
+     :class: bad
 
      /* BAD -- don't do this! */
      PyDoc_STRVAR(myfunction__doc__,
@@ -246,14 +271,3 @@ Copyright
 =========
 
 This document has been placed in the public domain.
-
-
-
-..
-   Local Variables:
-   mode: indented-text
-   indent-tabs-mode: nil
-   sentence-end-double-space: t
-   fill-column: 70
-   coding: utf-8
-   End: