diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3skip.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3skip.dtx | 147 |
1 files changed, 112 insertions, 35 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3skip.dtx b/Master/texmf-dist/source/latex/l3kernel/l3skip.dtx index f773f3e2867..d977bc4cebd 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3skip.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3skip.dtx @@ -38,7 +38,7 @@ \documentclass[full]{l3doc} %</driver> %<*driver|package> -\GetIdInfo$Id: l3skip.dtx 4972 2014-05-31 16:42:18Z bruno $ +\GetIdInfo$Id: l3skip.dtx 5211 2014-07-17 07:22:35Z joseph $ {L3 Dimensions and skips} %</driver|package> %<*driver> @@ -437,6 +437,73 @@ % \end{texnote} % \end{function} % +% \begin{function}[added = 2014-07-15, EXP]{\dim_to_decimal:n} +% \begin{syntax} +% \cs{dim_to_decimal:n} \Arg{dimexpr} +% \end{syntax} +% Evaluates the \meta{dimension expression}, and leaves the result, +% expressed in points (\texttt{pt}) in the input stream, with \emph{no +% units}. The result is rounded by \TeX{} to four or 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, EXP]{\dim_to_decimal_in_bp:n} +% \begin{syntax} +% \cs{dim_to_decimal_in_bp:n} \Arg{dimexpr} +% \end{syntax} +% Evaluates the \meta{dimension expression}, 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 four or 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. +% \end{function} +% +% \begin{function}[added = 2014-07-15, EXP] +% {\dim_to_decimal_in_unit:nn} +% \begin{syntax} +% \cs{dim_to_decimal_in_unit:nn} \Arg{dimexpr_1} \Arg{dimexpr_2} +% \end{syntax} +% Evaluates the \meta{dimension expressions}, and leaves the value of +% \meta{dimexpr_1}, expressed in a unit given by \meta{dimexpr_2}, in +% the input stream. The result is a decimal number, rounded by \TeX{} +% to four or 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_unit:nn { 1bp } { 1mm } +% \end{verbatim} +% leaves |0.35277| in the input stream, \emph{i.e.}~the magnitude of +% one big point when converted to millimetres. +% \end{function} +% +% \begin{function}[EXP, added = 2012-05-08, tested = m3fp-convert002] +% {\dim_to_fp:n} +% \begin{syntax} +% \cs{dim_to_fp:n} \Arg{dimexpr} +% \end{syntax} +% Expands to an internal floating point number equal to the value of +% the \meta{dimexpr} 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 is acceptable. +% \end{function} +% % \section{Viewing \texttt{dim} variables} % % \begin{function}{\dim_show:N, \dim_show:c} @@ -900,25 +967,6 @@ % \end{texnote} % \end{function} % -% \begin{function}[added = 2011-11-11, updated=2014-05-31, EXP] -% {\__dim_strip_bp:n, \__dim_strip_pt:n} -% \begin{syntax} -% \cs{__dim_strip_bp:n} \Arg{dimension expression} -% \cs{__dim_strip_pt:n} \Arg{dimension expression} -% \end{syntax} -% Evaluates the \meta{dimension expression}, 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 magnitude of the -% result, expressed in big points (\texttt{bp}) or points (\texttt{pt}), -% will be left in the input stream with \emph{no units}. If the decimal -% part of the magnitude is zero, it will be omitted. For example, -% \begin{verbatim} -% \__dim_strip_pt:n { 2.5 pt * 2 } -% \end{verbatim} -% will leave~|5| in the input stream. -% \end{function} -% % \end{documentation} % % \begin{implementation} @@ -1339,18 +1387,16 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[EXP, int]{\@@_strip_bp:n} -% Conversion to big points is done using a scaling inside \cs{__dim_eval:w} -% as \eTeX{} does that using $64$-bit precision. Here, $800/803$ is the -% integer fraction for $72/72.27$. +% \begin{macro}{\dim_use:N, \dim_use:c} +% Accessing a \meta{dim}. % \begin{macrocode} -\cs_new:Npn \@@_strip_bp:n #1 - { \@@_strip_pt:n { ( #1 ) * 800 / 803 } } +\cs_new_eq:NN \dim_use:N \tex_the:D +\cs_generate_variant:Nn \dim_use:N { c } % \end{macrocode} % \end{macro} % -% \begin{macro}[EXP]{\@@_strip_pt:n} -% \begin{macro}[EXP, aux]{\@@_strip_pt:w} +% \begin{macro}[EXP]{\dim_to_decimal:n} +% \begin{macro}[EXP, aux]{\@@_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}. The argument is put in parentheses as this @@ -1358,14 +1404,14 @@ % extra tokens lying around. This is used a lot by low-level % manipulations. % \begin{macrocode} -\cs_new:Npn \@@_strip_pt:n #1 +\cs_new:Npn \dim_to_decimal:n #1 { \exp_after:wN - \@@_strip_pt:w \dim_use:N \@@_eval:w (#1) \@@_eval_end: + \@@_to_decimal:w \dim_use:N \@@_eval:w (#1) \@@_eval_end: } \use:x { - \cs_new:Npn \exp_not:N \@@_strip_pt:w + \cs_new:Npn \exp_not:N \@@_to_decimal:w ##1 . ##2 \tl_to_str:n { pt } } { @@ -1377,14 +1423,37 @@ % \end{macro} % \end{macro} % -% \begin{macro}{\dim_use:N, \dim_use:c} -% Accessing a \meta{dim}. +% \begin{macro}[EXP]{\dim_to_decimal_in_bp:n} +% Conversion to big points is done using a scaling inside \cs{__dim_eval:w} +% as \eTeX{} does that using $64$-bit precision. Here, $800/803$ is the +% integer fraction for $72/72.27$. This is a common case so is hand-coded +% for accuracy (and speed). % \begin{macrocode} -\cs_new_eq:NN \dim_use:N \tex_the:D -\cs_generate_variant:Nn \dim_use:N { c } +\cs_new:Npn \dim_to_decimal_in_bp:n #1 + { \dim_to_decimal:n { ( #1 ) * 800 / 803 } } % \end{macrocode} % \end{macro} % +% \begin{macro}[EXP]{\dim_to_decimal_in_unit:nn} +% An analogue of \cs{dim_ratio:nn} that produces a decimal number as its +% result, rather than a rational fraction for use within dimension +% expressions. +% \begin{macrocode} +\cs_new:Npn \dim_to_decimal_in_unit:nn #1#2 + { + \dim_to_decimal:n + { + 1pt * + \dim_ratio:nn {#1} {#2} + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}[EXP]{\dim_to_fp:n} +% Defined in \pkg{l3fp-convert}, documented here. +% \end{macro} +% % \subsection{Viewing \texttt{dim} variables} % % \begin{macro}{\dim_show:N, \dim_show:c} @@ -1870,6 +1939,14 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\__dim_strip_bp:n, \__dim_strip_pt:n} +% Deprecated 2014-07-15. +% \begin{macrocode} +\cs_new_eq:NN \__dim_strip_bp:n \dim_to_decimal_in_bp:n +\cs_new_eq:NN \__dim_strip_pt:n \dim_to_decimal:n +% \end{macrocode} +% \end{macro} +% % \begin{macrocode} %</initex|package> % \end{macrocode} |