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: Sun, 31 May 2020 19:03:55 +0300 Message-ID: <831rn0ks5w.fsf@gnu.org> References: <877dwxexsh.fsf@tcd.ie> <83d06osfyw.fsf@gnu.org> <87zh9sfij1.fsf@tcd.ie> <837dwws38a.fsf@gnu.org> <877dwu4mj0.fsf@tcd.ie> <83mu5qmsuz.fsf@gnu.org> <87wo4s8nj5.fsf@tcd.ie> Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="64754"; 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 Sun May 31 18:07:14 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 1jfQUT-000Gi4-Ca for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 31 May 2020 18:07:13 +0200 Original-Received: from localhost ([::1]:33602 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jfQUS-0007Uu-AO for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 31 May 2020 12:07:12 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:52174) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jfQSM-0005fG-Cx for bug-gnu-emacs@gnu.org; Sun, 31 May 2020 12:05:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:50350) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jfQSM-0000aG-04 for bug-gnu-emacs@gnu.org; Sun, 31 May 2020 12:05:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jfQSL-00073p-S3 for bug-gnu-emacs@gnu.org; Sun, 31 May 2020 12:05:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 31 May 2020 16:05:01 +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.159094104627077 (code B ref 41571); Sun, 31 May 2020 16:05:01 +0000 Original-Received: (at 41571) by debbugs.gnu.org; 31 May 2020 16:04:06 +0000 Original-Received: from localhost ([127.0.0.1]:33663 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jfQRS-00072e-2Z for submit@debbugs.gnu.org; Sun, 31 May 2020 12:04:06 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:44598) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jfQRP-00071M-Tj for 41571@debbugs.gnu.org; Sun, 31 May 2020 12:04:04 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:56230) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jfQRJ-0000Ka-Su; Sun, 31 May 2020 12:03:57 -0400 Original-Received: from [176.228.60.248] (port=2003 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jfQRI-0005eO-Bk; Sun, 31 May 2020 12:03:57 -0400 In-Reply-To: <87wo4s8nj5.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:181296 Archived-At: > From: "Basil L. Contovounesios" > Cc: 41571@debbugs.gnu.org > Date: Sun, 31 May 2020 10:24:46 +0100 > > > (Btw, why are you attachments appear before the text? It makes > > responding harder, because I need to bring the citations to the > > front.) > > Sorry, I got into the habit of doing that because I wasn't sure whether > attachments should go before or after the email signature. I'm guessing > after? Yes, after is better if you include text that is worded as a preamble to the patch (which is usually the case). > > @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. > > This wording is much clearer, but the description of the output is > wrong: 'format-spec' and 'format' both produce the same result - a > formatted string, not a format string. Well, that just reflects on how the original text could lead to a grave misunderstanding, doesn't it? ;-) > > Here you use "key" without first explaining what it is. > > I was relying on the preceding xref to the node on alists, which defines > the terms "alist", "key", and "associated value". I don't recommend to rely on that, not in general. Cross-references are there for readers who want to see additional details, but the text should be self-explanatory even if the cross-references are not followed. IOW, the cross-references are optional reading. > > How is what's described in the last sentence "an exception"? Format > > strings used by 'format' also behave like that, right? > > It's an exception to "beginning with % and ending with a letter". Ah! But the text was worded in a way that led me to believe the exception was from the similarity between 'format' and 'format-spec'. > Would it be clearer if I said "the only specification that does not end > in a letter is %%, which is replaced with a single % in the output"? Not sure. Perhaps that sentence should simply be removed, because it looks like the differences between these two APIs are described in the following paragraph. And %% is supported the same by both of them, so mentioning it here is just a distraction. > The main use case for format-spec I've seen is where one part of the > program produces an alist with all the information that could ever be > needed, and another part of the program formats an often > user-customisable format string using this data. > > An example of such a use case is in battery.el, where the alist produced > by battery-status-function is used to format battery-echo-area-format > and battery-mode-line-format (battery.el doesn't currently use > format-spec, but it could and my WIP patch for master changes that). How about saying this in the text? In fact, "user-customizable format string" is never mentioned in the text, it is only hinted upon in the menu entry leading to this node. If the main use case is to let users customize string-valued variables conveniently, that use case should be described and explained in more detail, including why it makes customization more convenient. > How's the new attached version? It is much better, thanks.