[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-28 3cc77aa: Clarify (elisp) insert-file-contents with BEG or END n
From: |
Alan Mackenzie |
Subject: |
emacs-28 3cc77aa: Clarify (elisp) insert-file-contents with BEG or END not on character boundary |
Date: |
Sun, 3 Oct 2021 14:15:39 -0400 (EDT) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- emacs-28 3cc77aa: Clarify (elisp) insert-file-contents with BEG or END not on character boundary,
Alan Mackenzie <=