Merge from origin/emacs-26

2168165 ; * doc/lispref/nonascii.texi (Explicit Encoding): Fix typo.
8f18d12 Improve documentation of decoding into a unibyte buffer
7681a57 Remove redundants "See" before @xref or @pxref (Bug#35793)
9bee762 ; * src/coding.c: Improve commentary.  (Bug#34765)
e61349c Fix customization type of recentf-max-saved-items

# Conflicts:
#	src/coding.c

1 files changed, 19 insertions, 9 deletions

diff --git a/src/coding.c b/src/coding.c
index 9cba6494a8d..5b9bfa17dd2 100644
--- a/src/coding.c
+++ b/src/coding.c
@@ -7803,15 +7803,22 @@ encode_coding (struct coding_system *coding)
   SAFE_FREE ();
 }
 
-
-/* Name (or base name) of work buffer for code conversion.  */
+/* Code-conversion operations use internal buffers.  There's a single
+   reusable buffer, which is created the first time it is needed, and
+   then never killed.  When this reusable buffer is being used, the
+   reused_workbuf_in_use flag is set.  If we need another conversion
+   buffer while the reusable one is in use (e.g., if code-conversion
+   is reentered when another code-conversion is in progress), we
+   create temporary buffers using the name of the reusable buffer as
+   the base name, see code_conversion_save below.  These temporary
+   buffers are killed when the code-conversion operations that use
+   them return, see code_conversion_restore below.  */
+
+/* A string that serves as name of the reusable work buffer, and as base
+   name of temporary work buffers used for code-conversion operations.  */
 Lisp_Object Vcode_conversion_workbuf_name;
 
-/* A working buffer used by the top level conversion.  Once it is
-   created, it is never destroyed.  It has the name
-   Vcode_conversion_workbuf_name.  The other working buffers are
-   destroyed after the use is finished, and their names are modified
-   versions of Vcode_conversion_workbuf_name.  */
+/* The reusable working buffer, created once and never killed.  */
 static Lisp_Object Vcode_conversion_reused_workbuf;
 
 /* True iff Vcode_conversion_reused_workbuf is already in use.  */
@@ -9402,7 +9409,8 @@ START and END are buffer positions.
 Optional 4th arguments DESTINATION specifies where the decoded text goes.
 If nil, the region between START and END is replaced by the decoded text.
 If buffer, the decoded text is inserted in that buffer after point (point
-does not move).
+does not move).  If that buffer is unibyte, it receives the individual
+bytes of the internal representation of the decoded text.
 In those cases, the length of the decoded text is returned.
 If DESTINATION is t, the decoded text is returned.
 
@@ -9560,7 +9568,9 @@ if the decoding operation is trivial.
 
 Optional fourth arg BUFFER non-nil means that the decoded text is
 inserted in that buffer after point (point does not move).  In this
-case, the return value is the length of the decoded text.
+case, the return value is the length of the decoded text.  If that
+buffer is unibyte, it receives the individual bytes of the internal
+representation of the decoded text.
 
 This function sets `last-coding-system-used' to the precise coding system
 used (which may be different from CODING-SYSTEM if CODING-SYSTEM is