Subject: bug#4178: 23.1; doc bug, Elisp manual: notion of font family is not explained

From: "Drew Adams" <[email-masked]>
Date: Mon, 17 Aug 2009 10:08:33 -0700

Various parts of the Elisp manual refer to font families, but this
concept is nowhere explained (defined).
 
Using `i' in Info shows, for example, when checking for both `font'
and `family', these index entries:
 
`face-font-family-alternatives' `font-family-list' `x-family-fonts'
 
Look at the indexed doc and you will see that it talks about font
families, without ever saying what a font family is. This makes the
doc incomprehensible. Try to understand the `x-family-fonts'
description, for instance, without knowing what a font family is
(which is my case, FWIW).
 
Substitute `zophlog' for `family', then see if you understand:
 
  Function: x-zophlog-fonts &optional zophlog frame
     This function returns a list describing the available fonts for
     zophlog ZOPHLOG on FRAME.  If ZOPHLOG is omitted or `nil', this list
     applies to all zophlogs, and therefore, it contains all available
     fonts.  Otherwise, ZOPHLOG must be a string; it may contain the
     wildcards `?' and `*'.
 
     The list describes the display that FRAME is on; if FRAME is
     omitted or `nil', it applies to the selected frame's display
     (*note Input Focus::).
 
     Each element in the list is a vector of the following form:
 
          [ZOPHLOG WIDTH POINT-SIZE WEIGHT SLANT
           FIXED-P FULL REGISTRY-AND-ENCODING]
 
     The first five elements correspond to face attributes; if you
     specify these attributes for a face, it will use this font.
 
     The last three elements give additional information about the font.
     FIXED-P is non-`nil' if the font is fixed-pitch.  FULL is the full
     name of the font, and REGISTRY-AND-ENCODING is a string giving the
     registry and encoding of the font.
 
That's as much as I understand - essentially nothing. Please define
and explain the notion `font family'.
 
Elisp manual nodes that use the unexplained notion `font family':
 
Faces
Face Attributes
Font Selection
Font Lookup
Fontsets

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'