Logical markup.

Wrap general Message class description in a {classdesc} instead of nothing at
all.

2 files changed, 108 insertions, 102 deletions

diff --git a/Doc/lib/librfc822.tex b/Doc/lib/librfc822.tex
index d764ce6..bb192cd 100644
--- a/Doc/lib/librfc822.tex
+++ b/Doc/lib/librfc822.tex
@@ -2,20 +2,19 @@
 \label{module-rfc822}
 \stmodindex{rfc822}
 
-\setindexsubitem{(in module rfc822)}
 
-This module defines a class, \code{Message}, which represents a
+This module defines a class, \class{Message}, which represents a
 collection of ``email headers'' as defined by the Internet standard
 \rfc{822}.  It is used in various contexts, usually to read such
 headers from a file.
 
 Note that there's a separate module to read \UNIX{}, MH, and MMDF
-style mailbox files: \code{mailbox}.
-\refstmodindex{mailbox}
+style mailbox files: \module{mailbox}\refstmodindex{mailbox}.
 
-A \code{Message} instance is instantiated with an open file object as
-parameter.  The optional \code{seekable} parameter indicates if the
-file object is seekable; the default value is 1 for true.
+\begin{classdesc}{Message}{file\optional{, seekable}}
+A \class{Message} instance is instantiated with an open file object as
+parameter.  The optional \var{seekable} parameter indicates if the
+file object is seekable; the default value is \code{1} for true.
 Instantiation reads headers from the file up to a blank line and
 stores them in the instance; after instantiation, the file is
 positioned directly after the blank line that terminates the headers.
@@ -25,44 +24,46 @@ by a single linefeed; a terminating CR-LF is replaced by a single
 linefeed before the line is stored.
 
 All header matching is done independent of upper or lower case;
-e.g. \code{m['From']}, \code{m['from']} and \code{m['FROM']} all yield
-the same result.
+e.g. \code{\var{m}['From']}, \code{\var{m}['from']} and
+\code{\var{m}['FROM']} all yield the same result.
+\end{classdesc}
 
 \begin{funcdesc}{parsedate}{date}
-Attempts to parse a date according to the rules in \rfc{822}.  however,
-some mailers don't follow that format as specified, so
-\code{parsedate()} tries to guess correctly in such cases. 
+Attempts to parse a date according to the rules in \rfc{822}.
+however, some mailers don't follow that format as specified, so
+\function{parsedate()} tries to guess correctly in such cases. 
 \var{date} is a string containing an \rfc{822} date, such as 
-\code{"Mon, 20 Nov 1995 19:12:08 -0500"}.  If it succeeds in parsing
-the date, \code{parsedate()} returns a 9-tuple that can be passed
-directly to \code{time.mktime()}; otherwise \code{None} will be
+\code{'Mon, 20 Nov 1995 19:12:08 -0500'}.  If it succeeds in parsing
+the date, \function{parsedate()} returns a 9-tuple that can be passed
+directly to \function{time.mktime()}; otherwise \code{None} will be
 returned.  
 \end{funcdesc}
 
 \begin{funcdesc}{parsedate_tz}{date}
-Performs the same function as \code{parsedate()}, but returns either
-\code{None} or a 10-tuple; the first 9 elements make up a tuple that
-can be passed directly to \code{time.mktime()}, and the tenth is the
-offset of the date's timezone from UTC (which is the official term
-for Greenwich Mean Time).  (Note that the sign of the timezone offset
-is the opposite of the sign of the \code{time.timezone} variable for
-the same timezone; the latter variable follows the \POSIX{} standard
-while this module follows \rfc{822}.)  If the input string has no
-timezone, the last element of the tuple returned is \code{None}.
+Performs the same function as \function{parsedate()}, but returns
+either \code{None} or a 10-tuple; the first 9 elements make up a tuple
+that can be passed directly to \function{time.mktime()}, and the tenth
+is the offset of the date's timezone from UTC (which is the official
+term for Greenwich Mean Time).  (Note that the sign of the timezone
+offset is the opposite of the sign of the \code{time.timezone}
+variable for the same timezone; the latter variable follows the
+\POSIX{} standard while this module follows \rfc{822}.)  If the input
+string has no timezone, the last element of the tuple returned is
+\code{None}.
 \end{funcdesc}
 
 \begin{funcdesc}{mktime_tz}{tuple}
-Turn a 10-tuple as returned by \code{parsedate_tz()} into a UTC timestamp.
-It the timezone item in the tuple is \code{None}, assume local time.
-Minor deficiency: this first interprets the first 8 elements as a
-local time and then compensates for the timezone difference;
-this may yield a slight error around daylight savings time
+Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC
+timestamp.  It the timezone item in the tuple is \code{None}, assume
+local time.  Minor deficiency: this first interprets the first 8
+elements as a local time and then compensates for the timezone
+difference; this may yield a slight error around daylight savings time
 switch dates.  Not enough to worry about for common use.
 \end{funcdesc}
 
 \subsection{Message Objects}
 
-A \code{Message} instance has the following methods:
+A \class{Message} instance has the following methods:
 
 \begin{funcdesc}{rewindbody}{}
 Seek to the start of the message body.  This only works if the file
@@ -92,16 +93,17 @@ no header matching \var{name}.
 
 \begin{funcdesc}{getheader}{name}
 Like \code{getrawheader(\var{name})}, but strip leading and trailing
-whitespace (but not internal whitespace).
+whitespace.  Internal whitespace is not stripped.
 \end{funcdesc}
 
 \begin{funcdesc}{getaddr}{name}
-Return a pair (full name, email address) parsed from the string
-returned by \code{getheader(\var{name})}.  If no header matching
-\var{name} exists, return \code{None, None}; otherwise both the full
-name and the address are (possibly empty )strings.
+Return a pair \code{(\var{full name}, \var{email address})} parsed
+from the string returned by \code{getheader(\var{name})}.  If no
+header matching \var{name} exists, return \code{(None, None)};
+otherwise both the full name and the address are (possibly empty)
+strings.
 
-Example: If \code{m}'s first \code{From} header contains the string\\
+Example: If \var{m}'s first \code{From} header contains the string
 \code{'jack@cwi.nl (Jack Jansen)'}, then
 \code{m.getaddr('From')} will yield the pair
 \code{('Jack Jansen', 'jack@cwi.nl')}.
@@ -113,17 +115,17 @@ exact same result.
 \begin{funcdesc}{getaddrlist}{name}
 This is similar to \code{getaddr(\var{list})}, but parses a header
 containing a list of email addresses (e.g. a \code{To} header) and
-returns a list of (full name, email address) pairs (even if there was
-only one address in the header).  If there is no header matching
-\var{name}, return an empty list.
+returns a list of \code{(\var{full name}, \var{email address})} pairs
+(even if there was only one address in the header).  If there is no
+header matching \var{name}, return an empty list.
 
 XXX The current version of this function is not really correct.  It
 yields bogus results if a full name contains a comma.
 \end{funcdesc}
 
 \begin{funcdesc}{getdate}{name}
-Retrieve a header using \code{getheader} and parse it into a 9-tuple
-compatible with \code{time.mktime()}.  If there is no header matching
+Retrieve a header using \method{getheader()} and parse it into a 9-tuple
+compatible with \function{time.mktime()}.  If there is no header matching
 \var{name}, or it is unparsable, return \code{None}.
 
 Date parsing appears to be a black art, and not all mailers adhere to
@@ -133,21 +135,22 @@ function may occasionally yield an incorrect result.
 \end{funcdesc}
 
 \begin{funcdesc}{getdate_tz}{name}
-Retrieve a header using \code{getheader} and parse it into a 10-tuple;
-the first 9 elements will make a tuple compatible with
-\code{time.mktime()}, and the 10th is a number giving the offset of
-the date's timezone from UTC.  Similarly to \code{getdate()}, if
+Retrieve a header using \method{getheader()} and parse it into a
+10-tuple; the first 9 elements will make a tuple compatible with
+\function{time.mktime()}, and the 10th is a number giving the offset
+of the date's timezone from UTC.  Similarly to \method{getdate()}, if
 there is no header matching \var{name}, or it is unparsable, return
 \code{None}. 
 \end{funcdesc}
 
-\code{Message} instances also support a read-only mapping interface.
-In particular: \code{m[name]} is the same as \code{m.getheader(name)};
-and \code{len(m)}, \code{m.has_key(name)}, \code{m.keys()},
-\code{m.values()} and \code{m.items()} act as expected (and
-consistently).
+\class{Message} instances also support a read-only mapping interface.
+In particular: \code{\var{m}[name]} is the same as
+\code{\var{m}.getheader(name)}; and \code{len(\var{m})},
+\code{\var{m}.has_key(name)}, \code{\var{m}.keys()},
+\code{\var{m}.values()} and \code{\var{m}.items()} act as expected
+(and consistently).
 
-Finally, \code{Message} instances have two public instance variables:
+Finally, \class{Message} instances have two public instance variables:
 
 \begin{datadesc}{headers}
 A list containing the entire set of header lines, in the order in
diff --git a/Doc/librfc822.tex b/Doc/librfc822.tex
index d764ce6..bb192cd 100644
--- a/Doc/librfc822.tex
+++ b/Doc/librfc822.tex
@@ -2,20 +2,19 @@
 \label{module-rfc822}
 \stmodindex{rfc822}
 
-\setindexsubitem{(in module rfc822)}
 
-This module defines a class, \code{Message}, which represents a
+This module defines a class, \class{Message}, which represents a
 collection of ``email headers'' as defined by the Internet standard
 \rfc{822}.  It is used in various contexts, usually to read such
 headers from a file.
 
 Note that there's a separate module to read \UNIX{}, MH, and MMDF
-style mailbox files: \code{mailbox}.
-\refstmodindex{mailbox}
+style mailbox files: \module{mailbox}\refstmodindex{mailbox}.
 
-A \code{Message} instance is instantiated with an open file object as
-parameter.  The optional \code{seekable} parameter indicates if the
-file object is seekable; the default value is 1 for true.
+\begin{classdesc}{Message}{file\optional{, seekable}}
+A \class{Message} instance is instantiated with an open file object as
+parameter.  The optional \var{seekable} parameter indicates if the
+file object is seekable; the default value is \code{1} for true.
 Instantiation reads headers from the file up to a blank line and
 stores them in the instance; after instantiation, the file is
 positioned directly after the blank line that terminates the headers.
@@ -25,44 +24,46 @@ by a single linefeed; a terminating CR-LF is replaced by a single
 linefeed before the line is stored.
 
 All header matching is done independent of upper or lower case;
-e.g. \code{m['From']}, \code{m['from']} and \code{m['FROM']} all yield
-the same result.
+e.g. \code{\var{m}['From']}, \code{\var{m}['from']} and
+\code{\var{m}['FROM']} all yield the same result.
+\end{classdesc}
 
 \begin{funcdesc}{parsedate}{date}
-Attempts to parse a date according to the rules in \rfc{822}.  however,
-some mailers don't follow that format as specified, so
-\code{parsedate()} tries to guess correctly in such cases. 
+Attempts to parse a date according to the rules in \rfc{822}.
+however, some mailers don't follow that format as specified, so
+\function{parsedate()} tries to guess correctly in such cases. 
 \var{date} is a string containing an \rfc{822} date, such as 
-\code{"Mon, 20 Nov 1995 19:12:08 -0500"}.  If it succeeds in parsing
-the date, \code{parsedate()} returns a 9-tuple that can be passed
-directly to \code{time.mktime()}; otherwise \code{None} will be
+\code{'Mon, 20 Nov 1995 19:12:08 -0500'}.  If it succeeds in parsing
+the date, \function{parsedate()} returns a 9-tuple that can be passed
+directly to \function{time.mktime()}; otherwise \code{None} will be
 returned.  
 \end{funcdesc}
 
 \begin{funcdesc}{parsedate_tz}{date}
-Performs the same function as \code{parsedate()}, but returns either
-\code{None} or a 10-tuple; the first 9 elements make up a tuple that
-can be passed directly to \code{time.mktime()}, and the tenth is the
-offset of the date's timezone from UTC (which is the official term
-for Greenwich Mean Time).  (Note that the sign of the timezone offset
-is the opposite of the sign of the \code{time.timezone} variable for
-the same timezone; the latter variable follows the \POSIX{} standard
-while this module follows \rfc{822}.)  If the input string has no
-timezone, the last element of the tuple returned is \code{None}.
+Performs the same function as \function{parsedate()}, but returns
+either \code{None} or a 10-tuple; the first 9 elements make up a tuple
+that can be passed directly to \function{time.mktime()}, and the tenth
+is the offset of the date's timezone from UTC (which is the official
+term for Greenwich Mean Time).  (Note that the sign of the timezone
+offset is the opposite of the sign of the \code{time.timezone}
+variable for the same timezone; the latter variable follows the
+\POSIX{} standard while this module follows \rfc{822}.)  If the input
+string has no timezone, the last element of the tuple returned is
+\code{None}.
 \end{funcdesc}
 
 \begin{funcdesc}{mktime_tz}{tuple}
-Turn a 10-tuple as returned by \code{parsedate_tz()} into a UTC timestamp.
-It the timezone item in the tuple is \code{None}, assume local time.
-Minor deficiency: this first interprets the first 8 elements as a
-local time and then compensates for the timezone difference;
-this may yield a slight error around daylight savings time
+Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC
+timestamp.  It the timezone item in the tuple is \code{None}, assume
+local time.  Minor deficiency: this first interprets the first 8
+elements as a local time and then compensates for the timezone
+difference; this may yield a slight error around daylight savings time
 switch dates.  Not enough to worry about for common use.
 \end{funcdesc}
 
 \subsection{Message Objects}
 
-A \code{Message} instance has the following methods:
+A \class{Message} instance has the following methods:
 
 \begin{funcdesc}{rewindbody}{}
 Seek to the start of the message body.  This only works if the file
@@ -92,16 +93,17 @@ no header matching \var{name}.
 
 \begin{funcdesc}{getheader}{name}
 Like \code{getrawheader(\var{name})}, but strip leading and trailing
-whitespace (but not internal whitespace).
+whitespace.  Internal whitespace is not stripped.
 \end{funcdesc}
 
 \begin{funcdesc}{getaddr}{name}
-Return a pair (full name, email address) parsed from the string
-returned by \code{getheader(\var{name})}.  If no header matching
-\var{name} exists, return \code{None, None}; otherwise both the full
-name and the address are (possibly empty )strings.
+Return a pair \code{(\var{full name}, \var{email address})} parsed
+from the string returned by \code{getheader(\var{name})}.  If no
+header matching \var{name} exists, return \code{(None, None)};
+otherwise both the full name and the address are (possibly empty)
+strings.
 
-Example: If \code{m}'s first \code{From} header contains the string\\
+Example: If \var{m}'s first \code{From} header contains the string
 \code{'jack@cwi.nl (Jack Jansen)'}, then
 \code{m.getaddr('From')} will yield the pair
 \code{('Jack Jansen', 'jack@cwi.nl')}.
@@ -113,17 +115,17 @@ exact same result.
 \begin{funcdesc}{getaddrlist}{name}
 This is similar to \code{getaddr(\var{list})}, but parses a header
 containing a list of email addresses (e.g. a \code{To} header) and
-returns a list of (full name, email address) pairs (even if there was
-only one address in the header).  If there is no header matching
-\var{name}, return an empty list.
+returns a list of \code{(\var{full name}, \var{email address})} pairs
+(even if there was only one address in the header).  If there is no
+header matching \var{name}, return an empty list.
 
 XXX The current version of this function is not really correct.  It
 yields bogus results if a full name contains a comma.
 \end{funcdesc}
 
 \begin{funcdesc}{getdate}{name}
-Retrieve a header using \code{getheader} and parse it into a 9-tuple
-compatible with \code{time.mktime()}.  If there is no header matching
+Retrieve a header using \method{getheader()} and parse it into a 9-tuple
+compatible with \function{time.mktime()}.  If there is no header matching
 \var{name}, or it is unparsable, return \code{None}.
 
 Date parsing appears to be a black art, and not all mailers adhere to
@@ -133,21 +135,22 @@ function may occasionally yield an incorrect result.
 \end{funcdesc}
 
 \begin{funcdesc}{getdate_tz}{name}
-Retrieve a header using \code{getheader} and parse it into a 10-tuple;
-the first 9 elements will make a tuple compatible with
-\code{time.mktime()}, and the 10th is a number giving the offset of
-the date's timezone from UTC.  Similarly to \code{getdate()}, if
+Retrieve a header using \method{getheader()} and parse it into a
+10-tuple; the first 9 elements will make a tuple compatible with
+\function{time.mktime()}, and the 10th is a number giving the offset
+of the date's timezone from UTC.  Similarly to \method{getdate()}, if
 there is no header matching \var{name}, or it is unparsable, return
 \code{None}. 
 \end{funcdesc}
 
-\code{Message} instances also support a read-only mapping interface.
-In particular: \code{m[name]} is the same as \code{m.getheader(name)};
-and \code{len(m)}, \code{m.has_key(name)}, \code{m.keys()},
-\code{m.values()} and \code{m.items()} act as expected (and
-consistently).
+\class{Message} instances also support a read-only mapping interface.
+In particular: \code{\var{m}[name]} is the same as
+\code{\var{m}.getheader(name)}; and \code{len(\var{m})},
+\code{\var{m}.has_key(name)}, \code{\var{m}.keys()},
+\code{\var{m}.values()} and \code{\var{m}.items()} act as expected
+(and consistently).
 
-Finally, \code{Message} instances have two public instance variables:
+Finally, \class{Message} instances have two public instance variables:
 
 \begin{datadesc}{headers}
 A list containing the entire set of header lines, in the order in