emacs-27 0de6309: Clarify base64 requirements and say what {en, de}code_coding_region does

[Lars Ingebrigtsen]

branch: emacs-27
commit 0de63092c8ebae3877d97a18fa231c7ca2fbadc0
Author: Lars Ingebrigtsen <address@hidden>
Commit: Lars Ingebrigtsen <address@hidden>

    Clarify base64 requirements and say what {en,de}code_coding_region does
    
    * src/coding.c (Fencode_coding_region): Clarify what this does.
    (Fdecode_coding_region): Ditto.
    
    * src/fns.c (Fbase64_decode_region): Clarify that this function
    returns bytes, not text (bug#38587).
    (Fbase64_encode_region): Clarify that this function takes bytes,
    not text.
---
 src/coding.c | 14 ++++++++++++++
 src/fns.c    | 16 ++++++++++++++--
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/src/coding.c b/src/coding.c
index d996490..35d6be4 100644
--- a/src/coding.c
+++ b/src/coding.c
@@ -9415,6 +9415,13 @@ code_convert_region (Lisp_Object start, Lisp_Object end,
 DEFUN ("decode-coding-region", Fdecode_coding_region, Sdecode_coding_region,
        3, 4, "r\nzCoding system: ",
        doc: /* Decode the current region from the specified coding system.
+
+What's meant by \"decoding\" is transforming bytes into text
+(characters).  If, for instance, you have a region that contains data
+that represents the two bytes #xc2 #xa9, after calling this function
+with the utf-8 coding system, the region will contain the single
+character ?\\N{COPYRIGHT SIGN}.
+
 When called from a program, takes four arguments:
        START, END, CODING-SYSTEM, and DESTINATION.
 START and END are buffer positions.
@@ -9438,6 +9445,13 @@ not fully specified.)  */)
 DEFUN ("encode-coding-region", Fencode_coding_region, Sencode_coding_region,
        3, 4, "r\nzCoding system: ",
        doc: /* Encode the current region by specified coding system.
+
+What's meant by \"encoding\" is transforming textual data (characters)
+into bytes.  If, for instance, you have a region that contains the
+single character ?\\N{COPYRIGHT SIGN}, after calling this function with
+the utf-8 coding system, the data in the region will represent the two
+bytes #xc2 #xa9.
+
 When called from a program, takes four arguments:
         START, END, CODING-SYSTEM and DESTINATION.
 START and END are buffer positions.
diff --git a/src/fns.c b/src/fns.c
index 3ae3192..5e62d0e 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -3297,7 +3297,13 @@ static Lisp_Object base64_encode_string_1 (Lisp_Object, 
bool,
 DEFUN ("base64-encode-region", Fbase64_encode_region, Sbase64_encode_region,
        2, 3, "r",
        doc: /* Base64-encode the region between BEG and END.
-Return the length of the encoded text.
+The data in the region is assumed to represent bytes, not text.  If
+you want to base64-encode text, the text has to be converted into data
+first by using `encode-coding-region' with the appropriate coding
+system first.
+
+Return the length of the encoded data.
+
 Optional third argument NO-LINE-BREAK means do not break long lines
 into shorter lines.  */)
   (Lisp_Object beg, Lisp_Object end, Lisp_Object no_line_break)
@@ -3544,7 +3550,13 @@ base64_encode_1 (const char *from, char *to, ptrdiff_t 
length,
 DEFUN ("base64-decode-region", Fbase64_decode_region, Sbase64_decode_region,
        2, 3, "r",
        doc: /* Base64-decode the region between BEG and END.
-Return the length of the decoded text.
+Return the length of the decoded data.
+
+Note that after calling this function, the data in the region will
+represent bytes, not text.  If you want to end up with text, you have
+to call `decode-coding-region' afterwards with an appropriate coding
+system.
+
 If the region can't be decoded, signal an error and don't modify the buffer.
 Optional third argument BASE64URL determines whether to use the URL variant
 of the base 64 encoding, as defined in RFC 4648.  */)