xetexref update (12sep10)

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

2 files changed, 91 insertions, 12 deletions

diff --git a/Master/texmf-dist/doc/xetex/xetexref/XeTeX-reference.ltx b/Master/texmf-dist/doc/xetex/xetexref/XeTeX-reference.ltx
index 21433418434..bfb88cff4d7 100644
--- a/Master/texmf-dist/doc/xetex/xetexref/XeTeX-reference.ltx
+++ b/Master/texmf-dist/doc/xetex/xetexref/XeTeX-reference.ltx
@@ -14,6 +14,8 @@
 \usepackage{geometry}
 %\geometry{screen,margin=3cm}
 
+\def\PDF{\textsc{pdf}}
+
 \hypersetup{colorlinks,linkcolor=black,urlcolor=black}
 
 \usepackage[it]{titlesec}
@@ -31,8 +33,11 @@
     aftersave={%
       \begin{minipage}{\linewidth}
         \UseVerb{CMD}}]{CMD}}
+\edef\|{|}
 \DefineShortVerb{\|}
-\newcommand\xarg[1]{‹\textit{#1}›}
+\newcommand\xarg[1]{\texttt‹{\rmfamily\itshape #1}\texttt›}
+\def\<#1>{\xarg{#1}}
+\newcommand\oarg[1]{\texttt{[\,#1\,]}}
 \newcommand\desc[1]{\par#1\par}
 \def\endcmd{%
   \end{minipage}  
@@ -112,7 +117,7 @@ This syntax looks something like\par
 {\centering|\font\1="|\xarg{font name}\xarg{font options}|:|\xarg{font features}|"| \xarg{\TeX\ font features}\par}\noindent
 The \xarg{font name} is the actual name of the font (e.g., `|Charis SIL|') and the only mandatory part of the above syntax. 
 
-When using the |xdvipdfmx| driver, it is possible to use fonts
+When using the |xdvipdfmx| driver (which is the default), it is possible to use fonts
 that aren't installed in the operating system by surrounding their name with square brackets. The current directory and the |texmf| trees are searched for files named in this way, or the path may be embedded in the
 font declaration. \Eg,
 \begin{quote}\small
@@ -216,7 +221,12 @@ Enables glyph rotation in the output so vertical typesetting can be performed.
 
 \cmd|\XeTeXglyph|
 \xarg{Glyph slot}
-\desc{Inserts the glyph in \xarg{slot} of the current font. \strong{Font specific}, so will give different output for different fonts.}
+\desc{Inserts the glyph in \xarg{slot} of the current font. \strong{Font specific}, so will give different output for different fonts and possibly even different versions of the same font.}
+\endcmd
+
+\cmd|\XeTeXcountglyphs|
+\xarg{Font}
+\desc{The count of the number of glyphs in the specified \xarg{font}.}
 \endcmd
 
 \cmd|\XeTeXglyphindex|
@@ -482,6 +492,13 @@ In the following commands, \xarg{fam.} is a number (0--255) representing font to
 \desc{Defines a maths glyph accessible via a control sequence.}
 \endcmd
 
+\cmd|\XeTeXmathcharnumdef|
+\xarg{control sequence}
+\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{XeTeXmathcodenum}. This would be used to replace legacy code such as \cs{mathchardef}\cs{foo}\texttt{=}\cs{mathcode}\texttt{`}\cs{\-}.}
+\endcmd
+
 \cmd|\XeTeXdelcode|
 \xarg{char slot}
 \opteq
@@ -569,7 +586,7 @@ aAa A a B aBa BB
 \end{example}
 
 \noindent In the above example the input text is typeset as\par
-{\centering\verb|a[\itshape A\unshape]a A a \bgroup\color{blue}B\egroup aBa B.B|\par}
+{\centering\verb|a[\itshape A\upshape]a A a \bgroup\color{blue}B\egroup aBa B.B|\par}
 
 \newpage
 \section{Encodings}
@@ -624,30 +641,79 @@ aAa A a B aBa BB
 
 \section{Graphics}
 
-This description is incomplete.
+Thanks to Heiko Oberdiek, Paul Isambert, and William Adams for their help with the documentation in this section.
 
 \cmd|\XeTeXpicfile|
 \xarg{filename}
-\xarg{optional options}
-\desc{Insert an image.}
+\oarg{ scaled \xarg{int} \|
+  xscaled \xarg{int} \|
+  yscaled \xarg{int} \| \\\hspace*{2em}
+  width \xarg{dimen} \|
+  height \xarg{dimen} \|
+  rotated \xarg{decimal} }
+\desc{Insert an image. See below for explanation of optional arguments.}
 \endcmd
 
 \cmd|\XeTeXpdffile|
 \xarg{filename}
-\xarg{optional options}
-\desc{Insert (pages of) a PDF.}
+\oarg{page \xarg{int}}
+\oarg{ crop \| media \| bleed \| trim \| art }\\\hspace*{2em}
+\oarg{scaled \xarg{int} \|
+  xscaled \xarg{int} \|
+  yscaled \xarg{int} \|
+  width \xarg{dimen} \|\\\hspace*{2em}~
+  height \xarg{dimen} \|
+  rotated \xarg{decimal}}
+\desc{Insert (pages of) a \PDF{}. See below for explanation of optional arguments.}
 \endcmd
 
-\section{Parity with \pdfTeX}
+\noindent
+In the graphic/\PDF{} commands above,
+\xarg{filename} is the usual file name argument of \cs{input}, \cs{openin}, \etc.
+It must not terminated by \cs{relax} if options are given.  
+\xarg{int} and \xarg{dimen} are the usual integer or dimen specifications
+of regular \TeX.
+
+The rotation is specified in degrees (\ie, an input of `|360|' is full circle)  
+and the rotation is counterclockwise. The syntax of \xarg{decimal}
+require some explanation:
+\begin{quote}
+\<decimal> $\to$ \<optional signs>\<unsigned decimal>\\
+\<unsigned decimal> $\to$ \<normal decimal> \| \<coerced dimen> \| \<internal dimen>\\
+\<normal decimal> -> \<normal integer> \| \<decimal constant>
+\end{quote}
+A \xarg{coerced dimen} or \xarg{internal dimen} is interpreted as number with  
+unit `|pt|'. For example, for a rotation specified with a dimension \cs{testdim},
+\begin{itemize}
+\item \verb|\testdim=45pt  | results in a rotation of 45\textdegree,
+\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  
+within limits $-16384 < x < 16384$.
+
+The \cs{XeTeXpdffile} command takes one more optional argument for specifying to which `box' the \PDF{} should be cropped before inserting it (the second optional argument listed in thes syntax of \cs{XeTeXpdffile} above). The \PDF{} standard defines a number of (rectangular) bounding boxes that may be specified for various purposes. These are described in the \PDF{} Standard\footnote{Adobe Systems Incorporated, 2008:\\ \url{http://www.adobe.com/devnet/acrobat/pdfs/PDF32000_2008.pdf}} and summarised below.
+\begin{quote}
+\begin{description}
+\item[media] the box defining the physical page size.
+\item [crop] the box of the page contents for display/printing purposes.
+\item [bleed] the box containing the page contents plus whatever extra space required for printing purposes.
+\item [trim] the box of the finished page after trimming the printed `bleed box'.
+\item [art] the box containing the `meaningful content' of the page. This could be the crop box with boilerplate text/logos trimmed off.
+\end{description}
+\end{quote}
+When not specified in the \PDF{} to be inserted, the crop box defaults to the media box, and the bleed, trim, and art boxes default to the crop box.
+
+\section{Cross-compatibility with \pdfTeX\ and/or Lua\TeX}
 
 \cmd|\pdfpageheight|
 \xarg{dimension}
-\desc{The height of the PDF page.}
+\desc{The height of the \PDF{} page.}
 \endcmd
 
 \cmd|\pdfpagewidth|
 \xarg{dimension}
-\desc{The width of the PDF page.}
+\desc{The width of the \PDF{} page.}
 \endcmd
 
 \cmd|\pdfsavepos|
@@ -708,6 +774,19 @@ Therefore, |\a| is greater than |\z|: \strcmp{\a}{\z}
 Also note that catcodes are ignored: \strcmp{b}{\b}
 \end{example}
 
+\cmd|\suppressfontnotfounderror|
+\xarg{integer}
+\desc{When set to zero (default) if a font is loaded that cannot be located by \XeTeX, an error message will result and typesetting will halt under normal circumstances. When set to one, this error message is suppressed and the font control sequence being defined is set to \cs{nullfont}.}
+\begin{example}
+\suppressfontnotfounderror=1
+\font\x="ImpossibleFont" at 10pt
+\ifx\x\nullfont
+  \font\x="Georgia" at 10pt
+\fi
+\x This would be ‘ImpossibleFont’, if it existed.
+\end{example}
+\endcmd
+
 \section{Misc.}
 
 \cmd|\XeTeXversion|
diff --git a/Master/texmf-dist/doc/xetex/xetexref/XeTeX-reference.pdf b/Master/texmf-dist/doc/xetex/xetexref/XeTeX-reference.pdf
index ae607f81eb0..963912dc8a4 100644
--- a/Master/texmf-dist/doc/xetex/xetexref/XeTeX-reference.pdf
+++ b/Master/texmf-dist/doc/xetex/xetexref/XeTeX-reference.pdf