Debian Codegraph @

texmf-dist/doc/generic/iftex/iftex.tex

raw
1 \documentclass{article}
2 \usepackage[T1]{fontenc}
3 \usepackage{hyperref}
4 \hypersetup{colorlinks}
5 \usepackage{iftex}
6
7 \title{The iftex package}
8 \author{The \LaTeX\ Project Team\thanks{%
9 \url{https://github.com/latex3/iftex}}}
10
11 \date{\csname [email protected]\endcsname}
12
13 \newcommand\cs[1]{{\ttfamily\textbackslash #1}}
14 \renewcommand*\descriptionlabel[1]{\makebox[\dimexpr\textwidth][l]{%
15 \normalfont\bfseries #1}}
16
17 \begin{document}
18
19 \maketitle
20 \tableofcontents
21
22
23 \section{Introduction}
24 This original \textsf{iftex} was written as part of the \textsf{bidi}
25 collection (by the Persian TeX Group / Vafa Khalighi)
26 and provided checks for whether a document was being
27 processed with PDF\TeX, or Xe\TeX, or Lua\TeX. This version recodes
28 the package and incorporates similar tests from the \textsf{ifetex}
29 package by Martin Scharrer, the \textsf{ifxetex} package by Will
30 Robertson, the \textsf{ifluatex} and \textsf{ifvtex}
31 packages from Heiko Oberdiek and parts of \textsf{ifptex} by Takayuki
32 Yato.
33
34 For each \TeX\ variant engine supported two commands are provided:
35 \begin{itemize}
36 \item
37 a conditional, \verb|\iffootex| that is true if the \textsf(footex)
38 engine (or a compatible extension) is being used.
39
40 For compatibility with earlier packages which did not all use the same
41 naming convention all these conditionals are provided in two forms, a
42 lowercase name \verb|\iffootex| and a mixed case name \verb|\iffooTeX|.
43
44 \item a command \verb|RequireFooTeX| which checks that \textsf{footex}
45 is being used, and stops the run with an error message if a
46 different engine is detected.
47 \end{itemize}
48
49 \section{Loading the package}
50 The package can be loaded in the usual way in both Plain \TeX\ and \LaTeX.
51 \subsection{Loading the package in plain \TeX}
52 \begin{verbatim}
53 \input iftex.sty
54 \end{verbatim}
55
56 \subsection{Loading the package in \LaTeX}
57 \begin{verbatim}
58 \usepackage{iftex}
59 \end{verbatim}
60
61 \subsection{Loading the package in ini\TeX}
62 The package assumes no existing macros and may be loaded
63 during format setup in a format without the plain \TeX\ or \LaTeX\
64 format being loaded. From an initial ini\TeX\ setup the package may
65 be loaded as for plain \TeX.
66
67 \section{Engine test conditionals}
68 All the conditionals defined here are used in the same way:
69 \begin{verbatim}
70 \ifluatex
71 luatex specific code
72 \else
73 code for other engines
74 \fi
75 \end{verbatim}
76
77
78
79 \begin{description}
80 \item[\cs{ifetex}, \cs{ifeTeX}]
81 True if an e\TeX\ enabled format is in use. (This is necessarily true
82 in all \LaTeX\ variants.)
83 \item[\cs{ifpdftex}, \cs{ifPDFTeX}]
84 True if PDF\TeX\ is in use (whether writing PDF or DVI), so this is
85 true for documents processed with both the \textsf{latex} and
86 \textsf{pdflatex} commands.
87 \item[\cs{ifxetex}, \cs{ifXeTeX}]
88 True if Xe\TeX\ is in use.
89 \item[\cs{ifluatex}, \cs{ifLuaTeX}]
90 True if Lua\TeX\ and extensions such as LuaHB\TeX\ or LuaMeta\TeX\ are in use.
91 \item[\cs{ifluahbtex}, \cs{ifLuaHBTeX}]
92 True if the \textsf{luaharftex} Lua module is available.
93 This will be true in \textsf{luahbtex} and may be true in
94 \textsf{luatex} if a binary Lua \textsf{luaharftex} module has been
95 compiled and is available in Lua's search path.
96 \item[\cs{ifluametatex}, \cs{ifLuaMetaTeX}]
97 True if LuaMeta\TeX\ is in use.
98 \item[\cs{ifptex}, \cs{ifpTeX}]
99 True if any of the p\TeX\ variants are in use. (Note that the \textsf{ptex} command
100 uses the \textsf{uptex} engine in current releases.)
101 \item[\cs{ifuptex}, \cs{ifupTeX}]
102 True if any of the up\TeX\ variants are in use. (\verb|\ifetex| could
103 be used in addition to distinguish \textsf{uptex} and \textsf{euptex}.)
104 \item[\cs{ifptexng}, \cs{ifpTeXng}]
105 True if p\TeX-ng (Asiatic p\TeX) is in use.
106 \item[\cs{ifvtex}, \cs{ifVTeX}]
107 True if V\TeX\ is in use.
108 \item[\cs{ifalephtex}, \cs{ifAlephTeX}]
109 True if Aleph is in use. (The \textsf{aleph}-based \LaTeX\ command is
110 \textsf{lamed}.)
111 \item[\cs{iftutex}, \cs{ifTUTeX}]
112 This is not strictly an engine variant, but it is true if
113 \verb|\Umathchardef| is available, which essentially means that it is
114 true for Lua\TeX\ and Xe\TeX, allowing constructs such as
115 \begin{verbatim}
116 \iftutex
117 \usepackage{fontspec}
118 \setmainfont{TeX Gyre Termes}
119 \usepackage{unicode-math}
120 \setmathfont{Stix Two Math}
121 \else
122 \usepackage{newtxtext,newtxmath}
123 \fi
124 \end{verbatim}
125 \item[\cs{iftexpadtex}, \cs{ifTexpadTeX}]
126 True if Texpad\TeX\ is in use. Please note that Texpad\TeX\ can run in two
127 modes, one which uses Unicode and native fonts internally (similar to
128 Xe\TeX\ and Lua\TeX), and one which uses 8-bit codepages internally (similar to
129 PDF\TeX). This can be determined using \cs{iftutex}.
130 \item[\cs{ifhint}, \cs{ifHINT}]
131 True if Hi\TeX\ (HINT output format) is in use.
132 \item[\cs{ifprote}, \cs{ifProte}]
133 True if a Prote engine is in use. (This means it has \TeX\
134 primitives, e\TeX\ primitives, and the additional primitives required
135 by \LaTeX.)
136 \end{description}
137
138 \section{Requiring specific engines}
139 For each supported engine, the package provides a command
140 \verb|\Require...| which checks that the document is being processed
141 with a suitable engine, and stops with an error message if not.
142
143 \begin{description}
144 \item[\cs{RequireeTeX}]
145 \item[\cs{RequirePDFTeX}]
146 \item[\cs{RequireXeTeX}]
147 \item[\cs{RequireLuaTeX}]
148 \item[\cs{RequireLuaHBTeX}]
149 \item[\cs{RequireLuaMetaTeX}]
150 \item[\cs{RequirepTeX}]
151 \item[\cs{RequireupTeX}]
152 \item[\cs{RequirepTeXng}]
153 \item[\cs{RequireVTeX}]
154 \item[\cs{RequireAlephTeX}]
155 \item[\cs{RequireTUTeX}]
156 \item[\cs{RequireTexpadTeX}]
157 \item[\cs{RequireHINT}]
158 \item[\cs{RequireProte}]
159 \end{description}
160
161
162 \section{Output mode conditional}
163 This package also provides an \verb|\ifpdf| conditional that is true
164 if the format is set up to output in PDF mode rather than DVI. This is
165 equivalent to the test in the existing \textsf{ifpdf} package.
166
167 Unlike the engine tests above this is defined as if by \verb|\newif|
168 with user-documented commands \verb|\pdftrue| and \verb|\pdffalse| that can
169 change the boolean value. These would be needed to reset the boolean
170 if the output mode is reset (for example by setting
171 \verb|\pdfoutput=0| in PDF\LaTeX).
172
173 Unlike the original \textsf{ifpdf} package, the version here also
174 detects PDF output mode if running in V\TeX.
175
176 \section{Additional packages}
177 This extended \textsf{iftex} is designed to replace the original
178 \textsf{iftex} and also the packages
179 \textsf{ifetex},
180 \textsf{ifluatex},
181 \textsf{ifvtex},
182 \textsf{ifxetex},
183 \textsf{ifpdf}.
184
185 This collection includes small packages with these names that include
186 the main \textsf{iftex} package, and in some cases define additional
187 commands for increased compatibility. These packages should mean that
188 authors do not need to change existing documents, although it is
189 recommended that new documents use the \textsf{iftex} package
190 directly.
191
192
193 Note that while this package provides basic support for detecting
194 p\TeX\ (Japanese \TeX) variants and is broadly compatible with the
195 \textsf{ifptex} package, the \textsf{ifptex} package has many more detailed
196 tests for p\TeX\ variants and this package does \emph{not} replace the
197 \textsf{ifptex} (or \textsf{ifxptex}) packages, which are maintained
198 by their original authors and recommended for Japanese documents that
199 need fine control over the Japanese \TeX\ system in use.
200
201 \section{Compatibility with \textsf{scrbase}}
202 The \textsf{scrbase} package (which is automatically included in the
203 popular \textsf{KOMA-Script} classes) by default defines
204 \verb|\ifpdftex| and \verb|\ifVTeX| with a different syntax. If you
205 use the \textsf{scrbase} option \verb|internalonly| then
206 \textsf{scrbase} will not define these and the definitions as
207 described here will take effect. This is recommended and will not
208 affect any \textsf{scrbase} package code as internally
209 \textsf{scrbase} uses private versions of those commands prefixed with
210 \verb|\scr@|. However this package detects if the \textsf{scrbase}
211 definitions are in effect and if so does not redefine them, for
212 compatibility with existing documents. The \textsf{iftex} versions
213 will still be available under the names \verb|\ifPDFTeX| and
214 \verb|\ifvtex|.
215
216 \end{document}