xetexref (7dec18

git-svn-id: svn://tug.org/texlive/trunk@49341 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 258 insertions, 113 deletions

diff --git a/Master/texmf-dist/doc/xetex/xetexref/README b/Master/texmf-dist/doc/xetex/xetexref/README
deleted file mode 100644
index 948f97d1676..00000000000
--- a/Master/texmf-dist/doc/xetex/xetexref/README
+++ /dev/null
@@ -1,14 +0,0 @@
-================
-=== XETEXREF ===
-================
-
-This is unofficial reference documentation for XeTeX detailing its 
-extended features.
-
-Developed at https://github.com/wspr/xetexref,
-released at http://mirror.ctan.org/info/xetexref.
-
-Will Robertson
---------------
-Distributable under the LPPL,
-v1.3a or greater (your choice).
diff --git a/Master/texmf-dist/doc/xetex/xetexref/README.txt b/Master/texmf-dist/doc/xetex/xetexref/README.txt
new file mode 100644
index 00000000000..1835ecea38a
--- /dev/null
+++ b/Master/texmf-dist/doc/xetex/xetexref/README.txt
@@ -0,0 +1,34 @@
+# The XETEXREF documentation
+
+This package consists of a semi-official reference document for XeTeX.
+It is not a user manual; it simply attempts to list XeTeX’s extended features and interfaces.
+
+Developed at: <https://github.com/wspr/xetexref>
+Released at:  <http://ctan.org/pkg/xetexref>
+
+## Compilation
+
+A standard TeX distribution that includes XeTeX is needed to compile the `xetex-reference.tex` document. The following (freely available) fonts are required to be installed in your texmf tree:
+
+* Linux Libertine O
+* Antykwa Torunska
+* Charis SIL
+
+## Legalities
+
+Copyright 2007-2018 Will Robertson
+Copyright 2018      Joseph Wright
+Copyright 2011-2017 Karl Berry
+Copyright 2013      Khaled Hosny.
+
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.3c
+of this license or (at your option) any later version.
+The latest version of this license is in
+  http://www.latex-project.org/lppl.txt
+and version 1.3 or later is part of all distributions of LaTeX
+version 2005/12/01 or later.
+
+This work has the LPPL maintenance status `maintained'.
+
+The Current Maintainer of this work is Will Robertson.
diff --git a/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.pdf b/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.pdf
index c2500c1aa26..28be55006e6 100644
--- a/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.pdf
+++ b/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.pdf
diff --git a/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex b/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex
index ed0a8c842c2..3be42f8a96f 100644
--- a/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex
+++ b/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex
@@ -1,4 +1,4 @@
-% Copyright 2007-2011 Will Robertson
+% Copyright 2007-2017 Will Robertson
 % Copyright 2011 Karl Berry
 % Copyright 2013 Khaled Hosny
 %
@@ -12,13 +12,17 @@
 %
 % This work has the LPPL maintenance status `maintained'.
 %
-% The Current Maintainer of this work is Khaled Hosny.
+% The Current Maintainer of this work is Will Robertson.
 %
 % This work consists of the files xetex-reference.tex,
 % README.txt, and the derived file xetex-reference.pdf.
 
 \documentclass[12pt]{article}
 
+\title{The \xetex reference guide\\\url{https://ctan.org/pkg/xetexref}}
+\author{Will Robertson \and Khaled Hosny \and Karl Berry}
+\date{2018-12-07}
+
 \suppressfontnotfounderror=1
 
 \makeatletter
@@ -41,7 +45,10 @@
     BoldItalicFont = *-bolditalic ,
     Scale=MatchLowercase
   ]
-\setmonofont{inconsolata}[Scale=MatchLowercase, AutoFakeSlant=.2]
+\setmonofont{inconsolata}[
+  Scale=MatchLowercase,
+  StylisticSet=3, % <- straight quotes
+  AutoFakeSlant=.2]
 \setmathfont{texgyrepagella-math.otf}
 
 \usepackage{calc,fancyvrb,hyperref,refstyle,varioref,xcolor,hologo,xspace}
@@ -60,7 +67,7 @@
   linkcolor=black,
   urlcolor=black,
   pdfsubject={The XeTeX reference guide},
-  pdfauthor={Will Robertson \& Khaled Hosny},
+  pdfauthor={Will Robertson \& Khaled Hosny \& Karl Berry},
   pdfkeywords={xetex, tex, typesetting, unicode, math, opentype, graphite, aat}
 }
 
@@ -83,11 +90,12 @@
 \edef\|{|}
 \DefineShortVerb{\|}
 \newcommand\xarg[1]{$\langle\hbox{\rmfamily\itshape #1}\rangle$}
+\let\meta\xarg
 \def\<#1>{\xarg{#1}}
 \newcommand\oarg[1]{\texttt{[\,#1\,]}}
 \newcommand\desc[1]{\par\noindent\ignorespaces#1\par}
 \def\endcmd{%
-  \end{minipage}  
+  \end{minipage}
   \end{trivlist}}
 
 \def\cs#1{\texttt{\textbackslash#1}}
@@ -102,7 +110,7 @@
    \begin{VerbatimOut}{\examplefilename}}
   {\end{VerbatimOut}
    \typesetexample}
-   
+
 \newcommand\typesetexample{%
   \begin{trivlist}\item[]
   \vrule
@@ -119,7 +127,7 @@
 \let\strong\textbf
 \newcommand\hlink[2]{\href{#1}{#2}\footnote{\url{#1}}}
 
-\let\latin\textit
+\let\latin\relax % let existing font continue
 \def\eg{\latin{e.g.}}
 \def\ie{\latin{i.e.}}
 \def\Eg{\latin{E.g.}}
@@ -133,21 +141,19 @@
 \raggedbottom
 
 \begin{document}
-\title{The \xetex reference guide}
-\author{Will Robertson \and Khaled Hosny}
 \maketitle
 
-\vfill 
+\vfill
 
 \section*{Introduction}
 
 This document serves to summarise additional features of \xetex without
-being so much as a ‘users’ guide. Note that much of the functionality
+being so much as a ‘users’ guide. Much of the functionality
 addressed here is provided in abstracted form in various \latex
 packages and \context modules.
 
 The descriptions here should be a fairly exhaustive list of the new
-primitives and features of \xetex. Descriptions are still a little
+primitives and features of \xetex. Descriptions are still rather
 aenemic, however.
 
 \section*{License}
@@ -167,35 +173,61 @@ information.
 \newpage
 \tableofcontents
 
-\part{\xetex specifics}
-
 \section{The \cs{font} command}
 
 Traditionally, fonts were selected in \tex like this:
-|\font\1=|\xarg{tfm name} with various options possibly appended
-% harder to read without the extra space
-such as \ ‘| at 10pt|’ \ or \ ‘| scaled 1.2|’, with obvious meaning. This syntax
-still works, but it has been greatly extended in \xetex.
+|\font\1=|\xarg{tfm name} \xarg{\tex font options}, where the \xarg{\tex
+font options} included possibilities such as
+\ ‘| at 10pt|’ \
+or \ ‘| scaled 1200|’,
+with evident meaning. This syntax still works, but it has been greatly
+extended in \xetex.
 
 The extended syntax looks schematically like this:
 
-{\centering
- |\font\1="|\xarg{font identifier}\xarg{font options}|:|\xarg{font features}|"|
- \xarg{\tex font options}\par}
+\begin{quote}
+ |\font\1="|\xarg{font identifier}
+              \xarg{font options}%
+              |:|\xarg{font features}%
+         |"|\ \xarg{\tex font options}
+\end{quote}
+
+\noindent Each part of this command is discussed in the following, but
+here is an overview, starting from the end:
+
+\begin{itemize}
+\item The \xarg{\tex font options} are unchanged from traditional \tex.
+
+\item The ASCII double quote character |"| (hex 0x22) surrounds any font
+definition using the extended syntax.
 
-\noindent The \xarg{font identifier} is the only mandatory part of the
-above syntax.  If it is given in square brackets, (e.g.,
-|[lmroman10-regular]|), it is taken as a font file name.
-Without brackets, the name is looked up both as a file name and a system
+\item The \xarg{font features} are an optional list of names,
+comma or semi-colon separated, preceded by an ASCII colon |:| (0x3a).
+
+\item The \xarg{font options} are an optional list of specifiers which
+can only be used with system fonts (see next).
+
+\item The \xarg{font identifier} is the only mandatory part of the
+above syntax.  If it is given in square brackets, (\eg,
+|\font\1="[lmroman10-regular]"|), it is taken as a font file name.
+Without brackets, the name is looked up as both a file name and a system
 font name.
-When using a font name, the font is looked up through the operating
-system, using (except on Mac~OS~X) the |fontconfig| library.  Running
-|fc-list| should show you the font names available.  \Eg,
+
+\end{itemize}
+
+This distinction between file name lookups and system font name lookups
+is crucial to understanding \xetex's behavior and to writing portable
+documents (in short: don't use system fonts).
+
+System font name lookups use (except on Mac~OS~X) the
+|fontconfig| library; running |fc-list| should show you the font names
+available.  \Eg,
 \begin{quote}\small
 |\font\1="Liberation Serif"| \hfill \emph{look for OS-installed font}
 \end{quote}
 
-Fonts have many internal names, and XeTeX matches them in the following order:
+Fonts have many internal names, and XeTeX does the system font lookups
+in the following order:
 \vskip1ex
 \begin{itemize}
   \item Full Name;
@@ -214,23 +246,28 @@ default). The current directory and the |texmf| trees are searched for
 files matching the name, or the path may be embedded in the font
 declaration, as usual with |kpathsea|. \Eg,
 \begin{quote}\small
-|\font\2="[lmroman10-regular]"| \hfill
+|\font\1="[lmroman10-regular]"| \hfill
   {\em find |lmroman10-regular.otf| in any tree}
-|\font\3="[/myfonts/fp9r8a]"| \hfill
+|\font\2="[/myfonts/fp9r8a]"| \hfill
   {\em look for |fp9r8a| only in |/myfonts/|}
 \end{quote}
 
 A file with either an |.otf|, |.ttf| or |.pfb| extension (in that order) will be found.  The
 extension can also be specified explicitly.
-If the file is a font collection (e.g., |.ttc| or |.dfont|), the index of the
-font can be specified using a colon followed by zero-based font index inside
-the square brackets. \Eg,
+
+\subsection{Font collection files}
+
+One more special case about the \xarg{font identifier}: if the file is a
+font collection (\eg, |.ttc| or |.dfont|), the index of the font can be
+specified using a colon followed by zero-based font index inside the
+square brackets (in contrast to the font features we'll describe soon,
+which follow a colon outside any square brackets). \Eg,
 \begin{quote}\small
-|\font\4="[myfont.ttc:1]"| \hfill {\em load the second font from |myfont.ttc| file}
+|\font\2="[myfont.ttc:1]"| \hfill {\em load the second font from |myfont.ttc| file}
 \end{quote}
 
 
-\subsection{Font options}
+\subsection{Font options: For OS-selected fonts only}
 
 The following \xarg{font options} are only applicable when the font is selected
 through the operating system (\ie, without square brackets):
@@ -253,7 +290,7 @@ The following \xarg{font options} control which `renderer' \xetex uses to interf
 \end{optdesc}
 
 
-\subsection{Font features}
+\subsection{Font features: For all fonts}
 
 The \xarg{font features} is a comma or semi-colon separated list
 activating or deactivating various OpenType, Graphite, or AAT font
@@ -261,12 +298,13 @@ features, which will vary by font.  In contrast to font options,
 features work whether the font is selected by file name or through the
 operating system.
 
-The \xetex documentation files \path{aat-info.tex} and
-\path{opentype-info.tex} provide per-font lists of supported features.
+The \xetex utility files \path{aat-info.tex} and
+\path{opentype-info.tex} provide lists of supported features for a given
+font (see comments at the top of each).
 
-\subsubsection{Arbitrary OpenType, Graphite, or AAT features}
+\subsubsection{Font features specific to OpenType, Graphite, or AAT}
 
-OpenType font features are chosen with
+OpenType font features are usually chosen with
 \hlink{http://www.microsoft.com/typography/otspec/featuretags.htm}{standard
 tags}. They may be either comma- or semicolon-separated, and prefixed
 with a |+| to turn them on and a |-| to turn them off, optionally followed
@@ -274,21 +312,21 @@ by |=| and a 0-based index for selecting alternates from multiple
 alternates features (ignored for |-| prefixed tags).
 
 \begin{example}
-\font\liber="Linux Libertine O/I=5:+smcp" at 12pt
+\font\liber="[LinLibertine_RI.otf]/I=5:+smcp" at 12pt
 \liber This is the OpenType font Linux Libertine in italic with small caps.
 \end{example}
 
 Varying depending on the language and script in use (see
 \secref[vref]{script}), a small number of OpenType features, if they
-exist, will be activated by default.
+exist, may be activated by default.
 
 \begin{example}
-\font\antt="Antykwa Torunska"         at 12pt \antt 0
-\font\antt="Antykwa Torunska:+aalt=0" at 12pt \antt 0
-\font\antt="Antykwa Torunska:+aalt=1" at 12pt \antt 0
-\font\antt="Antykwa Torunska:+aalt=2" at 12pt \antt 0
-\font\antt="Antykwa Torunska:+aalt=3" at 12pt \antt 0
-\font\antt="Antykwa Torunska:+aalt=4" at 12pt \antt 0
+\font\antt="[AntykwaTorunska-Regular.otf]"         at 12pt \antt 0
+\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=0" at 12pt \antt 0
+\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=1" at 12pt \antt 0
+\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=2" at 12pt \antt 0
+\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=3" at 12pt \antt 0
+\font\antt="[AntykwaTorunska-Regular.otf]:+aalt=4" at 12pt \antt 0
 \end{example}
 
 AAT font features and Graphite font features are specified by strings
@@ -296,27 +334,23 @@ within each font rather than standardised tags. Therefore, even
 equivalent features between different fonts can have different names.
 
 \begin{example}
-\font\gra="Charis SIL/GR:Small Caps=True" at 12pt
+\font\gra="[CharisSIL-R.ttf]/GR:Small Caps=True" at 12pt
 \gra This is the Graphite font Charis SIL with small caps.
 \end{example}
 
-\subsubsection{Options for all fonts}
+\subsubsection{Features for all fonts}
 
 Some font features may be applied for any font. These are
 \begin{optdesc}
-\item[mapping=\textsl{<font map>}] 
-Uses the specified font mapping for this font. This uses the TECKit
-engine to transform unicode characters in the last-minute processing
-stage of the source. For example, |mapping=tex-text| will enable the
-classical mappings from ugly ascii |``---''| to proper typographical
-glyphs “—”, and so on.
 
-\item[color={\slshape RRGGBB}{[{\slshape TT}]}] 
+\item[color={\slshape RRGGBB}{[{\slshape TT}]}]
 Triple pair of hex values to specify the colour in RGB space, with an
 optional value for the transparency.
 
-\item[letterspace=$x$] 
-Adds $x/S$ space between letters in words, where $S$ is the font size.
+\begin{example}
+\font\9="[lmsans10-regular]:color=0000FF,mapping=tex-text"
+\9 A sans blue quoted em-dash: ``---''.
+\end{example}
 
 \item[embolden=$x$]
 Increase the envelope of each glyph by the set amount (this makes the
@@ -324,9 +358,19 @@ letters look ‘more bold’). $x=0$ corresponds to no change; $x=1.5$ is a
 good default value.
 
 \item[extend=$x$]
-Stretch each glyph horizontally by a factor of $x$ (i.e., $x=1$
+Stretch each glyph horizontally by a factor of $x$ (\ie, $x=1$
 corresponds to no change).
 
+\item[letterspace=$x$]
+Adds $x/S$ space between letters in words, where $S$ is the font size.
+
+\item[mapping=\textsl{<font map>}]
+Uses the specified font mapping for this font. This uses the TECKit
+engine to transform Unicode characters in the last-minute processing
+stage of the source. For example, |mapping=tex-text| will enable the
+classical mappings from ASCII |``---''| to proper typographical
+glyphs “—”, and so on.
+
 \item[slant=$x$]
 Slant each glyph by the set amount. $x=0$ corresponds to no change;
 $x=0.2$ is a good default value. The slant is given by $x=R/S$ where $R$
@@ -360,12 +404,10 @@ fonts.
 
 \subsubsection{Vertical typesetting}
 \begin{optdesc}
-\item[vertical] 
+\item[vertical]
 Enables glyph rotation in the output so vertical typesetting can be performed.
 \end{optdesc}
 
-\part{New commands}
-
 \section{Font primitives}
 
 \cmd|\XeTeXtracingfonts|
@@ -391,8 +433,8 @@ Enables glyph rotation in the output so vertical typesetting can be performed.
   \texttt{\fontname#1} is rendered by
   \ifcase\XeTeXfonttype#1\TeX\or AAT\or OpenType\or Graphite\fi.\par}
 \font\1="cmr10"
-\font\2="Charis SIL"
-\font\3="Charis SIL/OT"
+\font\2="[CharisSIL-R.ttf]"
+\font\3="[CharisSIL-R.ttf]/OT"
 \whattype\1 \whattype\2 \whattype\3
 \end{example}
 
@@ -407,7 +449,7 @@ Enables glyph rotation in the output so vertical typesetting can be performed.
 \endcmd
 
 \begin{example}
-\font\1="Charis SIL"\1
+\font\1="[CharisSIL-R.ttf]"\1
 The first character in Charis SIL is: "\char\XeTeXfirstfontchar\1"
 and the last character is: "\char\XeTeXlastfontchar\1".
 \end{example}
@@ -441,21 +483,21 @@ present. Use \texttt{fontforge} or similar to discover glyph names.}
 \endcmd
 
 \cmd|\XeTeXcharglyph|
-\xarg{char code} 
+\xarg{char code}
 \desc{Expands to the default glyph number of character \xarg{char code}
 in the current font, or 0 if the character is not available in the
 font.}
 \endcmd
 
 \begin{example}
-\font\1="Charis SIL"\1
+\font\1="[CharisSIL-R.ttf]"\1
 The glyph slot in Charis SIL for the Yen symbol is:
-    \the\XeTeXglyphindex"yen" . % the font-specific glyph name
-Or: \the\XeTeXcharglyph"00A5.   % the unicode character slot
+    \the\XeTeXglyphindex"yen" . % font-specific glyph name
+Or: \the\XeTeXcharglyph"00A5.   % unicode character slot
 
 This glyph may be typeset with the font-specific glyph slot:
-\XeTeXglyph150, 
-or the unicode character slot:
+\XeTeXglyph150,
+or the Unicode character slot:
 \char"00A5.
 \end{example}
 
@@ -494,9 +536,9 @@ these two dimensions.}
   \special{color pop}%
   \kern\XeTeXglyphbounds3 \gid}%
   #1}
-	
+
 \noindent
-\font\x="Charis SIL/I" at 24pt \x
+\font\x="[CharisSIL-I.ttf]" at 24pt \x
 \shadebbox{A} \shadebbox{W} \shadebbox{a} \shadebbox{f}
 \shadebbox{;} \shadebbox{*} \shadebbox{=}
 \end{example}
@@ -595,7 +637,7 @@ numerically. If the feature does not exist, the integer is
 \endcmd
 
 \begin{example}
-\font\1="Charis SIL/GR" at 10pt
+\font\1="[CharisSIL-R.ttf]/GR" at 10pt
 \def\featname{Uppercase Eng alternates}
 The feature ‘\featname’ has index
 \the\XeTeXfindfeaturebyname\1 "\featname"\relax
@@ -652,7 +694,7 @@ feature/selector exists before attempting to use it.}
 \endcmd
 
 \begin{example}
-\font\1="Charis SIL/GR" at 10pt
+\font\1="[CharisSIL-R.ttf]/GR" at 10pt
 \def\featname{Uppercase Eng alternates}
 \newcount\featcount
 \featcount=\XeTeXfindfeaturebyname\1 "\featname"\relax
@@ -662,8 +704,8 @@ feature/selector exists before attempting to use it.}
 \seleccount=\XeTeXfindselectorbyname\1 \featcount "\selecname"\relax
 The feature selector ‘\selecname’ has index \the\seleccount
 
-\font\2="Charis SIL/GR:\featname=\selecname" at 10pt
-\font\3="Charis SIL/GR:\the\featcount=\the\seleccount" at 10pt
+\font\2="[CharisSIL-R.ttf]/GR:\featname=\selecname" at 10pt
+\font\3="[CharisSIL-R.ttf]/GR:\the\featcount=\the\seleccount" at 10pt
 
 Activating the feature: \1 Ŋ \2 Ŋ \3 Ŋ
 \end{example}
@@ -777,7 +819,7 @@ number of the \xarg{char slot} if no assignment is given.}
 \opteq
 \xarg{type/fam./glyph slot}
 \desc{Defines a control sequence for accessing a maths glyph using the
-‘bit-packed’ number output by, e.g., \cs{Umathcodenum}. This would
+‘bit-packed’ number output by, \eg, \cs{Umathcodenum}. This would
 be used to replace legacy code such as
 \cs{mathchardef}\cs{foo}\texttt{=}\cs{mathcode}\texttt{`}\cs{\-}.}
 \endcmd
@@ -951,7 +993,7 @@ allowed. Off, 0, by default.}
 \endcmd
 
 \cmd|\XeTeXupwardsmode|
-\xarg{Integer} 
+\xarg{Integer}
 \desc{If greater than zero, successive lines of text (and rules, boxes,
 etc.) will be stacked upwards instead of downwards.}
 \endcmd
@@ -1009,7 +1051,7 @@ with unit ‘|pt|’. For example, for a rotation specified with a dimension
 \item \verb|\testdim=1in    | is 72.27\textdegree, and
 \item \verb|\testdim=100sp| is (100/65536)\textdegree.
 \end{itemize}
-In all cases the resulting decimal number for rotation $x$ must be  
+In all cases the resulting decimal number for rotation $x$ must be
 within the limits $-16384 < x < 16384$.
 
 The \cs{XeTeXpdffile} command takes one more optional argument for
@@ -1077,6 +1119,8 @@ the specified \xarg{font} to $n/1000$\,em. $n$ is clipped to $\pm1000$.}
 
 \section{Cross-compatibility with \pdftex and/or \luatex}
 
+\subsection{Geometry}
+
 \cmd|\pdfpageheight|
 \xarg{dimension}
 \desc{The height of the PDF page.}
@@ -1099,6 +1143,8 @@ the specified \xarg{font} to $n/1000$\,em. $n$ is clipped to $\pm1000$.}
 \desc{Retrieves the vertical position saved by \texttt{\char`\\pdfsavepos}.}
 \endcmd
 
+\subsection{Programming}
+
 \cmd|\ifincsname...(\else...)\fi|
 \desc{\tex conditional to branch true if the expansion occurs within
 \texttt{\char`\\csname ... \char`\\endcsname}.}
@@ -1111,15 +1157,18 @@ the specified \xarg{font} to $n/1000$\,em. $n$ is clipped to $\pm1000$.}
 \end{example}
 
 \cmd|\ifprimitive| \xarg{control sequence} |...(\else...)\fi|
-\desc{\tex conditional to test if a control sequence is a primitive and
-that it has not been redefined.}
+\desc{\tex conditional to test if a control sequence is a primitive
+which still has its primitive meaning, \ie, has not been redefined or
+undefined.}
 \endcmd
 
 \cmd|\primitive|
 \xarg{control sequence}
-\desc{If the control sequence is a primitive that’s been redefined, this
-command causes it to expand with its original (i.e., primitive)
-definition.}
+\desc{This command executes the primitive meaning of the following control
+sequence, regardless of whether the control sequence has been redefined
+or made undefined.  If the primitive was expandable, \cs{primitive} expands
+also.  On the other hand, if the control sequence never was a primitive,
+nothing happens and no error is raised.}
 \endcmd
 
 \cmd|\shellescape|
@@ -1156,6 +1205,88 @@ Therefore, |\a| is greater than |\z|: \strcmp{\a}{\z}
 Also note that catcodes are ignored: \strcmp{b}{\b}
 \end{example}
 
+\subsection{Randomness}
+
+\cmd|\normaldeviate|
+\xarg{number}
+\desc{Generate a normally-distributed random integer with a mean of $0$ and
+standard deviation $65\,536$. That is, about $68$\% of the time, the result
+will be between $−65\,536$ and $65\,536$ (one standard deviation away from
+the mean). About $95\%$ of results will be within two standard deviations, and
+$99.7$\% within three.}
+\endcmd
+
+\cmd|\randomseed|
+\desc{A read-only integer which allows querying of the random seed.}
+\endcmd
+
+\cmd|\setrandomseed|
+\xarg{number}
+\desc{Set the random seed to a specific value, allowing you to replay
+sequences of semi-randoms at a later moment.}
+\endcmd
+
+\cmd|\uniformdeviate|
+\xarg{number}
+\desc{Generate a uniformly-distributed random integer value between $0$
+(inclusive) and ⟨number⟩ (exclusive).}
+\endcmd
+
+\subsection{Timing}
+
+\cmd|\elapsedtime|
+\desc{Return a number that represents the time elapsed from the moment of
+the start of the run or the last point at which the timer was reset.
+The elapsed time is returned in `scaled seconds', meaning seconds divided by
+$65\,536$. If the time exceeds $32\,767$ seconds, the constant value
+$2^{31} − 1$ will be returned.}
+\endcmd
+
+\cmd|\resettimer|
+\desc{Reset the internal timer to $0$.}
+\endcmd
+
+\subsection{File queries}
+
+\cmd|\filedump|
+\texttt{[offset]} \xarg{number}
+\texttt{[length]} \xarg{number}
+\xarg{file}
+\desc{Expands to a hexadecimal dump of the contents of the file, starting
+from position zero and extending to the end of the file unless either an
+offset or length are given.}
+\endcmd
+
+\cmd|\filemoddate|
+\xarg{file name}
+\desc{Expands to the date the file was last modified in the format
+\texttt{D:YYYYMMDDHHMMSS+ZZZZ} as a string.}
+\endcmd
+
+\cmd|\filesize|
+\xarg{file name}
+\desc{Expands to the size of the file in bytes.}
+\endcmd
+
+\cmd|\mdfivesum|
+\texttt{[file]}
+\xarg{text}
+\desc{Expands to the MD5 sum of the \meta{text}, or if the \texttt{file}
+keyword is given, the MD5 sum of the file contents.}
+\endcmd
+
+\subsection{Fonts}
+
+\cmd|\pdfmapfile|
+\xarg{map spec}
+\desc{Defined in \texttt{xe(la)tex.ini} to place a whatsit special for \texttt{xdvipdfmx} to set a font map file. See the \pdftex user manual for full details.}
+\endcmd
+
+\cmd|\pdfmapline|
+\xarg{line from map spec}
+\desc{Defined in \texttt{xe(la)tex.ini} to place a whatsit special for \texttt{xdvipdfmx} to set up a font map. See the \pdftex user manual for full details.}
+\endcmd
+
 \cmd|\suppressfontnotfounderror|
 \xarg{integer}
 \desc{When set to zero (default) if a font is loaded that cannot be
@@ -1167,30 +1298,23 @@ suppressed and the font control sequence being defined is set to
 \suppressfontnotfounderror=1
 \font\x="ImpossibleFont" at 10pt
 \ifx\x\nullfont
-  \font\x="Georgia" at 10pt
+  \font\x="[texgyrepagella-regular.otf]" at 10pt
 \fi
 \x This would be ‘ImpossibleFont’, if it existed.
 \end{example}
 \endcmd
 
-\cmd|\pdfmapfile|
-\xarg{map spec}
-\desc{Defined in \texttt{xe(la)tex.ini} to place a whatsit special for \texttt{xdvipdfmx} to set a font map file. See the \pdftex user manual for full details.}
-\endcmd
-
-\cmd|\pdfmapline|
-\xarg{line from map spec}
-\desc{Defined in \texttt{xe(la)tex.ini} to place a whatsit special for \texttt{xdvipdfmx} to set up a font map. See the \pdftex user manual for full details.}
-\endcmd
 
 \section{Misc.}
 
 \cmd|\XeTeXversion|
-\desc{Expands to a number corresponding to the \xetex version.}
+\desc{Expands to a number corresponding to the \xetex version:
+      \the\XeTeXversion.}
 \endcmd
 
 \cmd|\XeTeXrevision|
-\desc{Expands to a string corresponding to the \xetex revision number.}
+\desc{Expands to a string corresponding to the \xetex revision number:
+      \XeTeXrevision.}
 \endcmd
 
 \begin{example}
@@ -1198,4 +1322,5 @@ The \xetex version used to typeset this document is:
 \the\XeTeXversion\XeTeXrevision
 \end{example}
 
+
 \end{document}