master 54c3794899: Doc fixes for 'text-quoting-style'

[Lars Ingebrigtsen]

branch: master
commit 54c3794899ef2d4d88812fb445b6e2acc85a2720
Author: Stefan Kangas <stefan@marxist.se>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    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 | 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 463039c5a0..ac284f745f 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 34b80d03aa..d98d121ebd 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,