From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under "(elisp) Text" Date: Fri, 29 May 2020 22:41:24 +0300 Message-ID: <83mu5qmsuz.fsf@gnu.org> References: <877dwxexsh.fsf@tcd.ie> <83d06osfyw.fsf@gnu.org> <87zh9sfij1.fsf@tcd.ie> <837dwws38a.fsf@gnu.org> <877dwu4mj0.fsf@tcd.ie> Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="4494"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 41571@debbugs.gnu.org To: "Basil L. Contovounesios" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri May 29 21:42:18 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jektW-00010u-9C for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 29 May 2020 21:42:18 +0200 Original-Received: from localhost ([::1]:50766 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jektU-0000qP-Ru for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 29 May 2020 15:42:16 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:35866) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jektG-0000qJ-MT for bug-gnu-emacs@gnu.org; Fri, 29 May 2020 15:42:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:44725) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jektG-0000Gx-Ap for bug-gnu-emacs@gnu.org; Fri, 29 May 2020 15:42:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jektG-0005AP-7n for bug-gnu-emacs@gnu.org; Fri, 29 May 2020 15:42:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 29 May 2020 19:42:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 41571 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 41571-submit@debbugs.gnu.org id=B41571.159078130119834 (code B ref 41571); Fri, 29 May 2020 19:42:02 +0000 Original-Received: (at 41571) by debbugs.gnu.org; 29 May 2020 19:41:41 +0000 Original-Received: from localhost ([127.0.0.1]:56271 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jeksu-00059q-Fc for submit@debbugs.gnu.org; Fri, 29 May 2020 15:41:40 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:56616) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jekss-00059c-Kz for 41571@debbugs.gnu.org; Fri, 29 May 2020 15:41:39 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:46508) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jeksm-0000BT-TQ; Fri, 29 May 2020 15:41:32 -0400 Original-Received: from [176.228.60.248] (port=1396 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jeksk-0001Ei-Ag; Fri, 29 May 2020 15:41:32 -0400 In-Reply-To: <877dwu4mj0.fsf@tcd.ie> (contovob@tcd.ie) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:181203 Archived-At: > From: "Basil L. Contovounesios" > Cc: 41571@debbugs.gnu.org > Date: Fri, 29 May 2020 19:35:31 +0100 > > How's the attached for emacs-27? Thanks, it's much better, but it still "needs work". (Btw, why are you attachments appear before the text? It makes responding harder, because I need to bring the citations to the front.) > +The functions described in this section accept a fixed set of > +specification characters. The next section describes a function > +@code{format-spec} which accepts custom specification characters. This would benefit from making it clear what you mean by "specification characters". An example would clarify that. (It is actually a general comment to your text: you frequently use terms that are left unexplained, which makes the reader stumble and try to understand what you mean. Specific examples below.) > +It is, in some circumstances, useful to allow users to control how The beginning of this sentence is unnecessarily complex. A much simpler variant would be Sometimes it is useful to allow Lisp programs to control... Note that I replaced "users" with "Lisp programs", since we are not talking about Emacs users here. > +A more convenient format string for such cases would be something like > +@code{"%f %l <%e>"}, where each specification character carries more > +semantic information and can easily be rearranged relative to other > +specification characters. The function @code{format-spec} described > +in this section performs a similar function to @code{format}, except > +it operates on format control strings that comprise arbitrary > +specification characters. "comprise" => "include", or even just "use" > +@defun format-spec format specification &optional only-present > +This function returns a string equal to the format control string The "equal" here is confusing, because equality is not really important here, especially since the job of this function is to produce strings that are NOT equal to the original. > +@var{format}, replacing any format specifications it contains with > +values found in the alist @var{specification} (@pxref{Association > +Lists}). > + > +Each key in @var{specification} is a format specification character, > +and its associated value is the string to replace it with. For > +example, an alist entry @code{(?a . "alpha")} means to replace any > +@samp{%a} specifications in @var{format} with @samp{alpha}. You say "key in SPECIFICATION", but SPECIFICATION is an alist, and a key in an alist has well-known meaning. The "key" above should be "association". And in general I'd rearrange the text to make the format of SPECIFICATION more explicit, something like: @defun format-spec template spec-alist &optional only-present This function returns a format string suitable for using in @code{format} and similar functions. The format string is produced from @var{template} according to conversions specified in @var{spec-alist}, which is an alist (@pxref{Association Lists}) of the form @w{@code{(@var{letter} . @var{replacement})}}. Each specification @code{%@var{letter}} in @var{template} will be replaced by @var{replacement} when producing the resulting format string. > +Some useful properties are gained as a result of @var{specification} > +being an alist. The alist may contain more unique keys than there are > +unique specification characters in @var{format}; unused keys are > +simply ignored. If the same key is contained more than once, the > +first one found is used. If @var{format} contains the same format > +specification character more than once, then the same value found in > +@var{specification} is used as a basis for all of that character's > +substitutions. Here you use "key" without first explaining what it is. Also, this paragraph describes several distinct features, so it is better to use an itemized list instead of just one sentence after another: it makes the description easier to grasp by dividing it into distinct smaller chunks. > +The optional argument @var{only-present} indicates how to handle > +format specification characters in @var{format} that are not found in > +@var{specification}. If it is @code{nil} or omitted, an error is > +emitted. Passive tense alert! Suggest to rephrase If it is @code{nil} or omitted, the function signals an error. > +The syntax of format specifications accepted by @code{format-spec} is > +similar, but not identical, to that accepted by @code{format}. In > +both cases, a format specification is a sequence of characters > +beginning with @samp{%} and ending with an alphabetic letter such as > +@samp{s}. The only exception to this is the specification @samp{%%}, > +which is replaced with a single @samp{%}. How is what's described in the last sentence "an exception"? Format strings used by 'format' also behave like that, right? > +Unlike @code{format}, which assigns specific meanings to a fixed set > +of specification characters, @code{format-spec} accepts arbitrary > +specification characters and treats them all equally. For example: > + > +@example > +(format-spec "su - %u %l" > + `((?u . ,(user-login-name)) > + (?l . "ls"))) > + @result{} "su - foo ls" > +@end example This example stops short of explaining why this function is useful: making the replacements fixed strings, as in "ls", is not the reason. OTOH, the use of user-login-name is obfuscated by the backtick notation, which seems to say that some magic is needed here. I think the reason for having this function should be explained better, with more meaningful examples. > +@item 0 > +This flag causes any padding inserted by the width, if specified, to ^^^^^^^^^^^^^^^^^^^^^ Width cannot insert anything, so this should be reworded. Same in a few other items. > +@item < > +This flag causes the substitution to be truncated to the given width, > +if specified, by removing characters from the left. "truncated ... by removing characters" is unnecessarily complicated. Why not say simply "truncated on the left"? > +@item > > +This flag causes the substitution to be truncated to the given width, > +if specified, by removing characters from the right. Same here. > +As is the case with @code{format}, a format specification can include > +a width, which is a decimal number that appears after any flags. If a > +substitution contains fewer characters than its specified width, it is > +extended with padding, normally comprising spaces inserted on the^^^^^ > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > +left: > ^^^^ "it is padded on the left" is simpler and more clear. > +Here is a more complicated example that combines several > +aforementioned features: > + > +@example > +(format-spec "%<06e %<06b" > + '((?b . "beta") > + (?e . "epsilon"))) > + @result{} "psilon 00beta" > +@end example Can we make this example be less trivial? This use case doesn't justify using format-spec at all. Even the subtle point of having the format specs in the order different from the alist is not evident unless you make a point of mentioning it (something that IMO should have been done earlier in the description). Thanks.