summaryrefslogtreecommitdiff
path: root/macros/latex/required/l3kernel/l3coffins.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/required/l3kernel/l3coffins.dtx')
-rw-r--r--macros/latex/required/l3kernel/l3coffins.dtx2590
1 files changed, 2590 insertions, 0 deletions
diff --git a/macros/latex/required/l3kernel/l3coffins.dtx b/macros/latex/required/l3kernel/l3coffins.dtx
new file mode 100644
index 0000000000..164d10019d
--- /dev/null
+++ b/macros/latex/required/l3kernel/l3coffins.dtx
@@ -0,0 +1,2590 @@
+% \iffalse meta-comment
+%
+%% File: l3coffins.dtx
+%
+% Copyright (C) 2010-2024 The LaTeX 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
+%
+% https://www.latex-project.org/lppl.txt
+%
+% This file is part of the "l3kernel bundle" (The Work in LPPL)
+% and all files in that bundle must be distributed together.
+%
+% -----------------------------------------------------------------------
+%
+% The development version of the bundle can be found at
+%
+% https://github.com/latex3/latex3
+%
+% for those people who are interested.
+%
+%<*driver>
+\documentclass[full,kernel]{l3doc}
+\begin{document}
+ \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \title{^^A
+% The \pkg{l3coffins} module\\ Coffin code layer^^A
+% }
+%
+% \author{^^A
+% The \LaTeX{} Project\thanks
+% {^^A
+% E-mail:
+% \href{mailto:latex-team@latex-project.org}
+% {latex-team@latex-project.org}^^A
+% }^^A
+% }
+%
+% \date{Released 2024-04-11}
+%
+% \maketitle
+%
+% \begin{documentation}
+%
+% The material in this module provides the low-level support system
+% for coffins. For details about the design concept of a coffin, see
+% the \pkg{xcoffins} module (in the \pkg{l3experimental} bundle).
+%
+% \section{Creating and initialising coffins}
+%
+% \begin{function}[added = 2011-08-17]{\coffin_new:N, \coffin_new:c}
+% \begin{syntax}
+% \cs{coffin_new:N} \meta{coffin}
+% \end{syntax}
+% Creates a new \meta{coffin} or raises an error if the name is
+% already taken. The declaration is global. The \meta{coffin} is
+% initially empty.
+% \end{function}
+%
+% \begin{function}[added = 2011-08-17, updated = 2019-01-21]
+% {
+% \coffin_clear:N, \coffin_clear:c,
+% \coffin_gclear:N, \coffin_gclear:c
+% }
+% \begin{syntax}
+% \cs{coffin_clear:N} \meta{coffin}
+% \end{syntax}
+% Clears the content of the \meta{coffin}.
+% \end{function}
+%
+% \begin{function}[added = 2011-08-17, updated = 2019-01-21]
+% {
+% \coffin_set_eq:NN, \coffin_set_eq:Nc,
+% \coffin_set_eq:cN, \coffin_set_eq:cc,
+% \coffin_gset_eq:NN, \coffin_gset_eq:Nc,
+% \coffin_gset_eq:cN, \coffin_gset_eq:cc
+% }
+% \begin{syntax}
+% \cs{coffin_set_eq:NN} \meta{coffin_1} \meta{coffin_2}
+% \end{syntax}
+% Sets both the content and poles of \meta{coffin_1} equal to those
+% of \meta{coffin_2}.
+% \end{function}
+%
+% \begin{function}[EXP, pTF, added = 2012-06-20]
+% {\coffin_if_exist:N, \coffin_if_exist:c}
+% \begin{syntax}
+% \cs{coffin_if_exist_p:N} \meta{coffin}
+% \cs{coffin_if_exist:NTF} \meta{coffin} \Arg{true code} \Arg{false code}
+% \end{syntax}
+% Tests whether the \meta{coffin} is currently defined.
+% \end{function}
+%
+% \section{Setting coffin content and poles}
+%
+% \begin{function}[added = 2011-08-17, updated = 2019-01-21]
+% {
+% \hcoffin_set:Nn, \hcoffin_set:cn,
+% \hcoffin_gset:Nn, \hcoffin_gset:cn
+% }
+% \begin{syntax}
+% \cs{hcoffin_set:Nn} \meta{coffin} \Arg{material}
+% \end{syntax}
+% Typesets the \meta{material} in horizontal mode, storing the result
+% in the \meta{coffin}. The standard poles for the \meta{coffin} are
+% then set up based on the size of the typeset material.
+% \end{function}
+%
+% \begin{function}[added = 2011-09-10, updated = 2019-01-21]
+% {
+% \hcoffin_set:Nw, \hcoffin_set:cw, \hcoffin_set_end:,
+% \hcoffin_gset:Nw, \hcoffin_gset:cw, \hcoffin_gset_end:
+% }
+% \begin{syntax}
+% \cs{hcoffin_set:Nw} \meta{coffin} \meta{material} \cs{hcoffin_set_end:}
+% \end{syntax}
+% Typesets the \meta{material} in horizontal mode, storing the result
+% in the \meta{coffin}. The standard poles for the \meta{coffin} are
+% then set up based on the size of the typeset material.
+% These functions are useful for setting the entire contents of an
+% environment in a coffin.
+% \end{function}
+%
+% \begin{function}[added = 2011-08-17, updated = 2023-02-03]
+% {
+% \vcoffin_set:Nnn, \vcoffin_set:cnn,
+% \vcoffin_gset:Nnn, \vcoffin_gset:cnn
+% }
+% \begin{syntax}
+% \cs{vcoffin_set:Nnn} \meta{coffin} \Arg{width} \Arg{material}
+% \end{syntax}
+% Typesets the \meta{material} in vertical mode constrained to the
+% given \meta{width} and stores the result in the \meta{coffin}. The
+% standard poles for the \meta{coffin} are then set up based on the
+% size of the typeset material.
+% \end{function}
+%
+% \begin{function}[added = 2011-09-10, updated = 2023-02-03]
+% {
+% \vcoffin_set:Nnw, \vcoffin_set:cnw, \vcoffin_set_end:,
+% \vcoffin_gset:Nnw, \vcoffin_gset:cnw, \vcoffin_gset_end:
+% }
+% \begin{syntax}
+% \cs{vcoffin_set:Nnw} \meta{coffin} \Arg{width} \meta{material} \cs{vcoffin_set_end:}
+% \end{syntax}
+% Typesets the \meta{material} in vertical mode constrained to the
+% given \meta{width} and stores the result in the \meta{coffin}. The
+% standard poles for the \meta{coffin} are then set up based on the
+% size of the typeset material.
+% These functions are useful for setting the entire contents of an
+% environment in a coffin.
+% \end{function}
+%
+% \begin{function}[added = 2012-07-20, updated = 2019-01-21]
+% {
+% \coffin_set_horizontal_pole:Nnn, \coffin_set_horizontal_pole:cnn,
+% \coffin_gset_horizontal_pole:Nnn, \coffin_gset_horizontal_pole:cnn
+% }
+% \begin{syntax}
+% \cs{coffin_set_horizontal_pole:Nnn} \meta{coffin}
+% ~~\Arg{pole} \Arg{offset}
+% \end{syntax}
+% Sets the \meta{pole} to run horizontally through the \meta{coffin}.
+% The \meta{pole} is placed at the \meta{offset} from the
+% baseline of the \meta{coffin}. The
+% \meta{offset} should be given as a dimension expression.
+% \end{function}
+%
+% \begin{function}[added = 2012-07-20, updated = 2019-01-21]
+% {
+% \coffin_set_vertical_pole:Nnn, \coffin_set_vertical_pole:cnn,
+% \coffin_gset_vertical_pole:Nnn, \coffin_gset_vertical_pole:cnn
+% }
+% \begin{syntax}
+% \cs{coffin_set_vertical_pole:Nnn} \meta{coffin} \Arg{pole} \Arg{offset}
+% \end{syntax}
+% Sets the \meta{pole} to run vertically through the \meta{coffin}.
+% The \meta{pole} is placed at the \meta{offset} from the
+% left-hand edge of the bounding box of the \meta{coffin}. The
+% \meta{offset} should be given as a dimension expression.
+% \end{function}
+%
+% \begin{function}[added = 2023-05-17]{\coffin_reset_poles:N, \coffin_greset_poles:N}
+% \begin{syntax}
+% \cs{coffin_reset_poles:N} \meta{coffin}
+% \end{syntax}
+% Resets the poles of the \meta{coffin} to the standard set, removing any
+% custom or inherited poles. The poles will therefore be equal to those that
+% would be obtained from \cs{hcoffin_set:Nn} or similar; the bounding box
+% of the coffin is not reset, so any material outside of the formal bounding box
+% will not influence the poles.
+% \end{function}
+%
+% \section{Coffin affine transformations}
+%
+% \begin{function}[updated = 2019-01-23]
+% {
+% \coffin_resize:Nnn, \coffin_resize:cnn,
+% \coffin_gresize:Nnn, \coffin_gresize:cnn
+% }
+% \begin{syntax}
+% \cs{coffin_resize:Nnn} \meta{coffin} \Arg{width} \Arg{total-height}
+% \end{syntax}
+% Resized the \meta{coffin} to \meta{width} and \meta{total-height},
+% both of which should be given as dimension expressions.
+% \end{function}
+%
+% \begin{function}
+% {
+% \coffin_rotate:Nn, \coffin_rotate:cn,
+% \coffin_grotate:Nn, \coffin_grotate:cn
+% }
+% \begin{syntax}
+% \cs{coffin_rotate:Nn} \meta{coffin} \Arg{angle}
+% \end{syntax}
+% Rotates the \meta{coffin} by the given \meta{angle} (given in
+% degrees counter-clockwise). This process rotates both the
+% coffin content and poles. Multiple rotations do not result in
+% the bounding box of the coffin growing unnecessarily.
+% \end{function}
+%
+% \begin{function}[updated = 2019-01-23]
+% {
+% \coffin_scale:Nnn, \coffin_scale:cnn,
+% \coffin_gscale:Nnn, \coffin_gscale:cnn
+% }
+% \begin{syntax}
+% \cs{coffin_scale:Nnn} \meta{coffin} \Arg{x-scale} \Arg{y-scale}
+% \end{syntax}
+% Scales the \meta{coffin} by a factors \meta{x-scale} and
+% \meta{y-scale} in the horizontal and vertical directions,
+% respectively. The two scale factors should be given as real numbers.
+% \end{function}
+%
+% \section{Joining and using coffins}
+%
+% \begin{function}[updated = 2019-01-22]
+% {
+% \coffin_attach:NnnNnnnn, \coffin_attach:cnnNnnnn,
+% \coffin_attach:Nnncnnnn, \coffin_attach:cnncnnnn,
+% \coffin_gattach:NnnNnnnn, \coffin_gattach:cnnNnnnn,
+% \coffin_gattach:Nnncnnnn, \coffin_gattach:cnncnnnn
+% }
+% \begin{syntax}
+% \cs{coffin_attach:NnnNnnnn}
+% ~~\meta{coffin_1} \Arg{coffin_1-pole_1} \Arg{coffin_1-pole_2}
+% ~~\meta{coffin_2} \Arg{coffin_2-pole_1} \Arg{coffin_2-pole_2}
+% ~~\Arg{x-offset} \Arg{y-offset}
+% \end{syntax}
+% This function attaches \meta{coffin_2} to \meta{coffin_1} such that the bounding box
+% of \meta{coffin_1} is not altered, \emph{i.e.}~\meta{coffin_2} can
+% protrude outside of the bounding box of the coffin. The alignment
+% is carried out by first calculating \meta{handle_1}, the
+% point of intersection of \meta{coffin_1-pole_1} and
+% \meta{coffin_1-pole_2}, and \meta{handle_2}, the point of intersection
+% of \meta{coffin_2-pole_1} and \meta{coffin_2-pole_2}. \meta{coffin_2} is
+% then attached to \meta{coffin_1} such that the relationship between
+% \meta{handle_1} and \meta{handle_2} is described by the \meta{x-offset}
+% and \meta{y-offset}. The two offsets should be given as dimension
+% expressions.
+% \end{function}
+%
+% \begin{function}[updated = 2019-01-22]
+% {
+% \coffin_join:NnnNnnnn, \coffin_join:cnnNnnnn,
+% \coffin_join:Nnncnnnn, \coffin_join:cnncnnnn,
+% \coffin_gjoin:NnnNnnnn, \coffin_gjoin:cnnNnnnn,
+% \coffin_gjoin:Nnncnnnn, \coffin_gjoin:cnncnnnn
+% }
+% \begin{syntax}
+% \cs{coffin_join:NnnNnnnn}
+% ~~\meta{coffin_1} \Arg{coffin_1-pole_1} \Arg{coffin_1-pole_2}
+% ~~\meta{coffin_2} \Arg{coffin_2-pole_1} \Arg{coffin_2-pole_2}
+% ~~\Arg{x-offset} \Arg{y-offset}
+% \end{syntax}
+% This function joins \meta{coffin_2} to \meta{coffin_1} such that the bounding box
+% of \meta{coffin_1} may expand. The new bounding
+% box covers the area containing the bounding boxes of the two
+% original coffins. The alignment is carried out by first calculating
+% \meta{handle_1}, the point of intersection of \meta{coffin_1-pole_1} and
+% \meta{coffin_1-pole_2}, and \meta{handle_2}, the point of intersection
+% of \meta{coffin_2-pole_1} and \meta{coffin_2-pole_2}. \meta{coffin_2} is
+% then attached to \meta{coffin_1} such that the relationship between
+% \meta{handle_1} and \meta{handle_2} is described by the \meta{x-offset}
+% and \meta{y-offset}. The two offsets should be given as dimension
+% expressions.
+% \end{function}
+%
+% \begin{function}[updated = 2012-07-20]
+% {\coffin_typeset:Nnnnn, \coffin_typeset:cnnnn}
+% \begin{syntax}
+% \cs{coffin_typeset:Nnnnn} \meta{coffin} \Arg{pole_1} \Arg{pole_2}
+% ~~\Arg{x-offset} \Arg{y-offset}
+% \end{syntax}
+% Typesetting is carried out by first calculating \meta{handle}, the
+% point of intersection of \meta{pole_1} and \meta{pole_2}. The coffin
+% is then typeset in horizontal mode such that the relationship between the
+% current reference point in the document and the \meta{handle} is described
+% by the \meta{x-offset} and \meta{y-offset}. The two offsets should
+% be given as dimension expressions. Typesetting a coffin is
+% therefore analogous to carrying out an alignment where the
+% \enquote{parent} coffin is the current insertion point.
+% \end{function}
+%
+% \section{Measuring coffins}
+%
+% \begin{function}{\coffin_dp:N, \coffin_dp:c}
+% \begin{syntax}
+% \cs{coffin_dp:N} \meta{coffin}
+% \end{syntax}
+% Calculates the depth (below the baseline) of the \meta{coffin}
+% in a form suitable for use in a \meta{dim expr}.
+% \end{function}
+%
+% \begin{function}{\coffin_ht:N, \coffin_ht:c}
+% \begin{syntax}
+% \cs{coffin_ht:N} \meta{coffin}
+% \end{syntax}
+% Calculates the height (above the baseline) of the \meta{coffin}
+% in a form suitable for use in a \meta{dim expr}.
+% \end{function}
+%
+% \begin{function}{\coffin_wd:N, \coffin_wd:c}
+% \begin{syntax}
+% \cs{coffin_wd:N} \meta{coffin}
+% \end{syntax}
+% Calculates the width of the \meta{coffin} in a form
+% suitable for use in a \meta{dim expr}.
+% \end{function}
+%
+% \section{Coffin diagnostics}
+%
+% \begin{function}[updated = 2011-09-02]
+% {\coffin_display_handles:Nn, \coffin_display_handles:cn}
+% \begin{syntax}
+% \cs{coffin_display_handles:Nn} \meta{coffin} \Arg{color}
+% \end{syntax}
+% This function first calculates the intersections between all of
+% the \meta{poles} of the \meta{coffin} to give a set of
+% \meta{handles}. It then prints the \meta{coffin} at the current
+% location in the source, with the position of the \meta{handles}
+% marked on the coffin. The \meta{handles} are labelled as part
+% of this process: the locations of the \meta{handles} and the labels
+% are both printed in the \meta{color} specified.
+% \end{function}
+%
+% \begin{function}[updated = 2011-09-02]
+% {\coffin_mark_handle:Nnnn, \coffin_mark_handle:cnnn}
+% \begin{syntax}
+% \cs{coffin_mark_handle:Nnnn} \meta{coffin} \Arg{pole_1} \Arg{pole_2} \Arg{color}
+% \end{syntax}
+% This function first calculates the \meta{handle} for the
+% \meta{coffin} as defined by the intersection of \meta{pole_1} and
+% \meta{pole_2}. It then marks the position of the \meta{handle}
+% on the \meta{coffin}. The \meta{handle} are labelled as part of
+% this process: the location of the \meta{handle} and the label are
+% both printed in the \meta{color} specified.
+% \end{function}
+%
+% \begin{function}[updated = 2015-08-01]
+% {\coffin_show_structure:N, \coffin_show_structure:c}
+% \begin{syntax}
+% \cs{coffin_show_structure:N} \meta{coffin}
+% \end{syntax}
+% This function shows the structural information about the
+% \meta{coffin} in the terminal. The width, height and depth of the
+% typeset material are given, along with the location of all of the
+% poles of the coffin.
+%
+% Notice that the poles of a coffin are defined by four values:
+% the $x$ and $y$ co-ordinates of a point that the pole
+% passes through and the $x$- and $y$-components of a
+% vector denoting the direction of the pole. It is the ratio between
+% the later, rather than the absolute values, which determines the
+% direction of the pole.
+% \end{function}
+%
+% \begin{function}[added = 2014-08-22, updated = 2015-08-01]
+% {\coffin_log_structure:N, \coffin_log_structure:c}
+% \begin{syntax}
+% \cs{coffin_log_structure:N} \meta{coffin}
+% \end{syntax}
+% This function writes the structural information about the
+% \meta{coffin} in the log file. See also \cs{coffin_show_structure:N}
+% which displays the result in the terminal.
+% \end{function}
+%
+% \begin{function}[added = 2021-05-11]
+% {\coffin_show:N, \coffin_show:c, \coffin_log:N, \coffin_log:c}
+% \begin{syntax}
+% \cs{coffin_show:N} \meta{coffin}
+% \cs{coffin_log:N} \meta{coffin}
+% \end{syntax}
+% Shows full details of poles and contents of the \meta{coffin} in the
+% terminal or log file. See \cs{coffin_show_structure:N} and
+% \cs{box_show:N} to show separately the pole structure and the
+% contents.
+% \end{function}
+%
+% \begin{function}[added = 2021-05-11]
+% {\coffin_show:Nnn, \coffin_show:cnn, \coffin_log:Nnn, \coffin_log:cnn}
+% \begin{syntax}
+% \cs{coffin_show:Nnn} \meta{coffin} \Arg{int expr_1} \Arg{int expr_2}
+% \cs{coffin_log:Nnn} \meta{coffin} \Arg{int expr_1} \Arg{int expr_2}
+% \end{syntax}
+% Shows poles and contents of the \meta{coffin} in the terminal or log
+% file, showing the first \meta{int expr_1} items in the coffin, and
+% descending into \meta{int expr_2} group levels. See
+% \cs{coffin_show_structure:N} and \cs{box_show:Nnn} to show
+% separately the pole structure and the contents.
+% \end{function}
+%
+% \section{Constants and variables}
+%
+% \begin{variable}{\c_empty_coffin}
+% A permanently empty coffin.
+% \end{variable}
+%
+% \begin{variable}[added = 2012-06-19]{\l_tmpa_coffin, \l_tmpb_coffin}
+% Scratch coffins 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}
+%
+% \begin{variable}[added = 2019-01-24]{\g_tmpa_coffin, \g_tmpb_coffin}
+% Scratch coffins for global 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}
+%
+% \end{documentation}
+%
+% \begin{implementation}
+%
+% \section{\pkg{l3coffins} implementation}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<@@=coffin>
+% \end{macrocode}
+%
+% \subsection{Coffins: data structures and general variables}
+%
+% \begin{variable}{\l_@@_internal_box}
+% \begin{variable}{\l_@@_internal_dim}
+% \begin{variable}{\l_@@_internal_tl}
+% Scratch variables.
+% \begin{macrocode}
+\box_new:N \l_@@_internal_box
+\dim_new:N \l_@@_internal_dim
+\tl_new:N \l_@@_internal_tl
+% \end{macrocode}
+% \end{variable}
+% \end{variable}
+% \end{variable}
+%
+% \begin{variable}{\c_@@_corners_prop}
+% The \enquote{corners}; of a coffin define the real content, as
+% opposed to the \TeX{} bounding box. They all start off in the same
+% place, of course.
+% \begin{macrocode}
+\prop_const_from_keyval:Nn \c_@@_corners_prop
+ {
+ tl = { 0pt } { 0pt } ,
+ tr = { 0pt } { 0pt } ,
+ bl = { 0pt } { 0pt } ,
+ br = { 0pt } { 0pt } ,
+ }
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{variable}{\c_@@_poles_prop}
+% Pole positions are given for horizontal, vertical and reference-point
+% based values.
+% \begin{macrocode}
+\prop_const_from_keyval:Nn \c_@@_poles_prop
+ {
+ l = { 0pt } { 0pt } { 0pt } { 1000pt } ,
+ hc = { 0pt } { 0pt } { 0pt } { 1000pt } ,
+ r = { 0pt } { 0pt } { 0pt } { 1000pt } ,
+ b = { 0pt } { 0pt } { 1000pt } { 0pt } ,
+ vc = { 0pt } { 0pt } { 1000pt } { 0pt } ,
+ t = { 0pt } { 0pt } { 1000pt } { 0pt } ,
+ B = { 0pt } { 0pt } { 1000pt } { 0pt } ,
+ H = { 0pt } { 0pt } { 1000pt } { 0pt } ,
+ T = { 0pt } { 0pt } { 1000pt } { 0pt } ,
+ }
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_slope_A_fp}
+% \begin{variable}{\l_@@_slope_B_fp}
+% Used for calculations of intersections.
+% \begin{macrocode}
+\fp_new:N \l_@@_slope_A_fp
+\fp_new:N \l_@@_slope_B_fp
+% \end{macrocode}
+% \end{variable}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_error_bool}
+% For propagating errors so that parts of the code can work around them.
+% \begin{macrocode}
+\bool_new:N \l_@@_error_bool
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_offset_x_dim}
+% \begin{variable}{\l_@@_offset_y_dim}
+% The offset between two sets of coffin handles when typesetting. These
+% values are corrected from those requested in an alignment for the
+% positions of the handles.
+% \begin{macrocode}
+\dim_new:N \l_@@_offset_x_dim
+\dim_new:N \l_@@_offset_y_dim
+% \end{macrocode}
+% \end{variable}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_pole_a_tl}
+% \begin{variable}{\l_@@_pole_b_tl}
+% Needed for finding the intersection of two poles.
+% \begin{macrocode}
+\tl_new:N \l_@@_pole_a_tl
+\tl_new:N \l_@@_pole_b_tl
+% \end{macrocode}
+% \end{variable}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_x_dim}
+% \begin{variable}{\l_@@_y_dim}
+% \begin{variable}{\l_@@_x_prime_dim}
+% \begin{variable}{\l_@@_y_prime_dim}
+% For calculating intersections and so forth.
+% \begin{macrocode}
+\dim_new:N \l_@@_x_dim
+\dim_new:N \l_@@_y_dim
+\dim_new:N \l_@@_x_prime_dim
+\dim_new:N \l_@@_y_prime_dim
+% \end{macrocode}
+% \end{variable}
+% \end{variable}
+% \end{variable}
+% \end{variable}
+%
+% \subsection{Basic coffin functions}
+%
+% There are a number of basic functions needed for creating coffins and
+% placing material in them. This all relies on the following data
+% structures.
+%
+% \begin{macro}[EXP]{\@@_to_value:N}
+% Coffins are a two-part structure and we rely on the internal nature of
+% box allocation to make everything work. As such, we need an interface
+% to turn coffin identifiers into numbers. For the purposes here, the
+% signature allowed is |N| despite the nature of the underlying primitive.
+% \begin{macrocode}
+\cs_new_eq:NN \@@_to_value:N \tex_number:D
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP, pTF]{\coffin_if_exist:N, \coffin_if_exist:c}
+% Several of the higher-level coffin functions would give multiple
+% errors if the coffin does not exist. A cleaner way to handle this
+% is provided here: both the box and the coffin structure are
+% checked.
+% \begin{macrocode}
+\prg_new_conditional:Npnn \coffin_if_exist:N #1 { p , T , F , TF }
+ {
+ \cs_if_exist:NTF #1
+ {
+ \cs_if_exist:cTF { coffin ~ \@@_to_value:N #1 ~ poles }
+ { \prg_return_true: }
+ { \prg_return_false: }
+ }
+ { \prg_return_false: }
+ }
+\prg_generate_conditional_variant:Nnn \coffin_if_exist:N
+ { c } { p , T , F , TF }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_if_exist:NT}
+% Several of the higher-level coffin functions would give multiple
+% errors if the coffin does not exist. So a wrapper is provided to deal
+% with this correctly, issuing an error on erroneous use.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_if_exist:NT #1#2
+ {
+ \coffin_if_exist:NTF #1
+ { #2 }
+ {
+ \msg_error:nne { coffin } { unknown }
+ { \token_to_str:N #1 }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}
+% {
+% \coffin_clear:N, \coffin_clear:c,
+% \coffin_gclear:N, \coffin_gclear:c
+% }
+% Clearing coffins means emptying the box and resetting all of the
+% structures.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_clear:N #1
+ {
+ \@@_if_exist:NT #1
+ {
+ \box_clear:N #1
+ \@@_reset_structure:N #1
+ }
+ }
+\cs_generate_variant:Nn \coffin_clear:N { c }
+\cs_new_protected:Npn \coffin_gclear:N #1
+ {
+ \@@_if_exist:NT #1
+ {
+ \box_gclear:N #1
+ \@@_greset_structure:N #1
+ }
+ }
+\cs_generate_variant:Nn \coffin_gclear:N { c }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\coffin_new:N, \coffin_new:c}
+% Creating a new coffin means making the underlying box and adding the
+% data structures. The \cs{debug_suspend:} and \cs{debug_resume:} functions
+% prevent \cs{prop_gclear_new:c} from writing useless information to
+% the log file.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_new:N #1
+ {
+ \box_new:N #1
+ \debug_suspend:
+ \prop_gclear_new:c { coffin ~ \@@_to_value:N #1 ~ corners }
+ \prop_gclear_new:c { coffin ~ \@@_to_value:N #1 ~ poles }
+ \prop_gset_eq:cN { coffin ~ \@@_to_value:N #1 ~ corners }
+ \c_@@_corners_prop
+ \prop_gset_eq:cN { coffin ~ \@@_to_value:N #1 ~ poles }
+ \c_@@_poles_prop
+ \debug_resume:
+ }
+\cs_generate_variant:Nn \coffin_new:N { c }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}
+% {
+% \hcoffin_set:Nn, \hcoffin_set:cn,
+% \hcoffin_gset:Nn, \hcoffin_gset:cn
+% }
+% Horizontal coffins are relatively easy: set the appropriate box,
+% reset the structures then update the handle positions.
+% \begin{macrocode}
+\cs_new_protected:Npn \hcoffin_set:Nn #1#2
+ {
+ \@@_if_exist:NT #1
+ {
+ \hbox_set:Nn #1
+ {
+ \color_ensure_current:
+ #2
+ }
+ \coffin_reset_poles:N #1
+ }
+ }
+\cs_generate_variant:Nn \hcoffin_set:Nn { c }
+\cs_new_protected:Npn \hcoffin_gset:Nn #1#2
+ {
+ \@@_if_exist:NT #1
+ {
+ \hbox_gset:Nn #1
+ {
+ \color_ensure_current:
+ #2
+ }
+ \coffin_greset_poles:N #1
+ }
+ }
+\cs_generate_variant:Nn \hcoffin_gset:Nn { c }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}
+% {
+% \vcoffin_set:Nnn, \vcoffin_set:cnn,
+% \vcoffin_gset:Nnn, \vcoffin_gset:cnn
+% }
+% \begin{macro}{\@@_set_vertical:NnnNNN}
+% \begin{macro}{\@@_set_vertical_aux:}
+% Setting vertical coffins is more complex. First, the material is
+% typeset with a given width. The default handles and poles are set as
+% for a horizontal coffin, before finding the top baseline using a
+% temporary box. No \cs{color_ensure_current:} here as that would add a
+% whatsit to the start of the vertical box and mess up the location of the
+% \texttt{T}~pole (see \emph{\TeX{} by Topic} for discussion of the
+% \tn{vtop} primitive, used to do the measuring).
+% \begin{macrocode}
+\cs_new_protected:Npn \vcoffin_set:Nnn #1#2#3
+ {
+ \@@_set_vertical:NnnNNN #1 {#2} {#3}
+ \vbox_set:Nn \coffin_reset_poles:N \@@_set_pole:Nnn
+ }
+\cs_generate_variant:Nn \vcoffin_set:Nnn { c }
+\cs_new_protected:Npn \vcoffin_gset:Nnn #1#2#3
+ {
+ \@@_set_vertical:NnnNNN #1 {#2} {#3}
+ \vbox_gset:Nn \coffin_greset_poles:N \@@_gset_pole:Nnn
+ }
+\cs_generate_variant:Nn \vcoffin_gset:Nnn { c }
+\cs_new_protected:Npn \@@_set_vertical:NnnNNN #1#2#3#4#5#6
+ {
+ \@@_if_exist:NT #1
+ {
+ #4 #1
+ {
+ \dim_set:Nn \tex_hsize:D {#2}
+ \@@_set_vertical_aux:
+ #3
+ }
+ #5 #1
+ \vbox_set_top:Nn \l_@@_internal_box { \vbox_unpack:N #1 }
+ #6 #1 { T }
+ {
+ { 0pt }
+ {
+ \dim_eval:n
+ { \box_ht:N #1 - \box_ht:N \l_@@_internal_box }
+ }
+ { 1000pt }
+ { 0pt }
+ }
+ \box_clear:N \l_@@_internal_box
+ }
+ }
+\cs_new_protected:Npe \@@_set_vertical_aux:
+ {
+ \bool_lazy_and:nnT
+ { \cs_if_exist_p:N \fmtname }
+ { \str_if_eq_p:Vn \fmtname { LaTeX2e } }
+ {
+ \dim_set_eq:NN \exp_not:N \linewidth \tex_hsize:D
+ \dim_set_eq:NN \exp_not:N \columnwidth \tex_hsize:D
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}
+% {\hcoffin_set:Nw, \hcoffin_set:cw, \hcoffin_gset:Nw, \hcoffin_gset:cw}
+% \begin{macro}{\hcoffin_set_end:, \hcoffin_gset_end:}
+% These are the \enquote{begin}/\enquote{end} versions of the above:
+% watch the grouping!
+% \begin{macrocode}
+\cs_new_protected:Npn \hcoffin_set:Nw #1
+ {
+ \@@_if_exist:NT #1
+ {
+ \hbox_set:Nw #1 \color_ensure_current:
+ \cs_set_protected:Npn \hcoffin_set_end:
+ {
+ \hbox_set_end:
+ \coffin_reset_poles:N #1
+ }
+ }
+ }
+\cs_generate_variant:Nn \hcoffin_set:Nw { c }
+\cs_new_protected:Npn \hcoffin_gset:Nw #1
+ {
+ \@@_if_exist:NT #1
+ {
+ \hbox_gset:Nw #1 \color_ensure_current:
+ \cs_set_protected:Npn \hcoffin_gset_end:
+ {
+ \hbox_gset_end:
+ \coffin_greset_poles:N #1
+ }
+ }
+ }
+\cs_generate_variant:Nn \hcoffin_gset:Nw { c }
+\cs_new_protected:Npn \hcoffin_set_end: { }
+\cs_new_protected:Npn \hcoffin_gset_end: { }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}
+% {\vcoffin_set:Nnw, \vcoffin_set:cnw, \vcoffin_gset:Nnw, \vcoffin_gset:cnw}
+% \begin{macro}{\@@_set_vertical:NnNNNNNw}
+% \begin{macro}{\vcoffin_set_end:, \vcoffin_gset_end:}
+% The same for vertical coffins.
+% \begin{macrocode}
+\cs_new_protected:Npn \vcoffin_set:Nnw #1#2
+ {
+ \@@_set_vertical:NnNNNNNw #1 {#2} \vbox_set:Nw
+ \vcoffin_set_end:
+ \vbox_set_end: \coffin_reset_poles:N \@@_set_pole:Nnn
+ }
+\cs_generate_variant:Nn \vcoffin_set:Nnw { c }
+\cs_new_protected:Npn \vcoffin_gset:Nnw #1#2
+ {
+ \@@_set_vertical:NnNNNNNw #1 {#2} \vbox_gset:Nw
+ \vcoffin_gset_end:
+ \vbox_gset_end: \coffin_greset_poles:N \@@_gset_pole:Nnn
+ }
+\cs_generate_variant:Nn \vcoffin_gset:Nnw { c }
+\cs_new_protected:Npn \@@_set_vertical:NnNNNNNw #1#2#3#4#5#6#7
+ {
+ \@@_if_exist:NT #1
+ {
+ #3 #1
+ \dim_set:Nn \tex_hsize:D {#2}
+ \@@_set_vertical_aux:
+ \cs_set_protected:Npn #4
+ {
+ #5
+ #6 #1
+ \vbox_set_top:Nn \l_@@_internal_box { \vbox_unpack:N #1 }
+ #7 #1 { T }
+ {
+ { 0pt }
+ {
+ \dim_eval:n
+ { \box_ht:N #1 - \box_ht:N \l_@@_internal_box }
+ }
+ { 1000pt }
+ { 0pt }
+ }
+ \box_clear:N \l_@@_internal_box
+ }
+ }
+ }
+\cs_new_protected:Npn \vcoffin_set_end: { }
+\cs_new_protected:Npn \vcoffin_gset_end: { }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}
+% {
+% \coffin_set_eq:NN, \coffin_set_eq:Nc,
+% \coffin_set_eq:cN, \coffin_set_eq:cc,
+% \coffin_gset_eq:NN, \coffin_gset_eq:Nc,
+% \coffin_gset_eq:cN, \coffin_gset_eq:cc
+% }
+% Setting two coffins equal is just a wrapper around other functions.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_set_eq:NN #1#2
+ {
+ \@@_if_exist:NT #1
+ {
+ \box_set_eq:NN #1 #2
+ \prop_set_eq:cc { coffin ~ \@@_to_value:N #1 ~ corners }
+ { coffin ~ \@@_to_value:N #2 ~ corners }
+ \prop_set_eq:cc { coffin ~ \@@_to_value:N #1 ~ poles }
+ { coffin ~ \@@_to_value:N #2 ~ poles }
+ }
+ }
+\cs_generate_variant:Nn \coffin_set_eq:NN { c , Nc , cc }
+\cs_new_protected:Npn \coffin_gset_eq:NN #1#2
+ {
+ \@@_if_exist:NT #1
+ {
+ \box_gset_eq:NN #1 #2
+ \prop_gset_eq:cc { coffin ~ \@@_to_value:N #1 ~ corners }
+ { coffin ~ \@@_to_value:N #2 ~ corners }
+ \prop_gset_eq:cc { coffin ~ \@@_to_value:N #1 ~ poles }
+ { coffin ~ \@@_to_value:N #2 ~ poles }
+ }
+ }
+\cs_generate_variant:Nn \coffin_gset_eq:NN { c , Nc , cc }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{variable}{\c_empty_coffin}
+% \begin{variable}{\l_@@_aligned_coffin}
+% \begin{variable}{\l_@@_aligned_internal_coffin}
+% Special coffins: these cannot be set up earlier as they need
+% \cs{coffin_new:N}. The empty coffin is set as a box as the full
+% coffin-setting system needs some material which is not yet available.
+% The empty coffin is creted entirely by hand: not everything is in place
+% yet.
+% \begin{macrocode}
+\coffin_new:N \c_empty_coffin
+\coffin_new:N \l_@@_aligned_coffin
+\coffin_new:N \l_@@_aligned_internal_coffin
+% \end{macrocode}
+% \end{variable}
+% \end{variable}
+% \end{variable}
+%
+% \begin{variable}
+% {\l_tmpa_coffin, \l_tmpb_coffin, \g_tmpa_coffin, \g_tmpb_coffin}
+% The usual scratch space.
+% \begin{macrocode}
+\coffin_new:N \l_tmpa_coffin
+\coffin_new:N \l_tmpb_coffin
+\coffin_new:N \g_tmpa_coffin
+\coffin_new:N \g_tmpb_coffin
+% \end{macrocode}
+% \end{variable}
+%
+% \subsection{Measuring coffins}
+%
+% \begin{macro}
+% {
+% \coffin_dp:N, \coffin_dp:c, \coffin_ht:N, \coffin_ht:c,
+% \coffin_wd:N, \coffin_wd:c
+% }
+% Coffins are just boxes when it comes to measurement. However, semantically
+% a separate set of functions are required.
+% \begin{macrocode}
+\cs_new_eq:NN \coffin_dp:N \box_dp:N
+\cs_new_eq:NN \coffin_dp:c \box_dp:c
+\cs_new_eq:NN \coffin_ht:N \box_ht:N
+\cs_new_eq:NN \coffin_ht:c \box_ht:c
+\cs_new_eq:NN \coffin_wd:N \box_wd:N
+\cs_new_eq:NN \coffin_wd:c \box_wd:c
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Coffins: handle and pole management}
+%
+% \begin{macro}{\@@_get_pole:NnN}
+% A simple wrapper around the recovery of a coffin pole, with some
+% error checking and recovery built-in.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_get_pole:NnN #1#2#3
+ {
+ \prop_get:cnNF
+ { coffin ~ \@@_to_value:N #1 ~ poles } {#2} #3
+ {
+ \msg_error:nnee { coffin } { unknown-pole }
+ { \exp_not:n {#2} } { \token_to_str:N #1 }
+ \tl_set:Nn #3 { { 0pt } { 0pt } { 0pt } { 0pt } }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_reset_structure:N, \@@_greset_structure:N}
+% Resetting the structure is a simple copy job.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_reset_structure:N #1
+ {
+ \prop_set_eq:cN { coffin ~ \@@_to_value:N #1 ~ corners }
+ \c_@@_corners_prop
+ \prop_set_eq:cN { coffin ~ \@@_to_value:N #1 ~ poles }
+ \c_@@_poles_prop
+ }
+\cs_new_protected:Npn \@@_greset_structure:N #1
+ {
+ \prop_gset_eq:cN { coffin ~ \@@_to_value:N #1 ~ corners }
+ \c_@@_corners_prop
+ \prop_gset_eq:cN { coffin ~ \@@_to_value:N #1 ~ poles }
+ \c_@@_poles_prop
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}
+% {
+% \coffin_set_horizontal_pole:Nnn, \coffin_set_horizontal_pole:cnn,
+% \coffin_gset_horizontal_pole:Nnn, \coffin_gset_horizontal_pole:cnn
+% }
+% \begin{macro}{\@@_set_horizontal_pole:NnnN}
+% \begin{macro}
+% {
+% \coffin_set_vertical_pole:Nnn, \coffin_set_vertical_pole:cnn,
+% \coffin_gset_vertical_pole:Nnn, \coffin_gset_vertical_pole:cnn
+% }
+% \begin{macro}{\@@_set_vertical_pole:NnnN}
+% \begin{macro}{\@@_set_pole:Nnn, \@@_gset_pole:Nnn}
+% Setting the pole of a coffin at the user/designer level requires a
+% bit more care. The idea here is to provide a reasonable interface to
+% the system, then to do the setting with full expansion. The
+% three-argument version is used internally to do a direct setting.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_set_horizontal_pole:Nnn #1#2#3
+ { \@@_set_horizontal_pole:NnnN #1 {#2} {#3} \prop_put:cne }
+\cs_generate_variant:Nn \coffin_set_horizontal_pole:Nnn { c }
+\cs_new_protected:Npn \coffin_gset_horizontal_pole:Nnn #1#2#3
+ { \@@_set_horizontal_pole:NnnN #1 {#2} {#3} \prop_gput:cne }
+\cs_generate_variant:Nn \coffin_gset_horizontal_pole:Nnn { c }
+\cs_new_protected:Npn \@@_set_horizontal_pole:NnnN #1#2#3#4
+ {
+ \@@_if_exist:NT #1
+ {
+ #4 { coffin ~ \@@_to_value:N #1 ~ poles }
+ {#2}
+ {
+ { 0pt } { \dim_eval:n {#3} }
+ { 1000pt } { 0pt }
+ }
+ }
+ }
+\cs_new_protected:Npn \coffin_set_vertical_pole:Nnn #1#2#3
+ { \@@_set_vertical_pole:NnnN #1 {#2} {#3} \prop_put:cne }
+\cs_generate_variant:Nn \coffin_set_vertical_pole:Nnn { c }
+\cs_new_protected:Npn \coffin_gset_vertical_pole:Nnn #1#2#3
+ { \@@_set_vertical_pole:NnnN #1 {#2} {#3} \prop_gput:cne }
+ \cs_generate_variant:Nn \coffin_gset_vertical_pole:Nnn { c }
+\cs_new_protected:Npn \@@_set_vertical_pole:NnnN #1#2#3#4
+ {
+ \@@_if_exist:NT #1
+ {
+ #4 { coffin ~ \@@_to_value:N #1 ~ poles }
+ {#2}
+ {
+ { \dim_eval:n {#3} } { 0pt }
+ { 0pt } { 1000pt }
+ }
+ }
+ }
+\cs_new_protected:Npn \@@_set_pole:Nnn #1#2#3
+ {
+ \prop_put:cne { coffin ~ \@@_to_value:N #1 ~ poles }
+ {#2} {#3}
+ }
+\cs_new_protected:Npn \@@_gset_pole:Nnn #1#2#3
+ {
+ \prop_gput:cne { coffin ~ \@@_to_value:N #1 ~ poles }
+ {#2} {#3}
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\coffin_reset_poles:N, \coffin_greset_poles:N}
+% Simple shortcuts.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_reset_poles:N #1
+ {
+ \@@_reset_structure:N #1
+ \@@_update_corners:N #1
+ \@@_update_poles:N #1
+ }
+\cs_new_protected:Npn \coffin_greset_poles:N #1
+ {
+ \@@_greset_structure:N #1
+ \@@_gupdate_corners:N #1
+ \@@_gupdate_poles:N #1
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_update_corners:N, \@@_gupdate_corners:N}
+% \begin{macro}{\@@_update_corners:NN}
+% \begin{macro}{\@@_update_corners:NNN}
+% Updating the corners of a coffin is straight-forward as at this stage
+% there can be no rotation. So the corners of the content are just those
+% of the underlying \TeX{} box.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_update_corners:N #1
+ { \@@_update_corners:NN #1 \prop_put:Nne }
+\cs_new_protected:Npn \@@_gupdate_corners:N #1
+ { \@@_update_corners:NN #1 \prop_gput:Nne }
+\cs_new_protected:Npn \@@_update_corners:NN #1#2
+ {
+ \exp_args:Nc \@@_update_corners:NNN
+ { coffin ~ \@@_to_value:N #1 ~ corners }
+ #1 #2
+ }
+\cs_new_protected:Npn \@@_update_corners:NNN #1#2#3
+ {
+ #3 #1
+ { tl }
+ { { 0pt } { \dim_eval:n { \box_ht:N #2 } } }
+ #3 #1
+ { tr }
+ {
+ { \dim_eval:n { \box_wd:N #2 } }
+ { \dim_eval:n { \box_ht:N #2 } }
+ }
+ #3 #1
+ { bl }
+ { { 0pt } { \dim_eval:n { -\box_dp:N #2 } } }
+ #3 #1
+ { br }
+ {
+ { \dim_eval:n { \box_wd:N #2 } }
+ { \dim_eval:n { -\box_dp:N #2 } }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_update_poles:N, \@@_gupdate_poles:N}
+% \begin{macro}{\@@_update_poles:NN}
+% \begin{macro}{\@@_update_poles:NNN}
+% This function is called when a coffin is set, and updates the poles to
+% reflect the nature of size of the box. Thus this function only alters
+% poles where the default position is dependent on the size of the box.
+% It also does not set poles which are relevant only to vertical
+% coffins.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_update_poles:N #1
+ { \@@_update_poles:NN #1 \prop_put:Nne }
+\cs_new_protected:Npn \@@_gupdate_poles:N #1
+ { \@@_update_poles:NN #1 \prop_gput:Nne }
+\cs_new_protected:Npn \@@_update_poles:NN #1#2
+ {
+ \exp_args:Nc \@@_update_poles:NNN
+ { coffin ~ \@@_to_value:N #1 ~ poles }
+ #1 #2
+ }
+\cs_new_protected:Npn \@@_update_poles:NNN #1#2#3
+ {
+ #3 #1 { hc }
+ {
+ { \dim_eval:n { 0.5 \box_wd:N #2 } }
+ { 0pt } { 0pt } { 1000pt }
+ }
+ #3 #1 { r }
+ {
+ { \dim_eval:n { \box_wd:N #2 } }
+ { 0pt } { 0pt } { 1000pt }
+ }
+ #3 #1 { vc }
+ {
+ { 0pt }
+ { \dim_eval:n { ( \box_ht:N #2 - \box_dp:N #2 ) / 2 } }
+ { 1000pt }
+ { 0pt }
+ }
+ #3 #1 { t }
+ {
+ { 0pt }
+ { \dim_eval:n { \box_ht:N #2 } }
+ { 1000pt }
+ { 0pt }
+ }
+ #3 #1 { b }
+ {
+ { 0pt }
+ { \dim_eval:n { -\box_dp:N #2 } }
+ { 1000pt }
+ { 0pt }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Coffins: calculation of pole intersections}
+%
+% \begin{macro}{\@@_calculate_intersection:Nnn}
+% \begin{macro}{\@@_calculate_intersection:nnnnnnnn}
+% \begin{macro}{\@@_calculate_intersection:nnnnnn}
+% The lead off in finding intersections is to recover the two poles
+% and then hand off to the auxiliary for the actual calculation. There
+% may of course not be an intersection, for which an error trap is
+% needed.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_calculate_intersection:Nnn #1#2#3
+ {
+ \@@_get_pole:NnN #1 {#2} \l_@@_pole_a_tl
+ \@@_get_pole:NnN #1 {#3} \l_@@_pole_b_tl
+ \bool_set_false:N \l_@@_error_bool
+ \exp_last_two_unbraced:Noo
+ \@@_calculate_intersection:nnnnnnnn
+ \l_@@_pole_a_tl \l_@@_pole_b_tl
+ \bool_if:NT \l_@@_error_bool
+ {
+ \msg_error:nn { coffin } { no-pole-intersection }
+ \dim_zero:N \l_@@_x_dim
+ \dim_zero:N \l_@@_y_dim
+ }
+ }
+% \end{macrocode}
+% The two poles passed here each have four values (as dimensions),
+% ($a$, $b$, $c$, $d$) and
+% ($a'$, $b'$, $c'$, $d'$). These are arguments
+% $1$--$4$ and $5$--$8$, respectively. In both
+% cases $a$ and $b$ are the co-ordinates of a point on the
+% pole and $c$ and $d$ define the direction of the pole. Finding
+% the intersection depends on the directions of the poles, which are
+% given by $d / c$ and $d' / c'$. However, if one of the poles
+% is either horizontal or vertical then one or more of $c$, $d$,
+% $c'$ and $d'$ are zero and a special case is needed.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_calculate_intersection:nnnnnnnn
+ #1#2#3#4#5#6#7#8
+ {
+ \dim_compare:nNnTF {#3} = \c_zero_dim
+% \end{macrocode}
+% The case where the first pole is vertical. So the $x$-component
+% of the interaction is at $a$. There is then a test on the
+% second pole: if it is also vertical then there is an error.
+% \begin{macrocode}
+ {
+ \dim_set:Nn \l_@@_x_dim {#1}
+ \dim_compare:nNnTF {#7} = \c_zero_dim
+ { \bool_set_true:N \l_@@_error_bool }
+% \end{macrocode}
+% The second pole may still be horizontal, in which case the
+% $y$-component of the intersection is $b'$. If not,
+% \[
+% y = \frac{d'}{c'} \left ( a - a' \right ) + b'
+% \]
+% with the $x$-component already known to be |#1|.
+% \begin{macrocode}
+ {
+ \dim_set:Nn \l_@@_y_dim
+ {
+ \dim_compare:nNnTF {#8} = \c_zero_dim
+ {#6}
+ {
+ \fp_to_dim:n
+ {
+ ( \dim_to_fp:n {#8} / \dim_to_fp:n {#7} )
+ * ( \dim_to_fp:n {#1} - \dim_to_fp:n {#5} )
+ + \dim_to_fp:n {#6}
+ }
+ }
+ }
+ }
+ }
+% \end{macrocode}
+% If the first pole is not vertical then it may be horizontal. If so,
+% then the procedure is essentially the same as that already done but
+% with the $x$- and $y$-components interchanged.
+% \begin{macrocode}
+ {
+ \dim_compare:nNnTF {#4} = \c_zero_dim
+ {
+ \dim_set:Nn \l_@@_y_dim {#2}
+ \dim_compare:nNnTF {#8} = { \c_zero_dim }
+ { \bool_set_true:N \l_@@_error_bool }
+ {
+% \end{macrocode}
+% Now we deal with the case where the second pole may be vertical, or
+% if not we have
+% \[
+% x = \frac{c'}{d'} \left ( b - b' \right ) + a'
+% \]
+% which is again handled by the same auxiliary.
+% \begin{macrocode}
+ \dim_set:Nn \l_@@_x_dim
+ {
+ \dim_compare:nNnTF {#7} = \c_zero_dim
+ {#5}
+ {
+ \fp_to_dim:n
+ {
+ ( \dim_to_fp:n {#7} / \dim_to_fp:n {#8} )
+ * ( \dim_to_fp:n {#4} - \dim_to_fp:n {#6} )
+ + \dim_to_fp:n {#5}
+ }
+ }
+ }
+ }
+ }
+% \end{macrocode}
+% The first pole is neither horizontal nor vertical. To avoid even
+% more complexity, we now work out both slopes and pass to an auxiliary.
+% \begin{macrocode}
+ {
+ \use:e
+ {
+ \@@_calculate_intersection:nnnnnn
+ { \dim_to_fp:n {#4} / \dim_to_fp:n {#3} }
+ { \dim_to_fp:n {#8} / \dim_to_fp:n {#7} }
+ }
+ {#1} {#2} {#5} {#6}
+ }
+ }
+ }
+% \end{macrocode}
+% Assuming the two poles are not parallel, then the intersection point is
+% found in two steps. First we find the $x$-value with
+% \[
+% x = \frac { sa - s'a' - b + b' }{ s - s' }
+% \]
+% and then finding the $y$-value with
+% \[
+% y = s ( x - a ) + b
+% \]
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_calculate_intersection:nnnnnn #1#2#3#4#5#6
+ {
+ \fp_compare:nNnTF {#1} = {#2}
+ { \bool_set_true:N \l_@@_error_bool }
+ {
+ \dim_set:Nn \l_@@_x_dim
+ {
+ \fp_to_dim:n
+ {
+ (
+ #1 * \dim_to_fp:n {#3}
+ - #2 * \dim_to_fp:n {#5}
+ - \dim_to_fp:n {#4}
+ + \dim_to_fp:n {#6}
+ )
+ /
+ ( #1 - #2 )
+ }
+ }
+ \dim_set:Nn \l_@@_y_dim
+ {
+ \fp_to_dim:n
+ {
+ #1 * ( \l_@@_x_dim - \dim_to_fp:n {#3} )
+ + \dim_to_fp:n {#4}
+ }
+ }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Affine transformations}
+%
+% \begin{variable}{\l_@@_sin_fp}
+% \begin{variable}{\l_@@_cos_fp}
+% Used for rotations to get the sine and cosine values.
+% \begin{macrocode}
+\fp_new:N \l_@@_sin_fp
+\fp_new:N \l_@@_cos_fp
+% \end{macrocode}
+% \end{variable}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_bounding_prop}
+% A property list for the bounding box of a coffin. This is only needed
+% during the rotation, so there is just the one.
+% \begin{macrocode}
+\prop_new:N \l_@@_bounding_prop
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_corners_prop, \l_@@_poles_prop}
+% Used to avoid needing to track scope for intermediate steps.
+% \begin{macrocode}
+\prop_new:N \l_@@_corners_prop
+\prop_new:N \l_@@_poles_prop
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_bounding_shift_dim}
+% The shift of the bounding box of a coffin from the real content.
+% \begin{macrocode}
+\dim_new:N \l_@@_bounding_shift_dim
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_left_corner_dim}
+% \begin{variable}{\l_@@_right_corner_dim}
+% \begin{variable}{\l_@@_bottom_corner_dim}
+% \begin{variable}{\l_@@_top_corner_dim}
+% These are used to hold maxima for the various corner values: these
+% thus define the minimum size of the bounding box after rotation.
+% \begin{macrocode}
+\dim_new:N \l_@@_left_corner_dim
+\dim_new:N \l_@@_right_corner_dim
+\dim_new:N \l_@@_bottom_corner_dim
+\dim_new:N \l_@@_top_corner_dim
+% \end{macrocode}
+% \end{variable}
+% \end{variable}
+% \end{variable}
+% \end{variable}
+%
+% \begin{macro}
+% {
+% \coffin_rotate:Nn, \coffin_rotate:cn,
+% \coffin_grotate:Nn, \coffin_grotate:cn
+% }
+% \begin{macro}{\@@_rotate:NnNNN}
+% Rotating a coffin requires several steps which can be conveniently
+% run together. The sine and cosine of the angle in degrees are
+% computed. This is then used to set \cs{l_@@_sin_fp} and
+% \cs{l_@@_cos_fp}, which are carried through unchanged for the rest
+% of the procedure.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_rotate:Nn #1#2
+ { \@@_rotate:NnNNN #1 {#2} \box_rotate:Nn \prop_set_eq:cN \hbox_set:Nn }
+\cs_generate_variant:Nn \coffin_rotate:Nn { c }
+\cs_new_protected:Npn \coffin_grotate:Nn #1#2
+ { \@@_rotate:NnNNN #1 {#2} \box_grotate:Nn \prop_gset_eq:cN \hbox_gset:Nn }
+\cs_generate_variant:Nn \coffin_grotate:Nn { c }
+\cs_new_protected:Npn \@@_rotate:NnNNN #1#2#3#4#5
+ {
+ \fp_set:Nn \l_@@_sin_fp { sind ( #2 ) }
+ \fp_set:Nn \l_@@_cos_fp { cosd ( #2 ) }
+% \end{macrocode}
+% Use a local copy of the property lists to avoid needing to pass the
+% name and scope around.
+% \begin{macrocode}
+ \prop_set_eq:Nc \l_@@_corners_prop
+ { coffin ~ \@@_to_value:N #1 ~ corners }
+ \prop_set_eq:Nc \l_@@_poles_prop
+ { coffin ~ \@@_to_value:N #1 ~ poles }
+% \end{macrocode}
+% The corners and poles of the coffin can now be rotated around the
+% origin. This is best achieved using mapping functions.
+% \begin{macrocode}
+ \prop_map_inline:Nn \l_@@_corners_prop
+ { \@@_rotate_corner:Nnnn #1 {##1} ##2 }
+ \prop_map_inline:Nn \l_@@_poles_prop
+ { \@@_rotate_pole:Nnnnnn #1 {##1} ##2 }
+% \end{macrocode}
+% The bounding box of the coffin needs to be rotated, and to do this
+% the corners have to be found first. They are then rotated in the same
+% way as the corners of the coffin material itself.
+% \begin{macrocode}
+ \@@_set_bounding:N #1
+ \prop_map_inline:Nn \l_@@_bounding_prop
+ { \@@_rotate_bounding:nnn {##1} ##2 }
+% \end{macrocode}
+% At this stage, there needs to be a calculation to find where the
+% corners of the content and the box itself will end up.
+% \begin{macrocode}
+ \@@_find_corner_maxima:N #1
+ \@@_find_bounding_shift:
+ #3 #1 {#2}
+% \end{macrocode}
+% The correction of the box position itself takes place here. The idea
+% is that the bounding box for a coffin is tight up to the content, and
+% has the reference point at the bottom-left. The $x$-direction is
+% handled by moving the content by the difference in the positions of
+% the bounding box and the content left edge. The $y$-direction is
+% dealt with by moving the box down by any depth it has acquired. The
+% internal box is used here to allow for the next step.
+% \begin{macrocode}
+ \hbox_set:Nn \l_@@_internal_box
+ {
+ \__kernel_kern:n
+ { \l_@@_bounding_shift_dim - \l_@@_left_corner_dim }
+ \box_move_down:nn { \l_@@_bottom_corner_dim }
+ { \box_use:N #1 }
+ }
+% \end{macrocode}
+% If there have been any previous rotations then the size of the
+% bounding box will be bigger than the contents. This can be corrected
+% easily by setting the size of the box to the height and width of the
+% content. As this operation requires setting box dimensions and these
+% transcend grouping, the safe way to do this is to use the internal box
+% and to reset the result into the target box.
+% \begin{macrocode}
+ \box_set_ht:Nn \l_@@_internal_box
+ { \l_@@_top_corner_dim - \l_@@_bottom_corner_dim }
+ \box_set_dp:Nn \l_@@_internal_box { 0pt }
+ \box_set_wd:Nn \l_@@_internal_box
+ { \l_@@_right_corner_dim - \l_@@_left_corner_dim }
+ #5 #1 { \box_use_drop:N \l_@@_internal_box }
+% \end{macrocode}
+% The final task is to move the poles and corners such that they are
+% back in alignment with the box reference point.
+% \begin{macrocode}
+ \prop_map_inline:Nn \l_@@_corners_prop
+ { \@@_shift_corner:Nnnn #1 {##1} ##2 }
+ \prop_map_inline:Nn \l_@@_poles_prop
+ { \@@_shift_pole:Nnnnnn #1 {##1} ##2 }
+% \end{macrocode}
+% Update the coffin data.
+% \begin{macrocode}
+ #4 { coffin ~ \@@_to_value:N #1 ~ corners }
+ \l_@@_corners_prop
+ #4 { coffin ~ \@@_to_value:N #1 ~ poles }
+ \l_@@_poles_prop
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_set_bounding:N}
+% The bounding box corners for a coffin are easy enough to find: this
+% is the same code as for the corners of the material itself, but
+% using a dedicated property list.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_set_bounding:N #1
+ {
+ \prop_put:Nne \l_@@_bounding_prop { tl }
+ { { 0pt } { \dim_eval:n { \box_ht:N #1 } } }
+ \prop_put:Nne \l_@@_bounding_prop { tr }
+ {
+ { \dim_eval:n { \box_wd:N #1 } }
+ { \dim_eval:n { \box_ht:N #1 } }
+ }
+ \dim_set:Nn \l_@@_internal_dim { -\box_dp:N #1 }
+ \prop_put:Nne \l_@@_bounding_prop { bl }
+ { { 0pt } { \dim_use:N \l_@@_internal_dim } }
+ \prop_put:Nne \l_@@_bounding_prop { br }
+ {
+ { \dim_eval:n { \box_wd:N #1 } }
+ { \dim_use:N \l_@@_internal_dim }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_rotate_bounding:nnn}
+% \begin{macro}{\@@_rotate_corner:Nnnn}
+% Rotating the position of the corner of the coffin is just a case
+% of treating this as a vector from the reference point. The same
+% treatment is used for the corners of the material itself and the
+% bounding box.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_rotate_bounding:nnn #1#2#3
+ {
+ \@@_rotate_vector:nnNN {#2} {#3} \l_@@_x_dim \l_@@_y_dim
+ \prop_put:Nne \l_@@_bounding_prop {#1}
+ { { \dim_use:N \l_@@_x_dim } { \dim_use:N \l_@@_y_dim } }
+ }
+\cs_new_protected:Npn \@@_rotate_corner:Nnnn #1#2#3#4
+ {
+ \@@_rotate_vector:nnNN {#3} {#4} \l_@@_x_dim \l_@@_y_dim
+ \prop_put:Nne \l_@@_corners_prop {#2}
+ { { \dim_use:N \l_@@_x_dim } { \dim_use:N \l_@@_y_dim } }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_rotate_pole:Nnnnnn}
+% Rotating a single pole simply means shifting the co-ordinate of
+% the pole and its direction. The rotation here is about the bottom-left
+% corner of the coffin.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_rotate_pole:Nnnnnn #1#2#3#4#5#6
+ {
+ \@@_rotate_vector:nnNN {#3} {#4} \l_@@_x_dim \l_@@_y_dim
+ \@@_rotate_vector:nnNN {#5} {#6}
+ \l_@@_x_prime_dim \l_@@_y_prime_dim
+ \prop_put:Nne \l_@@_poles_prop {#2}
+ {
+ { \dim_use:N \l_@@_x_dim } { \dim_use:N \l_@@_y_dim }
+ { \dim_use:N \l_@@_x_prime_dim }
+ { \dim_use:N \l_@@_y_prime_dim }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_rotate_vector:nnNN}
+% A rotation function, which needs only an input vector (as dimensions)
+% and an output space. The values \cs{l_@@_cos_fp} and
+% \cs{l_@@_sin_fp} should previously have been set up correctly.
+% Working this way means that the floating point work is kept to a
+% minimum: for any given rotation the sin and cosine values do no
+% change, after all.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_rotate_vector:nnNN #1#2#3#4
+ {
+ \dim_set:Nn #3
+ {
+ \fp_to_dim:n
+ {
+ \dim_to_fp:n {#1} * \l_@@_cos_fp
+ - \dim_to_fp:n {#2} * \l_@@_sin_fp
+ }
+ }
+ \dim_set:Nn #4
+ {
+ \fp_to_dim:n
+ {
+ \dim_to_fp:n {#1} * \l_@@_sin_fp
+ + \dim_to_fp:n {#2} * \l_@@_cos_fp
+ }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_find_corner_maxima:N}
+% \begin{macro}{\@@_find_corner_maxima_aux:nn}
+% The idea here is to find the extremities of the content of the
+% coffin. This is done by looking for the smallest values for the bottom
+% and left corners, and the largest values for the top and right
+% corners. The values start at the maximum dimensions so that the
+% case where all are positive or all are negative works out correctly.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_find_corner_maxima:N #1
+ {
+ \dim_set:Nn \l_@@_top_corner_dim { -\c_max_dim }
+ \dim_set:Nn \l_@@_right_corner_dim { -\c_max_dim }
+ \dim_set:Nn \l_@@_bottom_corner_dim { \c_max_dim }
+ \dim_set:Nn \l_@@_left_corner_dim { \c_max_dim }
+ \prop_map_inline:Nn \l_@@_corners_prop
+ { \@@_find_corner_maxima_aux:nn ##2 }
+ }
+\cs_new_protected:Npn \@@_find_corner_maxima_aux:nn #1#2
+ {
+ \dim_set:Nn \l_@@_left_corner_dim
+ { \dim_min:nn { \l_@@_left_corner_dim } {#1} }
+ \dim_set:Nn \l_@@_right_corner_dim
+ { \dim_max:nn { \l_@@_right_corner_dim } {#1} }
+ \dim_set:Nn \l_@@_bottom_corner_dim
+ { \dim_min:nn { \l_@@_bottom_corner_dim } {#2} }
+ \dim_set:Nn \l_@@_top_corner_dim
+ { \dim_max:nn { \l_@@_top_corner_dim } {#2} }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_find_bounding_shift:}
+% \begin{macro}{\@@_find_bounding_shift_aux:nn}
+% The approach to finding the shift for the bounding box is similar to
+% that for the corners. However, there is only one value needed here and
+% a fixed input property list, so things are a bit clearer.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_find_bounding_shift:
+ {
+ \dim_set:Nn \l_@@_bounding_shift_dim { \c_max_dim }
+ \prop_map_inline:Nn \l_@@_bounding_prop
+ { \@@_find_bounding_shift_aux:nn ##2 }
+ }
+\cs_new_protected:Npn \@@_find_bounding_shift_aux:nn #1#2
+ {
+ \dim_set:Nn \l_@@_bounding_shift_dim
+ { \dim_min:nn { \l_@@_bounding_shift_dim } {#1} }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_shift_corner:Nnnn}
+% \begin{macro}{\@@_shift_pole:Nnnnnn}
+% Shifting the corners and poles of a coffin means subtracting the
+% appropriate values from the $x$- and $y$-components. For
+% the poles, this means that the direction vector is unchanged.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_shift_corner:Nnnn #1#2#3#4
+ {
+ \prop_put:Nne \l_@@_corners_prop {#2}
+ {
+ { \dim_eval:n { #3 - \l_@@_left_corner_dim } }
+ { \dim_eval:n { #4 - \l_@@_bottom_corner_dim } }
+ }
+ }
+\cs_new_protected:Npn \@@_shift_pole:Nnnnnn #1#2#3#4#5#6
+ {
+ \prop_put:Nne \l_@@_poles_prop {#2}
+ {
+ { \dim_eval:n { #3 - \l_@@_left_corner_dim } }
+ { \dim_eval:n { #4 - \l_@@_bottom_corner_dim } }
+ {#5} {#6}
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{variable}{\l_@@_scale_x_fp}
+% \begin{variable}{\l_@@_scale_y_fp}
+% Storage for the scaling factors in $x$ and $y$, respectively.
+% \begin{macrocode}
+\fp_new:N \l_@@_scale_x_fp
+\fp_new:N \l_@@_scale_y_fp
+% \end{macrocode}
+% \end{variable}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_scaled_total_height_dim}
+% \begin{variable}{\l_@@_scaled_width_dim}
+% When scaling, the values given have to be turned into absolute values.
+% \begin{macrocode}
+\dim_new:N \l_@@_scaled_total_height_dim
+\dim_new:N \l_@@_scaled_width_dim
+% \end{macrocode}
+% \end{variable}
+% \end{variable}
+%
+% \begin{macro}
+% {
+% \coffin_resize:Nnn, \coffin_resize:cnn,
+% \coffin_gresize:Nnn, \coffin_gresize:cnn
+% }
+% \begin{macro}{\@@_resize:NnnNN}
+% Resizing a coffin begins by setting up the user-friendly names for
+% the dimensions of the coffin box. The new sizes are then turned into
+% scale factor. This is the same operation as takes place for the
+% underlying box, but that operation is grouped and so the same
+% calculation is done here.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_resize:Nnn #1#2#3
+ {
+ \@@_resize:NnnNN #1 {#2} {#3}
+ \box_resize_to_wd_and_ht_plus_dp:Nnn
+ \prop_set_eq:cN
+ }
+\cs_generate_variant:Nn \coffin_resize:Nnn { c }
+\cs_new_protected:Npn \coffin_gresize:Nnn #1#2#3
+ {
+ \@@_resize:NnnNN #1 {#2} {#3}
+ \box_gresize_to_wd_and_ht_plus_dp:Nnn
+ \prop_gset_eq:cN
+ }
+\cs_generate_variant:Nn \coffin_gresize:Nnn { c }
+\cs_new_protected:Npn \@@_resize:NnnNN #1#2#3#4#5
+ {
+ \fp_set:Nn \l_@@_scale_x_fp
+ { \dim_to_fp:n {#2} / \dim_to_fp:n { \coffin_wd:N #1 } }
+ \fp_set:Nn \l_@@_scale_y_fp
+ {
+ \dim_to_fp:n {#3}
+ / \dim_to_fp:n { \coffin_ht:N #1 + \coffin_dp:N #1 }
+ }
+ #4 #1 {#2} {#3}
+ \@@_resize_common:NnnN #1 {#2} {#3} #5
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_resize_common:NnnN}
+% The poles and corners of the coffin are scaled to the appropriate
+% places before actually resizing the underlying box.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_resize_common:NnnN #1#2#3#4
+ {
+ \prop_set_eq:Nc \l_@@_corners_prop
+ { coffin ~ \@@_to_value:N #1 ~ corners }
+ \prop_set_eq:Nc \l_@@_poles_prop
+ { coffin ~ \@@_to_value:N #1 ~ poles }
+ \prop_map_inline:Nn \l_@@_corners_prop
+ { \@@_scale_corner:Nnnn #1 {##1} ##2 }
+ \prop_map_inline:Nn \l_@@_poles_prop
+ { \@@_scale_pole:Nnnnnn #1 {##1} ##2 }
+% \end{macrocode}
+% Negative $x$-scaling values place the poles in the wrong
+% location: this is corrected here.
+% \begin{macrocode}
+ \fp_compare:nNnT \l_@@_scale_x_fp < \c_zero_fp
+ {
+ \prop_map_inline:Nn \l_@@_corners_prop
+ { \@@_x_shift_corner:Nnnn #1 {##1} ##2 }
+ \prop_map_inline:Nn \l_@@_poles_prop
+ { \@@_x_shift_pole:Nnnnnn #1 {##1} ##2 }
+ }
+ #4 { coffin ~ \@@_to_value:N #1 ~ corners }
+ \l_@@_corners_prop
+ #4 { coffin ~ \@@_to_value:N #1 ~ poles }
+ \l_@@_poles_prop
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}
+% {
+% \coffin_scale:Nnn, \coffin_scale:cnn,
+% \coffin_gscale:Nnn, \coffin_gscale:cnn
+% }
+% \begin{macro}{\@@_scale:NnnNN}
+% For scaling, the opposite calculation is done to find the new
+% dimensions for the coffin. Only the total height is needed, as this
+% is the shift required for corners and poles. The scaling is done
+% the \TeX{} way as this works properly with floating point values
+% without needing to use the \texttt{fp} module.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_scale:Nnn #1#2#3
+ { \@@_scale:NnnNN #1 {#2} {#3} \box_scale:Nnn \prop_set_eq:cN }
+\cs_generate_variant:Nn \coffin_scale:Nnn { c }
+\cs_new_protected:Npn \coffin_gscale:Nnn #1#2#3
+ { \@@_scale:NnnNN #1 {#2} {#3} \box_gscale:Nnn \prop_gset_eq:cN }
+\cs_generate_variant:Nn \coffin_gscale:Nnn { c }
+\cs_new_protected:Npn \@@_scale:NnnNN #1#2#3#4#5
+ {
+ \fp_set:Nn \l_@@_scale_x_fp {#2}
+ \fp_set:Nn \l_@@_scale_y_fp {#3}
+ #4 #1 { \l_@@_scale_x_fp } { \l_@@_scale_y_fp }
+ \dim_set:Nn \l_@@_internal_dim
+ { \coffin_ht:N #1 + \coffin_dp:N #1 }
+ \dim_set:Nn \l_@@_scaled_total_height_dim
+ { \fp_abs:n { \l_@@_scale_y_fp } \l_@@_internal_dim }
+ \dim_set:Nn \l_@@_scaled_width_dim
+ { -\fp_abs:n { \l_@@_scale_x_fp } \coffin_wd:N #1 }
+ \@@_resize_common:NnnN #1
+ { \l_@@_scaled_width_dim } { \l_@@_scaled_total_height_dim }
+ #5
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_scale_vector:nnNN}
+% This functions scales a vector from the origin using the pre-set scale
+% factors in $x$ and $y$. This is a much less complex operation
+% than rotation, and as a result the code is a lot clearer.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_scale_vector:nnNN #1#2#3#4
+ {
+ \dim_set:Nn #3
+ { \fp_to_dim:n { \dim_to_fp:n {#1} * \l_@@_scale_x_fp } }
+ \dim_set:Nn #4
+ { \fp_to_dim:n { \dim_to_fp:n {#2} * \l_@@_scale_y_fp } }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_scale_corner:Nnnn}
+% \begin{macro}{\@@_scale_pole:Nnnnnn}
+% Scaling both corners and poles is a simple calculation using the
+% preceding vector scaling.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_scale_corner:Nnnn #1#2#3#4
+ {
+ \@@_scale_vector:nnNN {#3} {#4} \l_@@_x_dim \l_@@_y_dim
+ \prop_put:Nne \l_@@_corners_prop {#2}
+ { { \dim_use:N \l_@@_x_dim } { \dim_use:N \l_@@_y_dim } }
+ }
+\cs_new_protected:Npn \@@_scale_pole:Nnnnnn #1#2#3#4#5#6
+ {
+ \@@_scale_vector:nnNN {#3} {#4} \l_@@_x_dim \l_@@_y_dim
+ \prop_put:Nne \l_@@_poles_prop {#2}
+ {
+ { \dim_use:N \l_@@_x_dim } { \dim_use:N \l_@@_y_dim }
+ {#5} {#6}
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_x_shift_corner:Nnnn}
+% \begin{macro}{\@@_x_shift_pole:Nnnnnn}
+% These functions correct for the $x$ displacement that takes
+% place with a negative horizontal scaling.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_x_shift_corner:Nnnn #1#2#3#4
+ {
+ \prop_put:Nne \l_@@_corners_prop {#2}
+ {
+ { \dim_eval:n { #3 + \box_wd:N #1 } } {#4}
+ }
+ }
+\cs_new_protected:Npn \@@_x_shift_pole:Nnnnnn #1#2#3#4#5#6
+ {
+ \prop_put:Nne \l_@@_poles_prop {#2}
+ {
+ { \dim_eval:n { #3 + \box_wd:N #1 } } {#4}
+ {#5} {#6}
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Aligning and typesetting of coffins}
+%
+% \begin{macro}
+% {
+% \coffin_join:NnnNnnnn, \coffin_join:cnnNnnnn,
+% \coffin_join:Nnncnnnn, \coffin_join:cnncnnnn,
+% \coffin_gjoin:NnnNnnnn, \coffin_gjoin:cnnNnnnn,
+% \coffin_gjoin:Nnncnnnn, \coffin_gjoin:cnncnnnn
+% }
+% \begin{macro}{\@@_join:NnnNnnnnN}
+% This command joins two coffins, using a horizontal and vertical pole
+% from each coffin and making an offset between the two. The result
+% is stored as the as a third coffin, which has all of its handles
+% reset to standard values. First, the more basic alignment function is
+% used to get things started.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_join:NnnNnnnn #1#2#3#4#5#6#7#8
+ {
+ \@@_join:NnnNnnnnN #1 {#2} {#3} #4 {#5} {#6} {#7} {#8}
+ \coffin_set_eq:NN
+ }
+\cs_generate_variant:Nn \coffin_join:NnnNnnnn { c , Nnnc , cnnc }
+\cs_new_protected:Npn \coffin_gjoin:NnnNnnnn #1#2#3#4#5#6#7#8
+ {
+ \@@_join:NnnNnnnnN #1 {#2} {#3} #4 {#5} {#6} {#7} {#8}
+ \coffin_gset_eq:NN
+ }
+\cs_generate_variant:Nn \coffin_gjoin:NnnNnnnn { c , Nnnc , cnnc }
+\cs_new_protected:Npn \@@_join:NnnNnnnnN #1#2#3#4#5#6#7#8#9
+ {
+ \@@_align:NnnNnnnnN
+ #1 {#2} {#3} #4 {#5} {#6} {#7} {#8} \l_@@_aligned_coffin
+% \end{macrocode}
+% Correct the placement of the reference point. If the $x$-offset
+% is negative then the reference point of the second box is to the left
+% of that of the first, which is corrected using a kern. On the right
+% side the first box might stick out, which would show up if it is wider
+% than the sum of the $x$-offset and the width of the second box.
+% So a second kern may be needed.
+% \begin{macrocode}
+ \hbox_set:Nn \l_@@_aligned_coffin
+ {
+ \dim_compare:nNnT { \l_@@_offset_x_dim } < \c_zero_dim
+ { \__kernel_kern:n { -\l_@@_offset_x_dim } }
+ \hbox_unpack:N \l_@@_aligned_coffin
+ \dim_set:Nn \l_@@_internal_dim
+ { \l_@@_offset_x_dim - \box_wd:N #1 + \box_wd:N #4 }
+ \dim_compare:nNnT \l_@@_internal_dim < \c_zero_dim
+ { \__kernel_kern:n { -\l_@@_internal_dim } }
+ }
+% \end{macrocode}
+% The coffin structure is reset, and the corners are cleared: only
+% those from the two parent coffins are needed.
+% \begin{macrocode}
+ \@@_reset_structure:N \l_@@_aligned_coffin
+ \prop_clear:c
+ {
+ coffin ~ \@@_to_value:N \l_@@_aligned_coffin
+ \c_space_tl corners
+ }
+ \@@_update_poles:N \l_@@_aligned_coffin
+% \end{macrocode}
+% The structures of the parent coffins are now transferred to the new
+% coffin, which requires that the appropriate offsets are applied. That
+% then depends on whether any shift was needed.
+% \begin{macrocode}
+ \dim_compare:nNnTF \l_@@_offset_x_dim < \c_zero_dim
+ {
+ \@@_offset_poles:Nnn #1 { -\l_@@_offset_x_dim } { 0pt }
+ \@@_offset_poles:Nnn #4 { 0pt } { \l_@@_offset_y_dim }
+ \@@_offset_corners:Nnn #1 { -\l_@@_offset_x_dim } { 0pt }
+ \@@_offset_corners:Nnn #4 { 0pt } { \l_@@_offset_y_dim }
+ }
+ {
+ \@@_offset_poles:Nnn #1 { 0pt } { 0pt }
+ \@@_offset_poles:Nnn #4
+ { \l_@@_offset_x_dim } { \l_@@_offset_y_dim }
+ \@@_offset_corners:Nnn #1 { 0pt } { 0pt }
+ \@@_offset_corners:Nnn #4
+ { \l_@@_offset_x_dim } { \l_@@_offset_y_dim }
+ }
+ \@@_update_vertical_poles:NNN #1 #4 \l_@@_aligned_coffin
+ #9 #1 \l_@@_aligned_coffin
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}
+% {
+% \coffin_attach:NnnNnnnn, \coffin_attach:cnnNnnnn,
+% \coffin_attach:Nnncnnnn, \coffin_attach:cnncnnnn,
+% \coffin_gattach:NnnNnnnn, \coffin_gattach:cnnNnnnn,
+% \coffin_gattach:Nnncnnnn, \coffin_gattach:cnncnnnn
+% }
+% \begin{macro}{\@@_attach:NnnNnnnnN}
+% \begin{macro}{\@@_attach_mark:NnnNnnnn}
+% A more simple version of the above, as it simply uses the size of the
+% first coffin for the new one. This means that the work here is rather
+% simplified compared to the above code. The function used when marking
+% a position is hear also as it is similar but without the structure
+% updates.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_attach:NnnNnnnn #1#2#3#4#5#6#7#8
+ {
+ \@@_attach:NnnNnnnnN #1 {#2} {#3} #4 {#5} {#6} {#7} {#8}
+ \coffin_set_eq:NN
+ }
+\cs_generate_variant:Nn \coffin_attach:NnnNnnnn { c , Nnnc , cnnc }
+\cs_new_protected:Npn \coffin_gattach:NnnNnnnn #1#2#3#4#5#6#7#8
+ {
+ \@@_attach:NnnNnnnnN #1 {#2} {#3} #4 {#5} {#6} {#7} {#8}
+ \coffin_gset_eq:NN
+ }
+\cs_generate_variant:Nn \coffin_gattach:NnnNnnnn { c , Nnnc , cnnc }
+\cs_new_protected:Npn \@@_attach:NnnNnnnnN #1#2#3#4#5#6#7#8#9
+ {
+ \@@_align:NnnNnnnnN
+ #1 {#2} {#3} #4 {#5} {#6} {#7} {#8} \l_@@_aligned_coffin
+ \box_set_ht:Nn \l_@@_aligned_coffin { \box_ht:N #1 }
+ \box_set_dp:Nn \l_@@_aligned_coffin { \box_dp:N #1 }
+ \box_set_wd:Nn \l_@@_aligned_coffin { \box_wd:N #1 }
+ \@@_reset_structure:N \l_@@_aligned_coffin
+ \prop_set_eq:cc
+ {
+ coffin ~ \@@_to_value:N \l_@@_aligned_coffin
+ \c_space_tl corners
+ }
+ { coffin ~ \@@_to_value:N #1 ~ corners }
+ \@@_update_poles:N \l_@@_aligned_coffin
+ \@@_offset_poles:Nnn #1 { 0pt } { 0pt }
+ \@@_offset_poles:Nnn #4
+ { \l_@@_offset_x_dim } { \l_@@_offset_y_dim }
+ \@@_update_vertical_poles:NNN #1 #4 \l_@@_aligned_coffin
+ #9 #1 \l_@@_aligned_coffin
+ }
+\cs_new_protected:Npn \@@_attach_mark:NnnNnnnn #1#2#3#4#5#6#7#8
+ {
+ \@@_align:NnnNnnnnN
+ #1 {#2} {#3} #4 {#5} {#6} {#7} {#8} \l_@@_aligned_coffin
+ \box_set_ht:Nn \l_@@_aligned_coffin { \box_ht:N #1 }
+ \box_set_dp:Nn \l_@@_aligned_coffin { \box_dp:N #1 }
+ \box_set_wd:Nn \l_@@_aligned_coffin { \box_wd:N #1 }
+ \box_set_eq:NN #1 \l_@@_aligned_coffin
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_align:NnnNnnnnN}
+% The internal function aligns the two coffins into a third one, but
+% performs no corrections on the resulting coffin poles. The process
+% begins by finding the points of intersection for the poles for each
+% of the input coffins. Those for the first coffin are worked out after
+% those for the second coffin, as this allows the `primed'
+% storage area to be used for the second coffin. The `real' box
+% offsets are then calculated, before using these to re-box the
+% input coffins. The default poles are then set up, but the final result
+% depends on how the bounding box is being handled.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_align:NnnNnnnnN #1#2#3#4#5#6#7#8#9
+ {
+ \@@_calculate_intersection:Nnn #4 {#5} {#6}
+ \dim_set:Nn \l_@@_x_prime_dim { \l_@@_x_dim }
+ \dim_set:Nn \l_@@_y_prime_dim { \l_@@_y_dim }
+ \@@_calculate_intersection:Nnn #1 {#2} {#3}
+ \dim_set:Nn \l_@@_offset_x_dim
+ { \l_@@_x_dim - \l_@@_x_prime_dim + #7 }
+ \dim_set:Nn \l_@@_offset_y_dim
+ { \l_@@_y_dim - \l_@@_y_prime_dim + #8 }
+ \hbox_set:Nn \l_@@_aligned_internal_coffin
+ {
+ \box_use:N #1
+ \__kernel_kern:n { -\box_wd:N #1 }
+ \__kernel_kern:n { \l_@@_offset_x_dim }
+ \box_move_up:nn { \l_@@_offset_y_dim } { \box_use:N #4 }
+ }
+ \coffin_set_eq:NN #9 \l_@@_aligned_internal_coffin
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_offset_poles:Nnn}
+% \begin{macro}{\@@_offset_pole:Nnnnnnn}
+% Transferring structures from one coffin to another requires that the
+% positions are updated by the offset between the two coffins. This is
+% done by mapping over the property list of the source coffins, moving
+% as appropriate and saving to the new coffin data structures. The
+% test for a |-| means that the structures from the parent coffins
+% are uniquely labelled and do not depend on the order of alignment.
+% The pay off for this is that |-| should not be used in coffin pole
+% or handle names, and that multiple alignments do not result in a
+% whole set of values.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_offset_poles:Nnn #1#2#3
+ {
+ \prop_map_inline:cn { coffin ~ \@@_to_value:N #1 ~ poles }
+ { \@@_offset_pole:Nnnnnnn #1 {##1} ##2 {#2} {#3} }
+ }
+\cs_new_protected:Npn \@@_offset_pole:Nnnnnnn #1#2#3#4#5#6#7#8
+ {
+ \dim_set:Nn \l_@@_x_dim { #3 + #7 }
+ \dim_set:Nn \l_@@_y_dim { #4 + #8 }
+ \tl_if_in:nnTF {#2} { - }
+ { \tl_set:Nn \l_@@_internal_tl { {#2} } }
+ { \tl_set:Nn \l_@@_internal_tl { { #1 - #2 } } }
+ \exp_last_unbraced:NNo \@@_set_pole:Nnn \l_@@_aligned_coffin
+ { \l_@@_internal_tl }
+ {
+ { \dim_use:N \l_@@_x_dim } { \dim_use:N \l_@@_y_dim }
+ {#5} {#6}
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_offset_corners:Nnn}
+% \begin{macro}{\@@_offset_corner:Nnnnn}
+% Saving the offset corners of a coffin is very similar, except that
+% there is no need to worry about naming: every corner can be saved
+% here as order is unimportant.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_offset_corners:Nnn #1#2#3
+ {
+ \prop_map_inline:cn { coffin ~ \@@_to_value:N #1 ~ corners }
+ { \@@_offset_corner:Nnnnn #1 {##1} ##2 {#2} {#3} }
+ }
+\cs_new_protected:Npn \@@_offset_corner:Nnnnn #1#2#3#4#5#6
+ {
+ \prop_put:cne
+ {
+ coffin ~ \@@_to_value:N \l_@@_aligned_coffin
+ \c_space_tl corners
+ }
+ { #1 - #2 }
+ {
+ { \dim_eval:n { #3 + #5 } }
+ { \dim_eval:n { #4 + #6 } }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_update_vertical_poles:NNN}
+% \begin{macro}{\@@_update_T:nnnnnnnnN}
+% \begin{macro}{\@@_update_B:nnnnnnnnN}
+% The \texttt{T} and \texttt{B} poles need to be recalculated
+% after alignment. These functions find the larger absolute value for
+% the poles, but this is of course only logical when the poles are
+% horizontal.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_update_vertical_poles:NNN #1#2#3
+ {
+ \@@_get_pole:NnN #3 { #1 -T } \l_@@_pole_a_tl
+ \@@_get_pole:NnN #3 { #2 -T } \l_@@_pole_b_tl
+ \exp_last_two_unbraced:Noo \@@_update_T:nnnnnnnnN
+ \l_@@_pole_a_tl \l_@@_pole_b_tl #3
+ \@@_get_pole:NnN #3 { #1 -B } \l_@@_pole_a_tl
+ \@@_get_pole:NnN #3 { #2 -B } \l_@@_pole_b_tl
+ \exp_last_two_unbraced:Noo \@@_update_B:nnnnnnnnN
+ \l_@@_pole_a_tl \l_@@_pole_b_tl #3
+ }
+\cs_new_protected:Npn \@@_update_T:nnnnnnnnN #1#2#3#4#5#6#7#8#9
+ {
+ \dim_compare:nNnTF {#2} < {#6}
+ {
+ \@@_set_pole:Nnn #9 { T }
+ { { 0pt } {#6} { 1000pt } { 0pt } }
+ }
+ {
+ \@@_set_pole:Nnn #9 { T }
+ { { 0pt } {#2} { 1000pt } { 0pt } }
+ }
+ }
+\cs_new_protected:Npn \@@_update_B:nnnnnnnnN #1#2#3#4#5#6#7#8#9
+ {
+ \dim_compare:nNnTF {#2} < {#6}
+ {
+ \@@_set_pole:Nnn #9 { B }
+ { { 0pt } {#2} { 1000pt } { 0pt } }
+ }
+ {
+ \@@_set_pole:Nnn #9 { B }
+ { { 0pt } {#6} { 1000pt } { 0pt } }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{variable}{\c_@@_empty_coffin}
+% An empty-but-horizontal coffin.
+% \begin{macrocode}
+\coffin_new:N \c_@@_empty_coffin
+\tex_setbox:D \c_@@_empty_coffin = \tex_hbox:D { }
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{macro}{\coffin_typeset:Nnnnn, \coffin_typeset:cnnnn}
+% Typesetting a coffin means aligning it with the current position,
+% which is done using a coffin with no content at all. As well as aligning to
+% the empty coffin, there is also a need to leave vertical mode, if necessary.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_typeset:Nnnnn #1#2#3#4#5
+ {
+ \mode_leave_vertical:
+ \@@_align:NnnNnnnnN \c_@@_empty_coffin { H } { l }
+ #1 {#2} {#3} {#4} {#5} \l_@@_aligned_coffin
+ \box_use_drop:N \l_@@_aligned_coffin
+ }
+\cs_generate_variant:Nn \coffin_typeset:Nnnnn { c }
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Coffin diagnostics}
+%
+% \begin{variable}{\l_@@_display_coffin}
+% \begin{variable}{\l_@@_display_coord_coffin}
+% \begin{variable}{\l_@@_display_pole_coffin}
+% Used for printing coffins with data structures attached.
+% \begin{macrocode}
+\coffin_new:N \l_@@_display_coffin
+\coffin_new:N \l_@@_display_coord_coffin
+\coffin_new:N \l_@@_display_pole_coffin
+% \end{macrocode}
+% \end{variable}
+% \end{variable}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_display_handles_prop}
+% This property list is used to print coffin handles at suitable
+% positions. The offsets are expressed as multiples of the basic offset
+% value, which therefore acts as a scale-factor.
+% \begin{macrocode}
+\prop_new:N \l_@@_display_handles_prop
+\prop_put:Nnn \l_@@_display_handles_prop { tl }
+ { { b } { r } { -1 } { 1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { thc }
+ { { b } { hc } { 0 } { 1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { tr }
+ { { b } { l } { 1 } { 1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { vcl }
+ { { vc } { r } { -1 } { 0 } }
+\prop_put:Nnn \l_@@_display_handles_prop { vchc }
+ { { vc } { hc } { 0 } { 0 } }
+\prop_put:Nnn \l_@@_display_handles_prop { vcr }
+ { { vc } { l } { 1 } { 0 } }
+\prop_put:Nnn \l_@@_display_handles_prop { bl }
+ { { t } { r } { -1 } { -1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { bhc }
+ { { t } { hc } { 0 } { -1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { br }
+ { { t } { l } { 1 } { -1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { Tl }
+ { { t } { r } { -1 } { -1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { Thc }
+ { { t } { hc } { 0 } { -1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { Tr }
+ { { t } { l } { 1 } { -1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { Hl }
+ { { vc } { r } { -1 } { 1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { Hhc }
+ { { vc } { hc } { 0 } { 1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { Hr }
+ { { vc } { l } { 1 } { 1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { Bl }
+ { { b } { r } { -1 } { -1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { Bhc }
+ { { b } { hc } { 0 } { -1 } }
+\prop_put:Nnn \l_@@_display_handles_prop { Br }
+ { { b } { l } { 1 } { -1 } }
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_display_offset_dim}
+% The standard offset for the label from the handle position when
+% displaying handles.
+% \begin{macrocode}
+\dim_new:N \l_@@_display_offset_dim
+\dim_set:Nn \l_@@_display_offset_dim { 2pt }
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_display_x_dim}
+% \begin{variable}{\l_@@_display_y_dim}
+% As the intersections of poles have to be calculated to find which
+% ones to print, there is a need to avoid repetition. This is done
+% by saving the intersection into two dedicated values.
+% \begin{macrocode}
+\dim_new:N \l_@@_display_x_dim
+\dim_new:N \l_@@_display_y_dim
+% \end{macrocode}
+% \end{variable}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_display_poles_prop}
+% A property list for printing poles: various things need to be deleted
+% from this to get a \enquote{nice} output.
+% \begin{macrocode}
+\prop_new:N \l_@@_display_poles_prop
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{variable}{\l_@@_display_font_tl}
+% Stores the settings used to print coffin data: this keeps things
+% flexible.
+% \begin{macrocode}
+\tl_new:N \l_@@_display_font_tl
+\bool_lazy_and:nnT
+ { \cs_if_exist_p:N \fmtname }
+ { \str_if_eq_p:Vn \fmtname { LaTeX2e } }
+ {
+ \tl_set:Nn \l_@@_display_font_tl
+ { \sffamily \tiny }
+ }
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{macro}{\@@_rule:nn}
+% Abstract out creation of rules here until there is a higher-level interface.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_rule:nn #1#2
+ {
+ \mode_leave_vertical:
+ \hbox:n { \tex_vrule:D width #1 height #2 \scan_stop: }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\coffin_mark_handle:Nnnn, \coffin_mark_handle:cnnn}
+% \begin{macro}{\@@_mark_handle_aux:nnnnNnn}
+% Marking a single handle is relatively easy. The standard attachment
+% function is used, meaning that there are two calculations for the
+% location. However, this is likely to be okay given the load expected.
+% Contrast with the more optimised version for showing all handles which
+% comes next.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_mark_handle:Nnnn #1#2#3#4
+ {
+ \hcoffin_set:Nn \l_@@_display_pole_coffin
+ {
+ \color_select:n {#4}
+ \@@_rule:nn { 1pt } { 1pt }
+ }
+ \@@_attach_mark:NnnNnnnn #1 {#2} {#3}
+ \l_@@_display_pole_coffin { hc } { vc } { 0pt } { 0pt }
+ \hcoffin_set:Nn \l_@@_display_coord_coffin
+ {
+ \color_select:n {#4}
+ \l_@@_display_font_tl
+ ( \tl_to_str:n { #2 , #3 } )
+ }
+ \prop_get:NnN \l_@@_display_handles_prop
+ { #2 #3 } \l_@@_internal_tl
+ \quark_if_no_value:NTF \l_@@_internal_tl
+ {
+ \prop_get:NnN \l_@@_display_handles_prop
+ { #3 #2 } \l_@@_internal_tl
+ \quark_if_no_value:NTF \l_@@_internal_tl
+ {
+ \@@_attach_mark:NnnNnnnn #1 {#2} {#3}
+ \l_@@_display_coord_coffin { l } { vc }
+ { 1pt } { 0pt }
+ }
+ {
+ \exp_last_unbraced:No \@@_mark_handle_aux:nnnnNnn
+ \l_@@_internal_tl #1 {#2} {#3}
+ }
+ }
+ {
+ \exp_last_unbraced:No \@@_mark_handle_aux:nnnnNnn
+ \l_@@_internal_tl #1 {#2} {#3}
+ }
+ }
+\cs_new_protected:Npn \@@_mark_handle_aux:nnnnNnn #1#2#3#4#5#6#7
+ {
+ \@@_attach_mark:NnnNnnnn #5 {#6} {#7}
+ \l_@@_display_coord_coffin {#1} {#2}
+ { #3 \l_@@_display_offset_dim }
+ { #4 \l_@@_display_offset_dim }
+ }
+\cs_generate_variant:Nn \coffin_mark_handle:Nnnn { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\coffin_display_handles:Nn, \coffin_display_handles:cn}
+% \begin{macro}{\@@_display_handles_aux:nnnnnn}
+% \begin{macro}{\@@_display_handles_aux:nnnn}
+% \begin{macro}{\@@_display_attach:Nnnnn}
+% Printing the poles starts by removing any duplicates, for which the
+% \texttt{H} poles is used as the definitive version for the baseline
+% and bottom. Two loops are then used to find the combinations of
+% handles for all of these poles. This is done such that poles are
+% removed during the loops to avoid duplication.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_display_handles:Nn #1#2
+ {
+ \hcoffin_set:Nn \l_@@_display_pole_coffin
+ {
+ \color_select:n {#2}
+ \@@_rule:nn { 1pt } { 1pt }
+ }
+ \prop_set_eq:Nc \l_@@_display_poles_prop
+ { coffin ~ \@@_to_value:N #1 ~ poles }
+ \@@_get_pole:NnN #1 { H } \l_@@_pole_a_tl
+ \@@_get_pole:NnN #1 { T } \l_@@_pole_b_tl
+ \tl_if_eq:NNT \l_@@_pole_a_tl \l_@@_pole_b_tl
+ { \prop_remove:Nn \l_@@_display_poles_prop { T } }
+ \@@_get_pole:NnN #1 { B } \l_@@_pole_b_tl
+ \tl_if_eq:NNT \l_@@_pole_a_tl \l_@@_pole_b_tl
+ { \prop_remove:Nn \l_@@_display_poles_prop { B } }
+ \coffin_set_eq:NN \l_@@_display_coffin #1
+ \prop_map_inline:Nn \l_@@_display_poles_prop
+ {
+ \prop_remove:Nn \l_@@_display_poles_prop {##1}
+ \@@_display_handles_aux:nnnnnn {##1} ##2 {#2}
+ }
+ \box_use_drop:N \l_@@_display_coffin
+ }
+% \end{macrocode}
+% For each pole there is a check for an intersection, which here does
+% not give an error if none is found. The successful values are stored
+% and used to align the pole coffin with the main coffin for output.
+% The positions are recovered from the preset list if available.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_display_handles_aux:nnnnnn #1#2#3#4#5#6
+ {
+ \prop_map_inline:Nn \l_@@_display_poles_prop
+ {
+ \bool_set_false:N \l_@@_error_bool
+ \@@_calculate_intersection:nnnnnnnn {#2} {#3} {#4} {#5} ##2
+ \bool_if:NF \l_@@_error_bool
+ {
+ \dim_set:Nn \l_@@_display_x_dim { \l_@@_x_dim }
+ \dim_set:Nn \l_@@_display_y_dim { \l_@@_y_dim }
+ \@@_display_attach:Nnnnn
+ \l_@@_display_pole_coffin { hc } { vc }
+ { 0pt } { 0pt }
+ \hcoffin_set:Nn \l_@@_display_coord_coffin
+ {
+ \color_select:n {#6}
+ \l_@@_display_font_tl
+ ( \tl_to_str:n { #1 , ##1 } )
+ }
+ \prop_get:NnN \l_@@_display_handles_prop
+ { #1 ##1 } \l_@@_internal_tl
+ \quark_if_no_value:NTF \l_@@_internal_tl
+ {
+ \prop_get:NnN \l_@@_display_handles_prop
+ { ##1 #1 } \l_@@_internal_tl
+ \quark_if_no_value:NTF \l_@@_internal_tl
+ {
+ \@@_display_attach:Nnnnn
+ \l_@@_display_coord_coffin { l } { vc }
+ { 1pt } { 0pt }
+ }
+ {
+ \exp_last_unbraced:No
+ \@@_display_handles_aux:nnnn
+ \l_@@_internal_tl
+ }
+ }
+ {
+ \exp_last_unbraced:No \@@_display_handles_aux:nnnn
+ \l_@@_internal_tl
+ }
+ }
+ }
+ }
+\cs_new_protected:Npn \@@_display_handles_aux:nnnn #1#2#3#4
+ {
+ \@@_display_attach:Nnnnn
+ \l_@@_display_coord_coffin {#1} {#2}
+ { #3 \l_@@_display_offset_dim }
+ { #4 \l_@@_display_offset_dim }
+ }
+\cs_generate_variant:Nn \coffin_display_handles:Nn { c }
+% \end{macrocode}
+% This is a dedicated version of \cs{coffin_attach:NnnNnnnn} with
+% a hard-wired first coffin. As the intersection is already known
+% and stored for the display coffin the code simply uses it directly,
+% with no calculation.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_display_attach:Nnnnn #1#2#3#4#5
+ {
+ \@@_calculate_intersection:Nnn #1 {#2} {#3}
+ \dim_set:Nn \l_@@_x_prime_dim { \l_@@_x_dim }
+ \dim_set:Nn \l_@@_y_prime_dim { \l_@@_y_dim }
+ \dim_set:Nn \l_@@_offset_x_dim
+ { \l_@@_display_x_dim - \l_@@_x_prime_dim + #4 }
+ \dim_set:Nn \l_@@_offset_y_dim
+ { \l_@@_display_y_dim - \l_@@_y_prime_dim + #5 }
+ \hbox_set:Nn \l_@@_aligned_coffin
+ {
+ \box_use:N \l_@@_display_coffin
+ \__kernel_kern:n { -\box_wd:N \l_@@_display_coffin }
+ \__kernel_kern:n { \l_@@_offset_x_dim }
+ \box_move_up:nn { \l_@@_offset_y_dim } { \box_use:N #1 }
+ }
+ \box_set_ht:Nn \l_@@_aligned_coffin
+ { \box_ht:N \l_@@_display_coffin }
+ \box_set_dp:Nn \l_@@_aligned_coffin
+ { \box_dp:N \l_@@_display_coffin }
+ \box_set_wd:Nn \l_@@_aligned_coffin
+ { \box_wd:N \l_@@_display_coffin }
+ \box_set_eq:NN \l_@@_display_coffin \l_@@_aligned_coffin
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}
+% {
+% \coffin_show_structure:N, \coffin_show_structure:c,
+% \coffin_log_structure:N, \coffin_log_structure:c,
+% \@@_show_structure:NN
+% }
+% For showing the various internal structures attached to a coffin in
+% a way that keeps things relatively readable. If there is no apparent
+% structure then the code complains.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_show_structure:N
+ { \@@_show_structure:NN \msg_show:nneeee }
+\cs_generate_variant:Nn \coffin_show_structure:N { c }
+\cs_new_protected:Npn \coffin_log_structure:N
+ { \@@_show_structure:NN \msg_log:nneeee }
+\cs_generate_variant:Nn \coffin_log_structure:N { c }
+\cs_new_protected:Npn \@@_show_structure:NN #1#2
+ {
+ \@@_if_exist:NT #2
+ {
+ #1 { coffin } { show }
+ { \token_to_str:N #2 }
+ {
+ \iow_newline: >~ ht ~=~ \dim_eval:n { \coffin_ht:N #2 }
+ \iow_newline: >~ dp ~=~ \dim_eval:n { \coffin_dp:N #2 }
+ \iow_newline: >~ wd ~=~ \dim_eval:n { \coffin_wd:N #2 }
+ }
+ {
+ \prop_map_function:cN
+ { coffin ~ \@@_to_value:N #2 ~ poles }
+ \msg_show_item_unbraced:nn
+ }
+ { }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}
+% {
+% \coffin_show:N, \coffin_show:c, \coffin_log:N, \coffin_log:c,
+% \coffin_show:Nnn, \coffin_show:cnn, \coffin_log:Nnn, \coffin_log:cnn,
+% \@@_show:NNNnn
+% }
+% Essentially a combination of \cs{coffin_show_structure:N} and
+% \cs{box_show:Nnn}, but we need to avoid having two prompts, so we
+% use \cs{msg_term:nneeee} instead of
+% \cs{msg_show:nneeee} in the |show| case.
+% \begin{macrocode}
+\cs_new_protected:Npn \coffin_show:N #1
+ { \coffin_show:Nnn #1 \c_max_int \c_max_int }
+\cs_generate_variant:Nn \coffin_show:N { c }
+\cs_new_protected:Npn \coffin_log:N #1
+ { \coffin_log:Nnn #1 \c_max_int \c_max_int }
+\cs_generate_variant:Nn \coffin_log:N { c }
+\cs_new_protected:Npn \coffin_show:Nnn
+ { \@@_show:NNNnn \msg_term:nneeee \box_show:Nnn }
+\cs_generate_variant:Nn \coffin_show:Nnn { c }
+\cs_new_protected:Npn \coffin_log:Nnn
+ { \@@_show:NNNnn \msg_log:nneeee \box_show:Nnn }
+\cs_generate_variant:Nn \coffin_log:Nnn { c }
+\cs_new_protected:Npn \@@_show:NNNnn #1#2#3#4#5
+ {
+ \@@_if_exist:NT #3
+ {
+ \@@_show_structure:NN #1 #3
+ #2 #3 {#4} {#5}
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Messages}
+%
+% \begin{macrocode}
+\msg_new:nnnn { coffin } { no-pole-intersection }
+ { No~intersection~between~coffin~poles. }
+ {
+ LaTeX~was~asked~to~find~the~intersection~between~two~poles,~
+ but~they~do~not~have~a~unique~meeting~point:~
+ the~value~(0pt,~0pt)~will~be~used.
+ }
+\msg_new:nnnn { coffin } { unknown }
+ { Unknown~coffin~'#1'. }
+ { The~coffin~'#1'~was~never~defined. }
+\msg_new:nnnn { coffin } { unknown-pole }
+ { Pole~'#1'~unknown~for~coffin~'#2'. }
+ {
+ LaTeX~was~asked~to~find~a~typesetting~pole~for~a~coffin,~
+ but~either~the~coffin~does~not~exist~or~the~pole~name~is~wrong.
+ }
+\msg_new:nnn { coffin } { show }
+ {
+ Size~of~coffin~#1 : #2 \\
+ Poles~of~coffin~#1 : #3 .
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \end{implementation}
+%
+% \PrintIndex