update to new C roles and directives
diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
index 93f6b64..20a7a60 100644
--- a/Doc/c-api/file.rst
+++ b/Doc/c-api/file.rst
@@ -7,79 +7,79 @@
.. index:: object: file
-Python's built-in file objects are implemented entirely on the :ctype:`FILE\*`
+Python's built-in file objects are implemented entirely on the :c:type:`FILE\*`
support from the C standard library. This is an implementation detail and may
change in future releases of Python.
-.. ctype:: PyFileObject
+.. c:type:: PyFileObject
- This subtype of :ctype:`PyObject` represents a Python file object.
+ This subtype of :c:type:`PyObject` represents a Python file object.
-.. cvar:: PyTypeObject PyFile_Type
+.. c:var:: PyTypeObject PyFile_Type
.. index:: single: FileType (in module types)
- This instance of :ctype:`PyTypeObject` represents the Python file type. This is
+ This instance of :c:type:`PyTypeObject` represents the Python file type. This is
exposed to Python programs as ``file`` and ``types.FileType``.
-.. cfunction:: int PyFile_Check(PyObject *p)
+.. c:function:: int PyFile_Check(PyObject *p)
- Return true if its argument is a :ctype:`PyFileObject` or a subtype of
- :ctype:`PyFileObject`.
+ Return true if its argument is a :c:type:`PyFileObject` or a subtype of
+ :c:type:`PyFileObject`.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
-.. cfunction:: int PyFile_CheckExact(PyObject *p)
+.. c:function:: int PyFile_CheckExact(PyObject *p)
- Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of
- :ctype:`PyFileObject`.
+ Return true if its argument is a :c:type:`PyFileObject`, but not a subtype of
+ :c:type:`PyFileObject`.
.. versionadded:: 2.2
-.. cfunction:: PyObject* PyFile_FromString(char *filename, char *mode)
+.. c:function:: PyObject* PyFile_FromString(char *filename, char *mode)
.. index:: single: fopen()
On success, return a new file object that is opened on the file given by
*filename*, with a file mode given by *mode*, where *mode* has the same
- semantics as the standard C routine :cfunc:`fopen`. On failure, return *NULL*.
+ semantics as the standard C routine :c:func:`fopen`. On failure, return *NULL*.
-.. cfunction:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
+.. c:function:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
- Create a new :ctype:`PyFileObject` from the already-open standard C file
+ Create a new :c:type:`PyFileObject` from the already-open standard C file
pointer, *fp*. The function *close* will be called when the file should be
closed. Return *NULL* and close the file using *close* on failure.
*close* is optional and can be set to *NULL*.
-.. cfunction:: FILE* PyFile_AsFile(PyObject \*p)
+.. c:function:: FILE* PyFile_AsFile(PyObject \*p)
- Return the file object associated with *p* as a :ctype:`FILE\*`.
+ Return the file object associated with *p* as a :c:type:`FILE\*`.
- If the caller will ever use the returned :ctype:`FILE\*` object while
- the :term:`GIL` is released it must also call the :cfunc:`PyFile_IncUseCount` and
- :cfunc:`PyFile_DecUseCount` functions described below as appropriate.
+ If the caller will ever use the returned :c:type:`FILE\*` object while
+ the :term:`GIL` is released it must also call the :c:func:`PyFile_IncUseCount` and
+ :c:func:`PyFile_DecUseCount` functions described below as appropriate.
-.. cfunction:: void PyFile_IncUseCount(PyFileObject \*p)
+.. c:function:: void PyFile_IncUseCount(PyFileObject \*p)
Increments the PyFileObject's internal use count to indicate
- that the underlying :ctype:`FILE\*` is being used.
+ that the underlying :c:type:`FILE\*` is being used.
This prevents Python from calling f_close() on it from another thread.
- Callers of this must call :cfunc:`PyFile_DecUseCount` when they are
- finished with the :ctype:`FILE\*`. Otherwise the file object will
+ Callers of this must call :c:func:`PyFile_DecUseCount` when they are
+ finished with the :c:type:`FILE\*`. Otherwise the file object will
never be closed by Python.
The :term:`GIL` must be held while calling this function.
- The suggested use is to call this after :cfunc:`PyFile_AsFile` and before
+ The suggested use is to call this after :c:func:`PyFile_AsFile` and before
you release the GIL::
FILE *fp = PyFile_AsFile(p);
@@ -94,11 +94,11 @@
.. versionadded:: 2.6
-.. cfunction:: void PyFile_DecUseCount(PyFileObject \*p)
+.. c:function:: void PyFile_DecUseCount(PyFileObject \*p)
Decrements the PyFileObject's internal unlocked_count member to
- indicate that the caller is done with its own use of the :ctype:`FILE\*`.
- This may only be called to undo a prior call to :cfunc:`PyFile_IncUseCount`.
+ indicate that the caller is done with its own use of the :c:type:`FILE\*`.
+ This may only be called to undo a prior call to :c:func:`PyFile_IncUseCount`.
The :term:`GIL` must be held while calling this function (see the example
above).
@@ -106,7 +106,7 @@
.. versionadded:: 2.6
-.. cfunction:: PyObject* PyFile_GetLine(PyObject *p, int n)
+.. c:function:: PyObject* PyFile_GetLine(PyObject *p, int n)
.. index:: single: EOFError (built-in exception)
@@ -120,20 +120,20 @@
raised if the end of the file is reached immediately.
-.. cfunction:: PyObject* PyFile_Name(PyObject *p)
+.. c:function:: PyObject* PyFile_Name(PyObject *p)
Return the name of the file specified by *p* as a string object.
-.. cfunction:: void PyFile_SetBufSize(PyFileObject *p, int n)
+.. c:function:: void PyFile_SetBufSize(PyFileObject *p, int n)
.. index:: single: setvbuf()
- Available on systems with :cfunc:`setvbuf` only. This should only be called
+ Available on systems with :c:func:`setvbuf` only. This should only be called
immediately after file object creation.
-.. cfunction:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)
+.. c:function:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)
Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0
on failure.
@@ -141,7 +141,7 @@
.. versionadded:: 2.3
-.. cfunction:: int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors)
+.. c:function:: int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors)
Set the file's encoding for Unicode output to *enc*, and its error
mode to *err*. Return 1 on success and 0 on failure.
@@ -149,7 +149,7 @@
.. versionadded:: 2.6
-.. cfunction:: int PyFile_SoftSpace(PyObject *p, int newflag)
+.. c:function:: int PyFile_SoftSpace(PyObject *p, int newflag)
.. index:: single: softspace (file attribute)
@@ -163,7 +163,7 @@
but doing so should not be needed.
-.. cfunction:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
+.. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
.. index:: single: Py_PRINT_RAW
@@ -173,7 +173,7 @@
appropriate exception will be set.
-.. cfunction:: int PyFile_WriteString(const char *s, PyObject *p)
+.. c:function:: int PyFile_WriteString(const char *s, PyObject *p)
Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on
failure; the appropriate exception will be set.