summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx153
1 files changed, 37 insertions, 116 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx b/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
index 2c77af11e46..a65e95aaca8 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
@@ -38,7 +38,7 @@
\documentclass[full]{l3doc}
%</driver>
%<*driver|package>
-\GetIdInfo$Id: l3candidates.dtx 4734 2014-05-04 21:48:49Z joseph $
+\GetIdInfo$Id: l3candidates.dtx 4972 2014-05-31 16:42:18Z bruno $
{L3 Experimental additions to l3kernel}
%</driver|package>
%<*driver>
@@ -78,28 +78,6 @@
% the kernel. We encourage programmers to test them out and report back on
% the \texttt{LaTeX-L} mailing list.
%
-% \section{Additions to \pkg{l3basics}}
-%
-% \begin{function}[EXP,TF]{\cs_if_exist_use:N, \cs_if_exist_use:c}
-% \begin{syntax}
-% \cs{cs_if_exist_use:NTF} \meta{control sequence} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% If the \meta{control sequence} exists, leave it in the input stream,
-% followed by the \meta{true code} (unbraced). Otherwise, leave the
-% \meta{false} code in the input stream. For example,
-% \begin{verbatim}
-% \cs_set:Npn \mypkg_use_character:N #1
-% { \cs_if_exist_use:cF { mypkg_#1:n } { \mypkg_default:N #1 } }
-% \end{verbatim}
-% calls the function |\mypkg_#1:n| if it exists, and falls back to
-% a default action otherwise. This could also be done (more slowly)
-% using \cs{str_case_x:nnn}.
-% \begin{texnote}
-% The \texttt{c} variants do not introduce the \meta{control sequence}
-% in the hash table if it is not there.
-% \end{texnote}
-% \end{function}
-%
% \section{Additions to \pkg{l3box}}
%
% \subsection{Affine transformations}
@@ -120,8 +98,10 @@
% the box. The updated \meta{box} will be an hbox, irrespective of the nature
% of the \meta{box} before the resizing is applied. Negative sizes will
% cause the material in the \meta{box} to be reversed in direction, but the
-% reference point of the \meta{box} will be unchanged. The resizing applies
-% within the current \TeX{} group level.
+% reference point of the \meta{box} will be unchanged.
+% Thus negative $y$-sizes will result in a box a depth dependent on the
+% height of the original box a height dependent on the depth.
+% The resizing applies within the current \TeX{} group level.
% \end{function}
%
% \begin{function}
@@ -136,8 +116,10 @@
% The updated \meta{box} will be an hbox, irrespective of the nature
% of the \meta{box} before the resizing is applied. A negative size will
% cause the material in the \meta{box} to be reversed in direction, but the
-% reference point of the \meta{box} will be unchanged. The resizing applies
-% within the current \TeX{} group level.
+% reference point of the \meta{box} will be unchanged.
+% Thus negative $y$-sizes will result in a box a depth dependent on the
+% height of the original box a height dependent on the depth.
+% The resizing applies within the current \TeX{} group level.
% \end{function}
%
% \begin{function}{\box_resize_to_wd:Nn, \box_resize_to_wd:cn}
@@ -149,8 +131,10 @@
% The updated \meta{box} will be an hbox, irrespective of the nature
% of the \meta{box} before the resizing is applied. A negative size will
% cause the material in the \meta{box} to be reversed in direction, but the
-% reference point of the \meta{box} will be unchanged. The resizing applies
-% within the current \TeX{} group level.
+% reference point of the \meta{box} will be unchanged.
+% Thus negative $y$-sizes will result in a box a depth dependent on the
+% height of the original box a height dependent on the depth.
+% The resizing applies within the current \TeX{} group level.
% \end{function}
%
% \begin{function}{\box_rotate:Nn, \box_rotate:cn}
@@ -176,7 +160,9 @@
% of the nature of the \meta{box} before the scaling is applied. Negative
% scalings will cause the material in the \meta{box} to be reversed in
% direction, but the reference point of the \meta{box} will be unchanged.
-% The scaling applies within the current \TeX{} group level.
+% Thus negative $y$-scales will result in a box a depth dependent on the
+% height of the original box a height dependent on the depth.
+% The resizing applies within the current \TeX{} group level.
% \end{function}
%
% \subsection{Viewing part of a box}
@@ -457,76 +443,6 @@
% before being assigned to the \meta{floating point variable}.
% \end{function}
%
-% \begin{function}[EXP]{\fp_function:Nw}
-% \begin{syntax}
-% \cs{fp_eval:n}
-% ~~|{|
-% ~~~~\cs{fp_function:Nw} \meta{function}
-% ~~~~~~|(| \meta{fpexpr_1} |,| \ldots{} |,| \meta{fpexpr_n} |)|
-% ~~|}|
-% \end{syntax}
-% Finds one or more arguments \meta{fpexpr_1} \ldots{} \meta{fpexpr_n}
-% following the \meta{function}, and evaluate them. Then calls the
-% \meta{function} followed by a single brace group containing
-% \Arg{result_1} \ldots{} \Arg{result_n}. For instance,
-% \begin{verbatim}
-% \cs_new_nopar:Npn \mypkg_log:w
-% { \fp_function:Nw \__mypkg_log:n }
-% \cs_new:Npn \__mypkg_log:n #1
-% {
-% \int_case:nnF { \tl_count:n {#1} }
-% {
-% { 1 } { \__mypkg_log_aux:nn #1 { 10 } }
-% { 2 } { \__mypkg_log_aux:nn #1 }
-% }
-% { \ERROR \c_nan_fp }
-% }
-% \cs_new:Npn \__mypkg_log_aux:nn #1#2 { ln(#1) / ln(#2) }
-% \fp_show:n { \mypkg_log:w (8, 2) + \mypkg_log:w (1e17) }
-% \end{verbatim}
-% shows $20 = \log_2(8) + \log(10^{17})$. The function |\mypkg_log:w|
-% behaves like other built-in functions such as |ln|, but allows $1$
-% or~$2$ arguments, and computes either the base~$10$ logarithm or the
-% logarithm of the first argument in a base given by the second
-% argument. Checking the number of arguments is acheived by
-% |\__mypkg_log:n|, which provides the default base~$10$ when there is
-% only one argument. The computation itself is done by
-% |\__mypkg_log_aux:nn|.
-% \end{function}
-%
-% \begin{function}{\fp_new_function:Npn}
-% \begin{syntax}
-% \cs{fp_new_function:Npn} \meta{function} \meta{parameters} \Arg{code}
-% \cs{fp_eval:n} |{| \meta{function} |(| \meta{fpexpr_1} |,| \ldots{} |,| \meta{fpexpr_n} |)| |}|
-% \end{syntax}
-% Defines the \meta{function} for use within floating point
-% expressions, expecting some \meta{parameters}, and evaluating the
-% \meta{code}, which must be expandable. When the \meta{function}
-% appears in a floating point expression, arguments \meta{fpexpr_1},
-% \ldots{}, \meta{fpexpr_n} are found and evaluated in the same way as
-% for built-in functions such as~|max|. If the number of arguments
-% matches the number of \meta{parameters}, the arguments replace |#1|,
-% \ldots{}, |#|$n$ in the \meta{code}, which is then evaluated to
-% produce a floating point result. Otherwise, the result is
-% \texttt{nan} after an error. The \meta{parameter text} must not
-% contain delimited arguments, that is, it must be empty or one of
-% |#1|, |#1#2|, |#1#2#3|, \ldots{} |#1#2#3#4#5#6#7#8#9|. The
-% arguments replacing parameters in the \meta{code} are internal
-% floating point numbers; operations such as |#1^2| thus correctly
-% take into account the sign of~|#1|. For instance,
-% \begin{verbatim}
-% \fp_new_function:Npn \mypkg_sqrt:w #1 { #1^.5 }
-% \fp_new_function:Npn \mypkg_veclen:w #1#2
-% { \mypkg_sqrt:w ( #1^2 + #2^2 ) }
-% \fp_show:n { \mypkg_veclen:w ( 42 / 7 , 2 * 4 - 0 ) }
-% \end{verbatim}
-% shows~$10$. In the example, |\mypkg_veclen:w| receives the
-% arguments $6=42/7$ and~$8=2\times 4-0$, thus expands to
-% |\mypkg_sqrt:w ( 6^2 + 8^2 )|, then |\mypkg_sqrt:w| receives
-% $100=6^2+8^2$ as an argument, and evaluates the square root $10 =
-% 100^{0.5}$.
-% \end{function}
-%
% \section{Additions to \pkg{l3prop}}
%
% \begin{function}[rEXP]
@@ -664,7 +580,8 @@
%
% \section{Additions to \pkg{l3skip}}
%
-% \begin{function}[added = 2013-05-06, EXP]{\dim_to_pt:n}
+% \begin{function}[added = 2013-05-06, updated=2014-05-31, EXP]
+% {\dim_to_pt:n}
% \begin{syntax}
% \cs{dim_to_pt:n} \Arg{dimexpr}
% \end{syntax}
@@ -674,16 +591,16 @@
% places. If the decimal part of the result is zero, it is omitted,
% together with the decimal marker.
%
-% If the \meta{dimension expression} contains additional tokens such
-% as redundant units, these will be ignored, so for example
+% For example
% \begin{verbatim}
-% \dim_to_pt:n { 1 bp pt }
+% \dim_to_pt:n { 1 bp }
% \end{verbatim}
% leaves |1.00374| in the input stream, \emph{i.e.}~the magnitude of
% one \enquote{big point} when converted to points.
% \end{function}
%
-% \begin{function}[added = 2013-05-06, EXP]{\dim_to_unit:nn}
+% \begin{function}[added = 2013-05-06, updated=2014-05-31, EXP]
+% {\dim_to_unit:nn}
% \begin{syntax}
% \cs{dim_to_unit:nn} \Arg{dimexpr_1} \Arg{dimexpr_2}
% \end{syntax}
@@ -693,10 +610,9 @@
% to four or five decimal places. If the decimal part of the result
% is zero, it is omitted, together with the decimal marker.
%
-% If the \meta{dimension expressions} contain additional tokens such
-% as redundant units, these will be ignored, so for example
+% For example
% \begin{verbatim}
-% \dim_to_unit:nn { 1 bp pt } { 1 mm }
+% \dim_to_unit:nn { 1 bp } { 1 mm }
% \end{verbatim}
% leaves |0.35277| in the input stream, \emph{i.e.}~the magnitude of
% one \enquote{big point} when converted to millimeters.
@@ -1311,8 +1227,15 @@
% \end{macrocode}
% The new height and depth can be applied directly.
% \begin{macrocode}
- \box_set_ht:Nn \l_@@_internal_box { \l_@@_top_new_dim }
- \box_set_dp:Nn \l_@@_internal_box { \l_@@_bottom_new_dim }
+ \fp_compare:nNnTF \l_@@_scale_y_fp > \c_zero_fp
+ {
+ \box_set_ht:Nn \l_@@_internal_box { \l_@@_top_new_dim }
+ \box_set_dp:Nn \l_@@_internal_box { -\l_@@_bottom_new_dim }
+ }
+ {
+ \box_set_dp:Nn \l_@@_internal_box { \l_@@_top_new_dim }
+ \box_set_ht:Nn \l_@@_internal_box { -\l_@@_bottom_new_dim }
+ }
% \end{macrocode}
% Things are not quite as obvious for the width, as the reference point
% needs to remain unchanged. For positive scaling factors resizing the
@@ -2528,7 +2451,6 @@
% \end{macro}
%
% \begin{macro}[EXP]{\dim_to_unit:nn}
-% \begin{macro}[aux, EXP]{\@@_to_unit:n}
% An analog of \cs{dim_ratio:nn} that produces a decimal number as its
% result, rather than a rational fraction for use within dimension
% expressions. The naive implementation as
@@ -2543,15 +2465,14 @@
{
\dim_to_pt:n
{
- 1pt * \@@_to_unit:n { \dim_to_pt:n {#1} pt }
- / \@@_to_unit:n { \dim_to_pt:n {#2} pt }
+ 1pt *
+ \dim_ratio:nn
+ { \dim_to_pt:n {#1} pt }
+ { \dim_to_pt:n {#2} pt }
}
}
-\cs_new:Npn \@@_to_unit:n #1
- { \__int_value:w \@@_eval:w #1 \@@_eval_end: }
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
% \begin{macrocode}
%<@@=skip>