summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/expl3/l3box.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/l3box.dtx')
-rw-r--r--Master/texmf-dist/source/latex/expl3/l3box.dtx183
1 files changed, 84 insertions, 99 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/l3box.dtx b/Master/texmf-dist/source/latex/expl3/l3box.dtx
index 5e8bcbb4352..fbf531008d2 100644
--- a/Master/texmf-dist/source/latex/expl3/l3box.dtx
+++ b/Master/texmf-dist/source/latex/expl3/l3box.dtx
@@ -1,5 +1,5 @@
% \iffalse
-%% File: l3box.dtx Copyright (C) 2005-2010 LaTeX3 project
+%% File: l3box.dtx Copyright (C) 2005-2011 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 @@
\RequirePackage{l3names}
%</driver|package>
%\fi
-\GetIdInfo$Id: l3box.dtx 2048 2010-09-26 19:13:59Z joseph $
+\GetIdInfo$Id: l3box.dtx 2178 2011-03-06 09:03:44Z mittelba $
{L3 Experimental Box module}
%\iffalse
%<*driver>
@@ -575,6 +575,7 @@
%
% \begin{macro}{\box_new:N,\box_new:c}
% Defining a new \m{box} register.
+% \testfile{m3box001.lvt}
% \begin{macrocode}
%<*initex>
\alloc_new:nnnN {box} \c_zero \c_max_register_int \tex_mathchardef:D
@@ -601,9 +602,8 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\if_hbox:N}
-% \begin{macro}{\if_vbox:N}
-% \begin{macro}{\if_box_empty:N}
+% \begin{macro}{\if_hbox:N,\if_vbox:N,\if_box_empty:N}
+% \testfile*
% The primitives for testing if a \m{box} is empty/void or which
% type of box it is.
% \begin{macrocode}
@@ -612,14 +612,16 @@
\cs_new_eq:NN \if_box_empty:N \tex_ifvoid:D
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
%
%
% \begin{macro}{\box_if_horizontal_p:N,\box_if_horizontal_p:c}
+% \testfile*
% \begin{macro}{\box_if_vertical_p:N,\box_if_vertical_p:c}
+% \testfile*
% \begin{macro}[TF]{\box_if_horizontal:N,\box_if_horizontal:c}
+% \testfile*
% \begin{macro}[TF]{\box_if_vertical:N,\box_if_vertical:c}
+% \testfile*
% \begin{macrocode}
\prg_new_conditional:Nnn \box_if_horizontal:N {p,TF,T,F} {
\tex_ifhbox:D #1 \prg_return_true: \else: \prg_return_false: \fi:
@@ -641,11 +643,11 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\box_if_empty_p:N}
-% \begin{macro}{\box_if_empty_p:c}
-% \begin{macro}[TF]{\box_if_empty:N}
-% \begin{macro}[TF]{\box_if_empty:c}
-% Testing if a \m{box} is empty/void.
+% \begin{macro}{\box_if_empty_p:N,\box_if_empty_p:c}
+% \testfile*
+% \begin{macro}[TF]{\box_if_empty:N,\box_if_empty:c}
+% \testfile*
+% Testing if a \m{box} is empty/void.
% \begin{macrocode}
\prg_new_conditional:Nnn \box_if_empty:N {p,TF,T,F} {
\tex_ifvoid:D #1 \prg_return_true: \else: \prg_return_false: \fi:
@@ -657,12 +659,11 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
-% \end{macro}
-% \end{macro}
%
%
% \begin{macro}{\box_set_eq:NN,\box_set_eq:cN,
% \box_set_eq:Nc,\box_set_eq:cc}
+% \testfile*
% Assigning the contents of a box to be another box.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \box_set_eq:NN #1#2 {\tex_setbox:D #1 \tex_copy:D #2}
@@ -672,6 +673,7 @@
%
% \begin{macro}{\box_set_eq_clear:NN,\box_set_eq_clear:cN,
% \box_set_eq_clear:Nc,\box_set_eq_clear:cc}
+% \testfile*
% Assigning the contents of a box to be another box.
% This clears the second box globally (that's how \TeX{} does it).
% \begin{macrocode}
@@ -684,6 +686,7 @@
% \box_gset_eq:Nc,\box_gset_eq:cc,
% \box_gset_eq_clear:NN,\box_gset_eq_clear:cN,
% \box_gset_eq_clear:Nc,\box_gset_eq_clear:cc}
+% \testfile*
% Global version of the above.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \box_gset_eq:NN {\pref_global:D\box_set_eq:NN}
@@ -693,15 +696,16 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\l_last_box}
+% \begin{variable}{\l_last_box}
% A different name for this read-only primitive.
% \begin{macrocode}
\cs_new_eq:NN \l_last_box \tex_lastbox:D
% \end{macrocode}
-% \end{macro}
+% \end{variable}
%
-% \begin{macro}{\box_set_to_last:N,\box_set_to_last:c}
-% \begin{macro}{\box_gset_to_last:N,\box_gset_to_last:c}
+% \begin{macro}{\box_set_to_last:N, \box_gset_to_last:N,
+% \box_set_to_last:c, \box_gset_to_last:c}
+% \testfile*
% Set a box to the previous box.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \box_set_to_last:N #1{\tex_setbox:D#1\l_last_box}
@@ -710,12 +714,10 @@
\cs_generate_variant:Nn \box_gset_to_last:N {c}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\box_move_left:nn}
-% \begin{macro}{\box_move_right:nn}
-% \begin{macro}{\box_move_up:nn}
-% \begin{macro}{\box_move_down:nn}
+% \begin{macro}{\box_move_left:nn,\box_move_right:nn,
+% \box_move_up:nn,\box_move_down:nn}
+% \testfile*
% Move box material in different directions.
% \begin{macrocode}
\cs_new:Npn \box_move_left:nn #1#2{\tex_moveleft:D\dim_eval:n{#1} #2}
@@ -724,12 +726,10 @@
\cs_new:Npn \box_move_down:nn #1#2{\tex_lower:D\dim_eval:n{#1} #2}
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\box_clear:N,\box_clear:c}
-% \begin{macro}{\box_gclear:N,\box_gclear:c}
+% \begin{macro}{\box_clear:N,\box_clear:c,
+% \box_gclear:N,\box_gclear:c}
+% \testfile*
% Clear a \m{box} register.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \box_clear:N #1{\box_set_eq_clear:NN #1 \c_empty_box }
@@ -738,12 +738,12 @@
\cs_generate_variant:Nn \box_gclear:N {c}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
-% \begin{macro}{\box_ht:N,\box_ht:c}
-% \begin{macro}{\box_dp:N,\box_dp:c}
-% \begin{macro}{\box_wd:N,\box_wd:c}
+% \begin{macro}{\box_ht:N,\box_ht:c,
+% \box_dp:N,\box_dp:c,
+% \box_wd:N,\box_wd:c}
+% \testfile*
% Accessing the height, depth, and width of a \m{box} register.
% \begin{macrocode}
\cs_new_eq:NN \box_ht:N \tex_ht:D
@@ -754,15 +754,13 @@
\cs_generate_variant:Nn \box_wd:N {c}
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-%\begin{macro}{\box_set_ht:Nn}
-%\begin{macro}{\box_set_ht:cn}
-%\begin{macro}{\box_set_dp:Nn}
-%\begin{macro}{\box_set_dp:cn}
-%\begin{macro}{\box_set_wd:Nn}
-%\begin{macro}{\box_set_wd:cn}
+%
+% \begin{macro}{\box_set_ht:Nn,
+% \box_set_ht:cn,
+% \box_set_dp:Nn,
+% \box_set_dp:cn,
+% \box_set_wd:Nn,
+% \box_set_wd:cn}
% Measuring is easy: all primitive work. These primitives are not
% expandable, so the derived functions are not either.
% \begin{macrocode}
@@ -780,14 +778,10 @@
\cs_generate_variant:Nn \box_set_wd:Nn { c }
% \end{macrocode}
%\end{macro}
-%\end{macro}
-%\end{macro}
-%\end{macro}
-%\end{macro}
-%\end{macro}
%
-% \begin{macro}{\box_use_clear:N,\box_use_clear:c}
-% \begin{macro}{\box_use:N,\box_use:c}
+% \begin{macro}{\box_use_clear:N,\box_use_clear:c,
+% \box_use:N,\box_use:c}
+% \testfile{m3box001.lvt}
% Using a \m{box}. These are just \TeX{} primitives with meaningful
% names.
% \begin{macrocode}
@@ -797,9 +791,9 @@
\cs_generate_variant:Nn \box_use:N {c}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
% \begin{macro}{\box_show:N,\box_show:c}
+% \testfile*
% Show the contents of a box and write it into the log file.
% \begin{macrocode}
\cs_set_eq:NN \box_show:N \tex_showbox:D
@@ -807,9 +801,7 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\c_empty_box}
-% \begin{macro}{\l_tmpa_box}
-% \begin{macro}{\l_tmpb_box}
+% \begin{variable}{\c_empty_box,\l_tmpa_box,\l_tmpb_box}
% We allocate some \m{box} registers here (and borrow a few from \LaTeX).
% \begin{macrocode}
%<package>\cs_set_eq:NN \c_empty_box \voidb@x
@@ -818,9 +810,7 @@
%<initex>\box_new:N \l_tmpa_box
\box_new:N \l_tmpb_box
% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
+% \end{variable}
%
%
% \subsection{Vertical boxes}
@@ -828,6 +818,7 @@
%
% \begin{macro}{\vbox:n,
% \vbox_top:n}
+% \testfile{m3box003.lvt}
% Put a vertical box directly into the input stream.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \vbox:n {\tex_vbox:D \scan_stop:}
@@ -835,8 +826,9 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\vbox_set:Nn,\vbox_set:cn}
-% \begin{macro}{\vbox_gset:Nn,\vbox_gset:cn}
+% \begin{macro}{\vbox_set:Nn,\vbox_set:cn,
+% \vbox_gset:Nn,\vbox_gset:cn}
+% \testfile*
% Storing material in a vertical box with a natural height.
% \begin{macrocode}
\cs_new_protected:Npn \vbox_set:Nn #1#2 {\tex_setbox:D #1 \tex_vbox:D {#2}}
@@ -845,11 +837,11 @@
\cs_generate_variant:Nn \vbox_gset:Nn {cn}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
-% \begin{macro}{\vbox_set_top:Nn,\vbox_set_top:cn}
-% \begin{macro}{\vbox_gset_top:Nn,\vbox_gset_top:cn}
+% \begin{macro}{\vbox_set_top:Nn,\vbox_set_top:cn,
+% \vbox_gset_top:Nn,\vbox_gset_top:cn}
+% \testfile*
% Storing material in a vertical box with a natural height and reference
% point at the baseline of the first object in the box.
% \begin{macrocode}
@@ -859,10 +851,10 @@
\cs_generate_variant:Nn \vbox_gset_top:Nn {cn}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\vbox_set_to_ht:Nnn,\vbox_set_to_ht:cnn}
-% \begin{macro}{\vbox_gset_to_ht:Nnn,\vbox_gset_to_ht:cnn,\vbox_gset_to_ht:ccn}
+% \begin{macro}{\vbox_set_to_ht:Nnn,\vbox_set_to_ht:cnn,
+% \vbox_gset_to_ht:Nnn,\vbox_gset_to_ht:cnn,\vbox_gset_to_ht:ccn}
+% \testfile*
% Storing material in a vertical box with a specified height.
% \begin{macrocode}
\cs_new_protected:Npn \vbox_set_to_ht:Nnn #1#2#3 {
@@ -873,13 +865,13 @@
\cs_generate_variant:Nn \vbox_gset_to_ht:Nnn {cnn,ccn}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
-% \begin{macro}{\vbox_set_inline_begin:N}
-% \begin{macro}{\vbox_set_inline_end:}
-% \begin{macro}{\vbox_gset_inline_begin:N}
-% \begin{macro}{\vbox_gset_inline_end:}
+% \begin{macro}{\vbox_set_inline_begin:N,
+% \vbox_set_inline_end:,
+% \vbox_gset_inline_begin:N,
+% \vbox_gset_inline_end:}
+% \testfile*
% Storing material in a vertical box. This type is useful in
% environment definitions.
% \begin{macrocode}
@@ -891,22 +883,19 @@
\cs_new_eq:NN \vbox_gset_inline_end: \c_group_end_token
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
%
-% \begin{macro}{\vbox_to_ht:nn}
-% \begin{macro}{\vbox_to_zero:n}
+% \begin{macro}{\vbox_to_ht:nn,\vbox_to_zero:n}
+% \testfile*
% Put a vertical box directly into the input stream.
% \begin{macrocode}
\cs_new_protected:Npn \vbox_to_ht:nn #1#2{\tex_vbox:D to \dim_eval:n{#1}{#2}}
\cs_new_protected:Npn \vbox_to_zero:n #1 {\tex_vbox:D to \c_zero_dim {#1}}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
% \begin{macro}{\vbox_set_split_to_ht:NNn}
+% \testfile*
% Splitting a vertical box in two.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \vbox_set_split_to_ht:NNn #1#2#3{
@@ -915,8 +904,9 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\vbox_unpack:N,\vbox_unpack:c}
-% \begin{macro}{\vbox_unpack_clear:N,\vbox_unpack_clear:c}
+% \begin{macro}{\vbox_unpack:N,\vbox_unpack:c,
+% \vbox_unpack_clear:N,\vbox_unpack_clear:c}
+% \testfile*
% Unpacking a box and if requested also clear it.
% \begin{macrocode}
\cs_new_eq:NN \vbox_unpack:N \tex_unvcopy:D
@@ -925,7 +915,6 @@
\cs_generate_variant:Nn \vbox_unpack_clear:N {c}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
%
@@ -937,13 +926,15 @@
%
% \begin{macro}{\hbox:n}
% Put a horizontal box directly into the input stream.
+% \testfile{m3box002.lvt}
% \begin{macrocode}
\cs_new_protected_nopar:Npn \hbox:n {\tex_hbox:D \scan_stop:}
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\hbox_set:Nn,\hbox_set:cn}
-% \begin{macro}{\hbox_gset:Nn,\hbox_gset:cn}
+% \begin{macro}{\hbox_set:Nn,\hbox_set:cn,
+% \hbox_gset:Nn,\hbox_gset:cn}
+% \testfile*
% Assigning the contents of a box to be another box.
% This clears the second box globally (that's how \TeX{} does it).
% \begin{macrocode}
@@ -953,10 +944,10 @@
\cs_generate_variant:Nn \hbox_gset:Nn {cn}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\hbox_set_to_wd:Nnn,\hbox_set_to_wd:cnn}
-% \begin{macro}{\hbox_gset_to_wd:Nnn,\hbox_gset_to_wd:cnn}
+% \begin{macro}{\hbox_set_to_wd:Nnn,\hbox_set_to_wd:cnn,
+% \hbox_gset_to_wd:Nnn,\hbox_gset_to_wd:cnn}
+% \testfile*
% Storing material in a horizontal box with a specified width.
% \begin{macrocode}
\cs_new_protected:Npn \hbox_set_to_wd:Nnn #1#2#3 {
@@ -967,12 +958,12 @@
\cs_generate_variant:Nn \hbox_gset_to_wd:Nnn {cnn}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\hbox_set_inline_begin:N,\hbox_set_inline_begin:c}
-% \begin{macro}{\hbox_set_inline_end:}
-% \begin{macro}{\hbox_gset_inline_begin:N,\hbox_gset_inline_begin:c}
-% \begin{macro}{\hbox_gset_inline_end:}
+% \begin{macro}{\hbox_set_inline_begin:N,\hbox_set_inline_begin:c,
+% \hbox_gset_inline_begin:N,\hbox_gset_inline_begin:c,
+% \hbox_set_inline_end:,
+% \hbox_gset_inline_end:}
+% \testfile*
% Storing material in a horizontal box. This type is useful in
% environment definitions.
% \begin{macrocode}
@@ -988,23 +979,18 @@
\cs_new_eq:NN \hbox_gset_inline_end: \c_group_end_token
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\hbox_to_wd:nn}
-% \begin{macro}{\hbox_to_zero:n}
+% \begin{macro}{\hbox_to_wd:nn,\hbox_to_zero:n}
+% \testfile*
% Put a horizontal box directly into the input stream.
% \begin{macrocode}
\cs_new_protected:Npn \hbox_to_wd:nn #1#2 {\tex_hbox:D to #1 {#2}}
\cs_new_protected:Npn \hbox_to_zero:n #1 {\tex_hbox:D to \c_zero_skip {#1}}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
-% \begin{macro}{\hbox_overlap_left:n}
-% \begin{macro}{\hbox_overlap_right:n}
+% \begin{macro}{\hbox_overlap_left:n,\hbox_overlap_right:n}
% Put a zero-sized box with the contents pushed against one side (which
% makes it stick out on the other) directly into the input stream.
% \begin{macrocode}
@@ -1012,11 +998,11 @@
\cs_new_protected:Npn \hbox_overlap_right:n #1 {\hbox_to_zero:n {#1 \tex_hss:D}}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
-% \begin{macro}{\hbox_unpack:N,\hbox_unpack:c}
-% \begin{macro}{\hbox_unpack_clear:N,\hbox_unpack_clear:c}
+% \begin{macro}{\hbox_unpack:N,\hbox_unpack:c,
+% \hbox_unpack_clear:N,\hbox_unpack_clear:c}
+% \testfile*
% Unpacking a box and if requested also clear it.
% \begin{macrocode}
\cs_new_eq:NN \hbox_unpack:N \tex_unhcopy:D
@@ -1025,7 +1011,6 @@
\cs_generate_variant:Nn \hbox_unpack_clear:N {c}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
%