bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under "(elisp) Text"

["Basil L. Contovounesios" <contovob@tcd.ie>]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob@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