From 8bc41bd77d272e2273e4f40cf7b4a57fe8900045 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Sun, 24 Sep 2017 11:02:40 -0700 Subject: [PATCH] Improve text-quoting-style doc in lispref * 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. --- doc/lispref/control.texi | 11 +++----- doc/lispref/display.texi | 13 ++++----- doc/lispref/elisp.texi | 1 + doc/lispref/help.texi | 69 ++++++++++++++++++++++++++++++++++-------------- doc/lispref/strings.texi | 12 +++------ doc/lispref/tips.texi | 4 +-- 6 files changed, 65 insertions(+), 45 deletions(-) diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 401a999cf2..ab0b49266d 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1101,13 +1101,10 @@ Signaling Errors 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 address@hidden"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. +Typically grave accent and apostrophe in the format translate to +matching curved quotes, e.g., @t{"Missing `%s'"} might result in address@hidden"Missing ‘foo’"}. @xref{Text Quoting Style}, for how to control +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 3dae984f33..12ca065d86 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -265,13 +265,10 @@ Displaying Messages 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 address@hidden"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. +Typically grave accent and apostrophe in the format translate to +matching curved quotes, e.g., @t{"Missing `%s'"} might result in address@hidden"Missing ‘foo’"}. @xref{Text Quoting Style}, for how to control +this translation. In batch mode, the message is printed to the standard error stream, followed by a newline. @@ -7035,7 +7032,7 @@ Active Display Table 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 4cbcdf855d..c752594584 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -940,6 +940,7 @@ Top * 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 cb21411352..3da365904e 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -33,6 +33,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. @@ -336,6 +337,7 @@ Keys in Documentation (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}. address@hidden Quoting Style}. @item ' (apostrophe) stands for a right quote. @@ -351,26 +353,6 @@ Keys in Documentation @strong{Please note:} Each @samp{\} must be doubled when written in a string in Emacs Lisp. address@hidden text-quoting-style address@hidden curved quotes address@hidden 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 address@hidden this’} with curved single quotes. If the value is address@hidden, 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. address@hidden defvar - @defun substitute-command-keys string This function scans @var{string} for the above special sequences and replaces them by what they stand for, returning the result as a string. @@ -429,6 +411,53 @@ Keys in Documentation strings---for instance, you can refer to functions, variables, and sections of this manual. @xref{Documentation Tips}, for details. address@hidden Text Quoting Style address@hidden 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 address@hidden(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 address@hidden, you can avoid translation by using a format @t{"%s"} +with an argument that is a call to @code{format}. For example, address@hidden(message "%s" (format "`(a ,(sin %S)) ==> (a %S)" x (sin x)))} +displays a message that starts with grave accent regardless of text +quoting style. + address@hidden text-quoting-style address@hidden curved quotes address@hidden 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 address@hidden, 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. address@hidden defvar + @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 219225d412..a89e9671d7 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -826,17 +826,13 @@ Formatting Strings @defun format-message string &rest objects @cindex curved quotes, in formatted messages @cindex curly quotes, in formatted messages address@hidden @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. @xref{Keys in Documentation}, for how the address@hidden 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 address@hidden"Missing ‘foo’"}. @xref{Text Quoting Style}, for how to control +this translation. @end defun @cindex @samp{%} in format diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 17fd4a1027..0bccde66cd 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -683,8 +683,8 @@ Documentation Tips older convention was designed for now-obsolete displays in which grave accent and apostrophe were mirror images. Documentation using this convention is converted to the user's -preferred format when it is copied into a help buffer. @xref{Keys in -Documentation}. +preferred format when it is copied into a help buffer. @xref{Text +Quoting Style}. @cindex hyperlinks in documentation strings Help mode automatically creates a hyperlink when a documentation string -- 2.13.5