[3.12] gh-121542: Document trailing newline behavior in `set_content()` (GH-121543...

gh-121542: Document trailing newline behavior in `set_content()` (GH-121543)
(cherry picked from commit fba475ae6f932d0aaee6832b4102b2d4c50df70f)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Yizheng Meng <dev@rapidcow.org>

diff --git a/Doc/library/email.contentmanager.rst b/Doc/library/email.contentmanager.rst
index a86e227429b06d3432762d444d7d5f3d1d14f933..b33fe82a6e4c9fc38c931c1a9fa671154621bfcf 100644 (file)
--- a/Doc/library/email.contentmanager.rst
+++ b/Doc/library/email.contentmanager.rst
@@ -157,7 +157,13 @@ Currently the email package provides only one concrete content manager,
        :exc:`ValueError`.
 
        * For ``str`` objects, if *cte* is not set use heuristics to
-         determine the most compact encoding.
+         determine the most compact encoding.  Prior to encoding,
+         :meth:`str.splitlines` is used to normalize all line boundaries,
+         ensuring that each line of the payload is terminated by the
+         current policy's :data:`~email.policy.Policy.linesep` property
+         (even if the original string did not end with one).
+       * For ``bytes`` objects, *cte* is taken to be base64 if not set,
+         and the aforementioned newline translation is not performed.
        * For :class:`~email.message.EmailMessage`, per :rfc:`2046`, raise
          an error if a *cte* of ``quoted-printable`` or ``base64`` is
          requested for *subtype* ``rfc822``, and for any *cte* other than