[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] scratch/customize-quotes 8b234b6: Amend documentation for
From: |
Alan Mackenzie |
Subject: |
[Emacs-diffs] scratch/customize-quotes 8b234b6: Amend documentation for text-quoting-style becoming a user option. |
Date: |
Sat, 30 Sep 2017 08:04:51 -0400 (EDT) |
branch: scratch/customize-quotes
commit 8b234b664e05bd38642831b1296943bde1ad18df
Author: Alan Mackenzie <address@hidden>
Commit: Alan Mackenzie <address@hidden>
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.
---
doc/lispref/control.texi | 14 ++++----------
doc/lispref/display.texi | 16 +++++-----------
doc/lispref/elisp.texi | 1 +
doc/lispref/help.texi | 49 ++++++++++++++++++++++++++++++++++++++++++++++++
doc/lispref/strings.texi | 14 ++++----------
doc/lispref/syntax.texi | 13 +++++++------
etc/NEWS | 6 ++----
7 files changed, 72 insertions(+), 41 deletions(-)
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index c39e035..4eddbe9 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
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.
-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
address@hidden 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
address@hidden"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 62b136f..afd09cf 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
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.
-One way around this problem is to bind @code{text-quoting-style} to
-the symbol @code{grave} around calls to @code{message}; this causes
address@hidden 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
address@hidden"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 4cbcdf8..c752594 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 74dc6da..4aa9b95 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}.
address@hidden 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.
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 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
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 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.
address@hidden 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 10385e0..dd00492 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
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. One way around such problems is to bind
address@hidden to the symbol @code{grave} around calls to
address@hidden; this causes @acronym{ASCII} quoting characters
-to be output unchanged. @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 influence
+or inhibit this translation.
@end defun
@cindex @samp{%} in format
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index e3ae535..b37f2b2 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,
address@hidden 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 755893b..634a360 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1234,10 +1234,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'
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] scratch/customize-quotes 8b234b6: Amend documentation for text-quoting-style becoming a user option.,
Alan Mackenzie <=