[latex3-commits] [git/LaTeX3-latex3-latex3] case-exceptions, main: Move box clipping/viewport functions to stable (83488becc)
Joseph Wright
joseph.wright at morningstar2.co.uk
Mon Apr 17 10:33:59 CEST 2023
Repository : https://github.com/latex3/latex3
On branches: case-exceptions,main
Link : https://github.com/latex3/latex3/commit/83488beccfc008f6c5f2c65c9f485d09eca564e9
>---------------------------------------------------------------
commit 83488beccfc008f6c5f2c65c9f485d09eca564e9
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date: Fri Apr 14 14:14:41 2023 +0100
Move box clipping/viewport functions to stable
>---------------------------------------------------------------
83488beccfc008f6c5f2c65c9f485d09eca564e9
l3kernel/CHANGELOG.md | 4 +
l3kernel/l3box.dtx | 219 +++++++++++++++++++++++++++++++++++++++++++++
l3kernel/l3candidates.dtx | 221 ----------------------------------------------
3 files changed, 223 insertions(+), 221 deletions(-)
diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index aa748468d..11687124e 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -10,6 +10,10 @@ this project uses date-based 'snapshot' version identifiers.
### Added
- `\box_set_clipped:N` and variants
+### Changed
+- `\box_set_trim:Nnnnn` and `\box_set_viewport:Nnnnn` moved to
+ stable kernel
+
### Fixed
- Incorrect internal name in `\pdf_pagesize_gset:nn`
diff --git a/l3kernel/l3box.dtx b/l3kernel/l3box.dtx
index 26fb88edd..9166b7072 100644
--- a/l3kernel/l3box.dtx
+++ b/l3kernel/l3box.dtx
@@ -874,6 +874,68 @@
% dependent on the height of the original and \emph{vice versa}.
% \end{function}
%
+% \section{Viewing part of a box}
+%
+% \begin{function}[updated = 2023-04-14]
+% {
+% \box_set_clipped:N, \box_set_clipped:c,
+% \box_gset_clipped:N, \box_gset_clipped:c
+% }
+% \begin{syntax}
+% \cs{box_set_clipped:N} \meta{box}
+% \end{syntax}
+% Clips the \meta{box} in the output so that only material inside the
+% bounding box is displayed in the output. The updated \meta{box} is an
+% hbox, irrespective of the nature of the \meta{box} before the clipping is
+% applied.
+%
+% \begin{texnote}
+% Clipping is implemented by the driver, and as such the full content of
+% the box is placed in the output file. Thus clipping does not remove
+% any information from the raw output, and hidden material can therefore
+% be viewed by direct examination of the file.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}[added = 2019-01-23]
+% {
+% \box_set_trim:Nnnnn, \box_set_trim:cnnnn,
+% \box_gset_trim:Nnnnn, \box_gset_trim:cnnnn
+% }
+% \begin{syntax}
+% \cs{box_set_trim:Nnnnn} \meta{box} \Arg{left} \Arg{bottom} \Arg{right} \Arg{top}
+% \end{syntax}
+% Adjusts the bounding box of the \meta{box} \meta{left} is removed from
+% the left-hand edge of the bounding box, \meta{right} from the right-hand
+% edge and so fourth. All adjustments are \meta{dim exprs}.
+% Material outside of the bounding box is still displayed in the output
+% unless \cs{box_clip:N} is subsequently applied.
+% The updated \meta{box} is an
+% hbox, irrespective of the nature of the \meta{box} before the trim
+% operation is applied.
+% The behavior of the operation where the trims requested is
+% greater than the size of the box is undefined.
+% \end{function}
+%
+% \begin{function}[added = 2019-01-23]
+% {
+% \box_set_viewport:Nnnnn, \box_set_viewport:cnnnn,
+% \box_gset_viewport:Nnnnn, \box_gset_viewport:cnnnn
+% }
+% \begin{syntax}
+% \cs{box_set_viewport:Nnnnn} \meta{box} \Arg{llx} \Arg{lly} \Arg{urx} \Arg{ury}
+% \end{syntax}
+% Adjusts the bounding box of the \meta{box} such that it has lower-left
+% co-ordinates (\meta{llx}, \meta{lly}) and upper-right co-ordinates
+% (\meta{urx}, \meta{ury}). All four co-ordinate positions are
+% \meta{dim exprs}. Material outside of the bounding box is
+% still displayed in the output unless \cs{box_clip:N} is
+% subsequently applied.
+% The updated \meta{box} is an
+% hbox, irrespective of the nature of the \meta{box} before the viewport
+% operation is applied.
+% \end{function}
+%
% \section{Primitive box conditionals}
%
% \begin{function}[EXP]{\if_hbox:N}
@@ -2297,6 +2359,163 @@
}
% \end{macrocode}
% \end{macro}
+%
+% \subsection{Viewing part of a box}
+%
+% \begin{macro}{\box_set_clipped:N, \box_set_clipped:c, \box_gset_clipped:N, \box_gset_clipped:c}
+% A wrapper around the driver-dependent code.
+% \begin{macrocode}
+\cs_new_protected:Npn \box_set_clipped:N #1
+ { \hbox_set:Nn #1 { \@@_backend_clip:N #1 } }
+\cs_generate_variant:Nn \box_set_clipped:N { c }
+\cs_new_protected:Npn \box_gset_clipped:N #1
+ { \hbox_gset:Nn #1 { \@@_backend_clip:N #1 } }
+\cs_generate_variant:Nn \box_gset_clipped:N { c }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}
+% {
+% \box_set_trim:Nnnnn, \box_set_trim:cnnnn,
+% \box_gset_trim:Nnnnn, \box_gset_trim:cnnnn
+% }
+% \begin{macro}{\@@_set_trim:NnnnnN}
+% Trimming from the left- and right-hand edges of the box is easy: kern the
+% appropriate parts off each side.
+% \begin{macrocode}
+\cs_new_protected:Npn \box_set_trim:Nnnnn #1#2#3#4#5
+ { \@@_set_trim:NnnnnN #1 {#2} {#3} {#4} {#5} \box_set_eq:NN }
+\cs_generate_variant:Nn \box_set_trim:Nnnnn { c }
+\cs_new_protected:Npn \box_gset_trim:Nnnnn #1#2#3#4#5
+ { \@@_set_trim:NnnnnN #1 {#2} {#3} {#4} {#5} \box_gset_eq:NN }
+\cs_generate_variant:Nn \box_gset_trim:Nnnnn { c }
+\cs_new_protected:Npn \@@_set_trim:NnnnnN #1#2#3#4#5#6
+ {
+ \hbox_set:Nn \l_@@_internal_box
+ {
+ \__kernel_kern:n { -#2 }
+ \box_use:N #1
+ \__kernel_kern:n { -#4 }
+ }
+% \end{macrocode}
+% For the height and depth, there is a need to watch the baseline is
+% respected. Material always has to stay on the correct side, so trimming
+% has to check that there is enough material to trim. First, the bottom
+% edge. If there is enough depth, simply set the depth, or if not move
+% down so the result is zero depth. \cs{box_move_down:nn} is used in both
+% cases so the resulting box always contains a \tn{lower} primitive.
+% The internal box is used here as it allows safe use of \cs{box_set_dp:Nn}.
+% \begin{macrocode}
+ \dim_compare:nNnTF { \box_dp:N #1 } > {#3}
+ {
+ \hbox_set:Nn \l_@@_internal_box
+ {
+ \box_move_down:nn \c_zero_dim
+ { \box_use_drop:N \l_@@_internal_box }
+ }
+ \box_set_dp:Nn \l_@@_internal_box { \box_dp:N #1 - (#3) }
+ }
+ {
+ \hbox_set:Nn \l_@@_internal_box
+ {
+ \box_move_down:nn { (#3) - \box_dp:N #1 }
+ { \box_use_drop:N \l_@@_internal_box }
+ }
+ \box_set_dp:Nn \l_@@_internal_box \c_zero_dim
+ }
+% \end{macrocode}
+% Same thing, this time from the top of the box.
+% \begin{macrocode}
+ \dim_compare:nNnTF { \box_ht:N \l_@@_internal_box } > {#5}
+ {
+ \hbox_set:Nn \l_@@_internal_box
+ {
+ \box_move_up:nn \c_zero_dim
+ { \box_use_drop:N \l_@@_internal_box }
+ }
+ \box_set_ht:Nn \l_@@_internal_box
+ { \box_ht:N \l_@@_internal_box - (#5) }
+ }
+ {
+ \hbox_set:Nn \l_@@_internal_box
+ {
+ \box_move_up:nn { (#5) - \box_ht:N \l_@@_internal_box }
+ { \box_use_drop:N \l_@@_internal_box }
+ }
+ \box_set_ht:Nn \l_@@_internal_box \c_zero_dim
+ }
+ #6 #1 \l_@@_internal_box
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}
+% {
+% \box_set_viewport:Nnnnn, \box_set_viewport:cnnnn,
+% \box_gset_viewport:Nnnnn, \box_gset_viewport:cnnnn
+% }
+% \begin{macro}{\@@_viewport:NnnnnN}
+% The same general logic as for the trim operation, but with absolute
+% dimensions. As a result, there are some things to watch out for in the
+% vertical direction.
+% \begin{macrocode}
+\cs_new_protected:Npn \box_set_viewport:Nnnnn #1#2#3#4#5
+ { \@@_set_viewport:NnnnnN #1 {#2} {#3} {#4} {#5} \box_set_eq:NN }
+\cs_generate_variant:Nn \box_set_viewport:Nnnnn { c }
+\cs_new_protected:Npn \box_gset_viewport:Nnnnn #1#2#3#4#5
+ { \@@_set_viewport:NnnnnN #1 {#2} {#3} {#4} {#5} \box_gset_eq:NN }
+\cs_generate_variant:Nn \box_gset_viewport:Nnnnn { c }
+\cs_new_protected:Npn \@@_set_viewport:NnnnnN #1#2#3#4#5#6
+ {
+ \hbox_set:Nn \l_@@_internal_box
+ {
+ \__kernel_kern:n { -#2 }
+ \box_use:N #1
+ \__kernel_kern:n { #4 - \box_wd:N #1 }
+ }
+ \dim_compare:nNnTF {#3} < \c_zero_dim
+ {
+ \hbox_set:Nn \l_@@_internal_box
+ {
+ \box_move_down:nn \c_zero_dim
+ { \box_use_drop:N \l_@@_internal_box }
+ }
+ \box_set_dp:Nn \l_@@_internal_box { - \@@_dim_eval:n {#3} }
+ }
+ {
+ \hbox_set:Nn \l_@@_internal_box
+ { \box_move_down:nn {#3} { \box_use_drop:N \l_@@_internal_box } }
+ \box_set_dp:Nn \l_@@_internal_box \c_zero_dim
+ }
+ \dim_compare:nNnTF {#5} > \c_zero_dim
+ {
+ \hbox_set:Nn \l_@@_internal_box
+ {
+ \box_move_up:nn \c_zero_dim
+ { \box_use_drop:N \l_@@_internal_box }
+ }
+ \box_set_ht:Nn \l_@@_internal_box
+ {
+ (#5)
+ \dim_compare:nNnT {#3} > \c_zero_dim
+ { - (#3) }
+ }
+ }
+ {
+ \hbox_set:Nn \l_@@_internal_box
+ {
+ \box_move_up:nn { - \@@_dim_eval:n {#5} }
+ { \box_use_drop:N \l_@@_internal_box }
+ }
+ \box_set_ht:Nn \l_@@_internal_box \c_zero_dim
+ }
+ #6 #1 \l_@@_internal_box
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+
%
% \begin{macrocode}
%</package>
diff --git a/l3kernel/l3candidates.dtx b/l3kernel/l3candidates.dtx
index b8e6c94f9..09b7a6888 100644
--- a/l3kernel/l3candidates.dtx
+++ b/l3kernel/l3candidates.dtx
@@ -84,65 +84,6 @@
% into the kernel. However, real use sometimes leads to better ideas, so functions from this module are
% \textbf{not necessarily stable} and we may have to adjust them!
%
-% \section{Additions to \pkg{l3box}}
-%
-% \begin{function}[updated = 2023-04-14]
-% {\box_set_clipped:N, \box_set_clipped:c, \box_gset_clipped:N, \box_gset_clipped:c}
-% \begin{syntax}
-% \cs{box_set_clipped:N} \meta{box}
-% \end{syntax}
-% Clips the \meta{box} in the output so that only material inside the
-% bounding box is displayed in the output. The updated \meta{box} is an
-% hbox, irrespective of the nature of the \meta{box} before the clipping is
-% applied.
-%
-% \begin{texnote}
-% Clipping is implemented by the driver, and as such the full content of
-% the box is placed in the output file. Thus clipping does not remove
-% any information from the raw output, and hidden material can therefore
-% be viewed by direct examination of the file.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}[added = 2019-01-23]
-% {
-% \box_set_trim:Nnnnn, \box_set_trim:cnnnn,
-% \box_gset_trim:Nnnnn, \box_gset_trim:cnnnn
-% }
-% \begin{syntax}
-% \cs{box_set_trim:Nnnnn} \meta{box} \Arg{left} \Arg{bottom} \Arg{right} \Arg{top}
-% \end{syntax}
-% Adjusts the bounding box of the \meta{box} \meta{left} is removed from
-% the left-hand edge of the bounding box, \meta{right} from the right-hand
-% edge and so fourth. All adjustments are \meta{dim exprs}.
-% Material outside of the bounding box is still displayed in the output
-% unless \cs{box_clip:N} is subsequently applied.
-% The updated \meta{box} is an
-% hbox, irrespective of the nature of the \meta{box} before the trim
-% operation is applied.
-% The behavior of the operation where the trims requested is
-% greater than the size of the box is undefined.
-% \end{function}
-%
-% \begin{function}[added = 2019-01-23]
-% {
-% \box_set_viewport:Nnnnn, \box_set_viewport:cnnnn,
-% \box_gset_viewport:Nnnnn, \box_gset_viewport:cnnnn
-% }
-% \begin{syntax}
-% \cs{box_set_viewport:Nnnnn} \meta{box} \Arg{llx} \Arg{lly} \Arg{urx} \Arg{ury}
-% \end{syntax}
-% Adjusts the bounding box of the \meta{box} such that it has lower-left
-% co-ordinates (\meta{llx}, \meta{lly}) and upper-right co-ordinates
-% (\meta{urx}, \meta{ury}). All four co-ordinate positions are
-% \meta{dim exprs}. Material outside of the bounding box is
-% still displayed in the output unless \cs{box_clip:N} is
-% subsequently applied.
-% The updated \meta{box} is an
-% hbox, irrespective of the nature of the \meta{box} before the viewport
-% operation is applied.
-% \end{function}
-%
% \section{Additions to \pkg{l3expan}}
%
% \begin{function}[added = 2018-04-04, updated = 2019-02-08]
@@ -666,168 +607,6 @@
%<*package>
% \end{macrocode}
%
-% \subsection{Additions to \pkg{l3box}}
-%
-% \begin{macrocode}
-%<@@=box>
-% \end{macrocode}
-%
-% \subsubsection{Viewing part of a box}
-%
-% \begin{macro}{\box_set_clipped:N, \box_set_clipped:c, \box_gset_clipped:N, \box_gset_clipped:c}
-% A wrapper around the driver-dependent code.
-% \begin{macrocode}
-\cs_new_protected:Npn \box_set_clipped:N #1
- { \hbox_set:Nn #1 { \@@_backend_clip:N #1 } }
-\cs_generate_variant:Nn \box_set_clipped:N { c }
-\cs_new_protected:Npn \box_gset_clipped:N #1
- { \hbox_gset:Nn #1 { \@@_backend_clip:N #1 } }
-\cs_generate_variant:Nn \box_gset_clipped:N { c }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \box_set_trim:Nnnnn, \box_set_trim:cnnnn,
-% \box_gset_trim:Nnnnn, \box_gset_trim:cnnnn
-% }
-% \begin{macro}{\@@_set_trim:NnnnnN}
-% Trimming from the left- and right-hand edges of the box is easy: kern the
-% appropriate parts off each side.
-% \begin{macrocode}
-\cs_new_protected:Npn \box_set_trim:Nnnnn #1#2#3#4#5
- { \@@_set_trim:NnnnnN #1 {#2} {#3} {#4} {#5} \box_set_eq:NN }
-\cs_generate_variant:Nn \box_set_trim:Nnnnn { c }
-\cs_new_protected:Npn \box_gset_trim:Nnnnn #1#2#3#4#5
- { \@@_set_trim:NnnnnN #1 {#2} {#3} {#4} {#5} \box_gset_eq:NN }
-\cs_generate_variant:Nn \box_gset_trim:Nnnnn { c }
-\cs_new_protected:Npn \@@_set_trim:NnnnnN #1#2#3#4#5#6
- {
- \hbox_set:Nn \l_@@_internal_box
- {
- \__kernel_kern:n { -#2 }
- \box_use:N #1
- \__kernel_kern:n { -#4 }
- }
-% \end{macrocode}
-% For the height and depth, there is a need to watch the baseline is
-% respected. Material always has to stay on the correct side, so trimming
-% has to check that there is enough material to trim. First, the bottom
-% edge. If there is enough depth, simply set the depth, or if not move
-% down so the result is zero depth. \cs{box_move_down:nn} is used in both
-% cases so the resulting box always contains a \tn{lower} primitive.
-% The internal box is used here as it allows safe use of \cs{box_set_dp:Nn}.
-% \begin{macrocode}
- \dim_compare:nNnTF { \box_dp:N #1 } > {#3}
- {
- \hbox_set:Nn \l_@@_internal_box
- {
- \box_move_down:nn \c_zero_dim
- { \box_use_drop:N \l_@@_internal_box }
- }
- \box_set_dp:Nn \l_@@_internal_box { \box_dp:N #1 - (#3) }
- }
- {
- \hbox_set:Nn \l_@@_internal_box
- {
- \box_move_down:nn { (#3) - \box_dp:N #1 }
- { \box_use_drop:N \l_@@_internal_box }
- }
- \box_set_dp:Nn \l_@@_internal_box \c_zero_dim
- }
-% \end{macrocode}
-% Same thing, this time from the top of the box.
-% \begin{macrocode}
- \dim_compare:nNnTF { \box_ht:N \l_@@_internal_box } > {#5}
- {
- \hbox_set:Nn \l_@@_internal_box
- {
- \box_move_up:nn \c_zero_dim
- { \box_use_drop:N \l_@@_internal_box }
- }
- \box_set_ht:Nn \l_@@_internal_box
- { \box_ht:N \l_@@_internal_box - (#5) }
- }
- {
- \hbox_set:Nn \l_@@_internal_box
- {
- \box_move_up:nn { (#5) - \box_ht:N \l_@@_internal_box }
- { \box_use_drop:N \l_@@_internal_box }
- }
- \box_set_ht:Nn \l_@@_internal_box \c_zero_dim
- }
- #6 #1 \l_@@_internal_box
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \box_set_viewport:Nnnnn, \box_set_viewport:cnnnn,
-% \box_gset_viewport:Nnnnn, \box_gset_viewport:cnnnn
-% }
-% \begin{macro}{\@@_viewport:NnnnnN}
-% The same general logic as for the trim operation, but with absolute
-% dimensions. As a result, there are some things to watch out for in the
-% vertical direction.
-% \begin{macrocode}
-\cs_new_protected:Npn \box_set_viewport:Nnnnn #1#2#3#4#5
- { \@@_set_viewport:NnnnnN #1 {#2} {#3} {#4} {#5} \box_set_eq:NN }
-\cs_generate_variant:Nn \box_set_viewport:Nnnnn { c }
-\cs_new_protected:Npn \box_gset_viewport:Nnnnn #1#2#3#4#5
- { \@@_set_viewport:NnnnnN #1 {#2} {#3} {#4} {#5} \box_gset_eq:NN }
-\cs_generate_variant:Nn \box_gset_viewport:Nnnnn { c }
-\cs_new_protected:Npn \@@_set_viewport:NnnnnN #1#2#3#4#5#6
- {
- \hbox_set:Nn \l_@@_internal_box
- {
- \__kernel_kern:n { -#2 }
- \box_use:N #1
- \__kernel_kern:n { #4 - \box_wd:N #1 }
- }
- \dim_compare:nNnTF {#3} < \c_zero_dim
- {
- \hbox_set:Nn \l_@@_internal_box
- {
- \box_move_down:nn \c_zero_dim
- { \box_use_drop:N \l_@@_internal_box }
- }
- \box_set_dp:Nn \l_@@_internal_box { - \@@_dim_eval:n {#3} }
- }
- {
- \hbox_set:Nn \l_@@_internal_box
- { \box_move_down:nn {#3} { \box_use_drop:N \l_@@_internal_box } }
- \box_set_dp:Nn \l_@@_internal_box \c_zero_dim
- }
- \dim_compare:nNnTF {#5} > \c_zero_dim
- {
- \hbox_set:Nn \l_@@_internal_box
- {
- \box_move_up:nn \c_zero_dim
- { \box_use_drop:N \l_@@_internal_box }
- }
- \box_set_ht:Nn \l_@@_internal_box
- {
- (#5)
- \dim_compare:nNnT {#3} > \c_zero_dim
- { - (#3) }
- }
- }
- {
- \hbox_set:Nn \l_@@_internal_box
- {
- \box_move_up:nn { - \@@_dim_eval:n {#5} }
- { \box_use_drop:N \l_@@_internal_box }
- }
- \box_set_ht:Nn \l_@@_internal_box \c_zero_dim
- }
- #6 #1 \l_@@_internal_box
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
% \subsection{Additions to \pkg{l3flag}}
%
% \begin{macrocode}
More information about the latex3-commits
mailing list.