master 2fb4108ab7f 2/2: Merge branch 'master' of git.savannah.gnu.org:/srv/git/emacs

[Eli Zaretskii]

branch: master
commit 2fb4108ab7f00084b2dc4c3e527f24ba344bb0fa
Merge: e57b19b4007 9c82f480590
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Merge branch 'master' of git.savannah.gnu.org:/srv/git/emacs
---
 doc/lispref/eval.texi      |  7 ++++--
 doc/lispref/variables.texi | 11 --------
 src/sfnt.c                 | 63 +++++++++++++++++++++++++++++++++++-----------
 3 files changed, 53 insertions(+), 28 deletions(-)

diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index a45517287b7..ea35d4d38c7 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -743,10 +743,13 @@ The argument @var{lexical} specifies the scoping rule for 
local
 variables (@pxref{Variable Scoping}).  If it is omitted or @code{nil},
 that means to evaluate @var{form} using the default dynamic scoping
 rule.  If it is @code{t}, that means to use the lexical scoping rule.
-The value of @var{lexical} can also be a non-empty alist specifying a
+
+The value of @var{lexical} can also be a non-empty list specifying a
 particular @dfn{lexical environment} for lexical bindings; however,
 this feature is only useful for specialized purposes, such as in Emacs
-Lisp debuggers.  @xref{Lexical Binding}.
+Lisp debuggers.  Each member of the list is either a cons cell which
+represents a lexical symbol-value pair, or a symbol representing a
+dynamically bound variable.
 
 Since @code{eval} is a function, the argument expression that appears
 in a call to @code{eval} is evaluated twice: once as preparation before
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index dea35a04d4f..779f6233735 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1186,17 +1186,6 @@ wants the current value of a variable, it looks first in 
the lexical
 environment; if the variable is not specified in there, it looks in
 the symbol's value cell, where the dynamic value is stored.
 
-  (Internally, the lexical environment is a list whose members are
-usually cons cells that are symbol-value pairs, but some of its
-members can be symbols rather than cons cells.  A symbol in the list
-means the lexical environment declared that symbol's variable as
-locally considered to be dynamically bound.  This list can be passed
-as the second argument to the @code{eval} function, in order to
-specify a lexical environment in which to evaluate a form.
-@xref{Eval}.  Most Emacs Lisp programs, however, should not interact
-directly with lexical environments in this way; only specialized
-programs like debuggers.)
-
 @cindex closures, example of using
   Lexical bindings have indefinite extent.  Even after a binding
 construct has finished executing, its lexical environment can be
diff --git a/src/sfnt.c b/src/sfnt.c
index 0648e12150c..348cff604af 100644
--- a/src/sfnt.c
+++ b/src/sfnt.c
@@ -12297,18 +12297,47 @@ sfnt_interpret_compound_glyph (struct sfnt_glyph 
*glyph,
 
 /* Unicode Variation Sequence (UVS) support.
 
-   Unicode defines a mechanism by which a two-codepoint sequence
-   consisting of a ``base character'' and ``variation selector'' is
-   able to produce a glyph that is a variant of the glyph that would
-   conventionally have been mapped to the ``base character''.
-
-   TrueType describes variation selector sequences through a type of
-   character mapping table that is given the format 14.  The character
-   mapping table consists of an array of variation selectors, each of
-   which have a corresponding ``default UVS table'', which describes
-   ranges of ``base characters'' having no special variant glyphs, and
-   a ``non-default UVS table'', which is a map of ``base characters''
-   to their corresponding variant glyphs.  */
+   Unicode defines a mechanism by which two-codepoint sequences
+   comprising a ``base character'' and ``variation selector'' combine
+   to produce a glyph besides that which is mapped to the ``base
+   character'' itself.
+
+   TrueType stores variation selector sequences inside a special type
+   of character mapping table that is given the format 14.  The
+   character mapping table consists of an array of variation
+   selectors, each of which is assigned a ``default UVS table''
+   recording ranges of ``base characters'' absent special variant
+   glyphs, and a ``non-default UVS table'', linking ``base
+   characters'' to their respective variant glyphs.
+
+   Unicode variation selectors occupy the range formed between 0xfe00
+   and 0xfe0f, along with that from 0xe0100 to 0xe01ef, within the
+   Unicode codespace.  When a variation selector is encountered as
+   text is being examined for display with a particular font, that
+   font's character mapping table is indexed by it, yielding a default
+   and non-default UVS table.  If the base character (which is
+   directly behind the variation selector) is subsequently located
+   within the default UVS table, then the glyph represented by this
+   union of base character and variation selector is that designated
+   by the base character within any UCS-4 or BMP character mapping
+   table in the font.  Since this glyph is at variance with that
+   derived from the base character only when the character set of the
+   character mapping table otherwise consulted is not UCS-4 or BMP,
+   the distinction between those two glyphs is largely notional.
+   Should the nondefault UVS table hold the base character, then the
+   glyph is conversely that enumerated in said table, whose indexing
+   is facilitated by sfnt_variation_glyph_for_char.  And if the base
+   character isn't present within either table or the tables for the
+   variation selector are absent in the first place, then the two
+   codepoints constituting the sequence are immiscible and therefore
+   the sequence cannot apply to the font.
+
+   The approach taken by Emacs character composition routines is
+   diametric to the approach illustrated above: in place of searching
+   for variation glyphs each time a variation selector character is
+   encountered, these routines ascertain which glyphs are linked to
+   each base character that they have adjudged subject to variation in
+   advance.  See sfntfont_get_variation_glyphs.  */
 
 /* Read a default UVS table from the font file FD, at the specified
    OFFSET.  Value is the default UVS table upon success, else
@@ -12843,9 +12872,13 @@ sfnt_read_table (int fd, struct sfnt_offset_subtable 
*subtable,
 
 /* Glyph variations.  Instead of defining separate fonts for each
    combination of weight, width and slant (bold, condensed, italic,
-   etc), some fonts specify a list of ``variation axes'', each of
-   which determines one delta to apply to each point in every
-   glyph.
+   etc), some fonts specify a list of ``variation axes'', which are
+   options that accept values consisting of numbers on scales
+   governing deltas applied to select points in their glyphs.
+
+   Particular styles within the font are then supplied as sets of
+   values on these scales to which their respective axes are set,
+   termed ``instances''.
 
    This optional information is specified in the `fvar' (font
    variation), `gvar' (glyph variation) and `cvar' (CVT variation)