emacs-28 3cc77aa: Clarify (elisp) insert-file-contents with BEG or END not on character boundary

[Alan Mackenzie]

branch: emacs-28
commit 3cc77aa976f356f2496bd8471cf68b44d26c22a7
Author: Alan Mackenzie <acm@muc.de>
Commit: Alan Mackenzie <acm@muc.de>

    Clarify (elisp) insert-file-contents with BEG or END not on character 
boundary
    
    * doc/lispref/files.texi (Reading from files): When the argument BEG or END 
to
    insert-file-contents are at a byte position not at a character boundary,
    clarify that raw bytes get inserted, and how to handle this awkwardness in
    Lisp.  Also clarify that insert-file-contents-literally is intended to 
insert
    raw bytes into the buffer.  Fix the outdated example that states it inserts
    500 characters, when it actually inserts 500 bytes.
---
 doc/lispref/files.texi | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 2dc808e..e73f53b 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -563,7 +563,17 @@ In this case, @var{visit} must be @code{nil}.  For example,
 @end example
 
 @noindent
-inserts the first 500 characters of a file.
+inserts the characters coded by the first 500 bytes of a file.
+
+If @var{beg} or @var{end} fails to be at a character boundary, Emacs's
+character code conversion will insert one or more raw-text characters
+(@pxref{Coding System Basics}) into the buffer.  If you want to read
+part of a file this way, you are recommended to bind
+@code{coding-system-for-read} to a suitable value around the call to
+this function (@pxref{Specifying Coding Systems}), and to write Lisp
+code which will check for raw-text characters at the boundaries, read
+the rest of these characters from the file, and convert them back to
+valid characters.
 
 If the argument @var{replace} is non-@code{nil}, it means to replace the
 contents of the buffer (actually, just the accessible portion) with the
@@ -577,10 +587,11 @@ with @code{insert-file-contents}, as long as 
@var{replace} and
 @end defun
 
 @defun insert-file-contents-literally filename &optional visit beg end replace
-This function works like @code{insert-file-contents} except that it
-does not run @code{after-insert-file-functions}, and does not do
-format decoding, character code conversion, automatic uncompression,
-and so on.
+This function works like @code{insert-file-contents} except that each
+byte in the file is handled separately, being converted into a
+raw-text character if needed.  It does not run
+@code{after-insert-file-functions}, and does not do format decoding,
+character code conversion, automatic uncompression, and so on.
 @end defun
 
 If you want to pass a file name to another process so that another