2 files changed, 26 insertions, 9 deletions

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index ead2f7a52f6..5c7947eeca6 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -635,6 +635,22 @@ Functions for retrieving the height and/or width of window dividers
 (@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
 described in the corresponding sections.
 
+If your Lisp program needs to make layout decisions, you will find the
+following function useful:
+
+@defun window-max-chars-per-line &optional window face
+This function returns the number of characters displayed in the
+specified @var{face} in the specified @var{window} (which must be a
+live window).  If @var{face} was remapped (@pxref{Face Remapping}),
+the information is returned for the remapped face.  If omitted or
+@code{nil}, @var{face} defaults to the default face, and @var{window}
+defaults to the selected window.  Unlike @code{window-body-width},
+this function accounts for the actual size of the @var{face}'s font,
+instead of working in units of frame's canonical character width.  It
+also accounts for space used by the continuation glyph, if
+@var{window} lacks one or both of its fringes.
+@end defun
+
 @cindex fixed-size window
 @vindex window-min-height
 @vindex window-min-width
diff --git a/etc/NEWS b/etc/NEWS
index 0bde705af8c..ad7d81703e0 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -181,13 +181,6 @@ for use in Emacs bug reports.
 hiding character but the default `.' can be used by let-binding the
 variable `read-hide-char'.
 
-** A new function `window-max-chars-per-line' returns the maximal
-number of characters that can be displayed on one line.  If a face
-and/or window are provided, these values are used for the
-calculation.  This function is different from `window-body-width' in
-that it accounts for (i) continuation glyphs, (ii) the size of the
-font, and (iii) the specified window.
-
 ** New possible value for `system-type': nacl.
 
 ** Emacs can now load shared/dynamic libraries (modules).
@@ -1230,18 +1223,26 @@ In particular, it now returns the average width of the font's
 characters, which can be used for geometry-related calculations.
 
 +++
-**** A new function `default-font-width' returns the average width of a
+*** A new function `default-font-width' returns the average width of a
 character in the current buffer's default font.  If the default face
 is remapped (see `face-remapping-alist'), the value for the remapped
 face is returned.  This function complements the existing function
 `default-font-height'.
 
 +++
-***** New functions `window-font-height' and `window-font-width' return
+*** New functions `window-font-height' and `window-font-width' return
 the height and average width of characters in a specified face and
 window.  If FACE is remapped (see `face-remapping-alist'), the
 function returns the information for the remapped face.
 
++++
+*** A new function `window-max-chars-per-line' returns the maximal
+number of characters that can be displayed on one line.  If a face
+and/or window are provided, these values are used for the
+calculation.  This function is different from `window-body-width' in
+that it accounts for (i) continuation glyphs, (ii) the size of the
+font, and (iii) the specified window.
+
 ---
 ** New utilities in subr-x.el:
 *** New macros `if-let' and `when-let' allow defining bindings and to