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.

1 files changed, 16 insertions, 5 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 2dc808e6945..e73f53b040d 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