emacs-28 3ea9357d10: Update documentation of 'aset' and 'store-substring'

[Eli Zaretskii]

branch: emacs-28
commit 3ea9357d109e303fece9d49e1fdad8a2e42cc858
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Update documentation of 'aset' and 'store-substring'
    
    * doc/lispref/strings.texi (Modifying Strings): Adjust to
    implementation changes: it is possible for the modified string to
    have fewer or more bytes than the original.  Add recommendations
    regarding unibyte vs multibyte strings and characters.  (Bug#55801)
---
 doc/lispref/strings.texi | 32 +++++++++++++++++++-------------
 1 file changed, 19 insertions(+), 13 deletions(-)

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 742ab76244..c9612e598a 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -461,23 +461,29 @@ Remove the final newline, if any, from @var{string}.
 described in this section.  @xref{Mutability}.
 
   The most basic way to alter the contents of an existing string is with
-@code{aset} (@pxref{Array Functions}).  @code{(aset @var{string}
-@var{idx} @var{char})} stores @var{char} into @var{string} at index
-@var{idx}.  Each character occupies one or more bytes, and if @var{char}
-needs a different number of bytes from the character already present at
-that index, @code{aset} signals an error.
+@code{aset} (@pxref{Array Functions}).  @w{@code{(aset @var{string}
+@var{idx} @var{char})}} stores @var{char} into @var{string} at character
+index @var{idx}.  It will automatically convert a pure-@acronym{ASCII}
+@var{string} to a multibyte string (@pxref{Text Representations}) if
+needed, but we recommend to always make sure @var{string} is multibyte
+(e.g., by using @code{string-to-multibyte}, @pxref{Converting
+Representations}), if @var{char} is a non-@acronym{ASCII} character, not
+a raw byte.
 
   A more powerful function is @code{store-substring}:
 
 @defun store-substring string idx obj
-This function alters part of the contents of the string @var{string}, by
-storing @var{obj} starting at index @var{idx}.  The argument @var{obj}
-may be either a character or a (smaller) string.
-
-Since it is impossible to change the length of an existing string, it is
-an error if @var{obj} doesn't fit within @var{string}'s actual length,
-or if any new character requires a different number of bytes from the
-character currently present at that point in @var{string}.
+This function alters part of the contents of the specified @var{string},
+by storing @var{obj} starting at character index @var{idx}.  The
+argument @var{obj} may be either a character (in which case the function
+behaves exactly as @code{aset}) or a (smaller) string.  If @var{obj}
+is a multibyte string, we recommend to make sure @var{string} is also
+multibyte, even if it's pure-@acronym{ASCII}.
+
+Since it is impossible to change the number of characters in an
+existing string, it is en error if @var{obj} consists of more
+characters than would fit in @var{string} starting at character index
+@var{idx}.
 @end defun
 
   To clear out a string that contained a password, use