Subject: Re: bug#50646: 28.0.50; narrow-to-defun sometimes narrows to wrong defun

From: Phil Sainty <[email-masked]>
Date: Mon, 20 Sep 2021 00:53:48 +1200

On 2021-09-20 00:17, Eli Zaretskii wrote:
> Then I suggest to mention insert-file-contents and other functions
> (if any) that do this explicitly.

Sounds sensible.  The pre-existing mention of `find-file-hook' means
(AFAIK) that we're already talking about more than just the two
'insert-file-contents*' functions.  The set of notable functions that
I know of are:

- find-file
- find-file-literally
- insert-file-contents
- insert-file-contents-literally
- insert-file
- insert-file-literally

The latter two are for interactive usage only (but analogous to the
insert-file-contents* functions, so maybe their docstrings should be
looked at too, for consistency).

For the `insert-file-contents-literally' docstring perhaps we just
need to add an explicit mention of `find-file'?

> Something like
>   This is contrary to other functions, like `insert-file-contents',
>   which may modify a buffer in several ways after ...

I now have this:

   "Like `insert-file-contents', but only reads in the file literally.
See `insert-file-contents' for an explanation of the parameters.

Insert after point the contents of file FILENAME as a sequence of
ASCII characters with no special encoding or conversion.

This is contrary to other functions, like `insert-file-contents' and
`find-file', which may modify a buffer in several ways after reading
into the buffer, due to Emacs features such as format decoding,
character code conversion, `find-file-hook', automatic uncompression,
etc.

Using `insert-file-contents-literally' ensures that none of these
modifications will take place."

I took "as a sequence of ASCII characters with no special encoding or
conversion" from (info "(emacs) Visiting") but I see that wording used
by `insert-file-literally' is "Insert contents of file FILENAME into
buffer after point with no conversion", and I figure the two should
probably use the same wording?  Is there a preference?

-Phil