bug#50560: 28.0.50; 'insert-file-contents-literally' on multibyte buffers

["Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

Augusto Stoffel <arstoffel@gmail.com> writes:

> I thought 'insert-file-contents-literally' literally just inserted the
> file contents, as bytes, but I noticed that in the following code
>
>     (create-image
>      (with-temp-buffer
>        (set-buffer-multibyte nil)
>        (insert-file-contents-literally "picure.jpg")
>        (buffer-substring-no-properties (point-min) (point-max)))
>      nil t)
>
> the call to 'set-buffer-multibyte' is really essential.
>
> Is this intended?  If so, I think a note in the doctring is due.

It is intended, and the source of confusion may be the apparently
symmetric `find-file-literally`, which _does_ make the buffer unibyte
before filling the new buffer with the contents from a file (and
documents this behavior).

But if you think about it, it makes sense that
`insert-file-contents-literally` does not set the buffer as unibyte,
because it's intended for programmatic cases where you insert the
content inside a buffer that may already have other content, so making
the buffer unibyte unconditionally may cause unexpected results.

So yeah, perhaps we can add a small sentence that clarifies this
behavior.