From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Paul Eggert Newsgroups: gmane.emacs.devel Subject: Re: Emacs 26.1 release branch created Date: Sun, 24 Sep 2017 11:13:06 -0700 Organization: UCLA Computer Science Department Message-ID: References: <83377mls4d.fsf@gnu.org> <20170919173511.GA19168@ACM> <20170921205447.GA8240@ACM> <20170922180440.GA7229@ACM> <5de6367f-49a0-b991-e084-c673d8443fde@cs.ucla.edu> <20170924143341.GB5725@ACM> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------691327C57F3C23AF2713B17F" X-Trace: blaine.gmane.org 1506276807 1698 195.159.176.226 (24 Sep 2017 18:13:27 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 24 Sep 2017 18:13:27 +0000 (UTC) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.3.0 Cc: Eli Zaretskii , Richard Stallman , emacs-devel@gnu.org To: Alan Mackenzie Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Sep 24 20:13:21 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dwBP6-0008Ua-Io for ged-emacs-devel@m.gmane.org; Sun, 24 Sep 2017 20:13:20 +0200 Original-Received: from localhost ([::1]:38988 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dwBPD-0007xI-Uh for ged-emacs-devel@m.gmane.org; Sun, 24 Sep 2017 14:13:27 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34914) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dwBP2-0007vr-2t for emacs-devel@gnu.org; Sun, 24 Sep 2017 14:13:17 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dwBP0-0006v0-1D for emacs-devel@gnu.org; Sun, 24 Sep 2017 14:13:16 -0400 Original-Received: from zimbra.cs.ucla.edu ([131.179.128.68]:32848) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dwBOw-0006tU-1W; Sun, 24 Sep 2017 14:13:10 -0400 Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 535D3160D82; Sun, 24 Sep 2017 11:13:08 -0700 (PDT) Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id zoLTi2nTjm8P; Sun, 24 Sep 2017 11:13:06 -0700 (PDT) Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 82529160E0D; Sun, 24 Sep 2017 11:13:06 -0700 (PDT) X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id sTem-PW-ii7a; Sun, 24 Sep 2017 11:13:06 -0700 (PDT) Original-Received: from [192.168.1.9] (unknown [47.154.18.85]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 531B9160D82; Sun, 24 Sep 2017 11:13:06 -0700 (PDT) In-Reply-To: <20170924143341.GB5725@ACM> Content-Language: en-US X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [fuzzy] X-Received-From: 131.179.128.68 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:218753 Archived-At: This is a multi-part message in MIME format. --------------691327C57F3C23AF2713B17F Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: quoted-printable Alan Mackenzie wrote: > Putting a single output > operation through two `format'-like operations is bizarre and > extravagant. It's not something we should encourage. It's not bizarre; it's routine in Emacs Lisp code. And it's not extravaga= nt: the=20 loss in efficiency for messages is tiny, and is not something users have = noticed=20 or complained about. > By contrast, binding a controlling variable around an operation is the > standard Emacs way of doing such things. It's standard for other things, but it's definitely not standard here. Th= e Emacs=20 source code never does it this way. > How many such instances are there in the code anyway? There are about 400 instances of '(message "%s"' or '(error "%s"' in the = Emacs=20 source code. For decades this has been common practice when an Elisp prog= rammer=20 wants to avoid translation or formatting in the argument to 'message'-lik= e=20 functions. It's not that easy to count how many of the 400 instances are = for=20 quotes as opposed to being for other things, but I'd guess dozens. > This would need fleshing out with something like "To inhibit > or influence this translation of ASCII quotes, see text-quoting-style". Sure, that's easy. Revised proposal attached. > The "boilerplate" you want to replace is short and to the point, It is not short; it's discursive and it gets in the way. In your proposal= , it's=20 about ten lines of boilerplate for each affected function, boilerplate th= at is=20 about as long as the main function description itself. We should move mos= t of=20 this boilerplate to a common section, and briefly allude to it in each af= fected=20 function. This will give us room to expand on the issue in the common sec= tion,=20 which I've done in my proposal - it has about twenty lines discussing the= issue,=20 and this is shorter and provides more useful info than repeating ten line= s in=20 multiple places. > A further general point about this bit of doc is its rather strange use > of the verb "generate". Also easy; the revised proposal (attached) uses "translates to" instead o= f=20 "generates". --------------691327C57F3C23AF2713B17F Content-Type: text/x-patch; name="0001-Improve-text-quoting-style-doc-in-lispref.patch" Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename="0001-Improve-text-quoting-style-doc-in-lispref.patch" =46rom 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}. =20 -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 =E2=80=98foo=E2=80=99"} with matchi= ng curved -quotes. In contrast, a call using a format like @t{"Missing '%s'"} -with only apostrophes typically generates a message like @t{"Missing -=E2=80=99foo=E2=80=99"} with only closing curved quotes, an unusual styl= e in English. +Typically grave accent and apostrophe in the format translate to +matching curved quotes, e.g., @t{"Missing `%s'"} might result in +@t{"Missing =E2=80=98foo=E2=80=99"}. @xref{Text Quoting Style}, for how= to control +this translation. =20 @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}). =20 -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 =E2=80=98foo=E2=80=99"} with matchi= ng curved -quotes. In contrast, a call using a format like @t{"Missing '%s'"} -with only apostrophes typically generates a message like @t{"Missing -=E2=80=99foo=E2=80=99"} with only closing curved quotes, an unusual styl= e in English. +Typically grave accent and apostrophe in the format translate to +matching curved quotes, e.g., @t{"Missing `%s'"} might result in +@t{"Missing =E2=80=98foo=E2=80=99"}. @xref{Text Quoting Style}, for how= to control +this translation. =20 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 it= s 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 =20 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 message= s. * Describing Characters:: Making printable descriptions of non-printing characters and key sequence= s. * 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}. +@xref{Text Quoting Style}. =20 @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. =20 -@defvar 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{=E2=80=98like this=E2=80=99} 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 - @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. =20 +@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 +=E2=80=98foo=E2=80=99."}. Less commonly, Emacs displays grave accents a= nd 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 =E2=80=99foo=E2=80=99."}, an un= usual 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{"\\=3D`(a ,(sin 0)) =3D=3D> (a 0.0)"} the gr= ave +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)) =3D=3D> (a %S)" x (sin x)))}= +displays a message that starts with grave accent regardless of text +quoting style. + +@defvar 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{=E2=80=98like this= =E2=80=99} +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 + @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 -@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{=E2=80=98like this=E2=80=99}= =2E In -contrast, a format that quotes with only apostrophes @t{'like this'} -typically generates two closing curved quotes @t{=E2=80=99like this=E2=80= =99}, an -unusual style in English. @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 =E2=80=98foo=E2=80=99"}. @xref{Text Quoting Style}, for how= to control +this translation. @end defun =20 @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}. =20 @cindex hyperlinks in documentation strings Help mode automatically creates a hyperlink when a documentation string --=20 2.13.5 --------------691327C57F3C23AF2713B17F--