From 44d6957767f4de200aab437166589652033f42fe Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Thu, 3 Dec 2015 18:03:47 +0200
Subject: [PATCH] Document new font-related functionality

* doc/lispref/display.texi (Low-Level Font): Document
'default-font-width', 'default-font-height', 'window-font-width',
and 'window-font-height'.

* etc/NEWS: Move entries for 'default-font-width',
'default-font-height', 'window-font-width', and 'window-font-height'
to their place and mark them documented.
---
 doc/lispref/display.texi | 33 +++++++++++++++++++++++++++++++++
 etc/NEWS                 | 36 +++++++++++++++++++++---------------
 2 files changed, 54 insertions(+), 15 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 3d520dbdd69..e9354cc2678 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3660,6 +3660,39 @@ tag (or @code{nil}, which stands for the default langsys), and each
 @end table
 @end defun
 
+@cindex font information for layout
+The following four functions return size information about fonts used
+by various faces, allowing various layout considerations in Lisp
+programs.  These functions take face remapping into consideration,
+returning information about the remapped face, if the face in question
+was remapped.  @xref{Face Remapping}.
+
+@defun default-font-width
+This function returns the average width in pixels of the font used by
+the current buffer's default face.
+@end defun
+
+@defun default-font-height
+This function returns the height in pixels of the font used by the
+current buffer's default face.
+@end defun
+
+@defun window-font-width &optional window face
+This function returns the average width in pixels for the font used by
+@var{face} in @var{window}.  The specified @var{window} must be a live
+window.  If @code{nil} or omitted, @var{window} defaults to the
+selected window, and @var{face} defaults to the default face in
+@var{window}.
+@end defun
+
+@defun window-font-height &optional window face
+This function returns the height in pixels for the font used by
+@var{face} in @var{window}.  The specified @var{window} must be a live
+window.  If @code{nil} or omitted, @var{window} defaults to the
+selected window, and @var{face} defaults to the default face in
+@var{window}.
+@end defun
+
 @node Fringes
 @section Fringes
 @cindex fringes
diff --git a/etc/NEWS b/etc/NEWS
index fa43a7f9f6a..0bde705af8c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -181,21 +181,6 @@ for use in Emacs bug reports.
 hiding character but the default `.' can be used by let-binding the
 variable `read-hide-char'.
 
-** The function `font-info' now returns more details about a font.
-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
-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
-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
@@ -1236,6 +1221,27 @@ name.  The variable `system-name' is now obsolete.
 ** If `pwd' is called with a prefix argument, insert the current default
 directory at point.
 
++++
+** New functions return extended information about fonts and faces.
+
++++
+*** The function `font-info' now returns more details about a font.
+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
+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
+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.
+
 ---
 ** New utilities in subr-x.el:
 *** New macros `if-let' and `when-let' allow defining bindings and to
-- 
2.39.5