l3 (12jul13)

git-svn-id: svn://tug.org/texlive/trunk@31181 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 86 insertions, 172 deletions

diff --git a/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx b/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
index e144922e224..1eaf1bdeb0f 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 %
-%% File: l3candidates.dtx Copyright(C) 2012 The LaTeX3 Project
+%% File: l3candidates.dtx Copyright(C) 2012,2013 The LaTeX3 Project
 %%
 %% It may be distributed and/or modified under the conditions of the
 %% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -36,7 +36,7 @@
 %
 %<*driver|package>
 \RequirePackage{l3bootstrap}
-\GetIdInfo$Id: l3candidates.dtx 4468 2013-03-14 20:30:45Z joseph $
+\GetIdInfo$Id: l3candidates.dtx 4521 2013-07-09 11:45:31Z joseph $
   {L3 Experimental additions to l3kernel}
 %</driver|package>
 %<*driver>
@@ -264,7 +264,7 @@
 %
 % \section{Additions to \pkg{l3clist}}
 %
-% \begin{function}{\clist_item:Nn, \clist_item:cn, \clist_item:nn}
+% \begin{function}[EXP]{\clist_item:Nn, \clist_item:cn, \clist_item:nn}
 %   \begin{syntax}
 %     \cs{clist_item:Nn} \meta{comma list} \Arg{integer expression}
 %   \end{syntax}
@@ -326,37 +326,6 @@
 %   is not empty.
 % \end{function}
 %
-% \begin{function}[EXP, added = 2012-06-26]{\clist_use:Nnnn}
-%   \begin{syntax}
-%     \cs{clist_use:Nnnn} \meta{clist~var} \Arg{separator~between~two} \Arg{separator~between~more~than~two} \Arg{separator~between~final~two}
-%   \end{syntax}
-%   Places the contents of the \meta{clist~var} in the input stream,
-%   with the appropriate \meta{separator} between the items.  Namely, if
-%   the comma list has more than $2$ items, the \meta{separator between
-%     more than two} is placed between each pair of items except the
-%   last, for which the \meta{separator between final two} is used.  If
-%   the comma list has $2$ items, then they are placed in the input
-%   stream separated by the \meta{separator between two}.  If the comma
-%   list has $1$ item, it is placed in the input stream, and a comma
-%   list with no items produces no output.  An error will be raised if
-%   the variable does not exist or if it is invalid.
-%
-%   For example,
-%   \begin{verbatim}
-%     \clist_set:Nn \l_tmpa_clist { a , b , , c , {de} , f }
-%     \clist_use:Nnnn \l_tmpa_clist { ~and~ } { ,~ } { ,~and~ }
-%   \end{verbatim}
-%   will insert \enquote{\texttt{a, b, c, de, and f}} in the input
-%   stream.  The first separator argument is not used in this case
-%   because the comma list has more than $2$ items.
-%   \begin{texnote}
-%     The result is returned within the \tn{unexpanded}
-%     primitive (\cs{exp_not:n}), which means that the \meta{items}
-%     will not expand further when appearing in an \texttt{x}-type
-%     argument expansion.
-%   \end{texnote}
-% \end{function}
-%
 % \section{Additions to \pkg{l3coffins}}
 %
 % \begin{function}{\coffin_resize:Nnn, \coffin_resize:cnn}
@@ -622,38 +591,45 @@
 %   \end{texnote}
 % \end{function}
 %
-% \begin{function}[EXP, added = 2012-06-26]{\seq_use:Nnnn}
+% \section{Additions to \pkg{l3skip}}
+%
+% \begin{function}[added = 2013-05-06, EXP]{\dim_to_pt:n}
 %   \begin{syntax}
-%     \cs{seq_use:Nnnn} \meta{seq~var} \Arg{separator~between~two} \Arg{separator~between~more~than~two} \Arg{separator~between~final~two}
+%     \cs{dim_to_pt:n} \Arg{dimexpr}
 %   \end{syntax}
-%   Places the contents of the \meta{seq~var} in the input stream, with
-%   the appropriate \meta{separator} between the items.  Namely, if the
-%   sequence has more than $2$ items, the \meta{separator between more
-%     than two} is placed between each pair of items except the last,
-%   for which the \meta{separator between final two} is used.  If the
-%   sequence has $2$ items, then they are placed in the input stream
-%   separated by the \meta{separator between two}.  If the sequence has
-%   $1$ item, it is placed in the input stream, and an empty sequence
-%   produces no output.  An error will be raised if the variable does
-%   not exist or if it is invalid.
-%
-%   For example,
+%   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.
+%
+%   If the \meta{dimension expression} contains additional tokens such
+%   as redundant units, these will be ignored, so for example
 %   \begin{verbatim}
-%     \seq_set_split:Nnn \l_tmpa_seq { | } { a | b | c | {de} | f }
-%     \seq_use:Nnnn \l_tmpa_seq { ~and~ } { ,~ } { ,~and~ }
+%     \dim_to_pt:n { 1 bp pt }
 %   \end{verbatim}
-%   will insert \enquote{\texttt{a, b, c, de, and f}} in the input
-%   stream.  The first separator argument is not used in this case
-%   because the sequence has more than $2$ items.
-%   \begin{texnote}
-%     The result is returned within the \tn{unexpanded}
-%     primitive (\cs{exp_not:n}), which means that the \meta{items}
-%     will not expand further when appearing in an \texttt{x}-type
-%     argument expansion.
-%   \end{texnote}
+%   leaves |1.00374| in the input stream, \emph{i.e.}~the magnitude of
+%   one \enquote{big point} when converted to points.
 % \end{function}
 %
-% \section{Additions to \pkg{l3skip}}
+% \begin{function}[added = 2013-05-06, EXP]{\dim_to_unit:nn}
+%   \begin{syntax}
+%     \cs{dim_to_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.
+%
+%   If the \meta{dimension expressions} contain additional tokens such
+%   as redundant units, these will be ignored, so for example
+%   \begin{verbatim}
+%     \dim_to_unit:nn { 1 bp pt } { 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.
+% \end{function}
 %
 % \begin{function}{\skip_split_finite_else_action:nnNN}
 %   \begin{syntax}
@@ -940,8 +916,8 @@
 %   The next step is to work out the $x$ and $y$ coordinates of vertices of
 %   the rotated box in relation to its original coordinates. The box can be
 %   visualized with vertices $B$, $C$, $D$ and $E$ is illustrated
-%   (Figure~\ref{fig:rotation}). The vertex $O$ is the reference point on the
-%   baseline, and in this implementation is also the centre of rotation.
+%   (Figure~\ref{fig:l3candidates:rotation}). The vertex $O$ is the reference point
+%   on the baseline, and in this implementation is also the centre of rotation.
 %   \begin{figure}
 %     \centering
 %     \setlength{\unitlength}{3pt}^^A
@@ -958,7 +934,7 @@
 %       \put(21,59){O}
 %     \end{picture}
 %     \caption{Co-ordinates of a box prior to rotation.}
-%     \label{fig:rotation}
+%     \label{fig:l3candidates:rotation}
 %   \end{figure}
 %   The formulae are, for a point $P$ and angle $\alpha$:
 %   \[
@@ -1602,7 +1578,7 @@
 %   any argument: this avoids losing braces. The argument
 %   of \cs{tl_if_empty:oTF} is empty if |#1| is |?| followed
 %   by blank spaces (besides, this particular variant of
-%   the emptyness test is optimized). If the item of the
+%   the emptiness test is optimized). If the item of the
 %   comma list is blank, grab the next one. As soon as one
 %   item is non-blank, exit: the second auxiliary will grab
 %   \cs{prg_return_false:} as |#2|, unless every item in
@@ -1628,62 +1604,6 @@
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}[EXP]{\clist_use:Nnnn}
-% \begin{macro}[EXP, aux]
-%   {\@@_use:wwn, \@@_use:nwwwwnwn, \@@_use:nwwn}
-%   First check that the variable exists.  Then count the items in the
-%   comma list.  If it has none, output nothing.  If it has one item,
-%   output that item, brace stripped (note that space-trimming has
-%   already been done when the comma list was assigned).  If it has two,
-%   place the \meta{separator~between~two} in the middle.
-%
-%   Otherwise, \cs{@@_use:nwwwwnwn} takes the following arguments; 1:
-%   a \meta{separator}, 2, 3, 4: three items from the comma list (or
-%   quarks), 5: the rest of the comma list, 6: a \meta{continuation}
-%   function (\texttt{use_ii} or \texttt{use_iii} with its
-%   \meta{separator} argument), 7: junk, and 8: the temporary result,
-%   which is built in a brace group following \cs{q_stop}.  The
-%   \meta{separator} and the first of the three items are placed in the
-%   result, then we use the \meta{continuation}, placing the remaining
-%   two items after it.  When we begin this loop, the three items really
-%   belong to the comma list, the first \cs{q_mark} is taken as a
-%   delimiter to the \texttt{use_ii} function, and the continuation is
-%   \texttt{use_ii} itself.  When we reach the last two items of the
-%   original token list, \cs{q_mark} is taken as a third item, and now
-%   the seconf \cs{q_mark} serves as a delimiter to \texttt{use_ii},
-%   switching to the other \meta{continuation}, \texttt{use_iii}, which
-%   uses the \meta{separator between final two}.
-%    \begin{macrocode}
-\cs_new:Npn \clist_use:Nnnn #1#2#3#4
-  {
-    \clist_if_exist:NTF #1
-      {
-        \int_case:nnn { \clist_count:N #1 }
-          {
-            { 0 } { }
-            { 1 } { \exp_after:wN \@@_use:wwn #1 , , { } }
-            { 2 } { \exp_after:wN \@@_use:wwn #1 , {#2} }
-          }
-          {
-            \exp_after:wN \@@_use:nwwwwnwn
-            \exp_after:wN { \exp_after:wN } #1 ,
-            \q_mark , { \@@_use:nwwwwnwn {#3} }
-            \q_mark , { \@@_use:nwwn {#4} }
-            \q_stop { }
-          }
-      }
-      { \__msg_kernel_expandable_error:nnn { kernel } { bad-variable } {#1} }
-  }
-\cs_new:Npn \@@_use:wwn #1 , #2 , #3 { \exp_not:n { #1 #3 #2 } }
-\cs_new:Npn \@@_use:nwwwwnwn
-    #1#2 , #3 , #4 , #5 \q_mark , #6#7 \q_stop #8
-  { #6 {#3} , {#4} , #5 \q_mark , {#6} #7 \q_stop { #8 #1 #2 } }
-\cs_new:Npn \@@_use:nwwn #1#2 , #3 \q_stop #4
-  { \exp_not:n { #4 #1 #2 } }
-%    \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
 % \subsection{Additions to \pkg{l3coffins}}
 %
 %    \begin{macrocode}
@@ -2260,25 +2180,24 @@
 % \end{macro}
 %
 % \begin{macro}[EXP]{\prop_get:Nn, \prop_get:cn}
-% \begin{macro}[aux, EXP]{\@@_get:Nn, \@@_get:No}
 % \begin{macro}[aux, EXP]{\@@_get_Nn:nwn}
 %   Getting the value corresponding to a key in a property list in an
-%   expandable fashion is a simple instance of mapping some tokens.
-%   Map the function \cs{prop_get:nnn} which takes as its three
-%   arguments the \meta{key} that we are looking for, the current
-%   \meta{key} and the current \meta{value}. If the \meta{keys} match,
-%   the \meta{value} is returned. If none of the keys match, this expands
-%   to nothing.
+%   expandable fashion is similar to mapping some tokens.  Go through
+%   the property list one \meta{key}--\meta{value} pair at a time: the
+%   arguments of \cs{@@_get_Nn:nwn} are the \meta{key} we are looking
+%   for, a \meta{key} of the property list, and its associated value.
+%   The \meta{keys} are compared (as strings).  If they match, the
+%   \meta{value} is returned, within \cs{exp_not:n}.  The loop
+%   terminates even if the \meta{key} is missing, and yields an empty
+%   value, because we have appended the appropriate
+%   \meta{key}--\meta{empty value} pair to the property list.
 %    \begin{macrocode}
 \cs_new:Npn \prop_get:Nn #1#2
-  { \@@_get:No #1 { \tl_to_str:n {#2} } }
-\cs_new:Npn \@@_get:Nn #1#2
   {
-    \exp_last_unbraced:Nno \@@_get_Nn:nwn {#2} #1
-      \s_@@ #2 \s_@@ { }
+    \exp_last_unbraced:Noo \@@_get_Nn:nwn { \tl_to_str:n {#2} } #1
+      \s_@@ \tl_to_str:n {#2} \s_@@ { }
     \__prg_break_point:
   }
-\cs_generate_variant:Nn \@@_get:Nn { No }
 \cs_new:Npn \@@_get_Nn:nwn #1 \s_@@ #2 \s_@@ #3
   {
     \str_if_eq_x:nnTF {#1} {#2}
@@ -2289,7 +2208,6 @@
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
-% \end{macro}
 %
 % \subsection{Additions to \pkg{l3seq}}
 %
@@ -2531,50 +2449,46 @@
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}[EXP]{\seq_use:Nnnn}
-% \begin{macro}[EXP, aux]
-%   {\@@_use:NnNnn, \@@_use:nwwwwnwn, \@@_use:nwwn}
-%   See \cs{clist_use:Nnnn} for a general explanation.  The main
-%   difference is that we use \cs{@@_item:n} as a delimiter rather than
-%   commas.  We also need to add \cs{@@_item:n} at various places.
+% \subsection{Additions to \pkg{l3skip}}
+%
+%    \begin{macrocode}
+%<@@=dim>
+%    \end{macrocode}
+%
+% \begin{macro}[EXP]{\dim_to_pt:n}
+%   A copy of the internal function \cs{@@_strip_pt:n}, which should
+%   perhaps be eliminated in favor of \cs{dim_to_pt:n}.
 %    \begin{macrocode}
-\cs_new:Npn \seq_use:Nnnn #1#2#3#4
+\cs_new_eq:NN \dim_to_pt:n \@@_strip_pt:n
+%    \end{macrocode}
+% \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
+%   \begin{verbatim}
+%     \cs_new:Npn \dim_to_unit:nn #1#2
+%       { \dim_to_pt:n { 1pt * \dim_ratio:nn {#1} {#2} } }
+%   \end{verbatim}
+%   would not ignore trailing tokens (see documentation), so we need a
+%   bit more work.
+%    \begin{macrocode}
+\cs_new:Npn \dim_to_unit:nn #1#2
   {
-    \seq_if_exist:NTF #1
+    \dim_to_pt:n
       {
-        \int_case:nnn { \seq_count:N #1 }
-          {
-            { 0 } { }
-            { 1 } { \exp_after:wN \@@_use:NnNnn #1 \@@_item:n { } { } }
-            { 2 } { \exp_after:wN \@@_use:NnNnn #1 {#2} }
-          }
-          {
-            \exp_after:wN \@@_use:nwwwwnwn
-            \exp_after:wN { \exp_after:wN } #1 \@@_item:n
-            \q_mark { \@@_use:nwwwwnwn {#3} }
-            \q_mark { \@@_use:nwwn {#4} }
-            \q_stop { }
-          }
+        1pt * \@@_to_unit:n { \dim_to_pt:n {#1} pt }
+        / \@@_to_unit:n { \dim_to_pt:n {#2} pt }
       }
-      { \__msg_kernel_expandable_error:nnn { kernel } { bad-variable } {#1} }
   }
-\cs_new:Npn \@@_use:NnNnn \@@_item:n #1 \@@_item:n #2#3
-  { \exp_not:n { #1 #3 #2 } }
-\cs_new:Npn \@@_use:nwwwwnwn
-    #1 \@@_item:n #2 \@@_item:n #3 \@@_item:n #4#5
-    \q_mark #6#7 \q_stop #8
-  {
-    #6 \@@_item:n {#3} \@@_item:n {#4} #5
-    \q_mark {#6} #7 \q_stop { #8 #1 #2 }
-  }
-\cs_new:Npn \@@_use:nwwn #1 \@@_item:n #2 #3 \q_stop #4
-  { \exp_not:n { #4 #1 #2 } }
+\cs_new:Npn \@@_to_unit:n #1
+  { \__int_value:w \@@_eval:w #1 \@@_eval_end: }
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
 %
-% \subsection{Additions to \pkg{l3skip}}
-%
 %    \begin{macrocode}
 %<@@=skip>
 %    \end{macrocode}
@@ -2613,7 +2527,7 @@
 %   There are four cases: empty token list, token list starting with
 %   a normal token, with a brace group, or with a space token.
 %   If the token list starts with a normal token, remove it
-%   and check for emptyness. Otherwise, compare with a single
+%   and check for emptiness. Otherwise, compare with a single
 %   space, only case where we have a single token.
 %    \begin{macrocode}
 \prg_new_conditional:Npnn \tl_if_single_token:n #1 { p , T , F , TF }
@@ -2668,7 +2582,7 @@
 % \begin{macro}[EXP]{\tl_count_tokens:n}
 % \begin{macro}[EXP,aux]{\@@_act_count_normal:nN,
 %     \@@_act_count_group:nn,\@@_act_count_space:n}
-%   The token coung is computed through an \cs{int_eval:n} construction.
+%   The token count is computed through an \cs{int_eval:n} construction.
 %   Each \texttt{1+} is output to the \emph{left}, into the integer
 %   expression, and the sum is ended by the \cs{c_zero} inserted by
 %   \cs{@@_act_end:wn}. Somewhat a hack.
@@ -2694,7 +2608,7 @@
 % \end{macro}
 %
 % \begin{variable}{\c_@@_act_uppercase_tl, \c_@@_act_lowercase_tl}
-%   These constants contain the correspondance between lowercase
+%   These constants contain the correspondence between lowercase
 %   and uppercase letters, in the form |aAbBcC...| and |AaBbCc...|
 %   respectively.
 %    \begin{macrocode}
@@ -2715,7 +2629,7 @@
 % \begin{macro}[EXP,aux]{\@@_act_case_normal:nN,
 %     \@@_act_case_group:nn,\@@_act_case_space:n}
 %   The only difference between uppercasing and lowercasing is
-%   the table of correspondance that is used. As for other
+%   the table of correspondence that is used. As for other
 %   token list actions, we feed \cs{@@_act:NNNnn} three
 %   functions, and this time, we use the \meta{parameters}
 %   argument to carry which case-changing we are applying.