add additional docs on base-85, refactor

Author: biniona

Doc/library/base64.rst

@@ -14,23 +14,17 @@
 --------------
 
 This module provides functions for encoding binary data to printable
-ASCII characters and decoding such encodings back to binary data.
-It provides encoding and decoding functions for the encodings specified in
-:rfc:`4648`, which defines the Base16, Base32, and Base64 algorithms,
-and for the de-facto standard Ascii85 and Base85 encodings.
-
-The :rfc:`4648` encodings are suitable for encoding binary data so that it can be
-safely sent by email, used as parts of URLs, or included as part of an HTTP
-POST request.  The encoding algorithm is not the same as the
-:program:`uuencode` program.
+ASCII characters and decoding such encodings back to binary data,
+such as :ref:`those specified in RFC 4648 <base_64_rfc_4648>` and
+:ref:`Base-85 encodings <base_64_base_85>`.
 
 There are two interfaces provided by this module.  The modern interface
 supports encoding :term:`bytes-like objects <bytes-like object>` to ASCII
 :class:`bytes`, and decoding :term:`bytes-like objects <bytes-like object>` or
 strings containing ASCII to :class:`bytes`.  Both base-64 alphabets
 defined in :rfc:`4648` (normal, and URL- and filesystem-safe) are supported.
 
-The legacy interface does not support decoding from strings, but it does
+The :ref:`legacy interface <base_64_legacy>` does not support decoding from strings, but it does
 provide functions for encoding and decoding to and from :term:`file objects
 <file object>`.  It only supports the Base64 standard alphabet, and it adds
 newlines every 76 characters as per :rfc:`2045`.  Note that if you are looking
@@ -46,7 +40,16 @@ package instead.
    Any :term:`bytes-like objects <bytes-like object>` are now accepted by all
    encoding and decoding functions in this module.  Ascii85/Base85 support added.
 
-The modern interface provides:
+
+.. _base_64_rfc_4648:
+
+RFC 4648 Encodings
+^^^^^^^^^^^^^^^^^^
+
+The :rfc:`4648` encodings are suitable for encoding binary data so that it can be
+safely sent by email, used as parts of URLs, or included as part of an HTTP
+POST request.  The encoding algorithm is not the same as the
+:program:`uuencode` program.
 
 .. function:: b64encode(s, altchars=None)
 
@@ -181,6 +184,28 @@ The modern interface provides:
    incorrectly padded or if there are non-alphabet characters present in the
    input.
 
+.. _base_64_base_85:
+
+Base 85 Encodings
+^^^^^^^^^^^^^^^^^
+
+Base-85 encoding is not formally specified. Base-85 encoding is a de facto standard
+originating from the ASCII Base-85 Strings encoding defined by the
+`PostScript Language <https://web.archive.org/web/20161222092741/https://www.adobe.com/products/postscript/pdfs/PLRM.pdf>`_. 
+
+The Ascii85 and Base85 functions in this module are two implementations of
+the de facto standard. Which function you should use depends on how the other
+software you use implements the Base-85 encoding.
+
+The two functions present in this module provide options
+to configure the encoding in the following ways:
+
+* Whether to include enclosing `<~` and `~>` markers
+* Whether to include newline characters
+* The set of ASCII characters used for encoding
+* Handling of null bytes
+
+Refer to the documentation of the individual functions for more information.
 
 .. function:: a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)
 
@@ -262,7 +287,10 @@ The modern interface provides:
    .. versionadded:: 3.13
 
 
-The legacy interface:
+.. _base_64_legacy:
+
+Legacy Interface
+^^^^^^^^^^^^^^^^
 
 .. function:: decode(input, output)