summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/xetex/xetexref/Makefile4
-rw-r--r--Master/texmf-dist/doc/xetex/xetexref/README.txt9
-rw-r--r--Master/texmf-dist/doc/xetex/xetexref/helpmsg.txt54
-rw-r--r--Master/texmf-dist/doc/xetex/xetexref/tryxefonts.tex47
-rw-r--r--Master/texmf-dist/doc/xetex/xetexref/xetex-reference.pdfbin150779 -> 157224 bytes
-rw-r--r--Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex82
6 files changed, 172 insertions, 24 deletions
diff --git a/Master/texmf-dist/doc/xetex/xetexref/Makefile b/Master/texmf-dist/doc/xetex/xetexref/Makefile
index b8c640f0d54..b19ad1745e8 100644
--- a/Master/texmf-dist/doc/xetex/xetexref/Makefile
+++ b/Master/texmf-dist/doc/xetex/xetexref/Makefile
@@ -21,6 +21,8 @@ pkg = xetexref
dist:
rm -rf $(pkg) $(pkg).zip
mkdir $(pkg)
- ln -s ../Makefile ../README.txt ../$(doc) ../xetex-reference.pdf $(pkg)
+ ln -s ../Makefile ../README.txt ../$(doc) ../xetex-reference.pdf \
+ ../helpmsg.txt ../tryxefonts.tex \
+ $(pkg)
zip -r $(pkg).zip $(pkg)
rm -rf $(pkg)
diff --git a/Master/texmf-dist/doc/xetex/xetexref/README.txt b/Master/texmf-dist/doc/xetex/xetexref/README.txt
index 01c88c2aaeb..cb0e3a637f9 100644
--- a/Master/texmf-dist/doc/xetex/xetexref/README.txt
+++ b/Master/texmf-dist/doc/xetex/xetexref/README.txt
@@ -1,12 +1,15 @@
# The XETEXREF documentation
-This package is a semi-official reference document for XeTeX.
-(It has not been reviewed by the XeTeX maintainers.)
+This package is a semi-official reference document for XeTeX,
+but has not been reviewed by the XeTeX maintainers.
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: <https://ctan.org/pkg/xetexref>
+Mailing list: <https://lists.tug.org/xetex>
+
+Bug reports, suggestions, improvements are welcome.
## Compilation
@@ -20,7 +23,7 @@ are required to be installed in your texmf tree and/or as system fonts:
## Legalities
-Copyright 2007-2023 Will Robertson
+Copyright 2007-2025 Will Robertson
Copyright 2019 Hironobu Yamashita
Copyright 2018 Joseph Wright
Copyright 2011-2017 Karl Berry
diff --git a/Master/texmf-dist/doc/xetex/xetexref/helpmsg.txt b/Master/texmf-dist/doc/xetex/xetexref/helpmsg.txt
new file mode 100644
index 00000000000..6f96a0cea41
--- /dev/null
+++ b/Master/texmf-dist/doc/xetex/xetexref/helpmsg.txt
@@ -0,0 +1,54 @@
+Usage: xetex [OPTION]... [TEXNAME[.tex]] [COMMANDS]
+ or: xetex [OPTION]... \FIRST-LINE
+ or: xetex [OPTION]... &FMT ARGS
+ Run XeTeX on TEXNAME, usually creating TEXNAME.pdf.
+ Any remaining COMMANDS are processed as XeTeX input, after TEXNAME is read.
+ If the first line of TEXNAME is %&FMT, and FMT is an existing .fmt file,
+ use it. Else use `NAME.fmt', where NAME is the program invocation name,
+ most commonly `xetex'.
+
+ Alternatively, if the first non-option argument begins with a backslash,
+ interpret all non-option arguments as a line of XeTeX input.
+
+ Alternatively, if the first non-option argument begins with a &, the
+ next word is taken as the FMT to read, overriding all else. Any
+ remaining arguments are processed as above.
+
+ If no arguments or options are specified, prompt for input.
+
+-cnf-line=STRING parse STRING as a configuration file line
+-etex enable e-TeX extensions
+[-no]-file-line-error disable/enable file:line:error style messages
+-fmt=FMTNAME use FMTNAME instead of program name or a %& line
+-halt-on-error stop processing at the first error
+-ini be xeinitex, for dumping formats; this is implicitly
+ true if the program name is `xeinitex'
+-interaction=STRING set interaction mode (STRING=batchmode/nonstopmode/
+ scrollmode/errorstopmode)
+-jobname=STRING set the job name to STRING
+-kpathsea-debug=NUMBER set path searching debugging flags according to
+ the bits of NUMBER
+[-no]-mktex=FMT disable/enable mktexFMT generation (FMT=tex/tfm)
+-mltex enable MLTeX extensions such as \charsubdef
+-output-comment=STRING use STRING for XDV file comment instead of date
+-output-directory=DIR use existing DIR as the directory to write files in
+-output-driver=CMD use CMD as the XDV-to-PDF driver instead of xdvipdfmx
+-no-pdf generate XDV (extended DVI) output rather than PDF
+[-no]-parse-first-line disable/enable parsing of first line of input file
+-papersize=STRING set PDF media size to STRING
+-progname=STRING set program (and fmt) name to STRING
+-recorder enable filename recorder
+[-no]-shell-escape disable/enable \write18{SHELL COMMAND}
+-shell-restricted enable restricted \write18
+-src-specials insert source specials into the XDV file
+-src-specials=WHERE insert source specials in certain places of
+ the XDV file. WHERE is a comma-separated value
+ list: cr display hbox math par parend vbox
+-synctex=NUMBER generate SyncTeX data for previewers according to
+ bits of NUMBER (`man synctex' for details)
+-translate-file=TCXNAME (ignored)
+-8bit make all characters printable, don't use ^^X sequences
+-help display this help and exit
+-version output version information and exit
+
+Email bug reports to xetex@tug.org (https://lists.tug.org/xetex).
diff --git a/Master/texmf-dist/doc/xetex/xetexref/tryxefonts.tex b/Master/texmf-dist/doc/xetex/xetexref/tryxefonts.tex
new file mode 100644
index 00000000000..407a65d3111
--- /dev/null
+++ b/Master/texmf-dist/doc/xetex/xetexref/tryxefonts.tex
@@ -0,0 +1,47 @@
+% Copyright 2011 Karl Berry.
+% You may freely use, modify, and/or distribute this file, without limitation.
+% Experimentally determine what XeTeX finds with different syntaxes.
+
+% fc-list : family style file spacing
+% reports files et al.
+
+\XeTeXtracingfonts = \maxdimen
+
+% with quotes and no brackets, first looked up as otf/ttf, then as tfm.
+
+% fc-list reports /usr/share/X11/fonts,
+% XeTeX finds /usr/share/fonts/default/ghostscript/putr.pfa. Why?
+\font\1 = "Utopia" \1 utopia
+
+% fc-list reports /usr/share/X11/fonts/Type1/cursor.pfa,
+% XeTeX finds it there. But it doesn't work, xdvipdfmx reports:
+% ** ERROR ** Invalid font: -1 (0). Why?
+\font\1 = "Cursor" \1 cursor
+
+% this fails, presumably because it is only available as pcf:
+%\font\1 = "Console" \1 console
+
+% tfm ok:
+\font\1 = "cmr10" \1 hello.
+
+
+% with quotes and square brackets, looked up as otf/ttf/pfb. This works:
+\font\1 = "[lmroman10-regular.otf]" at 16pt \1 lmotf
+
+% This works, finds cmr10.pfb in tree (for output):
+\font\1 = "[cmr10]" at 16pt \1 lmtfm
+
+
+% without quotes, always looked up as tfm. Thus, this fails:
+%\font\1 = lmroman10-regular.otf at 16pt \1 lm
+\end
+
+% From XeTeXFontMgr.h:
+ PlatformFontRef findFont(const char* name, char* variant, double ptSize);
+ // 1st arg is name as specified by user (C string, UTF-8)
+ // 2nd is /B/I/AAT/ICU[/USP]/S=## qualifiers
+ // 1. try name given as "full name"
+ // 2. if there's a hyphen, split and try "family-style"
+ // 3. try as PostScript name
+ // 4. try name as family with "Regular/Plain/Normal" style
+ // apply style qualifiers and optical sizing if present
diff --git a/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.pdf b/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.pdf
index faf730ef480..52938e8c747 100644
--- a/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.pdf
+++ b/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex b/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex
index e034026aa1c..a124048087c 100644
--- a/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex
+++ b/Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex
@@ -21,12 +21,7 @@
\author{Will Robertson \and Khaled Hosny \and Karl Berry}
\date{\today}
-\suppressfontnotfounderror=1
-\tracinglostchars=1
-
-\makeatletter
-\def\@dotsep{999}
-\makeatother
+\tracinglostchars=5
\usepackage{refstyle} % must load before unicode-math with 2023 LaTeX.
% https://tex.stackexchange.com/questions/675145
@@ -54,7 +49,7 @@
AutoFakeSlant=.2]\fi
\setmathfont{texgyrepagella-math.otf}
-\usepackage{calc,fancyvrb,hyperref,varioref,xcolor,hologo,xspace}
+\usepackage{calc,fancyvrb,hyperref,varioref,verbatim,xcolor,hologo,xspace}
\usepackage{geometry}
%\geometry{screen,margin=3cm}
@@ -1027,11 +1022,11 @@ aAa A a B aBa BB
\desc{Specify whether \xetex is to perform normalisation on the input
text and, if so, what type of normalisation to use. See
\url{https://unicode.org/reports/tr15/} for a description of Unicode
-normalisation. The \<Integer> value can be:\medskip
+normalisation. The \<integer> value can be:\medskip
\begin{optdesc}
\item[0] (default) do not perform normalisation.
\item[1] normalise to NFC form, using precomposed characters where possible
- instead base characters with combining marks.
+ instead of base characters with combining marks.
\item[2] normalise to NFD form, using base characters with combining marks
instead of precomposed characters.
\end{optdesc}}
@@ -1039,12 +1034,24 @@ normalisation. The \<Integer> value can be:\medskip
\cmd|\XeTeXinputencoding|
\xarg{charset name}
-\desc{Defines the input encoding of the following text.}
+
+\desc{Defines the input encoding of the following text. The argument is
+scanned like a filename, so can be surrounded by ASCII single or double
+quote characters, but braces should be avoided. If the name is not
+predefined, it is passed to the ICU routine \texttt{ucnv\char`_open}.
+Details are described at
+\url{https://tex.stackexchange.com/questions/324948/}, or see the source
+file \texttt{XeTeX\char`\_ext.c}, function
+\texttt{getencodingmodeandinfo}. A simple example:}
+\begin{example}
+\XeTeXinputencoding ISO-8859-1
+\end{example}
\endcmd
\cmd|\XeTeXdefaultencoding|
\xarg{charset name}
-\desc{Defines the input encoding of subsequent files to be read.}
+\desc{Defines the input encoding of subsequent files to be read. Handled
+analogously to the above.}
\endcmd
\section{Line breaking}
@@ -1062,12 +1069,12 @@ allowed. Off, 0, by default.}
\cmd|\XeTeXlinebreakskip|
\xarg{glue}
-\desc{Inter-character linebreak stretch}
+\desc{Inter-character linebreak stretch.}
\endcmd
\cmd|\XeTeXlinebreakpenalty|
\xarg{integer}
-\desc{Inter-character linebreak penalty}
+\desc{Inter-character linebreak penalty.}
\endcmd
\cmd|\XeTeXupwardsmode|
@@ -1214,10 +1221,10 @@ the horizontal list stored in \cs{box} \xarg{box number}.}
\section{Cross-compatibility with other \TeX\ engines}
-All of the major (non-frozen) \TeX\ engines support most of the
+The major (non-frozen) \TeX\ engines support most of the
functionality described in this section, in one way or another, so that
macro formats (e.g., \LaTeX) can make use of it. Please see the
-\pdftex\ manual for details (in \pdftex, all these primitive names
+\pdftex\ manual for details (in \pdftex, almost all these primitive names
begin with \verb|\pdf...|).
\subsection{Geometry}
@@ -1249,7 +1256,7 @@ begin with \verb|\pdf...|).
\cmd|\expanded|
\xarg{general text}
\desc{Carries out full expansion of a token list like \texttt{\char`\\message},
-but it is still expandable.}
+but is itself expandable.}
\endcmd
\cmd|\ifincsname...[\else...]\fi|
@@ -1269,6 +1276,14 @@ which still has its primitive meaning, \ie, has not been redefined or
undefined.}
\endcmd
+\cmd|\ignoreprimitiveerror|
+\xarg{integer}
+\desc{If set to 1, the \texttt{Infinite glue shrinkage found in box
+being split} error becomes a warning. Other values reserved for future
+use. Enabled with the \verb|-etex| option, which is the default
+configuration.}
+\endcmd
+
\cmd|\partokencontext|
\xarg{integer}
\desc{Specifies the cases in which \cs{par}, or the given
@@ -1354,7 +1369,6 @@ Also, macro logging is truncated at a depth $\ge$ the parameter value.}
\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
@@ -1490,12 +1504,16 @@ redefinition of the \cs{input} primitive.}
\cmd|\pdfmapfile|
\barg{\xarg{map file}}
-\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.}
+\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|
\barg{\xarg{line from map file}}
-\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.}
+\desc{Defined in \texttt{xe(la)texA.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|\tracinglostchars|
@@ -1525,6 +1543,24 @@ suppressed and the font control sequence being defined is set to
\end{example}
\endcmd
+\subsection{Output}
+
+\xetex\ outputs an extended DVI format, called XDV. Normally, \xetex\
+internally invokes the program \texttt{xdvipdfmx} to generate PDF from
+this. This can be overridden with the command line options mentioned
+just below.
+
+Thus, the version of PDF format that gets output is controlled by
+\texttt{xdvipdfmx}, not \xetex\ directly. This is given in the
+configuration file \texttt{dvipdfmx.cfg}. However, \TeX\ documents can
+specify the output version with \cs{special} directives. For example, to
+generate PDF-1.4 output (the default is newer than this):
+
+\begin{verbatim}
+\special{pdf:majorversion:1}
+\special{pdf:minorversion:4}
+\end{verbatim}
+
\subsection{Invoking \xetex}
\xetex\ has many command line options and can use many environment
@@ -1538,8 +1574,14 @@ to output its XDV (extended DVI) without further processing, and
\verb|-output-driver=|\xarg{cmd}, which processes the XDV output with
\xarg{cmd}; the default is \texttt{xdvipdfmx}.
-% doc FONTCONFIG_FILE etc in texmf.cnf
+For a list of all command line options, run \texttt{xetex --help}.
+Its current output is give below, for reference:
+
+\begin{footnotesize}
+\verbatiminput{helpmsg.txt}
+\end{footnotesize}
+% qqq doc FONTCONFIG_FILE etc in texmf.cnf
\section{Engine version}