summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3box.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3box.dtx1237
1 files changed, 1237 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3box.dtx b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
new file mode 100644
index 00000000000..1947f85b356
--- /dev/null
+++ b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
@@ -0,0 +1,1237 @@
+% \iffalse meta-comment
+%
+%% File: l3box.dtx Copyright (C) 2005-2011 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
+%% license or (at your option) any later version. The latest version
+%% of this license is in the file
+%%
+%% http://www.latex-project.org/lppl.txt
+%%
+%% This file is part of the "expl3 bundle" (The Work in LPPL)
+%% and all files in that bundle must be distributed together.
+%%
+%% The released version of this bundle is available from CTAN.
+%%
+%% -----------------------------------------------------------------------
+%%
+%% The development version of the bundle can be found at
+%%
+%% http://www.latex-project.org/svnroot/experimental/trunk/
+%%
+%% for those people who are interested.
+%%
+%%%%%%%%%%%
+%% NOTE: %%
+%%%%%%%%%%%
+%%
+%% Snapshots taken from the repository represent work in progress and may
+%% not work or may contain conflicting material! We therefore ask
+%% people _not_ to put them into distributions, archives, etc. without
+%% prior consultation with the LaTeX3 Project.
+%%
+%% -----------------------------------------------------------------------
+%
+%<*driver|package>
+\RequirePackage{l3names}
+\GetIdInfo$Id: l3box.dtx 2478 2011-06-19 21:34:23Z joseph $
+ {L3 Experimental boxes}
+%</driver|package>
+%<*driver>
+\documentclass[full]{l3doc}
+\begin{document}
+ \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \title{^^A
+% The \pkg{l3box} package\\ Boxes^^A
+% \thanks{This file describes v\ExplFileVersion,
+% last revised \ExplFileDate.}^^A
+% }
+%
+% \author{^^A
+% The \LaTeX3 Project\thanks
+% {^^A
+% E-mail:
+% \href{mailto:latex-team@latex-project.org}
+% {latex-team@latex-project.org}^^A
+% }^^A
+% }
+%
+% \date{Released \ExplFileDate}
+%
+% \maketitle
+%
+% \begin{documentation}
+%
+% There are three kinds of box operations: horizontal mode denoted
+% with prefix |\hbox_|, vertical mode with prefix |\vbox_|, and the
+% generic operations working in both modes with prefix |\box_|.
+%
+% \section{Creating and initialising boxes}
+%
+% \begin{function}{\box_new:N, \box_new:c}
+% \begin{syntax}
+% \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.
+% \end{function}
+%
+% \begin{function}{\box_clear:N, \box_clear:c}
+% \begin{syntax}
+% \cs{box_clear:N} \meta{box}
+% \end{syntax}
+% Clears the content of the \meta{box} by setting the box equal to
+% \cs{c_void_box} within the current \TeX{} group level.
+% \end{function}
+%
+% \begin{function}{\box_gclear:N, \box_gclear:c}
+% \begin{syntax}
+% \cs{box_gclear:N} \meta{box}
+% \end{syntax}
+% Clears the content of the \meta{box} by setting the box equal to
+% \cs{c_void_box} globally.
+% \end{function}
+%
+% \begin{function}{\box_clear_new:N, \box_clear_new:c}
+% \begin{syntax}
+% \cs{box_clear_new:N} \meta{box}
+% \end{syntax}
+% If the \meta{box} is not defined, globally creates it. If the \meta{box}
+% is defined,
+% clears the content of the \meta{box} by setting the box equal to
+% \cs{c_void_box} within the current \TeX{} group level.
+% \end{function}
+%
+% \begin{function}{\box_gclear_new:N, \box_gclear_new:c}
+% \begin{syntax}
+% \cs{box_gclear_new:N} \meta{box}
+% \end{syntax}
+% If the \meta{box} is not defined, globally creates it. If the \meta{box}
+% is defined,
+% clears the content of the \meta{box} by setting the box equal to
+% \cs{c_void_box} globally.
+% \end{function}
+%
+% \begin{function}
+% {\box_set_eq:NN, \box_set_eq:cN, \box_set_eq:Nc, \box_set_eq:cc}
+% \begin{syntax}
+% \cs{box_set_eq:NN} \meta{box1} \meta{box2}
+% \end{syntax}
+% Sets the content of \meta{box1} equal to that of \meta{box2}. This
+% assignment is restricted to the current \TeX{} group level.
+% \end{function}
+%
+% \begin{function}
+% {\box_gset_eq:NN, \box_gset_eq:cN, \box_gset_eq:Nc, \box_gset_eq:cc}
+% \begin{syntax}
+% \cs{box_gset_eq:NN} \meta{box1} \meta{box2}
+% \end{syntax}
+% Sets the content of \meta{box1} equal to that of \meta{box2} globally.
+% \end{function}
+%
+% \begin{function}
+% {
+% \box_set_eq_clear:NN, \box_set_eq_clear:cN,
+% \box_set_eq_clear:Nc, \box_set_eq_clear:cc
+% }
+% \begin{syntax}
+% \cs{box_set_eq_clear:NN} \meta{box1} \meta{box2}
+% \end{syntax}
+% Sets the content of \meta{box1} within the current \TeX{} group
+% equal to that of \meta{box2}, then clears \meta{box2} globally.
+% \end{function}
+%
+% \begin{function}
+% {
+% \box_gset_eq_clear:NN, \box_gset_eq_clear:cN,
+% \box_gset_eq_clear:Nc, \box_gset_eq_clear:cc
+% }
+% \begin{syntax}
+% \cs{box_gset_eq_clear:NN} \meta{box1} \meta{box2}
+% \end{syntax}
+% Sets the content of \meta{box1} equal to that of \meta{box2}, then
+% clears \meta{box2}. These assignments are global.
+% \end{function}
+%
+% \section{Using boxes}
+%
+% \begin{function}{\box_use:N, \box_use:c}
+% \begin{syntax}
+% \cs{box_use:N} \meta{box}
+% \end{syntax}
+% Inserts the current content of the \meta{box} onto the current
+% list for typesetting.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{copy}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}{\box_use_clear:N, \box_use_clear:c}
+% \begin{syntax}
+% \cs{box_use_clear:N} \meta{box}
+% \end{syntax}
+% Inserts the current content of the \meta{box} onto the current
+% list for typesetting, then globally clears the content of the
+% \meta{box}.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{box}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}{\box_move_right:nn, \box_move_left:nn}
+% \begin{syntax}
+% \cs{box_move_right:nn} \Arg{dimexpr} \Arg{box function}
+% \end{syntax}
+% This function operates in vertical mode, and inserts the
+% material specified by the \meta{box function}
+% such that its reference point is displaced horizontally by the given
+% \meta{dimexpr} from the reference point for typesetting, to the right
+% or left as appropriate. The \meta{box function} should be
+% a box opeeration such as |\box_use:N \<box>| or a \enquote{raw}
+% box specification such as |\vbox:n { xyz }|.
+% \end{function}
+%
+% \begin{function}{\box_move_up:nn, \box_move_down:nn}
+% \begin{syntax}
+% \cs{box_move_up:nn} \Arg{dimexpr} \Arg{box function}
+% \end{syntax}
+% This function operates in horizontal mode, and inserts the
+% material specified by the \meta{box function}
+% such that its reference point is displaced vertical by the given
+% \meta{dimexpr} from the reference point for typesetting, up
+% or down as appropriate. The \meta{box function} should be
+% a box opeeration such as |\box_use:N \<box>| or a \enquote{raw}
+% box specification such as |\vbox:n { xyz }|.
+% \end{function}
+%
+% \section{Measuring and setting box dimensions}
+%
+% \begin{function}{\box_dp:N, \box_dp:c}
+% \begin{syntax}
+% \cs{box_dp:N} \meta{box}
+% \end{syntax}
+% Calculates the depth (below the baseline) of the \meta{box}
+% and leaves this in the input stream. The output of this function
+% is suitable for use in a \meta{dimension expression} for
+% calculations.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{dp}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}{\box_ht:N, \box_ht:c}
+% \begin{syntax}
+% \cs{box_ht:N} \meta{box}
+% \end{syntax}
+% Calculates the height (above the baseline) of the \meta{box}
+% and leaves this in the input stream. The output of this function
+% is suitable for use in a \meta{dimension expression} for
+% calculations.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{ht}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}{\box_wd:N, \box_wd:c}
+% \begin{syntax}
+% \cs{box_wd:N} \meta{box}
+% \end{syntax}
+% Calculates the width of the \meta{box} and leaves this in the
+% input stream. The output of this function is suitable for use in a
+% \meta{dimension expression} for calculations.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{wd}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}{\box_set_dp:Nn, \box_set_dp:cn}
+% \begin{syntax}
+% \cs{box_set_dp:Nn} \meta{box} \Arg{dimension expression}
+% \end{syntax}
+% Set the depth (below the baseline) of the \meta{box} to the value of
+% the \Arg{dimension expression}. This is a global assignment.
+% \end{function}
+%
+% \begin{function}{\box_set_ht:Nn, \box_set_ht:cn}
+% \begin{syntax}
+% \cs{box_set_ht:Nn} \meta{box} \Arg{dimension expression}
+% \end{syntax}
+% Set the height (above the baseline) of the \meta{box} to the value of
+% the \Arg{dimension expression}. This is a global assignment.
+% \end{function}
+%
+% \begin{function}{\box_set_wd:Nn, \box_set_wd:cn}
+% \begin{syntax}
+% \cs{box_set_wd:Nn} \meta{box} \Arg{dimension expression}
+% \end{syntax}
+% Set the width of the \meta{box} to the value of the
+% \Arg{dimension expression}. This is a global assignment.
+% \end{function}
+%
+% \section{Box conditionals}
+%
+% \begin{function}[EXP,pTF]{\box_if_empty:N, \box_if_empty:c}
+% \begin{syntax}
+% \cs{box_if_empty_p:N} \meta{box}
+% \cs{box_if_empty:NTF} \meta{box} \Arg{true code} \Arg{false code}
+% \end{syntax}
+% Tests if \meta{box} is a empty (equal to \cs{c_empty_box}).
+% The branching versions then leave either
+% \meta{true code} or \meta{false code} in the input stream, as
+% appropriate to the truth of the test and the variant of the function
+% chosen. The logical truth of the test is left in the input stream by
+% the predicate version.
+% \end{function}
+%
+% \begin{function}[EXP,pTF]{\box_if_horizontal:N, \box_if_horizontal:c}
+% \begin{syntax}
+% \cs{box_if_horizontal_p:N} \meta{box}
+% \cs{box_if_horizontal:NTF} \meta{box} \Arg{true code} \Arg{false code}
+% \end{syntax}
+% Tests if \meta{box} is a horizontal box. The branching
+% versions then leave either \meta{true code} or \meta{false code}
+% in the input stream, as appropriate to the truth of the test and
+% the variant of the function chosen. The logical truth of the test
+% is left in the input stream by the predicate version.
+% \end{function}
+%
+% \begin{function}[EXP,pTF]{\box_if_vertical:N, \box_if_vertical:c}
+% \begin{syntax}
+% \cs{box_if_vertical_p:N} \meta{box}
+% \cs{box_if_vertical:NTF} \meta{box} \Arg{true code} \Arg{false code}
+% \end{syntax}
+% Tests if \meta{box} is a vertical box. The branching
+% versions then leave either \meta{true code} or \meta{false code}
+% in the input stream, as appropriate to the truth of the test and
+% the variant of the function chosen. The logical truth of the test
+% is left in the input stream by the predicate version.
+% \end{function}
+%
+% \section{The last box inserted}
+%
+% \begin{variable}{\l_last_box}
+% This is a box containing the last item added to the current partial
+% list, except in the case of the main vertical list (main galley), in
+% which case this box is always void. Notice that although this is
+% not a constant, it is \emph{not} settable by the programmer but is
+% instead varied by \TeX{}.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{lastbox} renamed.
+% \end{texnote}
+% \end{variable}
+%
+% \section{Constant boxes}
+%
+% \begin{variable}{\c_empty_box}
+% This is a permanently empty box, which is neither set as horizontal
+% nor vertical.
+% \end{variable}
+%
+% \section{Scratch boxes}
+%
+% \begin{variable}{\l_tmpa_tl, \l_tmpb_tl}
+% Scratch boxes for local assignment. These are never used by
+% the kernel code, and so are safe for use with any \LaTeX3-defined
+% function. However, they may be overwritten by other non-kernel
+% code and so should only be used for short-term storage.
+% \end{variable}
+%
+% \section{Viewing box contents}
+%
+% \begin{function}{\box_show:N, \box_show:c}
+% \begin{syntax}
+% \cs{box_show:N} \meta{box}
+% \end{syntax}
+% Writes the contents of \meta{box} to the log file.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{showbox}.
+% \end{texnote}
+% \end{function}
+%
+% \section{Horizontal mode boxes}
+%
+% \begin{function}{\hbox:n}
+% \begin{syntax}
+% \cs{hbox:n} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} into a horizontal box of natural
+% width and then includes this box in the current list for typesetting.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{hbox}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}{\hbox_to_wd:nn}
+% \begin{syntax}
+% \cs{hbox_to_wd:nn} \Arg{dimexpr} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} into a horizontal box of width
+% \meta{dimexpr} and then includes this box in the current list for
+% typesetting.
+% \end{function}
+%
+% \begin{function}{\hbox_to_zero:n}
+% \begin{syntax}
+% \cs{hbox_to_zero:n} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} into a horizontal box of zero width
+% and then includes this box in the current list for typesetting.
+% \end{function}
+%
+% \begin{function}{\hbox_set:Nn, \hbox_set:cn}
+% \begin{syntax}
+% \cs{hbox_set:Nn} \meta{box} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} at natural width and then stores the
+% result inside the \meta{box}. The assignment is local.
+% \end{function}
+%
+% \begin{function}{\hbox_gset:Nn, \hbox_gset:cn}
+% \begin{syntax}
+% \cs{hbox_gset:Nn} \meta{box} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} at natural width and then stores the
+% result inside the \meta{box}. The assignment is global.
+% \end{function}
+%
+% \begin{function}{\hbox_set_to_wd:Nnn, \hbox_set_to_wd:cnn}
+% \begin{syntax}
+% \cs{hbox_set_to_wd:Nnn} \meta{box} \Arg{dimexpr} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} to the width given by the \meta{dimexpr}
+% and then stores the result inside the \meta{box}. The assignment is
+% local.
+% \end{function}
+%
+% \begin{function}{\hbox_gset_to_wd:Nnn, \hbox_gset_to_wd:cnn}
+% \begin{syntax}
+% \cs{hbox_gset_to_wd:Nnn} \meta{box} \Arg{dimexpr} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} to the width given by the \meta{dimexpr}
+% and then stores the result inside the \meta{box}. The assignment is
+% global.
+% \end{function}
+%
+% \begin{function}{\hbox_overlap_right:n}
+% \begin{syntax}
+% \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.
+% \end{function}
+%
+% \begin{function}{\hbox_overlap_left:n}
+% \begin{syntax}
+% \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.
+% \end{function}
+%
+% \begin{function}
+% {
+% \hbox_set_inline_begin:N, \hbox_set_inline_begin:c,
+% \hbox_set_inline_end:
+% }
+% \begin{syntax}
+% \cs{hbox_set_inline_begin:N} \meta{box} \meta{contents}
+% ~~\cs{hbox_set_inline_end:}
+% \end{syntax}
+% Typesets the \meta{contents} at natural width and then stores the
+% result inside the \meta{box}. The assignment is local. In contrast
+% to \cs{hbox_set:Nn} 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_gset_inline_begin:N, \hbox_gset_inline_begin:c,
+% \hbox_gset_inline_end:
+% }
+% \begin{syntax}
+% \cs{hbox_gset_inline_begin:N} \meta{box} \meta{contents}
+% ~~\cs{hbox_gset_inline_end:}
+% \end{syntax}
+% Typesets the \meta{contents} at natural width and then stores the
+% result inside the \meta{box}. The assignment is global. In contrast
+% to \cs{hbox_set:Nn} 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}
+% \end{syntax}
+% Unpacks the content of the horizontal \meta{box}, retaining any stretching
+% or shrinking applied when the \meta{box} was set.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{unhcopy}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}{\hbox_unpack_clear:N, \hbox_unpack_clear:c}
+% \begin{syntax}
+% \cs{hbox_unpack_clear:N} \meta{box}
+% \end{syntax}
+% Unpacks the content of the horizontal \meta{box}, retaining any stretching
+% or shrinking applied when the \meta{box} was set. The \meta{box} is
+% then cleared globally.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{unhbox}.
+% \end{texnote}
+% \end{function}
+%
+% \section{Vertical mode boxes}
+%
+% 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
+% 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 later will typically be non-zero.
+%
+% \begin{function}{\vbox:n}
+% \begin{syntax}
+% \cs{vbox:n} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} into a vertical box of natural height
+% and includes this box in the current list for typesetting.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{vbox}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}{\vbox_top:n}
+% \begin{syntax}
+% \cs{vbox_top:n} \Arg{contents}
+% \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 tbe equal to that of the \emph{first}
+% item added to the box.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{vtop}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}{\vbox_to_ht:nn}
+% \begin{syntax}
+% \cs{vbox_to_ht:n} \Arg{contents} \Arg{dimexpr}
+% \end{syntax}
+% Typesets the \meta{contents} into a vertical box of height
+% \meta{dimexpr} and then includes this box in the current list for
+% typesetting.
+% \end{function}
+%
+% \begin{function}{\vbox_to_zero:n}
+% \begin{syntax}
+% \cs{vbox_to_zero:n} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} into a vertical box of zero height
+% and then includes this box in the current list for typesetting.
+% \end{function}
+%
+% \begin{function}{\vbox_set:Nn, \vbox_set:cn}
+% \begin{syntax}
+% \cs{vbox_set:Nn} \meta{box} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} at natural height and then stores the
+% result inside the \meta{box}. The assignment is local.
+% \end{function}
+%
+% \begin{function}{\vbox_gset:Nn, \vbox_gset:cn}
+% \begin{syntax}
+% \cs{vbox_gset:Nn} \meta{box} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} at natural height and then stores the
+% result inside the \meta{box}. The assignment is global.
+% \end{function}
+%
+% \begin{function}{\vbox_set_top:Nn, \vbox_set_top:cn}
+% \begin{syntax}
+% \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 tbe equal
+% to that of the \emph{first} item added to the box. The assignment is
+% local.
+% \end{function}
+%
+% \begin{function}{\vbox_gset_top:Nn, \vbox_gset_top:cn}
+% \begin{syntax}
+% \cs{vbox_gset_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 tbe equal
+% to that of the \emph{first} item added to the box. The assignment is
+% global.
+% \end{function}
+%
+% \begin{function}{\vbox_set_to_ht:Nnn, \vbox_set_to_ht:cnn}
+% \begin{syntax}
+% \cs{vbox_set_to_ht:Nnn} \meta{box} \Arg{dimexpr} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} to the height given by the
+% \meta{dimexpr} and then stores the result inside the \meta{box}.
+% The assignment is local.
+% \end{function}
+%
+% \begin{function}{\vbox_gset_to_ht:Nnn, \vbox_gset_to_ht:cnn}
+% \begin{syntax}
+% \cs{vbox_gset_to_ht:Nnn} \meta{box} \Arg{dimexpr} \Arg{contents}
+% \end{syntax}
+% Typesets the \meta{contents} to the height given by the
+% \meta{dimexpr} and then stores the result inside the \meta{box}.
+% The assignment is global.
+% \end{function}
+%
+% \begin{function}
+% {
+% \vbox_set_inline_begin:N, \vbox_set_inline_begin:c,
+% \vbox_set_inline_end:
+% }
+% \begin{syntax}
+% \cs{vbox_set_inline_begin:N} \meta{box} \meta{contents}
+% ~~\cs{vbox_set_inline_end:}
+% \end{syntax}
+% Typesets the \meta{contents} at natural height and then stores the
+% result inside the \meta{box}. The assignment is local. In contrast
+% to \cs{vbox_set:Nn} 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}
+% {
+% \vbox_gset_inline_begin:N, \vbox_gset_inline_begin:c,
+% \vbox_gset_inline_end:
+% }
+% \begin{syntax}
+% \cs{vbox_gset_inline_begin:N} \meta{box} \meta{contents}
+% ~~\cs{vbox_set_inline_end:}
+% \end{syntax}
+% Typesets the \meta{contents} at natural height and then stores the
+% result inside the \meta{box}. The assignment is global. In contrast
+% to \cs{vbox_set:Nn} 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}{\vbox_set_split_to_ht:NNn}
+% \begin{syntax}
+% \cs{vbox_set_split_to_ht:NNn} \meta{box1} \meta{box2} \Arg{dimexpr}
+% \end{syntax}
+% Sets \meta{box1} to contain material to the height given by the
+% \meta{dimexpr} by removing content from the top of \meta{box2}
+% (which must be a vertical box).
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{vsplit}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}{\vbox_unpack:N, \vbox_unpack:c}
+% \begin{syntax}
+% \cs{vbox_unpack:N} \meta{box}
+% \end{syntax}
+% Unpacks the content of the vertical \meta{box}, retaining any stretching
+% or shrinking applied when the \meta{box} was set.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{unvcopy}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}{\vbox_unpack_clear:N, \vbox_unpack_clear:c}
+% \begin{syntax}
+% \cs{vbox_unpack:N} \meta{box}
+% \end{syntax}
+% Unpacks the content of the vertical \meta{box}, retaining any stretching
+% or shrinking applied when the \meta{box} was set. The \meta{box}
+% is then cleared globally.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{unvbox}.
+% \end{texnote}
+% \end{function}
+%
+% \section{Primitive box conditionals}
+%
+% \begin{function}[EXP]{\if_hbox:N}
+% \begin{syntax}
+% \cs{if_hbox:N} \meta{box}
+% ~~\meta{true code}
+% \cs{else:}
+% ~~\meta{false code}
+% \cs{fi:}
+% \end{syntax}
+% Tests is \meta{box} is a horizontal box.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{ifhbox}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}[EXP]{\if_vbox:N}
+% \begin{syntax}
+% \cs{if_vbox:N} \meta{box}
+% ~~\meta{true code}
+% \cs{else:}
+% ~~\meta{false code}
+% \cs{fi:}
+% \end{syntax}
+% Tests is \meta{box} is a vertical box.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{ifvbox}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}[EXP]{\if_box_empty:N}
+% \begin{syntax}
+% \cs{if_box_empty:N} \meta{box}
+% ~~\meta{true code}
+% \cs{else:}
+% ~~\meta{false code}
+% \cs{fi:}
+% \end{syntax}
+% Tests is \meta{box} is an empty (void) box.
+% \begin{texnote}
+% This is the \TeX{} primitive \cs{ifvoid}.
+% \end{texnote}
+% \end{function}
+%
+% \end{documentation}
+%
+% \begin{implementation}
+%
+% \section{\pkg{l3box} implementation}
+%
+% \begin{macrocode}
+%<*initex|package>
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<*package>
+\ProvidesExplPackage
+ {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
+\package_check_loaded_expl:
+%<*initex|package>
+% \end{macrocode}
+%
+% The code in this module is very straight forward so I'm not going to
+% comment it very extensively.
+%
+% \subsection{Creating and initialising boxes}
+%
+% \TestFiles{m3box001.lvt}
+%
+% \begin{macro}{\box_new:N,\box_new:c}
+% Defining a new \meta{box} register: remember that box $255$ is not
+% generally available.
+% \begin{macrocode}
+%<*initex>
+\alloc_new:nnnN { box } \c_zero \c_max_register_int \tex_mathchardef:D
+\seq_put_right:Nn \g_box_allocation_seq {255}
+%</initex>
+%<*package>
+\cs_new_protected:Npn \box_new:N #1
+ {
+ \chk_if_free_cs:N #1
+ \newbox #1
+ }
+%</package>
+\cs_generate_variant:Nn \box_new:N { c }
+% \end{macrocode}
+%
+% \begin{macro}{\box_clear:N, \box_clear:c}
+% \begin{macro}{\box_gclear:N, \box_gclear:c}
+% \testfile*
+% Clear a \meta{box} register.
+% \begin{macrocode}
+\cs_new_protected_nopar:Npn \box_clear:N #1
+ { \box_set_eq:NN #1 \c_empty_box }
+\cs_new_protected_nopar:Npn \box_gclear:N #1
+ { \box_gset_eq:NN #1 \c_empty_box }
+\cs_generate_variant:Nn \box_clear:N { c }
+\cs_generate_variant:Nn \box_gclear:N { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\box_clear_new:N, \box_clear_new:c}
+% \begin{macro}{\box_gclear_new:N, \box_gclear_new:c}
+% \testfile*
+% Clear or new.
+% \begin{macrocode}
+\cs_new_protected_nopar:Npn \box_clear_new:N #1
+ {
+ \cs_if_exist:NTF #1
+ { \box_set_eq:NN #1 \c_empty_box }
+ { \box_new:N #1 }
+ }
+\cs_new_protected_nopar:Npn \box_gclear_new:N #1
+ {
+ \cs_if_exist:NTF #1
+ { \box_gset_eq:NN #1 \c_empty_box }
+ { \box_new:N #1 }
+ }
+\cs_generate_variant:Nn \box_clear_new:N { c }
+\cs_generate_variant:Nn \box_gclear_new:N { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}
+% {\box_set_eq:NN, \box_set_eq:cN, \box_set_eq:Nc, \box_set_eq:cc}
+% \testfile*
+% \begin{macro}
+% {\box_gset_eq:NN, \box_gset_eq:cN, \box_gset_eq:Nc, \box_gset_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 }
+\cs_new_protected_nopar:Npn \box_gset_eq:NN
+ { \pref_global:D \box_set_eq:NN }
+\cs_generate_variant:Nn \box_set_eq:NN { cN , Nc , cc }
+\cs_generate_variant:Nn \box_gset_eq:NN { cN , Nc , cc }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}
+% {
+% \box_set_eq_clear:NN, \box_set_eq_clear:cN,
+% \box_set_eq_clear:Nc, \box_set_eq_clear:cc
+% }
+% \testfile*
+% \begin{macro}
+% {
+% \box_gset_eq_clear:NN, \box_gset_eq_clear:cN,
+% \box_gset_eq_clear:Nc, \box_gset_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}
+\cs_new_protected_nopar:Npn \box_set_eq_clear:NN #1#2
+ { \tex_setbox:D #1 \tex_box:D #2 }
+\cs_new_protected_nopar:Npn \box_gset_eq_clear:NN
+ { \pref_global:D \box_set_eq_clear:NN }
+\cs_generate_variant:Nn \box_set_eq_clear:NN { cN , Nc , cc }
+\cs_generate_variant:Nn \box_gset_eq_clear:NN { cN , Nc , cc }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Measuring and setting box dimensions}
+%
+% \begin{macro}{\box_ht:N,\box_ht:c}
+% \begin{macro}{\box_dp:N,\box_dp:c}
+% \begin{macro}{\box_wd:N,\box_wd:c}
+% \testfile*
+% Accessing the height, depth, and width of a \meta{box} register.
+% \begin{macrocode}
+\cs_new_eq:NN \box_ht:N \tex_ht:D
+\cs_new_eq:NN \box_dp:N \tex_dp:D
+\cs_new_eq:NN \box_wd:N \tex_wd:D
+\cs_generate_variant:Nn \box_ht:N { c }
+\cs_generate_variant:Nn \box_dp:N { c }
+\cs_generate_variant:Nn \box_wd:N { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\box_set_ht:Nn, \box_set_ht:cn}
+% \begin{macro}{\box_set_dp:Nn, \box_set_dp:cn}
+% \begin{macro}{\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}
+\cs_new_protected_nopar:Npn \box_set_dp:Nn #1#2
+ { \box_dp:N #1 \dim_eval:w #2 \dim_eval_end: }
+\cs_new_protected_nopar:Npn \box_set_ht:Nn #1#2
+ { \box_ht:N #1 \dim_eval:w #2 \dim_eval_end: }
+\cs_new_protected_nopar:Npn \box_set_wd:Nn #1#2
+ { \box_wd:N #1 \dim_eval:w #2 \dim_eval_end: }
+\cs_generate_variant:Nn \box_set_ht:Nn { c }
+\cs_generate_variant:Nn \box_set_dp:Nn { c }
+\cs_generate_variant:Nn \box_set_wd:Nn { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Using boxes}
+%
+% \begin{macro}{\box_use_clear:N, \box_use_clear:c}
+% \begin{macro}{\box_use:N, \box_use:c}
+% Using a \meta{box}. These are just \TeX{} primitives with meaningful
+% names.
+% \begin{macrocode}
+\cs_new_eq:NN \box_use_clear:N \tex_box:D
+\cs_new_eq:NN \box_use:N \tex_copy:D
+\cs_generate_variant:Nn \box_use_clear:N { c }
+\cs_generate_variant:Nn \box_use:N { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\box_move_left:nn,\box_move_right:nn}
+% \begin{macro}{\box_move_up:nn,\box_move_down:nn}
+% \testfile*
+% Move box material in different directions.
+% \begin{macrocode}
+\cs_new_protected:Npn \box_move_left:nn #1#2
+ { \tex_moveleft:D \dim_eval:w #1 \dim_eval_end: #2 }
+\cs_new_protected:Npn \box_move_right:nn #1#2
+ { \tex_moveright:D \dim_eval:w #1 \dim_eval_end: #2 }
+\cs_new_protected:Npn \box_move_up:nn #1#2
+ { \tex_raise:D \dim_eval:w #1 \dim_eval_end: #2 }
+\cs_new_protected:Npn \box_move_down:nn #1#2
+ { \tex_lower:D \dim_eval:w #1 \dim_eval_end: #2 }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Box conditionals}
+%
+% \begin{macro}{\if_hbox:N}
+% \begin{macro}{\if_vbox:N}
+% \begin{macro}{\if_box_empty:N}
+% \testfile*
+% The primitives for testing if a \meta{box} is empty/void or which
+% type of box it is.
+% \begin{macrocode}
+\cs_new_eq:NN \if_hbox:N \tex_ifhbox:D
+\cs_new_eq:NN \if_vbox:N \tex_ifvbox:D
+\cs_new_eq:NN \if_box_empty:N \tex_ifvoid:D
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}[pTF]{\box_if_horizontal:N,\box_if_horizontal:c}
+% \testfile*
+% \begin{macro}[pTF]{\box_if_vertical:N,\box_if_vertical:c}
+% \testfile*
+% \begin{macrocode}
+\prg_new_conditional:Npnn \box_if_horizontal:N #1 { p , T , F , TF }
+ { \if_hbox:N #1 \prg_return_true: \else: \prg_return_false: \fi: }
+\prg_new_conditional:Npnn \box_if_vertical:N #1 { p , T , F , TF }
+ { \if_vbox:N #1 \prg_return_true: \else: \prg_return_false: \fi: }
+\cs_generate_variant:Nn \box_if_horizontal_p:N { c }
+\cs_generate_variant:Nn \box_if_horizontal:NT { c }
+\cs_generate_variant:Nn \box_if_horizontal:NF { c }
+\cs_generate_variant:Nn \box_if_horizontal:NTF { c }
+\cs_generate_variant:Nn \box_if_vertical_p:N { c }
+\cs_generate_variant:Nn \box_if_vertical:NT { c }
+\cs_generate_variant:Nn \box_if_vertical:NF { c }
+\cs_generate_variant:Nn \box_if_vertical:NTF { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}[pTF]{\box_if_empty:N, \box_if_empty:c}
+% \testfile*
+% Testing if a \meta{box} is empty/void.
+% \begin{macrocode}
+\prg_new_conditional:Npnn \box_if_empty:N #1 { p , T , F , TF }
+ { \if_box_empty:N #1 \prg_return_true: \else: \prg_return_false: \fi: }
+\cs_generate_variant:Nn \box_if_empty_p:N { c }
+\cs_generate_variant:Nn \box_if_empty:NT { c }
+\cs_generate_variant:Nn \box_if_empty:NF { c }
+\cs_generate_variant:Nn \box_if_empty:NTF { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{The last box inserted}
+%
+% \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{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}
+% \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 }
+\cs_new_protected_nopar:Npn \box_gset_to_last:N
+ { \pref_global:D \box_set_to_last:N }
+\cs_generate_variant:Nn \box_set_to_last:N { c }
+\cs_generate_variant:Nn \box_gset_to_last:N { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Constant boxes}
+%
+% \begin{variable}{\c_empty_box}
+% \begin{macrocode}
+%<*package>
+\cs_new_eq:NN \c_empty_box \voidb@x
+%</package>
+%<*initex>
+\box_new:N \c_empty_box
+%</initex>
+% \end{macrocode}
+% \end{variable}
+%
+% \subsection{Scratch boxes}
+%
+% \begin{variable}{\l_tmpa_box, \l_tmpb_box}
+% \begin{macrocode}
+%<*package>
+\cs_new_eq:NN \l_tmpa_box \@tempboxa
+%</package>
+%<*initex>
+\box_new:N \l_tmpa_box
+%</initex>
+\box_new:N \l_tmpb_box
+% \end{macrocode}
+% \end{variable}
+%
+% \subsection{Viewing box contents}
+%
+% \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_new_eq:NN \box_show:N \tex_showbox:D
+\cs_generate_variant:Nn \box_show:N { c }
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Horizontal mode boxes}
+%
+% \begin{macro}{\hbox:n}
+% \testfile{m3box002.lvt}
+% Put a horizontal box directly into the input stream.
+% \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}
+% \testfile*
+% \begin{macrocode}
+\cs_new_protected:Npn \hbox_set:Nn #1#2 { \tex_setbox:D #1 \tex_hbox:D {#2} }
+\cs_new_protected_nopar:Npn \hbox_gset:Nn { \pref_global:D \hbox_set:Nn }
+\cs_generate_variant:Nn \hbox_set:Nn { c }
+\cs_generate_variant:Nn \hbox_gset:Nn { c }
+% \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}
+% \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
+ { \tex_setbox:D #1 \tex_hbox:D to \dim_eval:w #2 \dim_eval_end: {#3} }
+\cs_new_protected_nopar:Npn \hbox_gset_to_wd:Nnn
+ { \pref_global:D \hbox_set_to_wd:Nnn }
+\cs_generate_variant:Nn \hbox_set_to_wd:Nnn { c }
+\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_gset_inline_begin:N, \hbox_gset_inline_begin:c}
+% \begin{macro}{\hbox_set_inline_end:}
+% \begin{macro}{\hbox_gset_inline_end:}
+% \testfile*
+% Storing material in a horizontal box. This type is useful in
+% environment definitions.
+% \begin{macrocode}
+\cs_new_protected_nopar:Npn \hbox_set_inline_begin:N #1
+ { \tex_setbox:D #1 \tex_hbox:D \c_group_begin_token }
+\cs_new_protected_nopar:Npn \hbox_gset_inline_begin:N
+ { \pref_global:D \hbox_set_inline_begin:N }
+\cs_generate_variant:Nn \hbox_set_inline_begin:N { c }
+\cs_generate_variant:Nn \hbox_gset_inline_begin:N { c }
+\cs_new_eq:NN \hbox_set_inline_end: \c_group_end_token
+\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}
+% \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 \dim_eval:w #1 \dim_eval_end: {#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}
+% 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}
+\cs_new_protected:Npn \hbox_overlap_left:n #1
+ { \hbox_to_zero:n { \tex_hss:D #1 } }
+\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}
+% \testfile*
+% Unpacking a box and if requested also clear it.
+% \begin{macrocode}
+\cs_new_eq:NN \hbox_unpack:N \tex_unhcopy:D
+\cs_new_eq:NN \hbox_unpack_clear:N \tex_unhbox:D
+\cs_generate_variant:Nn \hbox_unpack:N { c }
+\cs_generate_variant:Nn \hbox_unpack_clear:N { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Vertical mode boxes}
+%
+% \begin{macro}{\vbox:n}
+% \TestFiles{m3box003.lvt}
+% \begin{macro}{\vbox:n\vbox_top:n}
+% \TestFiles{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: }
+\cs_new_protected_nopar:Npn \vbox_top:n { \tex_vtop:D \scan_stop: }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\vbox_to_ht:nn,\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:w #1 \dim_eval_end: {#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:Nn, \vbox_set:cn}
+% \begin{macro}{\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} }
+\cs_new_protected_nopar:Npn \vbox_gset:Nn { \pref_global:D \vbox_set:Nn }
+\cs_generate_variant:Nn \vbox_set:Nn { c }
+\cs_generate_variant:Nn \vbox_gset:Nn { c }
+% \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}
+% \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}
+\cs_new_protected:Npn \vbox_set_top:Nn #1#2
+ { \tex_setbox:D #1 \tex_vtop:D {#2} }
+\cs_new_protected_nopar:Npn \vbox_gset_top:Nn
+ { \pref_global:D \vbox_set_top:Nn }
+\cs_generate_variant:Nn \vbox_set_top:Nn { c }
+\cs_generate_variant:Nn \vbox_gset_top:Nn { c }
+% \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}
+% \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
+ { \tex_setbox:D #1 \tex_vbox:D to \dim_eval:w #2 \dim_eval_end: {#3} }
+\cs_new_protected_nopar:Npn \vbox_gset_to_ht:Nnn
+ { \pref_global:D \vbox_set_to_ht:Nnn }
+\cs_generate_variant:Nn \vbox_set_to_ht:Nnn { c }
+\cs_generate_variant:Nn \vbox_gset_to_ht:Nnn { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\vbox_set_inline_begin:N, \vbox_set_inline_begin:c}
+% \begin{macro}{\vbox_gset_inline_begin:N, \vbox_gset_inline_begin:c}
+% \begin{macro}{\vbox_set_inline_end:}
+% \begin{macro}{\vbox_gset_inline_end:}
+% \testfile*
+% Storing material in a vertical box. This type is useful in
+% environment definitions.
+% \begin{macrocode}
+\cs_new_nopar:Npn \vbox_set_inline_begin:N #1
+ { \tex_setbox:D #1 \tex_vbox:D \c_group_begin_token }
+\cs_new_protected_nopar:Npn \vbox_gset_inline_begin:N
+ { \pref_global:D \vbox_set_inline_begin:N }
+\cs_generate_variant:Nn \vbox_set_inline_begin:N { c }
+\cs_generate_variant:Nn \vbox_gset_inline_begin:N { c }
+\cs_new_eq:NN \vbox_set_inline_end: \c_group_end_token
+\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_unpack:N, \vbox_unpack:c}
+% \begin{macro}{\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
+\cs_new_eq:NN \vbox_unpack_clear:N \tex_unvbox:D
+\cs_generate_variant:Nn \vbox_unpack:N { c }
+\cs_generate_variant:Nn \vbox_unpack_clear:N { c }
+% \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
+ { \tex_setbox:D #1 \tex_vsplit:D #2 to \dim_eval:w #3 \dim_eval_end: }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</initex|package>
+% \end{macrocode}
+%
+% \end{implementation}
+%
+% \PrintIndex