Improve documentation of 'set-fontset-font'

* doc/lispref/display.texi (Fontsets): Document the value of nil
for the 3rd argument of 'set-fontset-font'.

1 files changed, 9 insertions, 0 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 05bcd9fd297..b12995be6ed 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3304,6 +3304,9 @@ fontset, whose short name is @samp{fontset-default}.
 @var{character} may be a script name.  In that case, use
 @var{font-spec} for all character in the charsets.
 
+@var{font-spec} may be a font-spec object created by the function
+@code{font-spec} (@pxref{Low-Level Font}).
+
 @var{font-spec} may be a cons; @code{(@var{family} . @var{registry})},
 where @var{family} is a family name of a font (possibly including a
 foundry name at the head), @var{registry} is a registry name of a font
@@ -3311,6 +3314,12 @@ foundry name at the head), @var{registry} is a registry name of a font
 
 @var{font-spec} may be a font name string.
 
+@var{font-spec} may be @code{nil}, which explicitly specifies that
+there's no font for the specified @var{character}.  This is useful,
+for example, to avoid expensive system-wide search for fonts for
+characters that have no glyphs, like those from the Unicode Private
+Use Area (PUA).
+
 The optional argument @var{add}, if non-@code{nil}, specifies how to
 add @var{font-spec} to the font specifications previously set.  If it
 is @code{prepend}, @var{font-spec} is prepended.  If it is