mass changes; fix titles; add examples; correct typos; clarifications;

 unified style; etc.

7 files changed, 41 insertions, 22 deletions

diff --git a/Doc/mac/libctb.tex b/Doc/mac/libctb.tex
index 3928498..1cda336 100644
--- a/Doc/mac/libctb.tex
+++ b/Doc/mac/libctb.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{ctb}}
+\section{Built-in Module \sectcode{ctb}}
 \bimodindex{ctb}
 \renewcommand{\indexsubitem}{(in module ctb)}
 
@@ -44,7 +44,7 @@ Alternatively, passing \code{None} will result in default buffer sizes.
 For all connection methods that take a \var{timeout} argument, a value
 of \code{-1} is indefinite, meaning that the command runs to completion.
 
-\renewcommand{\indexsubitem}{(connection object method)}
+\renewcommand{\indexsubitem}{(connection object attribute)}
 
 \begin{datadesc}{callback}
 If this member is set to a value other than \code{None} it should point
@@ -59,6 +59,8 @@ calls for the time being.
 \end{datadesc}
 
 
+\renewcommand{\indexsubitem}{(connection object method)}
+
 \begin{funcdesc}{Open}{timeout}
 Open an outgoing connection, waiting at most \var{timeout} seconds for
 the connection to be established.
diff --git a/Doc/mac/libmac.tex b/Doc/mac/libmac.tex
index 62babda..545b62c 100644
--- a/Doc/mac/libmac.tex
+++ b/Doc/mac/libmac.tex
@@ -2,7 +2,7 @@
 
 The modules in this chapter are available on the Apple Macintosh only.
 
-\section{Built-in module \sectcode{mac}}
+\section{Built-in Module \sectcode{mac}}
 
 \bimodindex{mac}
 This module provides a subset of the operating system dependent
@@ -22,7 +22,7 @@ The following functions are available in this module:
 \code{unlink},
 as well as the exception \code{error}.
 
-\section{Standard module \sectcode{macpath}}
+\section{Standard Module \sectcode{macpath}}
 
 \stmodindex{macpath}
 This module provides a subset of the pathname manipulation functions
diff --git a/Doc/mac/libmacconsole.tex b/Doc/mac/libmacconsole.tex
index 2f60890..42d4e51 100644
--- a/Doc/mac/libmacconsole.tex
+++ b/Doc/mac/libmacconsole.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{macconsole}}
+\section{Built-in Module \sectcode{macconsole}}
 \bimodindex{macconsole}
 
 \renewcommand{\indexsubitem}{(in module macconsole)}
@@ -62,7 +62,7 @@ If set non-zero, the window will wait for user action before closing.
 
 \subsection{console window object}
 
-\renewcommand{\indexsubitem}{(console window method)}
+\renewcommand{\indexsubitem}{(console window attribute)}
 
 \begin{datadesc}{file}
 The file object corresponding to this console window. If the file is
@@ -70,6 +70,8 @@ buffered, you should call \code{file.flush()} between \code{write()}
 and \code{read()} calls.
 \end{datadesc}
 
+\renewcommand{\indexsubitem}{(console window method)}
+
 \begin{funcdesc}{setmode}{mode}
 Set the input mode of the console to \var{C_ECHO}, etc.
 \end{funcdesc}
diff --git a/Doc/mac/libmacdnr.tex b/Doc/mac/libmacdnr.tex
index ca75971..cd3625c 100644
--- a/Doc/mac/libmacdnr.tex
+++ b/Doc/mac/libmacdnr.tex
@@ -1,5 +1,5 @@
 
-\section{Built-in module \sectcode{macdnr}}
+\section{Built-in Module \sectcode{macdnr}}
 \bimodindex{macdnr}
 
 This module provides an interface to the Macintosh Domain Name
@@ -75,6 +75,8 @@ Wait for the query to complete.
 Return 1 if the query is complete.
 \end{funcdesc}
 
+\renewcommand{\indexsubitem}{(dnr result object attribute)}
+
 \begin{datadesc}{rtnCode}
 The error code returned by the query.
 \end{datadesc}
diff --git a/Doc/mac/libmacfs.tex b/Doc/mac/libmacfs.tex
index 80ec76d..74d1970 100644
--- a/Doc/mac/libmacfs.tex
+++ b/Doc/mac/libmacfs.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{macfs}}
+\section{Built-in Module \sectcode{macfs}}
 \bimodindex{macfs}
 
 \renewcommand{\indexsubitem}{(in module macfs)}
@@ -18,11 +18,14 @@ Create an FSSpec object for the specified file.
 
 \begin{funcdesc}{RawFSSpec}{data}
 Create an FSSpec object given the raw data for the C structure for the
-FSSpec.
+FSSpec as a string.  This is mainly useful if you have obtained an
+FSSpec structure over a network.
 \end{funcdesc}
 
 \begin{funcdesc}{RawAlias}{data}
-Create an Alias object given the raw data for the alias.
+Create an Alias object given the raw data for the C structure for the
+alias as a string.  This is mainly useful if you have obtained an
+FSSpec structure over a network.
 \end{funcdesc}
 
 \begin{funcdesc}{ResolveAliasFile}{file}
@@ -56,12 +59,13 @@ dialog. Return an FSSpec object and a success-indicator.
 
 \subsection{FSSpec objects}
 
-\renewcommand{\indexsubitem}{(FSSpec object method)}
+\renewcommand{\indexsubitem}{(FSSpec object attribute)}
 \begin{datadesc}{data}
 The raw data from the FSSpec object, suitable for passing
 to other applications, for instance.
 \end{datadesc}
 
+\renewcommand{\indexsubitem}{(FSSpec object method)}
 \begin{funcdesc}{as_pathname}{}
 Return the full pathname of the file described by the FSSpec object.
 \end{funcdesc}
@@ -91,12 +95,13 @@ Set the 4-char creator and type of the file.
 
 \subsection{alias objects}
 
-\renewcommand{\indexsubitem}{(alias object method)}
+\renewcommand{\indexsubitem}{(alias object attribute)}
 \begin{datadesc}{data}
 The raw data for the Alias record, suitable for storing in a resource
 or transmitting to other programs.
 \end{datadesc}
 
+\renewcommand{\indexsubitem}{(alias object method)}
 \begin{funcdesc}{Resolve}{\optional{file}}
 Resolve the alias. If the alias was created as a relative alias you
 should pass the file relative to which it is. Return the FSSpec for
diff --git a/Doc/mac/libmacspeech.tex b/Doc/mac/libmacspeech.tex
index 737016e..7480482 100644
--- a/Doc/mac/libmacspeech.tex
+++ b/Doc/mac/libmacspeech.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{macspeech}}
+\section{Built-in Module \sectcode{macspeech}}
 \bimodindex{macspeech}
 
 \renewcommand{\indexsubitem}{(in module macspeech)}
diff --git a/Doc/mac/libmactcp.tex b/Doc/mac/libmactcp.tex
index 11c0114..561284b 100644
--- a/Doc/mac/libmactcp.tex
+++ b/Doc/mac/libmactcp.tex
@@ -1,5 +1,6 @@
-\section{Built-in module \sectcode{mactcp}}
+\section{Built-in Module \sectcode{mactcp}}
 \bimodindex{mactcp}
+
 \renewcommand{\indexsubitem}{(in module mactcp)}
 
 This module provides an interface to the Macintosh TCP/IP driver
@@ -37,8 +38,9 @@ on this port). \var{port} is the UDP port number you want to receive
 datagrams on, a value of zero will make MacTCP select a free port.
 \end{funcdesc}
 
-\subsection{TCP stream objects}
-\renewcommand{\indexsubitem}{(TCP stream method)}
+\subsection{TCP Stream Objects}
+
+\renewcommand{\indexsubitem}{(TCP stream attribute)}
 
 \begin{datadesc}{asr}
 When set to a value different than \code{None} this should point to a
@@ -50,6 +52,8 @@ is a Python addition to the MacTCP semantics.
 It is safe to do further calls from the \code{asr}.
 \end{datadesc}
 
+\renewcommand{\indexsubitem}{(TCP stream method)}
+
 \begin{funcdesc}{PassiveOpen}{port}
 Wait for an incoming connection on TCP port \var{port} (zero makes the
 system pick a free port). The call returns immediately, and you should
@@ -104,15 +108,17 @@ Forcibly close both sides of a connection, ignoring outstanding data.
 \end{funcdesc}
 
 \begin{funcdesc}{Status}{}
-Return a TCP status object for this stream.
+Return a TCP status object for this stream giving the current status
+(see below).
 \end{funcdesc}
 
-\subsection{TCP status objects}
+\subsection{TCP Status Objects}
 This object has no methods, only some members holding information on
 the connection. A complete description of all fields in this objects
 can be found in the Apple documentation. The most interesting ones are:
 
-\renewcommand{\indexsubitem}{(TCP status method)}
+\renewcommand{\indexsubitem}{(TCP status attribute)}
+
 \begin{datadesc}{localHost}
 \dataline{localPort}
 \dataline{remoteHost}
@@ -137,11 +143,11 @@ without blocking).
 
 
 
-\subsection{UDP stream objects}
+\subsection{UDP Stream Objects}
 Note that, unlike the name suggests, there is nothing stream-like
 about UDP.
 
-\renewcommand{\indexsubitem}{(UDP stream method)}
+\renewcommand{\indexsubitem}{(UDP stream attribute)}
 
 \begin{datadesc}{asr}
 The asynchronous service routine to be called on events such as
@@ -153,9 +159,11 @@ single argument, the event code.
 A read-only member giving the port number of this UDP stream.
 \end{datadesc}
 
+\renewcommand{\indexsubitem}{(UDP stream method)}
+
 \begin{funcdesc}{Read}{timeout}
 Read a datagram, waiting at most \var{timeout} seconds ($-1$ is
-indefinite). Return the data.
+infinite).  Return the data.
 \end{funcdesc}
 
 \begin{funcdesc}{Write}{host\, port\, buf}