diff options
author | Karl Berry <karl@freefriends.org> | 2025-02-11 20:50:20 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2025-02-11 20:50:20 +0000 |
commit | 210bd4a987d41c57290dd6464cb673ae7ca093f3 (patch) | |
tree | 26209a93401e9aac2bf64bcfd19a532eff75f07e /Master/texmf-dist/doc | |
parent | f080d0030219823371f2991c3ebf1a4c80e0ef90 (diff) |
xetexref (11feb25)
git-svn-id: svn://tug.org/texlive/trunk@73885 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r-- | Master/texmf-dist/doc/xetex/xetexref/Makefile | 4 | ||||
-rw-r--r-- | Master/texmf-dist/doc/xetex/xetexref/README.txt | 9 | ||||
-rw-r--r-- | Master/texmf-dist/doc/xetex/xetexref/helpmsg.txt | 54 | ||||
-rw-r--r-- | Master/texmf-dist/doc/xetex/xetexref/tryxefonts.tex | 47 | ||||
-rw-r--r-- | Master/texmf-dist/doc/xetex/xetexref/xetex-reference.pdf | bin | 150779 -> 157224 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/xetex/xetexref/xetex-reference.tex | 82 |
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 Binary files differindex faf730ef480..52938e8c747 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 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} |