Changeset 391 for python/trunk/Doc/c-api/unicode.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/c-api/unicode.rst (modified) (54 diffs)

python/trunk/Doc/c-api/unicode.rst

@@ -12 +12 @@
 
 
+Unicode Type
+""""""""""""
+
 These are the basic Unicode object types used for the Unicode implementation in
 Python:
 
-.. % --- Unicode Type -------------------------------------------------------
-
-
-.. ctype:: Py_UNICODE
+
+.. c:type:: Py_UNICODE
 
    This type represents the storage type which is used by Python internally as
    basis for holding Unicode ordinals.  Python's default builds use a 16-bit type
-   for :ctype:`Py_UNICODE` and store Unicode values internally as UCS2. It is also
+   for :c:type:`Py_UNICODE` and store Unicode values internally as UCS2. It is also
    possible to build a UCS4 version of Python (most recent Linux distributions come
    with UCS4 builds of Python). These builds then use a 32-bit type for
-   :ctype:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms
-   where :ctype:`wchar_t` is available and compatible with the chosen Python
-   Unicode build variant, :ctype:`Py_UNICODE` is a typedef alias for
-   :ctype:`wchar_t` to enhance native platform compatibility. On all other
-   platforms, :ctype:`Py_UNICODE` is a typedef alias for either :ctype:`unsigned
-   short` (UCS2) or :ctype:`unsigned long` (UCS4).
+   :c:type:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms
+   where :c:type:`wchar_t` is available and compatible with the chosen Python
+   Unicode build variant, :c:type:`Py_UNICODE` is a typedef alias for
+   :c:type:`wchar_t` to enhance native platform compatibility. On all other
+   platforms, :c:type:`Py_UNICODE` is a typedef alias for either :c:type:`unsigned
+   short` (UCS2) or :c:type:`unsigned long` (UCS4).
 
 Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep
@@ -36 +37 @@
 
 
-.. ctype:: PyUnicodeObject
-
-   This subtype of :ctype:`PyObject` represents a Python Unicode object.
-
-
-.. cvar:: PyTypeObject PyUnicode_Type
-
-   This instance of :ctype:`PyTypeObject` represents the Python Unicode type.  It
+.. c:type:: PyUnicodeObject
+
+   This subtype of :c:type:`PyObject` represents a Python Unicode object.
+
+
+.. c:var:: PyTypeObject PyUnicode_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python Unicode type.  It
    is exposed to Python code as ``unicode`` and ``types.UnicodeType``.
 
@@ -50 +51 @@
 
 
-.. cfunction:: int PyUnicode_Check(PyObject *o)
+.. c:function:: int PyUnicode_Check(PyObject *o)
 
    Return true if the object *o* is a Unicode object or an instance of a Unicode
@@ -59 +60 @@
 
 
-.. cfunction:: int PyUnicode_CheckExact(PyObject *o)
+.. c:function:: int PyUnicode_CheckExact(PyObject *o)
 
    Return true if the object *o* is a Unicode object, but not an instance of a
@@ -67 +68 @@
 
 
-.. cfunction:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
-
-   Return the size of the object.  *o* has to be a :ctype:`PyUnicodeObject` (not
+.. c:function:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
+
+   Return the size of the object.  *o* has to be a :c:type:`PyUnicodeObject` (not
    checked).
 
    .. versionchanged:: 2.5
-      This function returned an :ctype:`int` type. This might require changes
+      This function returned an :c:type:`int` type. This might require changes
       in your code for properly supporting 64-bit systems.
 
 
-.. cfunction:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
+.. c:function:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
 
    Return the size of the object's internal buffer in bytes.  *o* has to be a
-   :ctype:`PyUnicodeObject` (not checked).
-
-   .. versionchanged:: 2.5
-      This function returned an :ctype:`int` type. This might require changes
+   :c:type:`PyUnicodeObject` (not checked).
+
+   .. versionchanged:: 2.5
+      This function returned an :c:type:`int` type. This might require changes
       in your code for properly supporting 64-bit systems.
 
 
-.. cfunction:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
-
-   Return a pointer to the internal :ctype:`Py_UNICODE` buffer of the object.  *o*
-   has to be a :ctype:`PyUnicodeObject` (not checked).
-
-
-.. cfunction:: const char* PyUnicode_AS_DATA(PyObject *o)
+.. c:function:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
+
+   Return a pointer to the internal :c:type:`Py_UNICODE` buffer of the object.  *o*
+   has to be a :c:type:`PyUnicodeObject` (not checked).
+
+
+.. c:function:: const char* PyUnicode_AS_DATA(PyObject *o)
 
    Return a pointer to the internal buffer of the object. *o* has to be a
-   :ctype:`PyUnicodeObject` (not checked).
-
-
-.. cfunction:: int PyUnicode_ClearFreeList()
+   :c:type:`PyUnicodeObject` (not checked).
+
+
+.. c:function:: int PyUnicode_ClearFreeList()
 
    Clear the free list. Return the total number of freed items.
@@ -105 +106 @@
    .. versionadded:: 2.6
 
+
+Unicode Character Properties
+""""""""""""""""""""""""""""
 
 Unicode provides many different character properties. The most often needed ones
@@ -110 +114 @@
 the Python configuration.
 
-.. % --- Unicode character properties ---------------------------------------
-
-
-.. cfunction:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
+
+.. c:function:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
 
    Return 1 or 0 depending on whether *ch* is a whitespace character.
 
 
-.. cfunction:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
 
    Return 1 or 0 depending on whether *ch* is a lowercase character.
 
 
-.. cfunction:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
 
    Return 1 or 0 depending on whether *ch* is an uppercase character.
 
 
-.. cfunction:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
 
    Return 1 or 0 depending on whether *ch* is a titlecase character.
 
 
-.. cfunction:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
 
    Return 1 or 0 depending on whether *ch* is a linebreak character.
 
 
-.. cfunction:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
 
    Return 1 or 0 depending on whether *ch* is a decimal character.
 
 
-.. cfunction:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
 
    Return 1 or 0 depending on whether *ch* is a digit character.
 
 
-.. cfunction:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
 
    Return 1 or 0 depending on whether *ch* is a numeric character.
 
 
-.. cfunction:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
 
    Return 1 or 0 depending on whether *ch* is an alphabetic character.
 
 
-.. cfunction:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
 
    Return 1 or 0 depending on whether *ch* is an alphanumeric character.
@@ -165 +167 @@
 
 
-.. cfunction:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)
+.. c:function:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)
 
    Return the character *ch* converted to lower case.
 
 
-.. cfunction:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)
+.. c:function:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)
 
    Return the character *ch* converted to upper case.
 
 
-.. cfunction:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)
+.. c:function:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)
 
    Return the character *ch* converted to title case.
 
 
-.. cfunction:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)
 
    Return the character *ch* converted to a decimal positive integer.  Return
@@ -186 +188 @@
 
 
-.. cfunction:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)
 
    Return the character *ch* converted to a single digit integer. Return ``-1`` if
@@ -192 +194 @@
 
 
-.. cfunction:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)
+.. c:function:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)
 
    Return the character *ch* converted to a double. Return ``-1.0`` if this is not
    possible.  This macro does not raise exceptions.
 
+
+Plain Py_UNICODE
+""""""""""""""""
+
 To create Unicode objects and access their basic sequence properties, use these
 APIs:
 
-.. % --- Plain Py_UNICODE ---------------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
-
-   Create a Unicode Object from the Py_UNICODE buffer *u* of the given size. *u*
+
+.. c:function:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
+
+   Create a Unicode object from the Py_UNICODE buffer *u* of the given size. *u*
    may be *NULL* which causes the contents to be undefined. It is the user's
    responsibility to fill in the needed data.  The buffer is copied into the new
@@ -213 +217 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
-
-   Return a read-only pointer to the Unicode object's internal :ctype:`Py_UNICODE`
-   buffer, *NULL* if *unicode* is not a Unicode object.
-
-
-.. cfunction:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
+
+   Create a Unicode object from the char buffer *u*.  The bytes will be interpreted
+   as being UTF-8 encoded.  *u* may also be *NULL* which
+   causes the contents to be undefined. It is the user's responsibility to fill in
+   the needed data.  The buffer is copied into the new object. If the buffer is not
+   *NULL*, the return value might be a shared object. Therefore, modification of
+   the resulting Unicode object is only allowed when *u* is *NULL*.
+
+   .. versionadded:: 2.6
+
+
+.. c:function:: PyObject *PyUnicode_FromString(const char *u)
+
+   Create a Unicode object from an UTF-8 encoded null-terminated char buffer
+   *u*.
+
+   .. versionadded:: 2.6
+
+
+.. c:function:: PyObject* PyUnicode_FromFormat(const char *format, ...)
+
+   Take a C :c:func:`printf`\ -style *format* string and a variable number of
+   arguments, calculate the size of the resulting Python unicode string and return
+   a string with the values formatted into it.  The variable arguments must be C
+   types and must correspond exactly to the format characters in the *format*
+   string.  The following format characters are allowed:
+
+   .. % The descriptions for %zd and %zu are wrong, but the truth is complicated
+   .. % because not all compilers support the %z width modifier -- we fake it
+   .. % when necessary via interpolating PY_FORMAT_SIZE_T.
+
+   .. tabularcolumns:: |l|l|L|
+
+   +-------------------+---------------------+--------------------------------+
+   | Format Characters | Type                | Comment                        |
+   +===================+=====================+================================+
+   | :attr:`%%`        | *n/a*               | The literal % character.       |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%c`        | int                 | A single character,            |
+   |                   |                     | represented as an C int.       |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%d`        | int                 | Exactly equivalent to          |
+   |                   |                     | ``printf("%d")``.              |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%u`        | unsigned int        | Exactly equivalent to          |
+   |                   |                     | ``printf("%u")``.              |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%ld`       | long                | Exactly equivalent to          |
+   |                   |                     | ``printf("%ld")``.             |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%lu`       | unsigned long       | Exactly equivalent to          |
+   |                   |                     | ``printf("%lu")``.             |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%zd`       | Py_ssize_t          | Exactly equivalent to          |
+   |                   |                     | ``printf("%zd")``.             |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%zu`       | size_t              | Exactly equivalent to          |
+   |                   |                     | ``printf("%zu")``.             |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%i`        | int                 | Exactly equivalent to          |
+   |                   |                     | ``printf("%i")``.              |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%x`        | int                 | Exactly equivalent to          |
+   |                   |                     | ``printf("%x")``.              |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%s`        | char\*              | A null-terminated C character  |
+   |                   |                     | array.                         |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%p`        | void\*              | The hex representation of a C  |
+   |                   |                     | pointer. Mostly equivalent to  |
+   |                   |                     | ``printf("%p")`` except that   |
+   |                   |                     | it is guaranteed to start with |
+   |                   |                     | the literal ``0x`` regardless  |
+   |                   |                     | of what the platform's         |
+   |                   |                     | ``printf`` yields.             |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%U`        | PyObject\*          | A unicode object.              |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%V`        | PyObject\*, char \* | A unicode object (which may be |
+   |                   |                     | *NULL*) and a null-terminated  |
+   |                   |                     | C character array as a second  |
+   |                   |                     | parameter (which will be used, |
+   |                   |                     | if the first parameter is      |
+   |                   |                     | *NULL*).                       |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%S`        | PyObject\*          | The result of calling          |
+   |                   |                     | :func:`PyObject_Unicode`.      |
+   +-------------------+---------------------+--------------------------------+
+   | :attr:`%R`        | PyObject\*          | The result of calling          |
+   |                   |                     | :func:`PyObject_Repr`.         |
+   +-------------------+---------------------+--------------------------------+
+
+   An unrecognized format character causes all the rest of the format string to be
+   copied as-is to the result string, and any extra arguments discarded.
+
+   .. versionadded:: 2.6
+
+
+.. c:function:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)
+
+   Identical to :func:`PyUnicode_FromFormat` except that it takes exactly two
+   arguments.
+
+   .. versionadded:: 2.6
+
+
+.. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
+
+   Return a read-only pointer to the Unicode object's internal
+   :c:type:`Py_UNICODE` buffer, *NULL* if *unicode* is not a Unicode object.
+   Note that the resulting :c:type:`Py_UNICODE*` string may contain embedded
+   null characters, which would cause the string to be truncated when used in
+   most C functions.
+
+
+.. c:function:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
 
    Return the length of the Unicode object.
 
    .. versionchanged:: 2.5
-      This function returned an :ctype:`int` type. This might require changes
+      This function returned an :c:type:`int` type. This might require changes
       in your code for properly supporting 64-bit systems.
 
 
-.. cfunction:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
+.. c:function:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
 
    Coerce an encoded object *obj* to an Unicode object and return a reference with
@@ -249 +363 @@
 
 
-.. cfunction:: PyObject* PyUnicode_FromObject(PyObject *obj)
+.. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)
 
    Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used
    throughout the interpreter whenever coercion to Unicode is needed.
 
-If the platform supports :ctype:`wchar_t` and provides a header file wchar.h,
+If the platform supports :c:type:`wchar_t` and provides a header file wchar.h,
 Python can interface directly to this type using the following functions.
-Support is optimized if Python's own :ctype:`Py_UNICODE` type is identical to
-the system's :ctype:`wchar_t`.
-
-.. % --- wchar_t support for platforms which support it ---------------------
-
-
-.. cfunction:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
-
-   Create a Unicode object from the :ctype:`wchar_t` buffer *w* of the given size.
+Support is optimized if Python's own :c:type:`Py_UNICODE` type is identical to
+the system's :c:type:`wchar_t`.
+
+
+wchar_t Support
+"""""""""""""""
+
+:c:type:`wchar_t` support for platforms which support it:
+
+.. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
+
+   Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given *size*.
    Return *NULL* on failure.
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)
-
-   Copy the Unicode object contents into the :ctype:`wchar_t` buffer *w*.  At most
-   *size* :ctype:`wchar_t` characters are copied (excluding a possibly trailing
-   0-termination character).  Return the number of :ctype:`wchar_t` characters
-   copied or -1 in case of an error.  Note that the resulting :ctype:`wchar_t`
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)
+
+   Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*.  At most
+   *size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing
+   0-termination character).  Return the number of :c:type:`wchar_t` characters
+   copied or -1 in case of an error.  Note that the resulting :c:type:`wchar_t`
    string may or may not be 0-terminated.  It is the responsibility of the caller
-   to make sure that the :ctype:`wchar_t` string is 0-terminated in case this is
-   required by the application.
-
-   .. versionchanged:: 2.5
-      This function returned an :ctype:`int` type and used an :ctype:`int`
+   to make sure that the :c:type:`wchar_t` string is 0-terminated in case this is
+   required by the application. Also, note that the :c:type:`wchar_t*` string
+   might contain null characters, which would cause the string to be truncated
+   when used with most C functions.
+
+   .. versionchanged:: 2.5
+      This function returned an :c:type:`int` type and used an :c:type:`int`
       type for *size*. This might require changes in your code for properly
       supporting 64-bit systems.
@@ -296 +415 @@
 these codecs are directly usable via the following functions.
 
-Many of the following APIs take two arguments encoding and errors. These
-parameters encoding and errors have the same semantics as the ones of the
-built-in :func:`unicode` Unicode object constructor.
+Many of the following APIs take two arguments encoding and errors, and they
+have the same semantics as the ones of the built-in :func:`unicode` Unicode
+object constructor.
 
 Setting encoding to *NULL* causes the default encoding to be used which is
-ASCII.  The file system calls should use :cdata:`Py_FileSystemDefaultEncoding`
-as the encoding for file names. This variable should be treated as read-only: On
+ASCII.  The file system calls should use :c:data:`Py_FileSystemDefaultEncoding`
+as the encoding for file names. This variable should be treated as read-only: on
 some systems, it will be a pointer to a static string, on others, it will change
 at run-time (such as when the application invokes setlocale).
@@ -313 +432 @@
 generic ones are documented for simplicity.
 
+
+Generic Codecs
+""""""""""""""
+
 These are the generic codec APIs:
 
-.. % --- Generic Codecs -----------------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
+
+.. c:function:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
 
    Create a Unicode object by decoding *size* bytes of the encoded string *s*.
@@ -327 +448 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)
-
-   Encode the :ctype:`Py_UNICODE` buffer of the given size and return a Python
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)
+
+   Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* and return a Python
    string object.  *encoding* and *errors* have the same meaning as the parameters
-   of the same name in the Unicode :meth:`encode` method.  The codec to be used is
-   looked up using the Python codec registry.  Return *NULL* if an exception was
-   raised by the codec.
-
-   .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
+   of the same name in the Unicode :meth:`~unicode.encode` method.  The codec
+   to be used is looked up using the Python codec registry.  Return *NULL* if
+   an exception was raised by the codec.
+
+   .. versionchanged:: 2.5
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
 
    Encode a Unicode object and return the result as Python string object.
@@ -352 +473 @@
    codec.
 
+
+UTF-8 Codecs
+""""""""""""
+
 These are the UTF-8 codec APIs:
 
-.. % --- UTF-8 Codecs -------------------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
+
+.. c:function:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
 
    Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string
@@ -363 +486 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
-
-   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF8`. If
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
+
+   If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF8`. If
    *consumed* is not *NULL*, trailing incomplete UTF-8 byte sequences will not be
    treated as an error. Those bytes will not be decoded and the number of bytes
@@ -377 +500 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
-
-   Encode the :ctype:`Py_UNICODE` buffer of the given size using UTF-8 and return a
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+
+   Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* using UTF-8 and return a
    Python string object.  Return *NULL* if an exception was raised by the codec.
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
 
    Encode a Unicode object using UTF-8 and return the result as Python string
@@ -397 +520 @@
    by the codec.
 
+
+UTF-32 Codecs
+"""""""""""""
+
 These are the UTF-32 codec APIs:
 
-.. % --- UTF-32 Codecs ------------------------------------------------------ */
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
-
-   Decode *length* bytes from a UTF-32 encoded buffer string and return the
+
+.. c:function:: PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
+
+   Decode *size* bytes from a UTF-32 encoded buffer string and return the
    corresponding Unicode object.  *errors* (if non-*NULL*) defines the error
    handling. It defaults to "strict".
@@ -432 +557 @@
 
 
-.. cfunction:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
-
-   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF32`. If
-   *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF32Stateful` will not treat
+.. c:function:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
+
+   If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF32`. If
+   *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF32Stateful` will not treat
    trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible
    by four) as an error. Those bytes will not be decoded and the number of bytes
@@ -443 +568 @@
 
 
-.. cfunction:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
+.. c:function:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
 
    Return a Python bytes object holding the UTF-32 encoded value of the Unicode
@@ -463 +588 @@
 
 
-.. cfunction:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
+.. c:function:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
 
    Return a Python string using the UTF-32 encoding in native byte order. The
@@ -472 +597 @@
 
 
+UTF-16 Codecs
+"""""""""""""
+
 These are the UTF-16 codec APIs:
 
-.. % --- UTF-16 Codecs ------------------------------------------------------ */
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
-
-   Decode *length* bytes from a UTF-16 encoded buffer string and return the
+
+.. c:function:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
+
+   Decode *size* bytes from a UTF-16 encoded buffer string and return the
    corresponding Unicode object.  *errors* (if non-*NULL*) defines the error
    handling. It defaults to "strict".
@@ -504 +630 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
-
-   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF16`. If
-   *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF16Stateful` will not treat
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
+
+   If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF16`. If
+   *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF16Stateful` will not treat
    trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a
    split surrogate pair) as an error. Those bytes will not be decoded and the
@@ -519 +645 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size* and an :ctype:`int *`
+      This function used an :c:type:`int` type for *size* and an :c:type:`int *`
       type for *consumed*. This might require changes in your code for
       properly supporting 64-bit systems.
 
 
-.. cfunction:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
+.. c:function:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
 
    Return a Python string object holding the UTF-16 encoded value of the Unicode
@@ -536 +662 @@
    mark (U+FEFF). In the other two modes, no BOM mark is prepended.
 
-   If *Py_UNICODE_WIDE* is defined, a single :ctype:`Py_UNICODE` value may get
-   represented as a surrogate pair. If it is not defined, each :ctype:`Py_UNICODE`
+   If *Py_UNICODE_WIDE* is defined, a single :c:type:`Py_UNICODE` value may get
+   represented as a surrogate pair. If it is not defined, each :c:type:`Py_UNICODE`
    values is interpreted as an UCS-2 character.
 
@@ -543 +669 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
 
    Return a Python string using the UTF-16 encoding in native byte order. The
@@ -553 +679 @@
    *NULL* if an exception was raised by the codec.
 
+
+UTF-7 Codecs
+""""""""""""
+
+These are the UTF-7 codec APIs:
+
+
+.. c:function:: PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)
+
+   Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string
+   *s*.  Return *NULL* if an exception was raised by the codec.
+
+
+.. c:function:: PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
+
+   If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF7`.  If
+   *consumed* is not *NULL*, trailing incomplete UTF-7 base-64 sections will not
+   be treated as an error.  Those bytes will not be decoded and the number of
+   bytes that have been decoded will be stored in *consumed*.
+
+
+.. c:function:: PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)
+
+   Encode the :c:type:`Py_UNICODE` buffer of the given size using UTF-7 and
+   return a Python bytes object.  Return *NULL* if an exception was raised by
+   the codec.
+
+   If *base64SetO* is nonzero, "Set O" (punctuation that has no otherwise
+   special meaning) will be encoded in base-64.  If *base64WhiteSpace* is
+   nonzero, whitespace will be encoded in base-64.  Both are set to zero for the
+   Python "utf-7" codec.
+
+
+Unicode-Escape Codecs
+"""""""""""""""""""""
+
 These are the "Unicode Escape" codec APIs:
 
-.. % --- Unicode-Escape Codecs ----------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
+
+.. c:function:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
 
    Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded
@@ -564 +724 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
-
-   Encode the :ctype:`Py_UNICODE` buffer of the given size using Unicode-Escape and
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
+
+   Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Unicode-Escape and
    return a Python string object.  Return *NULL* if an exception was raised by the
    codec.
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
 
    Encode a Unicode object using Unicode-Escape and return the result as Python
@@ -585 +745 @@
    raised by the codec.
 
+
+Raw-Unicode-Escape Codecs
+"""""""""""""""""""""""""
+
 These are the "Raw Unicode Escape" codec APIs:
 
-.. % --- Raw-Unicode-Escape Codecs ------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
+
+.. c:function:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
 
    Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape
@@ -596 +758 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
-
-   Encode the :ctype:`Py_UNICODE` buffer of the given size using Raw-Unicode-Escape
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+
+   Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Raw-Unicode-Escape
    and return a Python string object.  Return *NULL* if an exception was raised by
    the codec.
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
 
    Encode a Unicode object using Raw-Unicode-Escape and return the result as
@@ -617 +779 @@
    was raised by the codec.
 
+
+Latin-1 Codecs
+""""""""""""""
+
 These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode
 ordinals and only these are accepted by the codecs during encoding.
 
-.. % --- Latin-1 Codecs -----------------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
+
+.. c:function:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
 
    Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string
@@ -629 +793 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
-
-   Encode the :ctype:`Py_UNICODE` buffer of the given size using Latin-1 and return
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+
+   Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Latin-1 and return
    a Python string object.  Return *NULL* if an exception was raised by the codec.
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
 
    Encode a Unicode object using Latin-1 and return the result as Python string
@@ -649 +813 @@
    by the codec.
 
+
+ASCII Codecs
+""""""""""""
+
 These are the ASCII codec APIs.  Only 7-bit ASCII data is accepted. All other
 codes generate errors.
 
-.. % --- ASCII Codecs -------------------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
+
+.. c:function:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
 
    Create a Unicode object by decoding *size* bytes of the ASCII encoded string
@@ -661 +827 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
-
-   Encode the :ctype:`Py_UNICODE` buffer of the given size using ASCII and return a
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+
+   Encode the :c:type:`Py_UNICODE` buffer of the given *size* using ASCII and return a
    Python string object.  Return *NULL* if an exception was raised by the codec.
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
 
    Encode a Unicode object using ASCII and return the result as Python string
@@ -681 +847 @@
    by the codec.
 
-These are the mapping codec APIs:
-
-.. % --- Character Map Codecs -----------------------------------------------
+
+Character Map Codecs
+""""""""""""""""""""
 
 This codec is special in that it can be used to implement many different codecs
@@ -706 +872 @@
 characters to different code points.
 
-
-.. cfunction:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)
+These are the mapping codec APIs:
+
+.. c:function:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)
 
    Create a Unicode object by decoding *size* bytes of the encoded string *s* using
@@ -720 +887 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
-
-   Encode the :ctype:`Py_UNICODE` buffer of the given size using the given
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
+
+   Encode the :c:type:`Py_UNICODE` buffer of the given *size* using the given
    *mapping* object and return a Python string object. Return *NULL* if an
    exception was raised by the codec.
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
 
    Encode a Unicode object using the given *mapping* object and return the result
@@ -744 +911 @@
 
 
-.. cfunction:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)
-
-   Translate a :ctype:`Py_UNICODE` buffer of the given length by applying a
+.. c:function:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)
+
+   Translate a :c:type:`Py_UNICODE` buffer of the given *size* by applying a
    character mapping *table* to it and return the resulting Unicode object.  Return
    *NULL* when an exception was raised by the codec.
@@ -758 +925 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+MBCS codecs for Windows
+"""""""""""""""""""""""
 
 These are the MBCS codec APIs. They are currently only available on Windows and
@@ -766 +937 @@
 the user settings on the machine running the codec.
 
-.. % --- MBCS codecs for Windows --------------------------------------------
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
+
+.. c:function:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
 
    Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*.
@@ -775 +944 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)
-
-   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeMBCS`. If
-   *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeMBCSStateful` will not decode
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)
+
+   If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeMBCS`. If
+   *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeMBCSStateful` will not decode
    trailing lead byte and the number of bytes that have been decoded will be stored
    in *consumed*.
@@ -789 +958 @@
 
 
-.. cfunction:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
-
-   Encode the :ctype:`Py_UNICODE` buffer of the given size using MBCS and return a
+.. c:function:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+
+   Encode the :c:type:`Py_UNICODE` buffer of the given *size* using MBCS and return a
    Python string object.  Return *NULL* if an exception was raised by the codec.
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *size*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
+      This function used an :c:type:`int` type for *size*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
 
    Encode a Unicode object using MBCS and return the result as Python string
@@ -805 +974 @@
    by the codec.
 
-.. % --- Methods & Slots ----------------------------------------------------
-
+
+Methods & Slots
+"""""""""""""""
 
 .. _unicodemethodsandslots:
@@ -820 +990 @@
 
 
-.. cfunction:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)
+.. c:function:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)
 
    Concat two strings giving a new Unicode string.
 
 
-.. cfunction:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)
-
-   Split a string giving a list of Unicode strings.  If sep is *NULL*, splitting
+.. c:function:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)
+
+   Split a string giving a list of Unicode strings.  If *sep* is *NULL*, splitting
    will be done at all whitespace substrings.  Otherwise, splits occur at the given
    separator.  At most *maxsplit* splits will be done.  If negative, no limit is
@@ -833 +1003 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *maxsplit*. This might require
-      changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
+      This function used an :c:type:`int` type for *maxsplit*. This might require
+      changes in your code for properly supporting 64-bit systems.
+
+
+.. c:function:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
 
    Split a Unicode string at line breaks, returning a list of Unicode strings.
@@ -844 +1014 @@
 
 
-.. cfunction:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)
+.. c:function:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)
 
    Translate a string by applying a character mapping table to it and return the
@@ -860 +1030 @@
 
 
-.. cfunction:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
-
-   Join a sequence of strings using the given separator and return the resulting
+.. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
+
+   Join a sequence of strings using the given *separator* and return the resulting
    Unicode string.
 
 
-.. cfunction:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
-
-   Return 1 if *substr* matches *str*[*start*:*end*] at the given tail end
+.. c:function:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
+
+   Return 1 if *substr* matches ``str[start:end]`` at the given tail end
    (*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match),
    0 otherwise. Return ``-1`` if an error occurred.
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *start* and *end*. This
+      This function used an :c:type:`int` type for *start* and *end*. This
       might require changes in your code for properly supporting 64-bit
       systems.
 
 
-.. cfunction:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
-
-   Return the first position of *substr* in *str*[*start*:*end*] using the given
+.. c:function:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
+
+   Return the first position of *substr* in ``str[start:end]`` using the given
    *direction* (*direction* == 1 means to do a forward search, *direction* == -1 a
    backward search).  The return value is the index of the first match; a value of
@@ -887 +1057 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *start* and *end*. This
+      This function used an :c:type:`int` type for *start* and *end*. This
       might require changes in your code for properly supporting 64-bit
       systems.
 
 
-.. cfunction:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
+.. c:function:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
 
    Return the number of non-overlapping occurrences of *substr* in
@@ -898 +1068 @@
 
    .. versionchanged:: 2.5
-      This function returned an :ctype:`int` type and used an :ctype:`int`
+      This function returned an :c:type:`int` type and used an :c:type:`int`
       type for *start* and *end*. This might require changes in your code for
       properly supporting 64-bit systems.
 
 
-.. cfunction:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
+.. c:function:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
 
    Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and
@@ -910 +1080 @@
 
    .. versionchanged:: 2.5
-      This function used an :ctype:`int` type for *maxcount*. This might
+      This function used an :c:type:`int` type for *maxcount*. This might
       require changes in your code for properly supporting 64-bit systems.
 
 
-.. cfunction:: int PyUnicode_Compare(PyObject *left, PyObject *right)
+.. c:function:: int PyUnicode_Compare(PyObject *left, PyObject *right)
 
    Compare two strings and return -1, 0, 1 for less than, equal, and greater than,
@@ -920 +1090 @@
 
 
-.. cfunction:: int PyUnicode_RichCompare(PyObject *left,  PyObject *right,  int op)
+.. c:function:: int PyUnicode_RichCompare(PyObject *left,  PyObject *right,  int op)
 
    Rich compare two unicode strings and return one of the following:
@@ -936 +1106 @@
 
 
-.. cfunction:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)
+.. c:function:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)
 
    Return a new string object from *format* and *args*; this is analogous to
@@ -942 +1112 @@
 
 
-.. cfunction:: int PyUnicode_Contains(PyObject *container, PyObject *element)
+.. c:function:: int PyUnicode_Contains(PyObject *container, PyObject *element)
 
    Check whether *element* is contained in *container* and return true or false