diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3box.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3box.dtx | 175 |
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 |