fontspec v2 (8jun10)

git-svn-id: svn://tug.org/texlive/trunk@18825 c570f23f-e606-0410-a88d-b1316a301751
author: Karl Berry <karl@freefriends.org> 2010-06-09 00:22:21 +0000
committer: Karl Berry <karl@freefriends.org> 2010-06-09 00:22:21 +0000
commit: e75495f92d91038a568dec3fd1cc854d51daf4c7 (patch)
tree: 99417371e2a2c104d8082b24e8f1a0faef2be81e /Master/texmf-dist
parent: aac86e6df7bc5de903798b0c8a7f6b49cf4e9b75 (diff)
23 files changed, 1450 insertions, 820 deletions
diff --git a/Master/texmf-dist/doc/latex/fontspec/README b/Master/texmf-dist/doc/latex/fontspec/README
index 879e4453aff..c0b2f8226f5 100644
--- a/Master/texmf-dist/doc/latex/fontspec/README
+++ b/Master/texmf-dist/doc/latex/fontspec/README
@@ -1,6 +1,6 @@
 
-THE FONTSPEC PACKAGE v2.0b2
-===========================
+THE FONTSPEC PACKAGE v2.0
+=========================
 
 This is the initial release of the fontspec package with support for LuaTeX.
 (Previously, fontspec was XeTeX-only.)
@@ -17,15 +17,15 @@ others.
 
 Release versions of fontspec are available from CTAN:
 
-  http://tug.ctan.org/pkg/fontspec
+  <http://tug.ctan.org/pkg/fontspec>
   
 Development and historical versions are available from Github:
 
-  http://github.com/wspr/fontspec
+  <http://github.com/wspr/fontspec>
   
 Please offer suggestions and file bug reports in the issue tracker:
 
-  http://github.com/wspr/fontspec/issues
+  <http://github.com/wspr/fontspec/issues>
 
 
 LuaTeX requirements
@@ -34,7 +34,7 @@ LuaTeX requirements
 TeXLive 2010 is recommended for running this package under LuaTeX.
 
 This package requires the luaotfload package in order to load fonts in LuaTeX.
-Version 1.08 or greater is recommended for this release. Please see
+Version 1.10 or greater is recommended for this release. Please see
 instructions in that package for font setup. That package, in turn, requires
 a version of LuaTeX greater than that shipped with TeX Live 2009.
 
@@ -130,6 +130,18 @@ local texmf tree. Depending how your TeX distribution is configured
 you may then need to update the filename database with `texhash`.
 
 
+Test suite
+----------
+
+Towards the end of the development process of version 2, we started
+to add a test suite to ensure stability with any future changes. The
+output of each test is included in the distributed documentation file
+`fontspec-testsuite.pdf`.
+
+There aren't many tests yet, but we'll slowly add to them in time.
+If you would like to help put some tests together, contributions are
+gladly accepted!
+
 
 Manifest
 --------
@@ -142,10 +154,18 @@ Derived files:
         fontspec.pdf               documentation
         fontspec.sty               LaTeX style file
         fontspec.lua               Lua functions for LuaTeX
+        fontspec-patches.sty       redefinitions of various LaTeX internals
         fontspec.cfg               default configuration file
         fontspec-xetex.tex         example file for XeTeX
         fontspec-luatex.tex        example file for LuaTeX
-
+        fontspec-testsuite.tex     test suite documentation file
+
+Test suite: (within testsuite/)
+        testsuite.cls              class file for each test
+        testsuite-listing.tex      listing of each test in the suite
+        L*.ltx                     LuaLaTeX test file
+        X*.ltx                     XeLaTeX test file
+        F*.ltx                     Test file for both engines
 
 
 License
diff --git a/Master/texmf-dist/doc/latex/fontspec/fontspec-luatex.tex b/Master/texmf-dist/doc/latex/fontspec/fontspec-luatex.tex
index 1c8f3dcd63a..2ad2f115021 100644
--- a/Master/texmf-dist/doc/latex/fontspec/fontspec-luatex.tex
+++ b/Master/texmf-dist/doc/latex/fontspec/fontspec-luatex.tex
@@ -1,3 +1,5 @@
+
+
 % !TEX TS-program = LuaLaTeX
 
 \documentclass{article}
diff --git a/Master/texmf-dist/doc/latex/fontspec/fontspec-testsuite.pdf b/Master/texmf-dist/doc/latex/fontspec/fontspec-testsuite.pdf
new file mode 100644
index 00000000000..080a62ee33b
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/fontspec/fontspec-testsuite.pdf
diff --git a/Master/texmf-dist/doc/latex/fontspec/fontspec-xetex.tex b/Master/texmf-dist/doc/latex/fontspec/fontspec-xetex.tex
index 9bec0583744..3ad8bd736a8 100644
--- a/Master/texmf-dist/doc/latex/fontspec/fontspec-xetex.tex
+++ b/Master/texmf-dist/doc/latex/fontspec/fontspec-xetex.tex
@@ -1,3 +1,5 @@
+
+
 % !TEX TS-program = XeLaTeX
 
 \documentclass{article}
diff --git a/Master/texmf-dist/doc/latex/fontspec/fontspec.pdf b/Master/texmf-dist/doc/latex/fontspec/fontspec.pdf
index 6e05245594f..e1b4623bace 100644
--- a/Master/texmf-dist/doc/latex/fontspec/fontspec.pdf
+++ b/Master/texmf-dist/doc/latex/fontspec/fontspec.pdf
diff --git a/Master/texmf-dist/source/latex/fontspec/Makefile b/Master/texmf-dist/source/latex/fontspec/Makefile
index 69be2e2721d..4d260dba41e 100644
--- a/Master/texmf-dist/source/latex/fontspec/Makefile
+++ b/Master/texmf-dist/source/latex/fontspec/Makefile
@@ -1,20 +1,55 @@
 # Makefile for fontspec.
 
+#### MAKEFILE CONFIG ####
+
+SHELL = /bin/sh
+.SUFFIXES:
+
+#### BEGIN ####
+
+help:
+	echo 'FONTSPEC makefile targets:'
+	echo ' '
+	echo '                  help  -  (this message)'
+	echo '                unpack  -  extracts all files'
+	echo '                   doc  -  compile documentation'
+	echo '                gendoc  -  compile documentation including external examples'
+	echo '                  ctan  -  generate archive for CTAN'
+	echo '                   all  -  unpack & doc'
+	echo '                 world  -  all & ctan'
+	echo '                 clean  -  remove all generated and built files'
+	echo ' '
+	echo '                   install  -  install the package into your home texmf tree'
+	echo ' install TEXMFROOT=<texmf>  -  install the package into the path <texmf>'
+	echo ' '
+	echo '                 check  -  run the test suite'
+	echo '               initest  -  initialise any new tests'
+	echo '            <testname>  -  run only this test'
+	echo ' '
+	echo 'I recommend `make -j4 check` or thereabouts to parallelise'
+	echo 'the testing.'
+
+
 NAME = fontspec
 DOC = $(NAME).pdf
 DTX = $(NAME).dtx
 
 # Files grouped by generation mode
-COMPILED = $(DOC)
-UNPACKED = fontspec.sty fontspec-patches.sty fontspec.lua fontspec.cfg fontspec-luatex.tex fontspec-xetex.tex
+COMPILED = $(DOC) fontspec-testsuite.pdf
+EXAMPLES = fontspec-luatex.tex fontspec-xetex.tex
+UNPACKED = fontspec.sty fontspec-patches.sty fontspec.lua fontspec.cfg $(EXAMPLES)
 SOURCE = $(DTX) Makefile README
 GENERATED = $(COMPILED) $(UNPACKED)
 
+TESTS = $(shell ls testsuite/*.cls testsuite/*.tex testsuite/*.ltx)
+
+CTAN_FILES = $(SOURCE) $(COMPILED) $(EXAMPLES) $(TESTS)
+
 # Files grouped by installation location
 UNPACKED_DOC = fontspec-luatex.tex fontspec-xetex.tex
 
 RUNFILES = $(filter-out $(UNPACKED_DOC), $(UNPACKED))
-DOCFILES = $(DOC) README $(UNPACKED_DOC)
+DOCFILES = $(COMPILED) README $(UNPACKED_DOC)
 SRCFILES = $(DTX) Makefile
 
 ALL_FILES = $(RUNFILES) $(DOCFILES) $(SRCFILES)
@@ -31,26 +66,30 @@ TDS_ZIP = $(NAME).tds.zip
 ZIPS = $(CTAN_ZIP) $(TDS_ZIP)
 
 DO_PDFLATEX = pdflatex --interaction=batchmode $< >/dev/null
+DO_PDFLATEX_WRITE18 = pdflatex --shell-escape --interaction=batchmode $< >/dev/null
 DO_TEX = tex --interaction=batchmode $< >/dev/null
 DO_MAKEINDEX = makeindex -s gind.ist $(subst .dtx,,$<) >/dev/null 2>&1
 
 all: $(GENERATED)
 doc: $(COMPILED)
 unpack: $(UNPACKED)
-ctan: $(CTAN_ZIP)
+ctan: check $(CTAN_ZIP)
 tds: $(TDS_ZIP)
 world: all ctan
 
-$(COMPILED): $(DTX)
+gendoc: $(DTX)
+	$(DO_PDFLATEX_WRITE18)
+
+$(DOC): $(DTX)
 	$(DO_PDFLATEX)
 	$(DO_MAKEINDEX)
 	$(DO_PDFLATEX)
 	$(DO_PDFLATEX)
 
 $(UNPACKED): $(DTX)
-	$(DO_TEX)
+	@$(DO_TEX)
 
-$(CTAN_ZIP): $(SOURCE) $(COMPILED) $(TDS_ZIP)
+$(CTAN_ZIP): $(CTAN_FILES) $(TDS_ZIP)
 	@echo "Making $@ for CTAN upload."
 	@$(RM) -- $@
 	@zip -9 $@ $^ >/dev/null
@@ -59,6 +98,7 @@ define run-install
 @mkdir -p $(RUNDIR) && cp $(RUNFILES) $(RUNDIR)
 @mkdir -p $(DOCDIR) && cp $(DOCFILES) $(DOCDIR)
 @mkdir -p $(SRCDIR) && cp $(SRCFILES) $(SRCDIR)
+@mkdir -p $(SRCDIR)/testsuite/ && cp $(TESTS) $(SRCDIR)/testsuite/
 endef
 
 $(TDS_ZIP): TEXMFROOT=./tmp-texmf
@@ -73,6 +113,12 @@ $(TDS_ZIP): $(ALL_FILES)
 README: README.markdown
 	cp $< $@
 
+# lazy:
+fontspec-testsuite.pdf: $(DTX) check
+	@echo 'Compiling test suite.'
+	$(DO_PDFLATEX)
+	xelatex --interaction=batchmode fontspec-testsuite.tex
+
 .PHONY: install manifest clean mrproper
 
 install: $(ALL_FILES)
@@ -95,3 +141,163 @@ clean:
 	@$(RM) -- $(GENERATED) $(ZIPS)
 
 
+#############
+# TESTSUITE #
+#############
+
+#### Needed to compile and make stuff ####
+
+builddir=build
+testdir=testsuite
+lprefix=L
+xprefix=X
+both=F
+
+COPY = cp -a
+MOVE = mv -f
+COMPARE_OPTS = -density 300x300 -metric ae -fuzz 35%
+
+LTXSOURCE = $(NAME).sty $(NAME).cfg $(NAME)-patches.sty
+
+TESTLIST = testsuite-listing.tex
+
+SUITESOURCE = \
+  $(testdir)/testsuite.cls \
+  $(testdir)/$(TESTLIST)
+
+TESTOUT = $(shell ls $(testdir)/*.safe.pdf)
+BUILDTESTSRC = $(subst $(testdir)/,$(builddir)/,$(subst .safe.pdf,.ltx,$(TESTOUT)))
+BUILDTESTTARGET = $(subst $(testdir)/,$(builddir)/,$(subst .safe.pdf,.diff.pdf,$(TESTOUT)))
+
+BUILDSOURCE = $(addprefix $(builddir)/,$(LTXSOURCE))
+BUILDSUITE  = $(subst $(testdir)/,$(builddir)/,$(SUITESOURCE))
+BUILDFILES  = $(BUILDSOURCE) $(BUILDSUITE) $(BUILDTESTSRC)
+
+#### All tests ####
+
+check: $(TESTLIST)
+
+$(TESTLIST): $(BUILDFILES) $(BUILDTESTTARGET)
+	@cd $(testdir); \
+	ls *.ltx | sed -e 's/\(.*\).ltx/\\TEST{\1}/g' > $(TESTLIST)
+
+$(builddir)/%: $(testdir)/%
+	@mkdir -p $(builddir); \
+	$(COPY) $< $@
+
+$(builddir)/%: %
+	@mkdir -p $(builddir); \
+	$(COPY) -f $< $@
+
+
+#### Generating new tests ####
+
+lonelystub = $(shell cd $(testdir); ls | egrep '($(xprefix)|$(lprefix))(.*\.ltx)|(.*\.safe.pdf)' | cut -d . -f 1 | uniq -u)
+lonelyfile = $(addsuffix .safe.pdf,$(lonelystub))
+lonelypath = $(addprefix $(testdir)/,$(lonelyfile))
+lonelytest = $(addprefix $(builddir)/,$(addsuffix .pdf,$(lonelystub)))
+
+bothlonelystub = $(shell cd $(testdir); ls | egrep '($(both).*\.ltx)|($(both).*\.safe.pdf)' | cut -d . -f 1 | uniq -u)
+bothlonelyfile = $(addsuffix .safe.pdf,$(bothlonelystub))
+bothlonelypath = $(addprefix $(testdir)/,$(bothlonelyfile))
+bothlonelytest = $(addprefix $(builddir)/,$(addsuffix .pdf,$(bothlonelystub)))
+
+initest: $(lonelypath) $(bothlonelypath)
+
+$(lonelypath): $(lonelytest)
+	@$(COPY)  `echo $@ | sed -e s/$(testdir)/$(builddir)/ -e s/.safe.pdf/.pdf/`  $@
+
+$(bothlonelypath): $(bothlonelytest)
+	@$(COPY)  `echo $@ | sed -e s/$(testdir)/$(builddir)/ -e s/.safe.pdf/.pdf/`  $@
+
+#### REFERENCE OUTPUT GENERATION ####
+
+$(builddir)/$(both)%.gendiff.pdf: $(builddir)/$(both)%-$(lprefix).pdf $(builddir)/$(both)%-$(xprefix).pdf
+	@echo '$(both)$*: Comparing PDF from LuaLaTeX with PDF from XeLaTeX.'
+	@if test $(shell compare \
+	                $(COMPARE_OPTS) \
+	                $(builddir)/$(both)$*-$(lprefix).pdf \
+	                $(builddir)/$(both)$*-$(xprefix).pdf \
+	                $(builddir)/$(both)$*.gendiff.pdf 2>&1) -lt 1 ; then \
+	  echo '$(both)$*: Test generation successed.' ; \
+	else \
+	  echo '$(both)$*: Test generation failed; XeLaTeX and LuaLaTeX gave different output.' ; \
+	  false ; \
+	fi
+
+$(builddir)/$(both)%.pdf: $(builddir)/$(both)%.gendiff.pdf
+	  $(MOVE) $(builddir)/$(both)$*-$(xprefix).pdf $(builddir)/$(both)$*.pdf
+
+#### TESTS FOR BOTH ENGINES ####
+
+$(builddir)/$(both)%.diff.pdf: $(builddir)/$(both)%-$(lprefix).pdf $(builddir)/$(both)%-$(xprefix).pdf
+	@echo '$(both)$*: Comparing PDF from LuaLaTeX against reference output.'
+	@if test $(shell compare \
+	                $(COMPARE_OPTS) \
+	                $(builddir)/$(both)$*-$(lprefix).pdf \
+	                $(testdir)/$(both)$*.safe.pdf \
+	                $(builddir)/$(both)$*.diff.pdf 2>&1) -le 1 ; then \
+	  echo '$(both)$*: Test passed.' ; \
+	else \
+	  echo '$(both)$*: Test failed.' ; \
+	  false ; \
+	fi
+	@echo '$(both)$*: Comparing PDF from XeLaTeX against reference output.'
+	@if test $(shell compare \
+	                $(COMPARE_OPTS) \
+	                $(builddir)/$(both)$*-$(xprefix).pdf \
+	                $(testdir)/$(both)$*.safe.pdf \
+	                $(builddir)/$(both)$*.diff.pdf 2>&1) -le 1 ; then \
+	  echo '$(both)$*: Test passed.' ; \
+	else \
+	  echo '$(both)$*: Test failed.' ; \
+	  false ; \
+	fi
+
+$(builddir)/$(both)%-$(lprefix).pdf: $(BUILDSOURCE) $(BUILDSUITE) $(builddir)/$(both)%.ltx
+	@echo '$(both)$*: Generating PDF output with LuaLaTeX.'
+	@cd $(builddir); lualatex -jobname=$(both)$*-$(lprefix) -interaction=batchmode $(both)$*.ltx > /dev/null
+
+$(builddir)/$(both)%-$(xprefix).pdf: $(BUILDSOURCE) $(BUILDSUITE) $(builddir)/$(both)%.ltx
+	@echo '$(both)$*: Generating PDF output with XeLaTeX.'
+	@cd $(builddir); xelatex -jobname=$(both)$*-$(xprefix) -interaction=batchmode $(both)$*.ltx > /dev/null
+
+
+#### TEST FOR EACH ENGINE INDIVIDUALLY ####
+
+$(builddir)/$(lprefix)%.diff.pdf: $(builddir)/$(lprefix)%.pdf
+	@echo '$(lprefix)$*: Comparing PDF against reference output.'
+	@if test $(shell compare $(COMPARE_OPTS) \
+	          $(builddir)/$(lprefix)$*.pdf $(testdir)/$(lprefix)$*.safe.pdf \
+	          $(builddir)/$(lprefix)$*.diff.pdf 2>&1) -le 1 ; then \
+	  echo '$(lprefix)$*: Test passed.' ; \
+	else \
+	  echo '$(lprefix)$*: Test failed.' ; \
+	  false ; \
+	fi
+
+$(builddir)/$(xprefix)%.diff.pdf: $(builddir)/$(xprefix)%.pdf
+	@echo '$(xprefix)$*: Comparing PDF against reference output.'
+	@if test $(shell compare \
+	                $(COMPARE_OPTS) \
+	                $(builddir)/$(xprefix)$*.pdf \
+	                $(testdir)/$(xprefix)$*.safe.pdf \
+	                $(builddir)/$(xprefix)$*.diff.pdf 2>&1) -le 1 ; then \
+	  echo '$(xprefix)$*: Test passed.' ; \
+	else \
+	  echo '$(xprefix)$*: Test failed.' ; \
+	  false ; \
+	fi
+
+$(builddir)/$(xprefix)%.pdf: $(BUILDSOURCE) $(BUILDSUITE) $(builddir)/$(xprefix)%.ltx
+	@echo '$(xprefix)$*: Generating PDF output with XeLaTeX.'
+	@cd $(builddir); xelatex -interaction=batchmode $(xprefix)$*.ltx > /dev/null
+
+$(builddir)/$(lprefix)%.pdf: $(BUILDSOURCE) $(BUILDSUITE) $(builddir)/$(lprefix)%.ltx
+	@echo '$(lprefix)$*: Generating PDF output with LuaLaTeX.'
+	@cd $(builddir); lualatex -interaction=batchmode $(lprefix)$*.ltx > /dev/null
+
+#### HACK: allow `make <foobar>` run that test.
+
+%: build/%.ltx
+	make build/$*.diff.pdf
+\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/fontspec/fontspec.dtx b/Master/texmf-dist/source/latex/fontspec/fontspec.dtx
index fe714c0e29d..d0c26505930 100644
--- a/Master/texmf-dist/source/latex/fontspec/fontspec.dtx
+++ b/Master/texmf-dist/source/latex/fontspec/fontspec.dtx
@@ -48,6 +48,7 @@ This work consists of this file fontspec.dtx
 \generate{\file{fontspec.cfg}          {\from{fontspec.dtx}{cfg}}}
 \generate{\file{fontspec-xetex.tex}    {\from{fontspec.dtx}{example,xetex}}}
 \generate{\file{fontspec-luatex.tex}   {\from{fontspec.dtx}{example,luatex}}}
+\generate{\file{fontspec-testsuite.tex}{\from{fontspec.dtx}{testsuite}}}
 
 \def\tmpa{plain}
 \ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
@@ -62,7 +63,7 @@ This work consists of this file fontspec.dtx
 %<fontspec>\ProvidesPackage{fontspec}
 %<patches>\ProvidesPackage{fontspec-patches}
 %<*fontspec|patches>
-  [2010/06/03 v2.0b2 Advanced font selection for XeLaTeX/LuaLaTeX]
+  [2010/06/08 v2.0 Advanced font selection for XeLaTeX/LuaLaTeX]
 %</fontspec|patches>
 %
 %<*driver>
@@ -94,12 +95,12 @@ This work consists of this file fontspec.dtx
 %
 % This package began life as a \LaTeX\ interface to select system-installed
 % \MacOSX\ fonts in \name{Jonathan Kew}'s \XeTeX, the first widely-used
-% unicode extension to \TeX. Over time, \XeTeX\ was extended to support OpenType
+% Unicode extension to \TeX. Over time, \XeTeX\ was extended to support OpenType
 % fonts and then was ported into a cross-platform program to run also on Windows
 % and Linux.
 %
 % More recently, \LuaTeX\ is fast becoming the \TeX\ engine of the day; it
-% supports unicode encodings and OpenType fonts and opens up the internals of
+% supports Unicode encodings and OpenType fonts and opens up the internals of
 % \TeX\ via the Lua programming language. Hans Hagen's Con\TeX t Mk.\,IV is a
 % re-write of his powerful typesetting system, taking full advantage of
 % \LuaTeX's features including font support; a kernel of his work in this area
@@ -133,10 +134,19 @@ This work consists of this file fontspec.dtx
 %
 % \subsection{About this manual}
 %
-% As of version 2.0 with the addition of \LuaTeX\ support, this manual
+% This manual for version 2 of fontspec
 % is still in the process of being re-written.
-% It currently contains no typeset examples.
-% Your patience and feedback is appreciated!
+% If you see any typeset examples that are broken, please let me know!
+% I've managed to go over a lot of them but some have been brought over
+% from the old version without being proofed.
+%
+% I'd also like to reduce the number of non-free fonts used in these
+% examples. If you know any freely available fonts that could be used
+% as alternative to any of the fonts in this document, please suggest them
+% to me.
+% Finally, if any aspect of the documentation is unclear or you would
+% like to suggest more examples that could be made, get in touch.
+% (Contributions especially welcome.)
 %
 % \section{Package loading and options}
 %
@@ -145,19 +155,11 @@ This work consists of this file fontspec.dtx
 %   \usepackage{fontspec}
 % \end{Verbatim}
 %
-% In brief, \pkg{fontspec}'s package options are
-% \begin{description}[nolistsep,font=\ttfamily]
-% \item [no-math] Don't change any maths fonts;
-% \item [no-config] Don't load \pkg{fontspec.cfg}; and,
-% \item [quiet] Output \pkg{fontspec} warnings in the log file rather than the console output.
-% \end{description}
-% These are described in more detail below.
-%
 % \paragraph{\XeTeX\ users only}
-% \name{Ross Moore}'s \pkg{xunicode} package is recommended for
+% Ross Moore's \pkg{xunicode} package is recommended for
 % providing backwards compatibility with \LaTeX's methods for accessing extra
 % characters and accents (for example, |\%|, |\$|, |\textbullet|, |\"u|, and
-% so on), plus many more unicode characters. The \pkg{xltxtra} package adds a
+% so on), plus many more Unicode characters. The \pkg{xltxtra} package adds a
 % couple of general improvements to \LaTeX\ under \XeTeX; it also provides the
 % \cmd\XeTeX\ macro to typeset the \XeTeX\ logo.
 %
@@ -165,7 +167,7 @@ This work consists of this file fontspec.dtx
 % In order to load fonts by their name rather than by their filename (\eg, `Latin Modern Roman' instead of `ec-lmr10'), you may need to run the script \texttt{mkluatexfontdb}, which is distributed with the \pkg{luaotfload} package. Note that if you do not execute this script beforehand, the first time you attempt to typeset the process will pause for (up to) several minutes. (But only the first time.)
 % Please see the \pkg{luaotfload} documentation for more information.
 % Note that the \pkg{xunicode} package is not required as it has been
-% incorporated directly into the unicode font definitions (see the \pkg{euenc} package for more information).
+% incorporated directly into the Unicode font definitions (see the \pkg{euenc} package for more information).
 %
 % \paragraph{\pkg{babel}}
 % \emph{The \pkg{babel} package is not really supported!} Especially Vietnamese,
@@ -182,7 +184,7 @@ This work consists of this file fontspec.dtx
 % By default, \pkg{fontspec} adjusts \LaTeX's
 % default maths setup in order to maintain the correct Computer Modern symbols
 % when the roman font changes. However, it will attempt to avoid doing this if
-% another maths font package is loaded (such as \pkg{mathpazo} or my upcoming
+% another maths font package is loaded (such as \pkg{mathpazo} or the
 % \pkg{unicode-math} package).
 %
 % If you find that it is incorrectly changing the maths font when it should be
@@ -212,17 +214,16 @@ This work consists of this file fontspec.dtx
 %
 %
 %
-% \clearpage
 % \part{General font selection}
 %
 % This section concerns the variety of commands that can be used to select
 % fonts.
 %
 % \cmdbox{%
-%   \CMD{~~~~~\string\fontspec} \oarg{font features} \marg{font name}\\
-%   \CMD{~~\string\setmainfont} \oarg{font features} \marg{font name}\\
-%   \CMD{~~\string\setsansfont} \oarg{font features} \marg{font name}\\
-%   \CMD{~~\string\setmonofont} \oarg{font features} \marg{font name}\\
+%   \CMD{\string\fontspec} \oarg{font features} \marg{font name}\\
+%   \CMD{\string\setmainfont} \oarg{font features} \marg{font name}\\
+%   \CMD{\string\setsansfont} \oarg{font features} \marg{font name}\\
+%   \CMD{\string\setmonofont} \oarg{font features} \marg{font name}\\
 %   \CMD{\string\newfontfamily} \meta{cmd} \oarg{font features} \marg{font name}
 % }
 %
@@ -343,21 +344,23 @@ This work consists of this file fontspec.dtx
 %
 % These commands are used to select
 % the default font families for the entire document. They take the
-% same arguments as \cmd{\fontspec}. For example:
+% same arguments as \cmd{\fontspec}. See \exref{fontload}.
+% Here, the scales of the fonts have been chosen to equalise their
+% lowercase letter heights. The \feat{Scale} font feature will be discussed
+% further in \vref{sec:font-ind-features}, including methods for automatic
+% scaling.
+%
+% \begin{Lexample}[firstline=3]{fontload}{Loading the default, sans serif, and monospaced fonts.}
 %   \def\pangram{Pack my box with five
 %                      dozen liquor jugs.}
-% \begin{example}
-%   \setmainfont{Baskerville}
-%   \setsansfont[Scale=MatchLowercase]{Skia}
-%   \setmonofont[Scale=MatchLowercase]{Monaco}
+%   \setmainfont{TeX Gyre Bonum}
+%   \setsansfont[Scale=MatchLowercase]{Latin Modern Sans}
+%   \setmonofont[Scale=MatchLowercase]{Inconsolata}
 %   \rmfamily\pangram\par
 %   \sffamily\pangram\par
 %   \ttfamily\pangram
-% \end{example}
-% Here, the scales of the fonts have been chosen to equalise their
-% lowercase letter heights. The \feat{Scale} font feature will be discussed
-% further in \vref{sec:font-ind-features}, including methods for automatic
-% scaling.
+% \end{Lexample}
+%
 %
 %
 %
@@ -365,7 +368,7 @@ This work consists of this file fontspec.dtx
 %
 % \cmdbox{
 %   \CMD{\string\newfontfamily} \cs{\meta{font-switch}} \oarg{font features} \marg{font name} \\
-%   \CMD{~~\string\newfontface} \cs{\meta{font-switch}} \oarg{font features} \marg{font name}
+%   \CMD{\string\newfontface} \cs{\meta{font-switch}} \oarg{font features} \marg{font name}
 % }
 %
 % \noindent For cases when a specific font with a specific
@@ -376,37 +379,50 @@ This work consists of this file fontspec.dtx
 %
 % \DescribeMacro{\newfontfamily}
 % For this reason, new commands can be created for loading a particular font
-% family with the \cmd\newfontfamily\ command:
-% \begin{example}
-%   \newfontfamily\notefont{Didot}
-%   \notefont This is a \emph{note}.
-% \end{example}
+% family with the \cmd\newfontfamily\ command, demonstrated in \exref{nff}.
 % This macro should be used to create commands that would be used in
 % the same way as \cmd\rmfamily, for example.
+% If you would like to create a command that only changes the font
+% inside its argument (like \cmd{emph}) define it using regular \LaTeX\
+% commands:
+% \begin{Verbatim}
+%   \newcommand\textnote[1]{{\notefont #1}}
+%   \textnote{This is a note.}
+% \end{Verbatim}
+% Note that the double braces are intentional; the inner pair are used to
+% to delimit the scope of the font change.
+%
+% \begin{Lexample}{nff}{Defining new font families.}
+%   \newfontfamily\notefont{Kurier}
+%   \notefont This is a \emph{note}.
+% \end{Lexample}
 %
 % \DescribeMacro{\newfontface}
 % Sometimes only a specific font face is desired, without accompanying italic or bold variants
 % begin automatically selected.
 % This is common when selecting a fancy italic font, say, that has swash features unavailable
-% in the upright forms. \cmd\newfontface\ is used for this purpose:
-% \begin{example}
+% in the upright forms. \cmd\newfontface\ is used for this purpose, shown
+% in \exref{nfface}, which is repeated in \vref{sec:contextuals}.
+%
+% \begin{Xexample}{nfface}{Defining a single font face.}
 %   \newfontface\fancy
 %       [Contextuals={WordInitial,WordFinal}]
 %                        {Hoefler Text Italic}
 %   \fancy where is all the vegemite
-% \end{example}
-% \noindent This example is repeated in \vref{sec:contextuals}.
+%   % \emph, \textbf, etc., all don't work
+% \end{Xexample}
+
 %
 % \subsection{More control over font shape selection}
 % \label{sec:bfitfonts}
 %
 % \cmdbox{
-%  \feat{~~~~~~~BoldFont} = \meta{font name} \\
-%  \feat{~~~~~ItalicFont} = \meta{font name} \\
+%  \feat{BoldFont} = \meta{font name} \\
+%  \feat{ItalicFont} = \meta{font name} \\
 %  \feat{~BoldItalicFont} = \meta{font name} \\
-%  \feat{~~~~SlantedFont} = \meta{font name} \\
+%  \feat{SlantedFont} = \meta{font name} \\
 %  \feat{BoldSlantedFont} = \meta{font name} \\
-%  \feat{~~SmallCapsFont} = \meta{font name}
+%  \feat{SmallCapsFont} = \meta{font name}
 % }
 %
 % The automatic bold, italic, and bold italic font selections will not be
@@ -417,15 +433,17 @@ This work consists of this file fontspec.dtx
 % italic fonts to chose between.  The \feat{BoldFont} and
 % \feat{ItalicFont} features are provided for these situations. If only
 % one of these is used, the bold italic font is requested as the
-% default from the \emph{new} font.
-% \begin{example}
+% default from the \emph{new} font. See \exref{bff}.
+%
+% \begin{Xexample}{bff}{Explicit selection of the bold font.}
 %   \fontspec[BoldFont={Helvetica Neue}]
 %                           {Helvetica Neue UltraLight}
 %                 Helvetica Neue UltraLight         \\
 %   {\itshape     Helvetica Neue UltraLight Italic} \\
 %   {\bfseries               Helvetica Neue       } \\
 %   {\bfseries\itshape       Helvetica Neue Italic} \\
-% \end{example}
+% \end{Xexample}
+%
 % If a bold italic shape is not defined, or you want to specify
 % \emph{both} custom bold and italic shapes, the \feat{BoldItalicFont}
 % feature is provided.
@@ -433,21 +451,18 @@ This work consists of this file fontspec.dtx
 % \subsubsection{Input shorthands}
 %
 % For those cases that the base font name is repeated, you can
-% replace it with an asterisk. For example,
+% replace it with an asterisk. (This has been shown previously in this section.)
+% For example,
 % some space can be saved instead of writing `\texttt{Baskerville SemiBold}':
-% \begin{example}
+% \begin{Verbatim}
 %   \fontspec[BoldFont={* SemiBold}]{Baskerville}
-%          Baskerville \textit{Italic}
-%   \bfseries SemiBold \textit{Italic}
-% \end{example}
+% \end{Verbatim}
 %
 % As a matter of fact, this feature can also be used for the upright font too:
-% \begin{example}
+% \begin{Verbatim}
 %   \fontspec[UprightFont={* SemiBold},
 %             BoldFont={* Bold}]{Baskerville}
-%          Upright \textit{Italic}
-%   \bfseries Bold \textit{Bold Italic}
-% \end{example}
+% \end{Verbatim}
 %
 % \subsubsection{Small caps and slanted font shapes}
 %
@@ -517,14 +532,6 @@ This work consists of this file fontspec.dtx
 %   \setmathrm{Optima}
 %   \setboldmathrm[BoldFont=Optima ExtraBlack]{Optima Bold}
 % \end{Verbatim}
-% and this would allow you to typeset something like this:
-% \begin{example}
-%   \setmainfont{Optima Regular}
-%   $ X \rightarrow \mathrm{X} \rightarrow \mathbf{X} $
-%   \\\boldmath
-%   $ X \rightarrow \mathrm{X} \rightarrow \mathbf{X} $
-% \end{example}
-% (TODO: this example obviously doesn't work without the graphic.)
 %
 %
 % \subsection{Miscellaneous font selecting details}
@@ -567,15 +574,19 @@ This work consists of this file fontspec.dtx
 % It is desirable to define
 % options that are applied to every subsequent font selection command:
 % a default feature set, so to speak. This may be defined with the
-% \cmd{\defaultfontfeatures} command.
+% \cmd{\defaultfontfeatures} command, shown in \exref{dff}.
 % New calls of \cs{defaultfontfeatures} overwrite previous ones.
-% \begin{example}
-%   \fontspec{Didot}
-%    Some `default' Didot 0123456789             \\
-%   \defaultfontfeatures{Numbers=OldStyle, Color=888888}
-%   \fontspec{Didot}
-%    Now grey, with old-style figures: 0123456789
-% \end{example}
+%
+% \begin{Xexample}{dff}{A demonstration of the \cs{defaultfontfeatures} command.}
+%   \fontspec{TeX Gyre Adventor}
+%   Some `default' Didot 0123456789 \\
+%   \defaultfontfeatures{
+%      Numbers=OldStyle, Color=888888
+%   }
+%   \fontspec{TeX Gyre Adventor}
+%   Now grey, with old-style figures:
+%   0123456789
+% \end{Xexample}
 %
 % \subsection{Changing the currently selected features}
 % \label{sec:addfontfeatures}
@@ -585,22 +596,22 @@ This work consists of this file fontspec.dtx
 % This command allows font features to
 % be changed without knowing what features are currently selected or even what
 % font is being used. A good example of this could be to add a hook to all
-% tabular material to use monospaced numbers, as shown in the following example:
+% tabular material to use monospaced numbers, as shown in \exref{aff}.
 %
-% \begin{example}
-%   \fontspec[Numbers=OldStyle]{Skia}
+% \begin{Lexample}{aff}{A demonstration of the \cs{addfontfeatures} command.}
+%   \fontspec[Numbers={Proportional,OldStyle}]
+%            {TeX Gyre Adventor}
 %   `In 1842, 999 people sailed 97 miles in
 %    13 boats. In 1923, 111 people sailed 54
 %    miles in 56 boats.'            \bigskip
 %
 %   {\addfontfeatures{Numbers={Monospaced,Lining}}
 %   \begin{tabular}{@{} cccc @{}}
-%     \toprule  Year & People & Miles & Boats \\
-%     \midrule  1842 &  999   &  75   &  13   \\
-%               1923 &  111   &  54   &  56   \\
-%     \bottomrule
+%             Year & People & Miles & Boats \\
+%     \hline  1842 &  999   &  75   &  13   \\
+%             1923 &  111   &  54   &  56
 %   \end{tabular}}
-% \end{example}
+% \end{Lexample}
 %
 % \DescribeMacro{\addfontfeature}
 % This command may also be executed under the alias \cmd{\addfontfeature}.
@@ -617,12 +628,12 @@ This work consists of this file fontspec.dtx
 % \label{sec:bfit-feat}
 %
 % \cmdbox{
-%  \feat{~~~~~~~BoldFeatures}\marg{features} \\
-%  \feat{~~~~~ItalicFeatures}\marg{features} \\
-%  \feat{~BoldItalicFeatures}\marg{features} \\
-%  \feat{~~~~SlantedFeatures}\marg{features} \\
+%  \feat{BoldFeatures}\marg{features} \\
+%  \feat{ItalicFeatures}\marg{features} \\
+%  \feat{BoldItalicFeatures}\marg{features} \\
+%  \feat{SlantedFeatures}\marg{features} \\
 %  \feat{BoldSlantedFeatures}\marg{features} \\
-%  \feat{~~SmallCapsFeatures}\marg{features}
+%  \feat{SmallCapsFeatures}\marg{features}
 % }
 %
 % It is entirely possible that separate fonts in a family will require
@@ -635,28 +646,34 @@ This work consists of this file fontspec.dtx
 % \feat{Italic-}, and \feat{BoldItalicFeatures},
 % separate font features may be defined to their respective shapes
 % \emph{in addition} to, and with precedence over, the `global' font features.
-% \begin{aatexample}
+% See \exref{itfeat}.
+%
+% \begin{Xexample}{itfeat}{Features for, say, just italics.}
 %   \fontspec{Hoefler Text} \itshape \scshape
 %   Attention All Martini Drinkers \\
 %   \addfontfeature{ItalicFeatures={Alternate = 1}}
 %   Attention All Martini Drinkers \\
-% \end{aatexample}
+% \end{Xexample}
+%
 % Combined with the options for selecting arbitrary \emph{fonts} for
 % the different shapes, these separate feature options allow the
-% selection of arbitrary weights in the Skia typeface, for example:
-% \begin{aatexample}
+% selection of arbitrary weights in the Skia typeface, as shown in \exref{bffeat}.
+%
+% \begin{Xexample}{bffeat}{Multiple Master--like features in AAT fonts.}
 %   \fontspec[BoldFont={Skia},
 %    BoldFeatures={Weight=2}]{Skia}
 %   Skia \\ \bfseries Skia `Bold'
-% \end{aatexample}
+% \end{Xexample}
 %
 % Note that because most fonts include their small caps glyphs
 % within the main font, features specified with \feat{SmallCapsFeatures} are applied \emph{in addition} to
 % any other shape-specific features as defined above, and hence \feat{SmallCapsFeatures}
 % can be nested within \feat{ItalicFeatures} and friends. Every combination
 % of upright, italic, bold and small caps can thus be assigned individual
-% features, as shown in the following ludicrous example.
-% \begin{example}
+% features, as shown in the somewhat ludicrous \exref{scfeat}.
+%
+% \begin{Xexample}{scfeat}{An example of setting the \feat{SmallCapsFeatures}
+% separately for each font shape.}
 %   \fontspec[
 %       UprightFeatures={Color = 220022,
 %            SmallCapsFeatures = {Color=115511}},
@@ -666,12 +683,12 @@ This work consists of this file fontspec.dtx
 %            SmallCapsFeatures = {Color=992211}},
 %    BoldItalicFeatures={Color = 888844,
 %            SmallCapsFeatures = {Color=444422}},
-%            ]{Hoefler Text}
+%            ]{TeX Gyre Termes}
 %   Upright {\scshape Small Caps}\\
 %   \itshape Italic {\scshape Italic Small Caps}\\
 %   \upshape\bfseries Bold {\scshape Bold Small Caps}\\
 %   \itshape Bold Italic {\scshape Bold Italic Small Caps}
-% \end{example}
+% \end{Xexample}
 %
 % \subsection{Different features for different font sizes}
 % \label{sec:sizefeature}
@@ -702,16 +719,18 @@ This work consists of this file fontspec.dtx
 % to declare the size range, and optionally \opt{Font} to change the
 % font based on size. Other (regular) fontspec features that are added
 % are used on top of the font features that would be used anyway.
+% A demonstration to hopefully clarify these details is shown in \exref{sizefeat}.
+% A less trivial example is shown in the context of optical font sizes
+% in \vref{sec:opticalsize}.
 %
-% \begin{example}
+% \begin{Xexample}{sizefeat}{An example of specifying different font features for different sizes of font with \feat{SizeFeatures}.}
 %   \fontspec[ SizeFeatures={
-%       {Size={-8}, Font=Apple Chancery, Color=AA0000},
+%       {Size={-8}, Font=TeX Gyre Bonum Italic, Color=AA0000},
 %       {Size={8-14}, Color=00AA00},
-%       {Size={14-}, Color=0000AA}} ]{Skia}
+%       {Size={14-}, Color=0000AA}} ]{TeX Gyre Chorus}
+%
 %   {\scriptsize Small\par} Normal size\par {\Large Large\par}
-% \end{example}
-% A less trivial example is shown in the context of optical font sizes
-% in \vref{sec:opticalsize}.
+% \end{Xexample}
 %
 % To be precise, the \opt{Size} sub-feature accepts arguments in the form shown in \vref{tab:sizing}.
 % Braces around the size range are optional. For an exact font size (|Size=X|)
@@ -753,18 +772,39 @@ This work consists of this file fontspec.dtx
 % \subsection{Color}
 %
 % \feat{Color} (or \feat{Colour}), also shown in \vref{sec:defaults}
-% and elsewhere, uses \XeTeX\ font specifications to set the color of
+% and elsewhere, uses font specifications to set the color of
 % the text. The color is defined as a triplet of two-digit Hex RGB
 % values, with optionally another value for the transparency (where
 % |00| is completely transparent and |FF| is opaque.)
-% \begin{example}
+% \begin{Xexample}{color}{Selecting colour with transparency.}
 %   \fontsize{48}{48}
-%   \fontspec{Hoefler Text Black}
+%   \fontspec{TeX Gyre Bonum Bold}
 %   {\addfontfeature{Color=FF000099}W}\kern-1ex
 %   {\addfontfeature{Color=0000FF99}S}\kern-0.8ex
 %   {\addfontfeature{Color=DDBB2299}P}\kern-0.8ex
 %   {\addfontfeature{Color=00BB3399}R}
-% \end{example}
+% \end{Xexample}
+% Transparency is supported by \XeLaTeX\ with the \texttt{xdv2pdf}
+% driver and with Lua\LaTeX; \XeLaTeX\ with the \texttt{xdvipdfmx} driver
+% is not supported.
+%
+% If you load the \pkg{xcolor} package, you may use any named color instead
+% of writing the colours in hexadecimal.
+% \begin{Verbatim}
+%  \usepackage{xcolor}
+%  ...
+%  \fontspec[Color=red]{Verdana} ...
+%  \definecolor{Foo}{rgb}{0.3,0.4,0.5}
+%  \fontspec[Color=Foo]{Verdana} ...
+% \end{Verbatim}
+% The \pkg{color} package is \emph{not} supported; use \pkg{xcolor} instead.
+%
+% You may specify the transparency with a named font using the \feat{Opacity}
+% feature:
+% \begin{Verbatim}
+%  \fontspec[Color=red,Opacity=0.7]{Verdana} ...
+% \end{Verbatim}
+% The \feat{Opacity} feature may only be used in conjunction with the \feat{Color} feature; it will be silently ignored if it appears by itself.
 %
 % \subsection{Scale}
 %
@@ -785,14 +825,16 @@ This work consists of this file fontspec.dtx
 % also accepts options \opt{MatchLowercase}
 % and \opt{MatchUppercase}, which will scale the font being selected to match
 % the current default roman font to either the height of the lowercase or
-% uppercase letters, respectively.
-% \begin{example}
+% uppercase letters, respectively; these features are shown in \exref{scale}.
+%
+% \begin{Xexample}{scale}{Automatically calculated scale values.}
 %   \setmainfont{Georgia}
 %   \newfontfamily\lc[Scale=MatchLowercase]{Verdana}
 %    The perfect match {\lc is hard to find.}\\
 %   \newfontfamily\uc[Scale=MatchUppercase]{Arial}
 %    L O G O \uc F O N T
-% \end{example}
+% \end{Xexample}
+%
 % The amount of scaling used in each instance is reported in the \texttt{.log} file.
 % Since there is some subjectivity about the exact scaling to be used, these values
 % should be used to fine-tune the results.
@@ -807,35 +849,31 @@ This work consists of this file fontspec.dtx
 % more convenient to specify this information when the font is
 % first defined.
 %
-% The space in between words in a paragraph will be chosen automatically
-% by \XeTeX, and generally will not need to be adjusted. For those
+% The space in between words in a paragraph will be chosen automatically,
+% and generally will not need to be adjusted. For those
 % times when the precise details are important, the \feat{WordSpace}
 % features is
 % provided, which takes either a single scaling factor to scale the
-% value that \XeTeX\ has already chosen, or a triplet of comma-separated
-% values for the nominal value, the stretch, and the shrink of the
-% interword space, respectively. \Ie, |WordSpace=0.8| is the same as
-% |WordSpace={0.8,0.8,0.8}|.
+% default value, or a triplet of comma-separated
+% values to scale the nominal value, the stretch, and the shrink of the
+% interword space by, respectively. (|WordSpace={|$x$|}| is the same as
+% |WordSpace={|$x$|,|$x$|,|$x$|}|.)
 %
-% For example, I believe that the Cochin font, as distributed with \MacOSX,
-% is too widely spaced. Now, this can be rectified, as shown below.
 % \begingroup
 % \let\centering\relax
-% \def\fillertext{Some filler text for our example to take up some
-%   space, and to demonstrate the large default interword space in \textit{Cochin}.}
-% \begin{example}
-%   \fontspec{Cochin}
-%   \fillertext
-%   \vspace{1em}
-%
-%   \fontspec[ WordSpace = {0.7 , 0.8 , 0.9} ]{Cochin}
-%   \fillertext
-% \end{example}
+% \begin{Xexample}{wordspace}{Scaling the default interword space. An exaggerated value has been chosen to emphasise the effects here.}
+%   \fontspec{TeX Gyre Termes}
+%   Some text for our example to take
+%   up some space, and to demonstrate
+%   the default interword space.
+%   \bigskip
+%
+%   \addfontfeature{ WordSpace = 0.3 }
+%   Some text for our example to take
+%   up some space, and to demonstrate
+%   the default interword space.
+% \end{Xexample}
 % \endgroup
-% Be careful with the unpredictable things that the \AAT\ font renderer
-% can do with the text! Unlike \TeX, \MacOSX\ will allow
-% fonts to letterspace themselves, which can be seen above; OpenType fonts, however, will not
-% show this tendency, as they do not support this arguably dubious feature.
 %
 % \subsection{Post-punctuation space}
 %
@@ -845,25 +883,21 @@ This work consists of this file fontspec.dtx
 % effect can be justified, pardon the pun.
 %
 % The \feat{PunctuationSpace} feature takes a scaling factor by which to
-% adjust the nominal value chosen for the font. Note that |PunctuationSpace=0|
+% adjust the nominal value chosen for the font; this is demonstrated in
+% \exref{punctspace}.
+% Note that |PunctuationSpace=0|
 % is \emph{not} equivalent to \cmd\frenchspacing, although the difference
 % will only be apparent when a line of text is under-full.
-% \begingroup
-% \let\centering\relax
-% \begin{example}
+%
+% \begin{Lexample}{punctspace}{Scaling the default post-punctuation space.}
 %   \nonfrenchspacing
-%   \fontspec{Baskerville}
+%   \fontspec{TeX Gyre Schola}
 %    Letters, Words. Sentences.          \par
-%   \fontspec[PunctuationSpace=0.5]{Baskerville}
+%   \fontspec[PunctuationSpace=2]{TeX Gyre Schola}
 %    Letters, Words. Sentences.          \par
-%   \fontspec[PunctuationSpace=0]{Baskerville}
+%   \fontspec[PunctuationSpace=0]{TeX Gyre Schola}
 %    Letters, Words. Sentences.
-% \end{example}
-% \endgroup
-%
-% Also be aware that the above caveat for interword space also applies here,
-% so after the last line in the above example, the \feat{PunctuationSpace}
-% for \emph{all} Baskerville instances will be |0|.
+% \end{Lexample}
 %
 %
 %
@@ -873,32 +907,34 @@ This work consists of this file fontspec.dtx
 % The letter used for hyphenation may be chosen with the \feat{HyphenChar}
 % feature. It takes three types of input, which are chosen according to some
 % simple rules. If the input is the string \opt{None}, then hyphenation is
-% suppressed for this font. If the input is a single character, then this
+% suppressed for this font.
+% \note{Known bug: this doesn't work yet in Lua\LaTeX.}
+% If the input is a single character, then this
 % character is used. Finally, if the input is longer than a single character
 % it must be the UTF-8 slot number of the hyphen character you desire.
 %
-% Below, Adobe Garamond Pro's uppercase hyphenation character
-% is used to demonstrate a possible use for this feature.
-% The second example redundantly demonstrates the default behaviour
-% of using the hyphen as the hyphenation character.
-% \begingroup
-% \let\centering\relax
-% \begin{example}
-%   \def\text
-%     {A MULTITUDE OF OBSTREPEROUSLY HYPHENATED ENTITIES
-%                                        \par\vspace{1ex}}
-%   \fontspec[HyphenChar=None]{Adobe Garamond Pro} \text
-%   \fontspec[HyphenChar={-}]{Adobe Garamond Pro} \text
-%   \fontspec[HyphenChar="F6BA]{Adobe Garamond Pro} \text
-% \end{example}
-% \endgroup
+% Adobe Garamond Pro's uppercase hyphenation character
+% is used to demonstrate a possible use for this feature in \exref{hyphchar}.
 % Note that in an actual situation, the \opt{Uppercase} option of the \feat{Letters} feature
 % would probably supply this for you (see \vref{sec:letters}).
 %
-% This package (or the \pkg{xltxtra} package for \XeTeX\ users)
+% This package
 % redefines \LaTeX's \cmd\-\ macro
 % such that it adjusts along with the above changes.
 %
+% \begin{Xexample}{hyphchar}{Explicitly choosing the hyphenation character.}
+%  \def\text{\fbox{\parbox{1.55cm}{%
+%    EXAMPLE HYPHENATION%
+%  }}\qquad\qquad\null\par\bigskip}
+%
+%  \fontspec{Adobe Garamond Pro}
+%  \addfontfeature{HyphenChar=None}
+%  \text
+%  \addfontfeature{HyphenChar={+}}
+%  \text
+%  \addfontfeature{HyphenChar={"F6BA}}
+%  \text
+% \end{Xexample}
 %
 % \subsection{Optical font sizes} \label{sec:opticalsize}
 %
@@ -916,8 +952,10 @@ This work consists of this file fontspec.dtx
 %
 % For the OpenType font Warnock Pro, we have three optically sized
 % variants: caption, subhead, and display. With \opt{OpticalSize} set
-% to zero, no optical size font substitution is performed:
-% \begin{opentypeexample}
+% to zero, no optical size font substitution is performed, as shown in
+% \exref{optsize0}.
+%
+% \begin{Lexample}{optsize0}{Optical size substitution is suppressed when set to zero.}
 %   \fontspec[OpticalSize=0]{Warnock Pro Caption}
 %    Warnock Pro optical sizes                \\
 %   \fontspec[OpticalSize=0]{Warnock Pro}
@@ -926,23 +964,24 @@ This work consists of this file fontspec.dtx
 %    Warnock Pro optical sizes                \\
 %   \fontspec[OpticalSize=0]{Warnock Pro Display}
 %    Warnock Pro optical sizes
-% \end{opentypeexample}
+% \end{Lexample}
 %
-% Automatic OpenType optical scaling is shown in the following
-% example, in which we've scaled down some large text in order to be
-% able to compare the difference for equivalent font sizes: (this
+% Automatic OpenType optical scaling is in
+% \exref{optsize}, in which we've scaled down some large text in order to be
+% able to compare the difference for equivalent font sizes (this
 % gives the same output as we saw in the previous example for Warnock
-% Pro Display)
-% \begin{opentypeexample}
+% Pro Display).
+%
+% \begin{Lexample}{optsize}{A demonstration of automatic optical size selection.}
 %   \fontspec{Warnock Pro}
 %    Automatic optical size                  \\
 %   \scalebox{0.4}{\Huge
 %    Automatic optical size}
-% \end{opentypeexample}
+% \end{Lexample}
 %
-% The \feat{SizeFeatures} feature (\vref{sec:sizefeature}) can be
+% The \feat{SizeFeatures} feature (\vref*{sec:sizefeature}) can be
 % used to specify exactly which optical sizes will be used for ranges
-% of font size. For example, something like
+% of font size. For example, something like:
 % \begin{verbatim}
 %   \fontspec[
 %     SizeFeatures={
@@ -953,7 +992,6 @@ This work consists of this file fontspec.dtx
 %            ]{Warnock Pro}
 % \end{verbatim}
 %
-% \clearpage
 % \part{OpenType}
 % \label{sec:opentype-features}
 %
@@ -994,12 +1032,13 @@ This work consists of this file fontspec.dtx
 % \otf{TeX}{tlig/trep}
 % \end{features}
 %
-% \begin{opentypeexample}
+% \begin{Lexample}{lig}{An example of the \feat{Ligatures} feature.}
+%    \Huge
 %   \fontspec[Ligatures=Rare]{Adobe Garamond Pro}
 %    \textit{strict firefly}                \\
 %   \fontspec[Ligatures=NoCommon]{Adobe Garamond Pro}
 %    \textit{strict firefly}
-% \end{opentypeexample}
+% \end{Lexample}
 %
 % \subsection{Letters} \label{sec:letters}
 % The \opt{Letters} feature specifies how the letters in the current font
@@ -1023,27 +1062,32 @@ This work consists of this file fontspec.dtx
 % whereas the \opt{Uppercase...} options turn the \emph{capital} letters into
 % the smaller
 % caps (good, \eg, for applying to already uppercase acronyms like
-% `NASA'). `Unicase' is a weird hybrid of upper and lower case
-% letters.
-% \begin{opentypeexample}
+% `NASA').
+% This difference is shown in \exref{caps}.
+% `Unicase' is a weird hybrid of upper and lower case letters.
+%
+% \begin{Lexample}{caps}{Small caps from lowercase or uppercase letters.}
 %   \fontspec[Letters=SmallCaps]{TeX Gyre Adventor}
 %    THIS SENTENCE no verb                \\
 %   \fontspec[Letters=UppercaseSmallCaps]{TeX Gyre Adventor}
 %    THIS SENTENCE no verb
-% \end{opentypeexample}
+% \end{Lexample}
 %
 % Note that The \opt{Uppercase} option will (probably)
 % not actually map letters to uppercase.
 %  \note{If you want automatic uppercase letters, look to \LaTeX's
 %       \cmd\MakeUppercase\ command.}
 % It is designed select various
-% uppercase forms for glyphs such as accents and dashes.
-% \begin{opentypeexample}
-%   \fontspec{Warnock Pro}
-%    UPPER-CASE EXAMPLE \\
+% uppercase forms for glyphs such as accents and dashes, such as shown
+% in \exref{letters-uppercase}.
+%
+% \begin{Lexample}{letters-uppercase}{An example of the \opt{Uppercase} option of the \feat{Letters} feature.}
+%   \fontspec{Adobe Garamond Pro}
+%    UPPER-CASE example \\
 %   \addfontfeature{Letters=Uppercase}
-%    UPPER-CASE EXAMPLE
-% \end{opentypeexample}
+%    UPPER-CASE example
+% \end{Lexample}
+%
 % The \feat{Kerning} feature also contains an \opt{Uppercase} option,
 % which adds a small amount of spacing in between letters (see \vref{sec:kerning}).
 %
@@ -1078,12 +1122,12 @@ This work consists of this file fontspec.dtx
 % is based on a \LuaTeX\ feature of the \pkg{luaotfload} package,
 % not an OpenType feature.
 %
-% \begin{opentypeexample}
+% \begin{Lexample}{slashzero}{The effect of the \opt{SlashedZero} option.}
 %   \fontspec[Numbers=Lining]{TeX Gyre Bonum}
 %    0123456789
 %   \fontspec[Numbers=SlashedZero]{TeX Gyre Bonum}
 %    0123456789
-% \end{opentypeexample}
+% \end{Lexample}
 %
 %
 % \subsection{Contextuals}
@@ -1099,12 +1143,12 @@ This work consists of this file fontspec.dtx
 % \otf{Inner}{medi}
 % \end{features}
 %
-% \begin{opentypeexample}
+% \begin{Lexample}{swash}{An example of the \opt{Swashes} option of the \opt{Contextuals} feature.}
 %   \fontspec{Warnock Pro} \itshape
 %    Without Contextual Swashes             \\
 %   \fontspec[Contextuals=Swash]{Warnock Pro}
 %    With Contextual Swashes; cf. W C S
-% \end{opentypeexample}
+% \end{Lexample}
 %
 % Historic forms are accessed in OpenType
 % fonts via the feature \feat{Style=Historic}; this is generally \emph{not}
@@ -1126,24 +1170,14 @@ This work consists of this file fontspec.dtx
 % letters (and a small amount of punctuation, sometimes).
 % The \opt{Ordinal} option will only raise characters that are used
 % in some languages directly after a number.
-%
 % The \opt{ScientificInferior} feature will move glyphs
 % further below the baseline than the \opt{Inferior} feature.
+% These are all shown in \exref{vertpos}
 %
 % \opt{Numerator} and \opt{Denominator} should only be used for creating
 % arbitrary fractions (see next section).
 %
-% \begin{aatexample}
-%   \fontspec{Skia}
-%    Normal
-%   \fontspec[VerticalPosition=Superior]{Skia}
-%    Superior
-%   \fontspec[VerticalPosition=Inferior]{Skia}
-%    Inferior                \\
-%   \fontspec[VerticalPosition=Ordinal]{Skia}
-%    1st 2nd 3rd 4th 0th 8abcde
-% \end{aatexample}
-% \begin{opentypeexample}
+% \begin{Lexample}{vertpos}{The \feat{VerticalPosition} feature.}
 %   \fontspec[VerticalPosition=Superior]{Warnock Pro}
 %    Sup: abdehilmnorst (-\$12,345.67)                      \\
 %   \fontspec[VerticalPosition=Numerator]{Warnock Pro}
@@ -1154,12 +1188,12 @@ This work consists of this file fontspec.dtx
 %    Scientific Inferior: 12345                             \\
 %   \fontspec[VerticalPosition=Ordinal]{Warnock Pro}
 %   `Ordinals': 1st 2nd 3rd 4th 0th
-% \end{opentypeexample}
+% \end{Lexample}
 %
 % The \pkg{realscripts} package (yet to be released)
 % (or \pkg{xltxtra} for \XeTeX)
 % redefines the \cmd\textsubscript\ and
-% \cmd\textsuperscript\ commands to use the above font features.
+% \cmd\textsuperscript\ commands to use the above font features automatically.
 %
 %
 % \subsection{Fractions}
@@ -1169,22 +1203,20 @@ This work consists of this file fontspec.dtx
 % \otf{Alternate}{afrc}
 % \end{features}
 %
-% For OpenType fonts use a regular text slash to create fractions:
-% \begin{opentypeexample}
+% For OpenType fonts use a regular text slash to create fractions, but
+% the \feat{Fraction} feature must be explicitly activated.
+% Some (Asian fonts predominantly) also provide for the
+% \opt{Alternate} feature. These are both shown in \exref{ot-frac}.
+%
+% \begin{Xexample}{ot-frac}{The \feat{Fractions} feature.}
 %   \fontspec{Hiragino Maru Gothic Pro W4}
 %    1/2 \quad 1/4 \quad 5/6 \quad 13579/24680 \\
 %   \addfontfeature{Fractions=On}
 %    1/2 \quad 1/4 \quad 5/6 \quad 13579/24680 \\
-% \end{opentypeexample}
-%
-% Some (Asian fonts predominantly) also provide for the
-% \opt{Alternate} feature:
-% \begin{opentypeexample}
-%   \fontspec{Hiragino Maru Gothic Pro W4}
-%    1/2 \quad 1/4 \quad 5/6 \quad 13579/24680 \\
 %   \addfontfeature{Fractions=Alternate}
 %    1/2 \quad 1/4 \quad 5/6 \quad 13579/24680 \\
-% \end{opentypeexample}
+% \end{Xexample}
+%
 %
 % \subsection{StylisticSet}
 %
@@ -1192,24 +1224,24 @@ This work consists of this file fontspec.dtx
 % specified numerically. These correspond to OpenType
 % features |ss01|, |ss02|, etc.
 %
-% Here are two examples from the Junicode
-% font\footnote{\url{http://junicode.sf.net}}; thanks to Adam
+% Two demonstrations from the Junicode
+% font\footnote{\url{http://junicode.sf.net}}
+% are shown in \exref{ss} and \exref{ss2}; thanks to Adam
 % Buchbinder for the suggestion.
-% This example shows insular (ancient) letterforms:
-% \begin{opentypeexample}
+%
+% \begin{Lexample}{ss}{Insular (ancient) letterforms for the Junicode font, accessed with the \feat{StylisticSet} feature.}
 %   \fontspec{Junicode}
 %    Insular forms. \\
 %   \addfontfeature{StylisticSet=2}
 %    Insular forms. \\
-% \end{opentypeexample}
-% And here is shown enlarged minuscules: (capital letters remain
-% unchanged)
-% \begin{opentypeexample}
+% \end{Lexample}
+%
+% \begin{Lexample}{ss2}{Enlarged minuscules (capital letters remain unchanged) for the Junicode font, accessed with the \feat{STylisticSet} feature.}
 %   \fontspec{Junicode}
 %    ENLARGED Minuscules. \\
 %   \addfontfeature{StylisticSet=6}
 %    ENLARGED Minuscules. \\
-% \end{opentypeexample}
+% \end{Lexample}
 %
 % (This is a synonym of the \feat{Variant} feature for \AAT\ fonts.)
 % See \vref{sec:newfeatures} for a way to assign names to stylistic sets,
@@ -1250,47 +1282,7 @@ This work consists of this file fontspec.dtx
 % For fonts with multiple |salt| OpenType features,
 % use the fontspec \feat{Alternate} feature instead.
 %
-% \setexsize\Large
-%  \begin{opentypeexample}
-%   \fontspec{Warnock Pro}
-%    K Q R k v w y                      \\
-%   \addfontfeature{Style=Alternate}
-%    K Q R k v w y
-% \end{opentypeexample}
-% Note the occasional inconsistency with which font features are labelled; a long-tailed `Q' could turn up anywhere!
-% \setexsize\Large
-% \begin{opentypeexample}
-%   \fontspec{Adobe Jenson Pro}
-%    M Q Z                              \\
-%   \addfontfeature{Style=Historic}
-%    M Q Z
-% \end{opentypeexample}
-% \setexsize\Large
-% \begin{example}
-%   \fontspec{Adobe Garamond Pro}
-%    TITLING CAPS                       \\
-%   \addfontfeature{Style=TitlingCaps}
-%    TITLING CAPS
-% \end{example}
-%
-% Two features in one example; \opt{Italic} affects the Latin text and \opt{Ruby} the Japanese:
-% \setexsize\Large
-% \begin{opentypeexample}
-%   \fontspec{Hiragino Mincho Pro W3}
-%    Latin ようこそ ワカヨタレソ        \\
-%   \addfontfeature{Style={Italic, Ruby}}
-%    Latin ようこそ ワカヨタレソ
-% \end{opentypeexample}
-% Note the difference here between the default and the horizontal style kana:
-% \setexsize\Large
-% \begin{aatexample}
-%    \fontspec{Hiragino Mincho Pro}
-%     ようこそ ワカヨタレソ  \\
-%   {\addfontfeature{Style=HorizontalKana}
-%     ようこそ ワカヨタレソ} \\
-%   {\addfontfeature{Style=VerticalKana}
-%     ようこそ ワカヨタレソ}
-% \end{aatexample}
+% Typical examples for these features are shown in \ref{sec:ot-feat-style}.
 %
 %
 %
@@ -1315,13 +1307,14 @@ This work consists of this file fontspec.dtx
 % \end{features}
 %
 % As briefly mentioned previously at the end of \vref{sec:letters},
-% the \opt{Uppercase} option will add a small amount of tracking between uppercase letters:
-% \begin{opentypeexample}
+% the \opt{Uppercase} option will add a small amount of tracking between uppercase letters, seen in \exref{kernup}.
+%
+% \begin{Lexample}{kernup}{Adding extra kerning for uppercase letters.}
 %   \fontspec{Warnock Pro}
 %    UPPER-CASE EXAMPLE \\
 %   \addfontfeature{Kerning=Uppercase}
 %    UPPER-CASE EXAMPLE
-% \end{opentypeexample}
+% \end{Lexample}
 %
 %
 % \subsection{CJK shape}
@@ -1343,16 +1336,17 @@ This work consists of this file fontspec.dtx
 % fonts support the following \feat{CJKShape} options:
 % \opt{Traditional}, \opt{Simplified}, \opt{JIS1978}, \opt{JIS1983},
 % \opt{JIS1990}, and \opt{Expert}. OpenType also supports the \opt{NLC} option.
-% \setexsize\LARGE
-% \begin{opentypeexample}
+
+% \begin{Xexample}[firstline=2]{ot-cjk-shape}{Different standards for CJK ideograph presentation.}
+%   \LARGE\def\text{ 唖噛躯 妍并訝}
 %   \fontspec{Hiragino Mincho Pro}
 %   {\addfontfeature{CJKShape=Traditional}
-%    唖噛躯 妍并訝 }                          \\
+%   \text }                          \\
 %   {\addfontfeature{CJKShape=NLC}
-%    唖噛躯 妍并訝 }                          \\
+%   \text }                          \\
 %   {\addfontfeature{CJKShape=Expert}
-%    唖噛躯 妍并訝 }
-% \end{opentypeexample}
+%   \text }
+% \end{Xexample}
 %
 % \subsection{Character width}\label{sec:CharacterWidth}
 % Many Asian fonts are equipped with variously spaced characters for
@@ -1378,17 +1372,23 @@ This work consists of this file fontspec.dtx
 % a given block of space. The same features are given to roman letters
 % in Japanese fonts, for typesetting foreign words in the same style
 % as the surrounding text.
-% \begin{opentypeexample}
-%   \def\test{\makebox[2cm][l]{ようこそ}% %             \makebox[2.5cm][l]{ワカヨタレソ}% %             \makebox[2.5cm][l]{abcdef}}
+%
+% \begin{Xexample}[firstline=2]{charwdprop}{Proportional or fixed width forms.}
+%   \def\texta{ようこそ}\def\textb{ワカヨタレソ}
+%   \def\test{\makebox[2cm][l]{\texta}%
+%             \makebox[2.5cm][l]{\textb}%
+%             \makebox[2.5cm][l]{abcdef}}
 %   \fontspec{Hiragino Mincho Pro}
 %   {\addfontfeature{CharacterWidth=Proportional}\test}\\
 %   {\addfontfeature{CharacterWidth=Full}\test}\\
 %   {\addfontfeature{CharacterWidth=Half}\test}
-% \end{opentypeexample}
+% \end{Xexample}
+%
 % The same situation occurs with numbers, which are provided in
-% increasingly illegible compressed forms:
-% \setexsize\large
-% \begin{aatexample}
+% increasingly illegible compressed forms seen in exref{charwd}.
+%
+% \begin{Xexample}[firstline=2]{charwd}{Numbers can be compressed significantly.}
+%   \centering
 %   \fontspec[Renderer=AAT]{Hiragino Mincho Pro}
 %   {\addfontfeature{CharacterWidth=Full}
 %    ---12321---}\\
@@ -1398,7 +1398,8 @@ This work consists of this file fontspec.dtx
 %    ---123456787654321---}\\
 %   {\addfontfeature{CharacterWidth=Quarter}
 %    ---12345678900987654321---}
-% \end{aatexample}
+% \end{Xexample}
+%
 % The option \opt{CharacterWidth=Full} doesn't work with the
 % default OpenType font renderer (ICU) due to a bug in the Hiragino fonts.
 %
@@ -1421,6 +1422,8 @@ This work consists of this file fontspec.dtx
 % change which features are able to be selected for the font, they are selected
 % by \pkg{fontspec} before all others and will specifically select the \opt{ICU}
 % renderer for this font, as described in \vref{sec:renderer}.
+%
+%
 % \iffalse
 % \subsubsection{\feat{Script} examples}
 %
@@ -1488,6 +1491,7 @@ This work consists of this file fontspec.dtx
 %    Ş ş Ţ ţ
 % \end{opentypeexample}
 % \endgroup
+%
 % \fi
 %
 % \subsubsection{Defining new scripts and languages}
@@ -1539,7 +1543,6 @@ This work consists of this file fontspec.dtx
 %
 %
 %
-% \clearpage
 % \part{Fonts and features with \XeTeX}
 % \label{sec:xetex-features}
 %
@@ -1550,49 +1553,50 @@ This work consists of this file fontspec.dtx
 %
 % \subsection{Mapping}
 %
-% \feat{Mapping} enables a \XeTeX\ text-mapping scheme.
-% \begin{example}
+% \feat{Mapping} enables a \XeTeX\ text-mapping scheme, shown in \exref{mapping}.
+%
+% \begin{Xexample}{mapping}{\XeTeX's \feat{Mapping} feature.}
 %   \fontspec[Mapping=tex-text]{Cochin}
 %   ``!`A small amount of---text!''
-% \end{example}
+% \end{Xexample}
+%
 % Using the |tex-text| mapping is also equivalent to writing |Ligatures=TeX|.
 % The use of the latter syntax is recommended for better compatibility with
 % \LuaTeX\ documents.
 %
 %
 % \subsection{Letter spacing}
-% Letter spacing, or tracking, is the term given to adding (or subtracting) a small amount of horizontal space in between adjacent characters. It is specified with the \feat{LetterSpace}, which takes a numeric argument.
+% Letter spacing, or tracking, is the term given to adding (or subtracting) a small amount of horizontal space in between adjacent characters. It is specified with the \feat{LetterSpace}, which takes a numeric argument,
+% shown in \exref{tracking}.
 %
 % The letter spacing parameter is a normalised additive factor (not a scaling factor); it is defined as a percentage of the font size. That is, for a 10\,pt font, a letter spacing parameter of `|1.0|' will add 0.1\,pt between each letter.
-% \begin{example}
+%
+% \begin{Xexample}{tracking}{The \feat{LetterSpace} feature.}
 %   \fontspec{Didot}
 %   \addfontfeature{LetterSpace=0.0}
 %   USE TRACKING FOR DISPLAY CAPS TEXT \\
 %   \addfontfeature{LetterSpace=2.0}
 %   USE TRACKING FOR DISPLAY CAPS TEXT
-% \end{example}
+% \end{Xexample}
+%
 % This functionality \emph{should not be used for lowercase text}, which is spacing correctly to begin with, but it can be very useful, in small amounts, when setting small caps or all caps titles.
 % Also see the OpenType \opt{Uppercase}
 % option of the \feat{Letters} feature (\vref*{sec:letters}).
 %
 % \subsection{Font transformations}
 %
-% In rare situations users may want to mechanically distort the shapes of the glyphs in the current font. Please don't overuse these features; they are \emph{not} a good alternative to having the real shapes.
+% In rare situations users may want to mechanically distort the shapes of the glyphs in the current font such as shown in \exref{fake}. Please don't overuse these features; they are \emph{not} a good alternative to having the real shapes.
 %
-% \begin{example}
+% \begin{Xexample}{fake}{Articifial font transformations.}
 %   \fontspec{Charis SIL} \emph{ABCxyz} \quad
 %   \fontspec[FakeSlant=0.2]{Charis SIL} ABCxyz
-% \end{example}
 %
-% \begin{example}
 %   \fontspec{Charis SIL}  ABCxyz \quad
 %   \fontspec[FakeStretch=1.2]{Charis SIL} ABCxyz
-% \end{example}
 %
-% \begin{example}
 %   \fontspec{Charis SIL} \textbf{ABCxyz} \quad
 %   \fontspec[FakeBold=1.5]{Charis SIL} ABCxyz
-% \end{example}
+% \end{Xexample}
 %
 % If values are omitted, their defaults are as shown above.
 %
@@ -1605,7 +1609,7 @@ This work consists of this file fontspec.dtx
 %   \fontspec[BoldFeatures={FakeBold=1.5}]{Charis SIL}
 % \end{verbatim}
 %
-% If bolh of the \feat{AutoFake...} features are used, then the bold italic
+% If both of the \feat{AutoFake...} features are used, then the bold italic
 % font will also be faked.
 %
 %
@@ -1710,21 +1714,24 @@ This work consists of this file fontspec.dtx
 % This feature refers to glyph substitution that vary by their position;
 % things like contextual swashes are implemented here
 % The options for \AAT\ fonts are
-% \opt{WordInitial}, \opt{WordFinal}, \opt{LineInitial},
-% \opt{LineFinal}, and \opt{Inner} (also called `non-final' sometimes). As
+% \opt{WordInitial}, \opt{WordFinal} (\exref{wordcx}), \opt{LineInitial},
+% \opt{LineFinal}, and \opt{Inner} (\exref{lonsaat}, also called `non-final' sometimes). As
 % non-exclusive selectors, like the ligatures, you can turn them off
 % by prefixing their name with \opt{No}.
-% \begin{aatexample}
+%
+% \begin{Xexample}{wordcx}{Contextual glyph for the beginnings and ends of words.}
 %   \newfontface\fancy
 %       [Contextuals={WordInitial,WordFinal}]
 %                        {Hoefler Text Italic}
 %   \fancy where is all the vegemite
-% \end{aatexample}
-% \begin{aatexample}
+% \end{Xexample}
+%
+% \begin{Xexample}{longsaat}{A contextual feature for the `long s' can be convenient as the character does not need to be marked up explicitly.}
 %   \fontspec[Contextuals=Inner]{Hoefler Text}
 %   `Inner' swashes can \emph{sometimes}    \\
 %    contain the archaic long~s.
-% \end{aatexample}
+% \end{Xexample}
+%
 %
 %
 % \subsection{Vertical position}
@@ -1734,7 +1741,9 @@ This work consists of this file fontspec.dtx
 % The \opt{Ordinal} option is (supposed to be)
 % contextually sensitive to only raise characters that appear directly
 % after a number.
-% \begin{aatexample}
+% These are shown in \exref{aat-supp}.
+%
+% \begin{Xexample}{aat-supp}{Vertical position for AAT fonts.}
 %   \fontspec{Skia}
 %    Normal
 %   \fontspec[VerticalPosition=Superior]{Skia}
@@ -1743,7 +1752,7 @@ This work consists of this file fontspec.dtx
 %    Inferior                \\
 %   \fontspec[VerticalPosition=Ordinal]{Skia}
 %    1st 2nd 3rd 4th 0th 8abcde
-% \end{aatexample}
+% \end{Xexample}
 %
 % The \pkg{xltxtra} package redefines the \cmd\textsubscript\ and
 % \cmd\textsuperscript\ commands to use the above font features.
@@ -1757,48 +1766,51 @@ This work consists of this file fontspec.dtx
 % In \AAT\ fonts, the `fraction slash' or solidus character, is
 % to be used to create fractions. When \feat{Fractions} are turned
 % \opt{On}, then only pre-drawn fractions will be used.
-% \begin{aatexample}
+% See \exref{aat-frac}.
+%
+% Using the \opt{Diagonal} option (\AAT\ only), the font will attempt
+% to create the fraction from superscript and subscript
+% characters.
+%
+% \begin{Xexample}{aat-frac}{Fractions in AAT fonts.}
 %   \fontspec[Fractions=On]{Skia}
 %    1⁄2 \quad 5⁄6 \\ % fraction slash
 %    1/2 \quad 5/6    % regular  slash
-% \end{aatexample}
-% Using the \opt{Diagonal} option (\AAT\ only), the font will attempt
-% to create the fraction from superscript and subscript
-% characters. This is shown in the following example:
-% \begin{aatexample}
+%
 %   \fontspec[Fractions=Diagonal]{Skia}
 %          13579⁄24680 \\ % fraction slash
 %    \quad 13579/24680    % regular  slash
-% \end{aatexample}
+% \end{Xexample}
 %
 % Some (Asian fonts predominantly) also provide for the
-% \opt{Alternate} feature:
-% \begin{opentypeexample}
-%   \fontspec{Hiragino Maru Gothic Pro W4}
+% \opt{Alternate} feature shown in \exref{frac-alt}.
+%
+% \begin{Xexample}{frac-alt}{Alternate design of pre-composed fractions.}
+%   \fontspec{Hiragino Maru Gothic Pro}
 %    1/2 \quad 1/4 \quad 5/6 \quad 13579/24680 \\
 %   \addfontfeature{Fractions=Alternate}
-%    1/2 \quad 1/4 \quad 5/6 \quad 13579/24680 \\
-% \end{opentypeexample}
-% The \pkg{xltxtra} package provides a \cmd\vfrac\ command
-% for creating arbitrary so-called `vulgar' fractions:
-% \begin{opentypeexample}
-%   \fontspec{Warnock Pro}
-%   \vfrac{13579}{24680}
-% \end{opentypeexample}
+%    1/2 \quad 1/4 \quad 5/6 \quad 13579/24680
+% \end{Xexample}
 %
 %
 % \subsection{Variants}
 % The \feat{Variant} feature takes a single numerical input for
-% choosing different alphabetic shapes. Don't mind my fancy example
+% choosing different alphabetic shapes. Don't mind my fancy \exref{aat-var}
 % \texttt{:)} I'm just looping through the nine~(\,!\,) variants of
 % Zapfino.
-% \setexsize\Huge
-% \def\firstline{2}\def\lastline{9}
-% \begin{aatexample}
-%   \rule{0pt}{2cm}% %   \newcounter{var}\newcounter{trans}
-%   \whiledo{\value{var}<9}{% %     \stepcounter{trans}% %     \fontspec[Variant=\thevar,
-%       Color=005599\thetrans\thetrans]{Zapfino}% %     \makebox[0.75\width]{d}% %     \stepcounter{var}}
-% \end{aatexample}
+%
+% \begin{Xexample}[firstline=2,lastline=9]{aat-var}{Nine variants of Zapfino.}
+%   \Huge \rule{0pt}{2cm}
+%   \newcounter{var}\newcounter{trans}
+%   \whiledo{\value{var}<9}{%
+%     \stepcounter{trans}%
+%     \edef\1{%
+%     \noexpand\fontspec[Variant=\thevar,
+%       Color=005599\thetrans\thetrans]{Zapfino}}\1%
+%     \makebox[0.75\width]{d}%
+%     \stepcounter{var}}
+%   \hspace*{2cm}
+% \end{Xexample}
 %
 % See \vref{sec:newfeatures} for a way to assign names to variants,
 % which should be done on a per-font basis.
@@ -1806,18 +1818,21 @@ This work consists of this file fontspec.dtx
 % \subsection{Alternates}
 %
 % Selection of \feat{Alternate}s \emph{again}
-% must be done numerically. Here's an example with an \AAT\ font:
-% \begin{aatexample}
+% must be done numerically; see \exref{aat-alt}.
+% See \vref{sec:newfeatures} for a way to assign names to alternates,
+% which should be done on a per-font basis.
+%
+% \begin{Xexample}{aat-alt}{Alternate shape selection must be numerical.}
 %   \fontspec[Alternate=0]{Hoefler Text Italic}
 %    Sphinx Of Black Quartz, {\scshape Judge My Vow} \\
 %   \fontspec[Alternate=1]{Hoefler Text Italic}
 %    Sphinx Of Black Quartz, {\scshape Judge My Vow}
-% \end{aatexample}
-% See \vref{sec:newfeatures} for a way to assign names to alternates,
-% which should be done on a per-font basis.
+% \end{Xexample}
 %
 %
 % \subsection{Style}
+% \label{sec:ot-feat-style}
+%
 % The options of the \feat{Style} feature
 % are defined in \AAT\ as one of the following: \opt{Display},
 % \opt{Engraved}, \opt{IlluminatedCaps}, \opt{Italic},
@@ -1825,46 +1840,57 @@ This work consists of this file fontspec.dtx
 % \footnotetext{`Ruby' refers to a small optical size, used in
 % Japanese typography for annotations.}
 %
-% \setexsize\Large
-%  \begin{opentypeexample}
+% \Exref{style-alt} and \exref{style-hist} both contain glyph
+% subtitutions with similar characteristics.
+% Note the occasional inconsistency with which font features are labelled; a long-tailed `Q' could turn up anywhere!
+%
+%  \begin{Lexample}[firstline=2]{style-alt}{Example of the \opt{Alternate} option of the \feat{Style} feature.}
+%   \Large
 %   \fontspec{Warnock Pro}
 %    K Q R k v w y                      \\
 %   \addfontfeature{Style=Alternate}
 %    K Q R k v w y
-% \end{opentypeexample}
-% Note the occasional inconsistency with which font features are labelled; a long-tailed `Q' could turn up anywhere!
-% \setexsize\Large
-% \begin{opentypeexample}
+% \end{Lexample}
+%
+% \begin{Lexample}[firstline=2]{style-hist}{Example of the \opt{Historic} option of the \feat{Style} feature.}
+%   \Large
 %   \fontspec{Adobe Jenson Pro}
-%    M Q Z                              \\
+%    M Q Z                      \\
 %   \addfontfeature{Style=Historic}
 %    M Q Z
-% \end{opentypeexample}
-% \setexsize\Large
-% \begin{example}
+% \end{Lexample}
+%
+% In other features, larger breadths of changes can be seen, covering
+% the style of an entire alphabet. See \exref{style-titl} and \exref{style-itrub}; in the latter, the \opt{Italic} option affects the Latin text and the \opt{Ruby} option the Japanese.
+%
+% \begin{Lexample}[firstline=2]{style-titl}{Example of the \opt{TitlingCaps} option of the \feat{Style} feature.}
+%   \Large
 %   \fontspec{Adobe Garamond Pro}
 %    TITLING CAPS                       \\
 %   \addfontfeature{Style=TitlingCaps}
 %    TITLING CAPS
-% \end{example}
-% Two features in one example; \opt{Italic} affects the Latin text and \opt{Ruby} the Japanese:
-% \setexsize\Large
-% \begin{opentypeexample}
-%   \fontspec{Hiragino Mincho Pro W3}
-%    Latin ようこそ ワカヨタレソ        \\
+% \end{Lexample}
+%
+% \begin{Xexample}[firstline=2]{style-itrub}{Example of the \opt{Italic} and \opt{Ruby} options of the \feat{Style} feature.}
+%   \Large \def\kana{ようこそ ワカヨタレソ}
+%   \fontspec{Hiragino Mincho Pro}
+%    Latin \kana        \\
 %   \addfontfeature{Style={Italic, Ruby}}
-%    Latin ようこそ ワカヨタレソ
-% \end{opentypeexample}
-% Note the difference here between the default and the horizontal style kana:
-% \setexsize\Large
-% \begin{aatexample}
+%    Latin \kana
+% \end{Xexample}
+%
+% Note the difference here between the default and the horizontal style kana
+% in \exref{style-hvkana}.
+%
+% \begin{Xexample}[firstline=2]{style-hvkana}{Example of the \opt{HorizontalKana} and \opt{VerticalKana} options of the \feat{Style} feature.}
+%   \Large \def\kana{ようこそ ワカヨタレソ}
 %    \fontspec{Hiragino Mincho Pro}
-%     ようこそ ワカヨタレソ  \\
+%     \kana   \\
 %   {\addfontfeature{Style=HorizontalKana}
-%     ようこそ ワカヨタレソ} \\
+%     \kana } \\
 %   {\addfontfeature{Style=VerticalKana}
-%     ようこそ ワカヨタレソ}
-% \end{aatexample}
+%     \kana }
+% \end{Xexample}
 %
 %
 %
@@ -1879,85 +1905,44 @@ This work consists of this file fontspec.dtx
 % \opt{Traditional}, \opt{Simplified}, \opt{JIS1978}, \opt{JIS1983},
 % \opt{JIS1990}, and \opt{Expert}. OpenType also supports the \opt{NLC} option.
 %
-% \subsection{Character width}\label{sec:CharacterWidth}
-% Many Asian fonts are equipped with variously spaced characters for
-% shoe-horning into their generally monospaced text.
-% These are
-% accessed through the \feat{CharacterWidth} feature.
-%   \note{Apple
-%   seems to be adapting its \AAT\ features in this regard (at least in
-%   the fonts it distributes with \MacOSX) to have a one-to-one
-%   correspondence with the equivalent OpenType features. Previously
-%   \AAT\ was more fine grained, but naturally they're not documenting
-%   their \AAT\ tables any more, so if the following features don't work
-%   for a specific font let me know and I'll try and see if anything
-%   can be salvaged from the situation.}
-% For now, OpenType and \AAT\
-% share the same six options for this feature: \opt{Proportional},
-% \opt{Full}, \opt{Half}, \opt{Third},
-% \opt{Quarter}, \opt{AlternateProportional}, and
-% \opt{AlternateHalf}. \AAT\ also allows \opt{Default} to return to
-% whatever was originally specified.
-%
-% Japanese alphabetic glyphs (in Hiragana or Katakana) may be typeset
-% proportionally, to better fit horizontal measures, or monospaced, to
-% fit into the rigid grid imposed by ideographic typesetting. In this
-% latter case, there are also half-width forms for squeezing more kana
-% glyphs (which are less complex than the kanji they are amongst) into
-% a given block of space. The same features are given to roman letters
-% in Japanese fonts, for typesetting foreign words in the same style
-% as the surrounding text.
-% \begin{opentypeexample}
-%   \def\test{\makebox[2cm][l]{ようこそ}% %             \makebox[2.5cm][l]{ワカヨタレソ}% %             \makebox[2.5cm][l]{abcdef}}
-%   \fontspec{Hiragino Mincho Pro}
-%   {\addfontfeature{CharacterWidth=Proportional}\test}\\
-%   {\addfontfeature{CharacterWidth=Full}\test}\\
-%   {\addfontfeature{CharacterWidth=Half}\test}
-% \end{opentypeexample}
-% The same situation occurs with numbers, which are provided in
-% increasingly illegible compressed forms:
-% \setexsize\large
-% \begin{aatexample}
-%   \fontspec[Renderer=AAT]{Hiragino Mincho Pro}
-%   {\addfontfeature{CharacterWidth=Full}
-%    ---12321---}\\
-%   {\addfontfeature{CharacterWidth=Half}
-%    ---1234554321---}\\
-%   {\addfontfeature{CharacterWidth=Third}
-%    ---123456787654321---}\\
-%   {\addfontfeature{CharacterWidth=Quarter}
-%    ---12345678900987654321---}
-% \end{aatexample}
-% The option \opt{CharacterWidth=Full} doesn't work with the
-% default OpenType font renderer (ICU) due to a bug in the Hiragino fonts.
+% \subsection{Character width}
+% See \vref{sec:CharacterWidth} for relevant examples; the features are
+% the same between OpenType and \AAT\ fonts.
+% \AAT\ also allows \feat{CharacterWidth}|=|\opt{Default} to return to
+% the original font settings.
 %
 %
 % \subsection{Annotation}
 % Various Asian fonts are equipped with a more extensive range of
 % numbers and numerals in different forms.
-% For OpenType fonts, the only option supported is \opt{On} and \opt{Off}:
-% \begin{opentypeexample}
+% For OpenType fonts, annotations with the \feat{Annotation} feature are selected numerically, as shown in \exref{ot-annot}.
+%
+% \begin{Xexample}{ot-annot}{Annotation forms.}
 %   \fontspec{Hiragino Maru Gothic Pro}
-%    1 2 3 4 5 6 7 8 9                         \\
-%   \addfontfeature{Annotation=On}
 %    1 2 3 4 5 6 7 8 9
-% \end{opentypeexample}
-% I'm not sure if \XeTeX\ can access alternate annotation
-% forms, even if they exist (as in this case) in the font.
+%   \def\x#1{\\{\addfontfeature{Annotation=#1}
+%             1 2 3 4 5 6 7 8 9 }}
+%   \x0\x1\x2\x3\x4\x5\x6\x7\x7\x8\x9
+% \end{Xexample}
+%
 %
 %
 % \subsection{Vertical typesetting}
 %
+% TODO: improve!
+%
 % \XeTeX\ provides for vertical typesetting simply with the ability to rotate
-% the individual glyphs as a font is used for typesetting.
+% the individual glyphs as a font is used for typesetting, as shown in
+% \exref{vert}.
 %
-% \begin{aatexample}
+% \begin{Xexample}[firstline=2]{vert}{Vertical typesetting.}
+%   \def\verttext{共産主義者は}
 %   \fontspec{Hiragino Mincho Pro}
-%   共産主義者は
+%   \verttext
 %
 %   \fontspec[Renderer=AAT,Vertical=RotatedGlyphs]{Hiragino Mincho Pro}
-%   \rotatebox{-90}{共産主義者は}% requires the graphicx package
-% \end{aatexample}
+%   \rotatebox{-90}{\verttext}% requires the graphicx package
+% \end{Xexample}
 %
 % No actual provision is made for typesetting top-to-bottom
 % languages; for an example of how to do this, see the vertical Chinese
@@ -1990,7 +1975,9 @@ This work consists of this file fontspec.dtx
 % \opt{Box}, \opt{RoundedBox}, \opt{Circle}, \opt{BlackCircle},
 % \opt{Parenthesis}, \opt{Period}, \opt{RomanNumerals}, \opt{Diamond},
 % \opt{BlackSquare}, \opt{BlackRoundSquare}, and \opt{DoubleCircle}.
-% \begin{aatexample}
+% See \exref{aat-annot}
+%
+% \begin{Xexample}{aat-annot}{Various annotation forms.}
 %   \fontspec{Hei Regular}
 %    1 2 3 4 5 6 7 8 9                         \\
 %   \fontspec[Annotation=Circle]{Hei Regular}
@@ -1999,7 +1986,7 @@ This work consists of this file fontspec.dtx
 %    1 2 3 4 5 6 7 8 9                         \\
 %   \fontspec[Annotation=Period]{Hei Regular}
 %    1 2 3 4 5 6 7 8 9
-% \end{aatexample}
+% \end{Xexample}
 %
 % \section{\AAT\ \& Multiple Master font axes} \label{sec:mm}
 %
@@ -2010,19 +1997,20 @@ This work consists of this file fontspec.dtx
 %
 % \opt{Weight}, \opt{Width}, and \opt{OpticalSize} are supported by this
 % package. Skia, which is distributed with
-% Mac~OS~X, has two of these variable parameters, allowing for a
-% demonstration:
-% \begin{aatexample}
+% Mac~OS~X, has two of these variable parameters, allowing for the
+% demonstration in \exref{aatmm}.
+% Variations along a multiple master font's optical size axis has been
+% shown previously in \vref{sec:opticalsize}.
+%
+% \begin{Xexample}{aatmm}{Continuously variable font parameters. These fonts
+%  are unfortunately quite rare.}
 %   \fontspec[Weight=0.5,Width=3]{Skia}
 %    Really light and extended Skia         \\
 %   \fontspec[Weight=2,Width=0.5]{Skia}
 %    Really fat and condensed Skia
-% \end{aatexample}
-% Variations along a multiple master font's optical size axis has been
-% shown previously in \vref{sec:opticalsize}.
+% \end{Xexample}
 %
 %
-% \clearpage
 % \part{Programming interface}
 %
 % This is the beginning of some work to provide some hooks that use
@@ -2039,31 +2027,26 @@ This work consists of this file fontspec.dtx
 % \DescribeMacro{\newAATfeature}
 % New \AAT\ features may be created with this command:\par
 % {\centering\cmd\newAATfeature\marg{feature}\marg{option}\marg{feature code}\marg{selector code}\par}\noindent
-% Use the \XeTeX\ file \path{AAT-info.tex} to obtain the code numbers. For example:
-% \begin{aatexample}
+% Use the \XeTeX\ file \path{AAT-info.tex} to obtain the code numbers.
+% See \exref{newAATfeat}.
+%
+% \begin{Xexample}{newAATfeat}{Assigning new \AAT\ features.}
 %   \newAATfeature{Alternate}{HoeflerSwash}{17}{1}
 %   \fontspec[Alternate=HoeflerSwash]{Hoefler Text Italic}
 %    This is XeTeX by Jonathan Kew.
-% \end{aatexample}
-% This command replaces \cmd\newfeaturecode, which is provided
-% for backwards compatibility via \texttt{fontspec.cfg}.
+% \end{Xexample}
+%
 %
 % \DescribeMacro{\newICUfeature}
 % \DescribeMacro{\newopentypefeature}
 % New OpenType features may be created with this command:\par
 % {\centering\cmd\newICUfeature\marg{feature}\marg{option}\marg{feature tag}\par}
-% The synonym \cs{newopentypefeature} is provided for \LuaTeX\ users.
-% In the following example, the Moldavian language (see \vref{sec:ot}) must be activated to achieve the effect shown.
-% \setexsize\Large
-% \begingroup
-% \begin{opentypeexample}
-%   \newICUfeature{Style}{NoLocalForms}{-locl}
-%   \fontspec[Language=Moldavian]{FPL Neu}
-%   Ş ş Ţ ţ  \\
-%   \addfontfeature{Style=NoLocalForms}
-%   Ş ş Ţ ţ
-% \end{opentypeexample}
-% \endgroup
+% The synonym \cs{newopentypefeature} is provided for Lua\LaTeX\ users.
+%
+% Here's what it would look like in practise:
+% \begin{Verbatim}
+% \newopentypefeature{Style}{NoLocalForms}{-locl}
+% \begin{Verbatim}
 %
 % \DescribeMacro{\newfontfeature}
 % In case the above commands do not accommodate the desired font feature
@@ -2074,19 +2057,20 @@ This work consists of this file fontspec.dtx
 %
 % For example, Zapfino
 % contains the feature `Avoid d-collisions'. To access it
-% with this package, you could do the following:
-% \begin{aatexample}
+% with this package, you could do some like that shown in \exref{avoidd}
+%
+% \begin{Xexample}{avoidd}{Assigning new arbitary features.}
 %   \newfontfeature{AvoidD}{Special=Avoid d-collisions}
 %   \newfontfeature{NoAvoidD}{Special=!Avoid d-collisions}
 %   \fontspec[AvoidD,Variant=1]{Zapfino}
 %    sockdolager rubdown               \\
 %   \fontspec[NoAvoidD,Variant=1]{Zapfino}
 %    sockdolager rubdown
-% \end{aatexample}
+% \end{Xexample}
 %
 % The advantage to using the \cmd\newAATfeature\ and \cmd\newICUfeature\
-% commands is that they check if the selected font actually contains the font
-% feature. By contrast, \cmd\newfontfeature\ will not give a warning
+% commands instead of \cs{newfontfeature} is that they check if the selected font actually contains the desired font
+% feature at load time. By contrast, \cmd\newfontfeature\ will not give a warning
 % for improper input.
 %
 % \section{Going behind \pkg{fontspec}'s back}
@@ -2094,10 +2078,12 @@ This work consists of this file fontspec.dtx
 % while still taking advantage of its \LaTeX\ font selection conveniences. The
 % \feat{RawFeature} font feature allows literal \XeTeX\ font feature selection
 % when you happen to have the OpenType feature tag memorised.
-% \begin{example}
-%   \fontspec[RawFeature=+smcp]{FPL Neu}
-%   FPL Neu small caps
-% \end{example}
+%
+% \begin{Xexample}{raw}{Using raw font features directly.}
+%   \fontspec[RawFeature=+smcp]{TeX Gyre Pagella}
+%   Pagella small caps
+% \end{Xexample}
+%
 % Multiple features can either be included in a single declaration:\par
 % {\centering|[RawFeature=+smcp;+onum]|\par}
 % \noindent or with multiple declarations:\par
@@ -2109,12 +2095,14 @@ This work consists of this file fontspec.dtx
 % \DescribeMacro{\aliasfontfeature}
 % If you don't like the name of a particular font feature,
 % it may be aliased to another with the
-% \cs{aliasfontfeature}\marg{existing name}\marg{new name} command:
-% \begin{aatexample}
+% \cs{aliasfontfeature}\marg{existing name}\marg{new name} command,
+% such as shown in \exref{alias}.
+%
+% \begin{Xexample}{alias}{Renaming font features.}
 %   \aliasfontfeature{ItalicFeatures}{IF}
 %   \fontspec[IF = {Alternate=1}]{Hoefler Text}
 %   Roman Letters \itshape And Swash
-% \end{aatexample}
+% \end{Xexample}
 %
 % Spaces in feature (and option names, see below) \emph{are} allowed. (You may have
 % noticed this already in the lists of OpenType scripts and languages).
@@ -2122,13 +2110,15 @@ This work consists of this file fontspec.dtx
 % \DescribeMacro{\aliasfontfeatureoption}
 % If you wish to change the name of a font feature option,
 % it can be aliased to another with the command
-% \cs{aliasfontfeatureoption}\marg{font feature}\marg{existing name}\marg{new name}:
-% \begin{opentypeexample}
+% \cs{aliasfontfeatureoption}\marg{font feature}\marg{existing name}\marg{new name}, such as shown in \exref{aliasopt}.
+%
+% \begin{Lexample}{aliasopt}{Renaming font feature options.}
 %   \aliasfontfeature{VerticalPosition}{Vert Pos}
 %   \aliasfontfeatureoption{VerticalPosition}{ScientificInferior}{Sci Inf}
 %   \fontspec[Vert Pos=Sci Inf]{Warnock Pro}
 %    Scientific Inferior: 12345
-% \end{opentypeexample}
+% \end{Lexample}
+%
 % This example demonstrates an important point: when aliasing the feature
 % options, the \emph{original} feature name must be used when declaring
 % to which feature the option belongs.
@@ -2141,6 +2131,8 @@ This work consists of this file fontspec.dtx
 % \begin{Verbatim}
 %   \newfontfeature{PurpleColor}{color=550099BB}
 % \end{Verbatim}
+% Except that this example was written before support for named colours was
+% implemented. But you get the idea.
 %
 % \section{Programming details}
 %
@@ -2229,7 +2221,6 @@ This work consists of this file fontspec.dtx
 % \end{macro}
 %
 %  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %
-% \clearpage
 % \part{The patching/improvement of \LaTeXe\ and other packages}
 % \label{sec:patching}
 %
@@ -2246,7 +2237,7 @@ This work consists of this file fontspec.dtx
 %
 % \section{Unicode footnote symbols}
 % By default \LaTeX\ defines symbolic footnote characters in terms of commands
-% that don't resolve well; better results can be achieved by using specific unicode characters or proper LICRs with the \pkg{xunicode} package.
+% that don't resolve well; better results can be achieved by using specific Unicode characters or proper LICRs with the \pkg{xunicode} package.
 %
 % This problem has been solved by loading the 
 % \pkg{fixltx2e} and \pkg{xunicode} packages in \pkg{xltxtra}.
@@ -2254,9 +2245,9 @@ This work consists of this file fontspec.dtx
 % \section{Verbatim}
 % \label{sec:verb}
 %
-% Many verbatim mechanisms assume the existence of a `visible space' character that exists in the \textsc{ascii} space slot of the typewriter font. This character is known in unicode as \unichar{2434}{box open}, which looks like this: `\verb*| |'.
+% Many verbatim mechanisms assume the existence of a `visible space' character that exists in the \textsc{ascii} space slot of the typewriter font. This character is known in Unicode as \unichar{2434}{box open}, which looks like this: `\verb*| |'.
 %
-% When a unicode typewriter font is used, \LaTeX\ no longer prints visible spaces for the |verbatim*| environment and |\verb*| command. \pkg{xltxtra} fixes this problem by using the correct unicode glyph, and patches the following packages to do the same:
+% When a Unicode typewriter font is used, \LaTeX\ no longer prints visible spaces for the |verbatim*| environment and |\verb*| command. \pkg{xltxtra} fixes this problem by using the correct Unicode glyph, and patches the following packages to do the same:
 % \pkg{listings}, \pkg{fancyvrb}, \pkg{moreverb}, and \pkg{verbatim}.
 %
 % In the case that the typewriter font does not contain `\verb*| |', the Latin Modern Mono font is used as a fallback. 
@@ -2288,6 +2279,7 @@ This work consists of this file fontspec.dtx
 % \fi
 %    \begin{macrocode}
 \RequirePackage{expl3,xparse}
+\input binhex.tex  % before expl syntax!
 \ExplSyntaxOn
 %    \end{macrocode}
 %
@@ -2367,6 +2359,11 @@ This work consists of this file fontspec.dtx
 %    \end{macrocode}
 %
 %    \begin{macrocode}
+\cs_set:Npn \use_v:nnnnn #1#2#3#4#5 {#5}
+\cs_set:Npn \use_iv:nnnnn #1#2#3#4#5 {#4}
+%    \end{macrocode}
+%
+%    \begin{macrocode}
 \cs_new:Npn \fontspec_setkeys:xx #1#2
  {
   \use:x { \exp_not:N \setkeys*[zf]{#1}{#2} }
@@ -2428,7 +2425,22 @@ This work consists of this file fontspec.dtx
   loaded~ after~ euler.~ Type~ <return>~ to~ proceed\\
   with~ incorrect~ \string\mathit,~ \string\mathbf,~ etc.
 }
-
+\msg_new:nnnn {fontspec} {no-xcolor}
+{
+  Cannot~ load~ named~ colours~ without~ the~ xcolor~ package.
+}
+{
+  Sorry,~ I~ can't~ do~ anything~ to~ help.~ Instead~ of~ loading\\
+  the~ color~ package,~ use~ xcolor~ instead.~ It's~ better.
+}
+\msg_new:nnnn {fontspec} {unknown-color-model}
+{
+  Error~ loading~ colour~ `#1';~ unknown~ colour~ model.
+}
+{
+  Sorry,~ I~ can't~ do~ anything~ to~ help.~ Please~ report~ this~ error\\
+  to~ my~ developer~ with~ a~ minimal~ example~ that~ causes~ the~ problem.
+}
 %    \end{macrocode}
 % Warnings:
 %    \begin{macrocode}
@@ -2518,7 +2530,7 @@ This work consists of this file fontspec.dtx
 }
 \msg_new:nnn {fontspec} {no-scripts}
 {
-  Font~ \zf@fontname~ does not contain any OpenType `Script' information.
+  Font~ \zf@fontname\space does~ not~ contain~ any~ OpenType~ `Script'~ information.
 }
 %    \end{macrocode}
 %
@@ -2562,7 +2574,7 @@ This work consists of this file fontspec.dtx
 %
 % \subsection{Encodings}
 % Frank Mittelbach has recommended using the `\texttt{EU}$x$' family of font encodings
-% to experiment with unicode.
+% to experiment with Unicode.
 % Now that \XeTeX\ can find fonts in the |texmf| tree, the Latin Modern OpenType fonts
 % can be used as the defaults. See the |euenc| collection of files for how this is implemented.
 %    \begin{macrocode}
@@ -3176,6 +3188,9 @@ This work consists of this file fontspec.dtx
 % We want to store the actual name of the font family within the \meta{family}
 % variable because the actual \LaTeX\ family name is automatically generated
 % by fontspec and it's easier to keep it that way.
+%
+% Please use |\fontspec_set_family:Nnn| instead of |\fontspec_select:nn|,
+% which may change in the future.
 %    \begin{macrocode}
 \cs_new:Npn \fontspec_set_family:Nnn #1#2#3 {
   \fontspec_select:nn {#2}{#3}
@@ -3184,6 +3199,9 @@ This work consists of this file fontspec.dtx
 %    \end{macrocode}
 % \end{macro}
 %
+%
+%
+%
 % \subsection{Internal macros}
 % \label{sec:codeinternal}
 %
@@ -3196,21 +3214,12 @@ This work consists of this file fontspec.dtx
 % \begin{macro}{\fontspec_select:nn}
 % This is the command that defines font families for use, the underlying
 % procedure of all \cmd\fontspec-like commands. Given a
-% list of font features (|#1|) for a requested font (|#2|, stored
-% in \cs{zf@fontname} globally for the
-% \cs{zf@make@aat@feature@string} macro), it will define an NFSS
-% family for that font and put the family name into \cs{zf@family}.
-%
-% This macro does its processing inside a group, but it's a bit worthless coz
-% there's all sorts of \cmd\global\ action going on. Pity. Anyway, lots of things
-% are branched out for the pure reason of splitting
-% the code up into logical chunks. Some of it is never even re-used, so it
-% all might be a bit obfuscating. (\Eg, \cmd{\fontspec_init:} and \cmd{\fontspec_set_font_type:}.)
-%
-% First off, initialise some bits and pieces and run the |preparse| feature
-% processing. This catches font features such as |Renderer| that can change
-% the way subsequent features are processed. All font features that `slip through'
-% this stage are saved in the \cmd\zf@font@feat\ macro for future processing.
+% list of font features (|#1|) for a requested font (|#2|),
+% it will define an NFSS
+% family for that font and put the family name (globally) into \cs{zf@family}.
+% The \TeX\ `\cs{font}' command is (globally) stored in \cs{zf@basefont}.
+%
+% This macro does its processing inside a group to attempt to restrict the scope of its internal processing. This works to some degree to insulate the internal commands from having to be manually.
 %    \begin{macrocode}
 \cs_set:Npn \fontspec_select:nn #1#2 {
   \begingroup
@@ -3225,6 +3234,63 @@ This work consists of this file fontspec.dtx
   \let\zf@family@long\zf@fontname
   \let\zf@up\zf@fontname
 %    \end{macrocode}
+% Now convert the requested features to font definition
+% strings. First the features are parsed for information about font
+% loading (whether it's a named font or external font, etc.), and then
+% information is extracted for the names of the other shape fonts.
+%
+% Then the mapping from user features to low-level features occurs.
+% This is performed with \cs{fontspec_get_features:n}, in
+% which \cs{setkeys} retrieves the requested font features and
+% processes them. As \cs{setkeys} is run multiple times, some of its
+% information storing only occurs once while we decide if the font family
+% has been defined or not. When the later processing is occuring per-shape
+% this no longer needs to happen; this is indicated by the `firsttime'
+% conditional.
+%    \begin{macrocode}
+  \fontspec_preparse_features:nn {#1}{#2}
+  \fontspec_set_scriptlang:
+  \fontspec_get_features:n {\zf@font@feat}
+  \zf@firsttimefalse
+%    \end{macrocode}
+% Check if the family is unique and, if so, save its information.
+% (\cs{addfontfeature} and other macros use this data.)
+% Then the font family and its shapes are defined in the NFSS.
+%
+% All NFSS specifications take their default values, so if any of them
+% are redefined, the shapes will be selected to fit in with the
+% current state. For example, if \cmd\bfdefault\ is redefined to |b|, all
+% bold shapes defined by this package will also be assigned to |b|.
+%    \begin{macrocode}
+  \fontspec_save_family:nT {#2} {
+    \fontspec_info:nxx {defining-font} {#1} {#2}
+    \fontspec_save_fontinfo:nn {#1} {#2}
+    \DeclareFontFamily{\zf@enc}{\zf@family}{}
+    \fontspec_set_upright:
+    \fontspec_set_bold:
+    \fontspec_set_italic:
+    \fontspec_set_slanted:
+    \fontspec_set_bold_italic:
+    \fontspec_set_bold_slanted:
+  }
+  \endgroup
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\zf@fontspec}
+% For backwards compatibility. Do not use this from now on!
+%    \begin{macrocode}
+\cs_set_eq:NN \zf@fontspec \fontspec_select:nn
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\fontspec_preparse_features:nn}
+% Perform the (multi-step) feature parsing process.
+%    \begin{macrocode}
+\cs_new:Npn \fontspec_preparse_features:nn #1#2 {
+%    \end{macrocode}
 % Detect if external fonts are to be used, possibly automatically, and
 % parse fontspec features for bold/italic fonts and their features.
 %    \begin{macrocode}
@@ -3240,80 +3306,117 @@ This work consists of this file fontspec.dtx
   \fontspec_setkeys:xx {preparse} {\XKV@rm}
   \let\zf@font@feat\XKV@rm
 %    \end{macrocode}
+% Finally save the `confirmed' font definition.
 %    \begin{macrocode}
-  \global\font\zf@basefont="\fontspec_fullname:n {\zf@up}"~at~\f@size pt
+  \font\zf@basefont="\fontspec_fullname:n {\zf@up}"~at~\f@size pt
   \fontspec_set_font_type:
   \global\font\zf@basefont="\fontspec_fullname:n {\zf@up}"~at~\f@size pt
+  \zf@basefont % this is necessary for LuaLaTeX to check the scripts properly
+}
 %    \end{macrocode}
-% Now convert the remaining requested features to font definition
-% strings. This is performed with \cs{zf@get@feature@requests}, in
-% which \cs{setkeys} retrieves the requested font features and
-% processes them. To build up the complex family name, it
-% concatenates each font feature with the family name of the
-% font. So since \cs{setkeys} is run more than once (since different
-% font faces may have different feature names), we only want the
-% complex family name to be built up once, hence the \cs{zf@firsttime}
-% conditionals.
+% \end{macro}
+%
+%
+% \begin{macro}{\fontspec_if_detect_external:nT}
+% Check if either the fontname ends with a known font extension.
 %    \begin{macrocode}
-  \zf@firsttimetrue
-    \ifzf@icu
-      \tl_if_empty:NTF \l_fontspec_script_name_tl {
-        \fontspec_check_script:nTF {latn}
-        {
-          \tl_set:Nn \l_fontspec_script_name_tl {Latin}
-          \tl_set:Nn \l_fontspec_script_tl      {latn}
-          \tl_if_empty:NT \l_fontspec_lang_tl {
-            \tl_set:Nn \l_fontspec_lang_name_tl {Default}
-            \tl_set:Nn \l_fontspec_lang_tl      {DFLT}
-          }
-          \fontspec_setkeys:xxx {feat} {Script} {\l_fontspec_script_name_tl}
-          \fontspec_setkeys:xxx {feat} {Lang}   {\l_fontspec_lang_name_tl}
-        }
-        {
-          \fontspec_info:n {no-scripts}
-        }
-      }
-      {
-        \fontspec_setkeys:xxx {feat} {Script} {\l_fontspec_script_name_tl}
-        \fontspec_setkeys:xxx {feat} {Lang}   {\l_fontspec_lang_name_tl}
-      }
-    \fi
-    \fontspec_get_features:n{\zf@font@feat}
-  \zf@firsttimefalse
+\prg_new_conditional:Nnn \fontspec_if_detect_external:n {T}
+ {
+  \clist_map_inline:Nn \l_fontspec_extensions_clist
+   {
+    \bool_set_false:N \l_tmpa_bool
+    \tl_if_in:nnT {#1 <= end_of_string} {##1 <= end_of_string}
+      { \bool_set_true:N \l_tmpa_bool \clist_map_break: }
+   }
+  \bool_if:NTF \l_tmpa_bool \prg_return_true: \prg_return_false:
+ }
 %    \end{macrocode}
-% Now we have a unique (in fact, too unique!) string that contains
+% \end{macro}
+%
+% \begin{macro}{\fontspec_fullname:n}
+% Constructs the complete font name based on a common piece of info.
+%    \begin{macrocode}
+\cs_set:Npn \fontspec_fullname:n #1 {
+  \fontspec_namewrap:n { #1 \l_fontspec_extension_tl }
+  \l_fontspec_renderer_tl
+  \l_fontspec_optical_size_tl
+}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\fontspec_save_family:nT}
+%% Now we have a unique (in fact, too unique!) string that contains
 % the family name and every option in abbreviated form. This is used
 % with a counter to create a simple NFSS family name for the font we're
 % selecting.
 %
 % The font name is fully expanded, in case it's defined in terms of macros, before having its spaces zapped.
 %    \begin{macrocode}
+\prg_new_conditional:Nnn \fontspec_save_family:n {T} {
   \unless\ifcsname zf@UID@\zf@family@long\endcsname
-    \ifcsname c@zf@famc@#2\endcsname
+    \ifcsname c@zf@famc@#1\endcsname
       \expandafter\global\expandafter\advance
-        \csname c@zf@famc@#2\endcsname\@ne
+        \csname c@zf@famc@#1\endcsname\@ne
     \else
       \expandafter\global\expandafter\newcount
-        \csname c@zf@famc@#2\endcsname
+        \csname c@zf@famc@#1\endcsname
     \fi
-    \edef\@tempa{#2~}
+    \edef\@tempa{#1~}
     \cs_gset:cpx{zf@UID@\zf@family@long}{
       \expandafter\zap@space\@tempa\@empty
-      (\expandafter\the\csname c@zf@famc@#2\endcsname)
+      (\expandafter\the\csname c@zf@famc@#1\endcsname)
     }
   \fi
   \xdef\zf@family{\@nameuse{zf@UID@\zf@family@long}}
+  \cs_if_exist:cTF {zf@family@fontname\zf@family}
+    \prg_return_false: \prg_return_true:
+}
 %    \end{macrocode}
+% \end{macro}
 %
-% Now that we have the family name, we
-% can check to see if the family has already been defined, and if not,
-% do so. Once the family name is created, use it to create global
-% macros to save the user
-% string of the requested options and font name, primarily for use with
-% \cs{addfontfeatures}.
+% \begin{macro}{\fontspec_set_scriptlang:}
+% Only necessary for OpenType fonts.
+% First check if the font supports scripts, then apply defaults if
+% none are explicitly requested. Similarly with the language settings.
 %    \begin{macrocode}
-  \unless\ifcsname zf@family@fontname\zf@family\endcsname
-    \fontspec_info:nxx {defining-font} {#1} {#2}
+\cs_new:Npn \fontspec_set_scriptlang: {
+  \ifzf@icu
+    \tl_if_empty:NTF \l_fontspec_script_name_tl {
+      \fontspec_check_script:nTF {latn}
+      {
+        \tl_set:Nn \l_fontspec_script_name_tl {Latin}
+        \tl_set:Nn \l_fontspec_script_tl      {latn}
+        \tl_if_empty:NT \l_fontspec_lang_tl {
+          \tl_set:Nn \l_fontspec_lang_name_tl {Default}
+          \tl_set:Nn \l_fontspec_lang_tl      {DFLT}
+        }
+        \fontspec_setkeys:xxx {feat} {Script} {\l_fontspec_script_name_tl}
+        \fontspec_setkeys:xxx {feat} {Lang}   {\l_fontspec_lang_name_tl}
+      }
+      {
+        \fontspec_info:n {no-scripts}
+      }
+    }
+    {
+      \tl_if_empty:NT \l_fontspec_lang_tl {
+        \tl_set:Nn \l_fontspec_lang_name_tl {Default}
+        \tl_set:Nn \l_fontspec_lang_tl      {DFLT}
+      }
+      \fontspec_setkeys:xxx {feat} {Script} {\l_fontspec_script_name_tl}
+      \fontspec_setkeys:xxx {feat} {Lang}   {\l_fontspec_lang_name_tl}
+    }
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\fontspec_save_fontinfo:nn}
+% Saves the relevant font information for future processing.
+%    \begin{macrocode}
+\cs_new:Npn \fontspec_save_fontinfo:nn #1#2 {
     \tl_gset:cx {zf@family@fontname\zf@family} {#2}
     \tl_gset:cx {zf@family@options\zf@family} {\zf@default@options #1}
     \tl_gset:cx {zf@family@fontdef\zf@family} {
@@ -3325,71 +3428,27 @@ This work consists of this file fontspec.dtx
       { \int_use:N \c@zf@language }
     \tl_gset_eq:cN {g_fontspec_script_(\zf@family)_tl} \l_fontspec_script_tl
     \tl_gset_eq:cN {g_fontspec_lang_(\zf@family)_tl}   \l_fontspec_lang_tl
-%    \end{macrocode}
-% Next the font family and its shapes are defined in the NFSS.
-%
-% All NFSS specifications take their default values, so if any of them
-% are redefined, the shapes will be selected to fit in with the
-% current state. For example, if \cmd\bfdefault\ is redefined to |b|, all
-% bold shapes defined by this package will also be assigned to |b|.
-%
-% The macros \cs{zf@bf}, et al., are used to store the name of the
-% custom bold, et al., font, if requested as user options. If they are
-% empty, the default fonts are used.
-%
-% First we define the font family and define the normal shape: (any shape-specific
-% features are appended to the generic font features requested in the last argument
-% of \cmd\zf@make@font@shapes.)
-%    \begin{macrocode}
-    \DeclareFontFamily{\zf@enc}{\zf@family}{}
-    \zf@make@font@shapes{\zf@fontname}
-      {\mddefault}{\updefault}{\zf@font@feat\zf@up@feat}
-%    \end{macrocode}
-% And the different shapes are set accordingly.
-%    \begin{macrocode}
-    \fontspec_set_bold:
-    \fontspec_set_italic:
-    \fontspec_set_slanted:
-    \fontspec_set_bold_italic:
-    \fontspec_set_bold_slanted:
-  \fi
-  \endgroup
 }
 %    \end{macrocode}
 % \end{macro}
 %
 %
-% \begin{macro}{\fontspec_if_detect_external:nT}
-% Check if either the fontname ends with a known font extension.
+% \begin{macro}{\fontspec_set_upright:}
+% Sets the upright shape.
 %    \begin{macrocode}
-\prg_new_conditional:Nnn \fontspec_if_detect_external:n {T}
- {
-  \clist_map_inline:Nn \l_fontspec_extensions_clist
-   {
-    \bool_set_false:N \l_tmpa_bool
-    \tl_if_in:nnT {#1 <= end_of_string} {##1 <= end_of_string}
-      { \bool_set_true:N \l_tmpa_bool \clist_map_break: }
-   }
-  \bool_if:NTF \l_tmpa_bool \prg_return_true: \prg_return_false:
- }
-%    \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\fontspec_fullname:n}
-% Constructs the complete font name based on a common piece of info.
-%    \begin{macrocode}
-\cs_set:Npn \fontspec_fullname:n #1 {
-  \fontspec_namewrap:n { #1 \l_fontspec_extension_tl }
-  \l_fontspec_renderer_tl
-  \l_fontspec_optical_size_tl
+\cs_new:Npn \fontspec_set_upright: {
+  \zf@make@font@shapes{\zf@fontname}
+    {\mddefault}{\updefault}{\zf@font@feat\zf@up@feat}
 }
 %    \end{macrocode}
 % \end{macro}
 %
-%
-%
 % \begin{macro}{\fontspec_set_bold:}
-% Again, the extra bold options defined with
+% The macros \cs{zf@bf}, et al., are used to store the name of the
+% custom bold, et al., font, if requested as user options. If they are
+% empty, the default fonts are used.
+%
+% The extra bold options defined with
 % \feat{BoldFeatures} are appended to the generic font features.
 % Then, the bold font is defined either as the ATS
 % default (\cs{zf@make@font@shapes}' optional argument is to check if
@@ -3450,6 +3509,7 @@ This work consists of this file fontspec.dtx
   \@tempswatrue
   \ifzf@nobf\@tempswafalse\fi
   \ifzf@noit\@tempswafalse\fi
+  \bool_if:NT \l_fontspec_external_bool \@tempswafalse
   \if@tempswa
     \ifx\zf@bfit\@empty
       \ifx\zf@bf\@empty
@@ -3570,7 +3630,7 @@ This work consists of this file fontspec.dtx
     \else
       \edef\zf@fontname{#1#2}
       \let\zf@basefont\@tempfontb
-      \zf@DeclareFontShape{#3}{#4}{#5}
+      \fontspec_declare_shape:nnnn {}{#3}{#4}{#5}
 %    \end{macrocode}
 % Next, the small caps are defined. \cs{zf@make@smallcaps} is used to
 % define the appropriate string for activating small caps in the font,
@@ -3584,13 +3644,13 @@ This work consists of this file fontspec.dtx
         \unless\ifzf@nosc
           \zf@make@smallcaps
           \unless\ifx\zf@smallcaps\@empty
-            \zf@DeclareFontShape[\zf@smallcaps]{#3}
+            \fontspec_declare_shape:nnnn {\zf@smallcaps}{#3}
               {\ifx#4\itdefault\sidefault\else\scdefault\fi}{#5\zf@sc@feat}
           \fi
         \fi
       \else
         \edef\zf@fontname{\zf@sc}
-        \zf@DeclareFontShape{#3}
+        \fontspec_declare_shape:nnnn {}{#3}
           {\ifx#4\itdefault\sidefault\else\scdefault\fi}{#5\zf@sc@feat}
       \fi
     \fi
@@ -3601,14 +3661,14 @@ This work consists of this file fontspec.dtx
 % only works while \cmd\fontspec_select:nn\ passes single tokens to this macro\dots
 % \end{macro}
 %
-% \begin{macro}{\zf@DeclareFontShape}
-% \doarg{Raw appended font feature}
+% \begin{macro}{\fontspec_declare_shape:nnnn}
+% \darg{Raw appended font feature}
 % \darg{Font series}
 % \darg{Font shape}
 % \darg{Font features}
 % Wrapper for \cmd\DeclareFontShape.
 %    \begin{macrocode}
-\newcommand\zf@DeclareFontShape[4][]{
+\cs_new:Npn \fontspec_declare_shape:nnnn #1#2#3#4 {
   \clist_if_empty:NTF \l_fontspec_sizefeat_clist
   {
     \fontspec_get_features:n{#4}
@@ -3644,6 +3704,10 @@ This work consists of this file fontspec.dtx
 % \cmd\zf@adjust\ is defined in various places to deal with things like the hyphenation
 % character and interword spacing.
 %    \begin{macrocode}
+  \PackageInfo{fontspec}{
+    Defining~ shape~ #2/#3~ with~ raw~ font~ features:
+    \MessageBreak \l_fontspec_rawfeatures_sclist
+  \@gobble}
   \use:x{
     \exp_not:N\DeclareFontShape{\zf@enc}{\zf@family}{#2}{#3}
       {\l_fontspec_nfss_tl}{\zf@adjust}
@@ -3724,7 +3788,12 @@ This work consists of this file fontspec.dtx
   \tl_if_empty:NF \XKV@rm {
     \fontspec_error:nx {unknown-options} { \exp_not:V \XKV@rm }
   }
-  \PackageInfo{fontspec}{Raw~ font~ features~ "\l_fontspec_rawfeatures_sclist"}
+%    \end{macrocode}
+% Finish the colour specification:
+%    \begin{macrocode}
+  \cs_if_exist:NT \l_fontspec_hexcol_tl {
+    \zf@update@ff{color=\l_fontspec_hexcol_tl\l_fontspec_opacity_tl}
+  }
 }
 %    \end{macrocode}
 % \end{macro}
@@ -3753,6 +3822,7 @@ This work consists of this file fontspec.dtx
 \tl_clear:N \l_fontspec_lang_name_tl
 \tl_clear:N \l_fontspec_lang_tl
 \clist_clear:N \l_fontspec_sizefeat_clist
+\tl_set:Nn \l_fontspec_opacity_tl {FF}
 %    \end{macrocode}
 % Or once per fontspec font invocation:
 % (Some of these may be redundant.
@@ -3760,7 +3830,10 @@ This work consists of this file fontspec.dtx
 %    \begin{macrocode}
 \newcommand*\fontspec_init:{
   \zf@icufalse
-  \cs_set_eq:NN \fontspec_namewrap:n \use:n
+  \zf@firsttimetrue
+  \xetex_or_luatex:nnn { \cs_set:Npn \fontspec_namewrap:n ##1 }
+    { ##1 }
+    { name:##1 }
   \tl_clear:N \l_fontspec_optical_size_tl
   \tl_clear:N \l_fontspec_renderer_tl
   \luatex_if_engine:T {
@@ -3851,6 +3924,10 @@ This work consists of this file fontspec.dtx
     \fontspec_make_ICU_feature:n {#3}
   }
 }
+\cs_generate_variant:Nn \fontspec_make_feature:nnn {nnx}
+%    \end{macrocode}
+%
+%    \begin{macrocode}
 \cs_new:Npn \fontspec_make_AAT_feature:nn #1#2 {
   \tl_if_empty:nTF {#1}
   {
@@ -4148,7 +4225,9 @@ This work consists of this file fontspec.dtx
   \zf@nobftrue
   \zf@noittrue
   \bool_set_true:N \l_fontspec_external_bool
-  \cs_gset:Npn \fontspec_namewrap:n ##1 { [ #1 ##1 ] }
+  \xetex_or_luatex:nnn { \cs_gset:Npn \fontspec_namewrap:n ##1 }
+    {     [ #1 ##1 ] }
+    { file: #1 ##1   }
   \xetex_if_engine:T { \setkeys[zf]{preparse}{Renderer=ICU} }
 }
 \aliasfontfeature{ExternalLocation}{Path}
@@ -4342,7 +4421,7 @@ This work consists of this file fontspec.dtx
 % TODO: sizezfeatures and italicfont (etc) don't play nice
 %    \begin{macrocode}
 \define@key[zf]{preparse}{SizeFeatures}{
-  \unless\ifzf@firsttime\def\l_fontspec_sizefeat_clist{#1}\fi
+  \tl_set:Nn \l_fontspec_sizefeat_clist {#1}
   \zf@update@family{sizefeat:\zap@space #1~\@empty}
 }
 %    \end{macrocode}
@@ -4397,29 +4476,33 @@ This work consists of this file fontspec.dtx
   \group_end:
 }
 %    \end{macrocode}
-% This function sets the dimension |#1| (for font |#3|) to what would be known
-% as the `fontdimen' |#2| in \TeX\ but apparently isn't set that way in
-% \LuaTeX.
+% \end{macro}
+%
+%
+% \begin{macro}{\fontspec_set_font_dimen:NnN}
+% This function sets the dimension |#1| (for font |#3|) to `fontdimen' |#2|
+% for either font dimension 5 (x-height) or 8 (cap-height). If, for some
+% reason, these return an incorrect `zero' value (as \cs{fontdimen8} might
+% for a \texttt{.tfm} font), then we cheat and measure the height of a glyph.
+% We assume in this case that the font contains either an `X' or an `x'.
 %    \begin{macrocode}
-\xetex_or_luatex:nnn { \cs_new:Npn \fontspec_set_font_dimen:NnN #1#2#3 }
+\cs_new:Npn \fontspec_set_font_dimen:NnN #1#2#3
 {
   \dim_set:Nn #1 { \fontdimen #2 #3 }
-}
-%    \end{macrocode}
-% In Lua\TeX, fall back to manual calculations if necessary:
-%    \begin{macrocode}
-{
-  \dim_set:Nn #1 { \directlua{ fontspec.get_dimen(#2, "\cs_to_str:N #3") } }
   \dim_compare:nNnT #1 = {0pt} {
     \settoheight #1 {
       \tl_if_eq:nnTF {#3} {\font} \rmfamily #3
-      \prg_case_int:nnn #2 { 5 x 8 X } {?}
+      \prg_case_int:nnn #2 {
+        {5} {x} % x-height
+        {8} {X} % cap-height
+      } {?} % "else" clause; never reached.
     }
   }
 }
 %    \end{macrocode}
 % \end{macro}
 %
+%
 % \paragraph{Inter-word space}
 % These options set the relevant \cmd\fontdimen s for the
 % font being loaded.
@@ -4537,10 +4620,27 @@ This work consists of this file fontspec.dtx
 %    \begin{macrocode}
 \define@key[zf]{options}{Color}{
   \zf@update@family{+col:#1}
-  \zf@update@ff{color=#1}
+  \cs_if_exist:cTF {\token_to_str:N\color@#1}
+  {
+    \convertcolorspec{named}{#1}{HTML}\l_fontspec_hexcol_tl
+  }
+  {
+    \tl_set:Nn \l_fontspec_hexcol_tl {#1}
+  }
 }
 \keyval@alias@key[zf]{options}{Color}{Colour}
 %    \end{macrocode}
+%    \begin{macrocode}
+\newcounter{fontspec_tmp_int}
+\define@key[zf]{options}{Opacity}{
+  \zf@update@family{+opac:#1}
+  \setcounter {fontspec_tmp_int} { 255*\real{#1} }
+  \tl_set:Nx \l_fontspec_opacity_tl {
+    \nhex2 { \value{fontspec_tmp_int} }
+  }
+}
+%    \end{macrocode}
+%
 %
 % \paragraph{Mapping}
 %    \begin{macrocode}
@@ -4827,21 +4927,25 @@ This work consists of this file fontspec.dtx
 %
 %    \begin{macrocode}
 \define@key[zf]{options}{Alternate}[0]{
+  \clist_set_eq:NN \l_fontspec_tmpa_clist \XKV@rm
   \setkeys*[zf@feat]{Alternate}{#1}
   \unless\ifx\XKV@rm\@empty
     \def\XKV@tfam{Alternate}
     \fontspec_make_feature:nnn{17}{#1}{+salt=#1}
   \fi
+  \clist_set_eq:NN \XKV@rm \l_fontspec_tmpa_clist
 }
 %    \end{macrocode}
 %
 %    \begin{macrocode}
 \define@key[zf]{options}{Variant}{
+  \clist_set_eq:NN \l_fontspec_tmpa_clist \XKV@rm
   \setkeys*[zf@feat]{Variant}{#1}
   \unless\ifx\XKV@rm\@empty
     \def\XKV@tfam{Variant}
-    \fontspec_make_feature:nnn{18}{#1}{+ss\two@digits{#1}}
+    \fontspec_make_feature:nnx{18}{#1}{+ss\two@digits{#1}}
   \fi
+  \clist_set_eq:NN \XKV@rm \l_fontspec_tmpa_clist
 }
 \aliasfontfeature{Variant}{StylisticSet}
 %    \end{macrocode}
@@ -4889,9 +4993,7 @@ This work consists of this file fontspec.dtx
 %
 % \subsubsection{Annotation}
 %    \begin{macrocode}
-\zf@define@font@feature{Annotation}
-\zf@define@feature@option{Annotation}{Off}{24}{0}{-nalt}
-\zf@define@feature@option{Annotation}{On}{}{}{+nalt}
+\zf@define@feature@option{Annotation}{Off}{24}{0}{}
 \zf@define@feature@option{Annotation}{Box}{24}{1}{}
 \zf@define@feature@option{Annotation}{RoundedBox}{24}{2}{}
 \zf@define@feature@option{Annotation}{Circle}{24}{3}{}
@@ -4905,6 +5007,17 @@ This work consists of this file fontspec.dtx
 \zf@define@feature@option{Annotation}{DoubleCircle}{24}{11}{}
 %    \end{macrocode}
 %
+%    \begin{macrocode}
+\define@key[zf]{options}{Annotation}[0]{
+  \clist_set_eq:NN \l_fontspec_tmpa_clist \XKV@rm
+  \setkeys*[zf@feat]{Annotation}{#1}
+  \unless\ifx\XKV@rm\@empty
+    \def\XKV@tfam{Alternate}
+    \fontspec_make_feature:nnn{}{}{+nalt=#1}
+  \fi
+  \clist_set_eq:NN \XKV@rm \l_fontspec_tmpa_clist
+}
+%    \end{macrocode}
 %
 % \subsubsection{Vertical}
 %    \begin{macrocode}
@@ -5643,42 +5756,16 @@ function fontspec.check_ot_feat(fnt, feat, lang, script)
     end
 end
 
-%    \end{macrocode}
-% Get font dimens for \cs{fontspec_calc_scale:n} (despite the name of this function,
-% it doesn't return any arbitrary font dimen, only \cmd\dimen5 and \cmd\dimen8.)
-%    \begin{macrocode}
-
-function fontspec.get_dimen(fontdimen, csname)
-    local id, h, em, pt
-    if csname == "font" then
-        id = font.current()
-    else
-        id = font_id(csname)
-    end
-    if fontdimen == 8 then
-        h = fonts.ids[id].shared.otfdata.pfminfo.os2_capheight
-    elseif fontdimen == 5 then
-        h = fonts.ids[id].shared.otfdata.pfminfo.os2_xheight
-    end
-    em = fonts.ids[id].shared.otfdata.metadata.units_per_em
-    pt = fonts.ids[id].size / 65536
-    tex.sprint(string.format("%spt", (h/em)*pt))
-end
-
-function fontspec.charglyph(char, csname)
-    local id, c
+function fontspec.charglyph(char)
     if char then
+        local id, c
         if utf.len(char) > 1 then
             c = utf.byte(utf.char(char:gsub('"', '0x')))
         else
             c = utf.byte(char)
         end
 
-        if csname then
-            id = font_id(csname)
-        else
-            id = font.current()
-        end
+        id = font.current()
 
         if font.fonts[id]["characters"][c] then
             return font.fonts[id]["characters"][c].index
@@ -5892,11 +5979,19 @@ end
 %
 % \iffalse
 %</cfg>
-%<*example>
 % \fi
 %
 % \clearpage
-% \part{Example documents}
+% \PrintChanges
+%
+% \clearpage
+% \setcounter{IndexColumns}{2}
+% \PrintIndex
+%
+% \Finale
+%
+% \iffalse
+%<*example>
 %
 %    \begin{macrocode}
 %<luatex>% !TEX TS-program = LuaLaTeX
@@ -5953,20 +6048,71 @@ information.
 \end{document}
 %    \end{macrocode}
 %
-% \iffalse
 %</example>
-% \fi
-%
-% \clearpage
-% \PrintChanges
+%<*testsuite>
 %
-% \clearpage
-% \setcounter{IndexColumns}{2}
-% \PrintIndex
-%
-% \Finale
+%    \begin{macrocode}
+\documentclass{article}
+\usepackage{fontspec,fancyvrb,geometry,graphicx,calc,multicol}
+\geometry{margin=2cm,a4paper}
+\setmainfont[Ligatures=TeX]{TeX Gyre Pagella}
+\setmonofont{Consolas}
+
+\newcommand\meta[1]{$\langle$\emph{#1}$\rangle$}
+
+\newcommand\TEST[1]{%
+  \section{Test #1}
+  \begin{minipage}{0.5\textwidth}
+  \VerbatimInput{testsuite/#1.ltx}
+  \end{minipage}
+  \hfill
+  \begin{minipage}{8cm+4pt}
+    \fboxsep=1pt
+    \fboxrule=1pt
+    \fbox{\includegraphics[width=8cm]{testsuite/#1.safe.pdf}}
+  \end{minipage}
+}
+
+\newcommand\codeline[1]{\par{\centering#1\par}\par\noindent\ignorespaces}
+
+\pagestyle{empty}
+\begin{document}
+\title{The \textsf{fontspec} test suite}
+\author{Will Robertson}
+\date{Compiled: \today}
+\maketitle
+\thispagestyle{empty}
+
+\section*{Preamble}
+
+\begin{multicols}{2}\noindent
+The examples shown in the remainder of the document are generated directly from the code shown alongside.
+As well as being good minimal examples, these tests are useful to ensure that changes to \textsf{fontspec} don't affect old behaviour.
+
+When the test suite is run, the new output is compared pixel by pixel with that shown here and warnings produced if the outputs are not identical (within a small tolerance to account for rounding errors).
+
+Tests with a name that begins with `\textit X' are processed with \texttt{xelatex} only; `\textit L' with \texttt{lualatex}; and `\textit F' with both.
+In the latter case, the output from both engines is compared with each other, ensuring that the package is consistent cross-platform.
+
+To generate tests yourself, write a new file in the \texttt{testsuite/} folder with filename
+\codeline{\meta{F,L,X}\meta{num}\meta{letter}\texttt{.ltx}}
+according to the naming scheme above and the following numbering scheme. If you are writing a new test entirely, increment the \meta{num}; if you are writing a variation on an old test, increment the \meta{letter}. No need to be too fussy, though.
+
+After writing the new test, run
+\codeline{\texttt{make initest}}
+This will generate the reference output (\texttt{*.safe.pdf}) from which to check all future tests.
+After any changes have been made to \textsf{fontspec}, the entire test suite is compiled with \codeline{\texttt{make check}}
+If you want to run just a single test, use
+\codeline{\texttt{make }\meta{testname}}
+(but this syntax \emph{may} be fragile and need to be changed in the future).
+\end{multicols}
+
+\input{testsuite/testsuite-listing.tex}
+
+\end{document}
+%    \end{macrocode}
+%</testsuite>
 %
-% \iffalse
 %<*doc-style>
 %    \begin{macrocode}
 \ProvidesPackage{fontspec-style}
@@ -6014,57 +6160,106 @@ information.
 \labelformat{section}{Section~#1}
 \labelformat{subsection}{Section~#1}
 
-%% verbatim examples:
 \definecolor{niceblue}{rgb}{0.1,0.2,0.8}
-\newenvironment{example}
-  {\VerbatimEnvironment
-   \begin{VerbatimOut}{\examplefilename}}
-  {\end{VerbatimOut}\relax
-   \begingroup
-     \color{niceblue}
-     \typesetexample
-   \endgroup}
 
-\newlength\examplewidth\newlength\verbatimwidth
-\newlength\exoutdent   \newlength\exverbgap
-\setlength\exverbgap{1em}
-\setlength\exoutdent{-0.15\textwidth}
-\newsavebox\verbatimbox
-\edef\examplefilename{\jobname.example}
+\newsavebox\X
+\newsavebox\Y
+
+\newcounter{example}
+
+\newcommand\exref[1]{Example~\ref{ex:#1}}
+\newcommand\Exref[1]{Example~\ref{ex:#1}}
+
+\newenvironment{Xexample}[3][]
+  {\VerbatimEnvironment\begin{Fexample}[#1]{#2}{#3}{X}}
+  {\end{Fexample}}
+
+\newenvironment{Lexample}[3][]
+  {\VerbatimEnvironment\begin{Fexample}[#1]{#2}{#3}{L}}
+  {\end{Fexample}}
+
+
+
+\newenvironment{Fexample}[4][]
+  {%
+    \def\options{#1}%
+    \def\filename{#2}%
+    \def\captiontext{#3}%
+    \def\prefix{#4}
+    \refstepcounter{example}%
+    \label{ex:\filename}%
+    \IfFileExists{doc/\theexample-\prefix-\filename.tex}{}{%
+      \immediate\write18{cd doc && rm \theexample-* ;}%
+    }%
+    \VerbatimEnvironment
+    \begin{VerbatimOut}{doc/\theexample-\prefix-\filename.tex}}
+% text in the environment
+  {\end{VerbatimOut}
+    \begin{figure}
+      \setlength\parindent{0pt}%
+      \edef\@tempa{[gobble=0,fontsize=\noexpand\small,\options]}%
+      \savebox\X{%
+                  \expandafter\BVerbatimInput
+                  \@tempa{doc/\theexample-\prefix-\filename.tex}%
+                }%
+      \IfFileExists{doc/\theexample-\prefix-\filename.pdf}{}
+         {%
+           \edef\1{%
+             cd doc; \csname prog@\prefix\endcsname
+             "%
+             \unexpanded{%
+               \documentclass{article}%
+               \usepackage{booktabs,ifthen,graphicx,xcolor,varwidth}
+               \usepackage[active,tightpage]{preview}%
+               \usepackage{fontspec}%
+               \defaultfontfeatures{Ligatures=TeX} \begin{document}\begin{preview}\begin{varwidth}{0.7\linewidth}\input} \theexample-\prefix-\filename.tex
+             \unexpanded{\end{varwidth}\end{preview}\end{document}}
+             "
+           }%
+           \immediate\write18{
+              mkdir -p doc;
+              cp -a fontspec.dtx doc/;
+              cd doc;
+              tex fontspec.dtx > /dev/null ;
+           }
+           \immediate\write18{\unexpanded\expandafter{\1}}%
+         }%
+      \savebox\Y{%
+      \IfFileExists{doc/\theexample-\prefix-\filename.pdf}
+          {\includegraphics{doc/\theexample-\prefix-\filename.pdf}}
+          {Graphic not generated.}%
+      }
+      % TYPESETTING
+      \rule[0.5\baselineskip]{\columnwidth}{1pt}%
+      \vspace{-1.2ex}%
+      \def\@tempa{\small\textsf{Example~\theexample:~}}%
+      \settowidth\@tempdima{\@tempa\captiontext}%
+      \par
+      \ifdim\@tempdima>\linewidth
+        \settowidth\@tempdima{\@tempa}%
+        \@tempa\parbox[t]{\linewidth-\@tempdima}{\small\captiontext}%
+        \vspace{0.4\baselineskip}%
+      \else
+        \parbox{\linewidth}{\centering\@tempa~\captiontext}%
+      \fi
+      \par\rule[0.4\baselineskip]{\columnwidth}{1pt}\par
+      \ifdim\dimexpr\wd\X+\wd\Y>\linewidth\relax
+        \null\hfill\makebox[0pt][r]{\usebox\Y}\usebox\X
+      \else
+        \hfill\usebox\Y\hfill\usebox\X
+      \fi
+      \par\rule[0.5\baselineskip]{\columnwidth}{1pt}
+    \end{figure}
+}
 
-\newcommand\typesetexample{\relax
-   \begin{lrbox}{\verbatimbox}\relax
-     \BVerbatimInput[fontsize=\small,firstline=\firstline,lastline=\lastline]{\examplefilename}\relax
-   \end{lrbox}
-   \begin{list}{}{\setlength\itemindent{0pt}
-                  \setlength\leftmargin\exoutdent
-                  \setlength\rightmargin{0pt}}\item
-   \ifx\auxwidth\relax
-     \setlength\verbatimwidth{\wd\verbatimbox}\relax
-   \else
-     \setlength\verbatimwidth{\auxwidth}\relax
-     \let\auxwidth\relax
-   \fi
-%   \begin{minipage}[c]{\textwidth-\exoutdent-\verbatimwidth-\exverbgap}
-%     \catcode`\%=14\centering\examplesize\input\examplefilename\relax
-%   \end{minipage}\hfill
-   \centering
-   \begin{minipage}[c]{\verbatimwidth}
-     \usebox\verbatimbox
-   \end{minipage}
-   \end{list}
-   \global\let\examplesize\normalsize
-   \gdef\firstline{1}\gdef\lastline{}\par\noindent}
+\def\prog@X{xelatex
+               -output-driver=xdv2pdf\space
+               -jobname=\theexample-X-\filename\space}
 
-\let\examplesize\normalsize
-\let\auxwidth\relax
-\def\firstline{1}
-\def\lastline{}
+\def\prog@L{lualatex
+               -jobname=\theexample-L-\filename\space}
 
-\let\aatexample\example
-\let\endaatexample\endexample
-\let\opentypeexample\example
-\let\endopentypeexample\endexample
+%%%%%%%%%%%%%%%%%%%%%%
 
 \newcommand*\setexsize[1]{\let\examplesize#1}
 \newcommand*\setverbwidth[1]{\def\auxwidth{#1}}
diff --git a/Master/texmf-dist/source/latex/fontspec/testsuite/L001a.ltx b/Master/texmf-dist/source/latex/fontspec/testsuite/L001a.ltx
new file mode 100644
index 00000000000..538604c1e0b
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/testsuite/L001a.ltx
@@ -0,0 +1,7 @@
+
+\documentclass{testsuite}
+\usepackage{fontspec}
+\setmainfont{TeX Gyre Pagella}
+\begin{document}
+Hello, moon!
+\end{document}
+\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/fontspec/testsuite/L002a.ltx b/Master/texmf-dist/source/latex/fontspec/testsuite/L002a.ltx
new file mode 100644
index 00000000000..79f1c0dc2dd
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/testsuite/L002a.ltx
@@ -0,0 +1,16 @@
+
+\documentclass{testsuite}
+\usepackage{fontspec}
+\setmainfont[Color=FF0000]{Georgia}
+\def\1{abcABC}\def\2{XYZxyz}
+\def\test{\1\textsf{\2}\1\\}
+\begin{document}
+\setsansfont{Verdana}
+\test
+\setsansfont[Scale=0.5]{Verdana}
+\test
+\setsansfont[Scale=MatchLowercase]{Verdana}
+\test
+\setsansfont[Scale=MatchUppercase]{Verdana}
+\test
+\end{document}
+\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/fontspec/testsuite/L003a.ltx b/Master/texmf-dist/source/latex/fontspec/testsuite/L003a.ltx
new file mode 100644
index 00000000000..b0d4b43aa6b
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/testsuite/L003a.ltx
@@ -0,0 +1,13 @@
+\documentclass{testsuite}
+\usepackage{fontspec}
+\usepackage{xcolor}
+\begin{document}
+{\fontspec[Color=5500FF]{Verdana}Test}
+
+{\fontspec[Color=red]{Verdana}Test} vs
+{\color{red}\fontspec{Verdana}Test}
+
+\definecolor{Foo}{rgb}{0.3,0.4,0.5}
+{\fontspec[Color=Foo]{Verdana}Test} vs
+{\color{Foo}\fontspec{Verdana}Test}
+\end{document}
+\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/fontspec/testsuite/L003b.ltx b/Master/texmf-dist/source/latex/fontspec/testsuite/L003b.ltx
new file mode 100644
index 00000000000..8e9052dd6fb
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/testsuite/L003b.ltx
@@ -0,0 +1,12 @@
+\documentclass{testsuite}
+\usepackage{fontspec}
+\usepackage{xcolor}
+\begin{document}
+\fontspec[Color=red]{Verdana}
+Test
+
+\fontspec[
+    Color=red,Opacity=0.5
+      ]{Verdana}
+Test
+\end{document}
+\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/fontspec/testsuite/L005a.ltx b/Master/texmf-dist/source/latex/fontspec/testsuite/L005a.ltx
new file mode 100644
index 00000000000..0a9f5b9e69f
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/testsuite/L005a.ltx
@@ -0,0 +1,9 @@
+\documentclass{testsuite}
+\usepackage{fontspec}
+\begin{document}
+\Huge
+\fontspec{Junicode}
+Before
+\addfontfeature{StylisticSet=6}
+After
+\end{document}
+\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/fontspec/testsuite/X001a.ltx b/Master/texmf-dist/source/latex/fontspec/testsuite/X001a.ltx
new file mode 100644
index 00000000000..d97035602fd
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/testsuite/X001a.ltx
@@ -0,0 +1,7 @@
+
+\documentclass{testsuite}
+\usepackage{fontspec}
+\setmainfont{TeX Gyre Pagella}
+\begin{document}
+Hello, sun!
+\end{document}
+\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/fontspec/testsuite/X002a.ltx b/Master/texmf-dist/source/latex/fontspec/testsuite/X002a.ltx
new file mode 100644
index 00000000000..79f1c0dc2dd
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/testsuite/X002a.ltx
@@ -0,0 +1,16 @@
+
+\documentclass{testsuite}
+\usepackage{fontspec}
+\setmainfont[Color=FF0000]{Georgia}
+\def\1{abcABC}\def\2{XYZxyz}
+\def\test{\1\textsf{\2}\1\\}
+\begin{document}
+\setsansfont{Verdana}
+\test
+\setsansfont[Scale=0.5]{Verdana}
+\test
+\setsansfont[Scale=MatchLowercase]{Verdana}
+\test
+\setsansfont[Scale=MatchUppercase]{Verdana}
+\test
+\end{document}
+\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/fontspec/testsuite/X003a.ltx b/Master/texmf-dist/source/latex/fontspec/testsuite/X003a.ltx
new file mode 100644
index 00000000000..b0d4b43aa6b
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/testsuite/X003a.ltx
@@ -0,0 +1,13 @@
+\documentclass{testsuite}
+\usepackage{fontspec}
+\usepackage{xcolor}
+\begin{document}
+{\fontspec[Color=5500FF]{Verdana}Test}
+
+{\fontspec[Color=red]{Verdana}Test} vs
+{\color{red}\fontspec{Verdana}Test}
+
+\definecolor{Foo}{rgb}{0.3,0.4,0.5}
+{\fontspec[Color=Foo]{Verdana}Test} vs
+{\color{Foo}\fontspec{Verdana}Test}
+\end{document}
+\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/fontspec/testsuite/X004a.ltx b/Master/texmf-dist/source/latex/fontspec/testsuite/X004a.ltx
new file mode 100644
index 00000000000..b6b32e4c0d1
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/testsuite/X004a.ltx
@@ -0,0 +1,11 @@
+\documentclass{testsuite}
+\usepackage{fontspec}
+\usepackage{xcolor}
+\begin{document}
+   \fontspec[ SizeFeatures={
+       {Size={-8}, Font=TeX Gyre Bonum Italic, Color=AA0000},
+       {Size={8-14}, Color=00AA00},
+       {Size={14-}, Color=0000AA}} ]{TeX Gyre Chorus}
+
+   {\scriptsize Small\par} Normal size\par {\Large Large\par}
+\end{document}
+\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/fontspec/testsuite/X005a.ltx b/Master/texmf-dist/source/latex/fontspec/testsuite/X005a.ltx
new file mode 100644
index 00000000000..08dc161729c
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/testsuite/X005a.ltx
@@ -0,0 +1,9 @@
+\documentclass{testsuite}
+\usepackage{fontspec}
+\begin{document}
+\Huge
+\fontspec{Junicode}
+Before
+\addfontfeature{StylisticSet=6}
+After
+\end{document}
diff --git a/Master/texmf-dist/source/latex/fontspec/testsuite/testsuite-listing.tex b/Master/texmf-dist/source/latex/fontspec/testsuite/testsuite-listing.tex
new file mode 100644
index 00000000000..19b30a1cb7f
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/testsuite/testsuite-listing.tex
@@ -0,0 +1,10 @@
+\TEST{L001a}
+\TEST{L002a}
+\TEST{L003a}
+\TEST{L003b}
+\TEST{L005a}
+\TEST{X001a}
+\TEST{X002a}
+\TEST{X003a}
+\TEST{X004a}
+\TEST{X005a}
diff --git a/Master/texmf-dist/source/latex/fontspec/testsuite/testsuite.cls b/Master/texmf-dist/source/latex/fontspec/testsuite/testsuite.cls
new file mode 100644
index 00000000000..4c696c9dc35
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/testsuite/testsuite.cls
@@ -0,0 +1,17 @@
+
+\ProvidesClass{testsuite}
+\LoadClass{article}
+\RequirePackage{geometry}
+\geometry{
+  papersize={9cm,6cm},margin=0.5cm
+}
+\pagestyle{empty}
+\parindent=0pt
+\parskip=10pt
+
+\newcommand\LATIN{ABCDEFGHIJKLMNOPQRSTUVWXYZ}
+\newcommand\latin{abcdefghijklmnopqrstuvwxyz}
+
+\newcommand\GREEK{ΑΒΓΔΕΖΗΘϴΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩ}
+\newcommand\greek{αβγδεϵζηθϑικϰλμνξοπϖρϱςστυφϕχψω}
+
diff --git a/Master/texmf-dist/tex/latex/fontspec/fontspec-patches.sty b/Master/texmf-dist/tex/latex/fontspec/fontspec-patches.sty
index 5298ad11cc0..9a228421de2 100644
--- a/Master/texmf-dist/tex/latex/fontspec/fontspec-patches.sty
+++ b/Master/texmf-dist/tex/latex/fontspec/fontspec-patches.sty
@@ -14,7 +14,9 @@
 %% 
 %% 
 \ProvidesPackage{fontspec-patches}
-  [2010/06/03 v2.0b2 Advanced font selection for XeLaTeX/LuaLaTeX]
+  [2010/06/08 v2.0 Advanced font selection for XeLaTeX/LuaLaTeX]
+
+
 \ExplSyntaxOn
 \RequirePackage{fixltx2e}[2006/03/24]
 \DeclareRobustCommand \em {
diff --git a/Master/texmf-dist/tex/latex/fontspec/fontspec.cfg b/Master/texmf-dist/tex/latex/fontspec/fontspec.cfg
index bc1be91d447..7ecb2df2c4d 100644
--- a/Master/texmf-dist/tex/latex/fontspec/fontspec.cfg
+++ b/Master/texmf-dist/tex/latex/fontspec/fontspec.cfg
@@ -1,4 +1,6 @@
 
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%% FOR BACKWARDS COMPATIBILITY WITH PREVIOUS VERSIONS %%%
 
diff --git a/Master/texmf-dist/tex/latex/fontspec/fontspec.lua b/Master/texmf-dist/tex/latex/fontspec/fontspec.lua
index c67d56c2702..b777424cfeb 100644
--- a/Master/texmf-dist/tex/latex/fontspec/fontspec.lua
+++ b/Master/texmf-dist/tex/latex/fontspec/fontspec.lua
@@ -13,6 +13,8 @@
 --    License information appended.
 --  
 --  
+
+
 fontspec          = { }
 
 fontspec.module   = {
@@ -142,38 +144,16 @@ function fontspec.check_ot_feat(fnt, feat, lang, script)
     end
 end
 
-
-function fontspec.get_dimen(fontdimen, csname)
-    local id, h, em, pt
-    if csname == "font" then
-        id = font.current()
-    else
-        id = font_id(csname)
-    end
-    if fontdimen == 8 then
-        h = fonts.ids[id].shared.otfdata.pfminfo.os2_capheight
-    elseif fontdimen == 5 then
-        h = fonts.ids[id].shared.otfdata.pfminfo.os2_xheight
-    end
-    em = fonts.ids[id].shared.otfdata.metadata.units_per_em
-    pt = fonts.ids[id].size / 65536
-    tex.sprint(string.format("%spt", (h/em)*pt))
-end
-
-function fontspec.charglyph(char, csname)
-    local id, c
+function fontspec.charglyph(char)
     if char then
+        local id, c
         if utf.len(char) > 1 then
             c = utf.byte(utf.char(char:gsub('"', '0x')))
         else
             c = utf.byte(char)
         end
 
-        if csname then
-            id = font_id(csname)
-        else
-            id = font.current()
-        end
+        id = font.current()
 
         if font.fonts[id]["characters"][c] then
             return font.fonts[id]["characters"][c].index
diff --git a/Master/texmf-dist/tex/latex/fontspec/fontspec.sty b/Master/texmf-dist/tex/latex/fontspec/fontspec.sty
index b129b935e05..afb20ff702c 100644
--- a/Master/texmf-dist/tex/latex/fontspec/fontspec.sty
+++ b/Master/texmf-dist/tex/latex/fontspec/fontspec.sty
@@ -14,8 +14,11 @@
 %% 
 %% 
 \ProvidesPackage{fontspec}
-  [2010/06/03 v2.0b2 Advanced font selection for XeLaTeX/LuaLaTeX]
+  [2010/06/08 v2.0 Advanced font selection for XeLaTeX/LuaLaTeX]
+
+
 \RequirePackage{expl3,xparse}
+\input binhex.tex  % before expl syntax!
 \ExplSyntaxOn
 \msg_new:nnn {fontspec} {not-pdftex}
 {
@@ -60,6 +63,8 @@
 \newcount\c@zf@language
 \int_new:N \l_fontspec_strnum_int
 \cs_set:Npn \use:x #1 { \edef\@tempa{#1}\@tempa }
+\cs_set:Npn \use_v:nnnnn #1#2#3#4#5 {#5}
+\cs_set:Npn \use_iv:nnnnn #1#2#3#4#5 {#4}
 \cs_new:Npn \fontspec_setkeys:xx #1#2
  {
   \use:x { \exp_not:N \setkeys*[zf]{#1}{#2} }
@@ -111,7 +116,22 @@
   loaded~ after~ euler.~ Type~ <return>~ to~ proceed\\
   with~ incorrect~ \string\mathit,~ \string\mathbf,~ etc.
 }
-
+\msg_new:nnnn {fontspec} {no-xcolor}
+{
+  Cannot~ load~ named~ colours~ without~ the~ xcolor~ package.
+}
+{
+  Sorry,~ I~ can't~ do~ anything~ to~ help.~ Instead~ of~ loading\\
+  the~ color~ package,~ use~ xcolor~ instead.~ It's~ better.
+}
+\msg_new:nnnn {fontspec} {unknown-color-model}
+{
+  Error~ loading~ colour~ `#1';~ unknown~ colour~ model.
+}
+{
+  Sorry,~ I~ can't~ do~ anything~ to~ help.~ Please~ report~ this~ error\\
+  to~ my~ developer~ with~ a~ minimal~ example~ that~ causes~ the~ problem.
+}
 \msg_new:nnn {fontspec} {addfontfeatures-ignored}
 {
   \string\addfontfeature (s)~ ignored;\\
@@ -195,7 +215,7 @@
 }
 \msg_new:nnn {fontspec} {no-scripts}
 {
-  Font~ \zf@fontname~ does not contain any OpenType `Script' information.
+  Font~ \zf@fontname\space does~ not~ contain~ any~ OpenType~ `Script'~ information.
 }
 \DeclareOption{cm-default}{
   \fontspec_warning:n {cm-default-obsolete}
@@ -520,57 +540,100 @@
   \edef\zf@fontname{#2}
   \let\zf@family@long\zf@fontname
   \let\zf@up\zf@fontname
+  \fontspec_preparse_features:nn {#1}{#2}
+  \fontspec_set_scriptlang:
+  \fontspec_get_features:n {\zf@font@feat}
+  \zf@firsttimefalse
+  \fontspec_save_family:nT {#2} {
+    \fontspec_info:nxx {defining-font} {#1} {#2}
+    \fontspec_save_fontinfo:nn {#1} {#2}
+    \DeclareFontFamily{\zf@enc}{\zf@family}{}
+    \fontspec_set_upright:
+    \fontspec_set_bold:
+    \fontspec_set_italic:
+    \fontspec_set_slanted:
+    \fontspec_set_bold_italic:
+    \fontspec_set_bold_slanted:
+  }
+  \endgroup
+}
+\cs_set_eq:NN \zf@fontspec \fontspec_select:nn
+\cs_new:Npn \fontspec_preparse_features:nn #1#2 {
   \fontspec_if_detect_external:nT {#2}
    { \setkeys[zf]{preparse-external}{ExternalLocation} }
   \fontspec_setkeys:xx {preparse-external} {\zf@default@options #1}
   \let\zf@fontname\zf@up
   \fontspec_setkeys:xx {preparse} {\XKV@rm}
   \let\zf@font@feat\XKV@rm
-  \global\font\zf@basefont="\fontspec_fullname:n {\zf@up}"~at~\f@size pt
+  \font\zf@basefont="\fontspec_fullname:n {\zf@up}"~at~\f@size pt
   \fontspec_set_font_type:
   \global\font\zf@basefont="\fontspec_fullname:n {\zf@up}"~at~\f@size pt
-  \zf@firsttimetrue
-    \ifzf@icu
-      \tl_if_empty:NTF \l_fontspec_script_name_tl {
-        \fontspec_check_script:nTF {latn}
-        {
-          \tl_set:Nn \l_fontspec_script_name_tl {Latin}
-          \tl_set:Nn \l_fontspec_script_tl      {latn}
-          \tl_if_empty:NT \l_fontspec_lang_tl {
-            \tl_set:Nn \l_fontspec_lang_name_tl {Default}
-            \tl_set:Nn \l_fontspec_lang_tl      {DFLT}
-          }
-          \fontspec_setkeys:xxx {feat} {Script} {\l_fontspec_script_name_tl}
-          \fontspec_setkeys:xxx {feat} {Lang}   {\l_fontspec_lang_name_tl}
-        }
-        {
-          \fontspec_info:n {no-scripts}
-        }
-      }
-      {
-        \fontspec_setkeys:xxx {feat} {Script} {\l_fontspec_script_name_tl}
-        \fontspec_setkeys:xxx {feat} {Lang}   {\l_fontspec_lang_name_tl}
-      }
-    \fi
-    \fontspec_get_features:n{\zf@font@feat}
-  \zf@firsttimefalse
+  \zf@basefont % this is necessary for LuaLaTeX to check the scripts properly
+}
+\prg_new_conditional:Nnn \fontspec_if_detect_external:n {T}
+ {
+  \clist_map_inline:Nn \l_fontspec_extensions_clist
+   {
+    \bool_set_false:N \l_tmpa_bool
+    \tl_if_in:nnT {#1 <= end_of_string} {##1 <= end_of_string}
+      { \bool_set_true:N \l_tmpa_bool \clist_map_break: }
+   }
+  \bool_if:NTF \l_tmpa_bool \prg_return_true: \prg_return_false:
+ }
+\cs_set:Npn \fontspec_fullname:n #1 {
+  \fontspec_namewrap:n { #1 \l_fontspec_extension_tl }
+  \l_fontspec_renderer_tl
+  \l_fontspec_optical_size_tl
+}
+%% Now we have a unique (in fact, too unique!) string that contains
+\prg_new_conditional:Nnn \fontspec_save_family:n {T} {
   \unless\ifcsname zf@UID@\zf@family@long\endcsname
-    \ifcsname c@zf@famc@#2\endcsname
+    \ifcsname c@zf@famc@#1\endcsname
       \expandafter\global\expandafter\advance
-        \csname c@zf@famc@#2\endcsname\@ne
+        \csname c@zf@famc@#1\endcsname\@ne
     \else
       \expandafter\global\expandafter\newcount
-        \csname c@zf@famc@#2\endcsname
+        \csname c@zf@famc@#1\endcsname
     \fi
-    \edef\@tempa{#2~}
+    \edef\@tempa{#1~}
     \cs_gset:cpx{zf@UID@\zf@family@long}{
       \expandafter\zap@space\@tempa\@empty
-      (\expandafter\the\csname c@zf@famc@#2\endcsname)
+      (\expandafter\the\csname c@zf@famc@#1\endcsname)
     }
   \fi
   \xdef\zf@family{\@nameuse{zf@UID@\zf@family@long}}
-  \unless\ifcsname zf@family@fontname\zf@family\endcsname
-    \fontspec_info:nxx {defining-font} {#1} {#2}
+  \cs_if_exist:cTF {zf@family@fontname\zf@family}
+    \prg_return_false: \prg_return_true:
+}
+\cs_new:Npn \fontspec_set_scriptlang: {
+  \ifzf@icu
+    \tl_if_empty:NTF \l_fontspec_script_name_tl {
+      \fontspec_check_script:nTF {latn}
+      {
+        \tl_set:Nn \l_fontspec_script_name_tl {Latin}
+        \tl_set:Nn \l_fontspec_script_tl      {latn}
+        \tl_if_empty:NT \l_fontspec_lang_tl {
+          \tl_set:Nn \l_fontspec_lang_name_tl {Default}
+          \tl_set:Nn \l_fontspec_lang_tl      {DFLT}
+        }
+        \fontspec_setkeys:xxx {feat} {Script} {\l_fontspec_script_name_tl}
+        \fontspec_setkeys:xxx {feat} {Lang}   {\l_fontspec_lang_name_tl}
+      }
+      {
+        \fontspec_info:n {no-scripts}
+      }
+    }
+    {
+      \tl_if_empty:NT \l_fontspec_lang_tl {
+        \tl_set:Nn \l_fontspec_lang_name_tl {Default}
+        \tl_set:Nn \l_fontspec_lang_tl      {DFLT}
+      }
+      \fontspec_setkeys:xxx {feat} {Script} {\l_fontspec_script_name_tl}
+      \fontspec_setkeys:xxx {feat} {Lang}   {\l_fontspec_lang_name_tl}
+    }
+  \fi
+}
+\cs_new:Npn \fontspec_save_fontinfo:nn #1#2 {
     \tl_gset:cx {zf@family@fontname\zf@family} {#2}
     \tl_gset:cx {zf@family@options\zf@family} {\zf@default@options #1}
     \tl_gset:cx {zf@family@fontdef\zf@family} {
@@ -582,31 +645,10 @@
       { \int_use:N \c@zf@language }
     \tl_gset_eq:cN {g_fontspec_script_(\zf@family)_tl} \l_fontspec_script_tl
     \tl_gset_eq:cN {g_fontspec_lang_(\zf@family)_tl}   \l_fontspec_lang_tl
-    \DeclareFontFamily{\zf@enc}{\zf@family}{}
-    \zf@make@font@shapes{\zf@fontname}
-      {\mddefault}{\updefault}{\zf@font@feat\zf@up@feat}
-    \fontspec_set_bold:
-    \fontspec_set_italic:
-    \fontspec_set_slanted:
-    \fontspec_set_bold_italic:
-    \fontspec_set_bold_slanted:
-  \fi
-  \endgroup
 }
-\prg_new_conditional:Nnn \fontspec_if_detect_external:n {T}
- {
-  \clist_map_inline:Nn \l_fontspec_extensions_clist
-   {
-    \bool_set_false:N \l_tmpa_bool
-    \tl_if_in:nnT {#1 <= end_of_string} {##1 <= end_of_string}
-      { \bool_set_true:N \l_tmpa_bool \clist_map_break: }
-   }
-  \bool_if:NTF \l_tmpa_bool \prg_return_true: \prg_return_false:
- }
-\cs_set:Npn \fontspec_fullname:n #1 {
-  \fontspec_namewrap:n { #1 \l_fontspec_extension_tl }
-  \l_fontspec_renderer_tl
-  \l_fontspec_optical_size_tl
+\cs_new:Npn \fontspec_set_upright: {
+  \zf@make@font@shapes{\zf@fontname}
+    {\mddefault}{\updefault}{\zf@font@feat\zf@up@feat}
 }
 \cs_new:Npn \fontspec_set_bold: {
   \unless\ifzf@nobf
@@ -640,6 +682,7 @@
   \@tempswatrue
   \ifzf@nobf\@tempswafalse\fi
   \ifzf@noit\@tempswafalse\fi
+  \bool_if:NT \l_fontspec_external_bool \@tempswafalse
   \if@tempswa
     \ifx\zf@bfit\@empty
       \ifx\zf@bf\@empty
@@ -709,24 +752,24 @@
     \else
       \edef\zf@fontname{#1#2}
       \let\zf@basefont\@tempfontb
-      \zf@DeclareFontShape{#3}{#4}{#5}
+      \fontspec_declare_shape:nnnn {}{#3}{#4}{#5}
       \ifx\zf@sc\@empty
         \unless\ifzf@nosc
           \zf@make@smallcaps
           \unless\ifx\zf@smallcaps\@empty
-            \zf@DeclareFontShape[\zf@smallcaps]{#3}
+            \fontspec_declare_shape:nnnn {\zf@smallcaps}{#3}
               {\ifx#4\itdefault\sidefault\else\scdefault\fi}{#5\zf@sc@feat}
           \fi
         \fi
       \else
         \edef\zf@fontname{\zf@sc}
-        \zf@DeclareFontShape{#3}
+        \fontspec_declare_shape:nnnn {}{#3}
           {\ifx#4\itdefault\sidefault\else\scdefault\fi}{#5\zf@sc@feat}
       \fi
     \fi
   \endgroup
 }
-\newcommand\zf@DeclareFontShape[4][]{
+\cs_new:Npn \fontspec_declare_shape:nnnn #1#2#3#4 {
   \clist_if_empty:NTF \l_fontspec_sizefeat_clist
   {
     \fontspec_get_features:n{#4}
@@ -751,6 +794,10 @@
       }
     }
   }
+  \PackageInfo{fontspec}{
+    Defining~ shape~ #2/#3~ with~ raw~ font~ features:
+    \MessageBreak \l_fontspec_rawfeatures_sclist
+  \@gobble}
   \use:x{
     \exp_not:N\DeclareFontShape{\zf@enc}{\zf@family}{#2}{#3}
       {\l_fontspec_nfss_tl}{\zf@adjust}
@@ -794,7 +841,9 @@
   \tl_if_empty:NF \XKV@rm {
     \fontspec_error:nx {unknown-options} { \exp_not:V \XKV@rm }
   }
-  \PackageInfo{fontspec}{Raw~ font~ features~ "\l_fontspec_rawfeatures_sclist"}
+  \cs_if_exist:NT \l_fontspec_hexcol_tl {
+    \zf@update@ff{color=\l_fontspec_hexcol_tl\l_fontspec_opacity_tl}
+  }
 }
 \tl_clear:N \zf@bf
 \tl_clear:N \zf@it
@@ -816,9 +865,13 @@
 \tl_clear:N \l_fontspec_lang_name_tl
 \tl_clear:N \l_fontspec_lang_tl
 \clist_clear:N \l_fontspec_sizefeat_clist
+\tl_set:Nn \l_fontspec_opacity_tl {FF}
 \newcommand*\fontspec_init:{
   \zf@icufalse
-  \cs_set_eq:NN \fontspec_namewrap:n \use:n
+  \zf@firsttimetrue
+  \xetex_or_luatex:nnn { \cs_set:Npn \fontspec_namewrap:n ##1 }
+    { ##1 }
+    { name:##1 }
   \tl_clear:N \l_fontspec_optical_size_tl
   \tl_clear:N \l_fontspec_renderer_tl
   \luatex_if_engine:T {
@@ -873,6 +926,7 @@
     \fontspec_make_ICU_feature:n {#3}
   }
 }
+\cs_generate_variant:Nn \fontspec_make_feature:nnn {nnx}
 \cs_new:Npn \fontspec_make_AAT_feature:nn #1#2 {
   \tl_if_empty:nTF {#1}
   {
@@ -1045,7 +1099,9 @@
   \zf@nobftrue
   \zf@noittrue
   \bool_set_true:N \l_fontspec_external_bool
-  \cs_gset:Npn \fontspec_namewrap:n ##1 { [ #1 ##1 ] }
+  \xetex_or_luatex:nnn { \cs_gset:Npn \fontspec_namewrap:n ##1 }
+    {     [ #1 ##1 ] }
+    { file: #1 ##1   }
   \xetex_if_engine:T { \setkeys[zf]{preparse}{Renderer=ICU} }
 }
 \aliasfontfeature{ExternalLocation}{Path}
@@ -1171,7 +1227,7 @@
   \zf@update@family{scfeat:\zap@space #1~\@empty}
 }
 \define@key[zf]{preparse}{SizeFeatures}{
-  \unless\ifzf@firsttime\def\l_fontspec_sizefeat_clist{#1}\fi
+  \tl_set:Nn \l_fontspec_sizefeat_clist {#1}
   \zf@update@family{sizefeat:\zap@space #1~\@empty}
 }
 \define@key[zf]{sizing}{Size}{ \tl_set:Nn \l_fontspec_size_tl {#1} }
@@ -1198,16 +1254,16 @@
     \fontspec_info:n {set-scale}
   \group_end:
 }
-\xetex_or_luatex:nnn { \cs_new:Npn \fontspec_set_font_dimen:NnN #1#2#3 }
+\cs_new:Npn \fontspec_set_font_dimen:NnN #1#2#3
 {
   \dim_set:Nn #1 { \fontdimen #2 #3 }
-}
-{
-  \dim_set:Nn #1 { \directlua{ fontspec.get_dimen(#2, "\cs_to_str:N #3") } }
   \dim_compare:nNnT #1 = {0pt} {
     \settoheight #1 {
       \tl_if_eq:nnTF {#3} {\font} \rmfamily #3
-      \prg_case_int:nnn #2 { 5 x 8 X } {?}
+      \prg_case_int:nnn #2 {
+        {5} {x} % x-height
+        {8} {X} % cap-height
+      } {?} % "else" clause; never reached.
     }
   }
 }
@@ -1295,9 +1351,23 @@
 \def\zf@check@one@char#1#2\zf@@{\def\@tempb{#2}}
 \define@key[zf]{options}{Color}{
   \zf@update@family{+col:#1}
-  \zf@update@ff{color=#1}
+  \cs_if_exist:cTF {\token_to_str:N\color@#1}
+  {
+    \convertcolorspec{named}{#1}{HTML}\l_fontspec_hexcol_tl
+  }
+  {
+    \tl_set:Nn \l_fontspec_hexcol_tl {#1}
+  }
 }
 \keyval@alias@key[zf]{options}{Color}{Colour}
+\newcounter{fontspec_tmp_int}
+\define@key[zf]{options}{Opacity}{
+  \zf@update@family{+opac:#1}
+  \setcounter {fontspec_tmp_int} { 255*\real{#1} }
+  \tl_set:Nx \l_fontspec_opacity_tl {
+    \nhex2 { \value{fontspec_tmp_int} }
+  }
+}
 \xetex_or_luatex:nnn {
   \define@key[zf]{options}{Mapping}
 }{
@@ -1486,18 +1556,22 @@
 \zf@define@feature@option{Fractions}{Diagonal} {11}{2}{}
 \zf@define@feature@option{Fractions}{Alternate}{}  {} {+afrc}
 \define@key[zf]{options}{Alternate}[0]{
+  \clist_set_eq:NN \l_fontspec_tmpa_clist \XKV@rm
   \setkeys*[zf@feat]{Alternate}{#1}
   \unless\ifx\XKV@rm\@empty
     \def\XKV@tfam{Alternate}
     \fontspec_make_feature:nnn{17}{#1}{+salt=#1}
   \fi
+  \clist_set_eq:NN \XKV@rm \l_fontspec_tmpa_clist
 }
 \define@key[zf]{options}{Variant}{
+  \clist_set_eq:NN \l_fontspec_tmpa_clist \XKV@rm
   \setkeys*[zf@feat]{Variant}{#1}
   \unless\ifx\XKV@rm\@empty
     \def\XKV@tfam{Variant}
-    \fontspec_make_feature:nnn{18}{#1}{+ss\two@digits{#1}}
+    \fontspec_make_feature:nnx{18}{#1}{+ss\two@digits{#1}}
   \fi
+  \clist_set_eq:NN \XKV@rm \l_fontspec_tmpa_clist
 }
 \aliasfontfeature{Variant}{StylisticSet}
 \zf@define@font@feature{Style}
@@ -1529,9 +1603,7 @@
 \zf@define@feature@option{CharacterWidth}{AlternateProportional}{22}{5}{+palt}
 \zf@define@feature@option{CharacterWidth}{AlternateHalf}{22}{6}{+halt}
 \zf@define@feature@option{CharacterWidth}{Default}{22}{7}{}
-\zf@define@font@feature{Annotation}
-\zf@define@feature@option{Annotation}{Off}{24}{0}{-nalt}
-\zf@define@feature@option{Annotation}{On}{}{}{+nalt}
+\zf@define@feature@option{Annotation}{Off}{24}{0}{}
 \zf@define@feature@option{Annotation}{Box}{24}{1}{}
 \zf@define@feature@option{Annotation}{RoundedBox}{24}{2}{}
 \zf@define@feature@option{Annotation}{Circle}{24}{3}{}
@@ -1543,6 +1615,15 @@
 \zf@define@feature@option{Annotation}{BlackSquare}{24}{9}{}
 \zf@define@feature@option{Annotation}{BlackRoundSquare}{24}{10}{}
 \zf@define@feature@option{Annotation}{DoubleCircle}{24}{11}{}
+\define@key[zf]{options}{Annotation}[0]{
+  \clist_set_eq:NN \l_fontspec_tmpa_clist \XKV@rm
+  \setkeys*[zf@feat]{Annotation}{#1}
+  \unless\ifx\XKV@rm\@empty
+    \def\XKV@tfam{Alternate}
+    \fontspec_make_feature:nnn{}{}{+nalt=#1}
+  \fi
+  \clist_set_eq:NN \XKV@rm \l_fontspec_tmpa_clist
+}
 \zf@define@font@feature{Vertical}
 \define@key[zf@feat]{Vertical}{RotatedGlyphs}[]{
   \ifzf@icu
author	Karl Berry <karl@freefriends.org>	2010-06-09 00:22:21 +0000
committer	Karl Berry <karl@freefriends.org>	2010-06-09 00:22:21 +0000
commit	e75495f92d91038a568dec3fd1cc854d51daf4c7 (patch)
tree	99417371e2a2c104d8082b24e8f1a0faef2be81e /Master/texmf-dist
parent	aac86e6df7bc5de903798b0c8a7f6b49cf4e9b75 (diff)