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.