Documentation for new RFC 3548 functions.
diff --git a/Doc/lib/libbase64.tex b/Doc/lib/libbase64.tex
index 91f4818..b51f8c8 100644
--- a/Doc/lib/libbase64.tex
+++ b/Doc/lib/libbase64.tex
@@ -1,25 +1,118 @@
\section{\module{base64} ---
- Encode and decode MIME base64 data}
+ RFC 3548: Base16, Base32, Base64 Data Encodings}
\declaremodule{standard}{base64}
-\modulesynopsis{Encode and decode files using the MIME base64 data.}
+\modulesynopsis{RFC 3548: Base16, Base32, Base64 Data Encodings}
\indexii{base64}{encoding}
\index{MIME!base64 encoding}
-This module performs base64 encoding and decoding of arbitrary binary
-strings into text strings that can be safely sent by email or included
-as part of an HTTP POST request. The
-encoding scheme is defined in \rfc{1521} (\emph{MIME
-(Multipurpose Internet Mail Extensions) Part One: Mechanisms for
-Specifying and Describing the Format of Internet Message Bodies},
-section 5.2, ``Base64 Content-Transfer-Encoding'') and is used for
-MIME email and various other Internet-related applications; it is not
-the same as the output produced by the \program{uuencode} program.
-For example, the string \code{'www.python.org'} is encoded as the
-string \code{'d3d3LnB5dGhvbi5vcmc=\e n'}.
+This module provides data encoding and decoding as specified in
+\rfc{3548}. This standard defines the Base16, Base32, and Base64
+algorithms for encoding and decoding arbitrary binary strings into
+text strings that can be safely sent by email, used as parts of URLs,
+or included as part of an HTTP POST request. The encoding algorith is
+not the same as the \program{uuencode} program.
+There are two interfaces provided by this module. The modern
+interface supports encoding and decoding string objects using all
+three alphabets. The legacy interface provides for encoding and
+decoding to and from file-like objects as well as strings, but only
+using the Base64 standard alphabet.
+
+The modern interface provides:
+
+\begin{funcdesc}{b64encode}{s\optional{, altchars}}
+Encode a string use Base64.
+
+\var{s} is the string to encode. Optional \var{altchars} must be a
+string of at least length 2 (additional characters are ignored) which
+specifies an alternative alphabet for the \code{+} and \code{/}
+characters. This allows an application to e.g. generate URL or
+filesystem safe Base64 strings. The default is \code{None}, for which
+the standard Base64 alphabet is used.
+
+The encoded string is returned.
+\end{funcdesc}
+
+\begin{funcdesc}{b64decode}{s\optional{, altchars}}
+Decode a Base64 encoded string.
+
+\var{s} is the string to decode. Optional \var{altchars} must be a
+string of at least length 2 (additional characters are ignored) which
+specifies the alternative alphabet used instead of the \code{+} and
+\code{/} characters.
+
+The decoded string is returned. A \exception{TypeError} is raised if
+\var{s} were incorrectly padded or if there are non-alphabet
+characters present in the string.
+\end{funcdesc}
+
+\begin{funcdesc}{standard_b64encode}{s}
+Encode string \var{s} using the standard Base64 alphabet.
+\end{funcdesc}
+
+\begin{funcdesc}{standard_b64decode}{s}
+Decode string \var{s} using the standard Base64 alphabet.
+\end{funcdesc}
+
+\begin{funcdesc}{urlsafe_b64encode}{s}
+Encode string \var{s} using a URL-safe alphabet, which substitutes
+\code{-} instead of \code{+} and \code{_} instead of \code{/} in the
+standard Base64 alphabet.
+\end{funcdesc}
+
+\begin{funcdesc}{urlsafe_b64decode}{s}
+Decode string \var{s} using a URL-safe alphabet, which substitutes
+\code{-} instead of \code{+} and \code{_} instead of \code{/} in the
+standard Base64 alphabet.
+\end{funcdesc}
+
+\begin{funcdesc}{b32encode}{s}
+Encode a string using Base32. \var{s} is the string to encode. The
+encoded string is returned.
+\end{funcdesc}
+
+\begin{funcdesc}{b32decode}{s\optional{, casefold\optional{, map01}}}
+Decode a Base32 encoded string.
+
+\var{s} is the string to decode. Optional \var{casefold} is a flag
+specifying whether a lowercase alphabet is acceptable as input. For
+security purposes, the default is \code{False}.
+
+\rfc{3548} allows for optional mapping of the digit 0 (zero) to the
+letter O (oh), and for optional mapping of the digit 1 (one) to either
+the letter I (eye) or letter L (el). The optional argument
+\var{map01} when not \code{None}, specifies which letter the digit 1 should
+be mapped to (when map01 is not \var{None}, the digit 0 is always
+mapped to the letter O). For security purposes the default is
+\code{None}, so that 0 and 1 are not allowed in the input.
+
+The decoded string is returned. A \exception{TypeError} is raised if
+\var{s} were incorrectly padded or if there are non-alphabet characters
+present in the string.
+\end{funcdesc}
+
+\begin{funcdesc}{b16encode}{s}
+Encode a string using Base16.
+
+\var{s} is the string to encode. The encoded string is returned.
+\end{funcdesc}
+
+\begin{funcdesc}{b16decode}{s\optional{, casefold}}
+Decode a Base16 encoded string.
+
+\var{s} is the string to decode. Optional \var{casefold} is a flag
+specifying whether a lowercase alphabet is acceptable as input. For
+security purposes, the default is \code{False}.
+
+The decoded string is returned. A \exception{TypeError} is raised if
+\var{s} were incorrectly padded or if there are non-alphabet
+characters present in the string.
+\end{funcdesc}
+
+The legacy interface:
\begin{funcdesc}{decode}{input, output}
Decode the contents of the \var{input} file and write the resulting