From: Alan Mackenzie <acm@muc.de>
Date: Sat, 30 Sep 2017 11:08:16 +0000 (+0000)
Subject: Amend documentation for text-quoting-style becoming a user option.
X-Git-Tag: emacs-26.0.90~75
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=8c18dcbc784a97196d6513e5556de48af4cea617;p=emacs.git
Amend documentation for text-quoting-style becoming a user option.
* doc/lispref/control.texi (Signaling Errors):
* doc/lispref/display.texi (Displaying Messages):
* doc/lispref/strings.texi (Formatting Strings):
Edit for brevity, farming out the details to the new
Text Quoting Style node.
* doc/lispref/help.texi (Text Quoting Style): New section.
Move detailed discussion of text-quoting-style here.
Add discussion about how to output grave accent and apostrophe in
documentation and messages. Adjust xrefs to point to this section
when appropriate.
* etc/NEWS: text-quoting-style semantics have not changed.
---
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index c39e035459e..4eddbe9c122 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1101,16 +1101,10 @@ These examples show typical uses of @code{error}:
error symbol @code{error}, and a list containing the string returned by
@code{format-message}.
-The @code{text-quoting-style} variable controls what quotes are
-generated; @xref{Keys in Documentation}. A call using a format like
-@t{"Missing `%s'"} with grave accents and apostrophes typically
-generates a message like @t{"Missing âfooâ"} with matching curved
-quotes. In contrast, a call using a format like @t{"Missing '%s'"}
-with only apostrophes typically generates a message like @t{"Missing
-âfooâ"} with only closing curved quotes, an unusual style in English.
-One way around this problem is to bind @code{text-quoting-style} to
-the symbol @code{grave} around the call to @code{error}; this causes
-@acronym{ASCII} quote characters to be output unchanged.
+Typically grave accent and apostrophe in the format translate to
+matching curved quotes, e.g., @t{"Missing `%s'"} might result in
+@t{"Missing âfooâ"}. @xref{Text Quoting Style}, for how to influence
+or inhibit this translation.
@strong{Warning:} If you want to use your own string as an error message
verbatim, don't just write @code{(error @var{string})}. If @var{string}
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 62b136f6c60..afd09cfb330 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -265,16 +265,10 @@ properties, it is displayed with the specified faces (@pxref{Faces}).
The string is also added to the @file{*Messages*} buffer, but without
text properties (@pxref{Logging Messages}).
-The @code{text-quoting-style} variable controls what quotes are
-generated; @xref{Keys in Documentation}. A call using a format like
-@t{"Missing `%s'"} with grave accents and apostrophes typically
-generates a message like @t{"Missing âfooâ"} with matching curved
-quotes. In contrast, a call using a format like @t{"Missing '%s'"}
-with only apostrophes typically generates a message like @t{"Missing
-âfooâ"} with only closing curved quotes, an unusual style in English.
-One way around this problem is to bind @code{text-quoting-style} to
-the symbol @code{grave} around calls to @code{message}; this causes
-@acronym{ASCII} quote characters to be output unchanged.
+Typically grave accent and apostrophe in the format translate to
+matching curved quotes, e.g., @t{"Missing `%s'"} might result in
+@t{"Missing âfooâ"}. @xref{Text Quoting Style}, for how to influence
+or inhibit this translation.
In batch mode, the message is printed to the standard error stream,
followed by a newline.
@@ -7038,7 +7032,7 @@ window display table nor a buffer display table defined, or when Emacs
is outputting text to the standard output or error streams. Although its
default is typically @code{nil}, in an interactive session if the
terminal cannot display curved quotes, its default maps curved quotes
-to ASCII approximations. @xref{Keys in Documentation}.
+to ASCII approximations. @xref{Text Quoting Style}.
@end defvar
The @file{disp-table} library defines several functions for changing
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 4cbcdf855d1..c7525945845 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -940,6 +940,7 @@ Documentation
* Documentation Basics:: Where doc strings are defined and stored.
* Accessing Documentation:: How Lisp programs can access doc strings.
* Keys in Documentation:: Substituting current key bindings.
+* Text Quoting Style:: Quotation marks in doc strings and messages.
* Describing Characters:: Making printable descriptions of
non-printing characters and key sequences.
* Help Functions:: Subroutines used by Emacs help facilities.
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 74dc6dac9cb..4aa9b95180e 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -33,6 +33,7 @@ Help, emacs, The GNU Emacs Manual}.
* Documentation Basics:: Where doc strings are defined and stored.
* Accessing Documentation:: How Lisp programs can access doc strings.
* Keys in Documentation:: Substituting current key bindings.
+* Text Quoting Style:: Quotation marks in doc strings and messages.
* Describing Characters:: Making printable descriptions of
non-printing characters and key sequences.
* Help Functions:: Subroutines used by Emacs help facilities.
@@ -336,6 +337,7 @@ specifies @var{mapvar}'s value as the keymap for any following
(grave accent) stands for a left quote.
This generates a left single quotation mark, an apostrophe, or a grave
accent depending on the value of @code{text-quoting-style}.
+@xref{Text Quoting Style}.
@item '
(apostrophe) stands for a right quote.
@@ -428,6 +430,53 @@ C-g abort-recursive-edit
strings---for instance, you can refer to functions, variables, and
sections of this manual. @xref{Documentation Tips}, for details.
+@node Text Quoting Style
+@section Text Quoting Style
+
+ Typically, grave accents and apostrophes are treated specially in
+documentation strings and diagnostic messages, and translate to matching
+single quotation marks (also called ``curved quotes''). For example,
+the documentation string @t{"Alias for `foo'."} and the function call
+@code{(message "Alias for `foo'.")} both translate to @t{"Alias for
+âfooâ."}. Less commonly, Emacs displays grave accents and apostrophes
+as themselves, or as apostrophes only (e.g., @t{"Alias for 'foo'."}).
+Documentation strings and message formats should be written so that
+they display well with any of these styles. For example, the
+documentation string @t{"Alias for 'foo'."} is probably not what you
+want, as it can display as @t{"Alias for âfooâ."}, an unusual style in
+English.
+
+ Sometimes you may need to display a grave accent or apostrophe
+without translation, regardless of text quoting style. In a
+documentation string, you can do this with escapes. For example, in
+the documentation string @t{"\\=`(a ,(sin 0)) ==> (a 0.0)"} the grave
+accent is intended to denote Lisp code, so it is escaped and displays
+as itself regardless of quoting style. In a call to @code{message} or
+@code{error}, you can avoid translation by using a format @t{"%s"}
+with an argument that is a call to @code{format}. For example,
+@code{(message "%s" (format "`(a ,(sin %S)) ==> (a %S)" x (sin x)))}
+displays a message that starts with grave accent regardless of text
+quoting style.
+
+@defopt text-quoting-style
+@cindex curved quotes
+@cindex curly quotes
+The value of this user option is a symbol that specifies the style
+Emacs should use for single quotes in the wording of help and
+messages. If the option'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
+
@node Describing Characters
@section Describing Characters for Help Messages
@cindex describe characters and events
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 10385e05501..dd004927caf 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -826,20 +826,14 @@ to the produced string representations of the argument @var{objects}.
@defun format-message string &rest objects
@cindex curved quotes, in formatted messages
@cindex curly quotes, in formatted messages
-@cindex @code{text-quoting-style}, and formatting messages
This function acts like @code{format}, except it also converts any
grave accents (@t{`}) and apostrophes (@t{'}) in @var{string} as per the
value of @code{text-quoting-style}.
-A format that quotes with grave accents and apostrophes @t{`like
-this'} typically generates curved quotes @t{âlike thisâ}. In
-contrast, a format that quotes with only apostrophes @t{'like this'}
-typically generates two closing curved quotes @t{âlike thisâ}, an
-unusual style in English. One way around such problems is to bind
-@code{text-quoting-style} to the symbol @code{grave} around calls to
-@code{format-message}; this causes @acronym{ASCII} quoting characters
-to be output unchanged. @xref{Keys in Documentation}, for how the
-@code{text-quoting-style} variable affects generated quotes.
+Typically grave accent and apostrophe in the format translate to
+matching curved quotes, e.g., @t{"Missing `%s'"} might result in
+@t{"Missing âfooâ"}. @xref{Text Quoting Style}, for how to influence
+or inhibit this translation.
@end defun
@cindex @samp{%} in format
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index e3ae53536f9..b37f2b22b82 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -751,7 +751,8 @@ position. This function does that conveniently.
@defun syntax-ppss &optional pos
This function returns the parser state that the parser would reach at
-position @var{pos} starting from the beginning of the buffer.
+position @var{pos} starting from the beginning of the visible portion
+of the buffer.
@iftex
See the next section for
@end iftex
@@ -762,11 +763,11 @@ for a description of the parser state.
The return value is the same as if you call the low-level parsing
function @code{parse-partial-sexp} to parse from the beginning of the
-buffer to @var{pos} (@pxref{Low-Level Parsing}). However,
-@code{syntax-ppss} uses a cache to speed up the computation. Due to
-this optimization, the second value (previous complete subexpression)
-and sixth value (minimum parenthesis depth) in the returned parser
-state are not meaningful.
+visible portion of the buffer to @var{pos} (@pxref{Low-Level
+Parsing}). However, @code{syntax-ppss} uses caches to speed up the
+computation. Due to this optimization, the second value (previous
+complete subexpression) and sixth value (minimum parenthesis depth) in
+the returned parser state are not meaningful.
This function has a side effect: it adds a buffer-local entry to
@code{before-change-functions} (@pxref{Change Hooks}) for
diff --git a/etc/NEWS b/etc/NEWS
index 20182c1b816..51122b1152a 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1247,10 +1247,8 @@ change FOO, respectively. The exhaustive list of removed variables is:
** The variable 'text-quoting-style' is now a customizable option. It
controls whether to and how to translate ASCII quotes in messages and
help output. Its possible values and their semantics remain unchanged
-from Emacs 25, except that 'text-quoting-style' no longer affects the
-treatment of curved quotes in format arguments to functions like
-'message' and 'format-message'. In particular, when this variable's
-value is 'grave', all quotes in formats are output as-is.
+from Emacs 25. In particular, when this variable's value is 'grave',
+all quotes in formats are output as-is.
---
** Functions like 'check-declare-file' and 'check-declare-directory'