bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Stefan Kangas]

It seems like `format-prompt' and `minibuffer-default-prompt-format'
does not support curved quotes.  Should they?

To reproduce, evaluate this forms in emacs -Q:

    (format-prompt "foo `bar'" nil)

    => "foo `bar': "

And:

    (let ((minibuffer-default-prompt-format " (default `%s')"))
      (format-prompt "foo `bar'" t))

    => "foo `bar' (default `t'): "

My expectation is that I get this, where fancy quotes are supported:

    "foo ‘bar’ (default ‘t’): "

Now, this is easy to fix, but we need to decide if it's okay that
`format-prompt' just runs `substitute-command-keys' on these by default.
I believe that fix should be fine, but maybe I'm missing something.

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> It seems like `format-prompt' and `minibuffer-default-prompt-format'
> does not support curved quotes.  Should they?

I think so...

> Now, this is easy to fix, but we need to decide if it's okay that
> `format-prompt' just runs `substitute-command-keys' on these by default.
> I believe that fix should be fine, but maybe I'm missing something.

Perhaps refactor out the curved quote stuff from
`substitute-command-keys' into its own function and then use that?
(Note: I haven't actually looked at that function.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Perhaps refactor out the curved quote stuff from
> `substitute-command-keys' into its own function and then use that?
> (Note: I haven't actually looked at that function.)

I've been thinking about doing that for a while and I keep going back
and forth.

First, it's a bit tricky to factor this stuff out from
`substitute-command-keys'.  I have a rewrite of that function in the
works (that I should probably finish up at some point), but even then it
is not exactly obvious that this would be super easy and obvious to
factor out in a good way.

So if we do this, I think we should just bite the bullet and duplicate
this functionality in a new function.  It should just be a simple
search+replace, so the duplication shouldn't be too bad.

In some cases, we don't have command substitutions, so it would be nicer
to be able to say `use-fancy-quotes' if that's what we want.  On the
other hand, besides the name there is also no immediate drawback to run
`substitute-command-keys'.

It is kind of nice to know that if we ever expand to have input with
command substitution, it will just work.  For example, what if a prompt
wants to say something like

    (format-prompt "You pressed \\[foo-bar], now input ...")

On the other hand, there are some places where we obviously will never
want to run a "full" `substitute-command-keys', for example I think we
have some places where we awkwardly say (substitute-command-keys "'").

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> On the other hand, there are some places where we obviously will never
> want to run a "full" `substitute-command-keys', for example I think we
> have some places where we awkwardly say (substitute-command-keys "'").

Yeah, having a separate function for this would be good, because those
bits are pretty confusing.  But as you say, in this `format-prompt'
case, using `substitute-command-keys' is probably the right thing, since
we could be actually using key defs in the prompt.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Stefan Kangas]

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

tags 51040 + patch
thanks

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Yeah, having a separate function for this would be good, because those
> bits are pretty confusing.  But as you say, in this `format-prompt'
> case, using `substitute-command-keys' is probably the right thing, since
> we could be actually using key defs in the prompt.

OK, so here's what I propose.  The first patch adds a function
`substitute-quotes' and could go to master, the second one changes
`format-prompt' to use `substitute-command-keys' and could go to
emacs-28.

[-- Attachment #2: 0001-New-function-substitute-quotes.patch --]
[-- Type: text/x-diff, Size: 12135 bytes --]

From e455d509a27b2705f006bc2111228a9a8b8df0b4 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Mon, 11 Oct 2021 22:46:31 +0200
Subject: [PATCH 1/2] New function substitute-quotes

* lisp/help.el (substitute-quotes): New function.  (Bug#51040)
* lisp/cedet/srecode/srt-mode.el (srecode-macro-help):
* lisp/cus-theme.el (describe-theme-1):
* lisp/emacs-lisp/cl-extra.el (cl--describe-class):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-constructor):
* lisp/emacs-lisp/package.el (describe-package-1):
* lisp/help-fns.el (help-fns--parent-mode, help-fns--var-risky)
(help-fns--var-file-local, help-fns--var-bufferlocal)
(describe-face):
* lisp/help.el (substitute-command-keys):
* lisp/progmodes/octave.el (octave-help): Use the new function
instead of 'substitute-command-keys'.
* test/lisp/help-tests.el (help-tests-substitute-quotes): New test.
---
 lisp/cedet/srecode/srt-mode.el |  4 ++--
 lisp/cus-theme.el              |  2 +-
 lisp/emacs-lisp/cl-extra.el    | 10 +++++-----
 lisp/emacs-lisp/eieio-opt.el   |  2 +-
 lisp/emacs-lisp/package.el     |  2 +-
 lisp/help-fns.el               | 18 +++++++++---------
 lisp/help.el                   | 17 +++++++++++++++--
 lisp/progmodes/octave.el       |  4 ++--
 test/lisp/help-tests.el        | 20 ++++++++++++++++++++
 9 files changed, 56 insertions(+), 23 deletions(-)

diff --git a/lisp/cedet/srecode/srt-mode.el b/lisp/cedet/srecode/srt-mode.el
index 7157915849..0fc2a12822 100644
--- a/lisp/cedet/srecode/srt-mode.el
+++ b/lisp/cedet/srecode/srt-mode.el
@@ -260,9 +260,9 @@ srecode-macro-help
 	    (when (class-abstract-p C)
 	      (throw 'skip nil))
 
-	    (princ (substitute-command-keys "`"))
+            (princ (substitute-quotes "`"))
 	    (princ name)
-	    (princ (substitute-command-keys "'"))
+            (princ (substitute-quotes "'"))
 	    (when (slot-exists-p C 'key)
 	      (when key
 		(princ " - Character Key: ")
diff --git a/lisp/cus-theme.el b/lisp/cus-theme.el
index f618e3341c..fc278ba164 100644
--- a/lisp/cus-theme.el
+++ b/lisp/cus-theme.el
@@ -496,7 +496,7 @@ describe-theme-1
       (princ (substitute-command-keys " in `"))
       (help-insert-xref-button (file-name-nondirectory fn)
 			       'help-theme-def fn)
-      (princ (substitute-command-keys "'")))
+      (princ (substitute-quotes "'")))
     (princ ".\n")
     (if (custom-theme-p theme)
 	(progn
diff --git a/lisp/emacs-lisp/cl-extra.el b/lisp/emacs-lisp/cl-extra.el
index 499d26b737..7a0ecbdf81 100644
--- a/lisp/emacs-lisp/cl-extra.el
+++ b/lisp/emacs-lisp/cl-extra.el
@@ -769,7 +769,7 @@ cl--describe-class
       (help-insert-xref-button
        (help-fns-short-filename location)
        'cl-type-definition type location 'define-type)
-      (insert (substitute-command-keys "'")))
+      (insert (substitute-quotes "'")))
     (insert ".\n")
 
     ;; Parents.
@@ -779,7 +779,7 @@ cl--describe-class
         (insert " Inherits from ")
         (while (setq cur (pop pl))
           (setq cur (cl--class-name cur))
-          (insert (substitute-command-keys "`"))
+          (insert (substitute-quotes "`"))
           (help-insert-xref-button (symbol-name cur)
                                    'cl-help-type cur)
           (insert (substitute-command-keys (if pl "', " "'"))))
@@ -793,7 +793,7 @@ cl--describe-class
       (when ch
         (insert " Children ")
         (while (setq cur (pop ch))
-          (insert (substitute-command-keys "`"))
+          (insert (substitute-quotes "`"))
           (help-insert-xref-button (symbol-name cur)
                                    'cl-help-type cur)
           (insert (substitute-command-keys (if ch "', " "'"))))
@@ -812,10 +812,10 @@ cl--describe-class
       (when generics
         (insert (propertize "Specialized Methods:\n\n" 'face 'bold))
         (dolist (generic generics)
-          (insert (substitute-command-keys "`"))
+          (insert (substitute-quotes "`"))
           (help-insert-xref-button (symbol-name generic)
                                    'help-function generic)
-          (insert (substitute-command-keys "'"))
+          (insert (substitute-quotes "'"))
           (pcase-dolist (`(,qualifiers ,args ,doc)
                          (cl--generic-method-documentation generic type))
             (insert (format " %s%S\n" qualifiers args)
diff --git a/lisp/emacs-lisp/eieio-opt.el b/lisp/emacs-lisp/eieio-opt.el
index 9c842f4682..17931f29f3 100644
--- a/lisp/emacs-lisp/eieio-opt.el
+++ b/lisp/emacs-lisp/eieio-opt.el
@@ -152,7 +152,7 @@ eieio-help-constructor
         (help-insert-xref-button
 	 (help-fns-short-filename location)
 	 'cl-type-definition ctr location 'define-type)
-	(insert (substitute-command-keys "'")))
+        (insert (substitute-quotes "'")))
       (insert ".\nCreates an object of class " (symbol-name ctr) ".")
       (goto-char (point-max))
       (if (autoloadp def)
diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el
index 5445fa970f..bb0ba20a4f 100644
--- a/lisp/emacs-lisp/package.el
+++ b/lisp/emacs-lisp/package.el
@@ -2546,7 +2546,7 @@ describe-package-1
                         "',\n             shadowing a ")
                        (propertize "built-in package"
                                    'font-lock-face 'package-status-built-in))
-             (insert (substitute-command-keys "'")))
+             (insert (substitute-quotes "'")))
            (if signed
                (insert ".")
              (insert " (unsigned)."))
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 6be5cd4a50..8e4f4d7ac8 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -614,13 +614,13 @@ help-fns--parent-mode
                           (get function
                                'derived-mode-parent))))
     (when parent-mode
-      (insert (substitute-command-keys "  Parent mode: `"))
+      (insert (substitute-quotes "  Parent mode: `"))
       (let ((beg (point)))
         (insert (format "%s" parent-mode))
         (make-text-button beg (point)
                           'type 'help-function
                           'help-args (list parent-mode)))
-      (insert (substitute-command-keys "'.\n")))))
+      (insert (substitute-quotes "'.\n")))))
 
 (defun help-fns--obsolete (function)
   ;; Ignore lambda constructs, keyboard macros, etc.
@@ -1307,7 +1307,7 @@ help-fns--var-risky
     (princ "  This variable may be risky if used as a \
 file-local variable.\n")
     (when (assq variable safe-local-variable-values)
-      (princ (substitute-command-keys
+      (princ (substitute-quotes
               "  However, you have added it to \
 `safe-local-variable-values'.\n")))))
 
@@ -1357,8 +1357,8 @@ help-fns--var-file-local
 	          (insert-text-button
 	           file 'type 'help-dir-local-var-def
                    'help-args (list variable file)))
-	        (princ (substitute-command-keys "'.\n"))))
-          (princ (substitute-command-keys
+                (princ (substitute-quotes "'.\n"))))
+          (princ (substitute-quotes
 	          "  This variable's value is file-local.\n")))))))
 
 (add-hook 'help-fns-describe-variable-functions #'help-fns--var-watchpoints)
@@ -1436,10 +1436,10 @@ help-fns--var-bufferlocal
      ((not permanent-local))
      ((bufferp locus)
       (princ
-       (substitute-command-keys
+       (substitute-quotes
         "  This variable's buffer-local value is permanent.\n")))
      (t
-      (princ (substitute-command-keys
+      (princ (substitute-quotes
 	      "  This variable's value is permanent \
 if it is given a local binding.\n"))))))
 
@@ -1515,9 +1515,9 @@ describe-face
                   (setq help-mode--current-data (list :symbol f))
                 (setq help-mode--current-data (list :symbol f
                                                     :file file-name))
-		(princ (substitute-command-keys "Defined in `"))
+                (princ (substitute-quotes "Defined in `"))
 		(princ (help-fns-short-filename file-name))
-		(princ (substitute-command-keys "'"))
+                (princ (substitute-quotes "'"))
 		;; Make a hyperlink to the library.
 		(save-excursion
 		  (re-search-backward
diff --git a/lisp/help.el b/lisp/help.el
index eaca33795a..9da4f03786 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1172,9 +1172,9 @@ substitute-command-keys
                   (cond
                    ((null this-keymap)
                     (insert "\nUses keymap "
-                            (substitute-command-keys "`")
+                            (substitute-quotes "`")
                             (symbol-name name)
-                            (substitute-command-keys "'")
+                            (substitute-quotes "'")
                             ", which is not currently defined.\n")
                     (unless generate-summary
                       (setq keymap nil)))
@@ -1201,6 +1201,19 @@ substitute-command-keys
              (t (forward-char 1)))))
         (buffer-string)))))
 
+(defun substitute-quotes (string)
+  "Substitute quote characters for display.
+Each grave accent \\=` is replaced by left quote, and each
+apostrophe \\=' is replaced by right quote.  Left and right quote
+characters are specified by ‘text-quoting-style’."
+  (cond ((eq (text-quoting-style) 'curve)
+         (replace-regexp-in-string
+          "`" "‘"
+          (replace-regexp-in-string "'" "’" string)))
+        ((eq (text-quoting-style) 'straight)
+         (replace-regexp-in-string "`" "'" string))
+        (t string))))
+
 (defvar help--keymaps-seen nil)
 (defun describe-map-tree (startmap partial shadow prefix title no-menu
                                    transl always-title mention-shadow)
diff --git a/lisp/progmodes/octave.el b/lisp/progmodes/octave.el
index 6bf070cf9e..c7b1b4f61d 100644
--- a/lisp/progmodes/octave.el
+++ b/lisp/progmodes/octave.el
@@ -1721,12 +1721,12 @@ octave-help
                  (dir (file-name-directory
                        (directory-file-name (file-name-directory file)))))
             (replace-match "" nil nil nil 1)
-            (insert (substitute-command-keys "`"))
+            (insert (substitute-quotes "`"))
             ;; Include the parent directory which may be regarded as
             ;; the category for the FN.
             (help-insert-xref-button (file-relative-name file dir)
                                      'octave-help-file fn)
-            (insert (substitute-command-keys "'"))))
+            (insert (substitute-quotes "'"))))
         ;; Make 'See also' clickable.
         (with-syntax-table octave-mode-syntax-table
           (when (re-search-forward "^\\s-*See also:" nil t)
diff --git a/test/lisp/help-tests.el b/test/lisp/help-tests.el
index 871417da3d..13403050b9 100644
--- a/test/lisp/help-tests.el
+++ b/test/lisp/help-tests.el
@@ -167,6 +167,26 @@ help-tests-substitute-command-keys/quotes
     (test "'" "'")
     (test "\\`" "\\`"))))
 
+(ert-deftest help-tests-substitute-quotes ()
+ (let ((text-quoting-style 'curve))
+   (should (string= (substitute-quotes "quotes ‘like this’") "quotes ‘like this’"))
+   (should (string= (substitute-quotes "`x'") "‘x’"))
+   (should (string= (substitute-quotes "`") "‘"))
+   (should (string= (substitute-quotes "'") "’"))
+   (should (string= (substitute-quotes "\\`") "\\‘")))
+ (let ((text-quoting-style 'straight))
+   (should (string= (substitute-quotes "quotes `like this'") "quotes 'like this'"))
+   (should (string= (substitute-quotes "`x'") "'x'"))
+   (should (string= (substitute-quotes "`") "'"))
+   (should (string= (substitute-quotes "'") "'"))
+   (should (string= (substitute-quotes "\\`") "\\'")))
+ (let ((text-quoting-style 'grave))
+   (should (string= (substitute-quotes "quotes `like this'") "quotes `like this'"))
+   (should (string= (substitute-quotes "`x'") "`x'"))
+   (should (string= (substitute-quotes "`") "`"))
+   (should (string= (substitute-quotes "'") "'"))
+   (should (string= (substitute-quotes "\\`") "\\`"))))
+
 (ert-deftest help-tests-substitute-command-keys/literals ()
   (with-substitute-command-keys-test
    (test "foo \\=\\[goto-char]" "foo \\[goto-char]")
-- 
2.30.2


[-- Attachment #3: 0002-Use-substitute-command-keys-in-format-prompt.patch --]
[-- Type: text/x-diff, Size: 1457 bytes --]

From 7c229589833db0ef21128efd0672281279ba1823 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Mon, 11 Oct 2021 22:50:38 +0200
Subject: [PATCH 2/2] Use substitute-command-keys in format-prompt

* lisp/minibuffer.el (format-prompt): Use substitute-command-keys.
(Bug#51040)
---
 lisp/minibuffer.el | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 1e1a6f852e..694800de7c 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -4229,18 +4229,19 @@ format-prompt
 
 If DEFAULT is nil or an empty string, no \"default value\" string
 is included in the return value."
-  (concat
-   (if (null format-args)
-       prompt
-     (apply #'format prompt format-args))
-   (and default
-        (or (not (stringp default))
-            (length> default 0))
-        (format minibuffer-default-prompt-format
-                (if (consp default)
-                    (car default)
-                  default)))
-   ": "))
+  (substitute-command-keys
+   (concat
+    (if (null format-args)
+        prompt
+      (apply #'format prompt format-args))
+    (and default
+         (or (not (stringp default))
+             (length> default 0))
+         (format minibuffer-default-prompt-format
+                 (if (consp default)
+                     (car default)
+                   default)))
+    ": ")))
 
 (provide 'minibuffer)
 
-- 
2.30.2

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> OK, so here's what I propose.  The first patch adds a function
> `substitute-quotes' and could go to master, the second one changes
> `format-prompt' to use `substitute-command-keys' and could go to
> emacs-28.

The first one looks OK to me, but I'm unsure about the second one.  I
mean, it's a small change, but it's hard to say whether this will lead
to obscure regressions in some people's work flows.  So I'm leaning
towards not changing this in emacs-28 at this point.

Eli, do you have an opinion?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> The first one looks OK to me, but I'm unsure about the second one.  I
> mean, it's a small change, but it's hard to say whether this will lead
> to obscure regressions in some people's work flows.  So I'm leaning
> towards not changing this in emacs-28 at this point.

I'm fine with putting it on master as well, of course.
The issue it fixes it very minor in any case.

> Eli, do you have an opinion?

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: 51040@debbugs.gnu.org, Eli Zaretskii <eliz@gnu.org>
> Date: Tue, 12 Oct 2021 14:03:28 +0200
> 
> Stefan Kangas <stefan@marxist.se> writes:
> 
> > OK, so here's what I propose.  The first patch adds a function
> > `substitute-quotes' and could go to master, the second one changes
> > `format-prompt' to use `substitute-command-keys' and could go to
> > emacs-28.
> 
> The first one looks OK to me, but I'm unsure about the second one.  I
> mean, it's a small change, but it's hard to say whether this will lead
> to obscure regressions in some people's work flows.  So I'm leaning
> towards not changing this in emacs-28 at this point.
> 
> Eli, do you have an opinion?

I agree, let's not install on emacs-28 anything that doesn't have to
be there.

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 11 Oct 2021 13:58:58 -0700
> Cc: 51040@debbugs.gnu.org
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
> > Yeah, having a separate function for this would be good, because those
> > bits are pretty confusing.  But as you say, in this `format-prompt'
> > case, using `substitute-command-keys' is probably the right thing, since
> > we could be actually using key defs in the prompt.
> 
> OK, so here's what I propose.  The first patch adds a function
> `substitute-quotes' and could go to master, the second one changes
> `format-prompt' to use `substitute-command-keys' and could go to
> emacs-28.
> 
> From e455d509a27b2705f006bc2111228a9a8b8df0b4 Mon Sep 17 00:00:00 2001
> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 11 Oct 2021 22:46:31 +0200
> Subject: [PATCH 1/2] New function substitute-quotes
> 
> * lisp/help.el (substitute-quotes): New function.  (Bug#51040)
> * lisp/cedet/srecode/srt-mode.el (srecode-macro-help):
> * lisp/cus-theme.el (describe-theme-1):
> * lisp/emacs-lisp/cl-extra.el (cl--describe-class):
> * lisp/emacs-lisp/eieio-opt.el (eieio-help-constructor):
> * lisp/emacs-lisp/package.el (describe-package-1):
> * lisp/help-fns.el (help-fns--parent-mode, help-fns--var-risky)
> (help-fns--var-file-local, help-fns--var-bufferlocal)
> (describe-face):
> * lisp/help.el (substitute-command-keys):
> * lisp/progmodes/octave.el (octave-help): Use the new function
> instead of 'substitute-command-keys'.
> * test/lisp/help-tests.el (help-tests-substitute-quotes): New test.

Shouldn't substitute-quotes be documented?

> +(defun substitute-quotes (string)
> +  "Substitute quote characters for display.
> +Each grave accent \\=` is replaced by left quote, and each
> +apostrophe \\=' is replaced by right quote.  Left and right quote
> +characters are specified by ‘text-quoting-style’."
> +  (cond ((eq (text-quoting-style) 'curve)
> +         (replace-regexp-in-string
> +          "`" "‘"
> +          (replace-regexp-in-string "'" "’" string)))
> +        ((eq (text-quoting-style) 'straight)
> +         (replace-regexp-in-string "`" "'" string))

Aren't we supposed to use string-replace nowadays in these
situations?

Also, this seems to ignore the nil value of text-quoting-style?

And finally, I think the doc string of text-quoting-style should be
amended, since it says that variable's effect is limited to help text
and format-message, but now it seems its effect will spread much
wider.
> Subject: [PATCH 2/2] Use substitute-command-keys in format-prompt
> 
> * lisp/minibuffer.el (format-prompt): Use substitute-command-keys.
> (Bug#51040)

I'm not sure I understand the rationale for this.  This will change
the appearance of formatted prompts, won't it?  So people will now
have to use \\=' to get a literal apostrophe?  is that really what we
want, and if so, why?

Thanks.

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Stefan Kangas]

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

Eli Zaretskii <eliz@gnu.org> writes:

> Shouldn't substitute-quotes be documented?

Yes, I also didn't yet add NEWS yet.  Fixed in the attached.

> Aren't we supposed to use string-replace nowadays in these
> situations?

Good catch, fixed.

> Also, this seems to ignore the nil value of text-quoting-style?

The reason is that `text-quoting-style' (the function) handles this
already, and will never return nil.  (This is arguably a bit confusing,
but it is what it is.)

> And finally, I think the doc string of text-quoting-style should be
> amended, since it says that variable's effect is limited to help text
> and format-message, but now it seems its effect will spread much
> wider.

Hmm, in what sense will it spread wider?  I think this will still be
limited to help and messages?  IOW, I'm happy to add something, but I'm
not sure what that would be.

>> * lisp/minibuffer.el (format-prompt): Use substitute-command-keys.
>> (Bug#51040)
>
> I'm not sure I understand the rationale for this.  This will change
> the appearance of formatted prompts, won't it?  So people will now
> have to use \\=' to get a literal apostrophe?  is that really what we
> want, and if so, why?

The reason for the change is that we want curved quotes for all the
usual reasons, and it might be useful to allow command substitutions as
well, in case a prompt wants to show a keybinding.

format-prompt is new in Emacs 28.1, so I guess we're deciding its
semantics now.  That may or may not be strong enough reason to push this
change to emacs-28 instead of master.

New patch attached, thanks for reviewing.

[-- Attachment #2: 0001-New-function-substitute-quotes.patch --]
[-- Type: text/x-diff, Size: 14492 bytes --]

From 7686ce00e2a08054ee2a761e8b45f0e914bcee31 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Mon, 11 Oct 2021 22:46:31 +0200
Subject: [PATCH 1/2] New function substitute-quotes

* lisp/help.el (substitute-quotes): New function.  (Bug#51040)
* doc/lispref/help.texi (Keys in Documentation): Document
substitute-quotes.
* test/lisp/help-tests.el (help-tests-substitute-quotes): New test.

* lisp/cedet/srecode/srt-mode.el (srecode-macro-help):
* lisp/cus-theme.el (describe-theme-1):
* lisp/emacs-lisp/cl-extra.el (cl--describe-class):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-constructor):
* lisp/emacs-lisp/package.el (describe-package-1):
* lisp/help-fns.el (help-fns--parent-mode, help-fns--var-risky)
(help-fns--var-file-local, help-fns--var-bufferlocal)
(describe-face):
* lisp/help.el (substitute-command-keys):
* lisp/progmodes/octave.el (octave-help): Use the new function
instead of 'substitute-command-keys'.
---
 doc/lispref/help.texi          |  4 +++
 etc/NEWS                       |  5 ++++
 lisp/cedet/srecode/srt-mode.el |  4 +--
 lisp/cus-theme.el              |  2 +-
 lisp/emacs-lisp/cl-extra.el    | 10 +++----
 lisp/emacs-lisp/eieio-opt.el   |  2 +-
 lisp/emacs-lisp/package.el     |  2 +-
 lisp/help-fns.el               | 18 ++++++------
 lisp/help.el                   | 16 +++++++++--
 lisp/progmodes/octave.el       |  4 +--
 test/lisp/help-tests.el        | 52 +++++++++++++++++++++++-----------
 11 files changed, 80 insertions(+), 39 deletions(-)

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index a788852de7..e6093d92b2 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -378,6 +378,10 @@ Keys in Documentation
 This permits display of documentation that refers accurately to the
 user's own customized key bindings.
 
+@defun substitute-quotes
+This function works like @code{substitute-command-keys}, but only
+replaces quote characters.
+
 @cindex advertised binding
 If a command has multiple bindings, this function normally uses the
 first one it finds.  You can specify one particular key binding by
diff --git a/etc/NEWS b/etc/NEWS
index 9daf958b07..cf643c0f87 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -144,6 +144,11 @@ with recent versions of Firefox.
 \f
 * Lisp Changes in Emacs 29.1
 
++++
+** New function 'substitute-quotes'.
+This function works like 'substitute-command-keys' but only
+substitutes quote characters.
+
 +++
 ** :keys in 'menu-item' can now be a function.
 If so, it is called whenever the menu is computed, and can be used to
diff --git a/lisp/cedet/srecode/srt-mode.el b/lisp/cedet/srecode/srt-mode.el
index 7157915849..0fc2a12822 100644
--- a/lisp/cedet/srecode/srt-mode.el
+++ b/lisp/cedet/srecode/srt-mode.el
@@ -260,9 +260,9 @@ srecode-macro-help
 	    (when (class-abstract-p C)
 	      (throw 'skip nil))
 
-	    (princ (substitute-command-keys "`"))
+            (princ (substitute-quotes "`"))
 	    (princ name)
-	    (princ (substitute-command-keys "'"))
+            (princ (substitute-quotes "'"))
 	    (when (slot-exists-p C 'key)
 	      (when key
 		(princ " - Character Key: ")
diff --git a/lisp/cus-theme.el b/lisp/cus-theme.el
index f618e3341c..fc278ba164 100644
--- a/lisp/cus-theme.el
+++ b/lisp/cus-theme.el
@@ -496,7 +496,7 @@ describe-theme-1
       (princ (substitute-command-keys " in `"))
       (help-insert-xref-button (file-name-nondirectory fn)
 			       'help-theme-def fn)
-      (princ (substitute-command-keys "'")))
+      (princ (substitute-quotes "'")))
     (princ ".\n")
     (if (custom-theme-p theme)
 	(progn
diff --git a/lisp/emacs-lisp/cl-extra.el b/lisp/emacs-lisp/cl-extra.el
index 499d26b737..7a0ecbdf81 100644
--- a/lisp/emacs-lisp/cl-extra.el
+++ b/lisp/emacs-lisp/cl-extra.el
@@ -769,7 +769,7 @@ cl--describe-class
       (help-insert-xref-button
        (help-fns-short-filename location)
        'cl-type-definition type location 'define-type)
-      (insert (substitute-command-keys "'")))
+      (insert (substitute-quotes "'")))
     (insert ".\n")
 
     ;; Parents.
@@ -779,7 +779,7 @@ cl--describe-class
         (insert " Inherits from ")
         (while (setq cur (pop pl))
           (setq cur (cl--class-name cur))
-          (insert (substitute-command-keys "`"))
+          (insert (substitute-quotes "`"))
           (help-insert-xref-button (symbol-name cur)
                                    'cl-help-type cur)
           (insert (substitute-command-keys (if pl "', " "'"))))
@@ -793,7 +793,7 @@ cl--describe-class
       (when ch
         (insert " Children ")
         (while (setq cur (pop ch))
-          (insert (substitute-command-keys "`"))
+          (insert (substitute-quotes "`"))
           (help-insert-xref-button (symbol-name cur)
                                    'cl-help-type cur)
           (insert (substitute-command-keys (if ch "', " "'"))))
@@ -812,10 +812,10 @@ cl--describe-class
       (when generics
         (insert (propertize "Specialized Methods:\n\n" 'face 'bold))
         (dolist (generic generics)
-          (insert (substitute-command-keys "`"))
+          (insert (substitute-quotes "`"))
           (help-insert-xref-button (symbol-name generic)
                                    'help-function generic)
-          (insert (substitute-command-keys "'"))
+          (insert (substitute-quotes "'"))
           (pcase-dolist (`(,qualifiers ,args ,doc)
                          (cl--generic-method-documentation generic type))
             (insert (format " %s%S\n" qualifiers args)
diff --git a/lisp/emacs-lisp/eieio-opt.el b/lisp/emacs-lisp/eieio-opt.el
index 9c842f4682..17931f29f3 100644
--- a/lisp/emacs-lisp/eieio-opt.el
+++ b/lisp/emacs-lisp/eieio-opt.el
@@ -152,7 +152,7 @@ eieio-help-constructor
         (help-insert-xref-button
 	 (help-fns-short-filename location)
 	 'cl-type-definition ctr location 'define-type)
-	(insert (substitute-command-keys "'")))
+        (insert (substitute-quotes "'")))
       (insert ".\nCreates an object of class " (symbol-name ctr) ".")
       (goto-char (point-max))
       (if (autoloadp def)
diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el
index 5445fa970f..bb0ba20a4f 100644
--- a/lisp/emacs-lisp/package.el
+++ b/lisp/emacs-lisp/package.el
@@ -2546,7 +2546,7 @@ describe-package-1
                         "',\n             shadowing a ")
                        (propertize "built-in package"
                                    'font-lock-face 'package-status-built-in))
-             (insert (substitute-command-keys "'")))
+             (insert (substitute-quotes "'")))
            (if signed
                (insert ".")
              (insert " (unsigned)."))
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 03bbc979a9..4ad2631d60 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -617,13 +617,13 @@ help-fns--parent-mode
                           (get function
                                'derived-mode-parent))))
     (when parent-mode
-      (insert (substitute-command-keys "  Parent mode: `"))
+      (insert (substitute-quotes "  Parent mode: `"))
       (let ((beg (point)))
         (insert (format "%s" parent-mode))
         (make-text-button beg (point)
                           'type 'help-function
                           'help-args (list parent-mode)))
-      (insert (substitute-command-keys "'.\n")))))
+      (insert (substitute-quotes "'.\n")))))
 
 (defun help-fns--obsolete (function)
   ;; Ignore lambda constructs, keyboard macros, etc.
@@ -1310,7 +1310,7 @@ help-fns--var-risky
     (princ "  This variable may be risky if used as a \
 file-local variable.\n")
     (when (assq variable safe-local-variable-values)
-      (princ (substitute-command-keys
+      (princ (substitute-quotes
               "  However, you have added it to \
 `safe-local-variable-values'.\n")))))
 
@@ -1360,8 +1360,8 @@ help-fns--var-file-local
 	          (insert-text-button
 	           file 'type 'help-dir-local-var-def
                    'help-args (list variable file)))
-	        (princ (substitute-command-keys "'.\n"))))
-          (princ (substitute-command-keys
+                (princ (substitute-quotes "'.\n"))))
+          (princ (substitute-quotes
 	          "  This variable's value is file-local.\n")))))))
 
 (add-hook 'help-fns-describe-variable-functions #'help-fns--var-watchpoints)
@@ -1439,10 +1439,10 @@ help-fns--var-bufferlocal
      ((not permanent-local))
      ((bufferp locus)
       (princ
-       (substitute-command-keys
+       (substitute-quotes
         "  This variable's buffer-local value is permanent.\n")))
      (t
-      (princ (substitute-command-keys
+      (princ (substitute-quotes
 	      "  This variable's value is permanent \
 if it is given a local binding.\n"))))))
 
@@ -1518,9 +1518,9 @@ describe-face
                   (setq help-mode--current-data (list :symbol f))
                 (setq help-mode--current-data (list :symbol f
                                                     :file file-name))
-		(princ (substitute-command-keys "Defined in `"))
+                (princ (substitute-quotes "Defined in `"))
 		(princ (help-fns-short-filename file-name))
-		(princ (substitute-command-keys "'"))
+                (princ (substitute-quotes "'"))
 		;; Make a hyperlink to the library.
 		(save-excursion
 		  (re-search-backward
diff --git a/lisp/help.el b/lisp/help.el
index eaca33795a..a200ce3fad 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1172,9 +1172,9 @@ substitute-command-keys
                   (cond
                    ((null this-keymap)
                     (insert "\nUses keymap "
-                            (substitute-command-keys "`")
+                            (substitute-quotes "`")
                             (symbol-name name)
-                            (substitute-command-keys "'")
+                            (substitute-quotes "'")
                             ", which is not currently defined.\n")
                     (unless generate-summary
                       (setq keymap nil)))
@@ -1201,6 +1201,18 @@ substitute-command-keys
              (t (forward-char 1)))))
         (buffer-string)))))
 
+(defun substitute-quotes (string)
+  "Substitute quote characters for display.
+Each grave accent \\=` is replaced by left quote, and each
+apostrophe \\=' is replaced by right quote.  Left and right quote
+characters are specified by ‘text-quoting-style’."
+  (cond ((eq (text-quoting-style) 'curve)
+         (string-replace "`" "‘"
+                         (string-replace "'" "’" string)))
+        ((eq (text-quoting-style) 'straight)
+         (string-replace "`" "'" string))
+        (t string))))
+
 (defvar help--keymaps-seen nil)
 (defun describe-map-tree (startmap partial shadow prefix title no-menu
                                    transl always-title mention-shadow)
diff --git a/lisp/progmodes/octave.el b/lisp/progmodes/octave.el
index 6bf070cf9e..c7b1b4f61d 100644
--- a/lisp/progmodes/octave.el
+++ b/lisp/progmodes/octave.el
@@ -1721,12 +1721,12 @@ octave-help
                  (dir (file-name-directory
                        (directory-file-name (file-name-directory file)))))
             (replace-match "" nil nil nil 1)
-            (insert (substitute-command-keys "`"))
+            (insert (substitute-quotes "`"))
             ;; Include the parent directory which may be regarded as
             ;; the category for the FN.
             (help-insert-xref-button (file-relative-name file dir)
                                      'octave-help-file fn)
-            (insert (substitute-command-keys "'"))))
+            (insert (substitute-quotes "'"))))
         ;; Make 'See also' clickable.
         (with-syntax-table octave-mode-syntax-table
           (when (re-search-forward "^\\s-*See also:" nil t)
diff --git a/test/lisp/help-tests.el b/test/lisp/help-tests.el
index 871417da3d..c3fe768107 100644
--- a/test/lisp/help-tests.el
+++ b/test/lisp/help-tests.el
@@ -147,25 +147,45 @@ help-tests-substitute-command-keys/undefined-map
             "\nUses keymap [`'‘]foobar-map['’], which is not currently defined.\n")))
 
 (ert-deftest help-tests-substitute-command-keys/quotes ()
- (with-substitute-command-keys-test
+  (with-substitute-command-keys-test
+   (let ((text-quoting-style 'curve))
+     (test "quotes ‘like this’" "quotes ‘like this’")
+     (test "`x'" "‘x’")
+     (test "`" "‘")
+     (test "'" "’")
+     (test "\\`" "\\‘"))
+   (let ((text-quoting-style 'straight))
+     (test "quotes `like this'" "quotes 'like this'")
+     (test "`x'" "'x'")
+     (test "`" "'")
+     (test "'" "'")
+     (test "\\`" "\\'"))
+   (let ((text-quoting-style 'grave))
+     (test "quotes `like this'" "quotes `like this'")
+     (test "`x'" "`x'")
+     (test "`" "`")
+     (test "'" "'")
+     (test "\\`" "\\`"))))
+
+(ert-deftest help-tests-substitute-quotes ()
   (let ((text-quoting-style 'curve))
-    (test "quotes ‘like this’" "quotes ‘like this’")
-    (test "`x'" "‘x’")
-    (test "`" "‘")
-    (test "'" "’")
-    (test "\\`" "\\‘"))
+    (should (string= (substitute-quotes "quotes ‘like this’") "quotes ‘like this’"))
+    (should (string= (substitute-quotes "`x'") "‘x’"))
+    (should (string= (substitute-quotes "`") "‘"))
+    (should (string= (substitute-quotes "'") "’"))
+    (should (string= (substitute-quotes "\\`") "\\‘")))
   (let ((text-quoting-style 'straight))
-    (test "quotes `like this'" "quotes 'like this'")
-    (test "`x'" "'x'")
-    (test "`" "'")
-    (test "'" "'")
-    (test "\\`" "\\'"))
+    (should (string= (substitute-quotes "quotes `like this'") "quotes 'like this'"))
+    (should (string= (substitute-quotes "`x'") "'x'"))
+    (should (string= (substitute-quotes "`") "'"))
+    (should (string= (substitute-quotes "'") "'"))
+    (should (string= (substitute-quotes "\\`") "\\'")))
   (let ((text-quoting-style 'grave))
-    (test "quotes `like this'" "quotes `like this'")
-    (test "`x'" "`x'")
-    (test "`" "`")
-    (test "'" "'")
-    (test "\\`" "\\`"))))
+    (should (string= (substitute-quotes "quotes `like this'") "quotes `like this'"))
+    (should (string= (substitute-quotes "`x'") "`x'"))
+    (should (string= (substitute-quotes "`") "`"))
+    (should (string= (substitute-quotes "'") "'"))
+    (should (string= (substitute-quotes "\\`") "\\`"))))
 
 (ert-deftest help-tests-substitute-command-keys/literals ()
   (with-substitute-command-keys-test
-- 
2.30.2

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 12 Oct 2021 08:59:15 -0700
> Cc: larsi@gnus.org, 51040@debbugs.gnu.org
> 
> > Also, this seems to ignore the nil value of text-quoting-style?
> 
> The reason is that `text-quoting-style' (the function) handles this
> already, and will never return nil.  (This is arguably a bit confusing,
> but it is what it is.)

That's worth a comment, IMO.

(And why do you use the function and not the variable, btw?)

> > And finally, I think the doc string of text-quoting-style should be
> > amended, since it says that variable's effect is limited to help text
> > and format-message, but now it seems its effect will spread much
> > wider.
> 
> Hmm, in what sense will it spread wider?

In the sense that any caller of substitute-quotes will introduce this
into any text that is constructed from the results.

> I think this will still be limited to help and messages?

There's no way for us to limit the domain of its usage, in practice.

> IOW, I'm happy to add something, but I'm not sure what that would
> be.

It should at least say that any callers of the new function will be
affected by text-quoting-style.

> >> * lisp/minibuffer.el (format-prompt): Use substitute-command-keys.
> >> (Bug#51040)
> >
> > I'm not sure I understand the rationale for this.  This will change
> > the appearance of formatted prompts, won't it?  So people will now
> > have to use \\=' to get a literal apostrophe?  is that really what we
> > want, and if so, why?
> 
> The reason for the change is that we want curved quotes for all the
> usual reasons

We do?  Who is "we" here?  I sense another heated argument about this
issue, which was a hard sell even in the help and error messages.  My
take from that argument is that "we" want to limit these conversions
to as few contexts as possible, to keep the community at peace, if for
no other reason.

> and it might be useful to allow command substitutions as well, in
> case a prompt wants to show a keybinding.

But the change forces this on anyone who uses format-prompt, doesn't
it?  And we are now advertising format-prompt as THE canonical way of
producing prompts, don't we?  And we are proactively converting code
that issues prompts to use format-prompt, don't we?  So soon enough
every prompt will be forced to undergo these substitutions, whether it
wants or not.  Even worse, commands that don't use format-prompt will
produce prompts that look differently from those which do.  Right?

IOW, I'd be okay with an opt-in feature that would perform such
substitutions, if the Lisp program wants that.  But why enforce that?

> format-prompt is new in Emacs 28.1, so I guess we're deciding its
> semantics now.

I'm sorry, but to me this looks like a salami tactics, not a rational
decision-making process.  We decide that it would be nice to have
format-prompt that replaces boilerplate code, so far so good.  Then we
start adding features to it that have nothing to do with boilerplate,
they change the behavior in significant ways.  IOW, the semantics are
the side effect of adding more and more features without any
discussion of the roadmap or the goal which we want to achieve.

> That may or may not be strong enough reason to push this change to
> emacs-28 instead of master.

Not if this becomes now the canon of prompting the user, it isn't.

> +@defun substitute-quotes
> +This function works like @code{substitute-command-keys}, but only
> +replaces quote characters.

The argument is missing, and is not mentioned in the description.
Also, you need "@end defun" to end it.

Thanks.

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> (And why do you use the function and not the variable, btw?)

This is because that's how it's been designed to be used (not by me):

- `text-quoting-style' is the user option.

- Any code that wants to know what nil means should call the function
  `text-quoting-style' because the information needed is only available
  to C.  See default_to_grave_quoting_style in doc.c.  Maybe it could be
  moved to Lisp but the fundamental issue would be the same.

The alternative to this is to replicate default_to_grave_quoting_style
everywhere we want to access the `text-quoting-style' variable and
interpret nil.

> That's worth a comment, IMO.

Hmm, I could have sworn this was already documented in the
`text-quoting-style' variable docstring but it seems that it is not.

I would suggest that we document it there, instead of adding a comment
everywhere we use it.

>> IOW, I'm happy to add something, but I'm not sure what that would
>> be.
>
> It should at least say that any callers of the new function will be
> affected by text-quoting-style.

The `substitute-quotes' docstring currently says this:

    Substitute quote characters for display.
    Each grave accent ` is replaced by left quote, and each
    apostrophe ' is replaced by right quote.  Left and right quote
    characters are specified by ‘text-quoting-style’.

>> The reason for the change is that we want curved quotes for all the
>> usual reasons
>
> We do?  Who is "we" here?  I sense another heated argument about this
> issue, which was a hard sell even in the help and error messages.  My
> take from that argument is that "we" want to limit these conversions
> to as few contexts as possible, to keep the community at peace, if for
> no other reason.

ISTR several posts of your own to emacs-devel defending this position?
But see below.

>> and it might be useful to allow command substitutions as well, in
>> case a prompt wants to show a keybinding.
>
> But the change forces this on anyone who uses format-prompt, doesn't
> it?  And we are now advertising format-prompt as THE canonical way of
> producing prompts, don't we?  And we are proactively converting code
> that issues prompts to use format-prompt, don't we?  So soon enough
> every prompt will be forced to undergo these substitutions, whether it
> wants or not.  Even worse, commands that don't use format-prompt will
> produce prompts that look differently from those which do.  Right?
>
> IOW, I'd be okay with an opt-in feature that would perform such
> substitutions, if the Lisp program wants that.  But why enforce that?

I don't see the risk for controversy, as e.g. `format-message' already
does such substitutions.  Granted, it does not do the full monty
(command substitutions) but it does do the replacement of quoting
characters.  See its docstring.  So the argument is already won for the
"quoted curves in messages where it is supported" side, AFAICT.

This change is about avoiding the inconsistency where `format-messages'
does quote substitutions but `format-prompt' does not.

If it is too much with `substitute-command-keys', I think it should be
perfectly fine with just doing the quote substitutions.  We could use
`format-message' to achieve it in Emacs 28.

> Not if this becomes now the canon of prompting the user, it isn't.

In practice, `format-prompt' is only used for prompts where there is a
default.  Note that the second (DEFAULT) argument is not optional, which
makes it a bit awkward to use in other cases.

AFAICT, for messages without a default `format-message' is almost closer
to being the canonical way of formatting a prompt.

In reality, however, most prompts (in our code at least) don't use any
of them.

We could of course go in different directions:

- We say that `(format-prompt "Foo" nil)' is fine and what we want
  everywhere.  No more `format-message', no more naked strings.

- We extend the `completing-read' and friends to accept a cons as its
  second argument, where the car is the prompt (to be passed to
  `format-message') and the cdr is the default.

- Something else.

IOW, this area is not exactly clear-cut yet, but there's a slow movement
towards more unification along certain lines.  I agree that so far no
one has presented an overall roadmap, so the process is clearly a bit
haphazard.

(I don't think "salami tactics" is the right term, as that sort of
implies that someone has an overreaching plan.  AFAICT, that is
precisely what is missing.  ;-)

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 12 Oct 2021 10:26:53 -0700
> Cc: larsi@gnus.org, 51040@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > (And why do you use the function and not the variable, btw?)
> 
> This is because that's how it's been designed to be used (not by me):
> 
> - `text-quoting-style' is the user option.
> 
> - Any code that wants to know what nil means should call the function
>   `text-quoting-style' because the information needed is only available
>   to C.  See default_to_grave_quoting_style in doc.c.  Maybe it could be
>   moved to Lisp but the fundamental issue would be the same.
> 
> The alternative to this is to replicate default_to_grave_quoting_style
> everywhere we want to access the `text-quoting-style' variable and
> interpret nil.

Ouch! what a mess do we have with this stuff!

  . the doc string of text-quoting-style the function doesn't document
    its return values, but refers to the variable, so it's easy to
    conclude that it also returns nil
  . that doc string says "effective style", without explaining the
    special processing of nil
  . the function is not in the ELisp manual, but the variable is,
    twice(!)

> > That's worth a comment, IMO.
> 
> Hmm, I could have sworn this was already documented in the
> `text-quoting-style' variable docstring but it seems that it is not.
> 
> I would suggest that we document it there, instead of adding a comment
> everywhere we use it.

How many places like that do we have that we should worry?

> >> IOW, I'm happy to add something, but I'm not sure what that would
> >> be.
> >
> > It should at least say that any callers of the new function will be
> > affected by text-quoting-style.
> 
> The `substitute-quotes' docstring currently says this:

I was talking about the doc string of text-quoting-style.  It refer
neither to substitute-command-keys nor to substitute-quotes, only to
(some of) their callers.

> >> The reason for the change is that we want curved quotes for all the
> >> usual reasons
> >
> > We do?  Who is "we" here?  I sense another heated argument about this
> > issue, which was a hard sell even in the help and error messages.  My
> > take from that argument is that "we" want to limit these conversions
> > to as few contexts as possible, to keep the community at peace, if for
> > no other reason.
> 
> ISTR several posts of your own to emacs-devel defending this position?

You misunderstood what I was saying there.

> > IOW, I'd be okay with an opt-in feature that would perform such
> > substitutions, if the Lisp program wants that.  But why enforce that?
> 
> I don't see the risk for controversy, as e.g. `format-message' already
> does such substitutions.

That's part of the substitute-command-keys change with
text-quoting-style, and was done in the past.  I'm asking why would we
want another painful chapter like that.

> This change is about avoiding the inconsistency where `format-messages'
> does quote substitutions but `format-prompt' does not.

What inconsistency?  format-messages is about echo-area messages,
whereas format-prompt is about something else.  That we changed one
doesn't mean we must change the other.  It's a separate decision, and
now we have the benefit of the experience we didn't back then.

> If it is too much with `substitute-command-keys', I think it should be
> perfectly fine with just doing the quote substitutions.  We could use
> `format-message' to achieve it in Emacs 28.

Sorry, I don't follow you here.

> > Not if this becomes now the canon of prompting the user, it isn't.
> 
> In practice, `format-prompt' is only used for prompts where there is a
> default.  Note that the second (DEFAULT) argument is not optional, which
> makes it a bit awkward to use in other cases.
> 
> AFAICT, for messages without a default `format-message' is almost closer
> to being the canonical way of formatting a prompt.
> 
> In reality, however, most prompts (in our code at least) don't use any
> of them.
> 
> We could of course go in different directions:
> 
> - We say that `(format-prompt "Foo" nil)' is fine and what we want
>   everywhere.  No more `format-message', no more naked strings.
> 
> - We extend the `completing-read' and friends to accept a cons as its
>   second argument, where the car is the prompt (to be passed to
>   `format-message') and the cdr is the default.
> 
> - Something else.

We are mis-communicating.  My main problem is with changing the
default behavior of the prompts; I'm okay with having this as an
option.  How are the other things relevant to that?

> (I don't think "salami tactics" is the right term, as that sort of
> implies that someone has an overreaching plan.  AFAICT, that is
> precisely what is missing.  ;-)

No, it means there's a slip on a slippery slope.

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Stefan Kangas]

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

Eli Zaretskii <eliz@gnu.org> writes:

> Ouch! what a mess do we have with this stuff!
>
>   . the doc string of text-quoting-style the function doesn't document
>     its return values, but refers to the variable, so it's easy to
>     conclude that it also returns nil
>   . that doc string says "effective style", without explaining the
>     special processing of nil
>   . the function is not in the ELisp manual, but the variable is,
>     twice(!)

Yeah, it's a mess.  I suggest we address the documentation issues on
emacs-28 with the attached patch.

I compared the duplicate text, and the only thing that was different is
that the word "variable" had been changed into "option".  So I deleted
the one in the wrong section and that incorrectly said "variable".

[-- Attachment #2: 0001-Doc-fixes-for-text-quoting-style.patch --]
[-- Type: text/x-diff, Size: 3941 bytes --]

From cecc2e9dc32edba74d816c4fa327a288ed863006 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Wed, 13 Oct 2021 00:56:39 +0200
Subject: [PATCH] Doc fixes for 'text-quoting-style'

* doc/lispref/help.texi (Keys in Documentation): Remove duplicate
entry for 'text-quoting-style'.  Document the function with the same
name instead.
* src/doc.c (Ftext_quoting_style): Doc fix: clarify the return values.
(syms_of_doc) <Vtext_quoting_style>: Doc fix: clarify that you should
not read the value of this variable directly; use Ftext_quoting_style
instead.  (Bug#51040)
---
 doc/lispref/help.texi | 25 ++++++-------------------
 src/doc.c             | 14 ++++++++++++--
 2 files changed, 18 insertions(+), 21 deletions(-)

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index a788852de7..5133e20d85 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -353,25 +353,6 @@ Keys in Documentation
 @strong{Please note:} Each @samp{\} must be doubled when written in a
 string in Emacs Lisp.
 
-@defopt text-quoting-style
-@cindex curved quotes
-@cindex curly quotes
-The value of this variable is a symbol that specifies the style Emacs
-should use for single quotes in the wording of help and messages.  If
-the variable's value is @code{curve}, the style is @t{‘like this’}
-with curved single quotes.  If the value is @code{straight}, the style
-is @t{'like this'} with straight apostrophes.  If the value is
-@code{grave}, quotes are not translated and the style is @t{`like
-this'} with grave accent and apostrophe, the standard style before
-Emacs version 25.  The default value @code{nil} acts like @code{curve}
-if curved single quotes seem to be displayable, and like @code{grave}
-otherwise.
-
-This option is useful on platforms that have problems with curved
-quotes.  You can customize it freely according to your personal
-preference.
-@end defopt
-
 @defun substitute-command-keys string
 This function scans @var{string} for the above special sequences and
 replaces them by what they stand for, returning the result as a string.
@@ -477,6 +458,12 @@ Text Quoting Style
 preference.
 @end defopt
 
+@defun text-quoting-style
+You should not read the value of the variable
+@code{text-quoting-style} directly.  Instead, use this function with
+the same name to correctly handle the nil case described above.
+@end defun
+
 @node Describing Characters
 @section Describing Characters for Help Messages
 @cindex describe characters and events
diff --git a/src/doc.c b/src/doc.c
index 6be023bb93..4d5c693a29 100644
--- a/src/doc.c
+++ b/src/doc.c
@@ -681,7 +681,13 @@ default_to_grave_quoting_style (void)
 DEFUN ("text-quoting-style", Ftext_quoting_style,
        Stext_quoting_style, 0, 0, 0,
        doc: /* Return the current effective text quoting style.
-See variable `text-quoting-style'.  */)
+If the variable `text-quoting-style' is `grave', `straight' or
+`curve', just return that value.  If it is nil (the default), return
+`grave' if curved quotes cannot be displayed, otherwise return
+`quote'.  Any other value is invalid; in that case return `grave'.
+
+Note that in contrast to the variable `text-quoting-style', this
+function will never return nil.  */)
   (void)
 {
   /* Use grave accent and apostrophe `like this'.  */
@@ -731,7 +737,11 @@ syms_of_doc (void)
   `grave':    quote with grave accent and apostrophe \\=`like this\\=';
 	      i.e., do not alter the original quote marks.
   nil:        like `curve' if curved single quotes are displayable,
-	      and like `grave' otherwise.  This is the default.  */);
+	      and like `grave' otherwise.  This is the default.
+
+You should never read the value of this variable directly from a Lisp
+program.  Use the function `text-quoting-style' instead, as that will
+handle the default nil value.  */);
   Vtext_quoting_style = Qnil;
 
   DEFVAR_BOOL ("internal--text-quoting-flag", text_quoting_flag,
-- 
2.30.2

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 12 Oct 2021 16:21:52 -0700
> Cc: larsi@gnus.org, 51040@debbugs.gnu.org
> 
> >   . the doc string of text-quoting-style the function doesn't document
> >     its return values, but refers to the variable, so it's easy to
> >     conclude that it also returns nil
> >   . that doc string says "effective style", without explaining the
> >     special processing of nil
> >   . the function is not in the ELisp manual, but the variable is,
> >     twice(!)
> 
> Yeah, it's a mess.  I suggest we address the documentation issues on
> emacs-28 with the attached patch.

Thanks.

> +@defun text-quoting-style
> +You should not read the value of the variable
> +@code{text-quoting-style} directly.  Instead, use this function with
> +the same name to correctly handle the nil case described above.
> +@end defun

This should explain why we recommend using the function.

>  DEFUN ("text-quoting-style", Ftext_quoting_style,
>         Stext_quoting_style, 0, 0, 0,
>         doc: /* Return the current effective text quoting style.
> -See variable `text-quoting-style'.  */)
> +If the variable `text-quoting-style' is `grave', `straight' or
> +`curve', just return that value.  If it is nil (the default), return
> +`grave' if curved quotes cannot be displayed, otherwise return
> +`quote'.  Any other value is invalid; in that case return `grave'.

This is okay, with the exception of the "invalid" part: if we allow
it, it is not invalid.  Just say something like "Any other value is
treated as `grave'."

Also, perhaps we should say more about "cannot be displayed".  At
least the manual should elaborate about that, but I think the doc
string should also at least hint what it means.

(Btw, this whole feature has a bug, in that we determine the "cannot
be displayed" part only once, at startup, whereas it in general can be
different on each frame.  But that's a separate issue.)

> +You should never read the value of this variable directly from a Lisp
> +program.  Use the function `text-quoting-style' instead, as that will
> +handle the default nil value.  */);

Again, "handle" is too vague.  Either tell what it means, or perhaps
refer to the doc string of the function for these details.

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Also, perhaps we should say more about "cannot be displayed".  At
> least the manual should elaborate about that, but I think the doc
> string should also at least hint what it means.

I'm not sure how to describe that in a precise way, but perhaps:

"For example, some text terminals cannot display grave quotes."

Is that sufficient, or do we need even more detail?  I'm not sure what
to add besides perhaps that graphical displays/frames (which word do
we prefer?) can display such characters.

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 13 Oct 2021 14:25:41 +0200
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 51040@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Also, perhaps we should say more about "cannot be displayed".  At
> > least the manual should elaborate about that, but I think the doc
> > string should also at least hint what it means.
> 
> I'm not sure how to describe that in a precise way, but perhaps:
> 
> "For example, some text terminals cannot display grave quotes."

Yes, and I'd also mention font issues on GUI frames (though those
should be very rare).

> Is that sufficient, or do we need even more detail?

It's fine to be brief here, I think, as the above is sufficiently
self-explanatory.

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> Subject: [PATCH] Doc fixes for 'text-quoting-style'

I've now applied this to Emacs 29 (with some amendments to take Eli's
comments into consideration).

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Dmitry Gutov]

On 12.10.2021 21:43, Eli Zaretskii wrote:
>> This change is about avoiding the inconsistency where `format-messages'
>> does quote substitutions but `format-prompt' does not.
> What inconsistency?  format-messages is about echo-area messages,
> whereas format-prompt is about something else.

They're displayed in the same area of the screen, and with similar 
purpose (telling something to the user; prompts also ask something back, 
messages do not).

The different between the echo area and the minibuffer is subtle enough 
for most users, so this kind of difference will almost certainly be 
perceived as inconsistency.

I think the main reason this question hasn't come up before is that 
having any quotes in the prompt, `...' or not, is very rare. Offhand, 
I've found only two such instances in Emacs source tree (in faces.el).

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> Subject: [PATCH 1/2] New function substitute-quotes

Pushed to Emacs 29.

bug#51040: No curved quotes in format-prompt and minibuffer-default-prompt-format

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> It seems like `format-prompt' and `minibuffer-default-prompt-format'
> does not support curved quotes.  Should they?

I've now made this change in Emacs 29.