diff options
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3skip.dtx')
-rw-r--r-- | macros/latex/contrib/l3kernel/l3skip.dtx | 2600 |
1 files changed, 0 insertions, 2600 deletions
diff --git a/macros/latex/contrib/l3kernel/l3skip.dtx b/macros/latex/contrib/l3kernel/l3skip.dtx deleted file mode 100644 index 1839c8a2e5..0000000000 --- a/macros/latex/contrib/l3kernel/l3skip.dtx +++ /dev/null @@ -1,2600 +0,0 @@ -% \iffalse meta-comment -% -%% File: l3skip.dtx -% -% Copyright (C) 2004-2011 Frank Mittelbach, The LaTeX Project -% (C) 2012-2024 The LaTeX Project -% -% It may be distributed and/or modified under the conditions of the -% LaTeX Project Public License (LPPL), either version 1.3c of this -% license or (at your option) any later version. The latest version -% of this license is in the file -% -% https://www.latex-project.org/lppl.txt -% -% This file is part of the "l3kernel bundle" (The Work in LPPL) -% and all files in that bundle must be distributed together. -% -% ----------------------------------------------------------------------- -% -% The development version of the bundle can be found at -% -% https://github.com/latex3/latex3 -% -% for those people who are interested. -% -%<*driver> -\documentclass[full,kernel]{l3doc} -\begin{document} - \DocInput{\jobname.dtx} -\end{document} -%</driver> -% \fi -% -% \title{^^A -% The \pkg{l3skip} module\\ Dimensions and skips^^A -% } -% -% \author{^^A -% The \LaTeX{} Project\thanks -% {^^A -% E-mail: -% \href{mailto:latex-team@latex-project.org} -% {latex-team@latex-project.org}^^A -% }^^A -% } -% -% \date{Released 2024-03-14} -% -% \maketitle -% -% \begin{documentation} -% -% \LaTeX3 provides two general length variables: \texttt{dim} and -% \texttt{skip}. Lengths stored as \texttt{dim} variables have a fixed -% length, whereas \texttt{skip} lengths have a rubber (stretch/shrink) -% component. In addition, the \texttt{muskip} type is available for -% use in math mode: this is a special form of \texttt{skip} where the -% lengths involved are determined by the current math font (in -% \texttt{mu)}. There are common features in the creation and setting of -% length variables, but for clarity the functions are grouped by variable -% type. -% -% Many functions take -% \emph{dimension expressions} (\enquote{\meta{dim expr}}) or -% \emph{skip expressions} (\enquote{\meta{skip expr}}) as arguments. -% -% -% \section{Creating and initialising \texttt{dim} variables} -% -% \begin{function}{\dim_new:N, \dim_new:c} -% \begin{syntax} -% \cs{dim_new:N} \meta{dimension} -% \end{syntax} -% Creates a new \meta{dimension} or raises an error if the name is -% already taken. The declaration is global. The \meta{dimension} -% is initially equal to $0$\,pt. -% \end{function} -% -% \begin{function}[added = 2012-03-05]{\dim_const:Nn, \dim_const:cn} -% \begin{syntax} -% \cs{dim_const:Nn} \meta{dimension} \Arg{dim expr} -% \end{syntax} -% Creates a new constant \meta{dimension} or raises an error if the -% name is already taken. The value of the \meta{dimension} is set -% globally to the \meta{dim expr}. -% \end{function} -% -% \begin{function}{\dim_zero:N, \dim_zero:c, \dim_gzero:N, \dim_gzero:c} -% \begin{syntax} -% \cs{dim_zero:N} \meta{dimension} -% \end{syntax} -% Sets \meta{dimension} to $0$\,pt. -% \end{function} -% -% \begin{function}[added = 2012-01-07] -% {\dim_zero_new:N, \dim_zero_new:c, \dim_gzero_new:N, \dim_gzero_new:c} -% \begin{syntax} -% \cs{dim_zero_new:N} \meta{dimension} -% \end{syntax} -% Ensures that the \meta{dimension} exists globally by applying -% \cs{dim_new:N} if necessary, then applies -% \cs[index=dim_zero:N]{dim_(g)zero:N} to leave -% the \meta{dimension} set to zero. -% \end{function} -% -% \begin{function}[EXP, pTF, added=2012-03-03]{\dim_if_exist:N, \dim_if_exist:c} -% \begin{syntax} -% \cs{dim_if_exist_p:N} \meta{dimension} -% \cs{dim_if_exist:NTF} \meta{dimension} \Arg{true code} \Arg{false code} -% \end{syntax} -% Tests whether the \meta{dimension} is currently defined. This does -% not check that the \meta{dimension} really is a dimension variable. -% \end{function} -% -% \section{Setting \texttt{dim} variables} -% -% \begin{function}[updated = 2011-10-22] -% {\dim_add:Nn, \dim_add:cn, \dim_gadd:Nn, \dim_gadd:cn} -% \begin{syntax} -% \cs{dim_add:Nn} \meta{dimension} \Arg{dim expr} -% \end{syntax} -% Adds the result of the \meta{dim expr} to the current -% content of the \meta{dimension}. -% \end{function} -% -% \begin{function}[updated = 2011-10-22] -% {\dim_set:Nn, \dim_set:cn, \dim_gset:Nn, \dim_gset:cn} -% \begin{syntax} -% \cs{dim_set:Nn} \meta{dimension} \Arg{dim expr} -% \end{syntax} -% Sets \meta{dimension} to the value of \meta{dim expr}, which -% must evaluate to a length with units. -% \end{function} -% -% \begin{function} -% { -% \dim_set_eq:NN, \dim_set_eq:cN, \dim_set_eq:Nc, \dim_set_eq:cc, -% \dim_gset_eq:NN, \dim_gset_eq:cN, \dim_gset_eq:Nc, \dim_gset_eq:cc -% } -% \begin{syntax} -% \cs{dim_set_eq:NN} \meta{dimension_1} \meta{dimension_2} -% \end{syntax} -% Sets the content of \meta{dimension_1} equal to that of -% \meta{dimension_2}. -% \end{function} -% -% \begin{function}[updated = 2011-10-22] -% {\dim_sub:Nn, \dim_sub:cn, \dim_gsub:Nn, \dim_gsub:cn} -% \begin{syntax} -% \cs{dim_sub:Nn} \meta{dimension} \Arg{dim expr} -% \end{syntax} -% Subtracts the result of the \meta{dim expr} from the -% current content of the \meta{dimension}. -% \end{function} -% -% \section{Utilities for dimension calculations} -% -% \begin{function}[updated = 2012-09-26, EXP]{\dim_abs:n} -% \begin{syntax} -% \cs{dim_abs:n} \Arg{dim expr} -% \end{syntax} -% Converts the \meta{dim expr} to its absolute value, leaving the result -% in the input stream as a \meta{dimension denotation}. -% \end{function} -% -% \begin{function}[added = 2012-09-09, updated = 2012-09-26, EXP] -% {\dim_max:nn, \dim_min:nn} -% \begin{syntax} -% \cs{dim_max:nn} \Arg{dim expr_1} \Arg{dim expr_2} -% \cs{dim_min:nn} \Arg{dim expr_1} \Arg{dim expr_2} -% \end{syntax} -% Evaluates the two \meta{dim exprs} and leaves either the -% maximum or minimum value in the input stream as appropriate, as a -% \meta{dimension denotation}. -% \end{function} -% -% \begin{function}[updated = 2011-10-22, rEXP]{\dim_ratio:nn} -% \begin{syntax} -% \cs{dim_ratio:nn} \Arg{dim expr_1} \Arg{dim expr_2} -% \end{syntax} -% Parses the two \meta{dim exprs} and converts the ratio of -% the two to a form suitable for use inside a \meta{dim expr}. -% This ratio is then left in the input stream, allowing syntax such as -% \begin{verbatim} -% \dim_set:Nn \l_my_dim -% { 10 pt * \dim_ratio:nn { 5 pt } { 10 pt } } -% \end{verbatim} -% The output of \cs{dim_ratio:nn} on full expansion is a ratio expression -% between two integers, with all distances converted to scaled points. -% Thus -% \begin{verbatim} -% \tl_set:Ne \l_my_tl { \dim_ratio:nn { 5 pt } { 10 pt } } -% \tl_show:N \l_my_tl -% \end{verbatim} -% displays |327680/655360| on the terminal. -% \end{function} -% -% \section{Dimension expression conditionals} -% -% \begin{function}[EXP,pTF]{\dim_compare:nNn} -% \begin{syntax} -% \cs{dim_compare_p:nNn} \Arg{dim expr_1} \meta{relation} \Arg{dim expr_2} \\ -% \cs{dim_compare:nNnTF} -% ~~\Arg{dim expr_1} \meta{relation} \Arg{dim expr_2} -% ~~\Arg{true code} \Arg{false code} -% \end{syntax} -% This function first evaluates each of the \meta{dim exprs} -% as described for \cs{dim_eval:n}. The two results are then -% compared using the \meta{relation}: -% \begin{center} -% \begin{tabular}{ll} -% Equal & |=| \\ -% Greater than & |>| \\ -% Less than & |<| \\ -% \end{tabular} -% \end{center} -% This function is less flexible than \cs{dim_compare:nTF} but around -% $5$~times faster. -% \end{function} -% -% \begin{function}[updated = 2013-01-13, EXP, pTF]{\dim_compare:n} -% \begin{syntax} -% \cs{dim_compare_p:n} \\ -% ~~\{ \\ -% ~~~~\meta{dim expr_1} \meta{relation_1} \\ -% ~~~~\ldots{} \\ -% ~~~~\meta{dim expr_N} \meta{relation_N} \\ -% ~~~~\meta{dim expr_{N+1}} \\ -% ~~\} \\ -% \cs{dim_compare:nTF} -% ~~\{ \\ -% ~~~~\meta{dim expr_1} \meta{relation_1} \\ -% ~~~~\ldots{} \\ -% ~~~~\meta{dim expr_N} \meta{relation_N} \\ -% ~~~~\meta{dim expr_{N+1}} \\ -% ~~\} \\ -% ~~\Arg{true code} \Arg{false code} -% \end{syntax} -% This function evaluates the \meta{dim exprs} as -% described for \cs{dim_eval:n} and compares consecutive result using -% the corresponding \meta{relation}, namely it compares -% \meta{dim expr_1} and \meta{dim expr_2} using the \meta{relation_1}, -% then \meta{dim expr_2} and \meta{dim expr_3} using the -% \meta{relation_2}, until finally comparing \meta{dim expr_N} and -% \meta{dim expr_{N+1}} using the \meta{relation_N}. The test yields -% \texttt{true} if all comparisons are \texttt{true}. Each -% \meta{dim expr} is evaluated only once, and the -% evaluation is lazy, in the sense that if one comparison is -% \texttt{false}, then no other \meta{dim expr} is -% evaluated and no other comparison is performed. The -% \meta{relations} can be any of the following: -% \begin{center} -% \begin{tabular}{ll} -% Equal & |=| or |==| \\ -% Greater than or equal to & |>=| \\ -% Greater than & |>| \\ -% Less than or equal to & |<=| \\ -% Less than & |<| \\ -% Not equal & |!=| \\ -% \end{tabular} -% \end{center} -% This function is more flexible than \cs{dim_compare:nNnTF} but -% around $5$~times slower. -% \end{function} -% -% \begin{function}[added = 2013-07-24, EXP, noTF]{\dim_case:nn} -% \begin{syntax} -% \cs{dim_case:nnTF} \Arg{test dim expr} \\ -% ~~|{| \\ -% ~~~~\Arg{dim expr case_1} \Arg{code case_1} \\ -% ~~~~\Arg{dim expr case_2} \Arg{code case_2} \\ -% ~~~~\ldots \\ -% ~~~~\Arg{dim expr case_n} \Arg{code case_n} \\ -% ~~|}| \\ -% ~~\Arg{true code} -% ~~\Arg{false code} -% \end{syntax} -% This function evaluates the \meta{test dim expr} and -% compares this in turn to each of the -% \meta{dim expr cases}. If the two are equal then the -% associated \meta{code} is left in the input stream -% and other cases are discarded. If any of the -% cases are matched, the \meta{true code} is also inserted into the -% input stream (after the code for the appropriate case), while if none -% match then the \meta{false code} is inserted. The function -% \cs{dim_case:nn}, which does nothing if there is no match, is also -% available. For example -% \begin{verbatim} -% \dim_set:Nn \l_tmpa_dim { 5 pt } -% \dim_case:nnF -% { 2 \l_tmpa_dim } -% { -% { 5 pt } { Small } -% { 4 pt + 6 pt } { Medium } -% { - 10 pt } { Negative } -% } -% { No idea! } -% \end{verbatim} -% leaves \enquote{\texttt{Medium}} in the input stream. -% \end{function} -% -% \section{Dimension expression loops} -% -% \begin{function}[rEXP]{\dim_do_until:nNnn} -% \begin{syntax} -% \cs{dim_do_until:nNnn} \Arg{dim expr_1} \meta{relation} \Arg{dim expr_2} \Arg{code} -% \end{syntax} -% Places the \meta{code} in the input stream for \TeX{} to process, and -% then evaluates the relationship between the two -% \meta{dim exprs} as described for \cs{dim_compare:nNnTF}. -% If the test is \texttt{false} then the \meta{code} is inserted -% into the input stream again and a loop occurs until the -% \meta{relation} is \texttt{true}. -% \end{function} -% -% \begin{function}[rEXP]{\dim_do_while:nNnn} -% \begin{syntax} -% \cs{dim_do_while:nNnn} \Arg{dim expr_1} \meta{relation} \Arg{dim expr_2} \Arg{code} -% \end{syntax} -% Places the \meta{code} in the input stream for \TeX{} to process, and -% then evaluates the relationship between the two -% \meta{dim exprs} as described for \cs{dim_compare:nNnTF}. -% If the test is \texttt{true} then the \meta{code} is inserted -% into the input stream again and a loop occurs until the -% \meta{relation} is \texttt{false}. -% \end{function} -% -% \begin{function}[rEXP]{\dim_until_do:nNnn} -% \begin{syntax} -% \cs{dim_until_do:nNnn} \Arg{dim expr_1} \meta{relation} \Arg{dim expr_2} \Arg{code} -% \end{syntax} -% Evaluates the relationship between the two \meta{dim exprs} -% as described for \cs{dim_compare:nNnTF}, and then places the -% \meta{code} in the input stream if the \meta{relation} is -% \texttt{false}. After the \meta{code} has been processed by \TeX{} the -% test is repeated, and a loop occurs until the test is -% \texttt{true}. -% \end{function} -% -% \begin{function}[rEXP]{\dim_while_do:nNnn} -% \begin{syntax} -% \cs{dim_while_do:nNnn} \Arg{dim expr_1} \meta{relation} \Arg{dim expr_2} \Arg{code} -% \end{syntax} -% Evaluates the relationship between the two \meta{dim exprs} -% as described for \cs{dim_compare:nNnTF}, and then places the -% \meta{code} in the input stream if the \meta{relation} is -% \texttt{true}. After the \meta{code} has been processed by \TeX{} the -% test is repeated, and a loop occurs until the test is -% \texttt{false}. -% \end{function} -% -% \begin{function}[updated = 2013-01-13, rEXP]{\dim_do_until:nn} -% \begin{syntax} -% \cs{dim_do_until:nn} \Arg{dimension relation} \Arg{code} -% \end{syntax} -% Places the \meta{code} in the input stream for \TeX{} to process, and -% then evaluates the \meta{dimension relation} -% as described for \cs{dim_compare:nTF}. -% If the test is \texttt{false} then the \meta{code} is inserted -% into the input stream again and a loop occurs until the -% \meta{relation} is \texttt{true}. -% \end{function} -% -% \begin{function}[updated = 2013-01-13, rEXP]{\dim_do_while:nn} -% \begin{syntax} -% \cs{dim_do_while:nn} \Arg{dimension relation} \Arg{code} -% \end{syntax} -% Places the \meta{code} in the input stream for \TeX{} to process, and -% then evaluates the \meta{dimension relation} -% as described for \cs{dim_compare:nTF}. -% If the test is \texttt{true} then the \meta{code} is inserted -% into the input stream again and a loop occurs until the -% \meta{relation} is \texttt{false}. -% \end{function} -% -% \begin{function}[updated = 2013-01-13, rEXP]{\dim_until_do:nn} -% \begin{syntax} -% \cs{dim_until_do:nn} \Arg{dimension relation} \Arg{code} -% \end{syntax} -% Evaluates the \meta{dimension relation} -% as described for \cs{dim_compare:nTF}, and then places the -% \meta{code} in the input stream if the \meta{relation} is -% \texttt{false}. After the \meta{code} has been processed by \TeX{} the -% test is repeated, and a loop occurs until the test is -% \texttt{true}. -% \end{function} -% -% \begin{function}[updated = 2013-01-13, rEXP]{\dim_while_do:nn} -% \begin{syntax} -% \cs{dim_while_do:nn} \Arg{dimension relation} \Arg{code} -% \end{syntax} -% Evaluates the \meta{dimension relation} -% as described for \cs{dim_compare:nTF}, and then places the -% \meta{code} in the input stream if the \meta{relation} is -% \texttt{true}. After the \meta{code} has been processed by \TeX{} the -% test is repeated, and a loop occurs until the test is -% \texttt{false}. -% \end{function} -% -% \section{Dimension step functions} -% -% \begin{function}[added = 2018-02-18, rEXP] -% {\dim_step_function:nnnN} -% \begin{syntax} -% \cs{dim_step_function:nnnN} \Arg{initial value} \Arg{step} \Arg{final value} \meta{function} -% \end{syntax} -% This function first evaluates the \meta{initial value}, \meta{step} -% and \meta{final value}, all of which should be dimension expressions. -% The \meta{function} is then placed in front of each \meta{value} -% from the \meta{initial value} to the \meta{final value} in turn -% (using \meta{step} between each \meta{value}). The \meta{step} must -% be non-zero. If the \meta{step} is positive, the loop stops when -% the \meta{value} becomes larger than the \meta{final value}. If the -% \meta{step} is negative, the loop stops when the \meta{value} -% becomes smaller than the \meta{final value}. The \meta{function} -% should absorb one argument. -% \end{function} -% -% \begin{function}[added = 2018-02-18] -% {\dim_step_inline:nnnn} -% \begin{syntax} -% \cs{dim_step_inline:nnnn} \Arg{initial value} \Arg{step} \Arg{final value} \Arg{code} -% \end{syntax} -% This function first evaluates the \meta{initial value}, \meta{step} -% and \meta{final value}, all of which should be dimension expressions. -% Then for each \meta{value} from the \meta{initial value} to the -% \meta{final value} in turn (using \meta{step} between each -% \meta{value}), the \meta{code} is inserted into the input stream -% with |#1| replaced by the current \meta{value}. Thus the -% \meta{code} should define a function of one argument~(|#1|). -% \end{function} -% -% \begin{function}[added = 2018-02-18] -% {\dim_step_variable:nnnNn} -% \begin{syntax} -% \cs{dim_step_variable:nnnNn} \\ -% ~~\Arg{initial value} \Arg{step} \Arg{final value} \meta{tl~var} \Arg{code} -% \end{syntax} -% This function first evaluates the \meta{initial value}, \meta{step} -% and \meta{final value}, all of which should be dimension expressions. -% Then for each \meta{value} from the \meta{initial value} to the -% \meta{final value} in turn (using \meta{step} between each -% \meta{value}), the \meta{code} is inserted into the input stream, -% with the \meta{tl~var} defined as the current \meta{value}. Thus -% the \meta{code} should make use of the \meta{tl~var}. -% \end{function} -% -% \section{Using \texttt{dim} expressions and variables} -% -% \begin{function}[updated = 2011-10-22, EXP]{\dim_eval:n} -% \begin{syntax} -% \cs{dim_eval:n} \Arg{dim expr} -% \end{syntax} -% Evaluates the \meta{dim expr}, expanding any -% dimensions and token list variables within the \meta{expression} -% to their content (without requiring \cs{dim_use:N}/\cs{tl_use:N}) -% and applying the standard mathematical rules. The result of the -% calculation is left in the input stream as a -% \meta{dimension denotation} after two expansions. This is -% expressed in points (\texttt{pt}), and requires suitable -% termination if used in a \TeX{}-style assignment as it is \emph{not} -% an \meta{internal dimension}. -% \end{function} -% -% \begin{function}[EXP, added = 2018-11-03]{\dim_sign:n} -% \begin{syntax} -% \cs{dim_sign:n} \Arg{dim expr} -% \end{syntax} -% Evaluates the \meta{dim expr} then leaves $1$ or $0$ or $-1$ in the -% input stream according to the sign of the result. -% \end{function} -% -% \begin{function}[EXP]{\dim_use:N, \dim_use:c} -% \begin{syntax} -% \cs{dim_use:N} \meta{dimension} -% \end{syntax} -% Recovers the content of a \meta{dimension} and places it directly -% in the input stream. An error is raised if the variable does -% not exist or if it is invalid. Can be omitted in places where a -% \meta{dimension} is required (such as in the argument of -% \cs{dim_eval:n}). -% \begin{texnote} -% \cs{dim_use:N} is the \TeX{} primitive \tn{the}: this is one of -% several \LaTeX3 names for this primitive. -% \end{texnote} -% \end{function} -% -% \begin{function}[added = 2014-07-15, EXP]{\dim_to_decimal:n} -% \begin{syntax} -% \cs{dim_to_decimal:n} \Arg{dim expr} -% \end{syntax} -% Evaluates the \meta{dim expr}, and leaves the result, -% expressed in points (\texttt{pt}) in the input stream, with \emph{no -% units}. The result is rounded by \TeX{} to at most five decimal -% places. If the decimal part of the result is zero, it is omitted, -% together with the decimal marker. -% -% For example -% \begin{verbatim} -% \dim_to_decimal:n { 1bp } -% \end{verbatim} -% leaves |1.00374| in the input stream, \emph{i.e.}~the magnitude of -% one \enquote{big point} when converted to (\TeX{}) points. -% \end{function} -% -% \begin{function}[added = 2014-07-15, updated = 2023-05-20, EXP] -% {\dim_to_decimal_in_bp:n} -% \begin{syntax} -% \cs{dim_to_decimal_in_bp:n} \Arg{dim expr} -% \end{syntax} -% Evaluates the \meta{dim expr}, and leaves the result, -% expressed in big points (\texttt{bp}) in the input stream, with \emph{no -% units}. The result is rounded by \TeX{} to at most five decimal -% places. If the decimal part of the result is zero, it is omitted, -% together with the decimal marker. -% -% For example -% \begin{verbatim} -% \dim_to_decimal_in_bp:n { 1pt } -% \end{verbatim} -% leaves |0.99628| in the input stream, \emph{i.e.}~the magnitude of -% one (\TeX{}) point when converted to big points. -% \begin{texnote} -% The implementation of this function is re-entrant: the result of -% \begin{verbatim} -% \dim_compare:nNnTF -% { <x>bp } = -% { \dim_to_decimal_in_bp:n { <x>bp } bp } -% \end{verbatim} -% will be logically \texttt{true}. The decimal representations may -% differ provided they produce the same \TeX{} dimension. -% \end{texnote} -% \end{function} -% -% \begin{function}[added = 2023-05-20, EXP] -% { -% \dim_to_decimal_in_cc:n , -% \dim_to_decimal_in_cm:n , -% \dim_to_decimal_in_dd:n , -% \dim_to_decimal_in_in:n , -% \dim_to_decimal_in_mm:n , -% \dim_to_decimal_in_pc:n -% } -% \begin{syntax} -% \cs{dim_to_decimal_in_cm:n} \Arg{dim expr} -% \end{syntax} -% Evaluates the \meta{dim expr}, and leaves the result, -% expressed with the appropriate scaling in the input stream, with -% \emph{no units}. If the decimal part of the result is zero, it is omitted, -% together with the decimal marker. The precisions of the result is limited -% to a maximum of five decimal places with trailing zeros omitted. -% -% The maximum \TeX{} allowable dimension value (available as -% \tn{maxdimen} in plain \TeX{} and \LaTeX{} and \cs{c_max_dim} in -% \pkg{expl3}) can only be expressed exactly in the units -% \texttt{pt}, \texttt{bp} and \texttt{sp}. The maximum allowable -% input values to five decimal places are\\ -% \begin{center} -% \begin{tabular}{@{}>{$}r<{$}@{\,}l@{}} -% 1276.00215 & cc \\ -% 575.83174 & cm \\ -% 15312.02584 & dd \\ -% 226.70540 & in \\ -% 5758.31742 & mm \\ -% 1365.33333 & pc \\ -% \end{tabular} -% \end{center} -% (Note that these are not all equal, but rather any larger value will overflow -% due to the way \TeX{} converts to \texttt{sp}.) -% Values given to five decimal places larger that these will result in \TeX{} -% errors; the behavior if additional decimal places are given depends on the -% \TeX{} internals and thus larger values are \emph{not} supported by -% \pkg{expl3}. -% \begin{texnote} -% The implementation of these functions is re-entrant: the result of -% \begin{verbatim} -% \dim_compare:nNnTF -% { <x><unit> } = -% { \dim_to_decimal_in_<unit>:n { <x><unit> } <unit> } -% \end{verbatim} -% will be logically \texttt{true}. The decimal representations may -% differ provided they produce the same \TeX{} dimension. -% \end{texnote} -% \end{function} -% -% \begin{function}[added = 2015-05-18, EXP]{\dim_to_decimal_in_sp:n} -% \begin{syntax} -% \cs{dim_to_decimal_in_sp:n} \Arg{dim expr} -% \end{syntax} -% Evaluates the \meta{dim expr}, and leaves the result, -% expressed in scaled points (\texttt{sp}) in the input stream, with \emph{no -% units}. The result is necessarily an integer. -% \end{function} -% -% \begin{function}[added = 2014-07-15, updated = 2023-05-20, EXP] -% {\dim_to_decimal_in_unit:nn} -% \begin{syntax} -% \cs{dim_to_decimal_in_unit:nn} \Arg{dim expr_1} \Arg{dim expr_2} -% \end{syntax} -% Evaluates the \meta{dim exprs}, and leaves the value of -% \meta{dim expr_1}, expressed in a unit given by \meta{dim expr_2}, in -% the input stream. If the decimal part of the result -% is zero, it is omitted, together with the decimal marker. -% The precisions of the result is limited -% to a maximum of five decimal places with trailing zeros omitted. -% -% For example -% \begin{verbatim} -% \dim_to_decimal_in_unit:nn { 1bp } { 1mm } -% \end{verbatim} -% leaves |0.35278| in the input stream, \emph{i.e.}~the magnitude of -% one big point when expressed in millimetres. The conversions do -% \emph{not} guarantee that \TeX{} would yield identical results -% for the direct input in an equality test, thus for instance -% \begin{verbatim} -% \dim_compare:nNnTF -% { 1bp } = -% { \dim_to_decimal_in_unit:nn { 1bp } { 1mm } mm } -% \end{verbatim} -% will take the \texttt{false} branch. -% \end{function} -% -% \begin{function}[EXP, added = 2012-05-08, tested = m3fp-convert002] -% {\dim_to_fp:n} -% \begin{syntax} -% \cs{dim_to_fp:n} \Arg{dim expr} -% \end{syntax} -% Expands to an internal floating point number equal to the value of -% the \meta{dim expr} in \texttt{pt}. Since dimension expressions are -% evaluated much faster than their floating point equivalent, -% \cs{dim_to_fp:n} can be used to speed up parts of a computation -% where a low precision and a smaller range are acceptable. -% \end{function} -% -% \section{Viewing \texttt{dim} variables} -% -% \begin{function}{\dim_show:N, \dim_show:c} -% \begin{syntax} -% \cs{dim_show:N} \meta{dimension} -% \end{syntax} -% Displays the value of the \meta{dimension} on the terminal. -% \end{function} -% -% \begin{function}[added = 2011-11-22, updated = 2015-08-07]{\dim_show:n} -% \begin{syntax} -% \cs{dim_show:n} \Arg{dim expr} -% \end{syntax} -% Displays the result of evaluating the \meta{dim expr} -% on the terminal. -% \end{function} -% -% \begin{function}[added = 2014-08-22, updated = 2015-08-03]{\dim_log:N, \dim_log:c} -% \begin{syntax} -% \cs{dim_log:N} \meta{dimension} -% \end{syntax} -% Writes the value of the \meta{dimension} in the log file. -% \end{function} -% -% \begin{function}[added = 2014-08-22, updated = 2015-08-07]{\dim_log:n} -% \begin{syntax} -% \cs{dim_log:n} \Arg{dim expr} -% \end{syntax} -% Writes the result of evaluating the \meta{dim expr} -% in the log file. -% \end{function} -% -% \section{Constant dimensions} -% -% \begin{variable}{\c_max_dim} -% The maximum value that can be stored as a dimension. This can also -% be used as a component of a skip. -% \end{variable} -% -% \begin{variable}{\c_zero_dim} -% A zero length as a dimension. This can also be used as a component -% of a skip. -% \end{variable} -% -% \section{Scratch dimensions} -% -% \begin{variable}{\l_tmpa_dim, \l_tmpb_dim} -% Scratch dimension for local assignment. These are never used by -% the kernel code, and so are safe for use with any \LaTeX3-defined -% function. However, they may be overwritten by other non-kernel -% code and so should only be used for short-term storage. -% \end{variable} -% -% \begin{variable}{\g_tmpa_dim, \g_tmpb_dim} -% Scratch dimension for global assignment. These are never used by -% the kernel code, and so are safe for use with any \LaTeX3-defined -% function. However, they may be overwritten by other non-kernel -% code and so should only be used for short-term storage. -% \end{variable} -% -% \section{Creating and initialising \texttt{skip} variables} -% -% \begin{function}{\skip_new:N, \skip_new:c} -% \begin{syntax} -% \cs{skip_new:N} \meta{skip} -% \end{syntax} -% Creates a new \meta{skip} or raises an error if the name is -% already taken. The declaration is global. The \meta{skip} -% is initially equal to $0$\,pt. -% \end{function} -% -% \begin{function}[added = 2012-03-05]{\skip_const:Nn, \skip_const:cn} -% \begin{syntax} -% \cs{skip_const:Nn} \meta{skip} \Arg{skip expr} -% \end{syntax} -% Creates a new constant \meta{skip} or raises an error if the -% name is already taken. The value of the \meta{skip} is set -% globally to the \meta{skip expr}. -% \end{function} -% -% \begin{function}{\skip_zero:N, \skip_zero:c, \skip_gzero:N, \skip_gzero:c} -% \begin{syntax} -% \cs{skip_zero:N} \meta{skip} -% \end{syntax} -% Sets \meta{skip} to $0$\,pt. -% \end{function} -% -% \begin{function}[added = 2012-01-07] -% {\skip_zero_new:N, \skip_zero_new:c, \skip_gzero_new:N, \skip_gzero_new:c} -% \begin{syntax} -% \cs{skip_zero_new:N} \meta{skip} -% \end{syntax} -% Ensures that the \meta{skip} exists globally by applying -% \cs{skip_new:N} if necessary, then applies -% \cs[index=skip_zero:N]{skip_(g)zero:N} to leave -% the \meta{skip} set to zero. -% \end{function} -% -% \begin{function}[EXP, pTF, added=2012-03-03] -% {\skip_if_exist:N, \skip_if_exist:c} -% \begin{syntax} -% \cs{skip_if_exist_p:N} \meta{skip} -% \cs{skip_if_exist:NTF} \meta{skip} \Arg{true code} \Arg{false code} -% \end{syntax} -% Tests whether the \meta{skip} is currently defined. This does not -% check that the \meta{skip} really is a skip variable. -% \end{function} -% -% \section{Setting \texttt{skip} variables} -% -% \begin{function}[updated = 2011-10-22] -% {\skip_add:Nn, \skip_add:cn, \skip_gadd:Nn, \skip_gadd:cn} -% \begin{syntax} -% \cs{skip_add:Nn} \meta{skip} \Arg{skip expr} -% \end{syntax} -% Adds the result of the \meta{skip expr} to the current -% content of the \meta{skip}. -% \end{function} -% -% \begin{function}[updated = 2011-10-22] -% {\skip_set:Nn, \skip_set:cn, \skip_gset:Nn, \skip_gset:cn} -% \begin{syntax} -% \cs{skip_set:Nn} \meta{skip} \Arg{skip expr} -% \end{syntax} -% Sets \meta{skip} to the value of \meta{skip expr}, which -% must evaluate to a length with units and may include a rubber -% component (for example |1 cm plus 0.5 cm|. -% \end{function} -% -% \begin{function} -% { -% \skip_set_eq:NN, \skip_set_eq:cN, \skip_set_eq:Nc, \skip_set_eq:cc, -% \skip_gset_eq:NN, \skip_gset_eq:cN, \skip_gset_eq:Nc, \skip_gset_eq:cc -% } -% \begin{syntax} -% \cs{skip_set_eq:NN} \meta{skip_1} \meta{skip_2} -% \end{syntax} -% Sets the content of \meta{skip_1} equal to that of \meta{skip_2}. -% \end{function} -% -% \begin{function}[updated = 2011-10-22] -% {\skip_sub:Nn, \skip_sub:cn, \skip_gsub:Nn, \skip_gsub:cn} -% \begin{syntax} -% \cs{skip_sub:Nn} \meta{skip} \Arg{skip expr} -% \end{syntax} -% Subtracts the result of the \meta{skip expr} from the -% current content of the \meta{skip}. -% \end{function} -% -% \section{Skip expression conditionals} -% -% \begin{function}[EXP,pTF]{\skip_if_eq:nn} -% \begin{syntax} -% \cs{skip_if_eq_p:nn} \Arg{skip expr_1} \Arg{skip expr_2} -% \cs{skip_if_eq:nnTF} -% ~~\Arg{skip expr_1} \Arg{skip expr_2} -% ~~\Arg{true code} \Arg{false code} -% \end{syntax} -% This function first evaluates each of the -% \meta{skip exprs} as described for \cs{skip_eval:n}. -% The two results are then compared for exact equality, -% \emph{i.e.}~both the fixed and rubber components must be the same -% for the test to be true. -% \end{function} -% -% \begin{function}[EXP, pTF, added = 2012-03-05]{\skip_if_finite:n} -% \begin{syntax} -% \cs{skip_if_finite_p:n} \Arg{skip expr} -% \cs{skip_if_finite:nTF} \Arg{skip expr} \Arg{true code} \Arg{false code} -% \end{syntax} -% Evaluates the \meta{skip expr} as described for \cs{skip_eval:n}, -% and then tests if all of its components are finite. -% \end{function} -% -% \section{Using \texttt{skip} expressions and variables} -% -% \begin{function}[updated = 2011-10-22, EXP]{\skip_eval:n} -% \begin{syntax} -% \cs{skip_eval:n} \Arg{skip expr} -% \end{syntax} -% Evaluates the \meta{skip expr}, expanding any skips -% and token list variables within the \meta{expression} -% to their content (without requiring \cs{skip_use:N}/\cs{tl_use:N}) -% and applying the standard mathematical rules. The result of the -% calculation is left in the input stream as a \meta{glue denotation} -% after two expansions. This is expressed in points (\texttt{pt}), -% and requires suitable termination if used in a \TeX{}-style -% assignment as it is \emph{not} an \meta{internal glue}. -% \end{function} -% -% \begin{function}[EXP]{\skip_use:N, \skip_use:c} -% \begin{syntax} -% \cs{skip_use:N} \meta{skip} -% \end{syntax} -% Recovers the content of a \meta{skip} and places it directly -% in the input stream. An error is raised if the variable does -% not exist or if it is invalid. Can be omitted in places where a -% \meta{dimension} or \meta{skip} is required (such as in the argument of -% \cs{skip_eval:n}). -% \begin{texnote} -% \cs{skip_use:N} is the \TeX{} primitive \tn{the}: this is one of -% several \LaTeX3 names for this primitive. -% \end{texnote} -% \end{function} -% -% \section{Viewing \texttt{skip} variables} -% -% \begin{function}[updated = 2015-08-03]{\skip_show:N, \skip_show:c} -% \begin{syntax} -% \cs{skip_show:N} \meta{skip} -% \end{syntax} -% Displays the value of the \meta{skip} on the terminal. -% \end{function} -% -% \begin{function}[added = 2011-11-22, updated = 2015-08-07]{\skip_show:n} -% \begin{syntax} -% \cs{skip_show:n} \Arg{skip expr} -% \end{syntax} -% Displays the result of evaluating the \meta{skip expr} -% on the terminal. -% \end{function} -% -% \begin{function}[added = 2014-08-22, updated = 2015-08-03]{\skip_log:N, \skip_log:c} -% \begin{syntax} -% \cs{skip_log:N} \meta{skip} -% \end{syntax} -% Writes the value of the \meta{skip} in the log file. -% \end{function} -% -% \begin{function}[added = 2014-08-22, updated = 2015-08-07]{\skip_log:n} -% \begin{syntax} -% \cs{skip_log:n} \Arg{skip expr} -% \end{syntax} -% Writes the result of evaluating the \meta{skip expr} -% in the log file. -% \end{function} -% -% \section{Constant skips} -% -% \begin{variable}[updated = 2012-11-02]{\c_max_skip} -% The maximum value that can be stored as a skip (equal to -% \cs{c_max_dim} in length), with no stretch nor shrink component. -% \end{variable} -% -% \begin{variable}[updated = 2012-11-01]{\c_zero_skip} -% A zero length as a skip, with no stretch nor shrink component. -% \end{variable} -% -% \section{Scratch skips} -% -% \begin{variable}{\l_tmpa_skip, \l_tmpb_skip} -% Scratch skip for local assignment. These are never used by -% the kernel code, and so are safe for use with any \LaTeX3-defined -% function. However, they may be overwritten by other non-kernel -% code and so should only be used for short-term storage. -% \end{variable} -% -% \begin{variable}{\g_tmpa_skip, \g_tmpb_skip} -% Scratch skip for global assignment. These are never used by -% the kernel code, and so are safe for use with any \LaTeX3-defined -% function. However, they may be overwritten by other non-kernel -% code and so should only be used for short-term storage. -% \end{variable} -% -% \section{Inserting skips into the output} -% -% \begin{function}[updated = 2011-10-22] -% {\skip_horizontal:N, \skip_horizontal:c, \skip_horizontal:n} -% \begin{syntax} -% \cs{skip_horizontal:N} \meta{skip} -% \cs{skip_horizontal:n} \Arg{skip expr} -% \end{syntax} -% Inserts a horizontal \meta{skip} into the current list. -% The argument can also be a \meta{dim}. -% \begin{texnote} -% \cs{skip_horizontal:N} is the \TeX{} primitive \tn{hskip}. -% \end{texnote} -% \end{function} -% -% \begin{function}[updated = 2011-10-22] -% {\skip_vertical:N, \skip_vertical:c, \skip_vertical:n} -% \begin{syntax} -% \cs{skip_vertical:N} \meta{skip} -% \cs{skip_vertical:n} \Arg{skip expr} -% \end{syntax} -% Inserts a vertical \meta{skip} into the current list. -% The argument can also be a \meta{dim}. -% \begin{texnote} -% \cs{skip_vertical:N} is the \TeX{} primitive \tn{vskip}. -% \end{texnote} -% \end{function} -% -% \section{Creating and initialising \texttt{muskip} variables} -% -% \begin{function}{\muskip_new:N, \muskip_new:c} -% \begin{syntax} -% \cs{muskip_new:N} \meta{muskip} -% \end{syntax} -% Creates a new \meta{muskip} or raises an error if the name is -% already taken. The declaration is global. The \meta{muskip} -% is initially equal to $0$\,mu. -% \end{function} -% -% \begin{function}[added = 2012-03-05]{\muskip_const:Nn, \muskip_const:cn} -% \begin{syntax} -% \cs{muskip_const:Nn} \meta{muskip} \Arg{muskip expr} -% \end{syntax} -% Creates a new constant \meta{muskip} or raises an error if the -% name is already taken. The value of the \meta{muskip} is set -% globally to the \meta{muskip expr}. -% \end{function} -% -% \begin{function} -% {\muskip_zero:N, \muskip_zero:c, \muskip_gzero:N, \muskip_gzero:c} -% \begin{syntax} -% \cs{skip_zero:N} \meta{muskip} -% \end{syntax} -% Sets \meta{muskip} to $0$\,mu. -% \end{function} -% -% \begin{function}[added = 2012-01-07] -% { -% \muskip_zero_new:N, \muskip_zero_new:c, -% \muskip_gzero_new:N, \muskip_gzero_new:c -% } -% \begin{syntax} -% \cs{muskip_zero_new:N} \meta{muskip} -% \end{syntax} -% Ensures that the \meta{muskip} exists globally by applying -% \cs{muskip_new:N} if necessary, then applies -% \cs[index=muskip_zero:N]{muskip_(g)zero:N} -% to leave the \meta{muskip} set to zero. -% \end{function} -% -% \begin{function}[EXP, pTF, added=2012-03-03] -% {\muskip_if_exist:N, \muskip_if_exist:c} -% \begin{syntax} -% \cs{muskip_if_exist_p:N} \meta{muskip} -% \cs{muskip_if_exist:NTF} \meta{muskip} \Arg{true code} \Arg{false code} -% \end{syntax} -% Tests whether the \meta{muskip} is currently defined. This does not -% check that the \meta{muskip} really is a muskip variable. -% \end{function} -% -% \section{Setting \texttt{muskip} variables} -% -% \begin{function}[updated = 2011-10-22] -% {\muskip_add:Nn, \muskip_add:cn, \muskip_gadd:Nn, \muskip_gadd:cn} -% \begin{syntax} -% \cs{muskip_add:Nn} \meta{muskip} \Arg{muskip expr} -% \end{syntax} -% Adds the result of the \meta{muskip expr} to the current -% content of the \meta{muskip}. -% \end{function} -% -% \begin{function}[updated = 2011-10-22] -% {\muskip_set:Nn, \muskip_set:cn, \muskip_gset:Nn, \muskip_gset:cn} -% \begin{syntax} -% \cs{muskip_set:Nn} \meta{muskip} \Arg{muskip expr} -% \end{syntax} -% Sets \meta{muskip} to the value of \meta{muskip expr}, which -% must evaluate to a math length with units and may include a rubber -% component (for example |1 mu plus 0.5 mu|. -% \end{function} -% -% \begin{function} -% { -% \muskip_set_eq:NN, \muskip_set_eq:cN, -% \muskip_set_eq:Nc, \muskip_set_eq:cc, -% \muskip_gset_eq:NN, \muskip_gset_eq:cN, -% \muskip_gset_eq:Nc, \muskip_gset_eq:cc -% } -% \begin{syntax} -% \cs{muskip_set_eq:NN} \meta{muskip_1} \meta{muskip_2} -% \end{syntax} -% Sets the content of \meta{muskip_1} equal to that of -% \meta{muskip_2}. -% \end{function} -% -% \begin{function}[updated = 2011-10-22] -% {\muskip_sub:Nn, \muskip_sub:cn, \muskip_gsub:Nn, \muskip_gsub:cn} -% \begin{syntax} -% \cs{muskip_sub:Nn} \meta{muskip} \Arg{muskip expr} -% \end{syntax} -% Subtracts the result of the \meta{muskip expr} from the -% current content of the \meta{muskip}. -% \end{function} -% -% \section{Using \texttt{muskip} expressions and variables} -% -% \begin{function}[updated = 2011-10-22, EXP]{\muskip_eval:n} -% \begin{syntax} -% \cs{muskip_eval:n} \Arg{muskip expr} -% \end{syntax} -% Evaluates the \meta{muskip expr}, expanding any skips -% and token list variables within the \meta{expression} -% to their content (without requiring \cs{muskip_use:N}/\cs{tl_use:N}) -% and applying the standard mathematical rules. The result of the -% calculation is left in the input stream as a \meta{muglue denotation} -% after two expansions. This is expressed in \texttt{mu}, -% and requires suitable termination if used in a \TeX{}-style -% assignment as it is \emph{not} an \meta{internal muglue}. -% \end{function} -% -% \begin{function}[EXP]{\muskip_use:N, \muskip_use:c} -% \begin{syntax} -% \cs{muskip_use:N} \meta{muskip} -% \end{syntax} -% Recovers the content of a \meta{skip} and places it directly -% in the input stream. An error is raised if the variable does -% not exist or if it is invalid. Can be omitted in places where a -% \meta{dimension} is required (such as in the argument of -% \cs{muskip_eval:n}). -% \begin{texnote} -% \cs{muskip_use:N} is the \TeX{} primitive \tn{the}: this is one of -% several \LaTeX3 names for this primitive. -% \end{texnote} -% \end{function} -% -% \section{Viewing \texttt{muskip} variables} -% -% \begin{function}[updated = 2015-08-03]{\muskip_show:N, \muskip_show:c} -% \begin{syntax} -% \cs{muskip_show:N} \meta{muskip} -% \end{syntax} -% Displays the value of the \meta{muskip} on the terminal. -% \end{function} -% -% \begin{function}[added = 2011-11-22, updated = 2015-08-07]{\muskip_show:n} -% \begin{syntax} -% \cs{muskip_show:n} \Arg{muskip expr} -% \end{syntax} -% Displays the result of evaluating the \meta{muskip expr} -% on the terminal. -% \end{function} -% -% \begin{function}[added = 2014-08-22, updated = 2015-08-03]{\muskip_log:N, \muskip_log:c} -% \begin{syntax} -% \cs{muskip_log:N} \meta{muskip} -% \end{syntax} -% Writes the value of the \meta{muskip} in the log file. -% \end{function} -% -% \begin{function}[added = 2014-08-22, updated = 2015-08-07]{\muskip_log:n} -% \begin{syntax} -% \cs{muskip_log:n} \Arg{muskip expr} -% \end{syntax} -% Writes the result of evaluating the \meta{muskip expr} -% in the log file. -% \end{function} -% -% \section{Constant muskips} -% -% \begin{variable}{\c_max_muskip} -% The maximum value that can be stored as a muskip, with no stretch -% nor shrink component. -% \end{variable} -% -% \begin{variable}{\c_zero_muskip} -% A zero length as a muskip, with no stretch nor shrink component. -% \end{variable} -% -% \section{Scratch muskips} -% -% \begin{variable}{\l_tmpa_muskip, \l_tmpb_muskip} -% Scratch muskip for local assignment. These are never used by -% the kernel code, and so are safe for use with any \LaTeX3-defined -% function. However, they may be overwritten by other non-kernel -% code and so should only be used for short-term storage. -% \end{variable} -% -% \begin{variable}{\g_tmpa_muskip, \g_tmpb_muskip} -% Scratch muskip for global assignment. These are never used by -% the kernel code, and so are safe for use with any \LaTeX3-defined -% function. However, they may be overwritten by other non-kernel -% code and so should only be used for short-term storage. -% \end{variable} -% -% \section{Primitive conditional} -% -% \begin{function}[EXP]{\if_dim:w} -% \begin{syntax} -% \cs{if_dim:w} \meta{dimen_1} \meta{relation} \meta{dimen_2} -% ~~\meta{true code} -% \cs{else:} -% ~~\meta{false} -% \cs{fi:} -% \end{syntax} -% Compare two dimensions. The \meta{relation} is one of -% |<|, |=| or |>| with category code $12$. -% \begin{texnote} -% This is the \TeX{} primitive \tn{ifdim}. -% \end{texnote} -% \end{function} -% -% \end{documentation} -% -% \begin{implementation} -% -% \section{\pkg{l3skip} implementation} -% -% \begin{macrocode} -%<*package> -% \end{macrocode} -% -% \begin{macrocode} -%<@@=dim> -% \end{macrocode} -% -% \subsection{Length primitives renamed} -% -% \begin{macro}{\if_dim:w} -% \begin{macro}{\@@_eval:w} -% \begin{macro}{\@@_eval_end:} -% Primitives renamed. -% \begin{macrocode} -\cs_new_eq:NN \if_dim:w \tex_ifdim:D -\cs_new_eq:NN \@@_eval:w \tex_dimexpr:D -\cs_new_eq:NN \@@_eval_end: \tex_relax:D -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% -% \subsection{Internal auxiliaries} -% -% \begin{variable}{\s_@@_mark,\s_@@_stop} -% Internal scan marks. -% \begin{macrocode} -\scan_new:N \s_@@_mark -\scan_new:N \s_@@_stop -% \end{macrocode} -% \end{variable} -% -% \begin{macro}[EXP]{\@@_use_none_delimit_by_s_stop:w} -% Functions to gobble up to a scan mark. -% \begin{macrocode} -\cs_new:Npn \@@_use_none_delimit_by_s_stop:w #1 \s_@@_stop { } -% \end{macrocode} -% \end{macro} -% -% \subsection{Creating and initialising \texttt{dim} variables} -% -% \begin{macro}{\dim_new:N, \dim_new:c} -% Allocating \meta{dim} registers \ldots -% \begin{macrocode} -\cs_new_protected:Npn \dim_new:N #1 - { - \__kernel_chk_if_free_cs:N #1 - \cs:w newdimen \cs_end: #1 - } -\cs_generate_variant:Nn \dim_new:N { c } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\dim_const:Nn, \dim_const:cn} -% Contrarily to integer constants, we cannot avoid using a register, -% even for constants. We cannot use \cs{dim_gset:Nn} because -% debugging code would complain that the constant is not a global -% variable. Since \cs{dim_const:Nn} does not need to be fast, use -% \cs{dim_eval:n} to avoid needing a debugging patch that wraps the -% expression in checking code. -% \begin{macrocode} -\cs_new_protected:Npn \dim_const:Nn #1#2 - { - \dim_new:N #1 - \tex_global:D #1 = \dim_eval:n {#2} \scan_stop: - } -\cs_generate_variant:Nn \dim_const:Nn { c } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\dim_zero:N, \dim_zero:c} -% \begin{macro}{\dim_gzero:N, \dim_gzero:c} -% Reset the register to zero. Using \cs{c_zero_skip} deals with the -% case where the variable passed is incorrectly a skip (for example a -% \LaTeXe{} length). Besides, these functions are then simply copied -% for \cs{skip_zero:N} and related functions. -% \begin{macrocode} -\cs_new_protected:Npn \dim_zero:N #1 { #1 = \c_zero_skip } -\cs_new_protected:Npn \dim_gzero:N #1 - { \tex_global:D #1 = \c_zero_skip } -\cs_generate_variant:Nn \dim_zero:N { c } -\cs_generate_variant:Nn \dim_gzero:N { c } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro} -% {\dim_zero_new:N, \dim_zero_new:c, \dim_gzero_new:N, \dim_gzero_new:c} -% Create a register if needed, otherwise clear it. -% \begin{macrocode} -\cs_new_protected:Npn \dim_zero_new:N #1 - { \dim_if_exist:NTF #1 { \dim_zero:N #1 } { \dim_new:N #1 } } -\cs_new_protected:Npn \dim_gzero_new:N #1 - { \dim_if_exist:NTF #1 { \dim_gzero:N #1 } { \dim_new:N #1 } } -\cs_generate_variant:Nn \dim_zero_new:N { c } -\cs_generate_variant:Nn \dim_gzero_new:N { c } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}[pTF]{\dim_if_exist:N, \dim_if_exist:c} -% Copies of the \texttt{cs} functions defined in \pkg{l3basics}. -% \begin{macrocode} -\prg_new_eq_conditional:NNn \dim_if_exist:N \cs_if_exist:N - { TF , T , F , p } -\prg_new_eq_conditional:NNn \dim_if_exist:c \cs_if_exist:c - { TF , T , F , p } -% \end{macrocode} -% \end{macro} -% -% \subsection{Setting \texttt{dim} variables} -% -% \begin{macro}{\dim_set:Nn, \dim_set:cn} -% \begin{macro}{\dim_gset:Nn, \dim_gset:cn} -% Setting dimensions is easy enough but when debugging we want both to -% check that the variable is correctly local/global and to wrap the -% expression in some code. The \cs{scan_stop:} deals with the case -% where the variable passed is a skip (for example a \LaTeXe{} -% length). -% \begin{macrocode} -\cs_new_protected:Npn \dim_set:Nn #1#2 - { #1 = \@@_eval:w #2 \@@_eval_end: \scan_stop: } -\cs_new_protected:Npn \dim_gset:Nn #1#2 - { \tex_global:D #1 = \@@_eval:w #2 \@@_eval_end: \scan_stop: } -\cs_generate_variant:Nn \dim_set:Nn { c } -\cs_generate_variant:Nn \dim_gset:Nn { c } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\dim_set_eq:NN, \dim_set_eq:cN, \dim_set_eq:Nc, \dim_set_eq:cc} -% \begin{macro} -% {\dim_gset_eq:NN, \dim_gset_eq:cN, \dim_gset_eq:Nc, \dim_gset_eq:cc} -% All straightforward, with a \cs{scan_stop:} to deal with the case -% where |#1| is (incorrectly) a skip. -% \begin{macrocode} -\cs_new_protected:Npn \dim_set_eq:NN #1#2 - { #1 = #2 \scan_stop: } -\cs_generate_variant:Nn \dim_set_eq:NN { c , Nc , cc } -\cs_new_protected:Npn \dim_gset_eq:NN #1#2 - { \tex_global:D #1 = #2 \scan_stop: } -\cs_generate_variant:Nn \dim_gset_eq:NN { c , Nc , cc } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\dim_add:Nn, \dim_add:cn} -% \begin{macro}{\dim_gadd:Nn, \dim_gadd:cn} -% \begin{macro}{\dim_sub:Nn, \dim_sub:cn} -% \begin{macro}{\dim_gsub:Nn, \dim_gsub:cn} -% Using |by| here would slow things down just to detect nonsensical -% cases such as passing |\dimen 123| as the first argument. -% Using \cs{scan_stop:} deals with skip variables. Since -% debugging checks that the variable is correctly local/global, the -% global versions cannot be defined as \cs{tex_global:D} followed by -% the local versions. -% \begin{macrocode} -\cs_new_protected:Npn \dim_add:Nn #1#2 - { \tex_advance:D #1 \@@_eval:w #2 \@@_eval_end: \scan_stop: } -\cs_new_protected:Npn \dim_gadd:Nn #1#2 - { - \tex_global:D \tex_advance:D #1 - \@@_eval:w #2 \@@_eval_end: \scan_stop: - } -\cs_generate_variant:Nn \dim_add:Nn { c } -\cs_generate_variant:Nn \dim_gadd:Nn { c } -\cs_new_protected:Npn \dim_sub:Nn #1#2 - { \tex_advance:D #1 - \@@_eval:w #2 \@@_eval_end: \scan_stop: } -\cs_new_protected:Npn \dim_gsub:Nn #1#2 - { - \tex_global:D \tex_advance:D #1 - -\@@_eval:w #2 \@@_eval_end: \scan_stop: - } -\cs_generate_variant:Nn \dim_sub:Nn { c } -\cs_generate_variant:Nn \dim_gsub:Nn { c } -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% -% \subsection{Utilities for dimension calculations} -% -% \begin{macro}[EXP]{\dim_abs:n} -% \begin{macro}[EXP]{\@@_abs:N} -% \UnitTested -% \begin{macro}[EXP]{\dim_max:nn} -% \begin{macro}[EXP]{\dim_min:nn} -% \begin{macro}[EXP]{\@@_maxmin:wwN} -% \UnitTested -% \UnitTested -% Functions for $\min$, $\max$, and absolute value with only one evaluation. -% The absolute value is evaluated by removing a leading~|-| if present. -% \begin{macrocode} -\cs_new:Npn \dim_abs:n #1 - { - \exp_after:wN \@@_abs:N - \dim_use:N \@@_eval:w #1 \@@_eval_end: - } -\cs_new:Npn \@@_abs:N #1 - { \if_meaning:w - #1 \else: \exp_after:wN #1 \fi: } -\cs_new:Npn \dim_max:nn #1#2 - { - \dim_use:N \@@_eval:w \exp_after:wN \@@_maxmin:wwN - \dim_use:N \@@_eval:w #1 \exp_after:wN ; - \dim_use:N \@@_eval:w #2 ; - > - \@@_eval_end: - } -\cs_new:Npn \dim_min:nn #1#2 - { - \dim_use:N \@@_eval:w \exp_after:wN \@@_maxmin:wwN - \dim_use:N \@@_eval:w #1 \exp_after:wN ; - \dim_use:N \@@_eval:w #2 ; - < - \@@_eval_end: - } -\cs_new:Npn \@@_maxmin:wwN #1 ; #2 ; #3 - { - \if_dim:w #1 #3 #2 ~ - #1 - \else: - #2 - \fi: - } -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\dim_ratio:nn} -% \begin{macro}{\@@_ratio:n} -% With dimension expressions, something like |10 pt * ( 5 pt / 10 pt )| does -% not work. Instead, the ratio part needs to be converted to an integer -% expression. Using \cs{int_value:w} forces everything into |sp|, avoiding -% any decimal parts. -% \begin{macrocode} -\cs_new:Npn \dim_ratio:nn #1#2 - { \@@_ratio:n {#1} / \@@_ratio:n {#2} } -\cs_new:Npn \@@_ratio:n #1 - { \int_value:w \@@_eval:w (#1) \@@_eval_end: } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \subsection{Dimension expression conditionals} -% -% \begin{macro}[pTF, EXP]{\dim_compare:nNn} -% Simple comparison. -% \begin{macrocode} -\prg_new_conditional:Npnn \dim_compare:nNn #1#2#3 { p , T , F , TF } - { - \if_dim:w \@@_eval:w #1 #2 \@@_eval:w #3 \@@_eval_end: - \prg_return_true: \else: \prg_return_false: \fi: - } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}[pTF, EXP]{\dim_compare:n} -% \begin{macro}[EXP]{\@@_compare:w, \@@_compare:wNN} -% \begin{macro}[EXP] -% { -% \@@_compare_=:w, -% \@@_compare_!:w, -% \@@_compare_<:w, -% \@@_compare_>:w -% } -% \begin{macro}{\@@_compare_error:} -% This code is adapted from the \cs{int_compare:nTF} function. First -% make sure that there is at least one relation operator, by -% evaluating a dimension expression with a trailing -% \cs{@@_compare_error:}. Just like for integers, the looping -% auxiliary \cs{@@_compare:wNN} closes a primitive conditional and -% opens a new one. It is actually easier to grab a dimension operand -% than an integer one, because once evaluated, dimensions all end with -% \texttt{pt} (with category other). Thus we do not need specific -% auxiliaries for the three \enquote{simple} relations |<|, |=|, -% and~|>|. -% \begin{macrocode} -\prg_new_conditional:Npnn \dim_compare:n #1 { p , T , F , TF } - { - \exp_after:wN \@@_compare:w - \dim_use:N \@@_eval:w #1 \@@_compare_error: - } -\cs_new:Npn \@@_compare:w #1 \@@_compare_error: - { - \exp_after:wN \if_false: \exp:w \exp_end_continue_f:w - \@@_compare:wNN #1 ? { = \@@_compare_end:w \else: } \s_@@_stop - } -\exp_args:Nno \use:nn - { \cs_new:Npn \@@_compare:wNN #1 } { \tl_to_str:n {pt} #2#3 } - { - \if_meaning:w = #3 - \use:c { @@_compare_#2:w } - \fi: - #1 pt \exp_stop_f: - \prg_return_false: - \exp_after:wN \@@_use_none_delimit_by_s_stop:w - \fi: - \reverse_if:N \if_dim:w #1 pt #2 - \exp_after:wN \@@_compare:wNN - \dim_use:N \@@_eval:w #3 - } -\cs_new:cpn { @@_compare_ ! :w } - #1 \reverse_if:N #2 ! #3 = { #1 #2 = #3 } -\cs_new:cpn { @@_compare_ = :w } - #1 \@@_eval:w = { #1 \@@_eval:w } -\cs_new:cpn { @@_compare_ < :w } - #1 \reverse_if:N #2 < #3 = { #1 #2 > #3 } -\cs_new:cpn { @@_compare_ > :w } - #1 \reverse_if:N #2 > #3 = { #1 #2 < #3 } -\cs_new:Npn \@@_compare_end:w #1 \prg_return_false: #2 \s_@@_stop - { #1 \prg_return_false: \else: \prg_return_true: \fi: } -\cs_new_protected:Npn \@@_compare_error: - { - \if_int_compare:w \c_zero_int \c_zero_int \fi: - = - \@@_compare_error: - } -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% -% \begin{macro}[EXP, noTF]{\dim_case:nn} -% \begin{macro}{\@@_case:nnTF} -% \begin{macro}{\@@_case:nw, \@@_case_end:nw} -% For dimension cases, the first task to fully expand the check -% condition. The over all idea is then much the same as for -% \cs{str_case:nnTF} as described in \pkg{l3basics}. -% \begin{macrocode} -\cs_new:Npn \dim_case:nnTF #1 - { - \exp:w - \exp_args:Nf \@@_case:nnTF { \dim_eval:n {#1} } - } -\cs_new:Npn \dim_case:nnT #1#2#3 - { - \exp:w - \exp_args:Nf \@@_case:nnTF { \dim_eval:n {#1} } {#2} {#3} { } - } -\cs_new:Npn \dim_case:nnF #1#2 - { - \exp:w - \exp_args:Nf \@@_case:nnTF { \dim_eval:n {#1} } {#2} { } - } -\cs_new:Npn \dim_case:nn #1#2 - { - \exp:w - \exp_args:Nf \@@_case:nnTF { \dim_eval:n {#1} } {#2} { } { } - } -\cs_new:Npn \@@_case:nnTF #1#2#3#4 - { \@@_case:nw {#1} #2 {#1} { } \s_@@_mark {#3} \s_@@_mark {#4} \s_@@_stop } -\cs_new:Npn \@@_case:nw #1#2#3 - { - \dim_compare:nNnTF {#1} = {#2} - { \@@_case_end:nw {#3} } - { \@@_case:nw {#1} } - } -\cs_new:Npn \@@_case_end:nw #1#2#3 \s_@@_mark #4#5 \s_@@_stop - { \exp_end: #1 #4 } -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% -% \subsection{Dimension expression loops} -% -% \begin{macro}{\dim_while_do:nn} -% \begin{macro}{\dim_until_do:nn} -% \begin{macro}{\dim_do_while:nn} -% \begin{macro}{\dim_do_until:nn} -% |while_do| and |do_while| functions for dimensions. Same as for the -% |int| type only the names have changed. -% \begin{macrocode} -\cs_new:Npn \dim_while_do:nn #1#2 - { - \dim_compare:nT {#1} - { - #2 - \dim_while_do:nn {#1} {#2} - } - } -\cs_new:Npn \dim_until_do:nn #1#2 - { - \dim_compare:nF {#1} - { - #2 - \dim_until_do:nn {#1} {#2} - } - } -\cs_new:Npn \dim_do_while:nn #1#2 - { - #2 - \dim_compare:nT {#1} - { \dim_do_while:nn {#1} {#2} } - } -\cs_new:Npn \dim_do_until:nn #1#2 - { - #2 - \dim_compare:nF {#1} - { \dim_do_until:nn {#1} {#2} } - } -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\dim_while_do:nNnn} -% \begin{macro}{\dim_until_do:nNnn} -% \begin{macro}{\dim_do_while:nNnn} -% \begin{macro}{\dim_do_until:nNnn} -% |while_do| and |do_while| functions for dimensions. Same as for the -% |int| type only the names have changed. -% \begin{macrocode} -\cs_new:Npn \dim_while_do:nNnn #1#2#3#4 - { - \dim_compare:nNnT {#1} #2 {#3} - { - #4 - \dim_while_do:nNnn {#1} #2 {#3} {#4} - } - } -\cs_new:Npn \dim_until_do:nNnn #1#2#3#4 - { - \dim_compare:nNnF {#1} #2 {#3} - { - #4 - \dim_until_do:nNnn {#1} #2 {#3} {#4} - } - } -\cs_new:Npn \dim_do_while:nNnn #1#2#3#4 - { - #4 - \dim_compare:nNnT {#1} #2 {#3} - { \dim_do_while:nNnn {#1} #2 {#3} {#4} } - } -\cs_new:Npn \dim_do_until:nNnn #1#2#3#4 - { - #4 - \dim_compare:nNnF {#1} #2 {#3} - { \dim_do_until:nNnn {#1} #2 {#3} {#4} } - } -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% -% \subsection{Dimension step functions} -% -% \begin{macro}{\dim_step_function:nnnN} -% \begin{macro}{\@@_step:wwwN, \@@_step:NnnnN} -% Before all else, evaluate the initial value, step, and final value. -% Repeating a function by steps first needs a check on the direction -% of the steps. After that, do the function for the start value then -% step and loop around. It would be more symmetrical to test for a -% step size of zero before checking the sign, but we optimize for the -% most frequent case (positive step). -% \begin{macrocode} -\cs_new:Npn \dim_step_function:nnnN #1#2#3 - { - \exp_after:wN \@@_step:wwwN - \tex_the:D \@@_eval:w #1 \exp_after:wN ; - \tex_the:D \@@_eval:w #2 \exp_after:wN ; - \tex_the:D \@@_eval:w #3 ; - } -\cs_new:Npn \@@_step:wwwN #1; #2; #3; #4 - { - \dim_compare:nNnTF {#2} > \c_zero_dim - { \@@_step:NnnnN > } - { - \dim_compare:nNnTF {#2} = \c_zero_dim - { - \msg_expandable_error:nnn { kernel } { zero-step } {#4} - \use_none:nnnn - } - { \@@_step:NnnnN < } - } - {#1} {#2} {#3} #4 - } -\cs_new:Npn \@@_step:NnnnN #1#2#3#4#5 - { - \dim_compare:nNnF {#2} #1 {#4} - { - #5 {#2} - \exp_args:NNf \@@_step:NnnnN - #1 { \dim_eval:n { #2 + #3 } } {#3} {#4} #5 - } - } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\dim_step_inline:nnnn} -% \begin{macro}{\dim_step_variable:nnnNn} -% \begin{macro}{\@@_step:NNnnnn} -% The approach here is to build a function, with a global integer -% required to make the nesting safe (as seen in other in line -% functions), and map that function using \cs{dim_step_function:nnnN}. -% We put a \cs{prg_break_point:Nn} so that \texttt{map_break} -% functions from other modules correctly decrement \cs{g__kernel_prg_map_int} -% before looking for their own break point. The first argument is -% \cs{scan_stop:}, so that no breaking function recognizes this break -% point as its own. -% \begin{macrocode} -\cs_new_protected:Npn \dim_step_inline:nnnn - { - \int_gincr:N \g__kernel_prg_map_int - \exp_args:NNc \@@_step:NNnnnn - \cs_gset_protected:Npn - { @@_map_ \int_use:N \g__kernel_prg_map_int :w } - } -\cs_new_protected:Npn \dim_step_variable:nnnNn #1#2#3#4#5 - { - \int_gincr:N \g__kernel_prg_map_int - \exp_args:NNc \@@_step:NNnnnn - \cs_gset_protected:Npe - { @@_map_ \int_use:N \g__kernel_prg_map_int :w } - {#1}{#2}{#3} - { - \tl_set:Nn \exp_not:N #4 {##1} - \exp_not:n {#5} - } - } -\cs_new_protected:Npn \@@_step:NNnnnn #1#2#3#4#5#6 - { - #1 #2 ##1 {#6} - \dim_step_function:nnnN {#3} {#4} {#5} #2 - \prg_break_point:Nn \scan_stop: { \int_gdecr:N \g__kernel_prg_map_int } - } -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% -% \subsection{Using \texttt{dim} expressions and variables} -% -% \begin{macro}{\dim_eval:n} -% Evaluating a dimension expression expandably. -% \begin{macrocode} -\cs_new:Npn \dim_eval:n #1 - { \dim_use:N \@@_eval:w #1 \@@_eval_end: } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}[EXP]{\dim_sign:n, \@@_sign:Nw} -% See \cs{dim_abs:n}. Contrarily to \cs{int_sign:n} the case of a -% zero dimension cannot be distinguished from a positive dimension by -% looking only at the first character, since |0.2pt| and |0pt| start -% the same way. We need explicit comparisons. We start by -% distinguishing the most common case of a positive dimension. -% \begin{macrocode} -\cs_new:Npn \dim_sign:n #1 - { - \int_value:w \exp_after:wN \@@_sign:Nw - \dim_use:N \@@_eval:w #1 \@@_eval_end: ; - \exp_stop_f: - } -\cs_new:Npn \@@_sign:Nw #1#2 ; - { - \if_dim:w #1#2 > \c_zero_dim - 1 - \else: - \if_meaning:w - #1 - -1 - \else: - 0 - \fi: - \fi: - } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\dim_use:N, \dim_use:c} -% Accessing a \meta{dim}. We hand-code the |c| variant for some speed gain. -% \begin{macrocode} -\cs_new_eq:NN \dim_use:N \tex_the:D -\cs_new:Npn \dim_use:c #1 { \tex_the:D \cs:w #1 \cs_end: } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}[EXP]{\dim_to_decimal:n} -% \begin{macro}[EXP]{\@@_to_decimal:w} -% A function which comes up often enough to deserve a place in the -% kernel. Evaluate the dimension expression~|#1| then remove the -% trailing \texttt{pt}. When debugging is enabled, the argument is -% put in parentheses as this prevents the dimension expression from -% terminating early and leaving extra tokens lying around. This is -% used a lot by low-level manipulations. -% \begin{macrocode} -\cs_new:Npn \dim_to_decimal:n #1 - { - \exp_after:wN - \@@_to_decimal:w \dim_use:N \@@_eval:w #1 \@@_eval_end: - } -\use:e - { - \cs_new:Npn \exp_not:N \@@_to_decimal:w - #1 . #2 \tl_to_str:n { pt } - } - { - \int_compare:nNnTF {#2} > \c_zero_int - { #1 . #2 } - { #1 } - } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}[EXP]{\dim_to_fp:n} -% Defined in \pkg{l3fp-convert}, documented here. -% \end{macro} -% -% \subsection{Conversion of \texttt{dim} to other units} -% -% The conversion from \texttt{pt} or \texttt{sp} to other units is complicated -% by the fact that \TeX{}'s conversion to \texttt{sp} involves rounding and -% hard-coded ratios. In order to give re-entrant outcomes, we therefore need -% to do quite a bit of work: see -% \url{https://github.com/latex3/latex3/issues/954} for detailed discussion. -% After dealing with the trivial case, we therefore have some work to do. -% The code to do this is contributed by Ruixi Zhang. -% -% \begin{macro}[EXP]{\dim_to_decimal_in_sp:n} -% The one easy case: the only requirement here is that we avoid an -% overflow. -% \begin{macrocode} -\cs_new:Npn \dim_to_decimal_in_sp:n #1 - { \int_value:w \@@_eval:w #1 \@@_eval_end: } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}[EXP] -% { -% \dim_to_decimal_in_bp:n , -% \dim_to_decimal_in_cc:n , -% \dim_to_decimal_in_cm:n , -% \dim_to_decimal_in_dd:n , -% \dim_to_decimal_in_in:n , -% \dim_to_decimal_in_mm:n , -% \dim_to_decimal_in_pc:n -% } -% \begin{macro}[EXP]{\@@_to_decimal_aux:w} -% We first set up a helper macro \cs[no-index]{@@_tmp:w} which takes two -% arguments. The first argument is one of the following engine-defined -% units: |in|,~|pc|, |cm|, |mm|, |bp|, |dd|, |cc|, |nd|, and~|nc|. -% The second argument is $\frac{1}{2}\delta^{-1}$ in reduced fraction, -% where $\delta>1$~is the engine-defined conversion factor for each unit. -% Note that $\delta$~must be strictly larger than~$1$ for the following -% algorithm to work. -% -% Here is how the algorithm works: Suppose that a user inputs a -% non-negative dimension in a unit that has conversion factor~$\delta>1$. -% Then this dimension is internally represented as $X$\,sp, where -% $X=\lfloor N\delta\rfloor$ for some integer $N\ge0$. We then seek a -% formula to express this $N$ using~$X$. -% The \cs[no-index]{dim_to_decimal_in_<unit>:n} functions shall return -% the number $N/2^{16}$ in decimal. This way, we guarantee the returned -% decimal followed by the original unit will parse to exactly~$X$\,sp. -% -% So how do we get $N$ from~$X$? Well, since $X=\lfloor N\delta\rfloor$, -% we have $X\le N\delta<X+1$ and $X\delta^{-1}\le N<(X+1)\delta^{-1}$. -% Let's focus on the midpoint of this bounding interval for~$N$. The -% midpoint is $(X+\frac{1}{2})\delta^{-1}$. The fact $\delta>1$ implies -% that the bounding interval is shorter than~$1$ in length. Thus, -% (1)~$\hbox{midpoint}+\frac{1}{2}>N$ and -% (2)~$\hbox{midpoint}+\frac{1}{2}<N+1$. In other words, -% $N=\lfloor\hbox{midpoint}+\frac{1}{2}\rfloor$. As long as we can -% rewrite the midpoint as the result of a \enquote{scaling operation} of \eTeX, -% the $\lfloor\ldots+\frac{1}{2}\rfloor$ part will follow naturally. -% Indeed we can: $\hbox{midpoint}=(2X+1)\times(\frac{1}{2}\delta^{-1})$. -% -% Addendum: If $\delta\ge2$, then the bounding interval for~$N$ is at -% most~$\frac{1}{2}$ wide in length. In this case, the leftpoint -% $X\delta^{-1}$ suffices as $N=\lfloor X\delta^{-1}+\frac{1}{2}\rfloor$. -% Six out of the nine units listed above can be handled in this way, -% which is much simpler than using midpoint. But three remaining units -% have $1<\delta<2$; they are |bp|~($\delta=7227/7200$), -% |nd|~($\delta=685/642$), and |dd|~($\delta=1238/1157$), -% and these three must be handled using midpoint. -% For consistency, we shall use the midpoint approach for all nine units. -% \begin{macrocode} -\group_begin: - \cs_set_protected:Npn \@@_tmp:w #1#2 - { - \cs_new:cpn { dim_to_decimal_in_ #1 :n } ##1 - { - \exp_after:wN \@@_to_decimal_aux:w - \int_value:w \@@_eval:w ##1 \@@_eval_end: ; #2 ; - } - } -% \end{macrocode} -% Conversions to other units are now coded. -% Consult the pdf\/\TeX{} source for each conversion factor~$\delta$. -% Each factor $\frac{1}{2}\delta^{-1}$ is hand-coded -% for accuracy (and speed). As the units \texttt{nc} and \texttt{nd} -% are not supported by \XeTeX{} or (u)p\TeX{}, they are not included -% here. -% \begin{macrocode} - \@@_tmp:w { in } { 50 / 7227 } % delta = 7227/100 - \@@_tmp:w { pc } { 1 / 24 } % delta = 12/1 - \@@_tmp:w { cm } { 127 / 7227 } % delta = 7227/254 - \@@_tmp:w { mm } { 1270 / 7227 } % delta = 7227/2540 - \@@_tmp:w { bp } { 400 / 803 } % delta = 7227/7200 - \@@_tmp:w { dd } { 1157 / 2476 } % delta = 1238/1157 - \@@_tmp:w { cc } { 1157 / 29712 } % delta = 14856/1157 -\group_end: -% \end{macrocode} -% The tokens after \cs{@@_to_decimal_aux:w} shall have the following form: -% |<number>;<half of delta inverse>;|, where |<number>| represents the -% input dimension in |sp| unit. -% If |<number>| is positive, then |#1| is its leading digit and |#2| -% (possibly empty) is all the remaining digits; -% If |<number>| is zero, then |#1| is~|0|$_{12}$ and |#2| is empty; -% If |<number>| is negative, then |#1| is its sign~|-|$_{12}$ and |#2| -% is all its digits. -% In all three cases, |#1#2| is the original |<number>|. We can use |#1| -% to decide whether to use the |-1| formula or the |+1| formula. -% \begin{macrocode} -\cs_new:Npn \@@_to_decimal_aux:w #1#2 ; #3 ; - { - \dim_to_decimal:n - { -% \end{macrocode} -% We need different formulae depending on whether the user input dimension -% is negative or not. -% For negative dimension (internally represented as $X$\,sp), the formula -% is $(2X-1)\times(\frac{1}{2}\delta^{-1})$. -% For non-negative dimension, the formula -% is $(2X+1)\times(\frac{1}{2}\delta^{-1})$. -% The intermediate step doubles the dimension~$X$. -% To avoid overflow, we must invoke \cs[no-index]{int_eval:n}. -% \begin{macrocode} - \int_eval:n - { ( 2 * #1#2 \if:w #1 - - \else: + \fi: 1 ) * #3 } -% \end{macrocode} -% Now we append~|sp| to finish the dimension specification. -% \begin{macrocode} - sp - } - } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}[EXP]{\dim_to_decimal_in_unit:nn} -% \begin{macrocode} -\cs_new:Npn \dim_to_decimal_in_unit:nn #1#2 - { - \exp_after:wN \@@_chk_unit:w - \int_value:w \@@_eval:w #2 \@@_eval_end: ; {#1} - } -% \end{macrocode} -% \end{macro} -% \begin{macro}[EXP]{\@@_chk_unit:w} -% The tokens after \cs{@@_chk_unit:w} shall have the following form: -% |<number2>;{<dimexpr1>}|, where |<number2>| represents |<dimexpr2>| in -% |sp| unit. -% If |#1| is~|0|$_{12}$, the \enquote{unit} |<dimexpr2>| must also be zero. -% So we throw out a \enquote{division by zero} error message at this point. -% Otherwise, if |#1| is~|-|$_{12}$, we shall negate both |<dimexpr1>| and -% |<dimexpr2>| for later procedures. -% \begin{macrocode} -\cs_new:Npn \@@_chk_unit:w #1#2;#3 - { - \token_if_eq_charcode:NNTF #1 0 - { \msg_expandable_error:nn { dim } { zero-unit } } - { - \exp_after:wN \@@_branch_unit:w - \int_value:w \if:w #1 - - \fi: \@@_eval:w #3 \exp_after:wN ; - \int_value:w \if:w #1 - - \fi: #1#2 ; - } - } -% \end{macrocode} -% \end{macro} -% \begin{macro}[EXP]{\@@_branch_unit:w} -% The tokens after \cs{@@_branch_unit:w} shall have the following form: -% |<number1>;<number2>;|, where |<number1>| represents |<dimexpr1>| in -% |sp| unit (whose sign is taken care of) and |<number2>| represents the -% absolute value of |<dimexpr2>| in |sp| unit (which is strictly positive). -% -% As explained, the formulae $(2X\pm1)\times(\frac{1}{2}\delta^{-1})$ work -% if and only if $\delta=|<number2>|/65536>1$. This corresponds to -% |<dimexpr2>| strictly larger than 1\,pt in absolute value. -% In this case, we simply call \cs{@@_to_decimal_aux:w} and supply -% $\frac{1}{2}\delta^{-1}=32768/|<number2>|$ as |<half of delta inverse>|. -% -% Otherwise if $|<number2>|=65536$, then |<dimexpr2>| is 1\,pt in absolute -% value and we call \cs{dim_to_decimal:n} directly. -% -% Otherwise $0<|<number2>|<65536$ and we shall proceed differently. -% -% For unit less than 1\,pt, write $n=|<number2>|$, then $\delta=n/65536<1$. -% The midpoint formulae are not optimal. Let's go back to the inequalities -% $X\delta^{-1}\le N<(X+1)\delta^{-1}$. Since now $\delta<1$, the bounding -% interval is wider than~$1$ in length. Consider the ceiling integer -% $M=\lceil X\delta^{-1}\rceil$, then $X\delta^{-1}\le M<(X+1)\delta^{-1}$, -% or equivalently $X\le M\delta<X+1$, and thus $\lfloor M\delta\rfloor=X$. -% The key point here is that we \emph{don't} need to solve for~$N$; -% in fact, any integer that can reproduce~$X$ (such as~$M$) is good enough. -% So the algorithm goes like this: (1)~Compute rounding of $X\delta^{-1}$, -% i.e., $M'=\lfloor X\delta^{-1}+\frac{1}{2}\rfloor$; this $M'$ could be -% either $M$ or $M-1$. (2)~Check if $\lfloor M'\delta\rfloor=X$, i.e., -% whether our candidate $M'$ can reproduce~$X$. If so, then this $M'$ is -% good enough; if not, then we add one to~$M'$. -% -% But when $0<n<65536$, we cannot delay the problem of overflow any more. -% For $X\delta^{-1}=X\times65536/n$, where $X$ can go up to $2^{30}-1$ and -% $n$ can be as small as~$1$, the result is well over $2^{31}-1$ (largest -% integer allowed within |\numexpr|). -% For example, |\dim_to_decimal_in_unit:nn { \maxdimen } { 1sp }|. -% Here, all inputs are legal, so we should be able to output |1073741823| -% \emph{without} causing arithmetic overflow. -% -% As a workaround, let's write $X=qn+r$ with some $q\ge0$ and $0\le r<n$. -% Then $X\delta^{-1}=65536q+65536r/n$, and so -% $M'=65536q+\lfloor65536r/n+\frac{1}{2}\rfloor=65536q+R'$. -% Computing $R'$ will never overflow. If this $R'$ can reproduce~$r$, then -% it is good enough; otherwise we add one to~$R'$. In the end, we shall -% output $q+R'/65536$ in decimal. -% -% Note: $q=\lfloor X/n\rfloor=\lfloor\frac{2X-n}{2n}+\frac{1}{2}\rfloor$ -% represents the \enquote{integer} part, while $0\le R'\le65536$ represents the -% \enquote{fractional} part. (Can $R'=65536$ really happen? Didn't investigate.) -% \begin{macrocode} -\cs_new:Npn \@@_branch_unit:w #1;#2; - { - \int_compare:nNnTF {#2} > { 65536 } - { \@@_to_decimal_aux:w #1 ; 32768 / #2 ; } - { - \int_compare:nNnTF {#2} = { 65536 } - { \dim_to_decimal:n { #1sp } } - { \@@_get_quotient:w #1 ; #2 ; } - } - } -% \end{macrocode} -% \end{macro} -% \begin{macro}[EXP]{\@@_get_quotient:w} -% We wish to get the quotient $q$ via rounding of $\frac{2X-n}{2n}$. -% When $0\le X<n/2$, we have $\frac{2X-n}{2n}<0$. So, strictly speaking, -% |\numexpr| performs its rounding as -% $\lceil\frac{2X-n}{2n}-\frac{1}{2}\rceil$, not exactly what we want. -% However, lucky for us, only $X=0$ makes -% $\lceil\frac{2X-n}{2n}-\frac{1}{2}\rceil=-1\neq0$ (we want~$0$); -% all other $0<X<n/2$ make $\lceil\frac{2X-n}{2n}-\frac{1}{2}\rceil=0=q$. -% Thus, let's filter out $X=0$ early. -% If $X\neq0$, we extract its sign and leave the sign to the back. -% The sign does not participate in any calculations (also the code works -% with positive integers only). The sign is used at the last stages when -% we parse the decimal output. -% -% After \cs{@@_get_quotient:w} has done its job, either we have the -% decimal~|0|, or we have \cs{@@_get_remainder:w} followed by -% $q$|;|$\lvert X\rvert$|;|$n$|;<sign of X>;|. -% \begin{macrocode} -\cs_new:Npn \@@_get_quotient:w #1#2;#3; - { - \token_if_eq_charcode:NNTF #1 0 - { 0 } - { - \token_if_eq_charcode:NNTF #1 - - { - \exp_after:wN \exp_after:wN \exp_after:wN \@@_get_remainder:w - \int_eval:n { ( 2 * #2 - #3 ) / ( 2 * #3 ) } ; - #2 ; #3 ; - ; - } - { - \exp_after:wN \exp_after:wN \exp_after:wN \@@_get_remainder:w - \int_eval:n { ( 2 * #1#2 - #3 ) / ( 2 * #3 ) } ; - #1#2 ; #3 ; ; - } - } - } -% \end{macrocode} -% \end{macro} -% \begin{macro}[EXP]{\@@_get_remainder:w} -% \cs{@@_get_remainder:w} does not need to read the sign. -% After finding the remainder~$r$, the number~$\lvert X\rvert$ is no longer -% needed. We should then have \cs{@@_convert_remainder:w} followed by -% $r$|;|$n$|;|$q$|;<sign of X>;|. -% \begin{macrocode} -\cs_new:Npn \@@_get_remainder:w #1;#2;#3; - { - \exp_after:wN \exp_after:wN \exp_after:wN \@@_convert_remainder:w - \int_eval:n { #2 - #1 * #3 } ; - #3 ; #1 ; - } -% \end{macrocode} -% \end{macro} -% \begin{macro}[EXP]{\@@_convert_remainder:w} -% This is trivial. We compute $R'=\lfloor65536r/n+\frac{1}{2}\rfloor$, -% then leave \cs{@@_test_candidate:w} followed by -% $R'$|;|$r$|;|$n$|;|$q$|;<sign of X>;|. -% \begin{macrocode} -\cs_new:Npn \@@_convert_remainder:w #1;#2; - { - \exp_after:wN \exp_after:wN \exp_after:wN \@@_test_candidate:w - \int_eval:n { #1 * 65536 / #2 } ; - #1 ; #2 ; - } -% \end{macrocode} -% \end{macro} -% \begin{macro}[EXP]{\@@_test_candidate:w} -% Now the fun part: We take $R'$, $r$ and~$n$ to test whether -% $r=\lfloor R'\delta\rfloor$. This is done as a dimension comparison. -% The left-hand side, $r$, is simply |r sp|. The right-hand side, -% $\lfloor R'\delta\rfloor$, is exactly |<R' as decimal><dimen = n sp>|. -% If the result is true, then we've found~$R'$; -% otherwise we add one to~$R'$. -% After this step, $r$ and~$n$ are no longer needed. We should then have -% \cs{@@_parse_decimal:w} followed by $R'$|;|$q$|;<sign of X>;|. -% \begin{macrocode} -\cs_new:Npn \@@_test_candidate:w #1;#2;#3; - { - \dim_compare:nNnTF { #2sp } = - { \dim_to_decimal:n { #1sp } \@@_eval:w #3sp \@@_eval_end: } - { \@@_parse_decimal:w #1 ; } - { - \@@_parse_decimal:w \int_eval:n { #1 + 1 } ; - } - } -% \end{macrocode} -% \end{macro} -% \begin{macro}[EXP]{\@@_parse_decimal:w, \@@_parse_decimal_aux:w} -% The Grand Finale: We sum $q$ and $R'/65536$ together, and negate the -% result if necessary. These are all done expandably. -% If $0<R'/65536<1$, the integer summation is naturally terminated at the -% decimal point. If $R'/65536=0$ (or~$1$?), the summation is terminated -% at the semicolon. The auxiliary function \cs{@@_parse_decimal_aux:w} -% takes care of both cases. -% \begin{macrocode} -\cs_new:Npn \@@_parse_decimal:w #1;#2;#3; - { - \exp_after:wN \@@_parse_decimal_aux:w - \int_value:w #3 \int_eval:w #2 + \dim_to_decimal:n { #1sp } ; - } -\cs_new:Npn \@@_parse_decimal_aux:w #1 ; {#1} -% \end{macrocode} -% \end{macro} -% -% \subsection{Viewing \texttt{dim} variables} -% -% \begin{macro}{\dim_show:N, \dim_show:c} -% Diagnostics. -% \begin{macrocode} -\cs_new_eq:NN \dim_show:N \__kernel_register_show:N -\cs_generate_variant:Nn \dim_show:N { c } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\dim_show:n} -% Diagnostics. We don't use the \TeX{} primitive \tn{showthe} to show -% dimension expressions: this gives a more unified output. -% \begin{macrocode} -\cs_new_protected:Npn \dim_show:n - { \__kernel_msg_show_eval:Nn \dim_eval:n } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\dim_log:N, \dim_log:c, \dim_log:n} -% Diagnostics. Redirect output of \cs{dim_show:n} to the log. -% \begin{macrocode} -\cs_new_eq:NN \dim_log:N \__kernel_register_log:N -\cs_new_eq:NN \dim_log:c \__kernel_register_log:c -\cs_new_protected:Npn \dim_log:n - { \__kernel_msg_log_eval:Nn \dim_eval:n } -% \end{macrocode} -% \end{macro} -% -% \subsection{Constant dimensions} -% -% \begin{variable}{\c_zero_dim, \c_max_dim} -% Constant dimensions. -% \begin{macrocode} -\dim_const:Nn \c_zero_dim { 0 pt } -\dim_const:Nn \c_max_dim { 16383.99999 pt } -% \end{macrocode} -% \end{variable} -% -% \subsection{Scratch dimensions} -% -% \begin{variable}{\l_tmpa_dim, \l_tmpb_dim} -% \begin{variable}{\g_tmpa_dim, \g_tmpb_dim} -% We provide two local and two global scratch registers, maybe we -% need more or less. -% \begin{macrocode} -\dim_new:N \l_tmpa_dim -\dim_new:N \l_tmpb_dim -\dim_new:N \g_tmpa_dim -\dim_new:N \g_tmpb_dim -% \end{macrocode} -% \end{variable} -% \end{variable} -% -% \subsection{Creating and initialising \texttt{skip} variables} -% -% \begin{macrocode} -%<@@=skip> -% \end{macrocode} -% -% \begin{variable}{\s_@@_stop} -% Internal scan marks. -% \begin{macrocode} -\scan_new:N \s_@@_stop -% \end{macrocode} -% \end{variable} -% -% \begin{macro}{\skip_new:N, \skip_new:c} -% Allocation of a new internal registers. -% \begin{macrocode} -\cs_new_protected:Npn \skip_new:N #1 - { - \__kernel_chk_if_free_cs:N #1 - \cs:w newskip \cs_end: #1 - } -\cs_generate_variant:Nn \skip_new:N { c } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\skip_const:Nn, \skip_const:cn} -% Contrarily to integer constants, we cannot avoid using a register, -% even for constants. See \cs{dim_const:Nn} for why we cannot use -% \cs{skip_gset:Nn}. -% \begin{macrocode} -\cs_new_protected:Npn \skip_const:Nn #1#2 - { - \skip_new:N #1 - \tex_global:D #1 = \skip_eval:n {#2} \scan_stop: - } -\cs_generate_variant:Nn \skip_const:Nn { c } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\skip_zero:N, \skip_zero:c} -% \begin{macro}{\skip_gzero:N, \skip_gzero:c} -% Reset the register to zero. -% \begin{macrocode} -\cs_new_eq:NN \skip_zero:N \dim_zero:N -\cs_new_eq:NN \skip_gzero:N \dim_gzero:N -\cs_generate_variant:Nn \skip_zero:N { c } -\cs_generate_variant:Nn \skip_gzero:N { c } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro} -% {\skip_zero_new:N, \skip_zero_new:c, \skip_gzero_new:N, \skip_gzero_new:c} -% Create a register if needed, otherwise clear it. -% \begin{macrocode} -\cs_new_protected:Npn \skip_zero_new:N #1 - { \skip_if_exist:NTF #1 { \skip_zero:N #1 } { \skip_new:N #1 } } -\cs_new_protected:Npn \skip_gzero_new:N #1 - { \skip_if_exist:NTF #1 { \skip_gzero:N #1 } { \skip_new:N #1 } } -\cs_generate_variant:Nn \skip_zero_new:N { c } -\cs_generate_variant:Nn \skip_gzero_new:N { c } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}[pTF]{\skip_if_exist:N, \skip_if_exist:c} -% Copies of the \texttt{cs} functions defined in \pkg{l3basics}. -% \begin{macrocode} -\prg_new_eq_conditional:NNn \skip_if_exist:N \cs_if_exist:N - { TF , T , F , p } -\prg_new_eq_conditional:NNn \skip_if_exist:c \cs_if_exist:c - { TF , T , F , p } -% \end{macrocode} -% \end{macro} -% -% \subsection{Setting \texttt{skip} variables} -% -% \begin{macro}{\skip_set:Nn, \skip_set:cn} -% \begin{macro}{\skip_gset:Nn, \skip_gset:cn} -% Much the same as for dimensions. -% \begin{macrocode} -\cs_new_protected:Npn \skip_set:Nn #1#2 - { #1 = \tex_glueexpr:D #2 \scan_stop: } -\cs_new_protected:Npn \skip_gset:Nn #1#2 - { \tex_global:D #1 = \tex_glueexpr:D #2 \scan_stop: } -\cs_generate_variant:Nn \skip_set:Nn { c } -\cs_generate_variant:Nn \skip_gset:Nn { c } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro} -% {\skip_set_eq:NN, \skip_set_eq:cN, \skip_set_eq:Nc, \skip_set_eq:cc} -% \begin{macro} -% {\skip_gset_eq:NN, \skip_gset_eq:cN, \skip_gset_eq:Nc, \skip_gset_eq:cc} -% All straightforward. -% \begin{macrocode} -\cs_new_protected:Npn \skip_set_eq:NN #1#2 { #1 = #2 } -\cs_generate_variant:Nn \skip_set_eq:NN { c , Nc , cc } -\cs_new_protected:Npn \skip_gset_eq:NN #1#2 { \tex_global:D #1 = #2 } -\cs_generate_variant:Nn \skip_gset_eq:NN { c , Nc , cc } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\skip_add:Nn, \skip_add:cn} -% \begin{macro}{\skip_gadd:Nn, \skip_gadd:cn} -% \begin{macro}{\skip_sub:Nn, \skip_sub:cn} -% \begin{macro}{\skip_gsub:Nn, \skip_gsub:cn} -% Using |by| here deals with the (incorrect) case |\skip123|. -% \begin{macrocode} -\cs_new_protected:Npn \skip_add:Nn #1#2 - { \tex_advance:D #1 \tex_glueexpr:D #2 \scan_stop: } -\cs_new_protected:Npn \skip_gadd:Nn #1#2 - { \tex_global:D \tex_advance:D #1 \tex_glueexpr:D #2 \scan_stop: } -\cs_generate_variant:Nn \skip_add:Nn { c } -\cs_generate_variant:Nn \skip_gadd:Nn { c } -\cs_new_protected:Npn \skip_sub:Nn #1#2 - { \tex_advance:D #1 - \tex_glueexpr:D #2 \scan_stop: } -\cs_new_protected:Npn \skip_gsub:Nn #1#2 - { \tex_global:D \tex_advance:D #1 - \tex_glueexpr:D #2 \scan_stop: } -\cs_generate_variant:Nn \skip_sub:Nn { c } -\cs_generate_variant:Nn \skip_gsub:Nn { c } -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% -% \subsection{Skip expression conditionals} -% -% \begin{macro}[pTF]{\skip_if_eq:nn} -% Comparing skips means doing two expansions to make strings, and then -% testing them. As a result, only equality is tested. -% \begin{macrocode} -\prg_new_conditional:Npnn \skip_if_eq:nn #1#2 { p , T , F , TF } - { - \str_if_eq:eeTF { \skip_eval:n {#1} } { \skip_eval:n {#2} } - { \prg_return_true: } - { \prg_return_false: } - } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}[EXP,pTF]{\skip_if_finite:n} -% \begin{macro}[EXP]{\@@_if_finite:wwNw} -% With \eTeX{}, we have an easy access to the order of infinities of -% the stretch and shrink components of a skip. However, to access -% both, we either need to evaluate the expression twice, or evaluate -% it, then call an auxiliary to extract both pieces of information -% from the result. Since we are going to need an auxiliary anyways, -% it is quicker to make it search for the string \texttt{fil} which -% characterizes infinite glue. -% \begin{macrocode} -\cs_set_protected:Npn \@@_tmp:w #1 - { - \prg_new_conditional:Npnn \skip_if_finite:n ##1 { p , T , F , TF } - { - \exp_after:wN \@@_if_finite:wwNw - \skip_use:N \tex_glueexpr:D ##1 ; \prg_return_false: - #1 ; \prg_return_true: \s_@@_stop - } - \cs_new:Npn \@@_if_finite:wwNw ##1 #1 ##2 ; ##3 ##4 \s_@@_stop {##3} - } -\exp_args:No \@@_tmp:w { \tl_to_str:n { fil } } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \subsection{Using \texttt{skip} expressions and variables} -% -% \begin{macro}{\skip_eval:n} -% Evaluating a skip expression expandably. -% \begin{macrocode} -\cs_new:Npn \skip_eval:n #1 - { \skip_use:N \tex_glueexpr:D #1 \scan_stop: } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\skip_use:N, \skip_use:c} -% Accessing a \meta{skip}. -% \begin{macrocode} -\cs_new_eq:NN \skip_use:N \dim_use:N -\cs_new_eq:NN \skip_use:c \dim_use:c -% \end{macrocode} -% \end{macro} -% -% \subsection{Inserting skips into the output} -% -% \begin{macro}{\skip_horizontal:N, \skip_horizontal:c, \skip_horizontal:n} -% \begin{macro}{\skip_vertical:N, \skip_vertical:c, \skip_vertical:n} -% Inserting skips. -% \begin{macrocode} -\cs_new_eq:NN \skip_horizontal:N \tex_hskip:D -\cs_new:Npn \skip_horizontal:n #1 - { \skip_horizontal:N \tex_glueexpr:D #1 \scan_stop: } -\cs_new_eq:NN \skip_vertical:N \tex_vskip:D -\cs_new:Npn \skip_vertical:n #1 - { \skip_vertical:N \tex_glueexpr:D #1 \scan_stop: } -\cs_generate_variant:Nn \skip_horizontal:N { c } -\cs_generate_variant:Nn \skip_vertical:N { c } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \subsection{Viewing \texttt{skip} variables} -% -% \begin{macro}{\skip_show:N, \skip_show:c} -% Diagnostics. -% \begin{macrocode} -\cs_new_eq:NN \skip_show:N \__kernel_register_show:N -\cs_generate_variant:Nn \skip_show:N { c } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\skip_show:n} -% Diagnostics. We don't use the \TeX{} primitive \tn{showthe} to show -% skip expressions: this gives a more unified output. -% \begin{macrocode} -\cs_new_protected:Npn \skip_show:n - { \__kernel_msg_show_eval:Nn \skip_eval:n } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\skip_log:N, \skip_log:c, \skip_log:n} -% Diagnostics. Redirect output of \cs{skip_show:n} to the log. -% \begin{macrocode} -\cs_new_eq:NN \skip_log:N \__kernel_register_log:N -\cs_new_eq:NN \skip_log:c \__kernel_register_log:c -\cs_new_protected:Npn \skip_log:n - { \__kernel_msg_log_eval:Nn \skip_eval:n } -% \end{macrocode} -% \end{macro} -% -% \subsection{Constant skips} -% -% \begin{macro}{\c_zero_skip, \c_max_skip} -% Skips with no rubber component are just dimensions but need to terminate -% correctly. -% \begin{macrocode} -\skip_const:Nn \c_zero_skip { \c_zero_dim } -\skip_const:Nn \c_max_skip { \c_max_dim } -% \end{macrocode} -% \end{macro} -% -% \subsection{Scratch skips} -% -% \begin{variable}{\l_tmpa_skip, \l_tmpb_skip} -% \begin{variable}{\g_tmpa_skip, \g_tmpb_skip} -% We provide two local and two global scratch registers, maybe we -% need more or less. -% \begin{macrocode} -\skip_new:N \l_tmpa_skip -\skip_new:N \l_tmpb_skip -\skip_new:N \g_tmpa_skip -\skip_new:N \g_tmpb_skip -% \end{macrocode} -% \end{variable} -% \end{variable} -% -% \subsection{Creating and initialising \texttt{muskip} variables} -% -% \begin{macro}{\muskip_new:N, \muskip_new:c} -% And then we add muskips. -% \begin{macrocode} -\cs_new_protected:Npn \muskip_new:N #1 - { - \__kernel_chk_if_free_cs:N #1 - \cs:w newmuskip \cs_end: #1 - } -\cs_generate_variant:Nn \muskip_new:N { c } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\muskip_const:Nn, \muskip_const:cn} -% See \cs{skip_const:Nn}. -% \begin{macrocode} -\cs_new_protected:Npn \muskip_const:Nn #1#2 - { - \muskip_new:N #1 - \tex_global:D #1 = \muskip_eval:n {#2} \scan_stop: - } -\cs_generate_variant:Nn \muskip_const:Nn { c } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\muskip_zero:N, \muskip_zero:c} -% \begin{macro}{\muskip_gzero:N, \muskip_gzero:c} -% Reset the register to zero. -% \begin{macrocode} -\cs_new_protected:Npn \muskip_zero:N #1 - { #1 = \c_zero_muskip } -\cs_new_protected:Npn \muskip_gzero:N #1 - { \tex_global:D #1 = \c_zero_muskip } -\cs_generate_variant:Nn \muskip_zero:N { c } -\cs_generate_variant:Nn \muskip_gzero:N { c } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro} -% { -% \muskip_zero_new:N, \muskip_zero_new:c, -% \muskip_gzero_new:N, \muskip_gzero_new:c -% } -% Create a register if needed, otherwise clear it. -% \begin{macrocode} -\cs_new_protected:Npn \muskip_zero_new:N #1 - { \muskip_if_exist:NTF #1 { \muskip_zero:N #1 } { \muskip_new:N #1 } } -\cs_new_protected:Npn \muskip_gzero_new:N #1 - { \muskip_if_exist:NTF #1 { \muskip_gzero:N #1 } { \muskip_new:N #1 } } -\cs_generate_variant:Nn \muskip_zero_new:N { c } -\cs_generate_variant:Nn \muskip_gzero_new:N { c } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}[pTF]{\muskip_if_exist:N, \muskip_if_exist:c} -% Copies of the \texttt{cs} functions defined in \pkg{l3basics}. -% \begin{macrocode} -\prg_new_eq_conditional:NNn \muskip_if_exist:N \cs_if_exist:N - { TF , T , F , p } -\prg_new_eq_conditional:NNn \muskip_if_exist:c \cs_if_exist:c - { TF , T , F , p } -% \end{macrocode} -% \end{macro} -% -% \subsection{Setting \texttt{muskip} variables} -% -% \begin{macro}{\muskip_set:Nn, \muskip_set:cn} -% \begin{macro}{\muskip_gset:Nn, \muskip_gset:cn} -% This should be pretty familiar. -% \begin{macrocode} -\cs_new_protected:Npn \muskip_set:Nn #1#2 - { #1 = \tex_muexpr:D #2 \scan_stop: } -\cs_new_protected:Npn \muskip_gset:Nn #1#2 - { \tex_global:D #1 = \tex_muexpr:D #2 \scan_stop: } -\cs_generate_variant:Nn \muskip_set:Nn { c } -\cs_generate_variant:Nn \muskip_gset:Nn { c } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro} -% { -% \muskip_set_eq:NN, \muskip_set_eq:cN, -% \muskip_set_eq:Nc, \muskip_set_eq:cc -% } -% \begin{macro} -% { -% \muskip_gset_eq:NN, \muskip_gset_eq:cN, -% \muskip_gset_eq:Nc, \muskip_gset_eq:cc -% } -% All straightforward. -% \begin{macrocode} -\cs_new_protected:Npn \muskip_set_eq:NN #1#2 { #1 = #2 } -\cs_generate_variant:Nn \muskip_set_eq:NN { c , Nc , cc } -\cs_new_protected:Npn \muskip_gset_eq:NN #1#2 { \tex_global:D #1 = #2 } -\cs_generate_variant:Nn \muskip_gset_eq:NN { c , Nc , cc } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\muskip_add:Nn, \muskip_add:cn} -% \begin{macro}{\muskip_gadd:Nn, \muskip_gadd:cn} -% \begin{macro}{\muskip_sub:Nn, \muskip_sub:cn} -% \begin{macro}{\muskip_gsub:Nn, \muskip_gsub:cn} -% Using |by| here deals with the (incorrect) case |\muskip123|. -% \begin{macrocode} -\cs_new_protected:Npn \muskip_add:Nn #1#2 - { \tex_advance:D #1 \tex_muexpr:D #2 \scan_stop: } -\cs_new_protected:Npn \muskip_gadd:Nn #1#2 - { \tex_global:D \tex_advance:D #1 \tex_muexpr:D #2 \scan_stop: } -\cs_generate_variant:Nn \muskip_add:Nn { c } -\cs_generate_variant:Nn \muskip_gadd:Nn { c } -\cs_new_protected:Npn \muskip_sub:Nn #1#2 - { \tex_advance:D #1 - \tex_muexpr:D #2 \scan_stop: } -\cs_new_protected:Npn \muskip_gsub:Nn #1#2 - { \tex_global:D \tex_advance:D #1 - \tex_muexpr:D #2 \scan_stop: } -\cs_generate_variant:Nn \muskip_sub:Nn { c } -\cs_generate_variant:Nn \muskip_gsub:Nn { c } -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% -% \subsection{Using \texttt{muskip} expressions and variables} -% -% \begin{macro}{\muskip_eval:n} -% Evaluating a muskip expression expandably. -% \begin{macrocode} -\cs_new:Npn \muskip_eval:n #1 - { \muskip_use:N \tex_muexpr:D #1 \scan_stop: } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\muskip_use:N, \muskip_use:c} -% Accessing a \meta{muskip}. -% \begin{macrocode} -\cs_new_eq:NN \muskip_use:N \dim_use:N -\cs_new_eq:NN \muskip_use:c \dim_use:c -% \end{macrocode} -% \end{macro} -% -% \subsection{Viewing \texttt{muskip} variables} -% -% \begin{macro}{\muskip_show:N, \muskip_show:c} -% Diagnostics. -% \begin{macrocode} -\cs_new_eq:NN \muskip_show:N \__kernel_register_show:N -\cs_generate_variant:Nn \muskip_show:N { c } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\muskip_show:n} -% Diagnostics. We don't use the \TeX{} primitive \tn{showthe} to show -% muskip expressions: this gives a more unified output. -% \begin{macrocode} -\cs_new_protected:Npn \muskip_show:n - { \__kernel_msg_show_eval:Nn \muskip_eval:n } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\muskip_log:N, \muskip_log:c, \muskip_log:n} -% Diagnostics. Redirect output of \cs{muskip_show:n} to the log. -% \begin{macrocode} -\cs_new_eq:NN \muskip_log:N \__kernel_register_log:N -\cs_new_eq:NN \muskip_log:c \__kernel_register_log:c -\cs_new_protected:Npn \muskip_log:n - { \__kernel_msg_log_eval:Nn \muskip_eval:n } -% \end{macrocode} -% \end{macro} -% -% \subsection{Constant muskips} -% -% \begin{macro}{\c_zero_muskip} -% \begin{macro}{\c_max_muskip} -% Constant muskips given by their value. -% \begin{macrocode} -\muskip_const:Nn \c_zero_muskip { 0 mu } -\muskip_const:Nn \c_max_muskip { 16383.99999 mu } -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \subsection{Scratch muskips} -% -% \begin{variable}{\l_tmpa_muskip, \l_tmpb_muskip} -% \begin{variable}{\g_tmpa_muskip, \g_tmpb_muskip} -% We provide two local and two global scratch registers, maybe we -% need more or less. -% \begin{macrocode} -\muskip_new:N \l_tmpa_muskip -\muskip_new:N \l_tmpb_muskip -\muskip_new:N \g_tmpa_muskip -\muskip_new:N \g_tmpb_muskip -% \end{macrocode} -% \end{variable} -% \end{variable} -% -% \begin{macrocode} -%</package> -% \end{macrocode} -% -% \end{implementation} -% -% \PrintIndex |