From cdea8a3c60d42e94ae0f1f8bfe6c9339c73ff5ba Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Sat, 14 Mar 1998 06:17:43 +0000 Subject: [PATCH] Logical markup. Wrap general Message class description in a {classdesc} instead of nothing at all. --- Doc/lib/librfc822.tex | 105 ++++++++++++++++++++++-------------------- Doc/librfc822.tex | 105 ++++++++++++++++++++++-------------------- 2 files changed, 108 insertions(+), 102 deletions(-) diff --git a/Doc/lib/librfc822.tex b/Doc/lib/librfc822.tex index d764ce65401..bb192cd8c3a 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 d764ce65401..bb192cd8c3a 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