Document 'use-default-font-for-symbols' more

"why does my set-fontset-font call not work for symbols" is a common
question, and it's because 'use-default-font-for-symbols' is not
discoverable enough.

* doc/emacs/mule.texi (Modifying Fontsets): Mention it here.
* doc/lispref/display.texi (Fontsets): And here.
* src/fontset.c (Fset_fontset_font): And most importantly here.

3 files changed, 9 insertions, 2 deletions

diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi
index a16a9ea8f71..ab6125f5745 100644
--- a/doc/emacs/mule.texi
+++ b/doc/emacs/mule.texi
@@ -1671,6 +1671,10 @@ used.  Some examples are:
                   nil 'append)
 @end example
 
+When modifying the fontset for the @code{symbol} script, the value of
+@code{use-default-font-for-symbols} will affect whether the fontset is
+actually used.
+
 @noindent
 @xref{Fontsets, , , elisp, GNU Emacs Lisp Reference Manual}, for more
 details about using the @code{set-fontset-font} function.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 011738df268..a9f89406070 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3983,7 +3983,9 @@ that case, use @var{font-spec} for all the characters in the charset.
 
 @var{characters} may be a script symbol (@pxref{Character Properties,
 char-script-table}).  In that case, use @var{font-spec} for all the
-characters belonging to the script.
+characters belonging to the script.  See also
+@code{use-default-font-for-symbols}, which affects font selection
+when @var{fontset} is @code{symbol}.
 
 @var{characters} may be @code{nil}, which means to use @var{font-spec}
 for any character in @var{fontset} for which no font-spec is
diff --git a/src/fontset.c b/src/fontset.c
index a98d75606b3..bac04119957 100644
--- a/src/fontset.c
+++ b/src/fontset.c
@@ -1501,7 +1501,8 @@ CHARACTERS may be a script symbol.  In that case, use FONT-SPEC for
 all the characters that belong to the script.  See the variable
 `script-representative-chars' for the list of known scripts, and
 see the variable `char-script-table' for the script of any specific
-character.
+character.  Note: for the `symbol' script only, whether the FONTSET
+is actually used depends on the value of `use-default-font-for-symbols'.
 
 CHARACTERS may be a charset symbol.  In that case, use FONT-SPEC for
 all the characters in the charset.  See `list-character-sets' and