6 files changed, 234 insertions, 101 deletions

diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 172809b29d8..2a72276bc56 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -1156,7 +1156,7 @@ in that value.
 
 The usual reason to specify a documentation string for a type is to
 provide more information about the meanings of alternatives inside a
-@code{:choice} type or the parts of some other composite type.
+@code{choice} type or the parts of some other composite type.
 
 @item :help-echo @var{motion-doc}
 @kindex help-echo@r{, customization keyword}
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 3d738b9965f..6fff199485e 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2017,36 +2017,45 @@ it contains.
 
 @defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line
 This function returns the size of the text of @var{window}'s buffer in
-pixels.  @var{window} must be a live window and defaults to the selected
-one.  The return value is a cons of the maximum pixel-width of any text
-line and the maximum pixel-height of all text lines.
-
-The optional argument @var{from}, if non-@code{nil}, specifies the first
-text position to consider and defaults to the minimum accessible
-position of the buffer.  If @var{from} is @code{t}, it uses the minimum
-accessible position that is not a newline character.  The optional
-argument @var{to}, if non-@code{nil}, specifies the last text position
-to consider and defaults to the maximum accessible position of the
-buffer.  If @var{to} is @code{t}, it uses the maximum accessible
-position that is not a newline character.
+pixels.  @var{window} must be a live window and defaults to the
+selected one.  The return value is a cons of the maximum pixel-width
+of any text line and the maximum pixel-height of all text lines.  This
+function exists to allow Lisp programs to adjust the dimensions of
+@var{window} to the buffer text it needs to display.
+
+The optional argument @var{from}, if non-@code{nil}, specifies the
+first text position to consider, and defaults to the minimum
+accessible position of the buffer.  If @var{from} is @code{t}, it
+stands for the minimum accessible position that is not a newline
+character.  The optional argument @var{to}, if non-@code{nil},
+specifies the last text position to consider, and defaults to the
+maximum accessible position of the buffer.  If @var{to} is @code{t},
+it stands for the maximum accessible position that is not a newline
+character.
 
 The optional argument @var{x-limit}, if non-@code{nil}, specifies the
-maximum pixel-width that can be returned.  @var{x-limit} @code{nil} or
-omitted, means to use the pixel-width of @var{window}'s body
-(@pxref{Window Sizes}); this is useful when the caller does not intend
-to change the width of @var{window}.  Otherwise, the caller should
-specify here the maximum width @var{window}'s body may assume.  Text
-whose x-coordinate is beyond @var{x-limit} is ignored.  Since
+maximum X coordinate beyond which text should be ignored; it is
+therefore also the largest value of pixel-width that the function can
+return.  If @var{x-limit} @code{nil} or omitted, it means to use the
+pixel-width of @var{window}'s body (@pxref{Window Sizes}); this
+default means that text of truncated lines wider than the window will
+be ignored.  This default is useful when the caller does not intend to
+change the width of @var{window}.  Otherwise, the caller should
+specify here the maximum width @var{window}'s body may assume; in
+particular, if truncated lines are expected and their text needs to be
+accounted for, @var{x-limit} should be set to a large value.  Since
 calculating the width of long lines can take some time, it's always a
 good idea to make this argument as small as needed; in particular, if
 the buffer might contain long lines that will be truncated anyway.
 
 The optional argument @var{y-limit}, if non-@code{nil}, specifies the
-maximum pixel-height that can be returned.  Text lines whose
-y-coordinate is beyond @var{y-limit} are ignored.  Since calculating the
-pixel-height of a large buffer can take some time, it makes sense to
-specify this argument; in particular, if the caller does not know the
-size of the buffer.
+maximum Y coordinate beyond which text is to be ignored; it is
+therefore also the maximum pixel-height that the function can return.
+If @var{y-limit} is nil or omitted, it means to considers all the
+lines of text till the buffer position specified by @var{to}.  Since
+calculating the pixel-height of a large buffer can take some time, it
+makes sense to specify this argument; in particular, if the caller
+does not know the size of the buffer.
 
 The optional argument @var{mode-and-header-line} @code{nil} or omitted
 means to not include the height of the mode- or header-line of
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 70c3b3cf4be..4a7bda57c4e 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -28,6 +28,7 @@ keyboard character events.
 * 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}.
+* Custom Format Strings::     Formatting custom @code{format} specifications.
 * Case Conversion::           Case conversion functions.
 * Case Tables::               Customizing case conversion.
 @end menu
@@ -1122,6 +1123,181 @@ may be problematic; for example, @samp{%d} and @samp{%g} can mishandle
 NaNs and can lose precision and type, and @samp{#x%x} and @samp{#o%o}
 can mishandle negative integers.  @xref{Input Functions}.
 
+The functions described in this section accept a fixed set of
+specification characters.  The next section describes a function
+@code{format-spec} which can accept custom specification characters,
+such as @samp{%a} or @samp{%z}.
+
+@node Custom Format Strings
+@section Custom Format Strings
+@cindex custom format string
+@cindex custom @samp{%}-sequence in format
+
+Sometimes it is useful to allow users and Lisp programs alike to
+control how certain text is generated via custom format control
+strings.  For example, a format string could control how to display
+someone's forename, surname, and email address.  Using the function
+@code{format} described in the previous section, the format string
+could be something like @w{@code{"%s %s <%s>"}}.  This approach
+quickly becomes impractical, however, as it can be unclear which
+specification character corresponds to which piece of information.
+
+A more convenient format string for such cases would be something like
+@w{@code{"%f %l <%e>"}}, where each specification character carries
+more semantic information and can easily be rearranged relative to
+other specification characters, making such format strings more easily
+customizable by the user.
+
+The function @code{format-spec} described in this section performs a
+similar function to @code{format}, except it operates on format
+control strings that use arbitrary specification characters.
+
+@defun format-spec template spec-alist &optional only-present
+This function returns a string produced from the format string
+@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 formatting the resulting string.
+
+The characters in @var{template}, other than the format
+specifications, are copied directly into the output, including their
+text properties, if any.  Any text properties of the format
+specifications are copied to their replacements.
+
+Using an alist to specify conversions gives rise to some useful
+properties:
+
+@itemize @bullet
+@item
+If @var{spec-alist} contains more unique @var{letter} keys than there
+are unique specification characters in @var{template}, the unused keys
+are simply ignored.
+@item
+If @var{spec-alist} contains more than one association with the same
+@var{letter}, the closest one to the start of the list is used.
+@item
+If @var{template} contains the same specification character more than
+once, then the same @var{replacement} found in @var{spec-alist} is
+used as a basis for all of that character's substitutions.
+@item
+The order of specifications in @var{template} need not correspond to
+the order of associations in @var{spec-alist}.
+@end itemize
+
+The optional argument @var{only-present} indicates how to handle
+specification characters in @var{template} that are not found in
+@var{spec-alist}.  If it is @code{nil} or omitted, the function
+signals an error.  Otherwise, those format specifications and any
+occurrences of @samp{%%} in @var{template} are left verbatim in the
+output, including their text properties, if any.
+@end defun
+
+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}.
+
+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
+@group
+(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)
+     @result{} "emacs 27.1 (x86_64-pc-linux-gnu)"
+
+(format-spec "%n <%a>" my-site-info)
+     @result{} "Emacs Developers <emacs-devel@@gnu.org>"
+@end group
+@end example
+
+A format specification can include any number of the following flag
+characters immediately after the @samp{%} to modify aspects of the
+substitution.
+
+@table @samp
+@item 0
+This flag causes any padding specified by the width to consist of
+@samp{0} characters instead of spaces.
+
+@item -
+This flag causes any padding specified by the width to be inserted on
+the right rather than the left.
+
+@item <
+This flag causes the substitution to be truncated on the left to the
+given width, if specified.
+
+@item >
+This flag causes the substitution to be truncated on the right to the
+given width, if specified.
+
+@item ^
+This flag converts the substituted text to upper case (@pxref{Case
+Conversion}).
+
+@item _
+This flag converts the substituted text to lower case (@pxref{Case
+Conversion}).
+@end table
+
+The result of using contradictory flags (for instance, both upper and
+lower case) is undefined.
+
+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
+padded on the left:
+
+@example
+@group
+(format-spec "%8a is padded on the left with spaces"
+             '((?a . "alpha")))
+     @result{} "   alpha is padded on the left with spaces"
+@end group
+@end example
+
+Here is a more complicated example that combines several
+aforementioned features:
+
+@example
+@group
+(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)
+     @result{} "BAT :  73% (02:23 left)"
+
+(format-spec "%>^-3L : %3p%% (%05t left)"
+             (cons (cons ?L "AC")
+                   my-battery-info))
+     @result{} "AC  :  73% (02:23 left)"
+@end group
+@end example
+
+As the examples in this section illustrate, @code{format-spec} is
+often used for selectively formatting an assortment of different
+pieces of information.  This is useful in programs that provide
+user-customizable format strings, as the user can choose to format
+with a regular syntax and in any desired order only a subset of the
+information that the program makes available.
+
 @node Case Conversion
 @section Case Conversion in Lisp
 @cindex upper case
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 7c4bed04cb5..d765c95f773 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -58,7 +58,6 @@ the character after point.
                        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.
@@ -2029,8 +2028,15 @@ non-@code{nil} value.
 @end enumerate
 
 The argument @var{predicate} is the function to use to compare keys.
-If keys are numbers, it defaults to @code{<}; otherwise it defaults to
-@code{string<}.
+It is called with two arguments, the keys to compare, and should
+return non-@code{nil} if the first key should come before the second
+in the sorting order.  What exactly are the key arguments depends on
+what @var{startkeyfun} and @var{endkeyfun} return.  If @var{predicate}
+is omitted or @code{nil}, it defaults to @code{<} if the keys are
+numbers, to @code{compare-buffer-substrings} if the keys are cons
+cells (whose @code{car} and @code{cdr} are start and end buffer
+positions of the key), and to @code{string<} otherwise (with keys
+assumed to be strings).
 
 As an example of @code{sort-subr}, here is the complete function
 definition for @code{sort-lines}:
@@ -4662,69 +4668,6 @@ If optional argument @var{base64url} is non-@code{nil}, then padding
 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
diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi
index 584b0d7ee50..412176986cc 100644
--- a/doc/misc/ede.texi
+++ b/doc/misc/ede.texi
@@ -955,18 +955,16 @@ The example for Makefiles looks like this:
 ;;; MAKEFILE
 
 (defclass ede-generic-makefile-project (ede-generic-project)
-  ((buildfile :initform "Makefile")
-   )
+  ((buildfile :initform "Makefile"))
   "Generic Project for makefiles.")
 
 (defmethod ede-generic-setup-configuration ((proj ede-generic-makefile-project) config)
-  "Setup a configuration for Make."
+  "Set up a configuration for Make."
   (oset config build-command "make -k")
-  (oset config debug-command "gdb ")
-  )
+  (oset config debug-command "gdb "))
 
 (ede-generic-new-autoloader "generic-makefile" "Make"
-                            "Makefile" 'ede-generic-makefile-project)
+                            "Makefile" 'ede-generic-makefile-project)
 @end example
 
 This example project will detect any directory with the file
diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi
index 6e7d4386bec..8dd394cb848 100644
--- a/doc/misc/eieio.texi
+++ b/doc/misc/eieio.texi
@@ -744,14 +744,21 @@ slot values, and use the previously mentioned set/ref routines.
 @anchor{slot-value}
 This function retrieves the value of @var{slot} from @var{object}.
 Unlike @code{oref}, the symbol for @var{slot} must be quoted.
+
+This is a generalized variable that can be used with @code{setf} to
+modify the value stored in @var{slot}.  @xref{Generalized
+Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
 @end defun
 
 @defun set-slot-value object slot value
 @anchor{set-slot-value}
-This is not a CLOS function, but is the setter for @code{slot-value}
-used by the @code{setf} macro.  This
-function sets the value of @var{slot} from @var{object}.  Unlike
+This function sets the value of @var{slot} from @var{object}.  Unlike
 @code{oset}, the symbol for @var{slot} must be quoted.
+
+This is not a CLOS function, but is the obsolete setter for
+@code{slot-value} used by the @code{setf} macro.  It is therefore
+recommended to use @w{@code{(setf (slot-value @var{object} @var{slot})
+@var{value})}} instead.
 @end defun
 
 @defun slot-makeunbound object slot
@@ -1072,7 +1079,7 @@ Return a string of the form @samp{#<object-class myobjname>} for @var{obj}.
 This should look like Lisp symbols from other parts of Emacs such as
 buffers and processes, and is shorter and cleaner than printing the
 object's record.  It is more useful to use @code{object-print} to get
-and object's print form, as this allows the object to add extra display
+an object's print form, as this allows the object to add extra display
 information into the symbol.
 @end defun
 
@@ -1227,7 +1234,7 @@ objects on top of records, and thus everything is technically visible,
 some functions have been provided.  None of these functions are a part
 of CLOS.
 
-@defun object-slots obj
+@defun eieio-class-slots obj
 Return the list of public slots for @var{obj}.
 @end defun