diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3box.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3box.dtx | 62 |
1 files changed, 47 insertions, 15 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3box.dtx b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx index 4a1d1b34627..d864dc55b4c 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/07/19} +% \date{Released 2017/09/18} % % \maketitle % @@ -67,7 +67,7 @@ % \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}. +% \cs{c_empty_box}. % \end{function} % % \begin{function} @@ -139,13 +139,34 @@ % \end{texnote} % \end{function} % -% \begin{function}{\box_use_clear:N, \box_use_clear:c} +% \begin{function}{\box_use_drop:N, \box_use_drop:c} % \begin{syntax} -% \cs{box_use_clear:N} \meta{box} +% \cs{box_use_drop: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}. +% list for typesetting. The \meta{box} is then cleared at the group level the +% box was set at, \emph{i.e.}~the current content is \enquote{dropped} entirely. +% For example, with +% \begin{verbatim} +% \hbox_set:Nn \l_tmpa_box { A } +% \group_begin: +% \hbox_set:Nn \l_tmpa_box { B } +% \group_begin: +% \box_use_drop:N \l_tmpa_box +% \group_end: +% \box_show:N \l_tmpa_box +% \group_end: +% \box_show:N \l_tmpa_box +% \end{verbatim} +% the first use of |\box_show:N| will show an entirely cleared (void) box, and the +% second will show the letter |A| in the box. +% +% This function is useful as boxes can contain an open-ended amount of material. As +% such, they can have a significant memory impact on \TeX{}. At the same time, it is +% often the case that once a box has been inserted, it is no longer needed at all. +% Using |\box_use_drop:N| in these circumstances therefore offers improved memory +% use and performance. It should therefore be preferred over \cs{box_use:N} where +% it is clear that the content is no longer needed in the variable. % \begin{texnote} % This is the \TeX{} primitive \tn{box}. % \end{texnote} @@ -170,7 +191,7 @@ % \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 +% such that its reference point is displaced vertically by the given % \meta{dimexpr} from the reference point for typesetting, up % or down as appropriate. The \meta{box function} should be % a box operation such as |\box_use:N \<box>| or a \enquote{raw} @@ -283,6 +304,9 @@ % \begin{variable}[updated = 2012-11-04]{\c_empty_box} % This is a permanently empty box, which is neither set as horizontal % nor vertical. +% \begin{texnote} +% At the \TeX{} level this is a void box. +% \end{texnote} % \end{variable} % % \section{Scratch boxes} @@ -604,7 +628,7 @@ % \end{texnote} % \end{function} % -% \subsection{Affine transformations} +% \section{Affine transformations} % % Affine transformations are changes which (informally) preserve straight % lines. Simple translations are affine transformations, but are better handled @@ -968,14 +992,14 @@ % % \subsection{Using boxes} % -% \begin{macro}{\box_use_clear:N, \box_use_clear:c} +% \begin{macro}{\box_use_drop:N, \box_use_drop: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_drop: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_drop:N { c } \cs_generate_variant:Nn \box_use:N { c } % \end{macrocode} % \end{macro} @@ -1166,7 +1190,7 @@ % \end{macrocode} % \end{macro} % -% \subsection{Horizontal mode boxes} +% \subsection{Horizontal mode boxes} % % \begin{macro}{\hbox:n} % \testfile{m3box002.lvt} @@ -1629,7 +1653,7 @@ \box_set_dp:Nn \l_@@_internal_box { -\l_@@_bottom_new_dim } \box_set_wd:Nn \l_@@_internal_box { \l_@@_right_new_dim - \l_@@_left_new_dim } - \box_use:N \l_@@_internal_box + \box_use_drop:N \l_@@_internal_box } % \end{macrocode} % \end{macro} @@ -1982,7 +2006,7 @@ \hbox_to_wd:nn { \l_@@_right_new_dim } { \tex_kern:D \l_@@_right_new_dim - \box_use:N \l_@@_internal_box + \box_use_drop:N \l_@@_internal_box \tex_hss:D } } @@ -1991,7 +2015,7 @@ \hbox:n { \tex_kern:D \c_zero_dim - \box_use:N \l_@@_internal_box + \box_use_drop:N \l_@@_internal_box \tex_hss:D } } @@ -2002,6 +2026,7 @@ % \subsection{Deprecated functions} % % \begin{macro}[deprecated = 2018-12-31]{\box_resize:Nnn, \box_resize:cnn} +% \begin{macro}[deprecated = 2018-12-31]{\box_use_clear:N, \box_use_clear:c} % \begin{macrocode} \__debug_deprecation:nnNNpn { 2018-12-31 } { \box_resize_to_wd_and_ht_plus_dp:Nnn } @@ -2011,8 +2036,15 @@ { 2018-12-31 } { \box_resize_to_wd_and_ht_plus_dp:cnn } \cs_new_protected:Npn \box_resize:cnn { \box_resize_to_wd_and_ht_plus_dp:cnn } +\__debug_deprecation:nnNNpn + { 2018-12-31 } { \box_use_clear:N } +\cs_new_protected:Npn \box_use_clear:N { \box_use_drop:N } +\__debug_deprecation:nnNNpn + { 2018-12-31 } { \box_use_clear:c } +\cs_new_protected:Npn \box_use_clear:c { \box_use_drop:c } % \end{macrocode} % \end{macro} +% \end{macro} % % \begin{macrocode} %</initex|package> |