From a0dbddfcc03c4762f87cabd8bbb89aacddf56350 Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Thu, 2 Apr 1998 06:50:02 +0000
Subject: Markup consistency nits.

Fix indentation in code sample in PyArg_ParseTuple() section.

Added one index entry.

Fix include file reference in "Shared Libraries" to print <...> instead of
the upside-down versions of ! and ?.
---
 Doc/ext.tex     | 54 ++++++++++++++++++++++++++++++------------------------
 Doc/ext/ext.tex | 54 ++++++++++++++++++++++++++++++------------------------
 2 files changed, 60 insertions(+), 48 deletions(-)

diff --git a/Doc/ext.tex b/Doc/ext.tex
index 0532212..454e767 100644
--- a/Doc/ext.tex
+++ b/Doc/ext.tex
@@ -85,7 +85,7 @@ as follows:
 >>> status = spam.system("ls -l")
 \end{verbatim}
 
-Begin by creating a file \samp{spammodule.c}.  (In general, if a
+Begin by creating a file \file{spammodule.c}.  (In general, if a
 module is called \samp{spam}, the \C{} file containing its implementation
 is called \file{spammodule.c}; if the module name is very long, like
 \samp{spammify}, the module name can be just \file{spammify.c}.)
@@ -120,6 +120,7 @@ spam_system(self, args)
 {
     char *command;
     int sts;
+
     if (!PyArg_ParseTuple(args, "s", &command))
         return NULL;
     sts = system(command);
@@ -265,6 +266,7 @@ void
 initspam()
 {
     PyObject *m, *d;
+
     m = Py_InitModule("spam", SpamMethods);
     d = PyModule_GetDict(m);
     SpamError = PyErr_NewException("spam.error", NULL, NULL);
@@ -334,8 +336,8 @@ returning \ctype{void}), the corresponding Python function must return
 \end{verbatim}
 
 \cdata{Py_None} is the \C{} name for the special Python object
-\code{None}.  It is a genuine Python object (not a \NULL{}
-pointer, which means ``error'' in most contexts, as we have seen).
+\code{None}.  It is a genuine Python object rather than a \NULL{}
+pointer, which means ``error'' in most contexts, as we have seen.
 
 
 \section{The Module's Method Table and Initialization Function}
@@ -357,7 +359,7 @@ static PyMethodDef SpamMethods[] = {
 Note the third entry (\samp{METH_VARARGS}).  This is a flag telling
 the interpreter the calling convention to be used for the \C{}
 function.  It should normally always be \samp{METH_VARARGS} or
-\samp{METH_VARARGS | METH_KEYWORDS}; a value of \samp{0} means that an
+\samp{METH_VARARGS | METH_KEYWORDS}; a value of \code{0} means that an
 obsolete variant of \cfunction{PyArg_ParseTuple()} is used.
 
 When using only \samp{METH_VARARGS}, the function should expect
@@ -402,15 +404,15 @@ doesn't need to check for errors.
 There are two more things to do before you can use your new extension:
 compiling and linking it with the Python system.  If you use dynamic
 loading, the details depend on the style of dynamic loading your
-system uses; see the chapter on Dynamic Loading for more info about
-this.
+system uses; see the chapter ``Dynamic Loading'' for more information
+about this.
 
 If you can't use dynamic loading, or if you want to make your module a
 permanent part of the Python interpreter, you will have to change the
 configuration setup and rebuild the interpreter.  Luckily, this is
 very simple: just place your file (\file{spammodule.c} for example) in
 the \file{Modules} directory, add a line to the file
-\file{Modules/Setup} describing your file:
+\file{Modules/Setup.local} describing your file:
 
 \begin{verbatim}
 spam spammodule.o
@@ -418,12 +420,12 @@ spam spammodule.o
 
 and rebuild the interpreter by running \program{make} in the toplevel
 directory.  You can also run \program{make} in the \file{Modules}
-subdirectory, but then you must first rebuilt the \file{Makefile}
+subdirectory, but then you must first rebuild \file{Makefile}
 there by running `\program{make} Makefile'.  (This is necessary each
 time you change the \file{Setup} file.)
 
 If your module requires additional libraries to link with, these can
-be listed on the line in the \file{Setup} file as well, for instance:
+be listed on the line in the configuration file as well, for instance:
 
 \begin{verbatim}
 spam spammodule.o -lX11
@@ -747,9 +749,9 @@ Some example calls:
         int left, top, right, bottom, h, v;
         ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
                  &left, &top, &right, &bottom, &h, &v);
-                 /* A rectangle and a point */
-                 /* Possible Python call:
-                    f(((0, 0), (400, 300)), (10, 10)) */
+        /* A rectangle and a point */
+        /* Possible Python call:
+           f(((0, 0), (400, 300)), (10, 10)) */
     }
 
     {
@@ -784,7 +786,8 @@ arguments!  Keyword parameters passed in which are not present in the
 \var{kwlist} will cause \exception{TypeError} to be raised.
 
 Here is an example module which uses keywords, based on an example by
-Geoff Philbrick (\email{philbrick@hks.com}):
+Geoff Philbrick (\email{philbrick@hks.com}):%
+\index{Philbrick, Geoff}
 
 \begin{verbatim}
 #include <stdio.h>
@@ -1110,7 +1113,7 @@ owner.  There are exactly two important exceptions to this rule:
 \cfunction{PyTuple_SetItem()} and \cfunction{PyList_SetItem()}.  These
 functions take over ownership of the item passed to them --- even if
 they fail!  (Note that \cfunction{PyDict_SetItem()} and friends don't
-take over ownership --- they are ``normal''.)
+take over ownership --- they are ``normal.'')
 
 When a \C{} function is called from Python, it borrows references to its
 arguments from the caller.  The caller owns a reference to the object,
@@ -1138,6 +1141,7 @@ reference to a list item.  For instance:
 \begin{verbatim}
 bug(PyObject *list) {
     PyObject *item = PyList_GetItem(list, 0);
+
     PyList_SetItem(list, 1, PyInt_FromLong(0L));
     PyObject_Print(item, stdout, 0); /* BUG! */
 }
@@ -1171,6 +1175,7 @@ function reads:
 \begin{verbatim}
 no_bug(PyObject *list) {
     PyObject *item = PyList_GetItem(list, 0);
+
     Py_INCREF(item);
     PyList_SetItem(list, 1, PyInt_FromLong(0L));
     PyObject_Print(item, stdout, 0);
@@ -1206,7 +1211,7 @@ bug(PyObject *list) {
 \subsection{NULL Pointers}
 \label{nullPointers}
 
-In general, functions that take object references as arguments don't
+In general, functions that take object references as arguments do not
 expect you to pass them \NULL{} pointers, and will dump core (or
 cause later core dumps) if you do so.  Functions that return object
 references generally return \NULL{} only to indicate that an
@@ -1220,7 +1225,7 @@ when a pointer that may be \NULL{} is received, e.g.\ from
 \cfunction{malloc()} or from a function that may raise an exception.
 
 The macros \cfunction{Py_INCREF()} and \cfunction{Py_DECREF()}
-don't check for \NULL{} pointers --- however, their variants
+do not check for \NULL{} pointers --- however, their variants
 \cfunction{Py_XINCREF()} and \cfunction{Py_XDECREF()} do.
 
 The macros for checking for a particular object type
@@ -1329,13 +1334,14 @@ loading.
 \label{sharedlibs}
 
 The following systems support dynamic loading using shared libraries:
-SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!); and probably all
-systems derived from SVR4, or at least those SVR4 derivatives that
-support shared libraries (are there any that don't?).
+SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!), Linux, FreeBSD,
+NetBSD; and probably all systems derived from SVR4, or at least those
+SVR4 derivatives that support shared libraries (are there any that
+don't?).
 
 You don't need to do anything to configure dynamic loading on these
 systems --- the \file{configure} detects the presence of the
-\file{<dlfcn.h>} header file and automatically configures dynamic
+\code{<dlfcn.h>} header file and automatically configures dynamic
 loading.
 
 \subsection{SGI IRIX 4 Dynamic Loading}
@@ -1348,12 +1354,12 @@ work right away so I gave up trying to support it.)
 
 Before you build Python, you first need to fetch and build the
 \code{dl} package written by Jack Jansen.  This is available by
-anonymous ftp from \url{ftp://ftp.cwi.nl/pub/dynload}, file
+anonymous ftp from \url{ftp://ftp.cwi.nl/pub/dynload/}, file
 \file{dl-1.6.tar.Z}.  (The version number may change.)  Follow the
 instructions in the package's \file{README} file to build it.
 
 Once you have built \code{dl}, you can configure Python to use it.  To
-this end, you run the \file{configure} script with the option
+this end, you run the \program{configure} script with the option
 \code{--with-dl=\var{directory}} where \var{directory} is the absolute
 pathname of the \code{dl} directory.
 
@@ -1417,7 +1423,7 @@ contain the options \samp{-I\$(PYTHONTOP) -I\$(PYTHONTOP)/Include}.
 
 You must link the \file{.o} file to produce a shared library.  This is 
 done using a special invocation of the \UNIX{} loader/linker,
-\emph{ld}(1).  Unfortunately the invocation differs slightly per
+\manpage{ld}{1}.  Unfortunately the invocation differs slightly per
 system.
 
 On SunOS 4, use
@@ -1451,7 +1457,7 @@ along the Python module search path.
 \label{irixLinking}
 
 \strong{IMPORTANT:} You must compile your extension module with the
-additional \C{} flag \samp{-G0} (or \samp{-G 0}).  This instruct the
+additional \C{} flag \samp{-G0} (or \samp{-G 0}).  This instructs the
 assembler to generate position-independent code.
 
 You don't need to link the resulting \file{spammodule.o} file; just
diff --git a/Doc/ext/ext.tex b/Doc/ext/ext.tex
index 0532212..454e767 100644
--- a/Doc/ext/ext.tex
+++ b/Doc/ext/ext.tex
@@ -85,7 +85,7 @@ as follows:
 >>> status = spam.system("ls -l")
 \end{verbatim}
 
-Begin by creating a file \samp{spammodule.c}.  (In general, if a
+Begin by creating a file \file{spammodule.c}.  (In general, if a
 module is called \samp{spam}, the \C{} file containing its implementation
 is called \file{spammodule.c}; if the module name is very long, like
 \samp{spammify}, the module name can be just \file{spammify.c}.)
@@ -120,6 +120,7 @@ spam_system(self, args)
 {
     char *command;
     int sts;
+
     if (!PyArg_ParseTuple(args, "s", &command))
         return NULL;
     sts = system(command);
@@ -265,6 +266,7 @@ void
 initspam()
 {
     PyObject *m, *d;
+
     m = Py_InitModule("spam", SpamMethods);
     d = PyModule_GetDict(m);
     SpamError = PyErr_NewException("spam.error", NULL, NULL);
@@ -334,8 +336,8 @@ returning \ctype{void}), the corresponding Python function must return
 \end{verbatim}
 
 \cdata{Py_None} is the \C{} name for the special Python object
-\code{None}.  It is a genuine Python object (not a \NULL{}
-pointer, which means ``error'' in most contexts, as we have seen).
+\code{None}.  It is a genuine Python object rather than a \NULL{}
+pointer, which means ``error'' in most contexts, as we have seen.
 
 
 \section{The Module's Method Table and Initialization Function}
@@ -357,7 +359,7 @@ static PyMethodDef SpamMethods[] = {
 Note the third entry (\samp{METH_VARARGS}).  This is a flag telling
 the interpreter the calling convention to be used for the \C{}
 function.  It should normally always be \samp{METH_VARARGS} or
-\samp{METH_VARARGS | METH_KEYWORDS}; a value of \samp{0} means that an
+\samp{METH_VARARGS | METH_KEYWORDS}; a value of \code{0} means that an
 obsolete variant of \cfunction{PyArg_ParseTuple()} is used.
 
 When using only \samp{METH_VARARGS}, the function should expect
@@ -402,15 +404,15 @@ doesn't need to check for errors.
 There are two more things to do before you can use your new extension:
 compiling and linking it with the Python system.  If you use dynamic
 loading, the details depend on the style of dynamic loading your
-system uses; see the chapter on Dynamic Loading for more info about
-this.
+system uses; see the chapter ``Dynamic Loading'' for more information
+about this.
 
 If you can't use dynamic loading, or if you want to make your module a
 permanent part of the Python interpreter, you will have to change the
 configuration setup and rebuild the interpreter.  Luckily, this is
 very simple: just place your file (\file{spammodule.c} for example) in
 the \file{Modules} directory, add a line to the file
-\file{Modules/Setup} describing your file:
+\file{Modules/Setup.local} describing your file:
 
 \begin{verbatim}
 spam spammodule.o
@@ -418,12 +420,12 @@ spam spammodule.o
 
 and rebuild the interpreter by running \program{make} in the toplevel
 directory.  You can also run \program{make} in the \file{Modules}
-subdirectory, but then you must first rebuilt the \file{Makefile}
+subdirectory, but then you must first rebuild \file{Makefile}
 there by running `\program{make} Makefile'.  (This is necessary each
 time you change the \file{Setup} file.)
 
 If your module requires additional libraries to link with, these can
-be listed on the line in the \file{Setup} file as well, for instance:
+be listed on the line in the configuration file as well, for instance:
 
 \begin{verbatim}
 spam spammodule.o -lX11
@@ -747,9 +749,9 @@ Some example calls:
         int left, top, right, bottom, h, v;
         ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
                  &left, &top, &right, &bottom, &h, &v);
-                 /* A rectangle and a point */
-                 /* Possible Python call:
-                    f(((0, 0), (400, 300)), (10, 10)) */
+        /* A rectangle and a point */
+        /* Possible Python call:
+           f(((0, 0), (400, 300)), (10, 10)) */
     }
 
     {
@@ -784,7 +786,8 @@ arguments!  Keyword parameters passed in which are not present in the
 \var{kwlist} will cause \exception{TypeError} to be raised.
 
 Here is an example module which uses keywords, based on an example by
-Geoff Philbrick (\email{philbrick@hks.com}):
+Geoff Philbrick (\email{philbrick@hks.com}):%
+\index{Philbrick, Geoff}
 
 \begin{verbatim}
 #include <stdio.h>
@@ -1110,7 +1113,7 @@ owner.  There are exactly two important exceptions to this rule:
 \cfunction{PyTuple_SetItem()} and \cfunction{PyList_SetItem()}.  These
 functions take over ownership of the item passed to them --- even if
 they fail!  (Note that \cfunction{PyDict_SetItem()} and friends don't
-take over ownership --- they are ``normal''.)
+take over ownership --- they are ``normal.'')
 
 When a \C{} function is called from Python, it borrows references to its
 arguments from the caller.  The caller owns a reference to the object,
@@ -1138,6 +1141,7 @@ reference to a list item.  For instance:
 \begin{verbatim}
 bug(PyObject *list) {
     PyObject *item = PyList_GetItem(list, 0);
+
     PyList_SetItem(list, 1, PyInt_FromLong(0L));
     PyObject_Print(item, stdout, 0); /* BUG! */
 }
@@ -1171,6 +1175,7 @@ function reads:
 \begin{verbatim}
 no_bug(PyObject *list) {
     PyObject *item = PyList_GetItem(list, 0);
+
     Py_INCREF(item);
     PyList_SetItem(list, 1, PyInt_FromLong(0L));
     PyObject_Print(item, stdout, 0);
@@ -1206,7 +1211,7 @@ bug(PyObject *list) {
 \subsection{NULL Pointers}
 \label{nullPointers}
 
-In general, functions that take object references as arguments don't
+In general, functions that take object references as arguments do not
 expect you to pass them \NULL{} pointers, and will dump core (or
 cause later core dumps) if you do so.  Functions that return object
 references generally return \NULL{} only to indicate that an
@@ -1220,7 +1225,7 @@ when a pointer that may be \NULL{} is received, e.g.\ from
 \cfunction{malloc()} or from a function that may raise an exception.
 
 The macros \cfunction{Py_INCREF()} and \cfunction{Py_DECREF()}
-don't check for \NULL{} pointers --- however, their variants
+do not check for \NULL{} pointers --- however, their variants
 \cfunction{Py_XINCREF()} and \cfunction{Py_XDECREF()} do.
 
 The macros for checking for a particular object type
@@ -1329,13 +1334,14 @@ loading.
 \label{sharedlibs}
 
 The following systems support dynamic loading using shared libraries:
-SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!); and probably all
-systems derived from SVR4, or at least those SVR4 derivatives that
-support shared libraries (are there any that don't?).
+SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!), Linux, FreeBSD,
+NetBSD; and probably all systems derived from SVR4, or at least those
+SVR4 derivatives that support shared libraries (are there any that
+don't?).
 
 You don't need to do anything to configure dynamic loading on these
 systems --- the \file{configure} detects the presence of the
-\file{<dlfcn.h>} header file and automatically configures dynamic
+\code{<dlfcn.h>} header file and automatically configures dynamic
 loading.
 
 \subsection{SGI IRIX 4 Dynamic Loading}
@@ -1348,12 +1354,12 @@ work right away so I gave up trying to support it.)
 
 Before you build Python, you first need to fetch and build the
 \code{dl} package written by Jack Jansen.  This is available by
-anonymous ftp from \url{ftp://ftp.cwi.nl/pub/dynload}, file
+anonymous ftp from \url{ftp://ftp.cwi.nl/pub/dynload/}, file
 \file{dl-1.6.tar.Z}.  (The version number may change.)  Follow the
 instructions in the package's \file{README} file to build it.
 
 Once you have built \code{dl}, you can configure Python to use it.  To
-this end, you run the \file{configure} script with the option
+this end, you run the \program{configure} script with the option
 \code{--with-dl=\var{directory}} where \var{directory} is the absolute
 pathname of the \code{dl} directory.
 
@@ -1417,7 +1423,7 @@ contain the options \samp{-I\$(PYTHONTOP) -I\$(PYTHONTOP)/Include}.
 
 You must link the \file{.o} file to produce a shared library.  This is 
 done using a special invocation of the \UNIX{} loader/linker,
-\emph{ld}(1).  Unfortunately the invocation differs slightly per
+\manpage{ld}{1}.  Unfortunately the invocation differs slightly per
 system.
 
 On SunOS 4, use
@@ -1451,7 +1457,7 @@ along the Python module search path.
 \label{irixLinking}
 
 \strong{IMPORTANT:} You must compile your extension module with the
-additional \C{} flag \samp{-G0} (or \samp{-G 0}).  This instruct the
+additional \C{} flag \samp{-G0} (or \samp{-G 0}).  This instructs the
 assembler to generate position-independent code.
 
 You don't need to link the resulting \file{spammodule.o} file; just
-- 
cgit v0.12

