Improve documentation of ':lang' in font specs

* src/font.c (Ffont_spec): Doc fix: elaborate on the values and
use of the ':lang' property of the font spec.
* doc/emacs/frames.texi (Fonts): Document the language names that
can be in the STYLE part of XLFD.
* doc/lispref/display.texi (Low-Level Font): Document the ':lang'
property.

3 files changed, 17 insertions, 3 deletions

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index f401c8f645f..de72d87cf48 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -703,7 +703,10 @@ The font width---normally @samp{normal}, @samp{condensed},
 other values.
 @item style
 An optional additional style name.  Usually it is empty---most XLFDs
-have two hyphens in a row at this point.
+have two hyphens in a row at this point.  The style name can also
+specify a two-letter ISO-639 language name, like @samp{ja} or
+@samp{ko}; some fonts that support CJK scripts have that spelled out
+in the style name part.
 @item pixels
 The font height, in pixels.
 @item height
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 357a3c33fa3..b4e20371f35 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3419,6 +3419,15 @@ The charset registry and encoding of the font, such as
 @item :script
 The script that the font must support (a symbol).
 
+@item :lang
+The language that the font should support.  The value should be a
+symbol whose name is a two-letter ISO-639 language name.  On X, the
+value is matched against the ``Additional Style'' field of the XLFD
+name of a font, if it is non-empty.  On MS-Windows, fonts matching the
+spec are required to support codepages needed for the language.
+Currently, only a small set of CJK languages is supported with this
+property: @samp{ja}, @samp{ko}, and @samp{zh}.
+
 @item :otf
 @cindex OpenType font
 The font must be an OpenType font that supports these OpenType
diff --git a/src/font.c b/src/font.c
index 7aa0e8537ce..564c53ae54e 100644
--- a/src/font.c
+++ b/src/font.c
@@ -3857,8 +3857,10 @@ listed in the variable `script-representative-chars'.
 
 `:lang'
 
-VALUE must be a symbol of two-letter ISO-639 language names,
-e.g. `ja'.
+VALUE must be a symbol whose name is a two-letter ISO-639 language
+name, e.g. `ja'.  The value is matched against the "Additional Style"
+field of the XLFD spec of a font, if it's non-empty, on X, and
+against the codepages supported by the font on w32.
 
 `:otf'