summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-07-15 21:27:01 +0000
committerKarl Berry <karl@freefriends.org>2017-07-15 21:27:01 +0000
commitb1ce47fe4d0e1f06d1b019c3c6eb5f1b0ecd5e14 (patch)
tree58362abe4b603bb5f6db898b9b835bc8af730b3e /Master/texmf-dist/source/latex/l3kernel/l3box.dtx
parent03b8dcfa3435f0265dfad4fd09aaab8f4ff9c617 (diff)
l3 (15jul17)
git-svn-id: svn://tug.org/texlive/trunk@44813 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3box.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3box.dtx175
1 files changed, 120 insertions, 55 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3box.dtx b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
index 5bc3bd3c2ce..7b27571dee6 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
@@ -41,7 +41,7 @@
% }^^A
% }
%
-% \date{Released 2017/05/29}
+% \date{Released 2017/07/15}
%
% \maketitle
%
@@ -58,8 +58,8 @@
% \cs{box_new:N} \meta{box}
% \end{syntax}
% Creates a new \meta{box} or raises an error if the name is
-% already taken. The declaration is global. The \meta{box} will
-% initially be void.
+% already taken. The declaration is global. The \meta{box} is
+% initially void.
% \end{function}
%
% \begin{function}{\box_clear:N, \box_clear:c, \box_gclear:N, \box_gclear:c}
@@ -274,7 +274,7 @@
% \end{syntax}
% Sets the \meta{box} equal to the last item (box) added to the current
% partial list, removing the item from the list at the same time. When
-% applied to the main vertical list, the \meta{box} will always be void as
+% applied to the main vertical list, the \meta{box} is always void as
% it is not possible to recover the last added item.
% \end{function}
%
@@ -338,7 +338,7 @@
% \section{Boxes and color}
%
% All \LaTeX{}3 boxes are \enquote{color safe}: a color set inside the box
-% will not apply after the end of the box has occurred.
+% stops applying after the end of the box has occurred.
%
% \section{Horizontal mode boxes}
%
@@ -393,8 +393,7 @@
% \cs{hbox_overlap_right:n} \Arg{contents}
% \end{syntax}
% Typesets the \meta{contents} into a horizontal box of zero width
-% such that material will protrude to the right of the insertion
-% point.
+% such that material protrudes to the right of the insertion point.
% \end{function}
%
% \begin{function}[updated = 2017-04-05]{\hbox_overlap_left:n}
@@ -402,8 +401,7 @@
% \cs{hbox_overlap_left:n} \Arg{contents}
% \end{syntax}
% Typesets the \meta{contents} into a horizontal box of zero width
-% such that material will protrude to the left of the insertion
-% point.
+% such that material protrudes to the left of the insertion point.
% \end{function}
%
% \begin{function}[updated = 2017-04-05]
@@ -423,6 +421,21 @@
% where the \meta{content} may not be a simple argument.
% \end{function}
%
+% \begin{function}[added = 2017-06-08]
+% {
+% \hbox_set_to_wd:Nnw, \hbox_set_to_wd:cnw,
+% \hbox_gset_to_wd:Nnw, \hbox_gset_to_wd:cnw
+% }
+% \begin{syntax}
+% \cs{hbox_set_to_wd:Nnw} \meta{box} \Arg{dimexpr} \meta{contents} \cs{hbox_set_end:}
+% \end{syntax}
+% Typesets the \meta{contents} to the width given by the \meta{dimexpr}
+% and then stores the result inside the \meta{box}. In contrast
+% to \cs{hbox_set_to_wd:Nnn} this function does not absorb the argument
+% when finding the \meta{content}, and so can be used in circumstances
+% where the \meta{content} may not be a simple argument
+% \end{function}
+%
% \begin{function}{\hbox_unpack:N, \hbox_unpack:c}
% \begin{syntax}
% \cs{hbox_unpack:N} \meta{box}
@@ -451,11 +464,11 @@
% Vertical boxes inherit their baseline from their contents. The
% standard case is that the baseline of the box is at the same position
% as that of the last item added to the box. This means that the box
-% will have no depth unless the last item added to it had depth. As a
+% has no depth unless the last item added to it had depth. As a
% result most vertical boxes have a large height value and small or
% zero depth. The exception are |_top| boxes, where the reference point
% is that of the first item added. These tend to have a large depth and
-% small height, although the latter will typically be non-zero.
+% small height, although the latter is typically non-zero.
%
% \begin{function}[updated = 2017-04-05]{\vbox:n}
% \begin{syntax}
@@ -471,7 +484,7 @@
% \end{syntax}
% Typesets the \meta{contents} into a vertical box of natural height
% and includes this box in the current list for typesetting. The
-% baseline of the box will be equal to that of the \emph{first}
+% baseline of the box is equal to that of the \emph{first}
% item added to the box.
% \end{function}
%
@@ -507,7 +520,7 @@
% \cs{vbox_set_top:Nn} \meta{box} \Arg{contents}
% \end{syntax}
% Typesets the \meta{contents} at natural height and then stores the
-% result inside the \meta{box}. The baseline of the box will be equal
+% result inside the \meta{box}. The baseline of the box is equal
% to that of the \emph{first} item added to the box.
% \end{function}
%
@@ -540,6 +553,22 @@
% where the \meta{content} may not be a simple argument.
% \end{function}
%
+% \begin{function}[added = 2017-06-08]
+% {
+% \vbox_set_to_ht:Nnw, \vbox_set_to_ht:cnw,
+% \vbox_gset_to_ht:Nnw, \vbox_gset_to_ht:cnw
+% }
+% \begin{syntax}
+% \cs{vbox_set_to_wd:Nnw} \meta{box} \Arg{dimexpr} \meta{contents} \cs{vbox_set_end:}
+% \end{syntax}
+% Typesets the \meta{contents} to the height given by the \meta{dimexpr}
+% and then stores the result inside the \meta{box}. In contrast
+% to \cs{vbox_set_to_ht:Nnn} this function does not absorb the argument
+% when finding the \meta{content}, and so can be used in circumstances
+% where the \meta{content} may not be a simple argument
+% \end{function}
+%
+%
% \begin{function}[updated = 2011-10-22]{\vbox_set_split_to_ht:NNn}
% \begin{syntax}
% \cs{vbox_set_split_to_ht:NNn} \meta{box_1} \meta{box_2} \Arg{dimexpr}
@@ -591,13 +620,13 @@
% Resizes the \meta{box} to fit within the given \meta{x-size} (horizontally)
% and \meta{y-size} (vertically); both of the sizes are dimension
% expressions. The \meta{y-size} is the height only: it does not include any
-% depth. The updated \meta{box} will be an |hbox|, irrespective of the nature
+% depth. The updated \meta{box} is an |hbox|, irrespective of the nature
% of the \meta{box} before the resizing is applied. The final size of the
-% \meta{box} will be the smaller of \Arg{x-size} and \Arg{y-size},
-% \emph{i.e.}~the result will fit within the dimensions specified. 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. Thus a negative
-% \meta{y-size} will result in the \meta{box} having a depth dependent on the
+% \meta{box} is the smaller of \Arg{x-size} and \Arg{y-size},
+% \emph{i.e.}~the result fits within the dimensions specified. Negative
+% sizes cause the material in the \meta{box} to be reversed in direction,
+% but the reference point of the \meta{box} is unchanged. Thus a negative
+% \meta{y-size} results in the \meta{box} having a depth dependent on the
% height of the original and \emph{vice versa}. The resizing applies within
% the current \TeX{} group level.
% \end{function}
@@ -610,13 +639,13 @@
% Resizes the \meta{box} to fit within the given \meta{x-size} (horizontally)
% and \meta{y-size} (vertically); both of the sizes are dimension
% expressions. The \meta{y-size} is the total vertical size (height plus
-% depth). The updated \meta{box} will be an |hbox|, irrespective of the nature
+% depth). The updated \meta{box} is an |hbox|, irrespective of the nature
% of the \meta{box} before the resizing is applied. The final size of the
-% \meta{box} will be the smaller of \Arg{x-size} and \Arg{y-size},
-% \emph{i.e.}~the result will fit within the dimensions specified. 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. Thus a negative
-% \meta{y-size} will result in the \meta{box} having a depth dependent on the
+% \meta{box} is the smaller of \Arg{x-size} and \Arg{y-size},
+% \emph{i.e.}~the result fits within the dimensions specified. Negative
+% sizes cause the material in the \meta{box} to be reversed in direction,
+% but the reference point of the \meta{box} is unchanged. Thus a negative
+% \meta{y-size} results in the \meta{box} having a depth dependent on the
% height of the original and \emph{vice versa}. The resizing applies within
% the current \TeX{} group level.
% \end{function}
@@ -629,11 +658,11 @@
% Resizes the \meta{box} to \meta{y-size} (vertically), scaling the horizontal
% size by the same amount; \meta{y-size} is a dimension expression. The
% \meta{y-size} is the height only: it does not include any depth. The updated
-% \meta{box} will be an |hbox|, irrespective of the nature of the \meta{box}
-% before the resizing is applied. A negative \meta{y-size} will cause the
+% \meta{box} is an |hbox|, irrespective of the nature of the \meta{box}
+% before the resizing is applied. A negative \meta{y-size} causes the
% material in the \meta{box} to be reversed in direction, but the reference
-% point of the \meta{box} will be unchanged. Thus a negative \meta{y-size}
-% will result in the \meta{box} having a depth dependent on the height of the
+% point of the \meta{box} is unchanged. Thus a negative \meta{y-size}
+% results in the \meta{box} having a depth dependent on the height of the
% original and \emph{vice versa}. The resizing applies within the current
% \TeX{} group level.
% \end{function}
@@ -646,11 +675,11 @@
% Resizes the \meta{box} to \meta{y-size} (vertically), scaling the horizontal
% size by the same amount; \meta{y-size} is a dimension expression. The
% \meta{y-size} is the total vertical size (height plus depth). The updated
-% \meta{box} will be an |hbox|, irrespective of the nature of the \meta{box}
-% before the resizing is applied. A negative \meta{y-size} will cause
+% \meta{box} is an |hbox|, irrespective of the nature of the \meta{box}
+% before the resizing is applied. A negative \meta{y-size} causes
% the material in the \meta{box} to be reversed in direction, but the
-% reference point of the \meta{box} will be unchanged. Thus a negative
-% \meta{y-size} will result in the \meta{box} having a depth dependent on the
+% reference point of the \meta{box} is unchanged. Thus a negative
+% \meta{y-size} results in the \meta{box} having a depth dependent on the
% height of the original and \emph{vice versa}. The resizing applies within
% the current \TeX{} group level.
% \end{function}
@@ -661,11 +690,11 @@
% \end{syntax}
% Resizes the \meta{box} to \meta{x-size} (horizontally), scaling the vertical
% size by the same amount; \meta{x-size} is a dimension expression. The updated
-% \meta{box} will be an |hbox|, irrespective of the nature of the \meta{box}
-% before the resizing is applied. A negative \meta{x-size} will cause the
+% \meta{box} is an |hbox|, irrespective of the nature of the \meta{box}
+% before the resizing is applied. A negative \meta{x-size} causes the
% material in the \meta{box} to be reversed in direction, but the reference
-% point of the \meta{box} will be unchanged. Thus a negative \meta{x-size}
-% will result in the \meta{box} having a depth dependent on the height of the
+% point of the \meta{box} is unchanged. Thus a negative \meta{x-size}
+% results in the \meta{box} having a depth dependent on the height of the
% original and \emph{vice versa}. The resizing applies within the current
% \TeX{} group level.
% \end{function}
@@ -678,10 +707,10 @@
% Resizes the \meta{box} to \meta{x-size} (horizontally) and \meta{y-size}
% (vertically): both of the sizes are dimension expressions. The
% \meta{y-size} is the height only and does not include any depth. 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
+% \meta{box} is an |hbox|, irrespective of the nature of the \meta{box}
+% before the resizing is applied. Negative sizes cause the material in
% the \meta{box} to be reversed in direction, but the reference point of the
-% \meta{box} will be unchanged. Thus a negative \meta{y-size} will result in
+% \meta{box} is unchanged. Thus a negative \meta{y-size} results in
% the \meta{box} having a depth dependent on the height of the original and
% \emph{vice versa}. The resizing applies within the current \TeX{} group
% level.
@@ -695,10 +724,10 @@
% Resizes the \meta{box} to \meta{x-size} (horizontally) and \meta{y-size}
% (vertically): both of the sizes are dimension expressions. The
% \meta{y-size} is the total vertical size (height plus depth). 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
+% \meta{box} is an |hbox|, irrespective of the nature of the \meta{box}
+% before the resizing is applied. Negative sizes cause the material in
% the \meta{box} to be reversed in direction, but the reference point of the
-% \meta{box} will be unchanged. Thus a negative \meta{y-size} will result in
+% \meta{box} is unchanged. Thus a negative \meta{y-size} results in
% the \meta{box} having a depth dependent on the height of the original and
% \emph{vice versa}. The resizing applies within the current \TeX{} group
% level.
@@ -709,9 +738,9 @@
% \cs{box_rotate:Nn} \meta{box} \Arg{angle}
% \end{syntax}
% Rotates the \meta{box} by \meta{angle} (in degrees) anti-clockwise about
-% its reference point. The reference point of the updated box will be moved
+% its reference point. The reference point of the updated box is moved
% horizontally such that it is at the left side of the smallest rectangle
-% enclosing the rotated material. The updated \meta{box} will be an |hbox|,
+% enclosing the rotated material. The updated \meta{box} is an |hbox|,
% irrespective of the nature of the \meta{box} before the rotation is applied.
% The rotation applies within the current \TeX{} group level.
% \end{function}
@@ -722,11 +751,11 @@
% \end{syntax}
% Scales the \meta{box} by factors \meta{x-scale} and \meta{y-scale} in
% the horizontal and vertical directions, respectively (both scales are
-% integer expressions). The updated \meta{box} will be an |hbox|, irrespective
+% integer expressions). The updated \meta{box} is an |hbox|, irrespective
% 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.
-% Thus a negative \meta{y-scale} will result in the \meta{box} having a depth
+% scalings cause the material in the \meta{box} to be reversed in
+% direction, but the reference point of the \meta{box} is unchanged.
+% Thus a negative \meta{y-scale} results in the \meta{box} having a depth
% dependent on the height of the original and \emph{vice versa}. The resizing
% applies within the current \TeX{} group level.
% \end{function}
@@ -1196,6 +1225,24 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}{\hbox_set_to_wd:Nnw, \hbox_set_to_wd:cnw}
+% \begin{macro}{\hbox_gset_to_wd:Nnw, \hbox_gset_to_wd:cnw}
+% Combining the above ideas.
+% \begin{macrocode}
+\cs_new_protected:Npn \hbox_set_to_wd:Nnw #1#2
+ {
+ \tex_setbox:D #1 \tex_hbox:D to \__dim_eval:w #2 \__dim_eval_end:
+ \c_group_begin_token
+ \group_begin:
+ }
+\cs_new_protected:Npn \hbox_gset_to_wd:Nnw
+ { \tex_global:D \hbox_set_to_wd:Nnw }
+\cs_generate_variant:Nn \hbox_set_to_wd:Nnw { c }
+\cs_generate_variant:Nn \hbox_gset_to_wd:Nnw { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
% \begin{macro}{\hbox_to_wd:nn}
% \begin{macro}{\hbox_to_zero:n}
% \testfile*
@@ -1358,6 +1405,24 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}{\vbox_set_to_ht:Nnw, \vbox_set_to_ht:cnw}
+% \begin{macro}{\vbox_gset_to_ht:Nnw, \vbox_gset_to_ht:cnw}
+% A combination of the above ideas.
+% \begin{macrocode}
+\cs_new_protected:Npn \vbox_set_to_ht:Nnw #1#2
+ {
+ \tex_setbox:D #1 \tex_vbox:D to \__dim_eval:w #2 \__dim_eval_end:
+ \c_group_begin_token
+ \group_begin:
+ }
+\cs_new_protected:Npn \vbox_gset_to_ht:Nnw
+ { \tex_global:D \vbox_set_to_ht:Nnw }
+\cs_generate_variant:Nn \vbox_set_to_ht:Nnw { c }
+\cs_generate_variant:Nn \vbox_gset_to_ht:Nnw { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
% \begin{macro}{\vbox_unpack:N, \vbox_unpack:c}
% \begin{macro}{\vbox_unpack_clear:N, \vbox_unpack_clear:c}
% \testfile*
@@ -1457,8 +1522,8 @@
}
}
% \end{macrocode}
-% The edges of the box are then recorded: the left edge will
-% always be at zero. Rotation of the four edges then takes place: this is
+% The edges of the box are then recorded: the left edge is
+% always at zero. Rotation of the four edges then takes place: this is
% most efficiently done on a quadrant by quadrant basis.
% \begin{macrocode}
\cs_new_protected:Npn \@@_rotate:N #1
@@ -1523,7 +1588,7 @@
% The position of the box edges are now known, but the box at this
% stage be misplaced relative to the current \TeX{} reference point. So the
% content of the box is moved such that the reference point of the
-% rotated box will be in the same place as the original.
+% rotated box is in the same place as the original.
% \begin{macrocode}
\hbox_set:Nn \l_@@_internal_box { \box_use:N #1 }
\hbox_set:Nn \l_@@_internal_box
@@ -1862,8 +1927,8 @@
% \end{macro}
%
% \begin{macro}[aux]{\@@_resize_common:N}
-% The main resize function places in input into a box which will start
-% of with zero width, and includes the handles for engine rescaling.
+% The main resize function places its input into a box which start
+% off with zero width, and includes the handles for engine rescaling.
% \begin{macrocode}
\cs_new_protected:Npn \@@_resize_common:N #1
{
@@ -1917,7 +1982,7 @@
%
% \subsection{Deprecated functions}
%
-% \begin{macro}{\box_resize:Nnn, \box_resize:cnn}
+% \begin{macro}[deprecated = 2018-12-31]{\box_resize:Nnn, \box_resize:cnn}
% \begin{macrocode}
\cs_new_eq:NN \box_resize:Nnn \box_resize_to_wd_and_ht_plus_dp:Nnn
\cs_new_eq:NN \box_resize:cnn \box_resize_to_wd_and_ht_plus_dp:cnn