From 54c3794899ef2d4d88812fb445b6e2acc85a2720 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sat, 10 Sep 2022 07:29:48 +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) : 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 | 26 +++++++------------------- src/doc.c | 15 +++++++++++++-- 2 files changed, 20 insertions(+), 21 deletions(-) diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 463039c5a0e..ac284f745f4 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -374,25 +374,6 @@ as link in the @file{*Help*} buffer. @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 &optional no-face include-menus @vindex help-key-binding@r{ (face)} This function scans @var{string} for the above special sequences and @@ -505,6 +486,13 @@ quotes. You can customize it freely according to your personal 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 dynamically compute the correct quoting style on the +current terminal in the @code{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 34b80d03aa9..d98d121ebd5 100644 --- a/src/doc.c +++ b/src/doc.c @@ -643,7 +643,14 @@ 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 (for instance, on a +terminal with no support for these characters), otherwise return +`quote'. Any other value is treated as `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'. */ @@ -694,7 +701,11 @@ The value should be one of these symbols: `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 +compute the correct value for the current terminal in the nil case. */); Vtext_quoting_style = Qnil; DEFVAR_BOOL ("internal--text-quoting-flag", text_quoting_flag, -- 2.39.2