mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-23 07:19:15 +00:00
Code Issues Releases Activity

Clarify (elisp) insert-file-contents with BEG or END not on character boundary

Browse Source 
* 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.
This commit is contained in:
Alan Mackenzie 2021-10-03 18:13:23 +00:00
parent 5deeb0947d
commit 3cc77aa976
1 changed files with 16 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
doc/lispref/files.texi
View File

@ -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