GNU bug report logs - #41571
27.0.91; "(elisp) Interpolated Strings" is under "(elisp) Text"

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 41571 in the body.
You can then email your comments to 41571 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: bug-gnu-emacs <at> gnu.org
Subject: 27.0.91; "(elisp) Interpolated Strings" is under "(elisp) Text"
Date: Thu, 28 May 2020 00:57:34 +0100

[Message part 1 (text/plain, inline)]

Severity: minor
Tags: patch

[0001-Document-format-spec-under-Strings-and-Characters.patch (text/x-diff, attachment)]

[Message part 3 (text/plain, inline)]

The Elisp manual node "(elisp) Interpolated Strings", which documents
the function format-spec and is new in Emacs 27, is currently included
under "(elisp) Text", which opens with:

  This chapter describes the functions that deal with the text in a
  buffer.  Most examine, insert, or delete text in the current buffer,
  often operating at point or on text adjacent to point.  Many are
  interactive.  All the functions that change the text provide for undoing
  the changes (*note Undo).

I think a more appropriate location would be following "(elisp)
Formatting Strings", or at least under "(elisp) Strings and Characters".

Patch for emacs-27 attached.  WDYT?

Thanks,

--
Basil

In GNU Emacs 27.0.91 (build 7, x86_64-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2020-05-27 built on thunk
Repository revision: 9d7fd78421a339f00892b3241845b1024e2eff7d
Repository branch: emacs-27
Windowing system distributor 'The X.Org Foundation', version 11.0.12008000
System Description: Debian GNU/Linux bullseye/sid

Message #8 received at 41571 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 41571 <at> debbugs.gnu.org
Subject: Re: bug#41571: 27.0.91;
 "(elisp) Interpolated Strings" is under "(elisp) Text"
Date: Thu, 28 May 2020 09:58:47 +0300

> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
> Date: Thu, 28 May 2020 00:57:34 +0100
> 
> The Elisp manual node "(elisp) Interpolated Strings", which documents
> the function format-spec and is new in Emacs 27, is currently included
> under "(elisp) Text", which opens with:
> 
>   This chapter describes the functions that deal with the text in a
>   buffer.  Most examine, insert, or delete text in the current buffer,
>   often operating at point or on text adjacent to point.  Many are
>   interactive.  All the functions that change the text provide for undoing
>   the changes (*note Undo).
> 
> I think a more appropriate location would be following "(elisp)
> Formatting Strings", or at least under "(elisp) Strings and Characters".

I agree, but can we please take this opportunity to improve that
section?  First, it uses passive tense too much for no real reason
AFAICT.  More importantly, the description of the feature is not clear
enough.  I had trouble understanding even the "trivial example" it
shows, let alone all the rest.  The very purpose of the feature is not
really obvious after reading the text.

Thanks.

Message #11 received at 41571 <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41571 <at> debbugs.gnu.org
Subject: Re: bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under
 "(elisp) Text"
Date: Thu, 28 May 2020 11:41:54 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
>> Date: Thu, 28 May 2020 00:57:34 +0100
>> 
>> The Elisp manual node "(elisp) Interpolated Strings", which documents
>> the function format-spec and is new in Emacs 27, is currently included
>> under "(elisp) Text", which opens with:
>> 
>>   This chapter describes the functions that deal with the text in a
>>   buffer.  Most examine, insert, or delete text in the current buffer,
>>   often operating at point or on text adjacent to point.  Many are
>>   interactive.  All the functions that change the text provide for undoing
>>   the changes (*note Undo).
>> 
>> I think a more appropriate location would be following "(elisp)
>> Formatting Strings", or at least under "(elisp) Strings and Characters".
>
> I agree, but can we please take this opportunity to improve that
> section?  First, it uses passive tense too much for no real reason
> AFAICT.  More importantly, the description of the feature is not clear
> enough.  I had trouble understanding even the "trivial example" it
> shows, let alone all the rest.  The very purpose of the feature is not
> really obvious after reading the text.

Sure, I'll give it a try, as I was already working on improving the
format-spec implementation and documentation on master.

While I'm at it, may I change the node name?  Interpolating is the same
as formatting in this context, so the difference between the two nodes
is not clear to me.  Perhaps something like:

  * Formatting Custom Strings:: Formatting custom @code{format} specifications.

In fact, couldn't format-spec be documented alongside format and
format-message under "(elisp) Formatting Strings"?  Or does format-spec
need its own node?

Just to recap: format-spec is like format, except it allows custom
%-sequence characters, such as %z, which are substituted in a similar
way to format's %s.  A common use case is to allow users to customise
different output presented to them via custom format control strings.

Thanks,

-- 
Basil

Message #14 received at 41571 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 41571 <at> debbugs.gnu.org
Subject: Re: bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under
 "(elisp) Text"
Date: Thu, 28 May 2020 14:33:57 +0300

> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
> Cc: 41571 <at> debbugs.gnu.org
> Date: Thu, 28 May 2020 11:41:54 +0100
> 
> While I'm at it, may I change the node name?

Sure, the names aren't cast in stone, and the current one doesn't
strike me as especially successful/accurate.

> In fact, couldn't format-spec be documented alongside format and
> format-message under "(elisp) Formatting Strings"?

I thought about that as well when I read your original message, but
concluded that "Formatting Strings" is already too long.  We could
end that node with a sentence referring to the next one, so that
interested readers could continue there right away.  WDYT?

> Just to recap: format-spec is like format, except it allows custom
> %-sequence characters, such as %z, which are substituted in a similar
> way to format's %s.  A common use case is to allow users to customise
> different output presented to them via custom format control strings.

This text is sorely missed at the beginning of the node about
format-spec.

Thanks.

Message #17 received at 41571 <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41571 <at> debbugs.gnu.org
Subject: Re: bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under
 "(elisp) Text"
Date: Fri, 29 May 2020 19:35:31 +0100

[0001-Improve-format-spec-documentation-bug-41571.patch (text/x-diff, attachment)]

[Message part 2 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
>> Cc: 41571 <at> debbugs.gnu.org
>> Date: Thu, 28 May 2020 11:41:54 +0100
>> 
>> While I'm at it, may I change the node name?
>
> Sure, the names aren't cast in stone, and the current one doesn't
> strike me as especially successful/accurate.
>
>> In fact, couldn't format-spec be documented alongside format and
>> format-message under "(elisp) Formatting Strings"?
>
> I thought about that as well when I read your original message, but
> concluded that "Formatting Strings" is already too long.  We could
> end that node with a sentence referring to the next one, so that
> interested readers could continue there right away.  WDYT?

SGTM.

>> Just to recap: format-spec is like format, except it allows custom
>> %-sequence characters, such as %z, which are substituted in a similar
>> way to format's %s.  A common use case is to allow users to customise
>> different output presented to them via custom format control strings.
>
> This text is sorely missed at the beginning of the node about
> format-spec.

How's the attached for emacs-27?

Thanks,

-- 
Basil

Message #20 received at 41571 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 41571 <at> debbugs.gnu.org
Subject: Re: bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under
 "(elisp) Text"
Date: Fri, 29 May 2020 22:41:24 +0300

> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
> Cc: 41571 <at> 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.

Message #23 received at 41571 <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41571 <at> debbugs.gnu.org
Subject: Re: bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under
 "(elisp) Text"
Date: Sun, 31 May 2020 10:24:46 +0100

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
>> Cc: 41571 <at> 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".

Thanks for the very helpful feedback.

> (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?

>> +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.)

I agree that this sentence can be further clarified, but in general I
tried to reuse existing terminology and phrasing to the greatest extent
possible (maybe even too much).

E.g. the preceding paragraphs in "(elisp) Formatting Strings" define and
make extensive use of the terms "format string", "format specification",
"format specification character", as well as the shorter forms
"specification character" and "specification".

>> +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.

Done.

>> +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"

Done.

>> +@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.

I agree; this is just a copy of the corresponding text from "(elisp)
Formatting Strings".

>> +@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".

"Each key in [the alist] is a [...] character" means each key in each
association in the alist is a character, so the wording is not wrong,
just unclear.

> 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.

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.  'format-spec' is an alternative
to 'format', not a precursor.

>> +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.

I was relying on the preceding xref to the node on alists, which defines
the terms "alist", "key", and "associated value".

> 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.

Done, including mentioning that associations can appear in a different
order to their corresponding format specifications in the format string.

>> +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.

Fire extinguished.

>> +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?

It's an exception to "beginning with % and ending with a letter".

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"?

>> +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.

Hm, I'm not sure how to give a better existential justification; this
example just serves as a usage example.

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).

Would replicating such a use case make a better example?  E.g.:

  (setq my-site-info
        (list (cons ?s system-name)
              (cons ?t (symbol-name system-type))
              (cons ?c system-configuration)
              (cons ?v emacs-version)
              (cons ?e invocation-name)
              (cons ?p (number-to-string (emacs-pid)))
              (cons ?a user-mail-address)
              (cons ?n user-full-name)))

  (format-spec "%e %v (%c)" my-site-info)
    => "emacs 28.0.50 (x86_64-pc-linux-gnu)"

  (format-spec "%n <%a>" my-site-info)
    => "Emacs Developers <emacs-devel <at> gnu.org>"

>> +@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.

Most of this phrasing is taken from "(elisp) Formatting Strings".

Is it clear enough to say "...causes any padding specified by the width
to..."?

>> +@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"?

Done.

>> +@item >
>> +This flag causes the substitution to be truncated to the given width,
>> +if specified, by removing characters from the right.
>
> Same here.

Done.

>> +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.

Done.

>> +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.

It's hard coming up with a simple enough example that both justifies
format-spec and showcases modifier combinations.  Would replicating a
subset of the output of battery-status-function be any good?  E.g.:

  (setq my-battery-info
        (list (cons ?p "73")      ; Percentage
              (cons ?L "Battery") ; Status
              (cons ?t "2:23")    ; Remaining time
              (cons ?c "24330")   ; Capacity
              (cons ?r "10.6")))  ; Rate of discharge

  (format-spec "%>^-3L : %3p%% (%05t left)" my-battery-info)
    => "BAT :  73% (02:23 left)"

  (format-spec "%>^-3L : %3p%% (%05t left)"
               (cons (cons ?L "AC")
                     my-battery-info))
    => "AC  :  73% (02:23 left)"

> 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).

Done.

How's the new attached version?

-- 
Basil

[0001-Improve-format-spec-documentation-bug-41571.patch (text/x-diff, attachment)]

Message #26 received at 41571 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 41571 <at> debbugs.gnu.org
Subject: Re: bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under
 "(elisp) Text"
Date: Sun, 31 May 2020 19:03:55 +0300

> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
> Cc: 41571 <at> 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.

Message #29 received at 41571 <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41571 <at> debbugs.gnu.org
Subject: Re: bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under
 "(elisp) Text"
Date: Tue, 02 Jun 2020 15:03:36 +0100

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
>> Cc: 41571 <at> 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).

OK.

>> 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? ;-)

I thought truth is in the eye of the beholder. ;)

>> > 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.

OK.

>> > 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.

Done.

>> 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.

Done.

> 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.

I already tried doing that in the two opening paragraphs, which is why
the original text said something like "allow the user to control..."
rather than "allow Lisp programs to control...".  I've now mentioned
both in the opening and added a new paragraph at the end of the section.

How's the attached?

Thanks,

-- 
Basil

[0001-Improve-format-spec-documentation-bug-41571.patch (text/x-diff, attachment)]

Message #32 received at 41571 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 41571 <at> debbugs.gnu.org
Subject: Re: bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under
 "(elisp) Text"
Date: Tue, 02 Jun 2020 19:56:57 +0300

> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
> Cc: 41571 <at> debbugs.gnu.org
> Date: Tue, 02 Jun 2020 15:03:36 +0100
> 
> > 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.
> 
> I already tried doing that in the two opening paragraphs, which is why
> the original text said something like "allow the user to control..."
> rather than "allow Lisp programs to control...".  I've now mentioned
> both in the opening and added a new paragraph at the end of the section.
> 
> How's the attached?

LGTM, thanks.

Message #39 received at 41571-done <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41571-done <at> debbugs.gnu.org
Subject: Re: bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under
 "(elisp) Text"
Date: Tue, 02 Jun 2020 20:57:55 +0100

tags 41571 fixed
close 41571 27.1
quit

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
>> Cc: 41571 <at> debbugs.gnu.org
>> Date: Tue, 02 Jun 2020 15:03:36 +0100
>>
>> How's the attached?
>
> LGTM, thanks.

Thanks, pushed to emacs-27.

Improve format-spec documentation (bug#41571)
b07e3b1d97 2020-06-02 14:58:25 +0100
https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=b07e3b1d97e73c5cf0cd60edf4838b555530bbf0

-- 
Basil

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.