[latex3-commits] [git/LaTeX3-latex3-latex3] l3box-trim-clip: Move box clipping/viewport functions to stable (e7fad9382)

Joseph Wright joseph.wright at morningstar2.co.uk
Fri Apr 14 15:14:41 CEST 2023


Repository : https://github.com/latex3/latex3
On branch  : l3box-trim-clip
Link       : https://github.com/latex3/latex3/commit/e7fad9382fc7380128e634bcce0400da842b8b53

>---------------------------------------------------------------

commit e7fad9382fc7380128e634bcce0400da842b8b53
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


>---------------------------------------------------------------

e7fad9382fc7380128e634bcce0400da842b8b53
 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.