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

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

[-- Attachment #1: Type: text/plain, Size: 29 bytes --]

Severity: minor
Tags: patch


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Document-format-spec-under-Strings-and-Characters.patch --]
[-- Type: text/x-diff, Size: 6051 bytes --]

From 9f63db1262683c1b7c58909d04bb2efa4ac2491a Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Thu, 28 May 2020 00:53:42 +0100
Subject: [PATCH] Document format-spec under Strings and Characters

* doc/lispref/text.texi (Interpolated Strings): Move from here...
* doc/lispref/strings.texi (Interpolating Strings): ...to here.
---
 doc/lispref/strings.texi | 62 ++++++++++++++++++++++++++++++++++++++
 doc/lispref/text.texi    | 64 ----------------------------------------
 2 files changed, 62 insertions(+), 64 deletions(-)

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 70c3b3cf4b..e1e40243fb 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -28,6 +28,7 @@ Strings and Characters
 * Text Comparison::           Comparing characters or strings.
 * String Conversion::         Converting to and from characters and strings.
 * Formatting Strings::        @code{format}: Emacs's analogue of @code{printf}.
+* Interpolating Strings::     Formatting customizable strings.
 * Case Conversion::           Case conversion functions.
 * Case Tables::               Customizing case conversion.
 @end menu
@@ -1122,6 +1123,67 @@ Formatting Strings
 NaNs and can lose precision and type, and @samp{#x%x} and @samp{#o%o}
 can mishandle negative integers.  @xref{Input Functions}.
 
+@node Interpolating Strings
+@section Formatting Customizable Strings
+
+It is, in some circumstances, useful to present users with a string to
+be customized that can then be expanded programmatically.  For
+instance, @code{erc-header-line-format} is @code{"%n on %t (%m,%l)
+%o"}, and each of those characters after the percent signs are
+expanded when the header line is computed.  To do this, the
+@code{format-spec} function is used:
+
+@defun format-spec format specification &optional only-present
+@var{format} is the format specification string as in the example
+above.  @var{specification} is an alist that has elements where the
+@code{car} is a character and the @code{cdr} is the substitution.
+
+If @var{only-present} is @code{nil}, errors will be signaled if a
+format character has been used that's not present in
+@var{specification}.  If it's non-@code{nil}, that format
+specification is left verbatim in the result.
+@end defun
+
+Here's a trivial example:
+
+@example
+(format-spec "su - %u %l"
+             `((?u . ,(user-login-name))
+               (?l . "ls")))
+     @result{} "su - foo ls"
+@end example
+
+In addition to allowing padding/limiting to a certain length, the
+following modifiers can be used:
+
+@table @asis
+@item @samp{0}
+Pad with zeros instead of the default spaces.
+
+@item @samp{-}
+Pad to the right.
+
+@item @samp{^}
+Use upper case.
+
+@item @samp{_}
+Use lower case.
+
+@item @samp{<}
+If the length needs to be limited, remove characters from the left.
+
+@item @samp{>}
+Same as previous, but remove characters from the right.
+@end table
+
+If contradictory modifiers are used (for instance, both upper and
+lower case), then what happens is undefined.
+
+As an example, @samp{"%<010b"} means ``insert the @samp{b} expansion,
+but pad with leading zeros if it's less than ten characters, and if
+it's more than ten characters, shorten by removing characters from the
+left.''
+
 @node Case Conversion
 @section Case Conversion in Lisp
 @cindex upper case
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index de436fa9e6..a14867e1d1 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -58,7 +58,6 @@ Text
                        of another buffer.
 * Decompression::    Dealing with compressed data.
 * Base 64::          Conversion to or from base 64 encoding.
-* Interpolated Strings:: Formatting Customizable Strings.
 * Checksum/Hash::    Computing cryptographic hashes.
 * GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS.
 * Parsing HTML/XML:: Parsing HTML and XML.
@@ -4662,69 +4661,6 @@ Base 64
 is optional, and the URL variant of base 64 encoding is used.
 @end defun
 
-
-@node Interpolated Strings
-@section Formatting Customizable Strings
-
-It is, in some circumstances, useful to present users with a string to
-be customized that can then be expanded programmatically.  For
-instance, @code{erc-header-line-format} is @code{"%n on %t (%m,%l)
-%o"}, and each of those characters after the percent signs are
-expanded when the header line is computed.  To do this, the
-@code{format-spec} function is used:
-
-@defun format-spec format specification &optional only-present
-@var{format} is the format specification string as in the example
-above.  @var{specification} is an alist that has elements where the
-@code{car} is a character and the @code{cdr} is the substitution.
-
-If @var{only-present} is @code{nil}, errors will be signaled if a
-format character has been used that's not present in
-@var{specification}.  If it's non-@code{nil}, that format
-specification is left verbatim in the result.
-@end defun
-
-Here's a trivial example:
-
-@example
-(format-spec "su - %u %l"
-             `((?u . ,(user-login-name))
-               (?l . "ls")))
-     @result{} "su - foo ls"
-@end example
-
-In addition to allowing padding/limiting to a certain length, the
-following modifiers can be used:
-
-@table @asis
-@item @samp{0}
-Pad with zeros instead of the default spaces.
-
-@item @samp{-}
-Pad to the right.
-
-@item @samp{^}
-Use upper case.
-
-@item @samp{_}
-Use lower case.
-
-@item @samp{<}
-If the length needs to be limited, remove characters from the left.
-
-@item @samp{>}
-Same as previous, but remove characters from the right.
-@end table
-
-If contradictory modifiers are used (for instance, both upper and
-lower case), then what happens is undefined.
-
-As an example, @samp{"%<010b"} means ``insert the @samp{b} expansion,
-but pad with leading zeros if it's less than ten characters, and if
-it's more than ten characters, shorten by removing characters from the
-left.''
-
-
 @node Checksum/Hash
 @section Checksum/Hash
 @cindex MD5 checksum
-- 
2.26.2


[-- Attachment #3: Type: text/plain, Size: 1014 bytes --]


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