├── expl3-doc-cn ├── expl3-cn.pdf ├── expl3-cn.tex └── expl3.dtx ├── xparse-doc-cn ├── xparse-cn.pdf └── xparse-cn.tex ├── Readme.md └── .gitignore /expl3-doc-cn/expl3-cn.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/WenboSheng/LaTeX3-doc-cn/HEAD/expl3-doc-cn/expl3-cn.pdf -------------------------------------------------------------------------------- /xparse-doc-cn/xparse-cn.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/WenboSheng/LaTeX3-doc-cn/HEAD/xparse-doc-cn/xparse-cn.pdf -------------------------------------------------------------------------------- /Readme.md: -------------------------------------------------------------------------------- 1 | # LaTeX3-doc-cn 2 | 翻译一些关于 LaTeX3 的材料 3 | 4 | ## `expl3-doc-cn` 5 | 这份文档是英文文档 [expl3.pdf](http://mirrors.ctan.org/macros/latex/contrib/l3kernel/expl3.pdf) 的中文翻译。 6 | 该手册简要介绍了 LaTeX3 语法，是学习 LaTeX3 语法以及更多进阶材料的必读文档。 7 | 8 | ## `xparse-doc-cn` 9 | 本文档是 [xparse](http://mirrors.ctan.org/macros/latex/contrib/l3packages/xparse.pdf) 宏包文档的中文翻译。 10 | 该宏包提供了 LaTeX3 编程中定义文档命令和环境的方法。 11 | 12 | # 许可协议 13 | 以上各项目以及源代码以 LPPL 协议发布（[LaTeX Project Public License](http://www.latex-project.org/lppl/)，v1.3c） 14 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | ## Repository Related Files: 2 | ref/* 3 | tmp/* 4 | src/*.pdf 5 | src/*.exe 6 | 7 | ## Core latex/pdflatex auxiliary files: 8 | *.aux 9 | *.lof 10 | *.log 11 | *.lot 12 | *.fls 13 | *.out 14 | *.toc 15 | *.fmt 16 | *.fot 17 | *.cb 18 | *.cb2 19 | 20 | ## Intermediate documents: 21 | *.dvi 22 | *-converted-to.* 23 | # these rules might exclude image files for figures etc. 24 | # *.ps 25 | # *.eps 26 | # *.pdf 27 | 28 | ## Bibliography auxiliary files (bibtex/biblatex/biber): 29 | *.bbl 30 | *.bcf 31 | *.blg 32 | *-blx.aux 33 | *-blx.bib 34 | *.brf 35 | *.run.xml 36 | 37 | ## Build tool auxiliary files: 38 | *.fdb_latexmk 39 | *.synctex 40 | *.synctex.gz 41 | *.synctex.gz(busy) 42 | *.pdfsync 43 | 44 | ## Auxiliary and intermediate files from other packages: 45 | # algorithms 46 | *.alg 47 | *.loa 48 | 49 | # achemso 50 | acs-*.bib 51 | 52 | # amsthm 53 | *.thm 54 | 55 | # beamer 56 | *.nav 57 | *.snm 58 | *.vrb 59 | 60 | # cprotect 61 | *.cpt 62 | 63 | # fixme 64 | *.lox 65 | 66 | #(r)(e)ledmac/(r)(e)ledpar 67 | *.end 68 | *.?end 69 | *.[1-9] 70 | *.[1-9][0-9] 71 | *.[1-9][0-9][0-9] 72 | *.[1-9]R 73 | *.[1-9][0-9]R 74 | *.[1-9][0-9][0-9]R 75 | *.eledsec[1-9] 76 | *.eledsec[1-9]R 77 | *.eledsec[1-9][0-9] 78 | *.eledsec[1-9][0-9]R 79 | *.eledsec[1-9][0-9][0-9] 80 | *.eledsec[1-9][0-9][0-9]R 81 | 82 | # glossaries 83 | *.acn 84 | *.acr 85 | *.glg 86 | *.glo 87 | *.gls 88 | *.glsdefs 89 | 90 | # gnuplottex 91 | *-gnuplottex-* 92 | 93 | # hyperref 94 | *.brf 95 | 96 | # knitr 97 | *-concordance.tex 98 | # TODO Comment the next line if you want to keep your tikz graphics files 99 | *.tikz 100 | *-tikzDictionary 101 | 102 | # listings 103 | *.lol 104 | 105 | # makeidx 106 | *.idx 107 | *.ilg 108 | *.ind 109 | *.ist 110 | 111 | # minitoc 112 | *.maf 113 | *.mlf 114 | *.mlt 115 | *.mtc 116 | *.mtc[0-9] 117 | *.mtc[1-9][0-9] 118 | 119 | # minted 120 | _minted* 121 | *.pyg 122 | 123 | # morewrites 124 | *.mw 125 | 126 | # mylatexformat 127 | *.fmt 128 | 129 | # nomencl 130 | *.nlo 131 | 132 | # sagetex 133 | *.sagetex.sage 134 | *.sagetex.py 135 | *.sagetex.scmd 136 | 137 | # sympy 138 | *.sout 139 | *.sympy 140 | sympy-plots-for-*.tex/ 141 | 142 | # pdfcomment 143 | *.upa 144 | *.upb 145 | 146 | # pythontex 147 | *.pytxcode 148 | pythontex-files-*/ 149 | 150 | # thmtools 151 | *.loe 152 | 153 | # TikZ & PGF 154 | *.dpth 155 | *.md5 156 | *.auxlock 157 | 158 | # todonotes 159 | *.tdo 160 | 161 | # xindy 162 | *.xdy 163 | 164 | # xypic precompiled matrices 165 | *.xyc 166 | 167 | # endfloat 168 | *.ttt 169 | *.fff 170 | 171 | # Latexian 172 | TSWLatexianTemp* 173 | 174 | ## Editors: 175 | # WinEdt 176 | *.bak 177 | *.sav 178 | 179 | # Texpad 180 | .texpadtmp 181 | 182 | # Kile 183 | *.backup 184 | 185 | # KBibTeX 186 | *~[0-9]* 187 | 188 | # system 189 | .DS_Store 190 | ._* 191 | 192 | # misc 193 | *.hd 194 | 195 | 196 | -------------------------------------------------------------------------------- /xparse-doc-cn/xparse-cn.tex: -------------------------------------------------------------------------------- 1 | \documentclass{l3doc} 2 | \usepackage[UTF8, punct = kaiming, heading=false, fontset=fandol]{ctex} 3 | \usepackage{amstext} 4 | \usepackage{hyperref} 5 | 6 | \providecommand\acro[1]{\textsc{\MakeLowercase{#1}}} 7 | \newenvironment{arg-description}{% 8 | \begin{itemize}\def\makelabel##1{\hss\llap{\bfseries##1}}}{\end{itemize}} 9 | 10 | % \title{^^A 11 | % The \textsf{xparse} package\\ Document command parser^^A 12 | % } 13 | % 14 | % \author{^^A 15 | % The \LaTeX3 Project\thanks 16 | % {^^A 17 | % E-mail: 18 | % \href{mailto:latex-team@latex-project.org} 19 | % {latex-team@latex-project.org}^^A 20 | % }^^A 21 | % } 22 | % 23 | % \date{Released 2018-05-12} 24 | 25 | \begin{document} 26 | 27 | \title{\textsf{xparse} 宏包：进行文档命令解析\footnotemark} 28 | \author{\LaTeX3 项目组} 29 | \date{发布于 2018-08-23} 30 | 31 | \maketitle 32 | 33 | \makeatletter 34 | \def\@thefnmark{*} 35 | \@footnotetext{ 36 | 本文档是 \href{http://mirrors.ctan.org/macros/latex/contrib/l3packages/xparse.pdf}{xparse} 宏包文档的中译本。 37 | \pkg{xparse} 宏包提供了 \LaTeX3 编程中定义文档命令和环境的方法。 38 | 为方便起见修改了一些章节结构。 39 | 40 | 一些专有词汇翻译如下： 41 | \begin{description} 42 | \item[argument specification] 选项规范 43 | \item[embellishment] 装饰器 44 | \item[argument processors] 选项处理器 45 | \end{description} 46 | 47 | 本文档的地址为：\url{https://github.com/WenboSheng/LaTeX3-doc-cn/xparse-doc-cn} 48 | 49 | 本文档可在 \LaTeX\ 项目公共协议（LPPL, \LaTeX\ Project Public License）下复制和分发。 50 | LPPL 协议的内容见 \url{http://www.latex-project.org/lppl/}。 51 | \begin{flushright} 52 | 盛文博\\ 53 | \href{mailto:wbsheng88@foxmail.com}{}\\ 54 | \today 55 | \end{flushright} 56 | } 57 | \makeatother 58 | 59 | % The \pkg{xparse} package provides a high-level interface for 60 | % producing document-level commands. In that way, it is intended as 61 | % a replacement for the \LaTeXe{} \cs{newcommand} macro. However, 62 | % \pkg{xparse} works so that the interface to a function (optional 63 | % arguments, stars and mandatory arguments, for example) is separate 64 | % from the internal implementation. \pkg{xparse} provides a normalised 65 | % input for the internal form of a function, independent of the 66 | % document-level argument arrangement. 67 | % 68 | \pkg{xparse} 宏包为生成文档命令提供了高层次接口， 69 | 旨在代替 \LaTeXe{} 的 \cs{newcommand} 宏。 70 | \pkg{xparse} 将为函数准备的接口（例如可选项、星号、必选项等） 71 | 与内部具体实现相分离。 72 | \pkg{xparse} 将区分函数的内部形式与文档水平的选项组织， 73 | 并为前者提供了标准化输入。 74 | 75 | % At present, the functions in \pkg{xparse} which are regarded as 76 | % \enquote{stable} are: 77 | % \begin{itemize} 78 | % \item \cs{NewDocumentCommand} 79 | % \item \cs{RenewDocumentCommand} 80 | % \item \cs{ProvideDocumentCommand} 81 | % \item \cs{DeclareDocumentCommand} 82 | % \item \cs{NewDocumentEnvironment} 83 | % \item \cs{RenewDocumentEnvironment} 84 | % \item \cs{ProvideDocumentEnvironment} 85 | % \item \cs{DeclareDocumentEnvironment} 86 | % \item \cs{NewExpandableDocumentCommand} 87 | % \item \cs{RenewExpandableDocumentCommand} 88 | % \item \cs{ProvideExpandableDocumentCommand} 89 | % \item \cs{DeclareExpandableDocumentCommand} 90 | % \item \cs{IfNoValue(TF)} 91 | % \item \cs{IfValue(TF)} 92 | % \item \cs{IfBoolean(TF)} 93 | % \end{itemize} 94 | % with the other functions currently regarded as \enquote{experimental}. Please 95 | % try all of the commands provided here, but be aware that the 96 | % experimental ones may change or disappear. 97 | % 98 | 目前，\pkg{xparse} 中可以认为是“稳定”的函数有： 99 | \begin{itemize} 100 | \item \cs{NewDocumentCommand} 101 | \item \cs{RenewDocumentCommand} 102 | \item \cs{ProvideDocumentCommand} 103 | \item \cs{DeclareDocumentCommand} 104 | \item \cs{NewDocumentEnvironment} 105 | \item \cs{RenewDocumentEnvironment} 106 | \item \cs{ProvideDocumentEnvironment} 107 | \item \cs{DeclareDocumentEnvironment} 108 | \item \cs{NewExpandableDocumentCommand} 109 | \item \cs{RenewExpandableDocumentCommand} 110 | \item \cs{ProvideExpandableDocumentCommand} 111 | \item \cs{DeclareExpandableDocumentCommand} 112 | \item \cs{IfNoValue(TF)} 113 | \item \cs{IfValue(TF)} 114 | \item \cs{IfBoolean(TF)} 115 | \end{itemize} 116 | 其它函数目前尚处于“实验”性质阶段。 117 | 请尝试使用这里列出的所有命令。 118 | 不过要当心的是，实验性质的函数可能会改变或取消。 119 | 120 | % \subsection{Specifying arguments} 121 | % 122 | \section{选项指定} 123 | 124 | % Before introducing the functions used to create document commands, 125 | % the method for specifying arguments with \pkg{xparse} will be 126 | % illustrated. In order to allow each argument to be defined 127 | % independently, \pkg{xparse} does not simply need to know the 128 | % number of arguments for a function, but also the nature of each 129 | % one. This is done by constructing an \emph{argument specification}, 130 | % which defines the number of arguments, the type of each argument 131 | % and any additional information needed for \pkg{xparse} to read the 132 | % user input and properly pass it through to internal functions. 133 | % 134 | 在介绍用于创建文档命令的函数之前， 135 | 首先展示在 \pkg{xparse} 中如何指定选项。 136 | 为了允许每一选项都能独立定义， 137 | \pkg{xparse} 不仅需要知道函数选项的数量，还需要知道每一选项的属性。 138 | 这可以通过构造\emph{选项规范}实现。 139 | 选项规范定义了选项数量，每一选项的类型，以及任何 \pkg{xparse} 需要的额外信息 140 | ——\pkg{xparse} 通过这些信息才可以正确地读取用户输入并将其传递给内部函数。 141 | 142 | % The basic form of the argument specifier is a list of letters, where 143 | % each letter defines a type of argument. As will be described below, 144 | % some of the types need additional information, such as default values. 145 | % The argument types can be divided into two, those which define 146 | % arguments that are mandatory (potentially raising an error if not 147 | % found) and those which define optional arguments. The mandatory types 148 | % are: 149 | 选项规范的基本形式是一组字母， 150 | 其中每一字母定义了一种选项类型。 151 | 如下所述，一些类型还需要额外信息（比如默认值）。 152 | 选项类型可以分成两种，一些定义了必选项（如果未提供则会报错），另一些定义了可选项。 153 | 必选项类型有： 154 | % \begin{itemize}[font=\ttfamily] 155 | \begin{itemize}[font=\ttfamily] 156 | % \item[m] A standard mandatory argument, which can either be a single 157 | % token alone or multiple tokens surrounded by curly braces. 158 | % Regardless of the input, the argument will be passed to the 159 | % internal code surrounded by a brace pair. This is the \pkg{xparse} 160 | % type specifier for a normal \TeX{} argument. 161 | \item[m] （mandatory）标准的必选项，可以是单记号或者是带大括号的多个记号。 162 | 不过不管实际输入是怎样，传递到内部代码的选项总是会带大括号。 163 | \pkg{xparse} 据此指定常规的 \TeX{} 选项类型。 164 | % \item[r] Reads a \enquote{required} delimited argument, where the 165 | % delimiters are given as \meta{char1} and \meta{char2}: 166 | % \texttt{r}\meta{char1}\meta{char2}. If the opening \meta{character} 167 | % is missing, the default marker |-NoValue-| will be inserted after 168 | % a suitable error. 169 | \item[r] （right）读取“必须”定界的选项，其中定界符由 \meta{char1} 和 \meta{char2} 给出， 170 | 即：\texttt{r}\meta{char1}\meta{char2}。 171 | 如果 \meta{字符character} 缺失，则会产生相应的错误并插入默认标记 |-NoValue-|。 172 | % \item[R] As for \texttt{r}, this is a \enquote{required} delimited 173 | % argument but has a user-definable recovery \meta{default}, given 174 | % as \texttt{R}\meta{char1}\meta{char2}\marg{default}. 175 | \item[R] （Right）与 \texttt{r} 类似，这是一个“必须”定界的选项， 176 | 不同之处是缺省标记 \meta{default} 由用户定义，即：\texttt{R}\meta{char1}\meta{char2}\marg{default}。 177 | % \item[v] Reads an argument \enquote{verbatim}, between the following 178 | % character and its next occurrence, in a way similar to the argument 179 | % of the \LaTeXe{} command \cs{verb}. Thus a \texttt{v}-type argument 180 | % is read between two matching tokens, which cannot be any of |%|, |\|, 181 | % |#|, |{|, |}| or \verb*| |. 182 | % The verbatim argument can also be enclosed between braces, |{| and |}|. 183 | % A command with a verbatim 184 | % argument will not work when it appears within an argument of 185 | % another function. 186 | \item[v] （verbatim）读取“抄录”选项，抄录内容位于接下来的字符和再次遇到该字符之间， 187 | 这与 \LaTeXe{} 命令 \cs{verb} 的选项类似。 188 | 因此，在两个匹配记号之间的内容会作为 \texttt{v} 类型的选项读取， 189 | 但匹配记号不可以是这些字符：\verb|%|、|\|、|#|、|{|、|}| 或 \verb*| |。 190 | 抄录选项也可以放在大括号 |{| 和 |}| 内。 191 | 带有抄录选项的命令不可以位于另一个函数的选项内。 192 | % \end{itemize} 193 | \end{itemize} 194 | % The types which define optional arguments are: 195 | 可选项的类型有： 196 | % \begin{itemize}[font=\ttfamily] 197 | \begin{itemize}[font=\ttfamily] 198 | % \item[o] A standard \LaTeX{} optional argument, surrounded with square 199 | % brackets, which will supply 200 | % the special |-NoValue-| marker if not given (as described later). 201 | \item[o] （optional）标准的 \LaTeX{} 可选项，位于方括号内， 202 | 如果未给出则代之以特殊标记 |-NoValue-|（稍后介绍）。 203 | % \item[d] An optional argument which is delimited by \meta{char1} 204 | % and \meta{char2}, given as follows: 205 | % \texttt{d}\meta{char1}\meta{char2}. As with \texttt{o}, if no 206 | % value is given the special marker |-NoValue-| is returned. 207 | \item[d] （delimited）由 \meta{char1} 和 \meta{char2} 定界的可选项， 208 | 即：\texttt{d}\meta{char1}\meta{char2}。 209 | 与 \texttt{o} 类似，如果未给出则返回特殊标记 |-NoValue-|。 210 | % \item[O] As for \texttt{o}, but returns \meta{default} if no 211 | % value is given. Should be given as \texttt{O}\marg{default}. 212 | \item[O] （Optional）与 \texttt{o} 类似，但是当未给出时返回 \meta{default}。 213 | 因此形式为：\texttt{O}\marg{default}。 214 | % \item[D] As for \texttt{d}, but returns \meta{default} if no 215 | % value is given: \texttt{D}\meta{char1}\meta{char2}\marg{default}. 216 | % Internally, the \texttt{o}, \texttt{d} and \texttt{O} types are 217 | % short-cuts to an appropriated-constructed \texttt{D} type argument. 218 | \item[D] （Delimited）与 \texttt{d} 类似，但是当未给出时返回 \meta{default}， 219 | 即：\texttt{D}\meta{char1}\meta{char2}\marg{default}。 220 | 实际上， \texttt{o}, \texttt{d} 和 \texttt{O} 的内部实现其实都是特殊的 \texttt{D} 选项简称。 221 | % \item[s] An optional star, which will result in a value 222 | % \cs{BooleanTrue} if a star is present and \cs{BooleanFalse} 223 | % otherwise (as described later). 224 | \item[s] （star）可选的星号，当星号存在时会返回 \cs{BooleanTrue}，否则返回 \cs{BooleanFalse}（稍后介绍）。 225 | % \item[t] An optional \meta{char}, which will result in a value 226 | % \cs{BooleanTrue} if \meta{char} is present and \cs{BooleanFalse} 227 | % otherwise. Given as \texttt{t}\meta{char}. 228 | \item[t] （token）可选的 \meta{字符char}，当该 \meta{字符char} 存在时会返回 \cs{BooleanTrue}， 229 | 否则返回 \cs{BooleanFalse}，即形式为 \texttt{t}\meta{char}。 230 | % \item[e] A set of optional \emph{embellishments}, each of which 231 | % requires a \emph{value}: \texttt{e}\marg{chars}. If an 232 | % embellishment is not present, |-NoValue-| is returned. Each 233 | % embellishment gives one argument, ordered as for the list of 234 | % \meta{chars} in the argument specification. All \meta{chars} 235 | % must be distinct. \emph{This is an experimental type}. 236 | \item[e] （embellishment）一组可选的“装饰器”，其中每一个都需要对应的\emph{值}，即：\texttt{e}\marg{chars}。 237 | 如果某个装饰器未给出则返回 |-NoValue-|。 238 | 每一个装饰器给出一个选项，并且按照选项规范中 \meta{chars} 列表进行排序。 239 | 所有的 \meta{chars} 必须互不相同。\emph{这是一个实验性质的选项类型。} 240 | % \item[E] As for \texttt{e} but returns one or more \meta{defaults} 241 | % if values are not given: \texttt{E}\marg{chars}\marg{defaults}. See 242 | % Section~\ref{sec:embellishment} for more details. 243 | \item[E] （Embellishment）与\texttt{e} 类似，但是当未给出值时返回若干个指定的默认值 \meta{defaults}， 244 | 即：\texttt{E}\marg{chars}\marg{defaults}。 245 | 详见第~\ref{sec:embellishment} 节。 246 | % \end{itemize} 247 | % 248 | \end{itemize} 249 | 250 | % Using these specifiers, it is possible to create complex input syntax 251 | % very easily. For example, given the argument definition 252 | % `|s o o m O{default}|', the input `|*[Foo]{Bar}|' would be parsed as: 253 | % \begin{itemize}[nolistsep] 254 | % \item |#1| = |\BooleanTrue| 255 | % \item |#2| = |Foo| 256 | % \item |#3| = |-NoValue-| 257 | % \item |#4| = |Bar| 258 | % \item |#5| = |default| 259 | % \end{itemize} 260 | 使用这些选项规范就可以很容易地创建各种复杂的用户输入语法。 261 | 例如，选项定义为“|s o o m O{default}|”，那么实际输入“|*[Foo]{Bar}|”会按照如下方式解析： 262 | \begin{itemize}[nolistsep] 263 | \item |#1| = |\BooleanTrue| 264 | \item |#2| = |Foo| 265 | \item |#3| = |-NoValue-| 266 | \item |#4| = |Bar| 267 | \item |#5| = |default| 268 | \end{itemize} 269 | % whereas `|[One][Two]{}[Three]|' would be parsed as: 270 | % \begin{itemize}[nolistsep] 271 | % \item |#1| = |\BooleanFalse| 272 | % \item |#2| = |One| 273 | % \item |#3| = |Two| 274 | % \item |#4| = || 275 | % \item |#5| = |Three| 276 | % \end{itemize} 277 | % 278 | 而“|[One][Two]{}[Three]|” 的解析方式为： 279 | \begin{itemize}[nolistsep] 280 | \item |#1| = |\BooleanFalse| 281 | \item |#2| = |One| 282 | \item |#3| = |Two| 283 | \item |#4| = || 284 | \item |#5| = |Three| 285 | \end{itemize} 286 | 287 | % Delimited argument types (\texttt{d}, \texttt{o} and \texttt{r}) are 288 | % defined such that they require matched pairs of delimiters when collecting 289 | % an argument. For example 290 | % \begin{verbatim} 291 | % \NewDocumentCommand{\foo}{o}{#1} 292 | % \foo[[content]] % #1 = "[content]" 293 | % \foo[[] % Error: missing closing "]" 294 | % \end{verbatim} 295 | 定界选项类型（\texttt{d}, \texttt{o}, \texttt{r}）在确定选项时要求匹配的成对定界符。 296 | 例如： 297 | \begin{verbatim} 298 | \NewDocumentCommand{\foo}{o}{#1} 299 | \foo[[content]] % #1 = "[content]" 300 | \foo[[] % 报错信息为 Error: missing closing "]" 301 | \end{verbatim} 302 | % Also note that |{| and |}| cannot be used as delimiters as they are used 303 | % by \TeX{} as grouping tokens. Arguments to be grabbed inside these tokens 304 | % must be created as either \texttt{m}- or \texttt{g}-type arguments. 305 | % 306 | 另外要注意的是，|{| 和 |}| 不能用作定界符，因为在 \TeX{} 中这些是组记号。 307 | 在这些记号内部的选项必须以 \texttt{m} 或 \texttt{g} 类型进行创建。 308 | 309 | % Within delimited arguments, non-balanced or otherwise awkward tokens may 310 | % be included by protecting the entire argument with a brace pair 311 | % \begin{verbatim} 312 | % \NewDocumentCommand{\foobar}{o}{#1} 313 | % \foobar[{[}] % Allowed as the "[" is 'hidden' 314 | % \end{verbatim} 315 | 在定界选项中，如果有不匹配的记号或者其它奇怪的情况，可以用大括号将整个选项保护起来再导入，例如 316 | \begin{verbatim} 317 | \NewDocumentCommand{\foobar}{o}{#1} 318 | \foobar[{[}] % 由于“[” 被“隐藏”起来，这样使用是可以的 319 | \end{verbatim} 320 | % These braces will be stripped if they surround the \emph{entire} content 321 | % of the optional argument 322 | % \begin{verbatim} 323 | % \NewDocumentCommand{\foobaz}{o}{#1} 324 | % \foobaz[{abc}] % => "abc" 325 | % \foobaz[ {abc}] % => " {abc}" 326 | % \end{verbatim} 327 | % 328 | 如果大括号将\emph{整个}可选项内容全部包含，那么在处理时会被剥离： 329 | \begin{verbatim} 330 | \NewDocumentCommand{\foobaz}{o}{#1} 331 | \foobaz[{abc}] % => "abc" 332 | \foobaz[ {abc}] % => " {abc}" 333 | \end{verbatim} 334 | 335 | % Two more characters have a special meaning when creating an argument 336 | % specifier. First, \texttt{+} is used to make an argument long (to 337 | % accept paragraph tokens). In contrast to \LaTeXe's \cs{newcommand}, 338 | % this applies on an argument-by-argument basis. So modifying the 339 | % example to `|s o o +m O{default}|' means that the mandatory argument 340 | % is now \cs{long}, whereas the optional arguments are not. 341 | % 342 | 另外还有两个字符在选项规范中有特殊意义。 343 | 首先是 \texttt{+}，用来创建 long 类型选项（可以接受跨段落的记号）。 344 | 与 \LaTeXe{} 的 \cs{newcommand} 不同，该项功能是逐选项运行的。 345 | 例如在“|s o o +m O{default}|”中，必选项是 \cs{long} 而可选项则不是。 346 | 347 | % Secondly, the character \texttt{>} is used to declare so-called 348 | % \enquote{argument processors}, which can be used to modify the contents of an 349 | % argument before it is passed to the macro definition. The use of 350 | % argument processors is a somewhat advanced topic, (or at least a less 351 | % commonly used feature) and is covered in Section~\ref{sec:processors}. 352 | % 353 | 其次是字符 \texttt{>}，用来声明所谓的“选项处理器”， 354 | 该功能可以在传递给宏定义之前修改选项内容。 355 | 某种程度上来说，选项处理器的使用已经属于高级专题， 356 | （或者至少是使用较少的特性），将在第~\ref{sec:processors} 节中讨论。 357 | 358 | % When an optional argument is followed by a mandatory argument with the 359 | % same delimiter, \pkg{xparse} issues a warning because the optional 360 | % argument could not be omitted by the user, thus becoming in effect 361 | % mandatory. This applies to \texttt{o}, \texttt{d}, \texttt{O}, 362 | % \texttt{D}, \texttt{s}, \texttt{t}, \texttt{e}, and \texttt{E} type 363 | % arguments followed by \texttt{r} or \texttt{R}-type required 364 | % arguments, but also to \texttt{g} or \texttt{G} type arguments 365 | % followed by \texttt{m} type arguments. 366 | % 367 | 如果一个可选项之后跟着一个带有相同定界符的必选项， 368 | 那么 \pkg{xparse} 会产生一个警告。 369 | 这是因为用户此时不能省略可选项，实际上该可选项是必须的。 370 | 该情景包括 \texttt{o}, \texttt{d}, \texttt{O}, \texttt{D}, \texttt{s}, \texttt{t}, \texttt{e} 和 \texttt{E} 类型 371 | 之后跟着 \texttt{r} 或 \texttt{R} 类型选项， 372 | 以及 \texttt{g} 或 \texttt{G} 之后跟着 \texttt{m} 类型选项。 373 | 374 | % As \pkg{xparse} is also used to describe interfaces that have appeared 375 | % in the wider \LaTeXe{} eco-system, it also defines additional argument 376 | % types, described in Section~\ref{sec:backwards}: the mandatory types 377 | % \texttt{l} and \texttt{u} and the optional brace group types 378 | % \texttt{g} and \texttt{G}. Their use is not recommended because it is 379 | % simpler for a user if all packages use a similar syntax. For the same 380 | % reason, delimited arguments \texttt{r}, \texttt{R}, \texttt{d} and 381 | % \texttt{D} should normally use delimiters that are naturally paired, 382 | % such as |[| and |]| or |(| and |)|, or that are identical, such as |"| 383 | % and~|"|. A very common syntax is to have one optional argument 384 | % \texttt{o} treated as a key--value list (using for instance 385 | % \pkg{l3keys}) followed by some mandatory arguments~\texttt{m} (or 386 | % \texttt{+m}). 387 | % 388 | 由于 \pkg{xparse} 也用于描述已经在 \LaTeXe{} 生态系统中广泛使用的一些接口， 389 | 因此也定义了另外一些选项类型（在第~\ref{sec:backwards} 节介绍）： 390 | 必选类型 \texttt{l} 和 \texttt{u}，以及可选的大括号组类型 \texttt{g} 和 \texttt{G}。 391 | 但是不推荐使用这些类型，因为如果所有宏包都使用相同的语法的话，那么对于用户来说过于简略。 392 | 出于同样的原因，定界选项 \texttt{r}, \texttt{R}, \texttt{d} 和 \texttt{D} 应当使用自然配对的标准定界符， 393 | 比如 |[| 和 |]|、|(| 和 |)|，或者二者是相同的，比如 |"| 和 |"|。 394 | 此外，一种非常常见的语法是将一个可选项 \texttt{o} 当作键值列表（比如使用 \pkg{l3keys}）, 395 | 之后再跟着一些必选项 \texttt{m} （或 \texttt{+m}）。 396 | 397 | % \subsection{Spacing and optional arguments} 398 | % 399 | \section{空格和可选项} 400 | 401 | % \TeX{} will find the first argument after a function name irrespective 402 | % of any intervening spaces. This is true for both mandatory and 403 | % optional arguments. So |\foo[arg]| and \verb*|\foo [arg]| are 404 | % equivalent. Spaces are also ignored when collecting arguments up 405 | % to the last mandatory argument to be collected (as it must exist). 406 | % So after 407 | % \begin{verbatim} 408 | % \NewDocumentCommand \foo { m o m } { ... } 409 | % \end{verbatim} 410 | % the user input |\foo{arg1}[arg2]{arg3}| and 411 | % \verb*|\foo{arg1} [arg2] {arg3}| will both be parsed in the same 412 | % way. 413 | % 414 | \TeX{} 会在函数名之后寻找第一个选项，无论中间是否有空格，对于必选项和可选项都是如此。 415 | 比如 |\foo[arg]| 和 \verb*|\foo [arg]| 就是等价的。 416 | 不仅如此，实际上直到最后一个必选项之前（肯定有最后一个可选项）， 417 | 空格都会忽略。 418 | 例如，使用如下定义后 419 | \begin{verbatim} 420 | \NewDocumentCommand \foo { m o m } { ... } 421 | \end{verbatim} 422 | 用户输入 |\foo{arg1}[arg2]{arg3}| 和 \verb*|\foo{arg1} [arg2] {arg3}| 效果是相同的。 423 | 424 | % The behavior of optional arguments \emph{after} any mandatory arguments is 425 | % selectable. The standard settings will allow spaces here, and thus 426 | % with 427 | % \begin{verbatim} 428 | % \NewDocumentCommand \foobar { m o } { ... } 429 | % \end{verbatim} 430 | 在必选项\emph{之后}的可选项行为则是可以人为选择的。 431 | 标准设置会允许有空格，比如 432 | \begin{verbatim} 433 | \NewDocumentCommand \foobar { m o } { ... } 434 | \end{verbatim} 435 | % both |\foobar{arg1}[arg2]| and \verb*|\foobar{arg1} [arg2]| will find an 436 | % optional argument. This can be changed by giving the modified |!| in 437 | % the argument specification: 438 | % \begin{verbatim} 439 | % \NewDocumentCommand \foobar { m !o } { ... } 440 | % \end{verbatim} 441 | % where \verb*|\foobar{arg1} [arg2]| will not find an optional argument. 442 | % 443 | 此时 |\foobar{arg1}[arg2]| 和 \verb*|\foobar{arg1} [arg2]| 都会寻找可选项。 444 | 可以通过在选项规范中给出 |!| 来改变这一行为： 445 | \begin{verbatim} 446 | \NewDocumentCommand \foobar { m !o } { ... } 447 | \end{verbatim} 448 | 此时 \verb*|\foobar{arg1} [arg2]| 就不会寻找可选项。 449 | 450 | % There is one subtly here due to the difference in handling by \TeX{} 451 | % of \enquote{control symbols}, where the command name is made up of a single 452 | % character, such as \enquote{\cmd{\\}}. Spaces are not ignored by \TeX{} 453 | % here, and thus it is possible to require an optional argument directly 454 | % follow such a command. The most common example is the use of \cmd{\\} in 455 | % \pkg{amsmath} environments. In \pkg{xparse} terms it has signature 456 | % \begin{verbatim} 457 | % \DeclareDocumentCommad \\ { !s !o } { ... } 458 | % \end{verbatim} 459 | % 460 | 要专门提到一点。\TeX{} 对“控制符号”的处理会导致细微之处的差异， 461 | 也就是说命令名称是单个字符，比如“\cmd{\\}”。 462 | 此时 \TeX{} 不会忽略空格，需要在该命令后直接跟着所需的可选项。 463 | 最常见的例子就是 \pkg{amsmath} 环境中对 \cmd{\\} 的使用。 464 | 在 \pkg{xparse} 术语标记为 465 | \begin{verbatim} 466 | \DeclareDocumentCommad \\ { !s !o } { ... } 467 | \end{verbatim} 468 | 469 | % \subsection{Required delimited arguments} 470 | % 471 | \section{必须定界的选项} 472 | 473 | % The contrast between a delimited (\texttt{D}-type) and \enquote{required 474 | % delimited} (\texttt{R}-type) argument is that an error will be raised if 475 | % the latter is missing. Thus for example 476 | % \begin{verbatim} 477 | % \NewDocumentCommand {\foobaz} {r()m} {} 478 | % \foobaz{oops} 479 | % \end{verbatim} 480 | % will lead to an error message being issued. The marker |-NoValue-| 481 | % (\texttt{r}-type) or user-specified default (for \texttt{R}-type) will be 482 | % inserted to allow error recovery. 483 | % 484 | 定界选项（\texttt{D} 类型）和“必须定界”选项（\texttt{R} 类型）的区别是，后者缺失时会报错。 485 | 例如 486 | \begin{verbatim} 487 | \NewDocumentCommand {\foobaz} {r()m} {} 488 | \foobaz{oops} 489 | \end{verbatim} 490 | 会导致生成错误信息。 491 | 其中会插入标记 |-NoValue-|（\texttt{r} 类型）或者用户指定的缺省值（对于 \texttt{R} 而言）以帮助纠错。 492 | 493 | % Users should note that support for required delimited arguments is somewhat 494 | % experimental. Feedback is therefore very welcome on the \texttt{LaTeX-L} 495 | % mailing list. 496 | % 497 | 用户需要注意，对于必须定界选项的支持还处于一定的实验性质阶段。 498 | 因此十分欢迎在 \href{http://news.gmane.org/group/gmane.comp.tex.latex.latex3}{LaTeX-L} 邮件列表上进行反馈。 499 | 500 | % \subsection{Verbatim arguments} 501 | % 502 | \section{抄录选项} 503 | 504 | % Arguments of type~\texttt{v} are read in verbatim mode, which will 505 | % result in the grabbed argument consisting of tokens of category codes 506 | % $12$~(\enquote{other}) and $13$~(\enquote{active}), except spaces, 507 | % which are given category code $10$~(\enquote{space}). The argument is 508 | % delimited in a similar manner to the \LaTeXe{} \cs{verb} function, or 509 | % by (correctly nested) pairs of braces. 510 | % 511 | 类型 \texttt{v} 的选项读取时会进入抄录模式，因此选项内容会进行转义。 512 | 其中空格的类代码为 $10$ （空格符），而其它记号的类代码为 $12$ （其它符号）或者 $13$ （活动符）。 513 | 选项的定界方式可以类似于 \LaTeXe{} 的 \cs{verb} 函数， 514 | 也可以使用嵌套正确的成对大括号。 515 | 516 | % Functions containing verbatim arguments cannot appear in the arguments 517 | % of other functions. The \texttt{v}~argument specifier includes code to check 518 | % this, and will raise an error if the grabbed argument has already been 519 | % tokenized by \TeX{} in an irreversible way. 520 | % 521 | 包含抄录选项的函数不能作为其它函数的选项内。 522 | 指示符 \texttt{v} 背后的代码会为此进行检查。 523 | 因此，如果 \TeX{} 已经用不可逆的方式将选项内容读取为记号， 524 | 那么则会报错。 525 | 526 | % By default, an argument of type~\texttt{v} must be at most one line. 527 | % Prefixing with \texttt{+} allows line breaks within the argument. 528 | % 529 | 默认情况下 \texttt{v} 类型的选项必须在一行内。 530 | 如果选项加了前缀 \texttt{+} 那么可以换行。 531 | 532 | % Users should note that support for verbatim arguments is somewhat 533 | % experimental. Feedback is therefore very welcome on the \texttt{LaTeX-L} 534 | % mailing list. 535 | % 536 | 用户需要注意，对于必须定界选项的支持还处于一定的实验性质阶段。 537 | 因此十分欢迎在 \href{http://news.gmane.org/group/gmane.comp.tex.latex.latex3}{LaTeX-L} 邮件列表上进行反馈。 538 | 539 | % \subsection{Default values of arguments} 540 | % 541 | \section{选项的默认值} 542 | 543 | % Uppercase argument types (\texttt{O}, \texttt{D}, \ldots{}) allow to 544 | % specify a default value to be used when the argument is missing; their 545 | % lower-case counterparts use the special marker |-NoValue-|. The 546 | % default value can be expressed in terms of the value of any other 547 | % arguments by using |#1|, |#2|, and so on. 548 | % \begin{verbatim} 549 | % \NewDocumentCommand {\conjugate} { m O{#1ed} O{#2} } {(#1,#2,#3)} 550 | % \conjugate {walk} % => (walk,walked,walked) 551 | % \conjugate {find} [found] % => (find,found,found) 552 | % \conjugate {do} [did] [done] % => (do,did,done) 553 | % \end{verbatim} 554 | 大写的选项类型（\texttt{O}, \texttt{D}, \ldots{}）可以为选项缺失的情形指定缺省值； 555 | 而相对应的小写类型则使用特殊标记 |-NoValue-|。 556 | 此外，也可以通过 |#1|、|#2| 这样的方式将选项的缺省值设为其它选项的值。 557 | 例如 558 | \begin{verbatim} 559 | \NewDocumentCommand {\conjugate} { m O{#1ed} O{#2} } {(#1,#2,#3)} 560 | \conjugate {walk} % => (walk,walked,walked) 561 | \conjugate {find} [found] % => (find,found,found) 562 | \conjugate {do} [did] [done] % => (do,did,done) 563 | \end{verbatim} 564 | % The default values may refer to arguments that appear later in the 565 | % argument specification. For instance a command could accept two 566 | % optional arguments, equal by default: 567 | % \begin{verbatim} 568 | % \NewDocumentCommand {\margins} { O{#3} m O{#1} m } {(#1,#2,#3,#4)} 569 | % \margins {a} {b} % => {(-NoValue-,a,-NoValue-,b)} 570 | % \margins [1cm] {a} {b} % => {(1cm,a,1cm,b)} 571 | % \margins {a} [1cm] {b} % => {(1cm,a,1cm,b)} 572 | % \margins [1cm] {a} [2cm] {b} % => {(1cm,a,2cm,b)} 573 | % \end{verbatim} 574 | % 575 | 缺省值可以涉及到选项规范中之后出现的选项。 576 | 例如，某个命令可以接受两个可选项，并且默认情况下是相同的： 577 | \begin{verbatim} 578 | \NewDocumentCommand {\margins} { O{#3} m O{#1} m } {(#1,#2,#3,#4)} 579 | \margins {a} {b} % => {(-NoValue-,a,-NoValue-,b)} 580 | \margins [1cm] {a} {b} % => {(1cm,a,1cm,b)} 581 | \margins {a} [1cm] {b} % => {(1cm,a,1cm,b)} 582 | \margins [1cm] {a} [2cm] {b} % => {(1cm,a,2cm,b)} 583 | \end{verbatim} 584 | 585 | % Users should note that support for default arguments referring to 586 | % other arguments is somewhat experimental. Feedback is therefore very 587 | % welcome on the \texttt{LaTeX-L} mailing list. 588 | % 589 | 用户需要注意，对于以其它选项作为缺省值这一功能的支持还处于一定的实验性质阶段。 590 | 因此十分欢迎在 \href{http://news.gmane.org/group/gmane.comp.tex.latex.latex3}{LaTeX-L} 邮件列表上进行反馈。 591 | 592 | % \subsection{Default values for \enquote{embellishments}} 593 | % \label{sec:embellishment} 594 | % 595 | \section{“装饰符”的默认值} 596 | \label{sec:embellishment} 597 | 598 | % The \texttt{E}-type argument allows one default value per test character. 599 | % This is achieved by giving a list of defaults for each entry in the 600 | % list, for example: 601 | % \begin{verbatim} 602 | % E{^_}{{UP}{DOWN}} 603 | % \end{verbatim} 604 | \texttt{E} 类型选项可以允许每一测试字符都有默认值。 605 | 具体方法是对于序列中的每一条目都给出默认值。例如： 606 | \begin{verbatim} 607 | E{^_}{{UP}{DOWN}} 608 | \end{verbatim} 609 | % If the list of default values is \emph{shorter} than the list of test characters, 610 | % the special |-NoValue-| marker will be returned (as for the \texttt{e}-type 611 | % argument). Thus for example 612 | % \begin{verbatim} 613 | % E{^_}{{UP}} 614 | % \end{verbatim} 615 | % has default \texttt{UP} for the |^| test character, but will return the 616 | % |-NoValue-| marker as a default for |_|. This allows mixing of explicit 617 | % defaults with testing for missing values. 618 | % 619 | 如果默认值列表的长度比测试字符列表\emph{短}， 620 | 那么将会返回特殊标记 |-NoValue-|（与 \texttt{e} 类型选项相同）。 621 | 例如 622 | \begin{verbatim} 623 | E{^_}{{UP}} 624 | \end{verbatim} 625 | 对于测试字符 |^| 会返回 \texttt{UP}，而对于 |_| 则返回默认的 |-NoValue-| 标记。 626 | 使用这种方式可以同时进行缺失值测试和显式的默认值指定。 627 | 628 | % \subsection{Declaring commands and environments} 629 | % 630 | \section{声明命令和环境} 631 | 632 | % With the concept of an argument specifier defined, it is now 633 | % possible to describe the methods available for creating both 634 | % functions and environments using \pkg{xparse}. 635 | % 636 | 定义了选项规范的概念，现在就可以描述使用 \pkg{xparse} 创建函数和环境的具体方法了。 637 | 638 | % The interface-building commands are the preferred method for 639 | % creating document-level functions in \LaTeX3. All of the functions 640 | % generated in this way are naturally robust (using the \eTeX{} 641 | % \cs{protected} mechanism). 642 | % 643 | 接口命令是在 \LaTeX3 中创建文档层面函数的首选方法。 644 | 所有用这种方式生成的函数都自然是鲁棒的（使用了 \eTeX{} 的 \cs{protected} 机制）。 645 | 646 | % \begin{function} 647 | \begin{function} 648 | % { 649 | % \NewDocumentCommand , 650 | % \RenewDocumentCommand , 651 | % \ProvideDocumentCommand , 652 | % \DeclareDocumentCommand 653 | % } 654 | % \begin{syntax} 655 | % \cs{NewDocumentCommand} \meta{Function} \Arg{arg spec} \Arg{code} 656 | % \end{syntax} 657 | { 658 | \NewDocumentCommand , 659 | \RenewDocumentCommand , 660 | \ProvideDocumentCommand , 661 | \DeclareDocumentCommand 662 | } 663 | \begin{syntax} 664 | \cs{NewDocumentCommand} \meta{函数Function} \Arg{选项规范arg spec} \Arg{代码code} 665 | \end{syntax} 666 | % This family of commands are used to create a document-level 667 | % \meta{function}. The argument specification for the function is 668 | % given by \meta{arg spec}, and expanding 669 | % to be replaced by the \meta{code}. 670 | 这一组函数用于创建文档水平的\meta{函数 function}。 671 | 该函数的选项规范由 \meta{arg spec} 给出， 672 | 然后展开为 \meta{code}。 673 | % \end{function} 674 | % 675 | \end{function} 676 | 677 | % As an example: 678 | % \begin{verbatim} 679 | % \NewDocumentCommand \chapter { s o m } 680 | % { 681 | % \IfBooleanTF {#1} 682 | % { \typesetstarchapter {#3} } 683 | % { \typesetnormalchapter {#2} {#3} } 684 | % } 685 | % \end{verbatim} 686 | 以下是一个例子： 687 | \begin{verbatim} 688 | \NewDocumentCommand \chapter { s o m } 689 | { 690 | \IfBooleanTF {#1} 691 | { \typesetstarchapter {#3} } 692 | { \typesetnormalchapter {#2} {#3} } 693 | } 694 | \end{verbatim} 695 | % would be a way to define a \cs{chapter} command which would 696 | % essentially behave like the current \LaTeXe{} command (except that it 697 | % would accept an optional argument even when a \texttt{*} was parsed). 698 | % The \cs{typesetnormalchapter} could test its first argument for being 699 | % |-NoValue-| to see if an optional argument was present. 700 | % 701 | 这段代码定义了 \cs{chapter} 命令，本质上处理机制与当前 \LaTeXe{} 的同名命令是类似的 702 | （不同之处仅在于即便有 \texttt{*} 也可以有可选项）。 703 | 命令 \cs{typesetnormalchapter} 会检测第一个选项是否为 |-NoValue-| 以判断是否有可选项。 704 | 705 | % The difference between the \cs{New\ldots} \cs{Renew\ldots}, 706 | % \cs{Provide\ldots} and \cs{Declare\ldots} versions is the behaviour 707 | % if \meta{function} is already defined. 708 | \cs{New\ldots}, \cs{Renew\ldots}, \cs{Provide\ldots}, \cs{Declare\ldots} 709 | 这些版本之间的区别在于 \meta{函数function} 是否已经有定义。 710 | % \begin{itemize} 711 | \begin{itemize} 712 | % \item \cs{NewDocumentCommand} will issue an error if \meta{function} 713 | % has already been defined. 714 | \item 如果 \meta{function} 已经有定义，那么 \cs{NewDocumentCommand} 会报错。 715 | % \item \cs{RenewDocumentCommand} will issue an error if \meta{function} 716 | % has not previously been defined. 717 | \item 如果 \meta{function} 尚未定义，那么 \cs{ReNewDocumentCommand} 会报错。 718 | % \item \cs{ProvideDocumentCommand} creates a new definition for 719 | % \meta{function} only if one has not already been given. 720 | \item 只有当 \meta{function} 尚未定义时，\cs{ProvideDocumentCommand} 才会为其创建新的定义。 721 | % \item \cs{DeclareDocumentCommand} will always create the new 722 | % definition, irrespective of any existing \meta{function} with the 723 | % same name. This should be used sparingly. 724 | \item \cs{DeclareDocumentCommand} 总是会创建新定义， 725 | 不管当前 \meta{function} 是否存在。该命令使用时应当注意克制。 726 | % \end{itemize} 727 | % 728 | \end{itemize} 729 | 730 | % \begin{texnote} 731 | % Unlike \LaTeXe{}'s \cs{newcommand} and relatives, the 732 | % \cs{NewDocumentCommand} family of functions do not prevent creation of 733 | % functions with names starting \cs{end\ldots}. 734 | % \end{texnote} 735 | % 736 | \begin{texnote} 737 | 与 \LaTeXe{} 的 \cs{newcommand} 系列不同的是， 738 | \cs{NewDocumentCommand} 系列不会阻止创建以 \cs{end\ldots} 作为开头的函数。 739 | \end{texnote} 740 | 741 | % \begin{function} 742 | \begin{function} 743 | % { 744 | % \NewDocumentEnvironment , 745 | % \RenewDocumentEnvironment , 746 | % \ProvideDocumentEnvironment , 747 | % \DeclareDocumentEnvironment 748 | % } 749 | % \begin{syntax} 750 | % \cs{NewDocumentEnvironment} \Arg{environment} \Arg{arg spec} 751 | % ~~\Arg{start code} \Arg{end code} 752 | % \end{syntax} 753 | { 754 | \NewDocumentEnvironment , 755 | \RenewDocumentEnvironment , 756 | \ProvideDocumentEnvironment , 757 | \DeclareDocumentEnvironment 758 | } 759 | \begin{syntax} 760 | \cs{NewDocumentEnvironment} \Arg{环境environment} \Arg{选项规范arg spec} 761 | ~~\Arg{开始代码start code} \Arg{结束代码end code} 762 | \end{syntax} 763 | % These commands work in the same way as \cs{NewDocumentCommand}, 764 | % etc.\@, but create environments (\cs{begin}\Arg{environment} \ldots{} 765 | % \cs{end}\Arg{environment}). Both the \meta{start code} and 766 | % \meta{end code} 767 | % may access the arguments as defined by \meta{arg spec}. 768 | % The arguments will be given following \cs{begin}\Arg{environment}. 769 | 这些命令创建环境（\cs{begin}\Arg{environment} \ldots{} \cs{end}\Arg{environment}）， 770 | 其工作原理与 \cs{NewDocumentCommand} 系列相同。 771 | 其中，\meta{start code} 和 \meta{end code} 都可以接受由 \meta{arg spec} 定义的选项。 772 | 这些选项在 \cs{begin}\Arg{environment} 之后给出。 773 | % \end{function} 774 | % 775 | \end{function} 776 | 777 | % \subsection{Testing special values} 778 | % 779 | \section{特殊值的测试} 780 | 781 | % Optional arguments created using \pkg{xparse} make use of dedicated 782 | % variables to return information about the nature of the argument 783 | % received. 784 | % 785 | 由 \pkg{xparse} 创建的可选项可以使用专门设计的变量， 786 | 进而返回关于接收选项的属性信息。 787 | 788 | % \begin{function}[EXP]{\IfNoValueT, \IfNoValueF, \IfNoValueTF} 789 | \begin{function}[EXP]{\IfNoValueT, \IfNoValueF, \IfNoValueTF} 790 | % \begin{syntax} 791 | % \cs{IfNoValueTF} \Arg{argument} \Arg{true code} \Arg{false code} 792 | % \cs{IfNoValueT} \Arg{argument} \Arg{true code} 793 | % \cs{IfNoValueF} \Arg{argument} \Arg{false code} 794 | % \end{syntax} 795 | \begin{syntax} 796 | \cs{IfNoValueTF} \Arg{选项argument} \Arg{真值代码true code} \Arg{假值代码false code} 797 | \cs{IfNoValueT} \Arg{选项argument} \Arg{真值代码true code} 798 | \cs{IfNoValueF} \Arg{选项argument} \Arg{假值代码false code} 799 | \end{syntax} 800 | % The \cs{IfNoValue(TF)} tests are used to check if \meta{argument} (|#1|, 801 | % |#2|, \emph{etc.}) is the special |-NoValue-| marker For example 802 | % \begin{verbatim} 803 | % \NewDocumentCommand \foo { o m } 804 | % { 805 | % \IfNoValueTF {#1} 806 | % { \DoSomethingJustWithMandatoryArgument {#2} } 807 | % { \DoSomethingWithBothArguments {#1} {#2} } 808 | % } 809 | % \end{verbatim} 810 | % will use a different internal function if the optional argument 811 | % is given than if it is not present. 812 | % 813 | \cs{IfNoValue(TF)} 测试可以用于检查 \meta{argument}（|#1|、|#2|等）是否为特殊标记 |-NoValue-|。例如： 814 | \begin{verbatim} 815 | \NewDocumentCommand \foo { o m } 816 | { 817 | \IfNoValueTF {#1} 818 | { \DoSomethingJustWithMandatoryArgument {#2} } 819 | { \DoSomethingWithBothArguments {#1} {#2} } 820 | } 821 | \end{verbatim} 822 | 823 | % Note that three tests are available, depending on which outcome 824 | % branches are required: \cs{IfNoValueTF}, \cs{IfNoValueT} and 825 | % \cs{IfNoValueF}. 826 | % 827 | 要注意的是，根据判断分支结果的需求，这里提供了三个测试： 828 | \cs{IfNoValueTF}, \cs{IfNoValueT} 和 \cs{IfNoValueF}。 829 | 830 | % As the \cs{IfNoValue(TF)} tests are expandable, it is possible to 831 | % test these values later, for example at the point of typesetting or 832 | % in an expansion context. 833 | % 834 | 由于 \cs{IfNoValue(TF)} 测试是可展开的，因此对于值的测试可以延时进行， 835 | 比如在排版时或者在展开的文本中进行。 836 | 837 | % It is important to note that |-NoValue-| is constructed such that it 838 | % will \emph{not} match the simple text input |-NoValue-|, \emph{i.e.} 839 | % that 840 | % \begin{verbatim} 841 | % \IfNoValueTF{-NoValue-} 842 | % \end{verbatim} 843 | % will be logically \texttt{false}. 844 | % 845 | 另外要着重指出的是，这里 |-NoValue-| 的构建方式保证其\emph{不会}匹配简单的文本输入 |-NoValue-|，即 846 | \begin{verbatim} 847 | \IfNoValueTF{-NoValue-} 848 | \end{verbatim} 849 | 判断结果为 \texttt{false}。 850 | 851 | % When two optional arguments follow each other (a syntax we typically 852 | % discourage), it can make sense to allow users of the command to 853 | % specify only the second argument by providing an empty first 854 | % argument. Rather than testing separately for emptyness and for 855 | % |-NoValue-| it is then best to use the argument type~|O| with an 856 | % empty default value, and simply test for emptyness using the 857 | % \pkg{expl3} conditional \cs{tl_if_blank:nTF} or its \pkg{etoolbox} 858 | % analogue \tn{ifblank}. 859 | 当有两个连续的可选项时（我们不鼓励这种语法）， 860 | 用户可以将第一个选项设为空而只给出第二个选项。 861 | 此时可以分别检查选项是否为空以及是否为 |-NoValue-|， 862 | 但更好的方法是使用选项类型 |O| 并将缺省值设为空， 863 | 并直接使用 \pkg{expl3} 的条件命令 \cs{tl_if_blank:nTF} 或者 \pkg{etoolbox} 中的版本 \tn{ifblank} 检查是否为空。 864 | % \end{function} 865 | % 866 | \end{function} 867 | 868 | % \begin{function}[EXP]{\IfValueT, \IfValueF, \IfValueTF} 869 | \begin{function}[EXP]{\IfValueT, \IfValueF, \IfValueTF} 870 | % \begin{syntax} 871 | % \cs{IfValueTF} \Arg{argument} \Arg{true code} \Arg{false code} 872 | % \end{syntax} 873 | \begin{syntax} 874 | \cs{IfValueTF} \Arg{选项argument} \Arg{真值代码true code} \Arg{假值代码false code} 875 | \end{syntax} 876 | % The reverse form of the \cs{IfNoValue(TF)} tests are also available 877 | % as \cs{IfValue(TF)}. The context will determine which logical 878 | % form makes the most sense for a given code scenario. 879 | 与 \cs{IfNoValue(TF)} 结果相反的测试命令也是有的，即 \cs{IfValue(TF)}。 880 | 实际语境会决定在代码中哪一种逻辑形式是最有意义的。 881 | % \end{function} 882 | % 883 | \end{function} 884 | 885 | 886 | % \begin{variable}{\BooleanFalse, \BooleanTrue} 887 | % The \texttt{true} and \texttt{false} flags set when searching for 888 | % an optional character (using \texttt{s} or \texttt{t\meta{char}}) have 889 | % names which are accessible outside of code blocks. 890 | % \end{variable} 891 | % 892 | \begin{variable}{\BooleanFalse, \BooleanTrue} 893 | 当搜索可选字符时（使用 \texttt{s} 和 \texttt{t\meta{char}}）设置的 \texttt{true} 和 \texttt{false} 标志， 894 | 这样该变量名可以在代码块之外获取。 895 | \end{variable} 896 | 897 | % \begin{function}[EXP]{\IfBooleanT, \IfBooleanF, \IfBooleanTF} 898 | \begin{function}[EXP]{\IfBooleanT, \IfBooleanF, \IfBooleanTF} 899 | % \begin{syntax} 900 | % \cs{IfBooleanTF} \Arg{argument} \Arg{true code} \Arg{false code} 901 | % \end{syntax} 902 | \begin{syntax} 903 | \cs{IfBooleanTF} \Arg{选项argument} \Arg{真值代码true code} \Arg{假值代码false code} 904 | \end{syntax} 905 | % Used to test if \meta{argument} (|#1|, |#2|, \emph{etc.}) is 906 | % \cs{BooleanTrue} or \cs{BooleanFalse}. For example 907 | % \begin{verbatim} 908 | % \NewDocumentCommand \foo { s m } 909 | % { 910 | % \IfBooleanTF {#1} 911 | % { \DoSomethingWithStar {#2} } 912 | % { \DoSomethingWithoutStar {#2} } 913 | % } 914 | % \end{verbatim} 915 | % checks for a star as the first argument, then chooses the action to 916 | % take based on this information. 917 | 用于测试 \Arg{argument}（|#1|, |#2| 等）是否为 \cs{BooleanTrue} 或 \cs{BooleanFalse}。例如 918 | \begin{verbatim} 919 | \NewDocumentCommand \foo { s m } 920 | { 921 | \IfBooleanTF {#1} 922 | { \DoSomethingWithStar {#2} } 923 | { \DoSomethingWithoutStar {#2} } 924 | } 925 | \end{verbatim} 926 | 该命令会检查第一个选项是否为星号，并基于此选择接下来的行为。 927 | % \end{function} 928 | % 929 | \end{function} 930 | 931 | % \subsection{Argument processors} 932 | % \label{sec:processors} 933 | \section{选项处理器} 934 | \label{sec:processors} 935 | 936 | 937 | % \pkg{xparse} introduces the idea of an argument processor, which is 938 | % applied to an argument \emph{after} it has been grabbed by the 939 | % underlying system but before it is passed to \meta{code}. An argument 940 | % processor can therefore be used to regularise input at an early stage, 941 | % allowing the internal functions to be completely independent of input 942 | % form. Processors are applied to user input and to default values for 943 | % optional arguments, but \emph{not} to the special |-NoValue-| marker. 944 | % 945 | \pkg{xparse} 引入了选项处理器的概念， 946 | 可以在底层系统收集选项\emph{之后}但是尚未传递给 \meta{code} 时作用在选项上。 947 | 因此，选项处理器可以用于在早期调整输入， 948 | 这样内部函数就可以完全独立于输入形式。 949 | 选项处理器作用于用户输入以及可选项的缺省值上，但不会作用于特殊标记 |-NoValue-|。 950 | 951 | % Each argument processor is specified by the syntax 952 | % \texttt{>}\marg{processor} in the argument specification. Processors 953 | % are applied from right to left, so that 954 | 每一个选项处理器都通过选项规范中的语法 \texttt{>}\marg{processor} 来指定， 955 | 然后从右到左依次执行，因此 956 | % \begin{verbatim} 957 | % >{\ProcessorB} >{\ProcessorA} m 958 | % \end{verbatim} 959 | \begin{verbatim} 960 | >{\ProcessorB} >{\ProcessorA} m 961 | \end{verbatim} 962 | % would apply \cs{ProcessorA} 963 | % followed by \cs{ProcessorB} to the tokens grabbed by the \texttt{m} 964 | % argument. 965 | % 966 | 会先将 \cs{ProcessorA} 作用在 \texttt{m} 选项收集的记号上，然后再将 \cs{ProcessorB} 作用上去。 967 | 968 | % \begin{variable}{\ProcessedArgument} 969 | \begin{variable}{\ProcessedArgument} 970 | % \pkg{xparse} defines a very small set of processor functions. In the 971 | % main, it is anticipated that code writers will want to create their 972 | % own processors. These need to accept one argument, which is the 973 | % tokens as grabbed (or as returned by a previous processor function). 974 | % Processor functions should return the processed argument as the 975 | % variable \cs{ProcessedArgument}. 976 | \pkg{xparse} 只定义了少量处理器函数。 977 | 当然，可以预见代码作者会希望创建自己的选项处理器。 978 | 这需要将收集上来的（或者由之前的处理器函数返回的）记号作为选项。 979 | 因此，处理器函数应当返回被处理的选项，这就是 \cs{ProcessedArgument} 变量。 980 | % \end{variable} 981 | % 982 | \end{variable} 983 | 984 | % \begin{function}{\ReverseBoolean} 985 | \begin{function}{\ReverseBoolean} 986 | % \begin{syntax} 987 | % \cs{ReverseBoolean} 988 | % \end{syntax} 989 | \begin{syntax} 990 | \cs{ReverseBoolean} 991 | \end{syntax} 992 | % This processor reverses the logic of \cs{BooleanTrue} and 993 | % \cs{BooleanFalse}, so that the example from earlier would become 994 | 该处理器将反转 \cs{BooleanTrue} 和 \cs{BooleanFalse} 的逻辑值， 995 | 因此之前的例子会变成： 996 | % \begin{verbatim} 997 | % \NewDocumentCommand \foo { > { \ReverseBoolean } s m } 998 | % { 999 | % \IfBooleanTF #1 1000 | % { \DoSomethingWithoutStar {#2} } 1001 | % { \DoSomethingWithStar {#2} } 1002 | % } 1003 | % \end{verbatim} 1004 | \begin{verbatim} 1005 | \NewDocumentCommand \foo { > { \ReverseBoolean } s m } 1006 | { 1007 | \IfBooleanTF #1 1008 | { \DoSomethingWithoutStar {#2} } 1009 | { \DoSomethingWithStar {#2} } 1010 | } 1011 | \end{verbatim} 1012 | % \end{function} 1013 | % 1014 | \end{function} 1015 | 1016 | % \begin{function}[updated = 2012-02-12]{\SplitArgument} 1017 | \begin{function}[updated = 2012-02-12]{\SplitArgument} 1018 | % \begin{syntax} 1019 | % \cs{SplitArgument} \Arg{number} \Arg{token} 1020 | % \end{syntax} 1021 | \begin{syntax} 1022 | \cs{SplitArgument} \Arg{数量number} \Arg{记号token} 1023 | \end{syntax} 1024 | % This processor splits the argument given at each occurrence of the 1025 | % \meta{token} up to a maximum of \meta{number} tokens (thus 1026 | % dividing the input into $\text{\meta{number}} + 1$ parts). 1027 | % An error is given if too many \meta{tokens} are present in the 1028 | % input. The processed input is placed inside 1029 | % $\text{\meta{number}} + 1$ sets of braces for further use. 1030 | % If there are fewer than \Arg{number} of \Arg{tokens} in the argument 1031 | % then |-NoValue-| markers are added at the end of the processed 1032 | % argument. 1033 | 该处理器会将选项按照 \meta{token} 的出现位置进行分割， 1034 | 并且最多有 \meta{number} 个记号（因此输入的选项分成了 $\text{\meta{number}} + 1$ 个部分）。 1035 | 如果选项输入中有过多数量的 \meta{token} 那么会报错。 1036 | 处理后的输入会放在 $\text{\meta{number}} + 1$ 个大括号集合中供进一步使用。 1037 | 如果选项中 \Arg{token} 的数量小于 \Arg{number}， 1038 | 那么会在处理后的选项末尾加上合适数量的 |-NoValue-|。 1039 | % \begin{verbatim} 1040 | % \NewDocumentCommand \foo 1041 | % { > { \SplitArgument { 2 } { ; } } m } 1042 | % { \InternalFunctionOfThreeArguments #1 } 1043 | % \end{verbatim} 1044 | \begin{verbatim} 1045 | \NewDocumentCommand \foo 1046 | { > { \SplitArgument { 2 } { ; } } m } 1047 | { \InternalFunctionOfThreeArguments #1 } 1048 | \end{verbatim} 1049 | % Any category code $13$ (active) \meta{tokens} will be replaced 1050 | % before the split takes place. Spaces are trimmed at each end of each 1051 | % item parsed. 1052 | 在分割进行之前任何类代码为 $13$ （活动符）的 \meta{token} 都会被代替。 1053 | 每一项两端的空格都会被删去。 1054 | % \end{function} 1055 | % 1056 | \end{function} 1057 | 1058 | % \begin{function}{\SplitList} 1059 | \begin{function}{\SplitList} 1060 | % \begin{syntax} 1061 | % \cs{SplitList} \Arg{token(s)} 1062 | % \end{syntax} 1063 | \begin{syntax} 1064 | \cs{SplitList} \Arg{记号token(s)} 1065 | \end{syntax} 1066 | % This processor splits the argument given at each occurrence of the 1067 | % \meta{token(s)} where the number of items is not fixed. Each item is 1068 | % then wrapped in braces within |#1|. The result is that the 1069 | % processed argument can be further processed using a mapping function. 1070 | 该处理器会将选项按照 \meta{token(s)} 进行分割，分割的项目数量不限。 1071 | 然后每一项都会包裹在 |#1| 中的大括号内。 1072 | 处理后的选项可以进一步使用映射函数进行处理。 1073 | % \begin{verbatim} 1074 | % \NewDocumentCommand \foo 1075 | % { > { \SplitList { ; } } m } 1076 | % { \MappingFunction #1 } 1077 | % \end{verbatim} 1078 | \begin{verbatim} 1079 | \NewDocumentCommand \foo 1080 | { > { \SplitList { ; } } m } 1081 | { \MappingFunction #1 } 1082 | \end{verbatim} 1083 | % If only a single \meta{token} is used for the split, any 1084 | % category code $13$ (active) \meta{token} will be replaced 1085 | % before the split takes place. 1086 | 如果只用一个 \meta{token} 进行分割， 1087 | 那么在分割进行之前任何类代码为 $13$ （活动符）的 \meta{token} 都会被代替。 1088 | % \end{function} 1089 | % 1090 | \end{function} 1091 | 1092 | % \begin{function}[EXP]{\ProcessList} 1093 | \begin{function}[EXP]{\ProcessList} 1094 | % \begin{syntax} 1095 | % \cs{ProcessList} \Arg{list} \Arg{function} 1096 | % \end{syntax} 1097 | \begin{syntax} 1098 | \cs{ProcessList} \Arg{列表list} \Arg{函数function} 1099 | \end{syntax} 1100 | % To support \cs{SplitList}, the function \cs{ProcessList} is available 1101 | % to apply a \meta{function} to every entry in a \meta{list}. The 1102 | % \meta{function} should absorb one argument: the list entry. For example 1103 | 为了支持 \cs{SplitList}，这里提供了函数 \cs{ProcessList} 。 1104 | 它可以将一个函数 \meta{function} 作用到 \meta{list} 的每一条目上。 1105 | 函数 \meta{function} 应当吸收列表条目作为选项。例如 1106 | % \begin{verbatim} 1107 | % \NewDocumentCommand \foo 1108 | % { > { \SplitList { ; } } m } 1109 | % { \ProcessList {#1} { \SomeDocumentFunction } } 1110 | % \end{verbatim} 1111 | % 1112 | \begin{verbatim} 1113 | \NewDocumentCommand \foo 1114 | { > { \SplitList { ; } } m } 1115 | { \ProcessList {#1} { \SomeDocumentFunction } } 1116 | \end{verbatim} 1117 | 1118 | % \textbf{This function is experimental.} 1119 | \textbf{该函数是实验性质的。} 1120 | % \end{function} 1121 | % 1122 | \end{function} 1123 | 1124 | % \begin{function}{\TrimSpaces} 1125 | \begin{function}{\TrimSpaces} 1126 | % \begin{syntax} 1127 | % \cs{TrimSpaces} 1128 | % \end{syntax} 1129 | \begin{syntax} 1130 | \cs{TrimSpaces} 1131 | \end{syntax} 1132 | % Removes any leading and trailing spaces (tokens with character code~$32$ 1133 | % and category code~$10$) for the ends of the argument. Thus for example 1134 | % declaring a function 1135 | 删除任何选项两端（开头和结尾）的空格（类代码为 $32$ 和 $10$ 的记号）。 1136 | 例如，声明如下函数 1137 | % \begin{verbatim} 1138 | % \NewDocumentCommand \foo 1139 | % { > { \TrimSpaces } m } 1140 | % { \showtokens {#1} } 1141 | % \end{verbatim} 1142 | \begin{verbatim} 1143 | \NewDocumentCommand \foo 1144 | { > { \TrimSpaces } m } 1145 | { \showtokens {#1} } 1146 | \end{verbatim} 1147 | % and using it in a document as 1148 | 并在文档中使用如下命令 1149 | % \begin{verbatim} 1150 | % \foo{ hello world } 1151 | % \end{verbatim} 1152 | \begin{verbatim} 1153 | \foo{ hello world } 1154 | \end{verbatim} 1155 | % will show \texttt{hello world} at the terminal, with the space at each 1156 | % end removed. \cs{TrimSpaces} will remove multiple spaces from the ends of 1157 | % the input in cases where these have been included such that the standard 1158 | % \TeX{} conversion of multiple spaces to a single space does not apply. 1159 | % 1160 | 此时会在终端显示 \texttt{hello world}，两端的空格都会删除。 1161 | 当输入的内容已经导入时，就不能应用标准 \TeX{} 将多个空格转成单个空格的机制， 1162 | 此时 \cs{TrimSpaces} 会删除多重空格。 1163 | 1164 | % \textbf{This function is experimental.} 1165 | \textbf{该函数是实验性质的。} 1166 | % \end{function} 1167 | % 1168 | \end{function} 1169 | 1170 | % \subsection{Fully-expandable document commands} 1171 | % 1172 | \section{完全展开的文档命令} 1173 | 1174 | % There are \emph{very rare} occasion when it may be useful to create 1175 | % functions using a fully-expandable argument grabber. To support this, 1176 | % \pkg{xparse} can create expandable functions as well as the usual 1177 | % robust ones. This imposes a number of restrictions on the nature of 1178 | % the arguments accepted by a function, and the code it implements. 1179 | % This facility should only be used when \emph{absolutely necessary}; 1180 | % if you do not understand when this might be, \emph{do not use these 1181 | % functions}! 1182 | % 1183 | 在极少数情况下，使用完全展开的选项收集器创建函数会更有效。 1184 | 除了常规的鲁棒函数，\pkg{xparse} 也提供了对创建可展开函数的支持。 1185 | 这对函数接受的选项属性以及实现的代码提出了许多限制。 1186 | 因此只有当\emph{绝对需要}时才应该使用该功能。 1187 | 如果你不清楚是否必要，\emph{那么不要使用这些函数}！ 1188 | 1189 | % \begin{function} 1190 | \begin{function} 1191 | % { 1192 | % \NewExpandableDocumentCommand , 1193 | % \RenewExpandableDocumentCommand , 1194 | % \ProvideExpandableDocumentCommand , 1195 | % \DeclareExpandableDocumentCommand 1196 | % } 1197 | { 1198 | \NewExpandableDocumentCommand , 1199 | \RenewExpandableDocumentCommand , 1200 | \ProvideExpandableDocumentCommand , 1201 | \DeclareExpandableDocumentCommand 1202 | } 1203 | % \begin{syntax} 1204 | % \cs{NewExpandableDocumentCommand} 1205 | % ~~~~\meta{function} \Arg{arg spec} \Arg{code} 1206 | % \end{syntax} 1207 | \begin{syntax} 1208 | \cs{NewExpandableDocumentCommand} 1209 | ~~~~\meta{函数function} \Arg{选项规范arg spec} \Arg{代码code} 1210 | \end{syntax} 1211 | % This family of commands is used to create a document-level \meta{function}, 1212 | % which will grab its arguments in a fully-expandable manner. The 1213 | % argument specification for the function is given by \meta{arg spec}, 1214 | % and the function will execute \meta{code}. In general, \meta{code} will 1215 | % also be fully expandable, although it is possible that this will 1216 | % not be the case (for example, a function for use in a table might 1217 | % expand so that \cs{omit} is the first non-expandable non-space token). 1218 | % 1219 | 这组函数创建的文档层面的 \meta{function} 会按照完全展开的方式收集选项。 1220 | 函数的选项规范由 \meta{arg spec} 给出，然后会执行 \meta{code}。 1221 | 一般而言，\meta{code} 也是完全展开的，尽管例外情况也是可以的 1222 | （例如，表格中使用的函数展开时，可以将 \cs{omit} 作为第一个不展开的非空格记号）。 1223 | 1224 | % Parsing arguments expandably imposes a number of restrictions on 1225 | % both the type of arguments that can be read and the error checking 1226 | % available: 1227 | 解析选项时就进行展开有很多限制条件，比如读取的选项类型和可用的错误检查： 1228 | % \begin{itemize} 1229 | \begin{itemize} 1230 | % \item The last argument (if any are present) must be one of the 1231 | % mandatory types \texttt{m} or \texttt{r}. 1232 | \item 最后一个选项（如果有的话）必须是必选项且类型为 \texttt{m} 或 \texttt{r}。 1233 | % \item All short arguments appear before long arguments. 1234 | \item 所有的段内（short）选项必须出现在段间（long）选项之前。 1235 | % \item The mandatory argument types \texttt{l} and \texttt{u} may 1236 | % not be used after optional arguments. 1237 | \item 必选项类型 \texttt{l} 和 \texttt{u} 不可以用在可选项之后。 1238 | % \item The optional argument types \texttt{g} 1239 | % and \texttt{G} are not available. 1240 | \item 可选项类型 \texttt{g} 和 \texttt{G} 不可用。 1241 | % \item The \enquote{verbatim} argument type \texttt{v} is not available. 1242 | \item “抄录”选项类型 \texttt{v} 不可用。 1243 | % \item Argument processors (using \texttt{>}) are not available. 1244 | \item 选项处理器（使用 \texttt{>}）不可用。 1245 | % \item It is not possible to differentiate between, for example 1246 | % |\foo[| and |\foo{[}|: in both cases the \texttt{[} will be 1247 | % interpreted as the start of an optional argument. As a 1248 | % result, checking for optional arguments is less robust than 1249 | % in the standard version. 1250 | \item 不能区分一些情况，比如 |\foo[| 和 |\foo{[}|： 1251 | 在这两种情况下 \texttt{[} 都被解释为可选项的开始。 1252 | 因此，对于可选项的检查没有标准情形时那么鲁棒。 1253 | % \end{itemize} 1254 | \end{itemize} 1255 | % \pkg{xparse} will issue an error if an argument specifier is given 1256 | % which does not conform to the first six requirements. The last 1257 | % item is an issue when the function is used, and so is beyond the 1258 | % scope of \pkg{xparse} itself. 1259 | 如果给出的选项指示符不符合前六项要求，\pkg{xparse} 就会报错。 1260 | 最后一项是关于函数何时使用的，所以已经超出了 \pkg{xparse} 本身的范畴。 1261 | % \end{function} 1262 | % 1263 | \end{function} 1264 | 1265 | 1266 | % \subsection{Access to the argument specification} 1267 | % 1268 | \section{获取选项规范} 1269 | 1270 | % The argument specifications for document commands and environments are 1271 | % available for examination and use. 1272 | % 1273 | 文档命令和环境的选项规范可以用于检查使用。 1274 | 1275 | % \begin{function}{\GetDocumentCommandArgSpec, \GetDocumentEnvironmentArgSpec} 1276 | \begin{function}{\GetDocumentCommandArgSpec, \GetDocumentEnvironmentArgSpec} 1277 | % \begin{syntax} 1278 | % \cs{GetDocumentCommandArgSpec} \meta{function} 1279 | % \cs{GetDocumentEnvironmentArgSpec} \meta{environment} 1280 | % \end{syntax} 1281 | \begin{syntax} 1282 | \cs{GetDocumentCommandArgSpec} \meta{函数function} 1283 | \cs{GetDocumentEnvironmentArgSpec} \meta{环境environment} 1284 | \end{syntax} 1285 | % These functions transfer the current argument specification for the 1286 | % requested \meta{function} or \meta{environment} into the token list 1287 | % variable \cs{ArgumentSpecification}. If the \meta{function} or 1288 | % \meta{environment} has no known argument specification then an error 1289 | % is issued. The assignment to \cs{ArgumentSpecification} is local to 1290 | % the current \TeX{} group. 1291 | 这两个函数获取 \meta{function} 函数或 \meta{environment} 环境的当前选项规范， 1292 | 并将其转换为记号列表变量 \cs{ArgumentSpecification}。 1293 | 如果 \meta{function} 或 \meta{environment} 有未知选项规范则会报错。 1294 | \cs{ArgumentSpecification} 的赋值是在当前 \TeX{} 组内局部的。 1295 | % \end{function} 1296 | % 1297 | \end{function} 1298 | 1299 | % \begin{function} 1300 | % {\ShowDocumentCommandArgSpec, \ShowDocumentEnvironmentArgSpec} 1301 | \begin{function} 1302 | {\ShowDocumentCommandArgSpec, \ShowDocumentEnvironmentArgSpec} 1303 | % \begin{syntax} 1304 | % \cs{ShowDocumentCommandArgSpec} \meta{function} 1305 | % \cs{ShowDocumentEnvironmentArgSpec} \meta{environment} 1306 | % \end{syntax} 1307 | \begin{syntax} 1308 | \cs{ShowDocumentCommandArgSpec} \meta{函数function} 1309 | \cs{ShowDocumentEnvironmentArgSpec} \meta{环境environment} 1310 | \end{syntax} 1311 | % These functions show the current argument specification for the 1312 | % requested \meta{function} or \meta{environment} at the terminal. If 1313 | % the \meta{function} or \meta{environment} has no known argument 1314 | % specification then an error is issued. 1315 | 这两个函数会在终端显示 \meta{function} 或 \meta{environment} 的当前选项规范。 1316 | 如果 \meta{function} 或 \meta{environment} 有未知选项规范则会报错。 1317 | % \end{function} 1318 | % 1319 | \end{function} 1320 | 1321 | % \section{Load-time options} 1322 | % 1323 | \section{载入时选项} 1324 | 1325 | % \DescribeOption{log-declarations} 1326 | \DescribeOption{log-declarations} 1327 | % The package recognises the load-time option \texttt{log-declarations}, 1328 | % which is a key--value option taking the value \texttt{true} and 1329 | % \texttt{false}. By default, the option is set to \texttt{true}, meaning 1330 | % that each command or environment declared is logged. By loading 1331 | % \pkg{xparse} using 1332 | % \begin{verbatim} 1333 | % \usepackage[log-declarations=false]{xparse} 1334 | % \end{verbatim} 1335 | % this may be suppressed and no information messages are produced. 1336 | % 1337 | 本宏包载入时可以带一个键值型选项 \texttt{log-declarations}，取值为 \texttt{true} 或 \texttt{false}。 1338 | 默认情况下是 \texttt{true}，即声明的每一个命令或环境都会在日志中记录。 1339 | 如果使用 1340 | \begin{verbatim} 1341 | \usepackage[log-declarations=false]{xparse} 1342 | \end{verbatim} 1343 | 导入宏包，那么不会生成相关信息。 1344 | 1345 | % \section{Backwards Compatibility} 1346 | % \label{sec:backwards} 1347 | % 1348 | \section{向后兼容性} 1349 | \label{sec:backwards} 1350 | 1351 | % One role of \pkg{xparse} is to describe existing \LaTeX{} interfaces, 1352 | % including some that are rather unusual in \LaTeX{} (as opposed to 1353 | % formats such as plain \TeX{}) such as delimited arguments. As such, 1354 | % the package defines some argument specifiers that should largely be 1355 | % avoided nowadays as using them in packages leads to inconsistent user 1356 | % interfaces. The simplest syntax is often best, with argument 1357 | % specifications such as |mmmm| or |ommmm|, namely an optional argument 1358 | % followed by some standard mandatory ones. The optional argument can 1359 | % be made to support key--value syntax using tools from \pkg{l3keys}. 1360 | % 1361 | \pkg{xparse} 的作用之一便是描述已经有的 \LaTeX{} 接口， 1362 | 包括定界选项等其中相当不常用的一些情况（与 plain\TeX{} 格式相反）。 1363 | 正因为如此，本宏包定义了一些目前来说应当尽可能避免使用的选项规范， 1364 | 因为在宏包中使用会导致不相容的用户接口。 1365 | 1366 | % The argument types that are not recommended any longer are: 1367 | 不再推荐使用的选项类型是： 1368 | % \begin{itemize}[font=\ttfamily] 1369 | \begin{itemize}[font=\ttfamily] 1370 | % \item[l] A mandatory argument which reads everything up to the first 1371 | % begin-group token: in standard \LaTeX{} this is a left brace. 1372 | \item[l] （left）该必选项会依次读取，直到第一个组开始记号： 1373 | 在标准 \LaTeX{} 中是左大括号。 1374 | % \item[u] Reads a mandatory argument \enquote{until} \meta{tokens} are encountered, 1375 | % where the desired \meta{tokens} are given as an argument to the 1376 | % specifier: \texttt{u}\marg{tokens}. 1377 | \item[u] （until）读取必选项，“直到”遇到记号 \meta{tokens}。 1378 | 其中，要求的 \meta{tokens} 会传递给指示符，即 \texttt{u}\marg{tokens}。 1379 | % \item[g] An optional argument given inside a pair of \TeX{} group 1380 | % tokens (in standard \LaTeX{}, |{| \ldots |}|), which returns 1381 | % |-NoValue-| if not present. 1382 | \item[g] （group）可选项，其内容位于 \TeX{} 组记号对内部 1383 | （在标准 \LaTeX{} 中为 |{| \ldots{} |}|），未给出时返回 |-NoValue-|。 1384 | % \item[G] As for \texttt{g} but returns \meta{default} if no value 1385 | % is given: \texttt{G}\marg{default}. 1386 | \item[G] （Group）与 \texttt{g} 类似，但是当未给出时返回指定的默认值 \meta{default}， 1387 | 即：\texttt{G}\marg{default}。 1388 | % \end{itemize} 1389 | \end{itemize} 1390 | 1391 | \end{document} 1392 | -------------------------------------------------------------------------------- /expl3-doc-cn/expl3-cn.tex: -------------------------------------------------------------------------------- 1 | \documentclass[full]{l3doc} 2 | %latex3/l3kernel/expl3.dtx 3 | \usepackage[UTF8, punct = kaiming, heading, fontset=fandol]{ctex} 4 | \usepackage{graphicx} 5 | \usepackage{hyperref} 6 | 7 | \providecommand\acro[1]{\textsc{\MakeLowercase{#1}}} 8 | \newenvironment{arg-description}{% 9 | \begin{itemize}\def\makelabel##1{\hss\llap{\bfseries##1}}}{\end{itemize}} 10 | 11 | % \title{^^A 12 | % The \textsf{expl3} package and \LaTeX3 programming^^A 13 | % } 14 | % 15 | % \author{^^A 16 | % The \LaTeX3 Project\thanks 17 | % {^^A 18 | % E-mail: 19 | % \href{mailto:latex-team@latex-project.org} 20 | % {latex-team@latex-project.org}^^A 21 | % }^^A 22 | % } 23 | % 24 | % \date{Released 2019-01-01} 25 | 26 | \begin{document} 27 | 28 | \title{\textsf{expl3} 宏包与 \LaTeX3 编程\footnotemark} 29 | \author{\LaTeX3 项目组} 30 | \date{2019-01-01} 31 | 32 | \maketitle 33 | 34 | \makeatletter 35 | \def\@thefnmark{*} 36 | \@footnotetext{ 37 | 这份文档是英文文档 \href{http://mirrors.ctan.org/macros/latex/contrib/l3kernel/expl3.pdf}{expl3.pdf} 的中文翻译。 38 | 该手册简要介绍了 \LaTeX3 语法，是学习 \LaTeX3 语法以及更多进阶材料的必读文档。 39 | 40 | 翻译过程中需要说明以下几点 41 | \begin{description} 42 | \item[convention] 这里指 \LaTeX3 提出的一整套新的代码格式（新语言），应当使用这种代码风格进行开发。翻译为“约定”。 43 | \item[interface] 一般情况下翻译为“接口”。 44 | \item[primitive] (e)\TeX{} 以及各引擎提供的基本命令（控制序列），翻译为“原始命令”。 45 | \item[token] 这是 \TeX{} 中的一个基本概念，然而确实很难找到一个确切的中文词汇与之对应。 46 | 这里遵从zoho在 \href{https://github.com/CTeX-org/tex-impatient-cn/}{\emph{\TeX{} for the Impatient}} 47 | 等著作中的处理方式翻译为“记号”。 48 | 进而“token list”翻译为“记号序列”。 49 | \item[register] 翻译为“寄存器”。 50 | \item[quark] \LaTeX3 中的新概念，暂时按照物理学中的称呼翻译为“夸克”。 51 | \end{description} 52 | 53 | 本文档的地址为：\url{https://github.com/WenboSheng/LaTeX3-doc-cn/expl3-doc-cn} 54 | 55 | 本文档可在 \LaTeX\ 项目公共协议（LPPL, \LaTeX\ Project Public License）下复制和分发。 56 | LPPL 协议的内容见 \url{http://www.latex-project.org/lppl/}。 57 | \begin{flushright} 58 | 盛文博\\ 59 | \href{mailto:wbsheng88@foxmail.com}{}\\ 60 | \today 61 | \end{flushright} 62 | }% 63 | \makeatother 64 | 65 | % \begin{abstract} 66 | \begin{abstract} 67 | 68 | % This document gives an introduction to a new set of programming 69 | % conventions that have been designed to meet the requirements of 70 | % implementing large scale \TeX{} macro programming projects such as 71 | % \LaTeX{}. These programming conventions are the base layer of \LaTeX3. 72 | 针对 \LaTeX{} 等大型 \TeX{} 宏编程项目对编程风格设计的需求， 73 | 本文介绍一套属于 \LaTeX3 的基础层面的全新程序设计约定。 74 | 75 | % The main features of the system described are: 76 | % \begin{itemize} 77 | % \item classification of the macros (or, in \LaTeX{} terminology, 78 | % commands) into \LaTeX{} functions and \LaTeX{} parameters, and also 79 | % into modules containing related commands; 80 | % \item a systematic naming scheme based on these classifications; 81 | % \item a simple mechanism for controlling the expansion of a function's 82 | % arguments. 83 | % \end{itemize} 84 | % This system is being used as the basis for \TeX{} programming within 85 | % the \LaTeX3 project. Note that the language is not intended for either 86 | % document mark-up or style specification. Instead, it is intended that 87 | % such features will be built on top of the conventions described here. 88 | 该系统主要特性有： 89 | \begin{itemize} 90 | \item 将宏（在 \LaTeX{} 术语中也称之为命令）分为 \LaTeX{} 函数和 \LaTeX{} 参数， 91 | 并依照功能分为若干组模块； 92 | \item 基于这些分类提出了系统性的命名规则； 93 | \item 对于函数选项展开提出了简洁的控制机制。 94 | \end{itemize} 95 | 该系统已经用于 \LaTeX3 项目中的 \TeX{} 程序设计基础。 96 | 请注意，该语言不是为了用在文档标记或者样式规范中， 97 | 而是为了构建其基础。 98 | 99 | % This document is an introduction to the ideas behind the \pkg{expl3} 100 | % programming interface. For the complete documentation of the programming 101 | % layer provided by the \LaTeX3 Project, see the accompanying 102 | % \texttt{interface3} document. 103 | 本文档简要介绍了 \pkg{expl3} 程序接口的主要思路。 104 | 关于\LaTeX3 编程层面的完整叙述，请参考配套的 \texttt{interface3} 文档。 105 | 106 | % 107 | % \end{abstract} 108 | \end{abstract} 109 | 110 | % \section{Introduction} 111 | \section{简介} 112 | 113 | % The first step to develop a \LaTeX{} kernel beyond \LaTeXe{} is to 114 | % address how the underlying system is programmed. Rather than the 115 | % current mix of \LaTeX{} and \TeX{} macros, the \LaTeX3 system provides 116 | % its own consistent interface to all of the functions needed to 117 | % control \TeX{}. A key part of this work is to ensure that everything 118 | % is documented, so that \LaTeX{} programmers and users can work 119 | % efficiently without needing to be familiar with the internal nature 120 | % of the kernel or with plain \TeX{}. 121 | % 122 | 在 \LaTeXe{} 之后，开发 \LaTeX{} 内核的第一步就是如何设计底层系统编程。 123 | 当前的情况是混合使用 \LaTeX{} 和 \TeX{} 宏。 124 | 与此不同的是，\LaTeX3 系统为所有需要控制 \TeX{} 的函数提供了一套完整的接口。 125 | 这项工作中关键的一部分就是确保所有的一切都是文档化的， 126 | 这样即便 \LaTeX{} 程序员和用户不熟悉内核机制或者 plain\TeX{}，也可以进行高效开发。 127 | 128 | % The \pkg{expl3} bundle provides this new programming interface for 129 | % \LaTeX{}. To make programming systematic, \LaTeX3 uses some very 130 | % different conventions to \LaTeXe{} or plain \TeX{}. As a result, 131 | % programmers starting with \LaTeX3 need to become familiar with 132 | % the syntax of the new language. 133 | % 134 | \pkg{expl3} 宏集提供了新的 \LaTeX{} 程序设计接口。 135 | 为了使编程系统化，\LaTeX3 使用了与 \LaTeXe{} 或 plain \TeX{} 截然不同的程序风格约定。 136 | 因此，进行 \LaTeX3 开发需要熟悉这种全新的语法规则。 137 | 138 | % The next section shows where this language fits into a complete 139 | % \TeX{}-based document processing system. We then describe the major 140 | % features of the syntactic structure of command names, including the 141 | % argument specification syntax used in function names. 142 | % 143 | 下一节将展示，在一个完整的 \TeX{} 文档处理系统中，这项语言适用于哪些地方。 144 | 之后将描述命令名称的语法结构的主要特性，比如函数选项的语法规范。 145 | % The practical ideas behind this argument syntax will be explained, 146 | % together with the expansion control mechanism and the interface 147 | % used to define variant forms of functions. 148 | % 149 | 然后将解释这种选项语法背后的实用思想， 150 | 同时也包括展开控制机制和定义不同形式函数的接口。 151 | 152 | % As we shall demonstrate, the use of a structured naming scheme and of 153 | % variant forms for functions greatly improves the readability of the 154 | % code and hence also its reliability. Moreover, experience has shown 155 | % that the longer command names which result from the new syntax do not 156 | % make the process of \emph{writing} code significantly harder. 157 | 我们将说明， 158 | 使用结构化的命名规则和多样化的函数形式能够极大提高代码的可读性以及可靠性。 159 | 此外，实践表明，新语法导致的长命令名不会明显加剧写代码开发的困难程度。 160 | 161 | % \section{Languages and interfaces} 162 | \section{语言和接口} 163 | % 164 | % It is possible to identify several distinct languages related to the 165 | % various interfaces that are needed in a \TeX{}-based document processing 166 | % system. This section looks at those we consider most important for 167 | % the \LaTeX3 system. 168 | % 169 | 170 | 在基于 \TeX{} 的文档处理系统中， 171 | 我们可以罗列出涉及到不同层面接口的各种语言。 172 | 本节将介绍在 \LaTeX3 中最重要的一些部分。 173 | 174 | % \begin{description} 175 | \begin{description} 176 | % \item[Document mark-up] This comprises those commands (often called 177 | % tags) that are to embedded in the document (the |.tex| file). 178 | % 179 | \item[文档标记] 包括文档（|.tex| 文件）中的一些命令，通常称为标签（tag）。 180 | 181 | % It is generally accepted that such mark-up should be essentially 182 | % \emph{declarative}. It may be traditional \TeX{}-based mark-up such 183 | % as \LaTeXe{}, as described in~\cite{A-W:LLa94} and~\cite{A-W:GMS94}, 184 | % or a mark-up language defined via \acro{HTML} or \acro{XML}. 185 | % 186 | 一种广泛接受的观点是，这样的标记本质上应当是\emph{声明式的（declarative）}。 187 | 它可以是传统的 \TeX{} 标记，比如~\cite{A-W:LLa94} 和~\cite{A-W:GMS94} 中描述的 \LaTeXe{}； 188 | 或者是通过 \acro{HTML} 或 \acro{XML} 定义的标记语言。 189 | 190 | % One problem with more traditional \TeX{} coding conventions (as 191 | % described in~\cite{A-W:K-TB}) is that the names and syntax of \TeX{}'s 192 | % primitive formatting commands are ingeniously designed to be 193 | % \enquote{natural} when used directly by the author as document mark-up 194 | % or in macros. Ironically, the ubiquity (and widely recognised 195 | % superiority) of logical mark-up has meant that such explicit 196 | % formatting commands are almost never needed in documents or in 197 | % author-defined macros. Thus they are used almost exclusively by 198 | % \TeX{} programmers to define higher-level commands, and their 199 | % idiosyncratic syntax is not at all popular with this community. 200 | % Moreover, many of them have names that could be very useful as 201 | % document mark-up tags were they not pre-empted as primitives 202 | % (\emph{e.g.}~\tn{box} or \tn{special}). 203 | 传统 \TeX{} 代码约定（如同~\cite{A-W:K-TB} 所描述的）的一大问题就是， 204 | \TeX{} 确实精心而巧妙地设计了原始格式命令的名称和语法， 205 | 这样文档作者就可以在标记或宏中很“自然”地直接使用这些原始命令。 206 | 然而具有讽刺意味的是，无处不在的逻辑标记（这广泛认为是一大优势） 207 | 反而导致几乎没有必要在文档或自定义宏中直接使用这些原始格式命令。 208 | 几乎只有 \TeX{} 开发人员定义高层次命令时才使用原始命令， 209 | 而在社区中这种特殊的语法几乎是不流行的。 210 | 另外，原始命令占用了很多方便的名称（例如~\tn{box} 或 \tn{special}）， 211 | 否则本可以像文档标记一样广泛使用的。 212 | 213 | % 214 | % \item[Designer interface] This relates a (human) typographic 215 | % designer's specification for a document to a program that 216 | % \enquote{formats 217 | % the document}. It should ideally use a declarative language that 218 | % facilitates expression of the relationship and spacing rules 219 | % specified for the layout of the various document elements. 220 | % 221 | 222 | \item[设计者接口] 该接口将文档的排版设计规范与“格式化文档”的程序联系起来。 223 | 理想状况下应当使用声明式的语言，这样可以更好地表达不同文档元素之间的布局关系和间距规则。 224 | 225 | % This language is not embedded in document text and it will be very 226 | % different in form to the document mark-up language. For \LaTeX{}, 227 | % this level was almost completely missing from \LaTeX{}2.09; \LaTeXe{} 228 | % made some improvements in this area but it is still the case that 229 | % implementing a design specification in \LaTeX{} requires far more 230 | % \enquote{low-level} coding than is acceptable. 231 | % 232 | 这种语言没有嵌入到文档文本中，所以其形式与文档标记语言有很大不同。 233 | 对于 \LaTeX{}，在 \LaTeX{}2.09 中这一层次几乎完全是缺失的； 234 | \LaTeXe{} 在这一领域做了一些改进， 235 | 然而在 \LaTeX{} 中实现一套设计规范仍然需要很多“低层次”编程，而这是不可接受的。 236 | 237 | % \item[Programmer interface] 238 | % This language is the implementation language within which the 239 | % basic typesetting functionality is implemented, building upon the 240 | % primitives of \TeX{} (or a successor program). It may also be used 241 | % to implement the previous two languages \enquote{within} \TeX{}, as in 242 | % the 243 | % current \LaTeX{} system. 244 | \item[开发者接口] 245 | 这一语言构建在 \TeX{} 原始命令（或者后继程序）之上，并实现了基本排版功能。 246 | 它也用于“在\TeX{} 内”实现前两种语言，比如当前的 \LaTeX{} 系统就是这样。 247 | % 248 | % \end{description} 249 | \end{description} 250 | 251 | % 252 | % The last layer is covered by the conventions described in this 253 | % document, which describes a system aimed at providing a suitable 254 | % basis for coding \LaTeX3. Its main distinguishing features are 255 | % summarised here: 256 | % \begin{itemize} 257 | % \item A consistent naming scheme for all commands, including \TeX{} 258 | % primitives. 259 | % \item The classification of commands as \LaTeX{} functions or \LaTeX{} 260 | % parameters, and also their division into modules according to their 261 | % functionality. 262 | % \item A simple mechanism for controlling argument expansion. 263 | % \item Provision of a set of core \LaTeX{} functions that is sufficient 264 | % for handling programming constructs such as queues, sets, stacks, 265 | % property lists. 266 | % \item A \TeX{} programming environment in which, for example, all 267 | % white space is ignored. 268 | % \end{itemize} 269 | 270 | 本文档描述的语法约定覆盖最后一个层面， 271 | 这一系统旨在提供一个合适的 \LaTeX3 编程基础。 272 | 主要突出的特点总结如下： 273 | \begin{itemize} 274 | \item 为所有命令提供相容的命名机制，包括 \TeX{} 原始命令。 275 | \item 将命令分为 \LaTeX{} 函数或 \LaTeX{} 参数，同时也根据功能分为若干模块。 276 | \item 为选项展开提出简洁的控制机制。 277 | \item 提供一组 \LaTeX{} 核心函数，可以处理队列、集合、栈、属性列表等程序组件。 278 | \item \TeX{} 编程环境。比如在其中所有的空格都会被忽略。 279 | \end{itemize} 280 | 281 | % 282 | % \section{The naming scheme} 283 | \section{命名机制} 284 | % 285 | % \LaTeX3 does not use |@| as a \enquote{letter} for defining 286 | % internal macros. Instead, the symbols |_| and |:| 287 | % are used in internal macro names to provide structure. In 288 | % contrast to the plain \TeX{} format and the \LaTeXe{} kernel, these 289 | % extra letters are used only between parts of a macro name (no 290 | % strange vowel replacement). 291 | 292 | \LaTeX3 没有使用 |@| 作为定义内部宏的“字母”， 293 | 取而代之的是使用符号 |_| 和 |:| 来表现结构。 294 | 与 plain\TeX{} 格式和 \LaTeX{} 内核不同， 295 | 这些额外的字母只能用在宏名称的各部分之间（没有奇怪的元音替换）。 296 | 297 | % 298 | % While \TeX{} is actually a macro processor, by 299 | % convention for the \pkg{expl3} programming language we distinguish between 300 | % \emph{functions} and \emph{variables}. Functions can have arguments and they 301 | % are either expanded or executed. Variables can be assigned values and they 302 | % are used in arguments to functions; they are not used directly but are 303 | % manipulated by functions (including getting and setting functions). 304 | % Functions and variables with a related functionality (for example accessing 305 | % counters, or manipulating token lists, \emph{etc.})\ are collected together 306 | % into a 307 | % \emph{module}. 308 | % 309 | 虽然说 \TeX{} 实际上是宏处理器， 310 | 不过按照 \pkg{expl3} 程序语言的约定，我们还是区分\emph{函数}和\emph{变量}这两个概念。 311 | 函数可以带有可展开或者立即执行的选项。 312 | 变量可以被赋值，用于函数的选项； 313 | 变量不会直接使用，而是通过函数进行操作（包括获取函数和设置函数）。 314 | 具有相关功能的函数和变量（例如使用计数器、或者操作记号列表等）被归纳在一起组成一个\emph{模块}。 315 | 316 | % \subsection{Examples} 317 | \subsection{例子} 318 | % 319 | % Before giving the details of the naming scheme, here are a few typical 320 | % examples to indicate the flavour of the scheme; first some variable 321 | % names. 322 | % \begin{quote} 323 | % \cs{l_tmpa_box} is a local variable (hence the~|l_| prefix) 324 | % corresponding to a box register.\\ 325 | % \cs{g_tmpa_int} is a global variable (hence the~|g_| prefix) 326 | % corresponding to an integer register (i.e.~a \TeX{} count 327 | % register).\\ 328 | % \cs{c_empty_tl} is the constant~(|c_|) token list variable 329 | % that is always empty. 330 | % \end{quote} 331 | 在给出命名机制的细节之前，这里列出一些典型例子来说明该机制的风格； 332 | 首先是一些变量名 333 | \begin{quote} 334 | \cs{l_tmpa_box} 是对应于盒子寄存器的局部变量（这里的~|l_| 前缀代表局部）。\\ 335 | \cs{g_tmpa_int} 是对应于整型寄存器（即 \TeX{} 计数寄存器）的全局变量（这里的~|g_| 前缀代表全局）。\\ 336 | \cs{c_empty_tl} 是常值（|c_|）记号列表变量，并且总是空的。 337 | \end{quote} 338 | % 339 | % Now here is an example of a typical function name. 340 | 接下来是一个典型的函数名称例子。 341 | 342 | % 343 | % \cs{seq_push:Nn} is the function which puts the token list specified 344 | % by its second argument onto the stack specified by its first argument. 345 | % The different natures of the two arguments are indicated by the~|:Nn| 346 | % suffix. The first argument must be a single token which \enquote{names} 347 | % the stack parameter: such single-token arguments are denoted~|N|. 348 | % The second argument is a normal \TeX{} \enquote{undelimited argument}, 349 | % which 350 | % may either be a single token or a balanced, brace-delimited token 351 | % list (which we shall here call a \textit{braced token list}): the~|n| 352 | % denotes such a \enquote{normal} argument form. The name of the function 353 | % indicates it belongs to the |seq| module. 354 | % 355 | \cs{seq_push:Nn} 是一个函数，将由第二个选项确定的记号列表放入由第一个选项确定的栈中。 356 | 两个选项的不同之处由后缀~|:Nn| 指定。 357 | 第一个选项必须是一个单记号，用以命名栈参数：这样的单记号选项记为~|N|。 358 | 第二个选项是常规的 \TeX{} “未限定选项”，可以是单记号或者限定在配对大括号中的记号列表 359 | （这里我们称之为\emph{带括号的记号列表}）： 360 | 后缀~|n| 说明是“常规（normal）”的选项形式。 361 | 函数名说明它属于 |seq| 模块。 362 | 363 | % \subsection{Formal naming syntax} 364 | \subsection{正式的命名语法} 365 | % 366 | % We shall now look in more detail at the syntax of these names. A 367 | % function name in \LaTeX3 has a name consisting of three parts: 368 | % \begin{quote} 369 | % |\|\meta{module}|_|\meta{description}|:|\meta{arg-spec} 370 | % \end{quote} 371 | % while a variable has (up to) four distinct parts to its name: 372 | % \begin{quote} 373 | % |\|\meta{scope}|_|\meta{module}|_|\meta{description}|_|\meta{type} 374 | % \end{quote} 375 | 376 | 现在我们详细地看一下这些名称的语法。 377 | \LaTeX3 中的函数名包括三部分： 378 | \begin{quote} 379 | |\|\meta{模块module}|_|\meta{描述description}|:|\meta{选项规范arg-spec} 380 | \end{quote} 381 | 而变量名（至多）有四部分： 382 | \begin{quote} 383 | |\|\meta{作用域scope}|_|\meta{模块module}|_|\meta{描述description}|_|\meta{类型type} 384 | \end{quote} 385 | 386 | % 387 | % The syntax of all names contains 388 | % \begin{quote} 389 | % \meta{module} and \meta{description} 390 | % \end{quote} 391 | % these both give information about the command. 392 | 393 | 所有的名称语法都包含 394 | \begin{quote} 395 | \meta{模块module} 和 \meta{描述description} 396 | \end{quote} 397 | 这两部分给出了命令的信息。 398 | 399 | % 400 | % A \emph{module} is a collection of closely related functions and 401 | % variables. Typical module names include~|int| for integer parameters 402 | % and related functions,~|seq| for sequences and~|box| for boxes. 403 | % 404 | \emph{模块module} 是一组紧密相关的函数和变量的集合。 405 | 典型的模块名包括整型参数（以及相关函数）模块~|int|，序列~|seq| 和盒子~|box| 等等。 406 | 407 | % Packages providing new programming functionality will add new modules 408 | % as needed; the programmer can choose any unused name, consisting 409 | % of letters only, for a module. In general, the module name and module 410 | % prefix should be related: for example, the kernel module containing 411 | % \texttt{box} functions is called \texttt{l3box}. Module names and 412 | % programmers' contact details are listed in \pkg{l3prefixes.csv}. 413 | % 414 | 415 | 提供新程序功能的宏包会按需要添加新的模块； 416 | 开发者可以为模块选取任何未使用的名称，但只能包含字母。 417 | 一般而言，模块名和模块前缀应当是关联起来的： 418 | 例如，包含 \texttt{box} 函数的内核模块叫做 \texttt{l3box}。 419 | 模块名和开发者的联系信息在文件 \pkg{l3prefixes.csv} 中。 420 | 421 | % The \emph{description} gives more detailed information about the 422 | % function or parameter, and provides a unique name for it. It should 423 | % consist of letters and, possibly,~|_|~characters. In general, the 424 | % description should use |_| to divide up \enquote{words} or other easy to 425 | % follow parts of the name. For example, the \LaTeX3 kernel provides 426 | % \cs{if_cs_exist:N} which, as might be expected, tests if a command 427 | % name exists. 428 | % 429 | 430 | \emph{描述description} 给出函数或参数的更多详细信息，并确定了唯一的名称。 431 | 它应当包含字母和可能的~|_|~字符。 432 | 一般而言，描述部分应当使用 |_| 来划分“单词”或者其它部分。 433 | 例如，\LaTeX3 内核提供了 \cs{if_cs_exist:N}， 434 | 并且正如所预料的那样用于检测一个命令是否存在。 435 | 436 | % Where functions for variable manipulation can perform assignments 437 | % either locally or globally, the latter case is indicated by the inclusion of 438 | % a |g| in the second part of the function name. Thus \cs{tl_set:Nn} is a local 439 | % function but \cs{tl_gset:Nn} acts globally. Functions of this type are 440 | % always documented together, and the scope of action may therefore be 441 | % inferred from the presence or absence of a |g|. See the next subsection for 442 | % more detail on variable scope. 443 | % 444 | 445 | 进行变量操作的函数可以局部或者全局地执行。 446 | 后者需要在函数名的第二部分中包含 |g| 标记。 447 | 比如 \cs{tl_set:Nn} 是局部函数，而 \cs{tl_gset:Nn} 则是全局的。 448 | 这两种类型的函数总是一起文档化，而作用域可以从函数名是否存在 |g| 来推断。 449 | 关于变量作用域的信息详见下一小节。 450 | 451 | % \subsubsection{Separating private and public material} 452 | \subsubsection{区分私有和公共材料} 453 | 454 | % 455 | % One of the issues with the \TeX{} language is that it doesn't support 456 | % name spaces and encapsulation other than by convention. As a result 457 | % nearly every internal command in the \LaTeXe{} kernel has eventually 458 | % be used by extension packages as an entry point for modifications or 459 | % extensions. The consequences of this is that nowadays it is next to 460 | % impossible to change anything in the \LaTeXe{} kernel (even if it is 461 | % clearly just an internal command) without breaking something. 462 | % 463 | 464 | \TeX{} 语言的问题之一就是除了通过约定之外不支持名空间（name space）和封装。 465 | 结果便是 \LaTeXe{} 内核中的几乎所有内部命令最后都会被外部宏包使用并进行修改或扩展。 466 | 造成的后果是现在几乎不可能改动 \LaTeXe{} 内核中的任何东西而不造成破坏 467 | （即便很明显仅仅是个内部命令）。 468 | 469 | % In \pkg{expl3} we hope to improve this situation drastically by 470 | % clearly separating public interfaces (that extension packages can use 471 | % and rely on) and private functions and variables (that should not 472 | % appear outside of their module). There is (nearly) no way to enforce 473 | % this without severe computing overhead, so we implement it only 474 | % through a naming convention, and some support mechanisms. However, we 475 | % think that this naming convention is easy to understand and to follow, 476 | % so that we are confident that this will adopted and provides the 477 | % desired results. 478 | 479 | 在 \pkg{expl3} 中我们希望明确地区分公共接口（外部宏包可以使用或依赖）和私有函数/变量（不应当出现在模块之外）， 480 | 进而可以明显地改善目前这一状况。 481 | 而这在没有严重的计算开销条件下几乎不可能实施， 482 | 因此我们只是通过命名约定和一些支持机制来实现。 483 | 不过，我们认为这种命名约定很容易理解和遵守， 484 | 所以有信心认为该约定会被采用并提供想要的结果。 485 | 486 | % 487 | % Functions created by a module may either be \enquote{public} (documented 488 | % with a defined interface) or \enquote{private} (to be used only within 489 | % that module, and thus not formally documented). It is important that 490 | % only documented interfaces are used; at the same time, it is necessary to 491 | % show within the name of a function or variable whether it is public 492 | % or private. 493 | % 494 | 495 | 由模块创建的函数既可以是“公共”的（使用给定接口进行文档说明）， 496 | 也可以是“私有”的（只在该模块内部使用，因此没有正式文档）。 497 | 很重要的一点是，只能使用带有文档的接口； 498 | 同时有必要在函数名或变量名中表明是公共的还是私有的。 499 | 500 | % To allow clear separation of these two cases, the following convention 501 | % is used. Private functions should be defined with |__| added to the beginning 502 | % of the module name. Thus 503 | % \begin{verbatim} 504 | % \module_foo:nnn 505 | % \end{verbatim} 506 | % is a public function which should be documented while 507 | % \begin{verbatim} 508 | % \__module_foo:nnn 509 | % \end{verbatim} 510 | % is private to the module, and should \emph{not} be used outside of that 511 | % module. 512 | 513 | 使用以下约定来明确地区分这两种情况。 514 | 私有函数应当在模块名的开始加上 |__|。因此 515 | \begin{verbatim} 516 | \module_foo:nnn 517 | \end{verbatim} 518 | 是应当进行文档说明的公共函数，而 519 | \begin{verbatim} 520 | \__module_foo_nnn 521 | \end{verbatim} 522 | 是该模块私有的，在该模块外部\emph{不}应当使用。 523 | 524 | % 525 | % In the same way, private variables should use two "__" at the start of the 526 | % module name, such that 527 | % \begin{verbatim} 528 | % \l_module_foo_tl 529 | % \end{verbatim} 530 | % is a public variable and 531 | % \begin{verbatim} 532 | % \l__module_foo_tl 533 | % \end{verbatim} 534 | % is private. 535 | % 536 | 537 | 类似地，私有变量应当在模块名开始使用两个 "_"。因此 538 | \begin{verbatim} 539 | \l_module_foo_tl 540 | \end{verbatim} 541 | 是公共变量，而 542 | \begin{verbatim} 543 | \l__module_foo_tl 544 | \end{verbatim} 545 | 是私有的。 546 | 547 | % \subsubsection{Using \texttt{@@} and \pkg{l3docstrip} to mark private code} 548 | \subsubsection{使用 \texttt{@@} 和 \pkg{l3docstrip} 来标记私有代码} 549 | 550 | % 551 | % The formal syntax for internal functions allows clear separation of public 552 | % and private code, but includes redundant information (every internal function 553 | % or variable includes \texttt{__\meta{module}}). To aid programmers, the 554 | % \pkg{l3docstrip} program introduces the syntax 555 | % \begin{quote} 556 | % \ttfamily 557 | % |%<@@=|\meta{module}|>| 558 | % \end{quote} 559 | 内部函数的正式语法可以清晰地区分公共和私有代码， 560 | 但是同时也会包含冗余信息（每一内部函数或变量都包含 \texttt{__\meta{module}}）。 561 | 为了帮助开发者，\pkg{l3docstrip} 项目引入语法 562 | \begin{quote} 563 | \ttfamily 564 | |%<@@=|\meta{module}|>| 565 | \end{quote} 566 | % which then allows |@@| (and |_@@| in case of variables) to be used as 567 | % a place holder for \texttt{__\meta{module}} in code. Thus for example 568 | % \begin{verbatim} 569 | % %<@@=foo> 570 | % % \begin{macrocode} 571 | % \cs_new:Npn \@@_function:n #1 572 | % ... 573 | % \tl_new:N \l_@@_my_tl 574 | % % \end{macrocode} 575 | % \end{verbatim} 576 | % is converted by \pkg{l3docstrip} to 577 | % \begin{verbatim} 578 | % \cs_new:Npn \__foo_function:n #1 579 | % ... 580 | % \tl_new:N \l__foo_my_tl 581 | % \end{verbatim} 582 | % on extraction. As you can see both |_@@| and |@@| are mapped to 583 | % \texttt{__\meta{module}}, because we think that this helps to 584 | % distinguish variables from functions in the source when the |@@| 585 | % convention is used. 586 | 这样允许在代码中使用 |@@|（对于变量的情况是 |_@@|）作为 \texttt{__\meta{module}} 的占位符。 587 | 例如，\pkg{l3docstrip} 可以将如下代码 588 | \begin{verbatim} 589 | %<@@=foo> 590 | % \begin{macrocode} 591 | \cs_new:Npn \@@_function:n #1 592 | ... 593 | \tl_new:N \l_@@_my_tl 594 | % \end{macrocode} 595 | \end{verbatim} 596 | 转化并提取为 597 | \begin{verbatim} 598 | \cs_new:Npn \__foo_function:n #1 599 | ... 600 | \tl_new:N \l__foo_function_my_tl 601 | \end{verbatim} 602 | 可以看出，|_@@| 和 |@@| 被映射到 \texttt{__\meta{module}}。 603 | 我们认为，在源文件中使用 |@@| 约定有助于区分函数和变量。 604 | 605 | % 606 | % \subsubsection{Variables: scope and type} 607 | \subsubsection{变量：作用域和类型} 608 | 609 | % 610 | % The \meta{scope} part of the name describes how the variable can be 611 | % accessed. Variables are classified as local, global or constant. 612 | % This \emph{scope} type appears as a code at the beginning of the name; 613 | % the codes used are: 614 | % \begin{arg-description} 615 | % \item[c] constants (global variables whose value should not be 616 | % changed); 617 | % \item[g] variables whose value should only be set globally; 618 | % \item[l] variables whose value should only be set locally. 619 | % \end{arg-description} 620 | % 621 | 622 | 名称中的 \meta{作用域scope} 部分描述了变量是如何获取的。 623 | 变量分为局部、全局和常值等类型。 624 | \emph{作用域}类型出现在名称的开始处。 625 | 使用的代码为： 626 | \begin{arg-description} 627 | \item[c] 常值（值不会变化的全局变量）； 628 | \item[g] 变量的值只应当全局设置； 629 | \item[l] 变量的值只应当局部设置。 630 | \end{arg-description} 631 | 632 | % Separate functions are provided to assign data to local and global 633 | % variables; for example, \cs{tl_set:Nn} and \cs{tl_gset:Nn} respectively 634 | % set the value of a local or global \enquote{token list} variable. 635 | % Note that it is a poor \TeX{} practice to intermix local and global 636 | % assignments to a variable; otherwise you risk exhausting the save 637 | % stack.\footnote{See \emph{The \TeX{}book}, p.\,301, for further 638 | % information.} 639 | 640 | 使用不同的函数来为局部和全局变量赋值； 641 | 例如，\cs{tl_set:Nn} 和 \cs{tl_gset:Nn} 分别设置了局部和全局“记号列表”变量的值。 642 | 请注意，给一个变量进行混合的局部和全局赋值是一种很不好的 \TeX{} 做法； 643 | 这可能会有耗尽保存的栈容量的风险。\footnote{ 644 | 更多信息请参考 \emph{The \TeX{}book}，301页。} 645 | 646 | % 647 | % The \meta{type} is in the list of available 648 | % \emph{data-types};\footnote{Of course, if a totally new data type is 649 | % needed then this will not be the case. However, it is hoped that only 650 | % the kernel team will need to create new data types.} these include the 651 | % primitive \TeX{} data-types, such as the various registers, but to 652 | % these are added data-types built within the \LaTeX{} programming 653 | % system. 654 | % 655 | \meta{类型type} 的内容位于可用的\emph{数据类型}列表中；\footnote{ 656 | 当然，例外是需要一个全新的数据类型。 657 | 不过我们希望只有内核团队才需要创建新的数据类型。} 658 | 这包括 \TeX{} 原始命令中的数据类型，比如各种寄存器。 659 | 不过这些已经整合到由 \LaTeX{} 程序系统内部构建的数据类型中。 660 | 661 | % The data types in \LaTeX3 are: 662 | % \begin{description} 663 | % \item[bool] either true or false (the \LaTeX3 implementation does 664 | % not use \tn{iftrue} or \tn{iffalse}); 665 | % \item[box] box register; 666 | % \item[clist] comma separated list; 667 | % \item[coffin] a \enquote{box with handles} --- a higher-level data 668 | % type for carrying out |box| alignment operations; 669 | % \item[dim] \enquote{rigid} lengths; 670 | % \item[fp] floating-point values; 671 | % \item[ior] an input stream (for reading from a file); 672 | % \item[iow] an output stream (for writing to a file); 673 | % \item[int] integer-valued count register; 674 | % \item[muskip] math mode \enquote{rubber} lengths; 675 | % \item[prop] property list; 676 | % \item[seq] sequence: a data-type used to implement lists (with 677 | % access at both ends) and stacks; 678 | % \item[skip] \enquote{rubber} lengths; 679 | % \item[str] \TeX{} strings: a special case of |tl| in which all 680 | % characters have category \enquote{other} (catcode~$12$), 681 | % other than spaces which are category \enquote{space} 682 | % (catcode~$10$); 683 | % \item[tl] \enquote{token list variables}: placeholders for token lists. 684 | % \end{description} 685 | % When the \meta{type} and \meta{module} are identical (as often happens in 686 | % the more basic modules) the \meta{module} part is often omitted for 687 | % aesthetic reasons. 688 | 689 | \LaTeX3 中的数据类型包括： 690 | \begin{description} 691 | \item[bool] true 或者 false（\LaTeX3 不使用 \tn{iftrue} 或 \tn{iffalse}）； 692 | \item[box] 盒子寄存器； 693 | \item[clist] 逗号分隔列表； 694 | \item[coffin] “带有句柄的盒子”——一种高层次的数据类型，可以执行 |box| 对齐操作； 695 | \item[dim] “严格的”长度； 696 | \item[fp] 浮点数值； 697 | \item[ior] 输入流（用于文件读取）； 698 | \item[iow] 输出流（用于文件写入）； 699 | \item[int] 整型计数寄存器； 700 | \item[muskip] 数学模式的“弹性”长度； 701 | \item[prop] 属性列表； 702 | \item[seq] 序列：用于实现列表（可以获取两端的值）和栈的数据类型； 703 | \item[skip] “弹性”长度； 704 | \item[str] \TeX{} 字符串：一种特殊的 |tl|，其中所有的字符类型都是“其它”（类别码为~$12$）， 705 | 除了空格的类型是“空格”（类别码为~$10$）； 706 | \item[tl] “记号列表变量”：用于放置记号列表。 707 | \end{description} 708 | 当 \meta{类型type} 和 \meta{模块module} 相同时（通常出现在基本模块中）， 709 | \meta{模块module} 部分出于美观原因通常会省略。 710 | 711 | % 712 | % The name \enquote{token list} may cause confusion, and so some 713 | % background is useful. \TeX{} works with tokens and lists of tokens, 714 | % rather than characters. It provides two ways to store these token 715 | % lists: within macros and as token registers (|toks|). The 716 | % implementation in \LaTeX3 means that |toks| are not required, and that 717 | % all operations for storing tokens can use the |tl| variable type. 718 | 719 | 名称“记号列表”可能会引起困扰，因此介绍一些背景是有必要的。 720 | \TeX{} 处理的是记号和记号列表，而不是字符， 721 | 并且提供了两种方式来存储这些记号列表：在宏内部以及记号寄存器（|toks|）。 722 | 在 \LaTeX3 中的实现意味着 |toks| 是不需要了， 723 | 并且所有存储记号的操作都可以使用 |tl| 变量类型。 724 | 725 | % 726 | % Experienced \TeX{} programmers will notice that some of the variable 727 | % types listed are native \TeX{} registers whilst others are not. In 728 | % general, the underlying \TeX{} implementation for a data structure may 729 | % vary but the \emph{documented interface} will be stable. For example, 730 | % the |prop| data type was originally implemented as a |toks|, but 731 | % is currently built on top of the |tl| data structure. 732 | 高级 \TeX{} 开发者会注意到，一些变量类型是原生的 \TeX{} 寄存器，而另一些则不是。 733 | 一般来说，数据结构的底层实现会变动，而\emph{有文档说明的接口}则是稳定的。 734 | 例如，|prop| 数据类型一开始的实现是 |toks|，现在则构建在 |tl| 数据结构之上。 735 | 736 | % 737 | % \subsubsection{Variables: guidance} 738 | \subsubsection{变量：说明指导} 739 | 740 | % 741 | % Both comma lists and sequences have similar characteristics. 742 | % They both use special delimiters to mark out one entry from the 743 | % next, and are both accessible at both ends. In general, it is 744 | % easier to create comma lists `by hand' as they can be typed 745 | % in directly. User input often takes the form of a comma separated 746 | % list and so there are many cases where this is the obvious 747 | % data type to use. On the other hand, sequences use special internal 748 | % tokens to separate entries. This means that they can be used to 749 | % contain material that comma lists cannot (such as items that may 750 | % themselves contain commas!). In general, comma lists should be 751 | % preferred for creating fixed lists inside programs and for 752 | % handling user input where commas will not occur. On the other 753 | % hand, sequences should be used to store arbitrary lists of 754 | % data. 755 | 逗号列表和序列二者具有类似的特征。 756 | 它们都使用特殊的定界符来标识各条目，并且都可以从两端读取。 757 | 一般来说，“手动”创建逗号列表更容易一些，因为可以直接输入。 758 | 用户输入通常采用逗号分隔列表的形式，因此许多情况中这是一种显然可用的数据类型。 759 | 另一方面，序列会使用特殊的内部记号来分隔条目。 760 | 这意味着它们可以用于逗号列表不能应用的场合（例如每一条目本身可能包含逗号）。 761 | 一般而言，逗号列表主要用于创建项目中的固定列表以及处理逗号本身不会出现的用户输入。 762 | 同时，序列应当用于存储任意数据列表。 763 | 764 | % 765 | % \pkg{expl3} implements stacks using the sequence data structure. 766 | % Thus creating stacks involves first creating a sequence, and 767 | % then using the sequence functions which work in a stack manner 768 | % (\cs{seq_push:Nn}, \emph{etc}.). 769 | 770 | \pkg{expl3} 使用序列数据结构实现栈。 771 | 因此创建栈会首先创建一个序列，然后使用一些可以满足栈需求的序列函数（例如 \cs{seq_push:Nn} 等）。 772 | 773 | % 774 | % Due to the nature of the underlying \TeX{} implementation, it is 775 | % possible to assign values to token list variables and comma lists 776 | % without first declaring them. However, this is \emph{not supported 777 | % behavior}. The \LaTeX3 coding convention is that all variables must 778 | % be declared before use. 779 | 由于底层 \TeX{} 实现的固有性质，可以不首先声明就直接赋值给记号列表变量和逗号列表。 780 | 然而，我们\emph{不支持}这种行为。 781 | \LaTeX3 代码约定中，所有变量在使用之前都必须先声明。 782 | 783 | % 784 | % The \pkg{expl3} package can be loaded with the \texttt{check-declarations} 785 | % option to verify that all variables are declared before use. This has 786 | % a performance implication and is therefore intended for testing during 787 | % development and not for use in production documents. 788 | \pkg{expl3} 宏包可以在导入时加载选项 \texttt{check-declarations}， 789 | 用于确认所有的变量在使用前都已声明。 790 | 不过这会带来性能的影响，因此主要用于开发中的测试而不是文档生产。 791 | 792 | % 793 | % \subsubsection{Functions: argument specifications} 794 | \subsubsection{函数：选项规范} 795 | 796 | % 797 | % Function names end with an \meta{arg-spec} after a colon. This 798 | % gives an indication of the types of argument that a function takes, 799 | % and provides a convenient method of naming similar functions that 800 | % differ only in their argument forms (see the next section for 801 | % examples). 802 | 函数名称在冒号后以 \meta{选项规范arg-spec} 结尾。 803 | 这给出函数使用的选项类型， 804 | 并且提供了一种方便的手段用以给只有选项形式不同的类似函数命名（见下一节的例子）。 805 | % 806 | % The \meta{arg-spec} consists of a (possibly empty) list of letters, 807 | % each denoting one argument of the function. The letter, including 808 | % its case, conveys information about the type of argument required. 809 | \meta{选项规范arg-spec} 包含一个（可能为空的）字母列表，对应于该函数的每一选项。 810 | 字母（区分大小写）本身则带有所需选项类型的信息。 811 | 812 | % 813 | % All functions have a base form with arguments using one of the 814 | % following argument specifiers: 815 | 在所有函数都有的基本形式中，选项使用以下说明符之一： 816 | % \begin{arg-description} 817 | \begin{arg-description} 818 | % \item[n] Unexpanded token or braced token list.\\ 819 | % This is a standard \TeX{} undelimited macro argument. 820 | \item[n] 不展开的记号或者带大括号的记号列表。\\ 821 | 这是 \TeX{} 的标准未定界宏选项。 822 | % \item[N] Single token (unlike~|n|, the argument must \emph{not} be 823 | % surrounded by braces).\\ 824 | % A typical example of a command taking an~|N| 825 | % argument is~|\cs_set|, in which the command being defined must be 826 | % unbraced. 827 | \item[N] 单记号（与 |n| 不同，该选项一定\emph{不能}在大括号内）。\\ 828 | 带有 |N| 选项的函数中，一个典型的例子是~|\cs_set|，其中被定义的命令一定是不加大括号的。 829 | % \item[p] Primitive \TeX{} parameter specification.\\ 830 | % This can be something simple like~|#1#2#3|, but may use arbitrary 831 | % delimited argument syntax such as: |#1,#2\q_stop#3|. This is used 832 | % when defining functions. 833 | \item[p] \TeX{} 原始命令参数规范。\\ 834 | 可以简单地取为~|#1#2#3|，但也可以使用任意定界选项语法，比如 |#1,#2\q_stop#3|。 835 | 在定义函数时会使用。 836 | % \item[T,F] 837 | % These are special cases of~|n| arguments, used for the 838 | % true and false code in conditional commands. 839 | \item[T,F] 这是选项 |n| 的特殊情形，用于条件命令中的真值判断。 840 | % \end{arg-description} 841 | \end{arg-description} 842 | % There are two other specifiers with more general meanings: 843 | 另外还有两种意义更广泛的说明符： 844 | % \begin{arg-description} 845 | \begin{arg-description} 846 | % \item[D] This means: \textbf{Do not use}. This special case is used 847 | % for \TeX{} primitives. Programmers outside the kernel team should 848 | % not use these functions! 849 | \item[D] 意思是\textbf{不要使用}（\textbf{Do not use}）。 850 | 这一特殊情形用于 \TeX{} 原始命令。 851 | 内核团队之外的开发者不要使用这些函数！ 852 | % \item[w] This means that the argument syntax is \enquote{weird} in that it 853 | % does not follow any standard rule. It is used for functions with 854 | % arguments that take non standard forms: examples are \TeX{}-level 855 | % delimited arguments and the boolean tests needed after certain 856 | % primitive |\if|\ldots{} commands. 857 | \item[w] 选项语法是“奇怪的（weird）”，不遵从任何标准规则。 858 | 这用于带有非标准形式选项的函数： 859 | 相关例子包括 \TeX{} 层面的定界选项以及某些 |\if|\ldots{} 原始命令之后需要的布尔测试。 860 | % \end{arg-description} 861 | \end{arg-description} 862 | 863 | % 864 | % In case of |n| arguments that consist of a single token the 865 | % surrounding braces can be omitted in nearly all 866 | % situations---functions that force the use of braces even for single 867 | % token arguments are explicitly mentioned. However, programmers are 868 | % encouraged to always use braces around \texttt{n} arguments, as this 869 | % makes the relationship between function and argument clearer. 870 | 在 |n| 选项的情况中，如果只含有单个记号，那么包裹的大括号在几乎所有场合都可以省略 871 | ——那些即使是单记号选项也要加上大括号的函数会明确提及。 872 | 然而，我们鼓励开发者总是为 \texttt{n} 选项加上大括号， 873 | 这可以使得函数和选项的关系更清晰。 874 | 875 | % 876 | % Further argument specifiers are available as part of the expansion 877 | % control system. These are discussed in the next section. 878 | 进一步的选项说明符是展开控制系统的一部分，在下一节中讨论。 879 | 880 | % 881 | % \section{Expansion control} 882 | \section{展开控制} 883 | 884 | % 885 | % Let's take a look at some typical operations one might want to 886 | % perform. Suppose we maintain a stack of open files and we use the 887 | % stack |\g_ior_file_name_seq| to keep track of them (\texttt{ior} is 888 | % the prefix used for the file reading module). The basic operation here 889 | % is to push a name onto this stack which could be done by the operation 890 | % \begin{quote} 891 | % \cs{seq_gpush:Nn} |\g_ior_file_name_seq {#1}| 892 | % \end{quote} 893 | % where |#1| is the filename. In other words, this operation would 894 | % push the file name as is onto the stack. 895 | 让我们看一些可能要进行的典型操作。 896 | 假设我们维护一个文件打开的栈，并使用栈 |\g_ior_file_name_seq| 来保持对这些文件的跟踪 897 | （\texttt{ior} 是用于文件读取模块的前缀）。 898 | 这里基本操作是将一个文件名推入栈内，可以通过以下操作完成： 899 | \begin{quote} 900 | \cs{seq_gpush:Nn} |\g_ior_file_name_seq {#1}| 901 | \end{quote} 902 | 其中 |#1| 是文件名。即，该操作会将文件名本身推入栈内。 903 | 904 | % 905 | % However, we might face a situation where the filename is stored in 906 | % a variable of some sort, say |\l_ior_curr_file_tl|. In this case we 907 | % want to retrieve the value of the variable. If we simply use 908 | % \begin{quote} 909 | % \cs{seq_gpush:Nn} |\g_ior_file_name_seq| |\l_ior_curr_file_tl| 910 | % \end{quote} 911 | % we do not get the value of the variable pushed onto the stack, 912 | % only the variable name itself. Instead a suitable number of 913 | % \cs{exp_after:wN} would be necessary (together with extra braces) to 914 | % change the order of expansion,\footnote{\cs{exp_after:wN} is 915 | % the \LaTeX3 name for the \TeX{} \tn{expandafter} primitive.} \emph{i.e.} 916 | % \begin{quote} 917 | % \cs{exp_after:wN} \\ 918 | % | |\cs{seq_gpush:Nn} \\ 919 | % \cs{exp_after:wN} \\ 920 | % | \g_ior_file_name_seq| \\ 921 | % \cs{exp_after:wN} \\ 922 | % | { \l_ior_curr_file_tl }| 923 | % \end{quote} 924 | 然而，我们可能经常会面对的一种场合是，文件名存储在某一变量内，比如 |\l_ior_curr_file_tl|。 925 | 此时我们想要检索该变量的值。 926 | 如果简单地使用 927 | \begin{quote} 928 | \cs{seq_gpush:Nn} |\g_ior_file_name_seq| |\l_ior_curr_file_tl| 929 | \end{quote} 930 | 那么不会将变量的值推入栈内——推入栈内的仅仅是该变量本身的名称。 931 | 取代的办法是，有必要使用一定合适数量的 \cs{exp_after:wN} （以及额外的大括号） 932 | 来改变展开的顺序\footnote{ 933 | \cs{exp_after:wN} 是 \TeX{} 原始命令 \tn{expandafter} 的 \LaTeX3 名称}，即 934 | \begin{quote} 935 | \cs{exp_after:wN} \\ 936 | | |\cs{seq_gpush:Nn} \\ 937 | \cs{exp_after:wN} \\ 938 | | \g_ior_file_name_seq| \\ 939 | \cs{exp_after:wN} \\ 940 | | { \l_ior_curr_file_tl }| 941 | \end{quote} 942 | 943 | % 944 | % The above example is probably the simplest case but already shows 945 | % how the code changes to something difficult to understand. 946 | % Furthermore there is an assumption in this: that the storage bin 947 | % reveals its contents after exactly one expansion. Relying on this 948 | % means that you cannot do proper checking plus you have to know 949 | % exactly how a storage bin acts in order to get the correct number 950 | % of expansions. Therefore \LaTeX3 provides the programmer with a 951 | % general scheme that keeps the code compact and easy to understand. 952 | 以上的例子也许是最简单的情形， 953 | 但已经展示了代码是如何变得难以理解的。 954 | 此外这里还有一个假设：存储的容器正好在一次展开后就完全展示其中的内容。 955 | 依赖于这种机制就没法做任何合适的检查， 956 | 为了得到正确的展开数量就必须完全搞清楚存储容器是怎样运行的。 957 | 因此，\LaTeX3为开发者提供了一般性机制，使得代码紧凑并易于理解。 958 | 959 | % 960 | % To denote that some argument to a function needs special treatment one 961 | % just uses different letters in the arg-spec part of the function to 962 | % mark the desired behavior. In the above example one would write 963 | % \begin{quote} 964 | % \cs{seq_gpush:NV} |\g_ior_file_name_seq \l_ior_curr_file_tl| 965 | % \end{quote} 966 | % to achieve the desired effect. Here the |V| (the second argument) 967 | % is for \enquote{retrieve the value of the variable} before passing it to 968 | % the base function. 969 | 为了表达函数的选项需要特殊处理，只要在函数的选项规范部分中使用不同字母来标识需要的行为即可。 970 | 在上面的例子中，使用命令 971 | \begin{quote} 972 | \cs{seq_gpush:NV} |\g_ior_file_name_seq \l_ior_curr_file_tl| 973 | \end{quote} 974 | 即可达到想要的效果。 975 | 这里第二个选项 |V| 的意思是，在传递给基函数之前“先检索变量的值”。 976 | 977 | % 978 | % The following letters can be used to denote special treatment of 979 | % arguments before passing it to the base function: 980 | 以下字母可以用于表示选项传递给基函数之前的特殊处理： 981 | % \begin{description} 982 | \begin{description} 983 | % \item[c] Character string used as a command name.\\ The argument (a 984 | % token or braced token list) is \emph{fully expanded}; the result 985 | % must be a sequence of characters which is then used to construct a 986 | % command name (\emph{via}~\tn{csname} \ldots \tn{endcsname}). This 987 | % command name is a single token that is passed to the function as 988 | % the argument. Hence 989 | \item[c] 字符（character），作为命令名称使用。\\ 990 | 该选项（记号或者带大括号的记号列表）是\emph{完全展开的}； 991 | 其结果必须是字符序列， 992 | 并在之后用于构建命令名称（\emph{通过}~\tn{csname} \ldots \tn{endcsname} 方法）。 993 | 该命令名是单记号，可以作为选项传递给函数。因此 994 | % \begin{quote} 995 | % \cs{seq_gpush:cV} |{ g_file_name_seq }| \cs{l_tmpa_tl} 996 | % \end{quote} 997 | % is equivalent to 998 | % \begin{quote} 999 | % \cs{seq_gpush:NV} |\g_file_name_seq| \cs{l_tmpa_tl}. 1000 | % \end{quote} 1001 | \begin{quote} 1002 | \cs{seq_gpush:cV} |{ g_file_name_seq }| \cs{l_tmpa_tl} 1003 | \end{quote} 1004 | 等价于 1005 | \begin{quote} 1006 | \cs{seq_gpush:NV} |\g_file_name_seq| \cs{l_tmpa_tl} 1007 | \end{quote} 1008 | % Full expansion means that (a) the entire 1009 | % argument must be expandable and (b) any variables are 1010 | % converted to their content. So the preceding examples are also 1011 | % equivalent to 1012 | 完全展开的含义是 (a) 整个选项必须是可展开的；(b) 任何变量都会转为该变量的内容。 1013 | 因此之前的例子也等价于 1014 | % \begin{quote} 1015 | % \cs{tl_new:N} |\g_file_seq_name_tl| \\ 1016 | % \cs{tl_gset:Nn} |\g_file_seq_name_tl { g_file_name_seq }| \\ 1017 | % \cs{seq_gpush:cV} |{| \cs{tl_use:N} |\g_file_seq_name_tl }| \cs{l_tmpa_tl}. 1018 | % \end{quote} 1019 | % (Token list variables are expandable and we could omit the 1020 | % accessor function \cs{tl_use:N}. Other variable types require the 1021 | % appropriate \cs{\meta{var}_use:N} functions to be used in this 1022 | % context.) 1023 | \begin{quote} 1024 | \cs{tl_new:N} |\g_file_seq_name_tl| \\ 1025 | \cs{tl_gset:Nn} |\g_file_seq_name_tl { g_file_name_seq }| \\ 1026 | \cs{seq_gpush:cV} |{| \cs{tl_use:N} |\g_file_seq_name_tl }| \cs{l_tmpa_tl}. 1027 | \end{quote} 1028 | （记号列表变量是可展开的，此时我们可以省略访问函数 \cs{tl_use:N}。 1029 | 其它变量类型在这一环境下则需要使用合适的 \cs{_use:N} 函数。） 1030 | % \item[V] Value of a variable.\\ 1031 | % This means that the contents of the register in question is used as the 1032 | % argument, be it an integer, a length-type register, a token list variable 1033 | % or similar. The value is passed to the function as a braced token list. 1034 | % Can be applied to variables which have a \cs{\meta{var}_use:N} function 1035 | % (other than floating points and boxes), 1036 | % and which therefore deliver a single \enquote{value}. 1037 | \item[V] 变量的值（Value）。\\ 1038 | 此时，选项会使用寄存器的内容，可以是整型、长度类型的寄存器、记号列表变量等。 1039 | 该值作为带大括号的记号列表被传递给函数。 1040 | 可以用于带有 \cs{\meta{var}_use:N} 函数（而不是浮点数或盒子）， 1041 | 从而可以传递单“值”的变量。 1042 | % \item[v] Value of a register, constructed from a character string 1043 | % used as a command name.\\ 1044 | % This is a combination of |c| and |V| which first constructs a 1045 | % control sequence from the argument and then passes the value of the 1046 | % resulting register to the function. 1047 | % Can be applied to variables which have a \cs{\meta{var}_use:N} function (other than 1048 | % floating points and boxes), and which therefore deliver a single 1049 | % \enquote{value}. 1050 | \item[v] 寄存器的值（value），从命令名称的字符串构建而来。\\ 1051 | 该类型是 |c| 和 |V| 的结合，首先从选项中构造一个控制序列，然后将生成的寄存器的值传递给函数。 1052 | 可以用于带有 \cs{\meta{var}_use:N} 函数（而不是浮点数或盒子）， 1053 | 从而可以传递单值的变量。 1054 | % \item[x] Fully-expanded token or braced token list.\\ 1055 | % This means that the argument is expanded as in the replacement 1056 | % text of an~\tn{edef}, and the expansion is passed to the function as 1057 | % a braced token list. Expansion takes place until only unexpandable 1058 | % tokens are left. |x|-type arguments cannot be nested. 1059 | \item[x] 完全展开（expand）的记号或者带大括号的记号列表。\\ 1060 | 该选项会像用 \tn{edef} 一样展开，然后展开值作为带大括号的记号列表传递给函数。 1061 | 展开会一直执行，直到遇到不可展开的记号。 1062 | |x| 类型的选项不可以嵌套。 1063 | % \item[o] One-level-expanded token or braced token list.\\ 1064 | % This means that the argument is expanded one level, as by 1065 | % \tn{expandafter}, and the expansion is passed to the function as a 1066 | % braced token list. Note that if the original argument is a braced 1067 | % token list then only the first token in that list is expanded. 1068 | % In general, using \texttt{V} should be preferred to using 1069 | % \texttt{o} for simple variable retrieval. 1070 | \item[o] 展开一层（one-level）的记号或带大括号的记号列表。\\ 1071 | 这说明该选项会像 \tn{expandafter} 那样展开一层， 1072 | 然后展开值作为带大括号的记号列表传递给函数。 1073 | 请注意，如果原始的参数是带大括号的记号列表， 1074 | 那么只有列表中的第一个记号会被展开。 1075 | 一般来说，对于简单的变量检索使用类型 \texttt{V} 比使用 \texttt{o} 更好一些。 1076 | % \item[f] Expanding the first token recursively in a braced token 1077 | % list.\\ Almost the same as the |x| type except here the token list 1078 | % is expanded fully until the first unexpandable token is found and 1079 | % the rest is left unchanged. Note that if this function finds a 1080 | % space at the beginning of the argument it gobbles it and does not 1081 | % expand the next token. 1082 | \item[f] 在带有大括号的记号列表中递归地展开第一个（first）记号。\\ 1083 | 和 |x| 类型几乎相同，不同之处在于这里记号列表被完全展开， 1084 | 直到发现第一个不可展开的记号，而剩下的部分则保持不变。 1085 | 请注意，如果该函数在选项的一开始发现空格，那么会吞掉该空格，而不会展开接下来的记号。 1086 | % \end{description} 1087 | \end{description} 1088 | 1089 | % 1090 | % \subsection{Simpler means better} 1091 | \subsection{越简单越好} 1092 | 1093 | % 1094 | % Anyone who programs in \TeX{} is frustratingly familiar with the 1095 | % problem of arranging that arguments to functions are suitably expanded 1096 | % before the function is called. To illustrate how expansion control 1097 | % can bring instant relief to this problem we shall consider two 1098 | % examples copied from \texttt{latex.ltx}. 1099 | 如何安排函数的选项，使得选项在调用函数之前能够在合适的位置展开， 1100 | 这是每一个 \TeX{} 开发者都经常面对的头疼问题。 1101 | 我们从 \texttt{latex.ltx} 中选取两个例子， 1102 | 进而说明展开控制机制能够对这一问题带来立竿见影的效果。 1103 | 1104 | % 1105 | % \begin{verbatim} 1106 | % \global\expandafter\let 1107 | % \csname\cf@encoding \string#1\expandafter\endcsname 1108 | % \csname ?\string#1\endcsname 1109 | % \end{verbatim} 1110 | % This first piece of code is in essence simply a global \tn{let} whose 1111 | % two arguments firstly have to be constructed before \tn{let} is 1112 | % executed. The |#1| is a control sequence name such as 1113 | % |\textcurrency|. The token to be defined is obtained by 1114 | % concatenating the characters of the current font encoding stored in 1115 | % |\cf@encoding|, which has to be fully expanded, and the name of the 1116 | % symbol. The second token is the same except it uses the default 1117 | % encoding |?|. The result is a mess of interwoven \tn{expandafter} 1118 | % and \tn{csname} beloved of all \TeX{} programmers, and the code is 1119 | % essentially unreadable. 1120 | \begin{verbatim} 1121 | \global\expandafter\let 1122 | \csname\cf@encoding \string#1\expandafter\endcsname 1123 | \csname ?\string#1\endcsname 1124 | \end{verbatim} 1125 | 第一份代码片段本质上只是个全局的 \tn{let} 命令， 1126 | 它的两个选项必须在 \tn{let} 命令执行之前首先进行构造。 1127 | |#1| 是一个控制序列，比如 |\textcurrency|。 1128 | 将当前字体编码字符（存储在|\cf@encoding|，需要完全展开）和符号名称连接起来， 1129 | 并获得第一个选项需要定义的记号。 1130 | 而第二个选项中的记号也是相同的过程，只不过使用默认编码 |?|。 1131 | 而结果就是一团 \tn{expandafter} 和 \tn{csname} 交织在一起 1132 | （当然 \TeX{} 程序员都很喜欢用），导致代码本质上是不可读的。 1133 | 1134 | % 1135 | % Using the conventions and functionality outlined here, the task would 1136 | % be achieved with code such as this: 1137 | % \begin{verbatim} 1138 | % \cs_gset_eq:cc 1139 | % { \cf@encoding \token_to_str:N #1 } { ? \token_to_str:N #1 } 1140 | % \end{verbatim} 1141 | % The command \cs{cs_gset_eq:cc} is a global~\tn{let} that generates 1142 | % command names out of both of its arguments before making the 1143 | % definition. This produces code that is far more readable and more 1144 | % likely to be correct first time. (\cs{token_to_str:N} is the \LaTeX3 1145 | % name for \tn{string}.) 1146 | 使用这里提出的约定和功能，这项任务可以通过如下代码来实现： 1147 | \begin{verbatim} 1148 | \cs_gset_eq:cc 1149 | { \cf@encoding \token_to_str:N #1 } { ? \token_to_str:N #1 } 1150 | \end{verbatim} 1151 | 命令 \cs{cs_gset_eq:cc} 是全局的 \tn{let}， 1152 | 可以在定义之前先生成两个选项的命令名称。 1153 | 这样代码的可读性要好得多，出了问题也可以第一时间修改。 1154 | （\cs{token_to_str:N} 是 \tn{string} 的 \LaTeX3 名称。） 1155 | 1156 | % 1157 | % Here is the second example. 1158 | % \begin{verbatim} 1159 | % \expandafter 1160 | % \in@ 1161 | % \csname sym#3% 1162 | % \expandafter 1163 | % \endcsname 1164 | % \expandafter 1165 | % {% 1166 | % \group@list}% 1167 | % \end{verbatim} 1168 | % This piece of code is part of the definition of another function. It 1169 | % first produces two things: a token list, by expanding |\group@list| once; 1170 | % and a token whose name comes from~`|sym#3|'. Then the function~\cs{in@} 1171 | % is called and this tests if its first argument occurs in the token list 1172 | % of its second argument. 1173 | 这里是第二个例子： 1174 | \begin{verbatim} 1175 | \expandafter 1176 | \in@ 1177 | \csname sym#3% 1178 | \expandafter 1179 | \endcsname 1180 | \expandafter 1181 | {% 1182 | \group@list}% 1183 | \end{verbatim} 1184 | 这份代码是另外一个函数定义的一部分。 1185 | 它首先做两件事情： 1186 | 通过展开一次 |\group@list| 获得一个记号列表， 1187 | 从 |sym#3| 获取一个记号的名称。 1188 | 然后调用函数 \cs{in@} 并检测第一个选项是否在第二个选项代表的记号列表中。 1189 | 1190 | % 1191 | % Again we can improve enormously on the code. First we shall rename 1192 | % the function~\cs{in@}, which tests if its first argument appears 1193 | % within its second argument, according to our conventions. Such a 1194 | % function takes two normal \enquote{\texttt{n}} arguments and operates 1195 | % on token lists: it might reasonably be named |\tl_test_in:nn|. Thus 1196 | % the variant function we need would be defined with the appropriate 1197 | % argument types and its name would be |\tl_test_in:cV|. Now this code 1198 | % fragment would be simply: 1199 | % \begin{verbatim} 1200 | % \tl_test_in:cV { sym #3 } \group@list 1201 | % \end{verbatim} 1202 | % This code could be improved further by using a sequence |\l_group_seq| 1203 | % rather than the bare token list |\group@list|. Note that, in addition 1204 | % to the lack of \tn{expandafter}, the space after the~|}| is 1205 | % silently ignored since all white space is ignored in this programming 1206 | % environment. 1207 | 同样地，我们可以极大改进这份代码。 1208 | 首先根据约定，我们要重命名函数~\cs{in@}， 1209 | 该函数的功能是检测第一个选项是否出现在第二个选项内。 1210 | 这样的函数有两个正常的“|n|”选项，并操作记号列表： 1211 | 因此很自然地可以命名为 |\tl_test_in:nn|。 1212 | 我们需要的函数变体需要定义合适的选项类型，因此名称为 |\tl_test_in:cV|。 1213 | 现在该代码片段可以简化为 1214 | \begin{verbatim} 1215 | \tl_test_in:cV { sym #3 } \group@list 1216 | \end{verbatim} 1217 | 可以使用序列 |\l_group_seq| 来代替裸记号列表 |\group@list|， 1218 | 从而进一步改进代码。 1219 | 请注意，除了不需要 \tn{expandafter} 之外， 1220 | 右大括号 |}| 之后的空格也会自动忽略， 1221 | 这是因为该程序环境中所有的空格都会被忽略。 1222 | 1223 | % 1224 | % \subsection{New functions from old} 1225 | \subsection{函数推陈出新} 1226 | 1227 | % 1228 | % For many common functions the \LaTeX3 kernel provides variants 1229 | % with a range of argument forms, and similarly it is expected that 1230 | % extension packages providing new functions will make them available in 1231 | % all the commonly needed forms. 1232 | 对于很多常用函数，\LaTeX3 内核提供了针对不同选项形式的一系列函数变种。 1233 | 类似地，我们也希望扩展宏包提供的新函数对于常见选项类型都是可用的。 1234 | 1235 | % 1236 | % However, there will be occasions where it is necessary to construct a 1237 | % new such variant form; therefore the expansion module provides a 1238 | % straightforward mechanism for the creation of functions with any 1239 | % required argument type, starting from a function that takes \enquote{normal} 1240 | % \TeX{} undelimited arguments. 1241 | 然而构造新的函数变种形式有时候还是有必要的。 1242 | 为此，扩展模块提供了一种直接的机制， 1243 | 可以从带有“常规的”\TeX{} 未定界选项的函数开始，创建带有任何选项类型的函数 1244 | 1245 | % 1246 | % To illustrate this let us suppose you have a \enquote{base function} 1247 | % |\demo_cmd:Nnn| that takes three normal arguments, and that you need 1248 | % to construct the variant |\demo_cmd:cnx|, for which the first argument 1249 | % is used to construct the \emph{name} of a command, whilst the third 1250 | % argument must be fully expanded before being passed to 1251 | % |\demo_cmd:Nnn|. 1252 | % To produce the variant form from the base form, simply use this: 1253 | % \begin{verbatim} 1254 | % \cs_generate_variant:Nn \demo_cmd:Nnn { cnx } 1255 | % \end{verbatim} 1256 | % This defines the variant form so that you can then write, for example: 1257 | % \begin{verbatim} 1258 | % \demo_cmd:cnx { abc } { pq } { \rst \xyz } 1259 | % \end{verbatim} 1260 | % rather than \ldots\ well, something like this! 1261 | % \begin{verbatim} 1262 | % \def \tempa {{pq}}% 1263 | % \edef \tempb {\rst \xyz}% 1264 | % \expandafter 1265 | % \demo@cmd:nnn 1266 | % \csname abc% 1267 | % \expandafter 1268 | % \expandafter 1269 | % \expandafter 1270 | % \endcsname 1271 | % \expandafter 1272 | % \tempa 1273 | % \expandafter 1274 | % {% 1275 | % \tempb 1276 | % }% 1277 | % \end{verbatim} 1278 | 为了阐述这一点，假设有一个带有三个常规选项的“基函数”|\demo_cmd:Nnn|。 1279 | 现在想要构造变种 |\demo_cmd:cnx|，其中第一个选项用于构造命令的“名称”， 1280 | 而第三个选项必须在传给 |\demo_cmd:Nnn| 之前完全展开。 1281 | 只要简单地使用如下代码就可以从基本形式生成变种形式： 1282 | \begin{verbatim} 1283 | \cs_generate_variant:Nn \demo_cmd:Nnn { cnx } 1284 | \end{verbatim} 1285 | 然后变种函数就可以使用了，比如： 1286 | \begin{verbatim} 1287 | \demo_cmd:cnx { abc } { pq } { \rst \xyz } 1288 | \end{verbatim} 1289 | 否则的话……就要使用如下可怕的代码！ 1290 | \begin{verbatim} 1291 | \def \tempa {{pq}}% 1292 | \edef \tempb {\rst \xyz}% 1293 | \expandafter 1294 | \demo@cmd:nnn 1295 | \csname abc% 1296 | \expandafter 1297 | \expandafter 1298 | \expandafter 1299 | \endcsname 1300 | \expandafter 1301 | \tempa 1302 | \expandafter 1303 | {% 1304 | \tempb 1305 | }% 1306 | \end{verbatim} 1307 | 1308 | % 1309 | % Another example: you may wish to declare a function 1310 | % |\demo_cmd_b:xcxcx|, a variant of an existing function 1311 | % |\demo_cmd_b:nnnnn|, that fully 1312 | % expands arguments 1,~3 and~5, and produces commands to pass as 1313 | % arguments 2 and~4 using~\tn{csname}. 1314 | % The definition you need is simply 1315 | % \begin{verbatim} 1316 | % \cs_generate_variant:Nn \demo_cmd_b:nnnnn { xcxcx } 1317 | % \end{verbatim} 1318 | 另一个例子：你想要根据已有函数 |\demo_cmd_b:nnnnn| 来声明变种函数 |\demo_cmd_b:xcxcx|， 1319 | 使得可以完全展开选项1、3、5，然后使用 \tn{csname} 生成命令并传递选项2、4。 1320 | 定义这样的函数仅需要： 1321 | \begin{verbatim} 1322 | \cs_generate_variant:Nn \demo_cmd_b:nnnnn { xcxcx } 1323 | \end{verbatim} 1324 | 1325 | % 1326 | % This extension mechanism is written so that if the same new form of 1327 | % some existing command is implemented by two extension packages then the 1328 | % two definitions are identical and thus no conflict occurs. 1329 | 扩展机制的目的在于，如果两个不同的扩展宏包都对某个已有命令进行新变种的实现， 1330 | 那么这两个定义是相同的，不会造成冲突。 1331 | 1332 | % 1333 | % \section{The distribution} 1334 | \section{发布} 1335 | 1336 | % 1337 | % At present, the \pkg{expl3} modules are designed to be loaded on top 1338 | % of \LaTeXe{}. In time, a \LaTeX3 format will be produced based on this 1339 | % code. This allows the code to be used in \LaTeXe{} packages \emph{now} 1340 | % while a stand-alone \LaTeX3 is developed. 1341 | 目前，\pkg{expl3} 模块被设计为在 \LaTeXe{} 之上导入。 1342 | 之后会基于这些代码生成 \LaTeX3 格式。 1343 | 因此，\emph{目前}可以在 \LaTeXe{} 宏包中使用这些代码，而独立的 \LaTeX3 还在开发中。 1344 | 1345 | % 1346 | % \begin{bfseries} 1347 | % While \pkg{expl3} is still experimental, the bundle is now regarded 1348 | % as broadly stable. The syntax conventions and functions provided 1349 | % are now ready for wider use. There may still be changes to some 1350 | % functions, but these will be minor when compared to the scope of 1351 | % \pkg{expl3}. 1352 | % \end{bfseries} 1353 | \begin{bfseries} 1354 | 虽然 \pkg{expl3} 宏集仍然处于实验性质阶段，不过可以认为已经相当稳定了。 1355 | 提供的语法约定和函数也可以广泛应用。 1356 | 当然某些函数可能还有有改动，但与整个 \pkg{expl3} 相比只是一些小改动。 1357 | \end{bfseries} 1358 | 1359 | % 1360 | % New modules will be added to the distributed version of \pkg{expl3} 1361 | % as they reach maturity. At present, the \pkg{expl3} bundle consists 1362 | % of a number of modules, most of which are loaded by including the 1363 | % line: 1364 | % \begin{verbatim} 1365 | % \RequirePackage{expl3} 1366 | % \end{verbatim} 1367 | % in a \LaTeXe{} package, class or other file. The \pkg{expl3} modules 1368 | % regarded as stable, and therefore suitable for basing real code on, 1369 | % are as follows: 1370 | 新模块在成熟稳定后会加到 \pkg{expl3} 的发行版本中。 1371 | 目前 \pkg{expl3} 宏集已经包含了众多模块， 1372 | 在 \LaTeXe{} 宏包、文档类以及其它文件中包含如下一行代码即可导入绝大部分模块： 1373 | \begin{verbatim} 1374 | \RequirePackage{expl3} 1375 | \end{verbatim} 1376 | \pkg{expl3} 中的模块可以认为是稳定的， 1377 | 可以适合在其基础上构建实际代码， 1378 | 具体如下： 1379 | 1380 | % 1381 | % \begin{description} 1382 | \begin{description} 1383 | % \providecommand\explpkg[2]{\item[#1]#2} 1384 | \providecommand\explpkg[2]{\item[#1]#2} 1385 | % \explpkg{l3basics}{ 1386 | % This contains the basic definition modules used 1387 | % by the other packages. 1388 | % } 1389 | \explpkg{l3basics}{ 1390 | 包含其它宏包使用的基本定义模块。} 1391 | % \explpkg{l3box}{ 1392 | % Primitives for dealing with boxes. 1393 | % } 1394 | \explpkg{l3box}{ 1395 | 处理盒子的原始命令。} 1396 | % \explpkg{l3clist}{ 1397 | % Methods for manipulating comma-separated token lists. 1398 | % } 1399 | \explpkg{l3clist}{ 1400 | 操作逗号分隔记号列表的方法。} 1401 | % \explpkg{l3coffins}{ 1402 | % Augmented box constructs for alignment operations. 1403 | % } 1404 | \explpkg{l3coffins}{ 1405 | 补充的盒子对齐操作。} 1406 | % \explpkg{l3expan}{ 1407 | % This is the argument expansion module discussed earlier in this 1408 | % document. 1409 | % } 1410 | \explpkg{l3expan}{ 1411 | 本文档之前讨论的选项展开模块。} 1412 | % \explpkg{l3int}{ 1413 | % This implements the integer data-type \texttt{int}. 1414 | % } 1415 | \explpkg{l3int}{ 1416 | 实现整型数据类型 \texttt{int}。} 1417 | % \explpkg{l3keys}{ 1418 | % For processing lists of the form 1419 | % \texttt{\{ key1=val1 , key2=val2 \}}, intended to work 1420 | % as a \LaTeX3 version of \pkg{xkeyval}/\pkg{kvoptions}, although 1421 | % with input syntax more like that of \pkg{pgfkeys}. 1422 | % } 1423 | \explpkg{l3keys}{ 1424 | 处理具有形式 \texttt{\{ key1=val1 , key2=val2 \}} 的列表， 1425 | 本模块的目的是 \LaTeX3 版本的 \pkg{xkeyval}/\pkg{kvoptions} 宏包， 1426 | 不过输入的语法与 \pkg{pgfkeys} 更相似。} 1427 | % \explpkg{l3msg}{ 1428 | % Communicating with the user: includes low-level hooks to allow 1429 | % messages to be filtered (higher-level interface for filtering 1430 | % to be written!). 1431 | % } 1432 | \explpkg{l3msg}{ 1433 | 用户交互：包括一些用于过滤信息的低层次的钩子（高层次的过滤信息接口还在开发）。} 1434 | % \explpkg{l3names}{ 1435 | % This sets up the basic naming scheme and renames all 1436 | % the \TeX{} primitives. 1437 | % } 1438 | \explpkg{l3names}{ 1439 | 设置基本命名机制，并且重命名了所有的 \TeX{} 原始命令。} 1440 | % \explpkg{l3prg}{ 1441 | % Program control structures such as boolean data type |bool|, generic 1442 | % do-while loops, and conditional flow. 1443 | % } 1444 | \explpkg{l3prg}{ 1445 | 程序控制的一些结构，例如布尔变量类型 |bool|、一般的 do-while 循环以及条件流。} 1446 | % \explpkg{l3prop}{ 1447 | % This implements the data-type for \enquote{property lists} that are used, in 1448 | % particular, for storing key/value pairs. 1449 | % } 1450 | \explpkg{l3prop}{ 1451 | 实现了“属性列表”的数据类型，主要用于存储键值对。} 1452 | % \explpkg{l3quark}{ 1453 | % A \enquote{quark} is a command that is defined to expand to 1454 | % itself! Therefore they must never be expanded as this would generate an 1455 | % infinite recursion; they do however have many uses, \emph{e.g.}~as 1456 | % special markers and delimiters within code. 1457 | % } 1458 | \explpkg{l3quark}{ 1459 | “夸克（quark）”是定义为可以展开到自己的命令！ 1460 | 因此绝对不可以被展开，否则会产生无穷递归。 1461 | 不过它们确实有很多应用，比如作为代码内特别的标识符或定界符。\footnote{ 1462 | 这个概念疑似从 quine 变形而来，后者指能够生成自己的程序代码，见 \url{https://en.wikipedia.org/wiki/Quine_(computing)} 1463 | ——译注}} 1464 | % \explpkg{l3seq}{ 1465 | % This implements data-types such as queues and stacks. 1466 | % } 1467 | \explpkg{l3seq}{ 1468 | 实现了队列和栈等数据类型。} 1469 | % \explpkg{l3skip}{ 1470 | % Implements the \enquote{rubber length} datatype \texttt{skip}, the 1471 | % \enquote{rigid length} datatype |dim|, and the math mode 1472 | % \enquote{rubber length} datatype \texttt{muskip}. 1473 | % } 1474 | \explpkg{l3skip}{ 1475 | 实现了“弹性长度”数据类型 \texttt{skip}，“严格长度”数据类型 |dim|， 1476 | 以及数学模式“弹性长度”数据类型 \texttt{muskip}。} 1477 | % \explpkg{l3tl}{ 1478 | % This implements a basic data-type, called a \textit{token-list 1479 | % variable} (|tl var.|), used for storing named token lists: these are 1480 | % \TeX{} macros with no arguments. 1481 | % } 1482 | \explpkg{l3tl}{ 1483 | 实现了基本数据类型 \emph{记号列表变量}（|tl var.|），用于存储命名记号列表： 1484 | 不带参数的 \TeX{} 宏。} 1485 | % \explpkg{l3token}{ 1486 | % Analysing token lists and token streams, including peeking ahead to 1487 | % see what's coming next and inspecting tokens to detect which kind 1488 | % they are. 1489 | % } 1490 | \explpkg{l3token}{ 1491 | 分析记号列表和记号流，包括查看接下来的记号以及检测相关类型。} 1492 | % \end{description} 1493 | \end{description} 1494 | 1495 | % 1496 | % \section{Moving from \LaTeXe{} to \LaTeX3} 1497 | \section{从 \LaTeXe{} 到 \LaTeX3} 1498 | 1499 | % 1500 | % To help programmers to use \LaTeX3 code in existing \LaTeXe{} package, 1501 | % some short notes on making the change are probably desirable. 1502 | % Suggestions for inclusion here are welcome! Some of the following 1503 | % is concerned with code, and some with coding style. 1504 | 为了帮助开发者在现有的 \LaTeXe{} 宏包中使用 \LaTeX3 代码， 1505 | 给出一些关于相关改变的简要注记是值得的。 1506 | 这里总的建议就是欢迎使用！ 1507 | 以下的注记中一些是关于代码的，另一些则关于代码风格。 1508 | 1509 | % 1510 | % \begin{itemize} 1511 | \begin{itemize} 1512 | % \item \pkg{expl3} is mainly focused on programming. This means that 1513 | % some areas still require the use of \LaTeXe{} internal macros. 1514 | % For example, you may well need \tn{@ifpackageloaded}, as there 1515 | % is currently no native \LaTeX3 package loading module. 1516 | \item \pkg{expl3} 主要关注于程序设计。所以某些领域仍然需要 \LaTeXe{} 的内部宏。 1517 | 例如你可能需要 \tn{@ifpackageloaded}，因为当前 \LaTeX3 没有原生的宏包导入模块。 1518 | % \item User level macros should be generated using the mechanism 1519 | % available in the \pkg{xparse} package, which is part of the 1520 | % \texttt{l3package} bundle, available from CTAN or the \LaTeX3 SVN 1521 | % repository. 1522 | \item 用户水平的宏应当使用 \pkg{xparse} 宏包中的机制生成，这是 \texttt{l3package} 宏集的一部分， 1523 | 可以从 CTAN 或者 \LaTeX3 SVN 仓库获得。 1524 | % \item At an internal level, most functions should be generated 1525 | % \tn{long} (using \cs{cs_new:Npn}) rather than \enquote{short} (using 1526 | % \cs{cs_new_nopar:Npn}). 1527 | \item 在内部层面上，大部分函数应当生成为 \tn{long}（使用 \cs{cs_new:Npn}） 1528 | 而不是“short”（使用 \cs{cs_new_nopar:Npn}）。 1529 | % \item Where possible, declare all variables and functions (using 1530 | % \cs{cs_new:Npn}, \cs{tl_new:N}, etc.) before use. 1531 | \item 尽可能在使用之前声明所有变量和函数（使用 \cs{cs_new:Npn}, \cs{tl_new:N} 等）。 1532 | % \item Prefer \enquote{higher-level} functions over \enquote{lower-level}, 1533 | % where possible. So for example use \cs{cs_if_exist:N(TF)} and not 1534 | % \cs{if_cs_exist:N}. 1535 | \item 尽可能选择“高层次”函数而不是“低层次”函数。 1536 | 例如使用 \cs{cs_if_exist:N(TF)} 而不是 \cs{if_cs_exist:N}。 1537 | % \item Use space to make code readable. In general, we recommend 1538 | % a layout such as: 1539 | % \begin{verbatim} 1540 | % \cs_new:Npn \foo_bar:Nn #1#2 1541 | % { 1542 | % \cs_if_exist:NTF #1 1543 | % { \__foo_bar:n {#2} } 1544 | % { \__foo_bar:nn {#2} { literal } } 1545 | % } 1546 | % \end{verbatim} 1547 | % where spaces are used around |{| and |}| except for isolated 1548 | % |#1|, |#2|, \emph{etc.} 1549 | \item 使用空格以增加代码的可读性。一般我们推荐以下的风格： 1550 | \begin{verbatim} 1551 | \cs_new:Npn \foo_bar:Nn #1#2 1552 | { 1553 | \cs_if_exist:NTF #1 1554 | { \__foo_bar:n {#2} } 1555 | { \__foo_bar:nn {#2} { literal } } 1556 | } 1557 | \end{verbatim} 1558 | 在 |{| 和 |}| 周围使用空格，除非是单独的 |#1|, |#2| 等。 1559 | % \item Put different code items on separate lines: readability is 1560 | % much more useful than compactness. 1561 | \item 将不同的代码项目分行放置：可读性比紧凑性有用的多。 1562 | % \item Use long, descriptive names for functions and variables, 1563 | % and for auxiliary functions use the parent function name plus 1564 | % |aux|, |auxi|, |auxii| and so on. 1565 | \item 在函数和变量中使用长的描述性的名称， 1566 | 而对于辅助函数则使用父函数加上 |aux|, |auxi|, |auxii| 等前后缀。 1567 | % \item If in doubt, ask the team via the LaTeX-L list: someone will 1568 | % soon get back to you! 1569 | \item 如果有任何疑问， 1570 | 通过 \href{http://news.gmane.org/group/gmane.comp.tex.latex.latex3}{LaTeX-L} 列表咨询团队： 1571 | 相关人员会很快回复！ 1572 | % \end{itemize} 1573 | \end{itemize} 1574 | 1575 | % 1576 | % \section{Load-time options for \pkg{expl3}} 1577 | \section{宏包 \pkg{expl3} 的载入时选项} 1578 | 1579 | % 1580 | % To support code authors, the \pkg{expl3} package for \LaTeXe{} includes 1581 | % a small number of load-time options. These all work in a key--value 1582 | % sense, recognising the \texttt{true} and \texttt{false} values. Giving 1583 | % the option name alone is equivalent to using the option with the 1584 | % \texttt{true} value. 1585 | 为了支持代码开发者，\LaTeXe{} 宏包 \pkg{expl3} 包含了少量导入时选项。 1586 | 这些选项都以键值形式给出，并可以识别 \texttt{true} 和 \texttt{false} 值。 1587 | 只给出选项名等价于该选项使用 \texttt{true} 值。 1588 | 1589 | % 1590 | % \DescribeOption{check-declarations} 1591 | % All variables used in \LaTeX3 code should be declared. This is enforced 1592 | % by \TeX{} for variable types based on \TeX{} registers, but not for those 1593 | % which are constructed using macros as the underlying storage system. The 1594 | % \texttt{check-declarations} option enables checking for all variable 1595 | % assignments, issuing an error if any variables are assigned without being 1596 | % initialised. See also \cs{debug_on:n} \texttt{\{check-declarations\}} 1597 | % in \pkg{l3candidates} for finer control. 1598 | \DescribeOption{check-declarations} 1599 | 所有 \LaTeX3 代码中的变量都必须声明。 1600 | 对于基于 \TeX{} 寄存器的变量类型，这由 \TeX{} 强制执行； 1601 | 而出于底层的存储原因，对于使用宏构造的变量则不保证。 1602 | 选项 \texttt{check-declarations} 则确保对于所有变量分配都开启检查， 1603 | 如果任何变量没有初始化则报错。 1604 | 另见 \pkg{l3candidates} 中的 \cs{debug_on:n} \texttt{\{check-declarations\}}， 1605 | 可以进行更精细的控制。 1606 | 1607 | % 1608 | % \DescribeOption{log-functions} 1609 | % The \texttt{log-functions} option is used to enable recording of every new 1610 | % function name in the \texttt{.log} file. This is useful for debugging 1611 | % purposes, as it means that there is a complete list of all functions 1612 | % created by each module loaded (with the exceptions of a very small number 1613 | % required by the bootstrap code for \LaTeX3). See also \cs{debug_on:n} 1614 | % \texttt{\{log-functions\}} in \pkg{l3candidates} for finer control. 1615 | \DescribeOption{log-functions} 1616 | 该选项用于在 \texttt{.log} 文件中开启每一新函数名的记录。 1617 | 这会有一份由导入模块创建的全体函数列表 1618 | （例外是 \LaTeX3 的bootstrap代码需要的一小部分）。 1619 | 另见 \pkg{l3candidates} 中的\cs{debug_on:n} \texttt{\{log-functions\}}， 1620 | 可以进行更精细的控制。 1621 | 1622 | % 1623 | % \DescribeOption{enable-debug} 1624 | % To allow more localized checking and logging than provided by 1625 | % \texttt{check-declarations} and \texttt{log-functions}, \pkg{expl3} 1626 | % provides a few \cs[no-index]{debug_\ldots{}} functions (described 1627 | % elsewhere) that turn on the corresponding checks within a group. 1628 | % These functions can only be used if \pkg{expl3} is loaded with the 1629 | % \texttt{enable-debug} option. 1630 | \DescribeOption{enable-debug} 1631 | 除了 \texttt{check-declarations} 和 \texttt{log-functions} 之外， 1632 | \pkg{expl3} 还提供了一些 \cs[no-index]{debug_\ldots{}} 函数（描述另见他处） 1633 | 在一个组内开启相应检查，这样可以允许更多的本地化检查和日志记录。 1634 | 只有当 \pkg{expl3} 导入时带有 \texttt{enable-debug} 选项时才可以使用这些函数。 1635 | 1636 | % 1637 | % \DescribeOption{driver} 1638 | % Selects the driver to be used for color, graphics and related operations that 1639 | % are driver-dependent. Options available are 1640 | \DescribeOption{driver} 1641 | 选择颜色、图像和其它驱动相关操作所需要的驱动类型。可用选项有： 1642 | % \begin{itemize}[font = \texttt] 1643 | \begin{itemize}[font = \texttt] 1644 | % \item[auto] Let \LaTeX3 determine the correct driver. With DVI output, this 1645 | % selects the \texttt{dvips} back-end for \pdfTeX{} and \LuaTeX{}, and 1646 | % \texttt{dvipdfmx} for \pTeX{} and \upTeX{}. This is the standard setting. 1647 | \item[auto] 让 \LaTeX3 自己确定正确的驱动。 1648 | 输出 DVI 时，会为 \pdfTeX{} 和 \LuaTeX{} 选择 \texttt{dvips} 后端， 1649 | 而对于 \pTeX{} 和 \upTeX{} 则会选择 \texttt{dvipdfmx}。 1650 | 这是标准设置。 1651 | % \item[latex2e] Use the \pkg{graphics} package to select the driver, rather 1652 | % than \LaTeX3 code. 1653 | \item[latex2e] 使用 \pkg{graphics} 宏包代替 \LaTeX3 代码来选择驱动。 1654 | % \item[dvips] Use the \texttt{dvips} driver. 1655 | \item[dvips] 使用 \texttt{dvips} 驱动。 1656 | % \item[dvipdfmx] Use the \texttt{dvipdfmx} driver. 1657 | \item[dvipdfmx] 使用 \texttt{dvipdfmx} 驱动。 1658 | % \item[dvisvgm] Use the \texttt{dvisvgm} driver. 1659 | \item[dvisvgm] 使用 \texttt{dvisvgm} 驱动。 1660 | % \item[pdfmode] Use the \texttt{pdfmode} driver (direct PDF output from 1661 | % \pdfTeX{} or \LuaTeX{}). 1662 | \item[pdfmode] 使用 \texttt{pdfmode} 驱动（\pdfTeX{} 或 \LuaTeX{} 的直接PDF输出）。 1663 | % \item[xdvipdfmx] Use the \texttt{xdvipdfmx} driver (\XeTeX{} only). 1664 | \item[xdvipdfmx] 使用 \texttt{xdvipdfmx} 驱动（仅用于 \XeTeX{}）。 1665 | % \end{itemize} 1666 | \end{itemize} 1667 | 1668 | % 1669 | % \section{Using \pkg{expl3} with formats other than \LaTeXe{}} 1670 | \section{在 \LaTeXe{} 之外使用 \pkg{expl3}} 1671 | 1672 | % 1673 | % As well as the \LaTeXe{} package \pkg{expl3}, there is also a 1674 | % \enquote{generic} loader for the code, \texttt{expl3.tex}. This may be 1675 | % loaded using the plain \TeX{} syntax 1676 | % \begin{verbatim} 1677 | % \input expl3-generic % 1678 | % \end{verbatim} 1679 | % This enables the programming layer to work with the other formats. 1680 | % As no options are available loading in this way, the \enquote{native} 1681 | % drivers are automatically used. If this \enquote{generic} loader is 1682 | % used with \LaTeXe{} the code automatically switches to the appropriate 1683 | % package route. 1684 | 在 \LaTeXe{} 宏包 \pkg{expl3} 之外，还有一种“一般的”方法可以导入该代码：\texttt{expl3.tex}。 1685 | 这可以在 plain\TeX{} 语法中导入： 1686 | \begin{verbatim} 1687 | \input expl3-generic % 1688 | \end{verbatim} 1689 | 这可以在其它格式下进行程序设计层面的有关工作。 1690 | 使用这种方法时没有可用的选项，所以会自动选择“原生的”驱动。 1691 | 如果在 \LaTeXe{} 中使用这种“一般的”导入方法， 1692 | 那么代码会自动切换到合适的宏包路径上去。 1693 | 1694 | % 1695 | % After loading the programming layer using the generic interface, the 1696 | % commands \cs{ExplSyntaxOn} and \cs{ExplSyntaxOff} and the code-level 1697 | % functions and variables detailed in \pkg{interface3} are available. 1698 | % Note that other \LaTeXe{} packages \emph{using} \pkg{expl3} are not 1699 | % loadable: package loading is dependent on the \LaTeXe{} package-management 1700 | % mechanism. 1701 | 使用一般接口导入程序设计层面后， 1702 | 可以使用命令 \cs{ExplSyntaxOn}、\cs{ExplSyntaxOff}、 1703 | 以及 \pkg{interface3} 中详细介绍的代码层面上的函数和变量。 1704 | 请注意不会导入其它\emph{使用} \pkg{expl3} 的 \LaTeXe{} 宏包： 1705 | 宏包导入取决于 \LaTeXe{} 的宏包管理机制。 1706 | 1707 | % 1708 | % \section{Engine/primitive requirements} 1709 | \section{引擎和原始命令需求} 1710 | 1711 | % 1712 | % To use \pkg{expl3} and the higher level packages provided by the 1713 | % team, the minimal set of primitive requirements is currently 1714 | 为了使用本团队提供的 \pkg{expl3} 和高层面宏包， 1715 | 目前原始命令需求的最小集合是 1716 | % \begin{itemize} 1717 | \begin{itemize} 1718 | % \item All of those from \TeX90. 1719 | \item \TeX90 中的全部。 1720 | % \item All of those from \eTeX{} \emph{excluding} |\TeXXeTstate|, 1721 | % |\beginL|, |\beginR|, |\endL| and |\endR| (\emph{i.e.}~excluding 1722 | % \TeX{}-\kern0pt-\reflectbox{\TeX{}}). 1723 | \item \eTeX{} 中的全部，\emph{除了} |\TeXXeTstate|, |\beginL|, |\beginR|, |\endL|, |\endR| 1724 | （即，除了 \TeX{}-\kern0pt-\reflectbox{\TeX{}}）。 1725 | % \item Functionality equivalent to the \pdfTeX{} primitive 1726 | % |\pdfstrcmp|. 1727 | \item 等价于 \pdfTeX{} 原始命令 |\pdfstrcmp| 的功能。 1728 | % \end{itemize} 1729 | \end{itemize} 1730 | % Any engine which defines |\pdfoutput| (\emph{i.e.}~allows direct production 1731 | % of a PDF file without a DVI intermediate) must also provide |\pdfcolorstack|, 1732 | % |\pdfliteral|, |\pdfmatrix|, |\pdfrestore| and |\pdfsave| or equivalent 1733 | % functionality. Fully Unicode engines must provide a method for producing 1734 | % character tokens in an expandable manner. 1735 | 任何定义了 |\pdfoutput|（即，允许不经中间的DVI直接生成 PDF文件） 1736 | 的引擎必须同时提供 |\pdfcolorstack|, |\pdfliteral|, |\pdfmatrix|, |\pdfrestore|, |\pdfsave| 或者等价的功能。 1737 | Unicode引擎必须提供以可展开方式生成字符记号的方法。 1738 | 1739 | % 1740 | % \begin{itemize} 1741 | % \item \pdfTeX{} v1.40 or later. 1742 | % \item \XeTeX{} v0.99992 or later. 1743 | % \item \LuaTeX{} v0.76 or later. 1744 | % \item e-(u)\pTeX{} mid-2012 or later. 1745 | % \end{itemize} 1746 | 实际中，以下引擎可以满足这些需求 1747 | \begin{itemize} 1748 | \item \pdfTeX{} v1.40 或之后版本。 1749 | \item \XeTeX{} v0.99992 或之后版本。 1750 | \item \LuaTeX{} v0.70 或之后版本。 1751 | \item e-(u)p\TeX{} 2012 中期或之后版本。 1752 | \end{itemize} 1753 | 1754 | % 1755 | % Additional modules beyond the core of \pkg{expl3} may require additional 1756 | % primitives. In particular, third-party authors may significantly 1757 | % extend the primitive coverage requirements. 1758 | \pkg{expl3} 内核之外的其它模块可能需要额外的原始命令。 1759 | 特别要指出的是，第三方作者可能会明显地提高对原始命令覆盖的需求。 1760 | 1761 | % 1762 | % \section{The \LaTeX3 Project} 1763 | \section{\LaTeX3 项目组} 1764 | \LaTeX3 的开发由 \LaTeX3 项目组实施。成员名单略。 1765 | 1766 | % 1767 | % Development of \LaTeX3 is carried out by The \LaTeX3 Project. Over time, 1768 | % the membership of this team has naturally varied. Currently, the members 1769 | % are 1770 | % \begin{itemize} 1771 | % \item Johannes Braams 1772 | % \item David Carlisle 1773 | % \item Robin Fairbairns 1774 | % \item Morten H{\o}gholm 1775 | % \item Bruno Le Floch 1776 | % \item Thomas Lotze 1777 | % \item Frank Mittelbach 1778 | % \item Will Robertson 1779 | % \item Chris Rowley 1780 | % \item Rainer Sch{\"o}pf 1781 | % \item Joseph Wright 1782 | % \end{itemize} 1783 | % while former members are 1784 | % \begin{itemize} 1785 | % \item Michael Downes 1786 | % \item Denys Duchier 1787 | % \item Alan Jeffrey 1788 | % \item Martin Schr{\"o}der 1789 | % \end{itemize} 1790 | % 1791 | 1792 | \begin{thebibliography}{1} 1793 | 1794 | \bibitem{A-W:K-TB} 1795 | Donald E Knuth 1796 | \newblock \emph{The \TeX{}book}. 1797 | \newblock Addison-Wesley, Reading, Massachusetts, 1984. 1798 | 1799 | \bibitem{A-W:GMS94} 1800 | Goossens, Mittelbach and Samarin. 1801 | \newblock \emph{ The \LaTeX{} Companion}. 1802 | \newblock Addison-Wesley, Reading, Massachusetts, 1994. 1803 | 1804 | \bibitem{A-W:LLa94} 1805 | Leslie Lamport. 1806 | \newblock \emph{\LaTeX{}: A Document Preparation System}. 1807 | \newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994. 1808 | 1809 | \bibitem{tub:MR97-1} 1810 | Frank Mittelbach and Chris Rowley. 1811 | \newblock \enquote{The \LaTeX3 Project}. 1812 | \newblock \emph{TUGboat}, 1813 | Vol.\,18, No.\,3, pp.\,195--198, 1997. 1814 | 1815 | \end{thebibliography} 1816 | 1817 | 1818 | \end{document} 1819 | 1820 | 1821 | 1822 | 1823 | -------------------------------------------------------------------------------- /expl3-doc-cn/expl3.dtx: -------------------------------------------------------------------------------- 1 | % \iffalse meta-comment 2 | % 3 | %% File: expl3.dtx Copyright (C) 1990-2018 The LaTeX3 Project 4 | % 5 | % It may be distributed and/or modified under the conditions of the 6 | % LaTeX Project Public License (LPPL), either version 1.3c of this 7 | % license or (at your option) any later version. The latest version 8 | % of this license is in the file 9 | % 10 | % https://www.latex-project.org/lppl.txt 11 | % 12 | % This file is part of the "l3kernel bundle" (The Work in LPPL) 13 | % and all files in that bundle must be distributed together. 14 | % 15 | % ----------------------------------------------------------------------- 16 | % 17 | % The development version of the bundle can be found at 18 | % 19 | % https://github.com/latex3/latex3 20 | % 21 | % for those people who are interested. 22 | % 23 | %<*driver|generic|package> 24 | \def\ExplFileDate{2018-08-23}% 25 | % 26 | %<*driver> 27 | \documentclass[full]{l3doc} 28 | \usepackage{graphicx} 29 | \begin{document} 30 | \DocInput{\jobname.dtx} 31 | \end{document} 32 | % 33 | % \fi 34 | % 35 | % \providecommand\acro[1]{\textsc{\MakeLowercase{#1}}} 36 | % \newenvironment{arg-description}{% 37 | % \begin{itemize}\def\makelabel##1{\hss\llap{\bfseries##1}}}{\end{itemize}} 38 | % 39 | % \title{^^A 40 | % The \textsf{expl3} package and \LaTeX3 programming^^A 41 | % } 42 | % 43 | % \author{^^A 44 | % The \LaTeX3 Project\thanks 45 | % {^^A 46 | % E-mail: 47 | % \href{mailto:latex-team@latex-project.org} 48 | % {latex-team@latex-project.org}^^A 49 | % }^^A 50 | % } 51 | % 52 | % \date{Released 2018-08-23} 53 | % 54 | % \maketitle 55 | % 56 | % \begin{documentation} 57 | % 58 | % \begin{abstract} 59 | % 60 | % This document gives an introduction to a new set of programming 61 | % conventions that have been designed to meet the requirements of 62 | % implementing large scale \TeX{} macro programming projects such as 63 | % \LaTeX{}. These programming conventions are the base layer of \LaTeX3. 64 | % 65 | % The main features of the system described are: 66 | % \begin{itemize} 67 | % \item classification of the macros (or, in \LaTeX{} terminology, 68 | % commands) into \LaTeX{} functions and \LaTeX{} parameters, and also 69 | % into modules containing related commands; 70 | % \item a systematic naming scheme based on these classifications; 71 | % \item a simple mechanism for controlling the expansion of a function's 72 | % arguments. 73 | % \end{itemize} 74 | % This system is being used as the basis for \TeX{} programming within 75 | % the \LaTeX3 project. Note that the language is not intended for either 76 | % document mark-up or style specification. Instead, it is intended that 77 | % such features will be built on top of the conventions described here. 78 | % 79 | % This document is an introduction to the ideas behind the \pkg{expl3} 80 | % programming interface. For the complete documentation of the programming 81 | % layer provided by the \LaTeX3 Project, see the accompanying 82 | % \texttt{interface3} document. 83 | % 84 | % \end{abstract} 85 | % 86 | % \section{Introduction} 87 | % 88 | % The first step to develop a \LaTeX{} kernel beyond \LaTeXe{} is to 89 | % address how the underlying system is programmed. Rather than the 90 | % current mix of \LaTeX{} and \TeX{} macros, the \LaTeX3 system provides 91 | % its own consistent interface to all of the functions needed to 92 | % control \TeX{}. A key part of this work is to ensure that everything 93 | % is documented, so that \LaTeX{} programmers and users can work 94 | % efficiently without needing to be familiar with the internal nature 95 | % of the kernel or with plain \TeX{}. 96 | % 97 | % The \pkg{expl3} bundle provides this new programming interface for 98 | % \LaTeX{}. To make programming systematic, \LaTeX3 uses some very 99 | % different conventions to \LaTeXe{} or plain \TeX{}. As a result, 100 | % programmers starting with \LaTeX3 need to become familiar with 101 | % the syntax of the new language. 102 | % 103 | % The next section shows where this language fits into a complete 104 | % \TeX{}-based document processing system. We then describe the major 105 | % features of the syntactic structure of command names, including the 106 | % argument specification syntax used in function names. 107 | % 108 | % The practical ideas behind this argument syntax will be explained, 109 | % together with the expansion control mechanism and the interface 110 | % used to define variant forms of functions. 111 | % 112 | % As we shall demonstrate, the use of a structured naming scheme and of 113 | % variant forms for functions greatly improves the readability of the 114 | % code and hence also its reliability. Moreover, experience has shown 115 | % that the longer command names which result from the new syntax do not 116 | % make the process of \emph{writing} code significantly harder. 117 | % 118 | % \section{Languages and interfaces} 119 | % 120 | % It is possible to identify several distinct languages related to the 121 | % various interfaces that are needed in a \TeX{}-based document processing 122 | % system. This section looks at those we consider most important for 123 | % the \LaTeX3 system. 124 | % 125 | % \begin{description} 126 | % \item[Document mark-up] This comprises those commands (often called 127 | % tags) that are to embedded in the document (the |.tex| file). 128 | % 129 | % It is generally accepted that such mark-up should be essentially 130 | % \emph{declarative}. It may be traditional \TeX{}-based mark-up such 131 | % as \LaTeXe{}, as described in~\cite{A-W:LLa94} and~\cite{A-W:GMS94}, 132 | % or a mark-up language defined via \acro{HTML} or \acro{XML}. 133 | % 134 | % One problem with more traditional \TeX{} coding conventions (as 135 | % described in~\cite{A-W:K-TB}) is that the names and syntax of \TeX{}'s 136 | % primitive formatting commands are ingeniously designed to be 137 | % \enquote{natural} when used directly by the author as document mark-up 138 | % or in macros. Ironically, the ubiquity (and widely recognised 139 | % superiority) of logical mark-up has meant that such explicit 140 | % formatting commands are almost never needed in documents or in 141 | % author-defined macros. Thus they are used almost exclusively by 142 | % \TeX{} programmers to define higher-level commands, and their 143 | % idiosyncratic syntax is not at all popular with this community. 144 | % Moreover, many of them have names that could be very useful as 145 | % document mark-up tags were they not pre-empted as primitives 146 | % (\emph{e.g.}~\tn{box} or \tn{special}). 147 | % 148 | % \item[Designer interface] This relates a (human) typographic 149 | % designer's specification for a document to a program that 150 | % \enquote{formats 151 | % the document}. It should ideally use a declarative language that 152 | % facilitates expression of the relationship and spacing rules 153 | % specified for the layout of the various document elements. 154 | % 155 | % This language is not embedded in document text and it will be very 156 | % different in form to the document mark-up language. For \LaTeX{}, 157 | % this level was almost completely missing from \LaTeX{}2.09; \LaTeXe{} 158 | % made some improvements in this area but it is still the case that 159 | % implementing a design specification in \LaTeX{} requires far more 160 | % \enquote{low-level} coding than is acceptable. 161 | % 162 | % \item[Programmer interface] 163 | % This language is the implementation language within which the 164 | % basic typesetting functionality is implemented, building upon the 165 | % primitives of \TeX{} (or a successor program). It may also be used 166 | % to implement the previous two languages \enquote{within} \TeX{}, as in 167 | % the 168 | % current \LaTeX{} system. 169 | % 170 | % \end{description} 171 | % 172 | % The last layer is covered by the conventions described in this 173 | % document, which describes a system aimed at providing a suitable 174 | % basis for coding \LaTeX3. Its main distinguishing features are 175 | % summarised here: 176 | % \begin{itemize} 177 | % \item A consistent naming scheme for all commands, including \TeX{} 178 | % primitives. 179 | % \item The classification of commands as \LaTeX{} functions or \LaTeX{} 180 | % parameters, and also their division into modules according to their 181 | % functionality. 182 | % \item A simple mechanism for controlling argument expansion. 183 | % \item Provision of a set of core \LaTeX{} functions that is sufficient 184 | % for handling programming constructs such as queues, sets, stacks, 185 | % property lists. 186 | % \item A \TeX{} programming environment in which, for example, all 187 | % white space is ignored. 188 | % \end{itemize} 189 | % 190 | % \section{The naming scheme} 191 | % 192 | % \LaTeX3 does not use |@| as a \enquote{letter} for defining 193 | % internal macros. Instead, the symbols |_| and |:| 194 | % are used in internal macro names to provide structure. In 195 | % contrast to the plain \TeX{} format and the \LaTeXe{} kernel, these 196 | % extra letters are used only between parts of a macro name (no 197 | % strange vowel replacement). 198 | % 199 | % While \TeX{} is actually a macro processor, by 200 | % convention for the \pkg{expl3} programming language we distinguish between 201 | % \emph{functions} and \emph{variables}. Functions can have arguments and they 202 | % are either expanded or executed. Variables can be assigned values and they 203 | % are used in arguments to functions; they are not used directly but are 204 | % manipulated by functions (including getting and setting functions). 205 | % Functions and variables with a related functionality (for example accessing 206 | % counters, or manipulating token lists, \emph{etc.})\ are collected together 207 | % into a 208 | % \emph{module}. 209 | % 210 | % \subsection{Examples} 211 | % 212 | % Before giving the details of the naming scheme, here are a few typical 213 | % examples to indicate the flavour of the scheme; first some variable 214 | % names. 215 | % \begin{quote} 216 | % \cs{l_tmpa_box} is a local variable (hence the~|l_| prefix) 217 | % corresponding to a box register.\\ 218 | % \cs{g_tmpa_int} is a global variable (hence the~|g_| prefix) 219 | % corresponding to an integer register (i.e.~a \TeX{} count 220 | % register).\\ 221 | % \cs{c_empty_tl} is the constant~(|c_|) token list variable 222 | % that is always empty. 223 | % \end{quote} 224 | % 225 | % Now here is an example of a typical function name. 226 | % 227 | % \cs{seq_push:Nn} is the function which puts the token list specified 228 | % by its second argument onto the stack specified by its first argument. 229 | % The different natures of the two arguments are indicated by the~|:Nn| 230 | % suffix. The first argument must be a single token which \enquote{names} 231 | % the stack parameter: such single-token arguments are denoted~|N|. 232 | % The second argument is a normal \TeX{} \enquote{undelimited argument}, 233 | % which 234 | % may either be a single token or a balanced, brace-delimited token 235 | % list (which we shall here call a \textit{braced token list}): the~|n| 236 | % denotes such a \enquote{normal} argument form. The name of the function 237 | % indicates it belongs to the |seq| module. 238 | % 239 | % \subsection{Formal naming syntax} 240 | % 241 | % We shall now look in more detail at the syntax of these names. A 242 | % function name in \LaTeX3 has a name consisting of three parts: 243 | % \begin{quote} 244 | % |\|\meta{module}|_|\meta{description}|:|\meta{arg-spec} 245 | % \end{quote} 246 | % while a variable has (up to) four distinct parts to its name: 247 | % \begin{quote} 248 | % |\|\meta{scope}|_|\meta{module}|_|\meta{description}|_|\meta{type} 249 | % \end{quote} 250 | % 251 | % The syntax of all names contains 252 | % \begin{quote} 253 | % \meta{module} and \meta{description} 254 | % \end{quote} 255 | % these both give information about the command. 256 | % 257 | % A \emph{module} is a collection of closely related functions and 258 | % variables. Typical module names include~|int| for integer parameters 259 | % and related functions,~|seq| for sequences and~|box| for boxes. 260 | % 261 | % Packages providing new programming functionality will add new modules 262 | % as needed; the programmer can choose any unused name, consisting 263 | % of letters only, for a module. In general, the module name and module 264 | % prefix should be related: for example, the kernel module containing 265 | % \texttt{box} functions is called \texttt{l3box}. Module names and 266 | % programmers' contact details are listed in \pkg{l3prefixes.csv}. 267 | % 268 | % The \emph{description} gives more detailed information about the 269 | % function or parameter, and provides a unique name for it. It should 270 | % consist of letters and, possibly,~|_|~characters. In general, the 271 | % description should use |_| to divide up \enquote{words} or other easy to 272 | % follow parts of the name. For example, the \LaTeX3 kernel provides 273 | % \cs{if_cs_exist:N} which, as might be expected, tests if a command 274 | % name exists. 275 | % 276 | % Where functions for variable manipulation can perform assignments 277 | % either locally or globally, the latter case is indicated by the inclusion of 278 | % a |g| in the second part of the function name. Thus \cs{tl_set:Nn} is a local 279 | % function but \cs{tl_gset:Nn} acts globally. Functions of this type are 280 | % always documented together, and the scope of action may therefore be 281 | % inferred from the presence or absence of a |g|. See the next subsection for 282 | % more detail on variable scope. 283 | % 284 | % \subsubsection{Separating private and public material} 285 | % 286 | % One of the issues with the \TeX{} language is that it doesn't support 287 | % name spaces and encapsulation other than by convention. As a result 288 | % nearly every internal command in the \LaTeXe{} kernel has eventually 289 | % be used by extension packages as an entry point for modifications or 290 | % extensions. The consequences of this is that nowadays it is next to 291 | % impossible to change anything in the \LaTeXe{} kernel (even if it is 292 | % clearly just an internal command) without breaking something. 293 | % 294 | % In \pkg{expl3} we hope to improve this situation drastically by 295 | % clearly separating public interfaces (that extension packages can use 296 | % and rely on) and private functions and variables (that should not 297 | % appear outside of their module). There is (nearly) no way to enforce 298 | % this without severe computing overhead, so we implement it only 299 | % through a naming convention, and some support mechanisms. However, we 300 | % think that this naming convention is easy to understand and to follow, 301 | % so that we are confident that this will adopted and provides the 302 | % desired results. 303 | % 304 | % Functions created by a module may either be \enquote{public} (documented 305 | % with a defined interface) or \enquote{private} (to be used only within 306 | % that module, and thus not formally documented). It is important that 307 | % only documented interfaces are used; at the same time, it is necessary to 308 | % show within the name of a function or variable whether it is public 309 | % or private. 310 | % 311 | % To allow clear separation of these two cases, the following convention 312 | % is used. Private functions should be defined with |__| added to the beginning 313 | % of the module name. Thus 314 | % \begin{verbatim} 315 | % \module_foo:nnn 316 | % \end{verbatim} 317 | % is a public function which should be documented while 318 | % \begin{verbatim} 319 | % \__module_foo:nnn 320 | % \end{verbatim} 321 | % is private to the module, and should \emph{not} be used outside of that 322 | % module. 323 | % 324 | % In the same way, private variables should use two "__" at the start of the 325 | % module name, such that 326 | % \begin{verbatim} 327 | % \l_module_foo_tl 328 | % \end{verbatim} 329 | % is a public variable and 330 | % \begin{verbatim} 331 | % \l__module_foo_tl 332 | % \end{verbatim} 333 | % is private. 334 | % 335 | % \subsubsection{Using \texttt{@@} and \pkg{l3docstrip} to mark private code} 336 | % 337 | % The formal syntax for internal functions allows clear separation of public 338 | % and private code, but includes redundant information (every internal function 339 | % or variable includes \texttt{__\meta{module}}). To aid programmers, the 340 | % \pkg{l3docstrip} program introduces the syntax 341 | % \begin{quote} 342 | % \ttfamily 343 | % |%<@@=|\meta{module}|>| 344 | % \end{quote} 345 | % which then allows |@@| (and |_@@| in case of variables) to be used as 346 | % a place holder for \texttt{__\meta{module}} in code. Thus for example 347 | % \begin{verbatim} 348 | % %<@@=foo> 349 | % % \begin{macrocode} 350 | % \cs_new:Npn \@@_function:n #1 351 | % ... 352 | % \tl_new:N \l_@@_my_tl 353 | % % \end{macrocode} 354 | % \end{verbatim} 355 | % is converted by \pkg{l3docstrip} to 356 | % \begin{verbatim} 357 | % \cs_new:Npn \__foo_function:n #1 358 | % ... 359 | % \tl_new:N \l__foo_my_tl 360 | % \end{verbatim} 361 | % on extraction. As you can see both |_@@| and |@@| are mapped to 362 | % \texttt{__\meta{module}}, because we think that this helps to 363 | % distinguish variables from functions in the source when the |@@| 364 | % convention is used. 365 | % 366 | % \subsubsection{Variables: scope and type} 367 | % 368 | % The \meta{scope} part of the name describes how the variable can be 369 | % accessed. Variables are classified as local, global or constant. 370 | % This \emph{scope} type appears as a code at the beginning of the name; 371 | % the codes used are: 372 | % \begin{arg-description} 373 | % \item[c] constants (global variables whose value should not be 374 | % changed); 375 | % \item[g] variables whose value should only be set globally; 376 | % \item[l] variables whose value should only be set locally. 377 | % \end{arg-description} 378 | % 379 | % Separate functions are provided to assign data to local and global 380 | % variables; for example, \cs{tl_set:Nn} and \cs{tl_gset:Nn} respectively 381 | % set the value of a local or global \enquote{token list} variable. 382 | % Note that it is a poor \TeX{} practice to intermix local and global 383 | % assignments to a variable; otherwise you risk exhausting the save 384 | % stack.\footnote{See \emph{The \TeX{}book}, p.\,301, for further 385 | % information.} 386 | % 387 | % The \meta{type} is in the list of available 388 | % \emph{data-types};\footnote{Of course, if a totally new data type is 389 | % needed then this will not be the case. However, it is hoped that only 390 | % the kernel team will need to create new data types.} these include the 391 | % primitive \TeX{} data-types, such as the various registers, but to 392 | % these are added data-types built within the \LaTeX{} programming 393 | % system. 394 | % 395 | % The data types in \LaTeX3 are: 396 | % \begin{description} 397 | % \item[bool] either true or false (the \LaTeX3 implementation does 398 | % not use \tn{iftrue} or \tn{iffalse}); 399 | % \item[box] box register; 400 | % \item[clist] comma separated list; 401 | % \item[coffin] a \enquote{box with handles} --- a higher-level data 402 | % type for carrying out |box| alignment operations; 403 | % \item[dim] \enquote{rigid} lengths; 404 | % \item[fp] floating-point values; 405 | % \item[ior] an input stream (for reading from a file); 406 | % \item[iow] an output stream (for writing to a file); 407 | % \item[int] integer-valued count register; 408 | % \item[muskip] math mode \enquote{rubber} lengths; 409 | % \item[prop] property list; 410 | % \item[seq] sequence: a data-type used to implement lists (with 411 | % access at both ends) and stacks; 412 | % \item[skip] \enquote{rubber} lengths; 413 | % \item[str] \TeX{} strings: a special case of |tl| in which all 414 | % characters have category \enquote{other} (catcode~$12$), 415 | % other than spaces which are category \enquote{space} 416 | % (catcode~$10$); 417 | % \item[tl] \enquote{token list variables}: placeholders for token lists. 418 | % \end{description} 419 | % When the \meta{type} and \meta{module} are identical (as often happens in 420 | % the more basic modules) the \meta{module} part is often omitted for 421 | % aesthetic reasons. 422 | % 423 | % The name \enquote{token list} may cause confusion, and so some 424 | % background is useful. \TeX{} works with tokens and lists of tokens, 425 | % rather than characters. It provides two ways to store these token 426 | % lists: within macros and as token registers (|toks|). The 427 | % implementation in \LaTeX3 means that |toks| are not required, and that 428 | % all operations for storing tokens can use the |tl| variable type. 429 | % 430 | % Experienced \TeX{} programmers will notice that some of the variable 431 | % types listed are native \TeX{} registers whilst others are not. In 432 | % general, the underlying \TeX{} implementation for a data structure may 433 | % vary but the \emph{documented interface} will be stable. For example, 434 | % the |prop| data type was originally implemented as a |toks|, but 435 | % is currently built on top of the |tl| data structure. 436 | % 437 | % \subsubsection{Variables: guidance} 438 | % 439 | % Both comma lists and sequences have similar characteristics. 440 | % They both use special delimiters to mark out one entry from the 441 | % next, and are both accessible at both ends. In general, it is 442 | % easier to create comma lists `by hand' as they can be typed 443 | % in directly. User input often takes the form of a comma separated 444 | % list and so there are many cases where this is the obvious 445 | % data type to use. On the other hand, sequences use special internal 446 | % tokens to separate entries. This means that they can be used to 447 | % contain material that comma lists cannot (such as items that may 448 | % themselves contain commas!). In general, comma lists should be 449 | % preferred for creating fixed lists inside programs and for 450 | % handling user input where commas will not occur. On the other 451 | % hand, sequences should be used to store arbitrary lists of 452 | % data. 453 | % 454 | % \pkg{expl3} implements stacks using the sequence data structure. 455 | % Thus creating stacks involves first creating a sequence, and 456 | % then using the sequence functions which work in a stack manner 457 | % (\cs{seq_push:Nn}, \emph{etc}.). 458 | % 459 | % Due to the nature of the underlying \TeX{} implementation, it is 460 | % possible to assign values to token list variables and comma lists 461 | % without first declaring them. However, this is \emph{not supported 462 | % behavior}. The \LaTeX3 coding convention is that all variables must 463 | % be declared before use. 464 | % 465 | % The \pkg{expl3} package can be loaded with the \texttt{check-declarations} 466 | % option to verify that all variables are declared before use. This has 467 | % a performance implication and is therefore intended for testing during 468 | % development and not for use in production documents. 469 | % 470 | % \subsubsection{Functions: argument specifications} 471 | % 472 | % Function names end with an \meta{arg-spec} after a colon. This 473 | % gives an indication of the types of argument that a function takes, 474 | % and provides a convenient method of naming similar functions that 475 | % differ only in their argument forms (see the next section for 476 | % examples). 477 | % 478 | % The \meta{arg-spec} consists of a (possibly empty) list of letters, 479 | % each denoting one argument of the function. The letter, including 480 | % its case, conveys information about the type of argument required. 481 | % 482 | % All functions have a base form with arguments using one of the 483 | % following argument specifiers: 484 | % \begin{arg-description} 485 | % \item[n] Unexpanded token or braced token list.\\ 486 | % This is a standard \TeX{} undelimited macro argument. 487 | % \item[N] Single token (unlike~|n|, the argument must \emph{not} be 488 | % surrounded by braces).\\ 489 | % A typical example of a command taking an~|N| 490 | % argument is~|\cs_set|, in which the command being defined must be 491 | % unbraced. 492 | % \item[p] Primitive \TeX{} parameter specification.\\ 493 | % This can be something simple like~|#1#2#3|, but may use arbitrary 494 | % delimited argument syntax such as: |#1,#2\q_stop#3|. This is used 495 | % when defining functions. 496 | % \item[T,F] 497 | % These are special cases of~|n| arguments, used for the 498 | % true and false code in conditional commands. 499 | % \end{arg-description} 500 | % There are two other specifiers with more general meanings: 501 | % \begin{arg-description} 502 | % \item[D] This means: \textbf{Do not use}. This special case is used 503 | % for \TeX{} primitives. Programmers outside the kernel team should 504 | % not use these functions! 505 | % \item[w] This means that the argument syntax is \enquote{weird} in that it 506 | % does not follow any standard rule. It is used for functions with 507 | % arguments that take non standard forms: examples are \TeX{}-level 508 | % delimited arguments and the boolean tests needed after certain 509 | % primitive |\if|\ldots{} commands. 510 | % \end{arg-description} 511 | % 512 | % In case of |n| arguments that consist of a single token the 513 | % surrounding braces can be omitted in nearly all 514 | % situations---functions that force the use of braces even for single 515 | % token arguments are explicitly mentioned. However, programmers are 516 | % encouraged to always use braces around \texttt{n} arguments, as this 517 | % makes the relationship between function and argument clearer. 518 | % 519 | % Further argument specifiers are available as part of the expansion 520 | % control system. These are discussed in the next section. 521 | % 522 | % \section{Expansion control} 523 | % 524 | % Let's take a look at some typical operations one might want to 525 | % perform. Suppose we maintain a stack of open files and we use the 526 | % stack |\g_ior_file_name_seq| to keep track of them (\texttt{ior} is 527 | % the prefix used for the file reading module). The basic operation here 528 | % is to push a name onto this stack which could be done by the operation 529 | % \begin{quote} 530 | % \cs{seq_gpush:Nn} |\g_ior_file_name_seq {#1}| 531 | % \end{quote} 532 | % where |#1| is the filename. In other words, this operation would 533 | % push the file name as is onto the stack. 534 | % 535 | % However, we might face a situation where the filename is stored in 536 | % a variable of some sort, say |\l_ior_curr_file_tl|. In this case we 537 | % want to retrieve the value of the variable. If we simply use 538 | % \begin{quote} 539 | % \cs{seq_gpush:Nn} |\g_ior_file_name_seq| |\l_ior_curr_file_tl| 540 | % \end{quote} 541 | % we do not get the value of the variable pushed onto the stack, 542 | % only the variable name itself. Instead a suitable number of 543 | % \cs{exp_after:wN} would be necessary (together with extra braces) to 544 | % change the order of expansion,\footnote{\cs{exp_after:wN} is 545 | % the \LaTeX3 name for the \TeX{} \tn{expandafter} primitive.} \emph{i.e.} 546 | % \begin{quote} 547 | % \cs{exp_after:wN} \\ 548 | % | |\cs{seq_gpush:Nn} \\ 549 | % \cs{exp_after:wN} \\ 550 | % | \g_ior_file_name_seq| \\ 551 | % \cs{exp_after:wN} \\ 552 | % | { \l_ior_curr_file_tl }| 553 | % \end{quote} 554 | % 555 | % The above example is probably the simplest case but already shows 556 | % how the code changes to something difficult to understand. 557 | % Furthermore there is an assumption in this: that the storage bin 558 | % reveals its contents after exactly one expansion. Relying on this 559 | % means that you cannot do proper checking plus you have to know 560 | % exactly how a storage bin acts in order to get the correct number 561 | % of expansions. Therefore \LaTeX3 provides the programmer with a 562 | % general scheme that keeps the code compact and easy to understand. 563 | % 564 | % To denote that some argument to a function needs special treatment one 565 | % just uses different letters in the arg-spec part of the function to 566 | % mark the desired behavior. In the above example one would write 567 | % \begin{quote} 568 | % \cs{seq_gpush:NV} |\g_ior_file_name_seq \l_ior_curr_file_tl| 569 | % \end{quote} 570 | % to achieve the desired effect. Here the |V| (the second argument) 571 | % is for \enquote{retrieve the value of the variable} before passing it to 572 | % the base function. 573 | % 574 | % The following letters can be used to denote special treatment of 575 | % arguments before passing it to the base function: 576 | % \begin{description} 577 | % \item[c] Character string used as a command name.\\ The argument (a 578 | % token or braced token list) is \emph{fully expanded}; the result 579 | % must be a sequence of characters which is then used to construct a 580 | % command name (\emph{via}~\tn{csname} \ldots \tn{endcsname}). This 581 | % command name is a single token that is passed to the function as 582 | % the argument. Hence 583 | % \begin{quote} 584 | % \cs{seq_gpush:cV} |{ g_file_name_seq }| \cs{l_tmpa_tl} 585 | % \end{quote} 586 | % is equivalent to 587 | % \begin{quote} 588 | % \cs{seq_gpush:NV} |\g_file_name_seq| \cs{l_tmpa_tl}. 589 | % \end{quote} 590 | % Full expansion means that (a) the entire 591 | % argument must be expandable and (b) any variables are 592 | % converted to their content. So the preceding examples are also 593 | % equivalent to 594 | % \begin{quote} 595 | % \cs{tl_new:N} |\g_file_seq_name_tl| \\ 596 | % \cs{tl_gset:Nn} |\g_file_seq_name_tl { g_file_name_seq }| \\ 597 | % \cs{seq_gpush:cV} |{| \cs{tl_use:N} |\g_file_seq_name_tl }| \cs{l_tmpa_tl}. 598 | % \end{quote} 599 | % (Token list variables are expandable and we could omit the 600 | % accessor function \cs{tl_use:N}. Other variable types require the 601 | % appropriate \cs{\meta{var}_use:N} functions to be used in this 602 | % context.) 603 | % \item[V] Value of a variable.\\ 604 | % This means that the contents of the register in question is used 605 | % as the argument, be it an integer, a length-type register, a token 606 | % list variable or similar. The value is passed to the function as a 607 | % braced token list. Can be applied to variables which have a 608 | % \cs{\meta{var}_use:N} function (other than floating points and 609 | % boxes), and which therefore deliver a single \enquote{value}. 610 | % \item[v] Value of a register, constructed from a character string 611 | % used as a command name.\\ 612 | % This is a combination of |c| and |V| which first constructs a 613 | % control sequence from the argument and then passes the value of 614 | % the resulting register to the function. Can be applied to 615 | % variables which have a \cs{\meta{var}_use:N} function (other than 616 | % floating points and boxes), and which therefore deliver a single 617 | % \enquote{value}. 618 | % \item[x] Fully-expanded token or braced token list.\\ 619 | % This means that the argument is expanded as in the replacement 620 | % text of an~\tn{edef}, and the expansion is passed to the function as 621 | % a braced token list. Expansion takes place until only unexpandable 622 | % tokens are left. |x|-type arguments cannot be nested. 623 | % \item[o] One-level-expanded token or braced token list.\\ 624 | % This means that the argument is expanded one level, as by 625 | % \tn{expandafter}, and the expansion is passed to the function as a 626 | % braced token list. Note that if the original argument is a braced 627 | % token list then only the first token in that list is expanded. 628 | % In general, using \texttt{V} should be preferred to using 629 | % \texttt{o} for simple variable retrieval. 630 | % \item[f] Expanding the first token recursively in a braced token 631 | % list.\\ Almost the same as the |x| type except here the token list 632 | % is expanded fully until the first unexpandable token is found and 633 | % the rest is left unchanged. Note that if this function finds a 634 | % space at the beginning of the argument it gobbles it and does not 635 | % expand the next token. 636 | % \end{description} 637 | % 638 | % \subsection{Simpler means better} 639 | % 640 | % Anyone who programs in \TeX{} is frustratingly familiar with the 641 | % problem of arranging that arguments to functions are suitably expanded 642 | % before the function is called. To illustrate how expansion control 643 | % can bring instant relief to this problem we shall consider two 644 | % examples copied from \texttt{latex.ltx}. 645 | % 646 | % \begin{verbatim} 647 | % \global\expandafter\let 648 | % \csname\cf@encoding \string#1\expandafter\endcsname 649 | % \csname ?\string#1\endcsname 650 | % \end{verbatim} 651 | % This first piece of code is in essence simply a global \tn{let} whose 652 | % two arguments firstly have to be constructed before \tn{let} is 653 | % executed. The |#1| is a control sequence name such as 654 | % |\textcurrency|. The token to be defined is obtained by 655 | % concatenating the characters of the current font encoding stored in 656 | % |\cf@encoding|, which has to be fully expanded, and the name of the 657 | % symbol. The second token is the same except it uses the default 658 | % encoding |?|. The result is a mess of interwoven \tn{expandafter} 659 | % and \tn{csname} beloved of all \TeX{} programmers, and the code is 660 | % essentially unreadable. 661 | % 662 | % Using the conventions and functionality outlined here, the task would 663 | % be achieved with code such as this: 664 | % \begin{verbatim} 665 | % \cs_gset_eq:cc 666 | % { \cf@encoding \token_to_str:N #1 } { ? \token_to_str:N #1 } 667 | % \end{verbatim} 668 | % The command \cs{cs_gset_eq:cc} is a global~\tn{let} that generates 669 | % command names out of both of its arguments before making the 670 | % definition. This produces code that is far more readable and more 671 | % likely to be correct first time. (\cs{token_to_str:N} is the \LaTeX3 672 | % name for \tn{string}.) 673 | % 674 | % Here is the second example. 675 | % \begin{verbatim} 676 | % \expandafter 677 | % \in@ 678 | % \csname sym#3% 679 | % \expandafter 680 | % \endcsname 681 | % \expandafter 682 | % {% 683 | % \group@list}% 684 | % \end{verbatim} 685 | % This piece of code is part of the definition of another function. It 686 | % first produces two things: a token list, by expanding |\group@list| once; 687 | % and a token whose name comes from~`|sym#3|'. Then the function~\cs{in@} 688 | % is called and this tests if its first argument occurs in the token list 689 | % of its second argument. 690 | % 691 | % Again we can improve enormously on the code. First we shall rename 692 | % the function~\cs{in@}, which tests if its first argument appears 693 | % within its second argument, according to our conventions. Such a 694 | % function takes two normal \enquote{\texttt{n}} arguments and operates 695 | % on token lists: it might reasonably be named |\tl_test_in:nn|. Thus 696 | % the variant function we need would be defined with the appropriate 697 | % argument types and its name would be |\tl_test_in:cV|. Now this code 698 | % fragment would be simply: 699 | % \begin{verbatim} 700 | % \tl_test_in:cV { sym #3 } \group@list 701 | % \end{verbatim} 702 | % This code could be improved further by using a sequence |\l_group_seq| 703 | % rather than the bare token list |\group@list|. Note that, in addition 704 | % to the lack of \tn{expandafter}, the space after the~|}| is 705 | % silently ignored since all white space is ignored in this programming 706 | % environment. 707 | % 708 | % \subsection{New functions from old} 709 | % 710 | % For many common functions the \LaTeX3 kernel provides variants 711 | % with a range of argument forms, and similarly it is expected that 712 | % extension packages providing new functions will make them available in 713 | % all the commonly needed forms. 714 | % 715 | % However, there will be occasions where it is necessary to construct a 716 | % new such variant form; therefore the expansion module provides a 717 | % straightforward mechanism for the creation of functions with any 718 | % required argument type, starting from a function that takes \enquote{normal} 719 | % \TeX{} undelimited arguments. 720 | % 721 | % To illustrate this let us suppose you have a \enquote{base function} 722 | % |\demo_cmd:Nnn| that takes three normal arguments, and that you need 723 | % to construct the variant |\demo_cmd:cnx|, for which the first argument 724 | % is used to construct the \emph{name} of a command, whilst the third 725 | % argument must be fully expanded before being passed to 726 | % |\demo_cmd:Nnn|. 727 | % To produce the variant form from the base form, simply use this: 728 | % \begin{verbatim} 729 | % \cs_generate_variant:Nn \demo_cmd:Nnn { cnx } 730 | % \end{verbatim} 731 | % This defines the variant form so that you can then write, for example: 732 | % \begin{verbatim} 733 | % \demo_cmd:cnx { abc } { pq } { \rst \xyz } 734 | % \end{verbatim} 735 | % rather than \ldots\ well, something like this! 736 | % \begin{verbatim} 737 | % \def \tempa {{pq}}% 738 | % \edef \tempb {\rst \xyz}% 739 | % \expandafter 740 | % \demo@cmd:nnn 741 | % \csname abc% 742 | % \expandafter 743 | % \expandafter 744 | % \expandafter 745 | % \endcsname 746 | % \expandafter 747 | % \tempa 748 | % \expandafter 749 | % {% 750 | % \tempb 751 | % }% 752 | % \end{verbatim} 753 | % 754 | % Another example: you may wish to declare a function 755 | % |\demo_cmd_b:xcxcx|, a variant of an existing function 756 | % |\demo_cmd_b:nnnnn|, that fully 757 | % expands arguments 1,~3 and~5, and produces commands to pass as 758 | % arguments 2 and~4 using~\tn{csname}. 759 | % The definition you need is simply 760 | % \begin{verbatim} 761 | % \cs_generate_variant:Nn \demo_cmd_b:nnnnn { xcxcx } 762 | % \end{verbatim} 763 | % 764 | % This extension mechanism is written so that if the same new form of 765 | % some existing command is implemented by two extension packages then the 766 | % two definitions are identical and thus no conflict occurs. 767 | % 768 | % \section{The distribution} 769 | % 770 | % At present, the \pkg{expl3} modules are designed to be loaded on top 771 | % of \LaTeXe{}. In time, a \LaTeX3 format will be produced based on this 772 | % code. This allows the code to be used in \LaTeXe{} packages \emph{now} 773 | % while a stand-alone \LaTeX3 is developed. 774 | % 775 | % \begin{bfseries} 776 | % While \pkg{expl3} is still experimental, the bundle is now regarded 777 | % as broadly stable. The syntax conventions and functions provided 778 | % are now ready for wider use. There may still be changes to some 779 | % functions, but these will be minor when compared to the scope of 780 | % \pkg{expl3}. 781 | % \end{bfseries} 782 | % 783 | % New modules will be added to the distributed version of \pkg{expl3} 784 | % as they reach maturity. At present, the \pkg{expl3} bundle consists 785 | % of a number of modules, most of which are loaded by including the 786 | % line: 787 | % \begin{verbatim} 788 | % \RequirePackage{expl3} 789 | % \end{verbatim} 790 | % in a \LaTeXe{} package, class or other file. The \pkg{expl3} modules 791 | % regarded as stable, and therefore suitable for basing real code on, 792 | % are as follows: 793 | % 794 | % \begin{description} 795 | % \providecommand\explpkg[2]{\item[#1]#2} 796 | % \explpkg{l3basics}{ 797 | % This contains the basic definition modules used 798 | % by the other packages. 799 | % } 800 | % \explpkg{l3box}{ 801 | % Primitives for dealing with boxes. 802 | % } 803 | % \explpkg{l3clist}{ 804 | % Methods for manipulating comma-separated token lists. 805 | % } 806 | % \explpkg{l3coffins}{ 807 | % Augmented box constructs for alignment operations. 808 | % } 809 | % \explpkg{l3expan}{ 810 | % This is the argument expansion module discussed earlier in this 811 | % document. 812 | % } 813 | % \explpkg{l3int}{ 814 | % This implements the integer data-type \texttt{int}. 815 | % } 816 | % \explpkg{l3keys}{ 817 | % For processing lists of the form 818 | % \texttt{\{ key1=val1 , key2=val2 \}}, intended to work 819 | % as a \LaTeX3 version of \pkg{xkeyval}/\pkg{kvoptions}, although 820 | % with input syntax more like that of \pkg{pgfkeys}. 821 | % } 822 | % \explpkg{l3msg}{ 823 | % Communicating with the user: includes low-level hooks to allow 824 | % messages to be filtered (higher-level interface for filtering 825 | % to be written!). 826 | % } 827 | % \explpkg{l3names}{ 828 | % This sets up the basic naming scheme and renames all 829 | % the \TeX{} primitives. 830 | % } 831 | % \explpkg{l3prg}{ 832 | % Program control structures such as boolean data type |bool|, generic 833 | % do-while loops, and conditional flow. 834 | % } 835 | % \explpkg{l3prop}{ 836 | % This implements the data-type for \enquote{property lists} that are used, in 837 | % particular, for storing key/value pairs. 838 | % } 839 | % \explpkg{l3quark}{ 840 | % A \enquote{quark} is a command that is defined to expand to 841 | % itself! Therefore they must never be expanded as this would generate an 842 | % infinite recursion; they do however have many uses, \emph{e.g.}~as 843 | % special markers and delimiters within code. 844 | % } 845 | % \explpkg{l3seq}{ 846 | % This implements data-types such as queues and stacks. 847 | % } 848 | % \explpkg{l3skip}{ 849 | % Implements the \enquote{rubber length} datatype \texttt{skip}, the 850 | % \enquote{rigid length} datatype |dim|, and the math mode 851 | % \enquote{rubber length} datatype \texttt{muskip}. 852 | % } 853 | % \explpkg{l3tl}{ 854 | % This implements a basic data-type, called a \textit{token-list 855 | % variable} (|tl var.|), used for storing named token lists: these are 856 | % \TeX{} macros with no arguments. 857 | % } 858 | % \explpkg{l3token}{ 859 | % Analysing token lists and token streams, including peeking ahead to 860 | % see what's coming next and inspecting tokens to detect which kind 861 | % they are. 862 | % } 863 | % \end{description} 864 | % 865 | % \section{Moving from \LaTeXe{} to \LaTeX3} 866 | % 867 | % To help programmers to use \LaTeX3 code in existing \LaTeXe{} package, 868 | % some short notes on making the change are probably desirable. 869 | % Suggestions for inclusion here are welcome! Some of the following 870 | % is concerned with code, and some with coding style. 871 | % 872 | % \begin{itemize} 873 | % \item \pkg{expl3} is mainly focused on programming. This means that 874 | % some areas still require the use of \LaTeXe{} internal macros. 875 | % For example, you may well need \tn{@ifpackageloaded}, as there 876 | % is currently no native \LaTeX3 package loading module. 877 | % \item User level macros should be generated using the mechanism 878 | % available in the \pkg{xparse} package, which is part of the 879 | % \texttt{l3package} bundle, available from CTAN or the \LaTeX3 SVN 880 | % repository. 881 | % \item At an internal level, most functions should be generated 882 | % \tn{long} (using \cs{cs_new:Npn}) rather than \enquote{short} (using 883 | % \cs{cs_new_nopar:Npn}). 884 | % \item Where possible, declare all variables and functions (using 885 | % \cs{cs_new:Npn}, \cs{tl_new:N}, etc.) before use. 886 | % \item Prefer \enquote{higher-level} functions over \enquote{lower-level}, 887 | % where possible. So for example use \cs{cs_if_exist:N(TF)} and not 888 | % \cs{if_cs_exist:N}. 889 | % \item Use space to make code readable. In general, we recommend 890 | % a layout such as: 891 | % \begin{verbatim} 892 | % \cs_new:Npn \foo_bar:Nn #1#2 893 | % { 894 | % \cs_if_exist:NTF #1 895 | % { \__foo_bar:n {#2} } 896 | % { \__foo_bar:nn {#2} { literal } } 897 | % } 898 | % \end{verbatim} 899 | % where spaces are used around |{| and |}| except for isolated 900 | % |#1|, |#2|, \emph{etc.} 901 | % \item Put different code items on separate lines: readability is 902 | % much more useful than compactness. 903 | % \item Use long, descriptive names for functions and variables, 904 | % and for auxiliary functions use the parent function name plus 905 | % |aux|, |auxi|, |auxii| and so on. 906 | % \item If in doubt, ask the team via the LaTeX-L list: someone will 907 | % soon get back to you! 908 | % \end{itemize} 909 | % 910 | % \section{Load-time options for \pkg{expl3}} 911 | % 912 | % To support code authors, the \pkg{expl3} package for \LaTeXe{} includes 913 | % a small number of load-time options. These all work in a key--value 914 | % sense, recognising the \texttt{true} and \texttt{false} values. Giving 915 | % the option name alone is equivalent to using the option with the 916 | % \texttt{true} value. 917 | % 918 | % \DescribeOption{check-declarations} 919 | % All variables used in \LaTeX3 code should be declared. This is enforced 920 | % by \TeX{} for variable types based on \TeX{} registers, but not for those 921 | % which are constructed using macros as the underlying storage system. The 922 | % \texttt{check-declarations} option enables checking for all variable 923 | % assignments, issuing an error if any variables are assigned without being 924 | % initialised. See also \cs{debug_on:n} \texttt{\{check-declarations\}} 925 | % in \pkg{l3candidates} for finer control. 926 | % 927 | % \DescribeOption{log-functions} 928 | % The \texttt{log-functions} option is used to enable recording of every new 929 | % function name in the \texttt{.log} file. This is useful for debugging 930 | % purposes, as it means that there is a complete list of all functions 931 | % created by each module loaded (with the exceptions of a very small number 932 | % required by the bootstrap code for \LaTeX3). See also \cs{debug_on:n} 933 | % \texttt{\{log-functions\}} in \pkg{l3candidates} for finer control. 934 | % 935 | % \DescribeOption{enable-debug} 936 | % To allow more localized checking and logging than provided by 937 | % \texttt{check-declarations} and \texttt{log-functions}, \pkg{expl3} 938 | % provides a few \cs[no-index]{debug_\ldots{}} functions (described 939 | % elsewhere) that turn on the corresponding checks within a group. 940 | % These functions can only be used if \pkg{expl3} is loaded with the 941 | % \texttt{enable-debug} option. 942 | % 943 | % \DescribeOption{driver} 944 | % Selects the driver to be used for color, graphics and related operations that 945 | % are driver-dependent. Options available are 946 | % \begin{itemize}[font = \texttt] 947 | % \item[auto] Let \LaTeX3 determine the correct driver. With DVI output, this 948 | % selects the \texttt{dvips} back-end for \pdfTeX{} and \LuaTeX{}, and 949 | % \texttt{dvipdfmx} for \pTeX{} and \upTeX{}. This is the standard setting. 950 | % \item[latex2e] Use the \pkg{graphics} package to select the driver, rather 951 | % than \LaTeX3 code. 952 | % \item[dvips] Use the \texttt{dvips} driver. 953 | % \item[dvipdfmx] Use the \texttt{dvipdfmx} driver. 954 | % \item[dvisvgm] Use the \texttt{dvisvgm} driver. 955 | % \item[pdfmode] Use the \texttt{pdfmode} driver (direct PDF output from 956 | % \pdfTeX{} or \LuaTeX{}). 957 | % \item[xdvipdfmx] Use the \texttt{xdvipdfmx} driver (\XeTeX{} only). 958 | % \end{itemize} 959 | % 960 | % \section{Using \pkg{expl3} with formats other than \LaTeXe{}} 961 | % 962 | % As well as the \LaTeXe{} package \pkg{expl3}, there is also a 963 | % \enquote{generic} loader for the code, \texttt{expl3.tex}. This may be 964 | % loaded using the plain \TeX{} syntax 965 | % \begin{verbatim} 966 | % \input expl3-generic % 967 | % \end{verbatim} 968 | % This enables the programming layer to work with the other formats. 969 | % As no options are available loading in this way, the \enquote{native} 970 | % drivers are automatically used. If this \enquote{generic} loader is 971 | % used with \LaTeXe{} the code automatically switches to the appropriate 972 | % package route. 973 | % 974 | % After loading the programming layer using the generic interface, the 975 | % commands \cs{ExplSyntaxOn} and \cs{ExplSyntaxOff} and the code-level 976 | % functions and variables detailed in \pkg{interface3} are available. 977 | % Note that other \LaTeXe{} packages \emph{using} \pkg{expl3} are not 978 | % loadable: package loading is dependent on the \LaTeXe{} package-management 979 | % mechanism. 980 | % 981 | % \section{Engine/primitive requirements} 982 | % 983 | % To use \pkg{expl3} and the higher level packages provided by the 984 | % team, the minimal set of primitive requirements is currently 985 | % \begin{itemize} 986 | % \item All of those from \TeX90. 987 | % \item All of those from \eTeX{} \emph{excluding} |\TeXXeTstate|, 988 | % |\beginL|, |\beginR|, |\endL| and |\endR| (\emph{i.e.}~excluding 989 | % \TeX{}-\kern0pt-\reflectbox{\TeX{}}). 990 | % \item Functionality equivalent to the \pdfTeX{} primitive 991 | % |\pdfstrcmp|. 992 | % \end{itemize} 993 | % Any engine which defines |\pdfoutput| (\emph{i.e.}~allows direct production 994 | % of a PDF file without a DVI intermediate) must also provide |\pdfcolorstack|, 995 | % |\pdfliteral|, |\pdfmatrix|, |\pdfrestore| and |\pdfsave| or equivalent 996 | % functionality. Fully Unicode engines must provide a method for producing 997 | % character tokens in an expandable manner. 998 | % 999 | % Practically, these requirements are met by the engines 1000 | % \begin{itemize} 1001 | % \item \pdfTeX{} v1.40 or later. 1002 | % \item \XeTeX{} v0.99992 or later. 1003 | % \item \LuaTeX{} v0.76 or later. 1004 | % \item e-(u)\pTeX{} mid-2012 or later. 1005 | % \end{itemize} 1006 | % 1007 | % Additional modules beyond the core of \pkg{expl3} may require additional 1008 | % primitives. In particular, third-party authors may significantly 1009 | % extend the primitive coverage requirements. 1010 | % 1011 | % \section{The \LaTeX3 Project} 1012 | % 1013 | % Development of \LaTeX3 is carried out by The \LaTeX3 Project. Over time, 1014 | % the membership of this team has naturally varied. Currently, the members 1015 | % are 1016 | % \begin{itemize} 1017 | % \item Johannes Braams 1018 | % \item David Carlisle 1019 | % \item Robin Fairbairns 1020 | % \item Morten H{\o}gholm 1021 | % \item Bruno Le Floch 1022 | % \item Thomas Lotze 1023 | % \item Frank Mittelbach 1024 | % \item Will Robertson 1025 | % \item Chris Rowley 1026 | % \item Rainer Sch{\"o}pf 1027 | % \item Joseph Wright 1028 | % \end{itemize} 1029 | % while former members are 1030 | % \begin{itemize} 1031 | % \item Michael Downes 1032 | % \item Denys Duchier 1033 | % \item Alan Jeffrey 1034 | % \item Martin Schr{\"o}der 1035 | % \end{itemize} 1036 | % 1037 | % \begin{thebibliography}{1} 1038 | % 1039 | % \bibitem{A-W:K-TB} 1040 | % Donald E Knuth 1041 | % \newblock \emph{The \TeX{}book}. 1042 | % \newblock Addison-Wesley, Reading, Massachusetts, 1984. 1043 | % 1044 | % \bibitem{A-W:GMS94} 1045 | % Goossens, Mittelbach and Samarin. 1046 | % \newblock \emph{ The \LaTeX{} Companion}. 1047 | % \newblock Addison-Wesley, Reading, Massachusetts, 1994. 1048 | % 1049 | % \bibitem{A-W:LLa94} 1050 | % Leslie Lamport. 1051 | % \newblock \emph{\LaTeX{}: A Document Preparation System}. 1052 | % \newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994. 1053 | % 1054 | % \bibitem{tub:MR97-1} 1055 | % Frank Mittelbach and Chris Rowley. 1056 | % \newblock \enquote{The \LaTeX3 Project}. 1057 | % \newblock \emph{TUGboat}, 1058 | % Vol.\,18, No.\,3, pp.\,195--198, 1997. 1059 | % 1060 | % \end{thebibliography} 1061 | % 1062 | % \end{documentation} 1063 | % 1064 | % \begin{implementation} 1065 | % 1066 | % \section{\pkg{expl3} implementation} 1067 | % 1068 | % The implementation here covers several things. There are two 1069 | % \enquote{loaders} to define: the parts of the code that are specific to 1070 | % \LaTeXe{} or to non-\LaTeXe{} formats. These have to cover the same 1071 | % concepts as each other but in rather different ways: as a result, much 1072 | % of the code is given in separate blocks. There is also a short piece of 1073 | % code for the start of the \enquote{payload}: this is to ensure that 1074 | % loading is always done in the right way. 1075 | % 1076 | % \subsection{Loader interlock} 1077 | % 1078 | % A short piece of set up to check that the loader and \enquote{payload} 1079 | % versions match. 1080 | % 1081 | % \begin{macro}{\ExplLoaderFileDate} 1082 | % As DocStrip is used to generate \cs{ExplFileDate} 1083 | % for all files from the same source, it has to match. Thus the loaders 1084 | % simply save this information with a new name. 1085 | % \begin{macrocode} 1086 | %<*loader> 1087 | \let\ExplLoaderFileDate\ExplFileDate 1088 | % 1089 | % \end{macrocode} 1090 | % \end{macro} 1091 | % 1092 | % The interlock test itself is simple: \cs{ExplLoaderFileDate} must be 1093 | % defined and identical to \cs{ExplFileDate}. As this has to work for 1094 | % both \LaTeXe{} and other formats, there is some auto-detection involved. 1095 | % (Done this way avoids having two very similar blocks for \LaTeXe{} and 1096 | % other formats.) 1097 | % \begin{macrocode} 1098 | %<*!loader> 1099 | \begingroup 1100 | \def\next{\endgroup}% 1101 | \expandafter\ifx\csname PackageError\endcsname\relax 1102 | \begingroup 1103 | \def\next{\endgroup\endgroup}% 1104 | \def\PackageError#1#2#3% 1105 | {% 1106 | \endgroup 1107 | \errhelp{#3}% 1108 | \errmessage{#1 Error: #2!}% 1109 | }% 1110 | \fi 1111 | \expandafter\ifx\csname ExplLoaderFileDate\endcsname\relax 1112 | \def\next 1113 | {% 1114 | \PackageError{expl3}{No expl3 loader detected} 1115 | {% 1116 | You have attempted to use the expl3 code directly rather than using 1117 | the correct loader. Loading of expl3 will abort. 1118 | }% 1119 | \endgroup 1120 | \endinput 1121 | } 1122 | \else 1123 | \ifx\ExplLoaderFileDate\ExplFileDate 1124 | \else 1125 | \def\next 1126 | {% 1127 | \PackageError{expl3}{Mismatched expl3 files detected} 1128 | {% 1129 | You have attempted to load expl3 with mismatched files: 1130 | probably you have one or more files 'locally installed' which 1131 | are in conflict. Loading of expl3 will abort. 1132 | }% 1133 | \endgroup 1134 | \endinput 1135 | }% 1136 | \fi 1137 | \fi 1138 | \next 1139 | % 1140 | % \end{macrocode} 1141 | % 1142 | % A reload test for the payload, just in case. 1143 | % \begin{macrocode} 1144 | %<*!loader> 1145 | \begingroup\expandafter\expandafter\expandafter\endgroup 1146 | \expandafter\ifx\csname ver@expl3-code.tex\endcsname\relax 1147 | \expandafter\edef\csname ver@expl3-code.tex\endcsname 1148 | {% 1149 | \ExplFileDate\space 1150 | L3 programming layer 1151 | }% 1152 | \else 1153 | \expandafter\endinput 1154 | \fi 1155 | % 1156 | % \end{macrocode} 1157 | % 1158 | % All good: log the version of the code used (for log completeness). As this 1159 | % is more-or-less \cs{ProvidesPackage} without a separate file and as this also 1160 | % needs to work without \LaTeXe{}, just write the information directly to the 1161 | % log. 1162 | % \begin{macrocode} 1163 | %<*!loader> 1164 | \immediate\write-1 % 1165 | {% 1166 | Package: expl3 1167 | \ExplFileDate\space 1168 | L3 programming layer (code)% 1169 | }% 1170 | % 1171 | % \end{macrocode} 1172 | % 1173 | % \subsection{\LaTeXe{} loader} 1174 | % 1175 | % \begin{macrocode} 1176 | %<*package&loader> 1177 | % \end{macrocode} 1178 | % 1179 | % Identify the package. 1180 | % \begin{macrocode} 1181 | \ProvidesPackage{expl3} 1182 | [% 1183 | \ExplFileDate\space 1184 | L3 programming layer (loader) 1185 | ]% 1186 | % \end{macrocode} 1187 | % 1188 | % \begin{macro}[int]{\expl@create@bool@option} 1189 | % \begin{variable}[int] 1190 | % { 1191 | % \l@expl@check@declarations@bool , 1192 | % \l@expl@log@functions@bool , 1193 | % \l@expl@enable@debug@bool 1194 | % } 1195 | % \begin{variable}[int]{\l@expl@options@clist} 1196 | % Options to be set up. These have to be done by hand as there is no 1197 | % \pkg{expl3} yet: the logging option is needed before loading 1198 | % \pkg{l3basics}! Only a minimal set of options are handled here: 1199 | % others are left for a proper key--value approach once the kernel is 1200 | % loaded. After processing the options we set the 1201 | % \texttt{enable-debug} boolean so that the options 1202 | % \texttt{check-declarations} and \texttt{log-functions} imply 1203 | % \texttt{enable-debug}: otherwise the necessary debugging code would 1204 | % not be set up properly. 1205 | % \begin{macrocode} 1206 | \newcommand\expl@create@bool@option[2]% 1207 | {% 1208 | \DeclareOption{#1}{\chardef #2=1 }% 1209 | \DeclareOption{#1=true}{\chardef #2=1 }% 1210 | \DeclareOption{#1=false}{\chardef #2=0 }% 1211 | \newcommand*#2{}% 1212 | \chardef #2=0 % 1213 | }% 1214 | \expl@create@bool@option{check-declarations}\l@expl@check@declarations@bool 1215 | \expl@create@bool@option{log-functions}\l@expl@log@functions@bool 1216 | \expl@create@bool@option{enable-debug}\l@expl@enable@debug@bool 1217 | \let\expl@create@bool@option\@undefined 1218 | \chardef\l@expl@enable@debug@bool=0 % 1219 | \newcommand*\l@expl@options@clist{}% 1220 | \DeclareOption* 1221 | {% 1222 | \ifx\l@expl@options@clist\@empty 1223 | \let\l@expl@options@clist\CurrentOption 1224 | \else 1225 | \expandafter\expandafter\expandafter\def 1226 | \expandafter\expandafter\expandafter\l@expl@options@clist 1227 | \expandafter\expandafter\expandafter 1228 | {\expandafter\l@expl@options@clist\expandafter,\CurrentOption} 1229 | \fi 1230 | }% 1231 | \ProcessOptions\relax 1232 | \ifodd\l@expl@check@declarations@bool 1233 | \chardef\l@expl@enable@debug@bool=1 % 1234 | \fi 1235 | \ifodd\l@expl@log@functions@bool 1236 | \chardef\l@expl@enable@debug@bool=1 % 1237 | \fi 1238 | % \end{macrocode} 1239 | % \end{variable} 1240 | % \end{variable} 1241 | % \end{macro} 1242 | % 1243 | % \begin{macro}{\GetIdInfo} 1244 | % This is implemented right at the start of \texttt{l3bootstrap.dtx}. 1245 | % \end{macro} 1246 | % 1247 | % \begin{macro}{\ProvidesExplPackage, \ProvidesExplClass, \ProvidesExplFile} 1248 | % For other packages and classes building on this one it is convenient 1249 | % not to need \cs{ExplSyntaxOn} each time. 1250 | % \begin{macrocode} 1251 | \protected\def\ProvidesExplPackage#1#2#3#4% 1252 | {% 1253 | \ProvidesPackage{#1}[#2 \ifx\relax#3\relax\else v#3\space\fi #4]% 1254 | \ExplSyntaxOn 1255 | }% 1256 | \protected\def\ProvidesExplClass#1#2#3#4% 1257 | {% 1258 | \ProvidesClass{#1}[#2 \ifx\relax#3\relax\else v#3\space\fi #4]% 1259 | \ExplSyntaxOn 1260 | }% 1261 | \protected\def\ProvidesExplFile#1#2#3#4% 1262 | {% 1263 | \ProvidesFile{#1}[#2 \ifx\relax#3\relax\else v#3\space\fi #4]% 1264 | \ExplSyntaxOn 1265 | }% 1266 | % \end{macrocode} 1267 | % \end{macro} 1268 | % 1269 | % Load the business end: this leaves \cs{expl3} syntax on. 1270 | % \begin{macrocode} 1271 | \input{expl3-code.tex}% 1272 | % \end{macrocode} 1273 | % 1274 | % A check that the bootstrap code did not abort loading: if it did, 1275 | % bail out silently here. 1276 | % \begin{macrocode} 1277 | \begingroup\expandafter\expandafter\expandafter\endgroup 1278 | \expandafter\ifx\csname tex\string _let:D\endcsname\relax 1279 | \expandafter\endinput 1280 | \fi 1281 | % \end{macrocode} 1282 | % 1283 | % \begin{macro}{\color} 1284 | % The \cs{color} macro must be defined for showing coffin poles, so 1285 | % a no-op version is provided here. 1286 | % \begin{macrocode} 1287 | \AtBeginDocument 1288 | { 1289 | \cs_if_exist:NF \color 1290 | { \DeclareRobustCommand \color [2] [ ] { } } 1291 | } 1292 | % \end{macrocode} 1293 | % \end{macro} 1294 | % 1295 | % \begin{variable}{\l__expl_driver_tl} 1296 | % \begin{variable}{\l__expl_native_drivers_bool} 1297 | % With the code now loaded, options can be handled using a real key--value 1298 | % interpreter. The \enquote{faked} options are also included so that any 1299 | % erroneous input is mopped up (\emph{e.g.}~\texttt{log-function = 1300 | % foo}). The checks on driver choice are set up here, so when actually 1301 | % the driver it's a straight forward operation. 1302 | % \begin{macrocode} 1303 | \__kernel_msg_new:nnnn { expl } { wrong-driver } 1304 | { Driver~request~inconsistent~with~engine:~using~'#2'~driver. } 1305 | { 1306 | You~have~requested~driver~'#1',~but~this~is~not~suitable~for~use~with~the~ 1307 | active~engine.~LaTeX3~will~use~the~'#2'~driver~instead. 1308 | } 1309 | \tl_new:N \l__expl_driver_tl 1310 | \keys_define:nn { expl } 1311 | { 1312 | driver .choice:, 1313 | driver / auto .code:n = 1314 | { 1315 | \tl_set:Nx \l__expl_driver_tl 1316 | { 1317 | \sys_if_engine_xetex:TF 1318 | { xdvipdfmx } 1319 | { 1320 | \sys_if_output_pdf:TF 1321 | { pdfmode } 1322 | { 1323 | \bool_lazy_or:nnTF 1324 | { \sys_if_engine_pdftex_p: } 1325 | { \sys_if_engine_luatex_p: } 1326 | { dvips } 1327 | { dvipdfmx } 1328 | } 1329 | } 1330 | } 1331 | }, 1332 | driver / dvipdfmx .code:n = 1333 | { 1334 | \tl_set:Nn \l__expl_driver_tl { dvipdfmx } 1335 | \sys_if_engine_xetex:TF 1336 | { 1337 | \__kernel_msg_error:nnnn { expl } { wrong-driver } 1338 | { dvipdfmx } { xdvipdfmx } 1339 | \tl_set:Nn \l__expl_driver_tl { xdvipdfmx } 1340 | } 1341 | { 1342 | \sys_if_output_pdf:T 1343 | { 1344 | \__kernel_msg_error:nnnn { expl } { wrong-driver } 1345 | { dvipdfmx } { pdfmode } 1346 | \tl_set:Nn \l__expl_driver_tl { pdfmode } 1347 | } 1348 | } 1349 | }, 1350 | driver / dvips .code:n = 1351 | { 1352 | \tl_set:Nn \l__expl_driver_tl { dvips } 1353 | \sys_if_engine_xetex:TF 1354 | { 1355 | \__kernel_msg_error:nnnn { expl } { wrong-driver } 1356 | { dvips } { xdvipdfmx } 1357 | \tl_set:Nn \l__expl_driver_tl { xdvipdfmx } 1358 | } 1359 | { 1360 | \sys_if_output_pdf:T 1361 | { 1362 | \__kernel_msg_error:nnnn { expl } { wrong-driver } 1363 | { dvips } { pdfmode } 1364 | \tl_set:Nn \l__expl_driver_tl { pdfmode } 1365 | } 1366 | } 1367 | }, 1368 | driver / dvisvgm .code:n = 1369 | { 1370 | \tl_set:Nn \l__expl_driver_tl { dvisvgm } 1371 | \sys_if_engine_xetex:TF 1372 | { 1373 | \__kernel_msg_error:nnnn { expl } { wrong-driver } 1374 | { dvips } { xdvipdfmx } 1375 | \tl_set:Nn \l__expl_driver_tl { xdvipdfmx } 1376 | } 1377 | { 1378 | \sys_if_output_pdf:T 1379 | { 1380 | \__kernel_msg_error:nnnn { expl } { wrong-driver } 1381 | { dvips } { pdfmode } 1382 | \tl_set:Nn \l__expl_driver_tl { pdfmode } 1383 | } 1384 | } 1385 | }, 1386 | driver / latex2e .code:n = 1387 | { \tl_set:Nn \l__expl_driver_tl { latex2e } }, 1388 | driver / pdfmode .code:n = 1389 | { 1390 | \tl_set:Nn \l__expl_driver_tl { pdfmode } 1391 | \sys_if_engine_xetex:TF 1392 | { 1393 | \__kernel_msg_error:nnnn { expl } { wrong-driver } 1394 | { pdfmode } { xdvipdfmx } 1395 | \tl_set:Nn \l__expl_driver_tl { xdvipdfmx } 1396 | } 1397 | { 1398 | \sys_if_output_pdf:F 1399 | { 1400 | \__kernel_msg_error:nnnn { expl } { wrong-driver } 1401 | { pdfmode } { dvips } 1402 | \tl_set:Nn \l__expl_driver_tl { dvips } 1403 | } 1404 | } 1405 | }, 1406 | driver / xdvipdfmx .code:n = 1407 | { 1408 | \tl_set:Nn \l__expl_driver_tl { xdvipdfmx } 1409 | \sys_if_engine_xetex:F 1410 | { 1411 | \sys_if_output_pdf:TF 1412 | { 1413 | \__kernel_msg_error:nnnn { expl } { wrong-driver } 1414 | { xdvipdfmx } { pdfmode } 1415 | \tl_set:Nn \l__expl_driver_tl { pdfmode } 1416 | } 1417 | { 1418 | \__kernel_msg_error:nnnn { expl } { wrong-driver } 1419 | { xdvipdfmx } { dvips } 1420 | \tl_set:Nn \l__expl_driver_tl { dvips } 1421 | } 1422 | } 1423 | }, 1424 | driver .initial:n = { auto } , 1425 | native-drivers .choice:, 1426 | native-drivers .default:n = { true }, 1427 | native-drivers / false .meta:n = { driver = latex2e }, 1428 | native-drivers / true .meta:n = { driver = auto } 1429 | } 1430 | % \end{macrocode} 1431 | % Mop up any incorrect settings for the other options. 1432 | % \begin{macrocode} 1433 | \keys_define:nn { expl } 1434 | { 1435 | check-declarations .bool_set:N = \l@expl@check@declarations@bool, 1436 | log-functions .bool_set:N = \l@expl@log@functions@bool 1437 | } 1438 | \keys_set:nV { expl } \l@expl@options@clist 1439 | % \end{macrocode} 1440 | % \end{variable} 1441 | % \end{variable} 1442 | % 1443 | % \begin{macro} 1444 | % { 1445 | % \box_rotate:Nn, 1446 | % \box_resize_to_wd_and_ht_plus_dp:Nnn, 1447 | % \box_resize_to_ht_plus_dp:Nn, 1448 | % \box_resize_to_wd:Nn, 1449 | % \box_scale:Nnn 1450 | % } 1451 | % For the \LaTeXe{} drivers, 1452 | % alter various definitions to use the \pkg{graphics} package 1453 | % instead. The package is loaded right at the start of the hook 1454 | % as there is otherwise a potential issue with \pkg{(x)color}: see 1455 | % \url{http://groups.google.com/group/comp.text.tex/msg/c9de8913c756ef4c}. 1456 | % \begin{macrocode} 1457 | \str_if_eq:VnTF \l__expl_driver_tl { latex2e } 1458 | { 1459 | \tl_gput_left:Nn \@begindocumenthook { \RequirePackage { graphics } } 1460 | \__kernel_msg_new:nnnn { box } { clipping-not-available } 1461 | { Box~clipping~not~available. } 1462 | { 1463 | The~\box_clip:N~function~is~only~available~when~loading~expl3~ 1464 | with~the~"native-drivers"~option. 1465 | } 1466 | \cs_set_protected:Npn \box_clip:N #1 1467 | { 1468 | \hbox_set:Nn #1 { \box_use:N #1 } 1469 | \__kernel_msg_error:nn { box } { clipping-not-available } 1470 | } 1471 | \cs_set_protected:Npn \box_rotate:Nn #1#2 1472 | { \hbox_set:Nn #1 { \rotatebox {#2} { \box_use:N #1 } } } 1473 | \cs_set_protected:Npn \box_resize_to_wd_and_ht_plus_dp:Nnn #1#2#3 1474 | { 1475 | \hbox_set:Nn #1 1476 | { 1477 | \resizebox * 1478 | { \dim_eval:n {#2} } 1479 | { \dim_eval:n {#3} } 1480 | { \box_use:N #1 } 1481 | } 1482 | } 1483 | \cs_set_protected:Npn \box_resize_to_ht_plus_dp:Nn #1#2 1484 | { 1485 | \hbox_set:Nn #1 1486 | { 1487 | \resizebox * { ! } { \dim_eval:n {#2} } 1488 | { \box_use:N #1 } 1489 | } 1490 | } 1491 | \cs_set_protected:Npn \box_resize_to_wd:Nn #1#2 1492 | { 1493 | \hbox_set:Nn #1 1494 | { 1495 | \resizebox * { \dim_eval:n {#2} } { ! } 1496 | { \box_use:N #1 } 1497 | } 1498 | } 1499 | \cs_set_protected:Npn \__box_scale_aux:N #1 1500 | { 1501 | \exp_last_unbraced:Nx \scalebox 1502 | { { \fp_use:N \l__box_scale_x_fp } [ \fp_use:N \l__box_scale_y_fp ] } 1503 | { \box_use:N #1 } 1504 | } 1505 | \cs_set_protected:Npn \color_ensure_current: { \set@color } 1506 | } 1507 | % \end{macrocode} 1508 | % \end{macro} 1509 | % For native drivers, just load the appropriate file. As \cs{expl3} syntax 1510 | % is already on and the full mechanism is only engaged at the end of the 1511 | % loader, \cs{ProvidesExplFile} is temporarily redefined here. 1512 | % \begin{macrocode} 1513 | { 1514 | \group_begin: 1515 | \cs_set_protected:Npn \ProvidesExplFile 1516 | { 1517 | \char_set_catcode_space:n { `\ } 1518 | \ProvidesExplFileAux 1519 | } 1520 | \cs_set_protected:Npn \ProvidesExplFileAux #1#2#3#4 1521 | { 1522 | \group_end: 1523 | \ProvidesFile {#1} [ #2~v#3~#4 ] 1524 | } 1525 | \tl_const:Nn \c__expl_def_ext_tl { def } 1526 | \@onefilewithoptions { l3 \l__expl_driver_tl } [ ] [ ] \c__expl_def_ext_tl 1527 | } 1528 | % \end{macrocode} 1529 | % 1530 | % \begin{macro}{\@pushfilename, \@popfilename} 1531 | % \begin{macro}{\__expl_status_pop:w} 1532 | % The idea here is to use \LaTeXe{}'s \tn{@pushfilename} and 1533 | % \tn{@popfilename} to track the current syntax status. This can be 1534 | % achieved by saving the current status flag at each push to a stack, 1535 | % then recovering it at the pop stage and checking if the code 1536 | % environment should still be active. 1537 | % \begin{macrocode} 1538 | \tl_put_left:Nn \@pushfilename 1539 | { 1540 | \exp_args:Nx \__kernel_file_input_push:n 1541 | { 1542 | \tl_to_str:N \@currname 1543 | \tl_to_str:N \@currext 1544 | } 1545 | \tl_put_left:Nx \l__expl_status_stack_tl 1546 | { 1547 | \bool_if:NTF \l__kernel_expl_bool 1548 | { 1 } 1549 | { 0 } 1550 | } 1551 | \ExplSyntaxOff 1552 | } 1553 | \tl_put_right:Nn \@pushfilename { \@pushfilenameaux } 1554 | % \end{macrocode} 1555 | % This bit of trickery is needed to grab the name of the file being loaded 1556 | % so we can record it. 1557 | % \begin{macrocode} 1558 | \cs_set_protected:Npn \@pushfilenameaux #1#2#3 1559 | { 1560 | \str_gset:Nn \g_file_curr_name_str {#3} 1561 | #1 #2 {#3} 1562 | } 1563 | \tl_put_right:Nn \@popfilename 1564 | { 1565 | \__kernel_file_input_pop: 1566 | \tl_if_empty:NTF \l__expl_status_stack_tl 1567 | { \ExplSyntaxOff } 1568 | { \exp_after:wN \__expl_status_pop:w \l__expl_status_stack_tl \q_stop } 1569 | } 1570 | % \end{macrocode} 1571 | % The pop auxiliary function removes the first item from the stack, 1572 | % saves the rest of the stack and then does the test. The flag here 1573 | % is not a proper \texttt{bool}, so a low-level test is used. 1574 | % \begin{macrocode} 1575 | \cs_new_protected:Npn \__expl_status_pop:w #1#2 \q_stop 1576 | { 1577 | \tl_set:Nn \l__expl_status_stack_tl {#2} 1578 | \int_if_odd:nTF {#1} 1579 | { \ExplSyntaxOn } 1580 | { \ExplSyntaxOff } 1581 | } 1582 | % \end{macrocode} 1583 | % \end{macro} 1584 | % \end{macro} 1585 | % 1586 | % \begin{variable}{\l__expl_status_stack_tl} 1587 | % As \pkg{expl3} itself cannot be loaded with the code environment 1588 | % already active, at the end of the package \cs{ExplSyntaxOff} can 1589 | % safely be called. 1590 | % \begin{macrocode} 1591 | \tl_new:N \l__expl_status_stack_tl 1592 | \tl_set:Nn \l__expl_status_stack_tl { 0 } 1593 | % \end{macrocode} 1594 | % \end{variable} 1595 | % 1596 | % \begin{macrocode} 1597 | % 1598 | % \end{macrocode} 1599 | % 1600 | % \subsection{Generic loader} 1601 | % 1602 | % \begin{macrocode} 1603 | %<*generic> 1604 | % \end{macrocode} 1605 | % 1606 | % The generic loader starts with a test to ensure that the current format is 1607 | % not \LaTeXe{}! 1608 | % \begin{macrocode} 1609 | \begingroup 1610 | \def\tempa{LaTeX2e}% 1611 | \def\next{}% 1612 | \ifx\fmtname\tempa 1613 | \def\next 1614 | {% 1615 | \PackageInfo{expl3}{Switching from generic to LaTeX2e loader}% 1616 | % \end{macrocode} 1617 | % The \cs{relax} stops \cs{RequirePackage} from scanning for a date 1618 | % argument. Putting \tn{endinput} \emph{after} loading the package is 1619 | % crucial, as otherwise \tn{endinput} would close the file 1620 | % \file{expl3.sty} at the end of its first line: indeed, as long as 1621 | % \file{expl3.sty} is open it is impossible to close the file 1622 | % \file{expl3-generic.tex}. 1623 | % \begin{macrocode} 1624 | \RequirePackage{expl3}\relax \endinput 1625 | }% 1626 | \fi 1627 | \expandafter\endgroup 1628 | \next 1629 | % \end{macrocode} 1630 | % 1631 | % Reload check and identify the package: 1632 | % no \LaTeXe{} mechanism so this is all pretty basic. 1633 | % \begin{macrocode} 1634 | \begingroup\expandafter\expandafter\expandafter\endgroup 1635 | \expandafter\ifx\csname ver@expl3-generic.tex\endcsname\relax 1636 | \else 1637 | \immediate\write-1 1638 | {% 1639 | Package expl3 Info: The package is already loaded.% 1640 | }% 1641 | \expandafter\endinput 1642 | \fi 1643 | \immediate\write-1 1644 | {% 1645 | Package: expl3 1646 | \ExplFileDate\space 1647 | L3 programming layer (loader)% 1648 | }% 1649 | \expandafter\edef\csname ver@expl3-generic.tex\endcsname 1650 | {\ExplFileDate\space L3 programming layer}% 1651 | % \end{macrocode} 1652 | % 1653 | % \begin{variable}[int]{\l@expl@tidy@tl} 1654 | % Save the category code of |@| and then set it to \enquote{letter}. 1655 | % \begin{macrocode} 1656 | \expandafter\edef\csname l@expl@tidy@tl\endcsname 1657 | {% 1658 | \catcode64=\the\catcode64\relax 1659 | \let\expandafter\noexpand\csname l@expl@tidy@tl\endcsname 1660 | \noexpand\undefined 1661 | }% 1662 | \catcode64=11 % 1663 | % \end{macrocode} 1664 | % \end{variable} 1665 | % 1666 | % \begin{variable}[int] 1667 | % { 1668 | % \l@expl@check@declarations@bool , 1669 | % \l@expl@log@functions@bool , 1670 | % \l@expl@enable@debug@bool 1671 | % } 1672 | % In generic mode, there is no convenient option handling and so instead 1673 | % the two variables are defined to do nothing. 1674 | % Appropriate value before input of the loader. 1675 | % \begin{macrocode} 1676 | \chardef \l@expl@check@declarations@bool = 0 % 1677 | \chardef \l@expl@log@functions@bool = 0 % 1678 | \chardef \l@expl@enable@debug@bool = 0 % 1679 | % \end{macrocode} 1680 | % \end{variable} 1681 | % 1682 | % \begin{macro}{\AtBeginDocument} 1683 | % \begin{macro}[int]{\expl@AtBeginDocument} 1684 | % There are a few uses of \cs{AtBeginDocument} in the package code: the 1685 | % easiest way around that is to simply do nothing for these. As 1686 | % bundles such as \pkg{miniltx} may have defined \cs{AtBeginDocument} 1687 | % any existing definition is saved for restoration after the payload. 1688 | % \begin{macrocode} 1689 | \let\expl@AtBeginDocument\AtBeginDocument 1690 | \def\AtBeginDocument#1{}% 1691 | \expandafter\def\expandafter\l@expl@tidy@tl\expandafter 1692 | {% 1693 | \l@expl@tidy@tl 1694 | \let\AtBeginDocument\expl@AtBeginDocument 1695 | \let\expl@AtBeginDocument\undefined 1696 | }% 1697 | % \end{macrocode} 1698 | % \end{macro} 1699 | % \end{macro} 1700 | % 1701 | % Load the business end: this leaves \cs{expl3} syntax on. 1702 | % \begin{macrocode} 1703 | \input expl3-code.tex % 1704 | % \end{macrocode} 1705 | % 1706 | % A check that the bootstrap code did not abort loading: if it did, 1707 | % bail out silently here. 1708 | % \begin{macrocode} 1709 | \begingroup\expandafter\expandafter\expandafter\endgroup 1710 | \expandafter\ifx\csname tex\string _let:D\endcsname\relax 1711 | \expandafter\endinput 1712 | \fi 1713 | % \end{macrocode} 1714 | % 1715 | % For driver loading in generic mode, there are no options: pick the most 1716 | % appropriate case! To allow this loading to take place a temporary 1717 | % definition of \cs{ProvidesExplFile} is provided 1718 | % \begin{macrocode} 1719 | \cs_set_protected:Npn \ProvidesExplFile 1720 | { 1721 | \group_begin: 1722 | \char_set_catcode_space:n { `\ } 1723 | \ProvidesExplFileAux 1724 | } 1725 | \cs_set_protected:Npn \ProvidesExplFileAux #1#2#3#4 1726 | { 1727 | \group_end: 1728 | \iow_log:x { File:~#1~#2~v#3~#4 } 1729 | } 1730 | \tex_input:D 1731 | l3 1732 | \sys_if_engine_xetex:TF 1733 | { xdvipdfmx } 1734 | { 1735 | \bool_lazy_and:nnTF 1736 | { \cs_if_exist_p:N \tex_pdfoutput:D } 1737 | { \int_compare_p:nNn \tex_pdfoutput:D > 0 } 1738 | { pdfmode } 1739 | { dvips } 1740 | } 1741 | .def \scan_stop: 1742 | \cs_undefine:N \ProvidesExplFile 1743 | \cs_undefine:N \ProvidesExplFileAux 1744 | % \end{macrocode} 1745 | % 1746 | % For the generic loader, a few final steps to take. Turn of \cs{expl3} 1747 | % syntax and tidy up the small number of temporary changes. 1748 | % \begin{macrocode} 1749 | \ExplSyntaxOff 1750 | \l@expl@tidy@tl 1751 | % \end{macrocode} 1752 | % 1753 | % \begin{macrocode} 1754 | % 1755 | % \end{macrocode} 1756 | % 1757 | % \end{implementation} 1758 | % 1759 | % \PrintIndex 1760 | --------------------------------------------------------------------------------