bug#75345: 29.4; 'insert' doc string still mentions 'string-as-multibyte'

bug#75345: 29.4; 'insert' doc string still mentions 'string-as-multibyte'

[Ulrich Müller]

[-- Attachment #1: Type: text/plain, Size: 911 bytes --]

C-h f insert RET

   insert is a built-in function in ‘src/editfns.c’.

   [...]

   When operating on binary data, it may be necessary to preserve the
   original bytes of a unibyte string when inserting it into a multibyte
   buffer; to accomplish this, apply ‘string-as-multibyte’ to the string
   and insert the result.

C-h f string-as-multibyte RET

   string-as-multibyte is a built-in function in ‘src/fns.c’.

   This function is obsolete since 26.1; use `decode-coding-string'.

   [...]

This looks inconsistent, presumably 'insert' shouldn't mention
'string-as-multibyte'. Attached patch updates the doc string.

Also, the elisp manual still mentions functions string-as-unibyte and
string-as-multibyte in section "(elisp) Top > Non-ASCII Characters >
Selecting a Representation". Should these be removed from the manual,
or at least be labelled as obsolete?


[-- Attachment #2: 0001-Update-insert-doc-string.patch --]
[-- Type: text/plain, Size: 1054 bytes --]

From 858f94f942cb40481ac8bc83a36ae5555066c1bc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ulrich=20M=C3=BCller?= <ulm@gentoo.org>
Date: Sat, 4 Jan 2025 10:37:59 +0100
Subject: [PATCH] Update 'insert' doc string

* src/editfns.c (Finsert): Mention 'decode-coding-string' instead
of the obsolete 'string-as-multibyte' in doc string.
---
 src/editfns.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/editfns.c b/src/editfns.c
index 581bd03798e..8a5fb673fe7 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -1363,8 +1363,8 @@ DEFUN ("insert", Finsert, Sinsert, 0, MANY, 0,
 
 When operating on binary data, it may be necessary to preserve the
 original bytes of a unibyte string when inserting it into a multibyte
-buffer; to accomplish this, apply `string-as-multibyte' to the string
-and insert the result.
+buffer; to accomplish this, apply `decode-coding-string' with the
+`no-conversion' coding system to the string and insert the result.
 
 usage: (insert &rest ARGS)  */)
   (ptrdiff_t nargs, Lisp_Object *args)
-- 
2.47.1

bug#75345: 29.4; 'insert' doc string still mentions 'string-as-multibyte'

[Eli Zaretskii]

> From: Ulrich Müller <ulm@gentoo.org>
> Date: Sat, 04 Jan 2025 10:50:04 +0100
> 
> C-h f insert RET
> 
>    insert is a built-in function in ‘src/editfns.c’.
> 
>    [...]
> 
>    When operating on binary data, it may be necessary to preserve the
>    original bytes of a unibyte string when inserting it into a multibyte
>    buffer; to accomplish this, apply ‘string-as-multibyte’ to the string
>    and insert the result.
> 
> C-h f string-as-multibyte RET
> 
>    string-as-multibyte is a built-in function in ‘src/fns.c’.
> 
>    This function is obsolete since 26.1; use `decode-coding-string'.
> 
>    [...]
> 
> This looks inconsistent, presumably 'insert' shouldn't mention
> 'string-as-multibyte'. Attached patch updates the doc string.

Thanks, installed on emacs-30, and closing the bug.

> Also, the elisp manual still mentions functions string-as-unibyte and
> string-as-multibyte in section "(elisp) Top > Non-ASCII Characters >
> Selecting a Representation". Should these be removed from the manual,
> or at least be labelled as obsolete?

I'm not yet convinced these functions should be removed from the
manual.