From 1764edc3b60a2c9fb210ca74b758f3e8e8a53692 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Tue, 25 May 2021 20:48:22 +0000
Subject: l3kernel (25may21)

git-svn-id: svn://tug.org/texlive/trunk@59345 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/source/latex/l3kernel/l3box.dtx | 24 ++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

(limited to 'Master/texmf-dist/source/latex/l3kernel/l3box.dtx')

diff --git a/Master/texmf-dist/source/latex/l3kernel/l3box.dtx b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
index 1eb6848d857..f9cef57a962 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
@@ -43,15 +43,37 @@
 %    }^^A
 % }
 %
-% \date{Released 2021-05-11}
+% \date{Released 2021-05-25}
 %
 % \maketitle
 %
 % \begin{documentation}
 %
+% Box variables contain typeset material that can be inserted on the
+% page or in other boxes.  Their contents cannot be converted back to
+% lists of tokens.
 % 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_|.
+% For instance, a new box variable containing the words \enquote{Hello,
+% world!} (in a horizontal box) can be obtained by the following code.
+% \begin{verbatim}
+% \box_new:N \l_hello_box
+% \hbox_set:Nn \l_hello_box { Hello, ~ world! }
+% \end{verbatim}
+% The argument is typeset inside a \TeX{} group so that any variables
+% assigned during the construction of this box restores its value
+% afterwards.
+%
+% Box variables from \pkg{l3box} are compatible with those of \LaTeXe{}
+% and plain \TeX{} and can be used interchangeably.  The \pkg{l3box}
+% commands to construct boxes, such as \cs{hbox:n} or \cs{hbox_set:Nn},
+% are \enquote{color-safe}, meaning that
+% \begin{verbatim}
+% \hbox:n { \color_select:n { blue } Hello, } ~ world!
+% \end{verbatim}
+% will result in \enquote{Hello,} taking the color blue, but
+% \enquote{world!} remaining with the prevailing color outside the box.
 %
 % \section{Creating and initialising boxes}
 %
-- 
cgit v1.2.3

