@cindex curly quotes
@cindex curved quotes
@cindex homoglyph face
+
+Emacs tries to determine if the curved quotes @samp{‘} and @samp{’}
+can be displayed on the current display. By default, if this seems to
+be so, then Emacs will translate the @acronym{ASCII} quotes (@samp{`}
+and @samp{'}), when they appear in messages and help texts, to these
+curved quotes. You can influence or inhibit this translation by
+customizing the user option @code{text-quoting-style} (@pxref{Keys in
+Documentation,,, elisp, The Emacs Lisp Reference Manual}).
+
If the curved quotes @samp{‘}, @samp{’}, @samp{“}, and @samp{”} are
known to look just like @acronym{ASCII} characters, they are shown
-with the @code{homoglyph} face. Curved quotes that cannot be
-displayed are shown as their @acronym{ASCII} approximations @samp{`},
-@samp{'}, and @samp{"} with the @code{homoglyph} face.
+with the @code{homoglyph} face. Curved quotes that are known not to
+be displayable are shown as their @acronym{ASCII} approximations
+@samp{`}, @samp{'}, and @samp{"} with the @code{homoglyph} face.
@node Cursor Display
@section Displaying the Cursor
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
+@code{nil} around the call to @code{error}; this causes the
+@acronym{ASCII} quote characters to be output unchanged.
@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}
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
+@code{nil} around calls to @code{message}; this causes the
+@acronym{ASCII} quote characters to be output unchanged.
In batch mode, the message is printed to the standard error stream,
followed by a newline.
@strong{Please note:} Each @samp{\} must be doubled when written in a
string in Emacs Lisp.
-@defvar text-quoting-style
+@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 are displayable, and
-like @code{grave} otherwise.
-
-This variable can be used by experts on platforms that have problems
-with curved quotes. As it is not intended for casual use, it is not a
-user option.
-@end defvar
+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{nil} or @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{t} acts like
+@code{curve} if curved single quotes seem to be displayable, and like
+@code{nil} 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
This function scans @var{string} for the above special sequences and
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. @xref{Keys in Documentation}, for how the
-@code{text-quoting-style} variable affects generated quotes.
+unusual style in English. One way around such problems is to bind
+@code{text-quoting-style} to @code{nil} around calls to
+@code{format-message}; this causes the @acronym{ASCII} quoting
+characters to be output unchanged. @xref{Keys in Documentation}, for
+how the @code{text-quoting-style} variable affects generated quotes.
@end defun
@cindex @samp{%} in format
*** Many variables obsoleted in 22.1 referring to face symbols
+++
-** The variable '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.
+** 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. The value nil now means "no translation", and the value
+t, the default, means "use curved quotes if displayable" (as nil did
+in Emacs 25). The other possible values remain unchanged.
+`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.
---
** Functions like 'check-declare-file' and 'check-declare-directory'
(visible-bell display boolean)
(no-redraw-on-reenter display boolean)
+ ;; doc.c
+ (text-quoting-style display
+ (choice
+ (const :tag "No translation" nil)
+ (const :tag "Prefer \\=‘curved\\=’ quotes, if possible" t)
+ (const :tag "\\=‘Curved\\=’ quotes" curved)
+ (const :tag "\\='Straight\\=' quotes" straight)
+ (const :tag "\\=`Grave\\=' quotes" grave)))
+
;; dosfns.c
(dos-display-scancodes display boolean)
(dos-hyper-key keyboard integer)
text_quoting_style (void)
{
if (NILP (Vtext_quoting_style)
- ? default_to_grave_quoting_style ()
- : EQ (Vtext_quoting_style, Qgrave))
+ || (EQ (Vtext_quoting_style, Qt)
+ ? default_to_grave_quoting_style ()
+ : EQ (Vtext_quoting_style, Qgrave)))
return GRAVE_QUOTING_STYLE;
else if (EQ (Vtext_quoting_style, Qstraight))
return STRAIGHT_QUOTING_STYLE;
Vbuild_files = Qnil;
DEFVAR_LISP ("text-quoting-style", Vtext_quoting_style,
- doc: /* Style to use for single quotes in help and messages.
-Its value should be a symbol. It works by substituting certain single
-quotes for grave accent and apostrophe. This is done in help output
-and in functions like `message' and `format-message'. It is not done
-in `format'.
-
-`curve' means quote with curved single quotes ‘like this’.
-`straight' means quote with straight apostrophes \\='like this\\='.
-`grave' means quote with grave accent and apostrophe \\=`like this\\=';
-i.e., do not alter quote marks. The default value nil acts like
-`curve' if curved single quotes are displayable, and like `grave'
-otherwise. */);
- Vtext_quoting_style = Qnil;
+ doc: /* How to translate single quotes in help and messages.
+Its value should be a symbol, and describes the style of quote
+substituted for ASCII quote characters GRAVE ACCENT (\\=`, \\=\\x60) and
+APOSTROPHE (\\=', \\=\\x27). This is done in help output and in functions
+like `message' and `format-message'. It is not done in `format'.
+
+The value nil means do not translate the quotes at all. The value t
+(the default) acts like `curve' if curved single quotes appear to be
+displayable, and like nil otherwise. `curve' means quote with curved
+single quotes ‘like this’. `straight' means quote with apostrophes
+\\='like this\\='. `grave' means do not translate quote marks and is
+now a synonym for nil.
+
+(The value t was newly introduced in Emacs 26, and in Emacs 25 nil
+meant what t means now.) */);
+ Vtext_quoting_style = Qt;
DEFVAR_BOOL ("internal--text-quoting-flag", text_quoting_flag,
- doc: /* If nil, a nil `text-quoting-style' is treated as `grave'. */);
+ doc: /* If nil, a `text-quoting-style' value t is treated as `nil'. */);
/* Initialized by ‘main’. */
defsubr (&Sdocumentation);
projects / emacs.git / commitdiff