Subject: bug#77889: closed (Re: bug#77889: [PATCH] Clarify insert-char when called from Lisp)

From: [email-masked] (GNU bug Tracking System)
Date: Fri, 18 Apr 2025 11:13:02 +0000

Your bug report

#77889: [PATCH] Clarify insert-char when called from Lisp

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
77889: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=77889
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#77889: [PATCH] Clarify insert-char when called from Lisp
From: Eli Zaretskii <[email-masked]>
To: Lactose ‎ <[email-masked]>
Cc: [email-masked]
Date: Fri, 18 Apr 2025 14:11:58 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Lactose ‎ <[email-masked]>
> Date: Thu, 17 Apr 2025 18:39:30 -0700
> 
> The doc for `insert-char' is unclear what values are valid for CHARACTER
> when called from Lisp. This clarifies that only code points can be
> passed when called from Lisp instead of interactively.
> 
> > Interactively, prompt for CHARACTER using `read-char-by-name'.
> > You can specify CHARACTER in one of these ways:
> 
> This reads to me as two separate, unrelated statements. Somemone could
> interpret the latter as applying when called from Lisp, when in fact it's
> only true when called interactively.
> 
> > Interactively, prompt for CHARACTER using `read-char-by-name'.
> > When prompted, you can specify CHARACTER in one of these ways:
> 
> This is much better as it is now clear it only applies when
> called interactively.
> 
> In addition, I added details on how to call `insert-char' from Lisp.
> 
> > When called from Lisp, you can only pass CHARACTER as a code point.
> > See `char-from-name' for retrieving a code point from a Unicode character name.

Thanks, I used these ideas and suggestions to fix the doc string in a
slightly different way.  Done on the emacs-30 branch, and closing the
bug.

Subject: [PATCH] Clarify insert-char when called from Lisp
From: Lactose ‎ <[email-masked]>
To: [email-masked]
Date: Thu, 17 Apr 2025 18:39:30 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

The doc for `insert-char' is unclear what values are valid for CHARACTER
when called from Lisp. This clarifies that only code points can be
passed when called from Lisp instead of interactively.

> Interactively, prompt for CHARACTER using `read-char-by-name'.
> You can specify CHARACTER in one of these ways:

This reads to me as two separate, unrelated statements. Somemone could
interpret the latter as applying when called from Lisp, when in fact it's
only true when called interactively.

> Interactively, prompt for CHARACTER using `read-char-by-name'.
> When prompted, you can specify CHARACTER in one of these ways:

This is much better as it is now clear it only applies when
called interactively.

In addition, I added details on how to call `insert-char' from Lisp.

> When called from Lisp, you can only pass CHARACTER as a code point.
> See `char-from-name' for retrieving a code point from a Unicode character name.
diff --git a/src/editfns.c b/src/editfns.c
index a938d09..41927b5 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -1441,7 +1441,7 @@ DEFUN ("insert-char", Finsert_char, Sinsert_char, 1, 3,
               t))",
        doc: /* Insert COUNT copies of CHARACTER.
 Interactively, prompt for CHARACTER using `read-char-by-name'.
-You can specify CHARACTER in one of these ways:
+When promted, you can specify CHARACTER in one of these ways:
 
  - As its Unicode character name, e.g. \"LATIN SMALL LETTER A\".
    Completion is available; if you type a substring of the name
@@ -1455,6 +1455,9 @@ You can specify CHARACTER in one of these ways:
  - As a code point with a radix specified with #, e.g. #o21430
    (octal), #x2318 (hex), or #10r8984 (decimal).
 
+When called from Lisp, you can only pass CHARACTER as a code point.
+See `char-from-name' for retrieving a code point from a Unicode character name.
+
 If called interactively, COUNT is given by the prefix argument.  If
 omitted or nil, it defaults to 1.