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}
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.
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
* 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.
* 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.
(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.
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
@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
@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
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
** 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'
projects / emacs.git / commitdiff