Merge from origin/emacs-27

35661ef943 (origin/emacs-27) Fix typo in "(elisp) Type Keywords"
1af0e95fec Gnus nnir-summary-line-format has no effect
dd366b5d3b Improve documentation of 'window-text-pixel-size'
fbd49f969e * src/xdisp.c (Fwindow_text_pixel_size): Doc fix.  (Bug#41...
d8593fd19f Minor improvements to EDE and EIEIO manuals
3916e63f9e Have Fido mode also imitate Ido mode in ignore-case options
cc35b197c7 Update package-menu-quick-help
bf09106256 Improve documentation of 'sort-subr'
73749efa13 Update Ukrainian transliteration
30a7ee505a Fix Arabic shaping when eww/shr fill the text to be rendered
7d323f07c0 Silence some byte-compiler warnings in tests
cf473e742f * test/lisp/battery-tests.el: New file.
b07e3b1d97 Improve format-spec documentation (bug#41571)

# Conflicts:
#	test/lisp/emacs-lisp/package-tests.el

1 files changed, 30 insertions, 19 deletions

diff --git a/lisp/format-spec.el b/lisp/format-spec.el
index f418cea4259..9278bd74c42 100644
--- a/lisp/format-spec.el
+++ b/lisp/format-spec.el
@@ -29,35 +29,46 @@
 
 (defun format-spec (format specification &optional only-present)
   "Return a string based on FORMAT and SPECIFICATION.
-FORMAT is a string containing `format'-like specs like \"su - %u %k\",
-while SPECIFICATION is an alist mapping from format spec characters
-to values.
+FORMAT is a string containing `format'-like specs like \"su - %u %k\".
+SPECIFICATION is an alist mapping format specification characters
+to their substitutions.
 
 For instance:
 
   (format-spec \"su - %u %l\"
-               `((?u . ,(user-login-name))
+               \\=`((?u . ,(user-login-name))
                  (?l . \"ls\")))
 
-Each format spec can have modifiers, where \"%<010b\" means \"if
-the expansion is shorter than ten characters, zero-pad it, and if
-it's longer, chop off characters from the left side\".
+Each %-spec may contain optional flag and width modifiers, as
+follows:
 
-The following modifiers are allowed:
+  %<flags><width>character
 
-* 0: Use zero-padding.
-* -: Pad to the right.
-* ^: Upper-case the expansion.
-* _: Lower-case the expansion.
-* <: Limit the length by removing chars from the left.
-* >: Limit the length by removing chars from the right.
+The following flags are allowed:
 
-Any text properties on a %-spec itself are propagated to the text
-that it generates.
+* 0: Pad to the width, if given, with zeros instead of spaces.
+* -: Pad to the width, if given, on the right instead of the left.
+* <: Truncate to the width, if given, on the left.
+* >: Truncate to the width, if given, on the right.
+* ^: Convert to upper case.
+* _: Convert to lower case.
 
-If ONLY-PRESENT, format spec characters not present in
-SPECIFICATION are ignored, and the \"%\" characters are left
-where they are, including \"%%\" strings."
+The width modifier behaves like the corresponding one in `format'
+when applied to %s.
+
+For example, \"%<010b\" means \"substitute into the output the
+value associated with ?b in SPECIFICATION, either padding it with
+leading zeros or truncating leading characters until it's ten
+characters wide\".
+
+Any text properties of FORMAT are copied to the result, with any
+text properties of a %-spec itself copied to its substitution.
+
+ONLY-PRESENT indicates how to handle %-spec characters not
+present in SPECIFICATION.  If it is nil or omitted, emit an
+error; otherwise leave those %-specs and any occurrences of
+\"%%\" in FORMAT verbatim in the result, including their text
+properties, if any."
   (with-temp-buffer
     (insert format)
     (goto-char (point-min))