Commit 8c18dcbc authored by Alan Mackenzie's avatar Alan Mackenzie

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.
parent 5f76ac15
......@@ -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}
......
......@@ -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
......
......@@ -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.
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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'
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment