% \iffalse
%% File l3coffins.dtx (C) Copyright 2010 LaTeX3 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
%%
%%    http://www.latex-project.org/lppl.txt
%%
%% This file is part of the ``xcoffins bundle'' (The Work in LPPL)
%% and all files in that bundle must be distributed together.
%%
%% The released version of this bundle is available from CTAN.
%%
%% -----------------------------------------------------------------------
%%
%% The development version of the bundle can be found at
%%
%%    http://www.latex-project.org/svnroot/experimental/trunk/
%%
%% for those people who are interested.
%%
%%%%%%%%%%%
%% NOTE: %% 
%%%%%%%%%%%
%%
%%   Snapshots taken from the repository represent work in progress and may
%%   not work or may contain conflicting material!  We therefore ask
%%   people _not_ to put them into distributions, archives, etc. without
%%   prior consultation with the LaTeX Project Team.
%%
%% -----------------------------------------------------------------------
%%
%<*driver|package>
\RequirePackage{expl3}
\RequirePackage{graphicx,xcolor,trace}
\GetIdInfo$Id: l3coffins.dtx 2109 2010-12-23 19:39:41Z joseph $
          {Coffins}
%</driver|package>
%<*driver>
%\fi
\ProvidesFile{\filename.\filenameext}
  [\filedate\space v\fileversion\space\filedescription]
%\iffalse
\documentclass{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
%\fi
%
%\title{^^A
%  The \LaTeX3 kernel: coffins\thanks{^^A
%    This file describes v\fileversion, last revised \filedate.^^A
%  }^^A
%}
%\author{\Team}^^A
%
%\date{Released \filedate}
%
%\maketitle
%
%\begin{abstract}
% A \LaTeX3 `coffin' is a design-level method for typesetting
% boxed material. The structure of coffins contains not only the 
% boxed material itself but also information about the size of the
% box and potential alignment positions. This structure makes it is 
% possible to build complex layouts rapidly by assembling coffins.
% The code here provides the low-level support system for coffins.
%\end{abstract}
%
%\tableofcontents
%
%\begin{documentation}
%
%\section{Introduction}
%
% 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.
%
%\section{Code-level functions}
% 
%\begin{function}{ 
%  \coffin_new:N |
%}
%  \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} will 
%  initially be empty.
%\end{function}
%
%\begin{function}{ 
%  \coffin_clear:N |
%}
%  \begin{syntax}
%    \cs{coffin_clear:N} \meta{coffin}
%  \end{syntax}
%  Clears the content of the \meta{coffin} within the current \TeX\
%  group level.
%\end{function}
%
%\begin{function}{ 
%  \coffin_set_eq:NN |
%}
%  \begin{syntax}
%    \cs{coffin_set_eq:NN} \meta{coffin1} \meta{coffin2}
%  \end{syntax}
%  Sets both the content and poles of \meta{coffin1} equal to those
%  of \meta{coffin2} within the current \TeX\ group level.
%\end{function}
%
%\begin{function}{ \hcoffin_set:Nn }
%  \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}{ \vcoffin_set:Nnn }
%  \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}{ 
%  \coffin_set_horizontal_pole:Nnn |
%}
%  \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} will be located at the \meta{offset} from the
%  bottom edge of the bounding box of the \meta{coffin}. The
%  \meta{offset} should be given as a dimension expression; this may
%  include the terms cs{TotalHeight}, \cs{Height}, \cs{Depth} and 
%  \cs{Width}, which will evaluate to the appropriate dimensions of 
%  the \meta{coffin}.
%\end{function}
%
%\begin{function}{ 
%  \coffin_set_vertical_pole:Nnn |
%}
%  \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} will be located 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; this may
%  include the terms \cs{TotalHeight}, \cs{Height}, \cs{Depth} and 
%  \cs{Width}, which will evaluate to the appropriate dimensions of 
%  the \meta{coffin}.
%\end{function}
%
%\begin{function}{ 
%  \coffin_rotate:Nn |
%}
%  \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 will rotate both the
%  coffin content and poles. Multiple rotations will not result in 
%  the bounding box of the coffin growing unnecessarily.
%\end{function}
%
%\begin{function}{ 
%  \coffin_attach:NnnNnnnn |
%}
%  \begin{syntax}
%    \cs{coffin_attach:NnnNnnnn} 
%    ~~\meta{coffin1} \Arg{coffin1-pole1} \Arg{coffin1-pole2}
%    ~~\meta{coffin2} \Arg{coffin2-pole1} \Arg{coffin2-pole2}
%    ~~\Arg{x-offset} \Arg{y-offset}
%  \end{syntax}
%  This function carries out alignment such that the bounding box
%  of \meta{coffin1} is not altered, \emph{i.e.}~\meta{coffin2} can
%  protrude outside of the bounding box of the coffin. The alignment 
%  is carried out by first calculating \meta{handle1}, the
%  point of intersection of \meta{coffin1-pole1} and 
%  \meta{coffin1-pole2}, and \meta{handle2}, the point of intersection
%  of \meta{coffin2-pole1} and \meta{coffin2-pole2}. \meta{coffin2} is
%  then attached to \meta{coffin1} such that the relationship between
%  \meta{handle1} and \meta{handle2} is described by the \meta{x-offset}
%  and \meta{y-offset}. The two offsets should be given as dimension
%  expressions.
%\end{function}
%
%\begin{function}{ 
%  \coffin_join:NnnNnnnn |
%}
%  \begin{syntax}
%    \cs{coffin_join:NnnNnnnn} 
%    ~~\meta{coffin1} \Arg{coffin1-pole1} \Arg{coffin1-pole2}
%    ~~\meta{coffin2} \Arg{coffin2-pole1} \Arg{coffin2-pole2}
%    ~~\Arg{x-offset} \Arg{y-offset}
%  \end{syntax}
%  This function carries out alignment such that the bounding box
%  of \meta{coffin1} after the process will expand. The new bounding
%  box will cover the area contain the bounding boxes of the two 
%  original coffins. The alignment is carried out by first calculating
%  \meta{handle1}, the point of intersection of \meta{coffin1-pole1} and
%  \meta{coffin1-pole2}, and \meta{handle2}, the point of intersection
%  of \meta{coffin2-pole1} and \meta{coffin2-pole2}. \meta{coffin2} is
%  then attached to \meta{coffin1} such that the relationship between
%  \meta{handle1} and \meta{handle2} is described by the \meta{x-offset}
%  and \meta{y-offset}. The two offsets should be given as dimension
%  expressions.
%\end{function}
%
%\begin{function}{ 
%  \coffin_typeset:Nnnnn |
%}
%  \begin{syntax}
%    \cs{coffin_typeset:Nnnnn} \meta{coffin} \Arg{pole1} \Arg{pole2}
%    ~~\Arg{x-offset} \Arg{y-offset}
%  \end{syntax}
%  Typesetting is carried out by first calculating \meta{handle}, the
%  point of intersection of \meta{pole1} and \meta{pole2}. The coffin
%  is then typeset 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 
%  `parent' coffin is the current insertion point.
%\end{function}
%
%\begin{function}{
%  \coffin_display_handles:Nn |
%}
%  \begin{syntax}
%    \cs{coffin_display_handles:Nn} \meta{coffin} \Arg{colour}
%  \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} will be labelled as part 
%  of this process: the locations of the \meta{handles} and the labels 
%  are both printed in the \meta{colour} specified.
%\end{function}
%
%\begin{function}{ 
%  \coffin_mark_handle:Nnnn |
%}
%  \begin{syntax}
%    \cs{coffin_mark_handle:Nnnn} \meta{coffin} \Arg{pole1} \Arg{pole2}
%    ~~\Arg{colour}
%  \end{syntax}
%  This function first calculates the \meta{handle} for the 
%  \meta{coffin} as defined by the intersection of \meta{pole1} and
%  \meta{pole2}. It then marks the position of the \meta{handle} 
%  on the \meta{coffin}. The \meta{handle} will be labelled as part of
%  this process: the location of the \meta{handle} and the label are
%  both printed in the \meta{colour} specified.
%\end{function}
%
%\begin{function}{
%  \coffin_show_structure:N |
%}
%  \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}
%
%\end{documentation}
%
%\begin{implementation}
%
%\section{Implementation}
% 
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%    
%    \begin{macrocode}
\ProvidesExplPackage
  {\filename}{\filedate}{\fileversion}{\filedescription} 
%    \end{macrocode}
%
%\subsection{Coffins: data structures and general variables}
%
%\begin{macro}{\l_coffin_tmp_box}
%\begin{macro}{\l_coffin_tmp_dim}
%\begin{macro}{\l_coffin_tmp_fp}
%\begin{macro}{\l_coffin_tmp_tl}
% Scratch variables.
%    \begin{macrocode}
\box_new:N \l_coffin_tmp_box
\dim_new:N \l_coffin_tmp_dim
\fp_new:N  \l_coffin_tmp_fp
\tl_new:N  \l_coffin_tmp_tl
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\c_coffin_corners_prop}
% The `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_new:N \c_coffin_corners_prop
\tl_set:Nn \l_coffin_tmp_tl { { 0 pt } { 0 pt } }
\prop_put:Nno \c_coffin_corners_prop { tl } { \l_coffin_tmp_tl }
\prop_put:Nno \c_coffin_corners_prop { tr } { \l_coffin_tmp_tl }
\prop_put:Nno \c_coffin_corners_prop { bl } { \l_coffin_tmp_tl }
\prop_put:Nno \c_coffin_corners_prop { br } { \l_coffin_tmp_tl }
%    \end{macrocode}
%\end{macro}
% 
%\begin{macro}{\c_coffin_poles_prop}
% Pole positions are given for horizontal, vertical and reference-point
% based values.
%    \begin{macrocode}
\prop_new:N \c_coffin_poles_prop
\tl_set:Nn \l_coffin_tmp_tl { { 0 pt } { 0 pt } { 0 pt } { 1000 pt } }
\prop_put:Nno \c_coffin_poles_prop { l }  { \l_coffin_tmp_tl }
\prop_put:Nno \c_coffin_poles_prop { hc } { \l_coffin_tmp_tl }
\prop_put:Nno \c_coffin_poles_prop { r }  { \l_coffin_tmp_tl }
\tl_set:Nn \l_coffin_tmp_tl { { 0 pt } { 0 pt } { 1000 pt } { 0 pt } }
\prop_put:Nno \c_coffin_poles_prop { b }  { \l_coffin_tmp_tl }
\prop_put:Nno \c_coffin_poles_prop { vc } { \l_coffin_tmp_tl }
\prop_put:Nno \c_coffin_poles_prop { t }  { \l_coffin_tmp_tl }
\prop_put:Nno \c_coffin_poles_prop { B }  { \l_coffin_tmp_tl }
\prop_put:Nno \c_coffin_poles_prop { H }  { \l_coffin_tmp_tl }
\prop_put:Nno \c_coffin_poles_prop { T }  { \l_coffin_tmp_tl }
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\l_coffin_calc_a_fp}
%\begin{macro}{\l_coffin_calc_b_fp}
%\begin{macro}{\l_coffin_calc_c_fp}
%\begin{macro}{\l_coffin_calc_d_fp}
%\begin{macro}{\l_coffin_calc_result_fp}
% Used for calculations of intersections and in other internal places.
%    \begin{macrocode}
\fp_new:N \l_coffin_calc_a_fp
\fp_new:N \l_coffin_calc_b_fp
\fp_new:N \l_coffin_calc_c_fp
\fp_new:N \l_coffin_calc_d_fp
\fp_new:N \l_coffin_calc_result_fp
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\l_coffin_error_bool}
% For propagating errors so that parts of the code can work around them.
%    \begin{macrocode}
\bool_new:N \l_coffin_error_bool
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\l_coffin_offset_x_dim}
%\begin{macro}{\l_coffin_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_coffin_offset_x_dim
\dim_new:N \l_coffin_offset_y_dim
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\l_coffin_pole_a_tl}
%\begin{macro}{\l_coffin_pole_b_tl}
% Needed for finding the intersection of two poles.
%    \begin{macrocode}
\tl_new:N \l_coffin_pole_a_tl
\tl_new:N \l_coffin_pole_b_tl
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\l_coffin_sin_fp}
%\begin{macro}{\l_coffin_cos_fp}
% Used for rotations to get the sine and cosine values.
%    \begin{macrocode}
\fp_new:N \l_coffin_sin_fp
\fp_new:N \l_coffin_cos_fp
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\l_coffin_x_dim}
%\begin{macro}{\l_coffin_y_dim}
%\begin{macro}{\l_coffin_x_prime_dim}
%\begin{macro}{\l_coffin_y_prime_dim}
% For calculating intersections and so forth.
%    \begin{macrocode}
\dim_new:N \l_coffin_x_dim
\dim_new:N \l_coffin_y_dim
\dim_new:N \l_coffin_x_prime_dim
\dim_new:N \l_coffin_y_prime_dim
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\l_coffin_x_fp}
%\begin{macro}{\l_coffin_y_fp}
%\begin{macro}{\l_coffin_x_prime_fp}
%\begin{macro}{\l_coffin_y_prime_fp}
% Used for calculations where there are clear \( x \)- and 
% \( y \)-components, for example during vector rotation.
%    \begin{macrocode}
\fp_new:N \l_coffin_x_fp
\fp_new:N \l_coffin_y_fp
\fp_new:N \l_coffin_x_prime_fp
\fp_new:N \l_coffin_y_prime_fp
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\l_coffin_Depth_dim}
%\begin{macro}{\l_coffin_Height_dim}
%\begin{macro}{\l_coffin_TotalHeight_dim}
%\begin{macro}{\l_coffin_Width_dim}
% Dimensions for the various parts of a coffin.
%    \begin{macrocode}
\dim_new:N \l_coffin_Depth_dim
\dim_new:N \l_coffin_Height_dim
\dim_new:N \l_coffin_TotalHeight_dim
\dim_new:N \l_coffin_Width_dim
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_saved_Depth:}
%\begin{macro}{\coffin_saved_Height:}
%\begin{macro}{\coffin_saved_TotalHeight:}
%\begin{macro}{\coffin_saved_Width:}
% Used to save the meaning of \cs{Depth}, \cs{Height}, \cs{TotalHeight}
% and \cs{Width}.
%    \begin{macrocode}
\cs_new_nopar:Npn \coffin_saved_Depth:       { }
\cs_new_nopar:Npn \coffin_saved_Height:      { }
\cs_new_nopar:Npn \coffin_saved_TotalHeight: { }
\cs_new_nopar:Npn \coffin_saved_Width:       { }
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\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}{\coffin_clear:N}
% Clearing coffins means emptying the box and resetting all of the
% structures.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \coffin_clear:N #1 {
  \box_clear:N #1
  \coffin_reset_structure:N #1
}
%    \end{macrocode}
%\end{macro}
% 
%\begin{macro}{\coffin_new:N}
% Creating a new coffin means making the underlying box and adding the
% data structures. These are created globally, as there is a need to
% avoid any strange effects if the coffin is created inside a group.
% This means that the usual rule about \cs{l_\ldots} variables has
% to be broken.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \coffin_new:N #1 {
  \cs_if_free:NTF #1
    {
      \box_new:N #1
      \prop_new:c { l_coffin_corners_ \tex_number:D #1 _prop }
      \prop_new:c { l_coffin_poles_ \tex_number:D #1 _prop }
      \prop_gset_eq:cN { l_coffin_corners_ \tex_number:D #1 _prop } 
        \c_coffin_corners_prop
      \prop_gset_eq:cN { l_coffin_poles_ \tex_number:D #1 _prop } 
        \c_coffin_poles_prop
    }
    { 
      \msg_kernel_error:nnx { coffin }{ variable-already-defined } 
        { \token_to_str:N #1 }
    }
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\hcoffin_set:Nn}
% 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 {
  \hbox_set:Nn #1 
    { 
      \group_begin:
        \set@color
        #2 
      \group_end: 
    }
  \coffin_reset_structure:N #1
  \coffin_update_poles:N #1
  \coffin_update_corners:N #1
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\vcoffin_set:Nnn}
% 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.
%    \begin{macrocode}
\cs_new_protected:Npn \vcoffin_set:Nnn #1#2#3 {
  \vbox_set:Nn #1 
    {
      \dim_set:Nn \tex_hsize:D {#2}
      \group_begin:
        \set@color
        #3 
      \group_end: 
    }
  \coffin_reset_structure:N #1
  \coffin_update_poles:N #1
  \coffin_update_corners:N #1
  \vbox_set_top:Nn \l_coffin_tmp_box { \vbox_unpack:N #1 }
  \dim_set:Nn \l_coffin_tmp_dim
    { \box_ht:N #1 - \box_ht:N \l_coffin_tmp_box }
  \coffin_set_pole:Nnx #1 { T }
    { { 0 pt } { \dim_use:N \l_coffin_tmp_dim } { 1000 pt } { 0 pt } }
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_set_eq:NN}
% Setting two coffins equal is just a wrapper around other functions.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \coffin_set_eq:NN #1#2 {
  \box_set_eq:NN #1 #2
  \coffin_set_eq_structure:NN #1 #2
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\c_empty_coffin}
%\begin{macro}{\l_coffin_aligned_coffin}
%\begin{macro}{\l_coffin_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.
%    \begin{macrocode}
\coffin_new:N \c_empty_coffin
\hbox_set:Nn  \c_empty_coffin { }
\coffin_new:N \l_coffin_aligned_coffin
\coffin_new:N \l_coffin_aligned_internal_coffin
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\subsection{Coffins: handle and pole management}
%
%\begin{macro}{\coffin_get_pole:NnN}
% A simple wrapper around the recovery of a coffin pole, with some 
% error checking and recovery built-in.
%    \begin{macrocode}
\cs_set_protected_nopar:Npn \coffin_get_pole:NnN #1#2#3 {
  \prop_get:cnN { l_coffin_poles_ \tex_number:D #1 _prop } {#2} #3
  \quark_if_no_value:NT #3
    { 
      \msg_kernel_error:nnxx { coffin } { unknown-coffin-pole }
        {#2} { \token_to_str:N #1 }
      \tl_set:Nn #3 { { 0 pt } { 0 pt } { 0 pt } { 0 pt } }
    }
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_reset_structure:N}
% Resetting the structure is a simple copy job.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \coffin_reset_structure:N #1 {
  \prop_set_eq:cN { l_coffin_corners_ \tex_number:D #1 _prop } 
    \c_coffin_corners_prop
  \prop_set_eq:cN { l_coffin_poles_ \tex_number:D #1 _prop } 
    \c_coffin_poles_prop
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_set_eq_structure:NN}
% Setting coffin structures equal simply means copying the property
% list.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \coffin_set_eq_structure:NN #1#2 {
  \prop_set_eq:cc { l_coffin_corners_ \tex_number:D #1 _prop }
    { l_coffin_corners_ \tex_number:D #2 _prop }
  \prop_set_eq:cc { l_coffin_poles_ \tex_number:D #1 _prop }
    { l_coffin_poles_ \tex_number:D #2 _prop }
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_set_user_dimensions:N}
%\begin{macro}{\coffin_end_user_dimensions:}
%\begin{macro}{\Depth}
%\begin{macro}{\Height}
%\begin{macro}{\TotalHeight}
%\begin{macro}{\Width}
% These make design-level names for the dimensions of a coffin easy to
% get at.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \coffin_set_user_dimensions:N #1 {
  \cs_set_eq:NN \coffin_saved_Height:      \Height
  \cs_set_eq:NN \coffin_saved_Depth:       \Depth
  \cs_set_eq:NN \coffin_saved_TotalHeight: \TotalHeight
  \cs_set_eq:NN \coffin_saved_Width:       \Width
  \cs_set_eq:NN \Height      \l_coffin_Height_dim
  \cs_set_eq:NN \Depth       \l_coffin_Depth_dim
  \cs_set_eq:NN \TotalHeight \l_coffin_TotalHeight_dim
  \cs_set_eq:NN \Width       \l_coffin_Width_dim
  \dim_set:Nn \Height      { \box_ht:N #1 }
  \dim_set:Nn \Depth       { \box_dp:N #1 }
  \dim_set:Nn \TotalHeight { \box_ht:N #1 - \box_dp:N #1 }
  \dim_set:Nn \Width       { \box_wd:N #1 }
}
\cs_new_protected_nopar:Npn \coffin_end_user_dimensions: {
  \cs_set_eq:NN \Height      \coffin_saved_Height:
  \cs_set_eq:NN \Depth       \coffin_saved_Depth:
  \cs_set_eq:NN \TotalHeight \coffin_saved_TotalHeight:
  \cs_set_eq:NN \Width       \coffin_saved_Width:
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_set_horizontal_pole:Nnn}
%\begin{macro}{\coffin_set_vertical_pole:Nnn}
%\begin{macro}{\coffin_set_pole:Nnn}
%\begin{macro}{\coffin_set_pole:Nnx}
% 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_nopar:Npn \coffin_set_horizontal_pole:Nnn #1#2#3 {
  \coffin_set_user_dimensions:N #1
  \coffin_set_pole:Nnx #1 {#2}
    {
      { 0 pt } { \tex_the:D \etex_dimexpr:D #3 \scan_stop: } 
      { 1000 pt } { 0 pt } 
    }
  \coffin_end_user_dimensions:
}
\cs_new_protected_nopar:Npn \coffin_set_vertical_pole:Nnn #1#2#3 {
  \coffin_set_user_dimensions:N #1
  \coffin_set_pole:Nnx #1 {#2} 
    { 
      { \tex_the:D \etex_dimexpr:D #3 \scan_stop: } { 0 pt } 
      { 0 pt } { 1000 pt }
    }
  \coffin_end_user_dimensions:
}
\cs_new_protected_nopar:Npn \coffin_set_pole:Nnn #1#2#3 {
  \prop_put:cnn { l_coffin_poles_ \tex_number:D #1 _prop } {#2} {#3}
}
\cs_generate_variant:Nn \coffin_set_pole:Nnn { Nnx }
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_update_corners:N}
% 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_nopar:Npn \coffin_update_corners:N #1 {
  \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } { tl } 
    { { 0 pt } { \dim_use:N \box_ht:N #1 } }
  \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } { tr } 
    { { \dim_use:N \box_wd:N #1 } { \dim_use:N \box_ht:N #1 } }
  \dim_set:Nn \l_coffin_tmp_dim { - \dim_use:N \box_dp:N #1 }  
  \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } { bl } 
    { { 0 pt } { \dim_use:N \l_coffin_tmp_dim } }
  \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } { br } 
    { { \dim_use:N \box_wd:N #1 } { \dim_use:N \l_coffin_tmp_dim } }
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_update_poles:N}
% 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_nopar:Npn \coffin_update_poles:N #1 {
  \dim_set:Nn \l_coffin_tmp_dim { 0.5 \box_wd:N #1 }
  \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _prop } { hc } 
    { { \dim_use:N \l_coffin_tmp_dim } { 0 pt } { 0 pt } { 1000 pt } }
  \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _prop } { r } 
    { { \dim_use:N \box_wd:N #1 } { 0 pt } { 0 pt } { 1000 pt } }
  \dim_set:Nn \l_coffin_tmp_dim { ( \box_ht:N #1 - \box_dp:N #1 ) / 2 }
  \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _prop } { vc } 
    { { 0 pt } { \dim_use:N \l_coffin_tmp_dim } { 1000 pt } { 0 pt } }
  \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _prop } { t }
    { { 0 pt } { \dim_use:N \box_ht:N #1 } { 1000 pt } { 0 pt } }
  \dim_set:Nn \l_coffin_tmp_dim { \box_dp:N #1 }
  \dim_compare:nNnF { \l_coffin_tmp_dim } = { \c_zero_dim }
    { \dim_set:Nn \l_coffin_tmp_dim { -\l_coffin_tmp_dim } }
  \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _prop } { b } 
    { { 0 pt } { \dim_use:N \l_coffin_tmp_dim } { 1000 pt } { 0 pt } }
}
%    \end{macrocode}
%\end{macro}
%
%\subsection{Coffins: calculation of pole intersections}
%
%\begin{macro}{\coffin_calculate_intersection:Nnn}
%\begin{macro}[aux]{\coffin_calculate_intersection:nnnnnnnn}
%\begin{macro}[aux]{\coffin_calculate_intersection_aux: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_nopar:Npn \coffin_calculate_intersection:Nnn #1#2#3 {
  \coffin_get_pole:NnN #1 {#2} \l_coffin_pole_a_tl
  \coffin_get_pole:NnN #1 {#3} \l_coffin_pole_b_tl
  \bool_set_false:N \l_coffin_error_bool
  \exp_last_two_unbraced:Noo
    \coffin_calculate_intersection:nnnnnnnn
      \l_coffin_pole_a_tl \l_coffin_pole_b_tl
  \bool_if:NT \l_coffin_error_bool
    {    
      \msg_kernel_error:nn { coffin } { no-pole-intersection }
      \dim_zero:N \l_coffin_x_dim
      \dim_zero:N \l_coffin_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' \) will be zero and a special case is needed.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn 
  \coffin_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 will be 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_coffin_x_dim {#1}
      \dim_compare:nNnTF {#7} = { \c_zero_dim }
        { \bool_set_true:N \l_coffin_error_bool }
%    \end{macrocode}
% The second pole may still be horizontal, in which case the 
% \( y \)-component of the intersection will be \( b' \). If not,
% \[
%   y = \frac{d'}{c'} \left ( x - a' \right ) + b'
% \]
% with the \( x \)-component already known to be "#1". This calculation
% is done as a generalised auxiliary.
%    \begin{macrocode}
        {
          \dim_compare:nNnTF {#8} = { \c_zero_dim }
            { \dim_set:Nn \l_coffin_y_dim {#6} }
            { 
              \coffin_calculate_intersection_aux:nnnnnN
                {#1} {#5} {#6} {#7} {#8} \l_coffin_y_dim
            }
        }
    }
%    \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_coffin_y_dim {#2}
          \dim_compare:nNnTF {#8} = { \c_zero_dim }
            { \bool_set_true:N \l_coffin_error_bool }
            {
              \dim_compare:nNnTF {#7} = { \c_zero_dim }
                { \dim_set:Nn \l_coffin_x_dim {#5} }
%    \end{macrocode}
% The formula for the case where the second pole is neither horizontal
% nor vertical is
% \[
%   x = \frac{c'}{d'} \left ( y - b' \right ) + a'
% \]
% which is again handled by the same auxiliary.
%    \begin{macrocode}
                { 
                  \coffin_calculate_intersection_aux:nnnnnN
                    {#2} {#6} {#5} {#8} {#7} \l_coffin_x_dim
                } 
            }
        }
%    \end{macrocode}
% The first pole is neither horizontal nor vertical. This still leaves
% the second pole, which may be a special case. For those possibilities,
% the calculations are the same as above with the first and second poles
% interchanged.
%    \begin{macrocode}
        {
          \dim_compare:nNnTF {#7} = { \c_zero_dim }
            {
              \dim_set:Nn \l_coffin_x_dim {#5} 
              \coffin_calculate_intersection_aux:nnnnnN
                {#5} {#1} {#2} {#3} {#4} \l_coffin_y_dim
            }
            {
              \dim_compare:nNnTF {#8} = { \c_zero_dim } 
                {
                  \dim_set:Nn \l_coffin_x_dim {#6}  
                  \coffin_calculate_intersection_aux:nnnnnN
                    {#6} {#2} {#1} {#4} {#3} \l_coffin_x_dim
                }
%    \end{macrocode}
% If none of the special cases apply then there is still a need to 
% check that there is a unique intersection between the two pole. This
% is the case if they have different slopes.
%    \begin{macrocode}
                { 
                  \fp_set_from_dim:Nn \l_coffin_calc_a_fp {#3}
                  \fp_set_from_dim:Nn \l_coffin_calc_b_fp {#4}
                  \fp_set_from_dim:Nn \l_coffin_calc_c_fp {#7}
                  \fp_set_from_dim:Nn \l_coffin_calc_d_fp {#8}
                  \fp_div:Nn \l_coffin_calc_b_fp \l_coffin_calc_a_fp
                  \fp_div:Nn \l_coffin_calc_d_fp \l_coffin_calc_c_fp
                  \fp_compare:nNnTF
                    { \l_coffin_calc_b_fp } = { \l_coffin_calc_d_fp }
                    { \bool_set_true:N \l_coffin_error_bool }
%    \end{macrocode}
% All of the tests pass, so there is the full complexity of the
% calculation:
% \[
%   x = \frac { a ( d / c ) - a' ( d' / c' ) - b + b' }
%            { ( d / c ) - ( d' / c' ) }
% \]
% and noting that the two ratios are already worked out from the test
% just performed. There is quite a bit of shuffling from dimensions to
% floating points in order to do the work. The \( y \)-values is then
% worked out using the standard auxiliary starting from the 
% \( x \)-position.
%    \begin{macrocode}
                    {
                      \fp_set_from_dim:Nn \l_coffin_calc_result_fp {#6}
                      \fp_set_from_dim:Nn \l_coffin_calc_a_fp {#2} 
                      \fp_sub:Nn \l_coffin_calc_result_fp
                        { \l_coffin_calc_a_fp }
                      \fp_set_from_dim:Nn \l_coffin_calc_a_fp {#1}
                      \fp_mul:Nn \l_coffin_calc_a_fp
                        { \l_coffin_calc_b_fp }
                      \fp_add:Nn \l_coffin_calc_result_fp
                        { \l_coffin_calc_a_fp }
                      \fp_set_from_dim:Nn \l_coffin_calc_a_fp {#5}
                      \fp_mul:Nn \l_coffin_calc_a_fp
                        { \l_coffin_calc_d_fp }
                      \fp_sub:Nn \l_coffin_calc_result_fp
                        { \l_coffin_calc_a_fp }
                      \fp_sub:Nn \l_coffin_calc_b_fp
                        { \l_coffin_calc_d_fp }
                      \fp_div:Nn \l_coffin_calc_result_fp
                        { \l_coffin_calc_b_fp }
                      \dim_set:Nn \l_coffin_x_dim
                        { \fp_to_dim:N \l_coffin_calc_result_fp }
                      \coffin_calculate_intersection_aux:nnnnnN
                        { \l_coffin_x_dim }
                        {#5} {#6} {#8} {#7} \l_coffin_y_dim
                    }
                }
            }
        }
    }
}
%    \end{macrocode}
% The formula for finding the intersection point is in most cases the
% same. The formula here is
% \[
%   \#6 = \frac{\#5}{\#4} \left ( \#1 - \#2 \right ) + \#3
% \]
% Thus "#4" and "#5" should be the directions of the pole while
% "#2" and "#3" are co-ordinates.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn 
  \coffin_calculate_intersection_aux:nnnnnN #1#2#3#4#5#6 {
    \fp_set_from_dim:Nn \l_coffin_calc_result_fp {#1}
    \fp_set_from_dim:Nn \l_coffin_calc_a_fp {#2}
    \fp_set_from_dim:Nn \l_coffin_calc_b_fp {#3}
    \fp_set_from_dim:Nn \l_coffin_calc_c_fp {#4}
    \fp_set_from_dim:Nn \l_coffin_calc_d_fp {#5}
    \fp_sub:Nn \l_coffin_calc_result_fp { \l_coffin_calc_a_fp }
    \fp_div:Nn \l_coffin_calc_result_fp { \l_coffin_calc_d_fp }
    \fp_mul:Nn \l_coffin_calc_result_fp { \l_coffin_calc_c_fp }
    \fp_add:Nn \l_coffin_calc_result_fp { \l_coffin_calc_b_fp }
    \dim_set:Nn #6 { \fp_to_dim:N \l_coffin_calc_result_fp }
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\subsection{Aligning and typesetting of coffins}
%
%\begin{macro}{\coffin_join:NnnNnnnn}
% 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 will have 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_nopar:Npn \coffin_join:NnnNnnnn #1#2#3#4#5#6#7#8 {
  \coffin_align:NnnNnnnnN 
    #1 {#2} {#3} #4 {#5} {#6} {#7} {#8} \l_coffin_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 will 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_coffin_aligned_coffin
    {
      \dim_compare:nNnT { \l_coffin_offset_x_dim } < { \c_zero_dim }
        { \tex_kern:D -\l_coffin_offset_x_dim }
      \hbox_unpack:N \l_coffin_aligned_coffin 
      \dim_set:Nn \l_coffin_tmp_dim
        { \l_coffin_offset_x_dim - \box_wd:N #1 + \box_wd:N #4 }
      \dim_compare:nNnT { \l_coffin_tmp_dim } < { \c_zero_dim }
        { \tex_kern:D -\l_coffin_tmp_dim } 
    }  
%    \end{macrocode}
% The coffin structure is reset, and the corners are cleared: only
% those from the two parent coffins are needed.
%    \begin{macrocode}
  \coffin_reset_structure:N \l_coffin_aligned_coffin
  \prop_clear:c
    {
      l_coffin_corners_ \tex_number:D \l_coffin_aligned_coffin _ prop
    }
  \coffin_update_poles:N \l_coffin_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
% will then depend on whether any shift was needed.
%    \begin{macrocode}
  \dim_compare:nNnTF { \l_coffin_offset_x_dim } < { \c_zero_dim }
    {
      \coffin_offset_poles:Nnn #1 { -\l_coffin_offset_x_dim } { 0 pt }
      \coffin_offset_poles:Nnn #4 { 0 pt } { \l_coffin_offset_y_dim }
      \coffin_offset_corners:Nnn #1 { -\l_coffin_offset_x_dim } { 0 pt }
      \coffin_offset_corners:Nnn #4 { 0 pt } { \l_coffin_offset_y_dim }
    }
    {
      \coffin_offset_poles:Nnn #1 { 0 pt } { 0 pt }
      \coffin_offset_poles:Nnn #4
        { \l_coffin_offset_x_dim } { \l_coffin_offset_y_dim } 
      \coffin_offset_corners:Nnn #1 { 0 pt } { 0 pt }
      \coffin_offset_corners:Nnn #4
        { \l_coffin_offset_x_dim } { \l_coffin_offset_y_dim } 
    }
  \coffin_update_vertical_poles:NNN #1 #4 \l_coffin_aligned_coffin  
  \coffin_set_eq:NN #1 \l_coffin_aligned_coffin
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_attach:NnnNnnnn}
%\begin{macro}{\coffin_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_nopar:Npn \coffin_attach:NnnNnnnn #1#2#3#4#5#6#7#8 {
  \coffin_align:NnnNnnnnN 
    #1 {#2} {#3} #4 {#5} {#6} {#7} {#8} \l_coffin_aligned_coffin
  \box_set_ht:Nn \l_coffin_aligned_coffin { \box_ht:N #1 }
  \box_set_dp:Nn \l_coffin_aligned_coffin { \box_dp:N #1 }
  \box_set_wd:Nn \l_coffin_aligned_coffin { \box_wd:N #1 }
  \coffin_reset_structure:N \l_coffin_aligned_coffin
  \prop_set_eq:cc
    { l_coffin_corners_ \tex_number:D \l_coffin_aligned_coffin _prop }
    { l_coffin_corners_ \tex_number:D #1 _prop }
  \coffin_update_poles:N    \l_coffin_aligned_coffin
  \coffin_offset_poles:Nnn #1 { 0 pt } { 0 pt }
  \coffin_offset_poles:Nnn #4
    { \l_coffin_offset_x_dim } { \l_coffin_offset_y_dim } 
  \coffin_update_vertical_poles:NNN #1 #4 \l_coffin_aligned_coffin
  \coffin_set_eq:NN #1 \l_coffin_aligned_coffin
}
\cs_new_protected_nopar:Npn 
  \coffin_attach_mark:NnnNnnnn #1#2#3#4#5#6#7#8 {
  \coffin_align:NnnNnnnnN 
    #1 {#2} {#3} #4 {#5} {#6} {#7} {#8} \l_coffin_aligned_coffin
  \box_set_ht:Nn \l_coffin_aligned_coffin { \box_ht:N #1 }
  \box_set_dp:Nn \l_coffin_aligned_coffin { \box_dp:N #1 }
  \box_set_wd:Nn \l_coffin_aligned_coffin { \box_wd:N #1 }
  \box_set_eq:NN #1 \l_coffin_aligned_coffin
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_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
% will depend on how the bounding box is being handled.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn 
  \coffin_align:NnnNnnnnN #1#2#3#4#5#6#7#8#9 {
  \coffin_calculate_intersection:Nnn #4 {#5} {#6}
  \dim_set:Nn \l_coffin_x_prime_dim { \l_coffin_x_dim }
  \dim_set:Nn \l_coffin_y_prime_dim { \l_coffin_y_dim }
  \coffin_calculate_intersection:Nnn #1 {#2} {#3}
  \dim_set:Nn \l_coffin_offset_x_dim
    { \l_coffin_x_dim - \l_coffin_x_prime_dim + #7 }
  \dim_set:Nn \l_coffin_offset_y_dim
    { \l_coffin_y_dim - \l_coffin_y_prime_dim + #8 }
  \hbox_set:Nn \l_coffin_aligned_internal_coffin 
    {
      \box_use:N #1
      \tex_kern:D -\box_wd:N #1
      \tex_kern:D \l_coffin_offset_x_dim
      \box_move_up:nn { \l_coffin_offset_y_dim } { \box_use:N #4 }
    }
  \coffin_set_eq:NN #9 \l_coffin_aligned_internal_coffin
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_offset_poles:Nnn}
%\begin{macro}[aux]{\coffin_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 to 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_nopar:Npn \coffin_offset_poles:Nnn #1#2#3 {
  \prop_map_inline:cn { l_coffin_poles_ \tex_number:D #1 _prop }
    { \coffin_offset_pole:Nnnnnnn #1 {##1} ##2 {#2} {#3} }
}
\cs_new_protected_nopar:Npn 
  \coffin_offset_pole:Nnnnnnn #1#2#3#4#5#6#7#8 {
  \dim_set:Nn \l_coffin_x_dim { #3 + #7 }
  \dim_set:Nn \l_coffin_y_dim { #4 + #8 }
  \tl_if_in:nnTF {#2} { - }
    { \tl_set:Nn \l_coffin_tmp_tl { {#2} } }
    { \tl_set:Nn \l_coffin_tmp_tl { { #1 - #2 } } }
  \exp_last_unbraced:NNo \coffin_set_pole:Nnx \l_coffin_aligned_coffin
    { \l_coffin_tmp_tl }
    {
      { \dim_use:N \l_coffin_x_dim } { \dim_use:N \l_coffin_y_dim }
      {#5} {#6}
    }  
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_offset_corners:Nnn}
%\begin{macro}[aux]{\coffin_offset_corners: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_nopar:Npn \coffin_offset_corners:Nnn #1#2#3 {
  \prop_map_inline:cn { l_coffin_corners_ \tex_number:D #1 _prop }
    { \coffin_offset_corner:Nnnnn #1 {##1} ##2 {#2} {#3} }
}
\cs_new_protected_nopar:Npn \coffin_offset_corner:Nnnnn #1#2#3#4#5#6 {
  \prop_put:cnx 
    { l_coffin_corners_ \tex_number:D \l_coffin_aligned_coffin _prop }
    { #1 - #2 }
    {
      { \tex_the:D \etex_dimexpr:D #3 + #5 \scan_stop: }
      { \tex_the:D \etex_dimexpr:D #4 + #6 \scan_stop: }
    }
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_update_vertical_poles:NNN}
%\begin{macro}[aux]{\coffin_update_T:nnnnnnnnN}
%\begin{macro}[aux]{\coffin_update_B:nnnnnnnnN}
% The \texttt{T} and \texttt{B} poles will 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_nopar:Npn \coffin_update_vertical_poles:NNN #1#2#3 {
  \coffin_get_pole:NnN #3 { #1 -T } \l_coffin_pole_a_tl
  \coffin_get_pole:NnN #3 { #2 -T } \l_coffin_pole_b_tl
  \exp_last_two_unbraced:Noo \coffin_update_T:nnnnnnnnN
    \l_coffin_pole_a_tl \l_coffin_pole_b_tl #3
  \coffin_get_pole:NnN #3 { #1 -B } \l_coffin_pole_a_tl
  \coffin_get_pole:NnN #3 { #2 -B } \l_coffin_pole_b_tl
  \exp_last_two_unbraced:Noo \coffin_update_B:nnnnnnnnN
    \l_coffin_pole_a_tl \l_coffin_pole_b_tl #3
}
\cs_new_protected_nopar:Npn 
  \coffin_update_T:nnnnnnnnN #1#2#3#4#5#6#7#8#9 {
  \dim_compare:nNnTF {#2} < {#6}
    {
      \coffin_set_pole:Nnx #9 { T } 
        { { 0 pt } {#6} { 1000 pt } { 0 pt } }
    }
    {
      \coffin_set_pole:Nnx #9 { T } 
        { { 0 pt } {#2} { 1000 pt } { 0 pt } }
    }
}
\cs_new_protected_nopar:Npn 
  \coffin_update_B:nnnnnnnnN #1#2#3#4#5#6#7#8#9 {
  \dim_compare:nNnTF {#2} < {#6}
    {
      \coffin_set_pole:Nnx #9 { B } 
        { { 0 pt } {#2}  { 1000 pt } { 0 pt } }
    }
    {
      \coffin_set_pole:Nnx #9 { B } 
        { { 0 pt } {#6} { 1000 pt } { 0 pt } }
    }
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_typeset:Nnnnn}
%\begin{macro}{\coffin_typeset_overlay:Nnnnn}
% Typesetting a coffin means aligning it with the current position,
% which is done using a coffin with no content at all. This is done
% using the same approach as \cs{coffin_align:NnnNnnnnN} but without the
% offset corrections (which would be thrown away). The same is true
% for overlaying coffins, which uses the known size of an empty
% box!
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \coffin_typeset:Nnnnn #1#2#3#4#5 {
  \coffin_align:NnnNnnnnN \c_empty_coffin { H } { l } 
    #1 {#2} {#3} {#4} {#5} \l_coffin_aligned_coffin
  \hbox_set:Nn \l_coffin_aligned_coffin
    {
      \dim_compare:nNnT { \l_coffin_offset_x_dim } < { \c_zero_dim }
        { \tex_kern:D -\l_coffin_offset_x_dim }
      \hbox_unpack:N \l_coffin_aligned_coffin 
      \dim_set:Nn \l_coffin_tmp_dim
        { \l_coffin_offset_x_dim + \box_wd:N #1 }
      \dim_compare:nNnT { \l_coffin_tmp_dim } < { \c_zero_dim }
        { \tex_kern:D -\l_coffin_tmp_dim } 
    } 
  \hbox_unpack:N \c_empty_box  
  \box_use:N \l_coffin_aligned_coffin
}
\cs_new_protected_nopar:Npn \coffin_typeset_overlay:Nnnnn #1#2#3#4#5 {
  \coffin_align:NnnNnnnnN \c_empty_coffin { H } { l } 
    #1 {#2} {#3} {#4} {#5} \l_coffin_aligned_coffin
  \box_set_ht:Nn \l_coffin_aligned_coffin { \c_zero_dim }
  \box_set_dp:Nn \l_coffin_aligned_coffin { \c_zero_dim }
  \box_set_wd:Nn \l_coffin_aligned_coffin { \c_zero_dim }
  \hbox_unpack:N \c_empty_box
  \box_use:N \l_coffin_aligned_coffin
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\subsection{Rotating coffins}
%
%\begin{macro}{\l_coffin_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_coffin_bounding_prop
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\l_coffin_bounding_shift_dim}
% The shift of the bounding box of a coffin from the real content.
%    \begin{macrocode}
\dim_new:N \l_coffin_bounding_shift_dim
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\l_coffin_left_corner_dim}
%\begin{macro}{\l_coffin_right_corner_dim}
%\begin{macro}{\l_coffin_bottom_corner_dim}
%\begin{macro}{\l_coffin_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_coffin_left_corner_dim
\dim_new:N \l_coffin_right_corner_dim
\dim_new:N \l_coffin_bottom_corner_dim
\dim_new:N \l_coffin_top_corner_dim
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_rotate:Nn}
% Rotating a coffin requires several steps which can be conveniently 
% run together. The first step is to convert the angle given in degrees
% to one in radians. This is then used to set \cs{l_coffin_sin_fp} and
% \cs{l_coffin_cos_fp}, which are carried through unchanged for the rest
% of the procedure.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \coffin_rotate:Nn #1#2 {
  \fp_set:Nn \l_coffin_tmp_fp {#2}
  \fp_div:Nn \l_coffin_tmp_fp { 180 }
  \fp_mul:Nn \l_coffin_tmp_fp { \c_pi_fp }
  \fp_sin:Nn \l_coffin_sin_fp { \l_coffin_tmp_fp }
  \fp_cos:Nn \l_coffin_cos_fp { \l_coffin_tmp_fp }
%    \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:cn { l_coffin_corners_ \tex_number:D #1 _prop }
    { \coffin_rotate_corner:Nnnn #1 {##1} ##2 }
  \prop_map_inline:cn { l_coffin_poles_ \tex_number:D #1 _prop }
    { \coffin_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}
  \coffin_set_bounding:N #1
  \prop_map_inline:Nn \l_coffin_bounding_prop
    { \coffin_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}
  \coffin_find_corner_maxima:N #1 
  \coffin_find_bounding_shift:
  \hbox_set:Nn #1 { \rotatebox {#2} { \box_use:N #1 } }
%    \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.
%    \begin{macrocode}
  \hbox_set:Nn #1 
    {
      \tex_kern:D \l_coffin_bounding_shift_dim
      \tex_kern:D -\l_coffin_left_corner_dim
      \box_move_down:nn { \l_coffin_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.
%    \begin{macrocode}
  \box_set_ht:Nn #1 
    { \l_coffin_top_corner_dim - \l_coffin_bottom_corner_dim }
  \box_set_dp:Nn #1 { 0 pt }  
  \box_set_wd:Nn #1 
    { \l_coffin_right_corner_dim - \l_coffin_left_corner_dim }
%    \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:cn { l_coffin_corners_ \tex_number:D #1 _prop }
    { \coffin_shift_corner:Nnnn #1 {##1} ##2 }
  \prop_map_inline:cn { l_coffin_poles_ \tex_number:D #1 _prop }
    { \coffin_shift_pole:Nnnnnn #1 {##1} ##2 }
} 
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_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_nopar:Npn \coffin_set_bounding:N #1 {
  \prop_put:Nnx \l_coffin_bounding_prop { tl } 
    { { 0 pt } { \dim_use:N \box_ht:N #1 } }
  \prop_put:Nnx \l_coffin_bounding_prop { tr } 
    { { \dim_use:N \box_wd:N #1 } { \dim_use:N \box_ht:N #1 } }
  \dim_set:Nn \l_coffin_tmp_dim { - \dim_use:N \box_dp:N #1 }  
  \prop_put:Nnx \l_coffin_bounding_prop { bl } 
    { { 0 pt } { \dim_use:N \l_coffin_tmp_dim } }
  \prop_put:Nnx \l_coffin_bounding_prop { br } 
    { { \dim_use:N \box_wd:N #1 } { \dim_use:N \l_coffin_tmp_dim } }
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_rotate_bounding:nnn}
%\begin{macro}{\coffin_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_nopar:Npn \coffin_rotate_bounding:nnn #1#2#3 {
  \coffin_rotate_vector:nnNN {#2} {#3} \l_coffin_x_dim \l_coffin_y_dim
  \prop_put:Nnx \l_coffin_bounding_prop {#1}
    { { \dim_use:N \l_coffin_x_dim } { \dim_use:N \l_coffin_y_dim } }  
}
\cs_new_protected_nopar:Npn \coffin_rotate_corner:Nnnn #1#2#3#4 {
  \coffin_rotate_vector:nnNN {#3} {#4} \l_coffin_x_dim \l_coffin_y_dim
  \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } {#2}
    { { \dim_use:N \l_coffin_x_dim } { \dim_use:N \l_coffin_y_dim } }  
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_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_nopar:Npn \coffin_rotate_pole:Nnnnnn #1#2#3#4#5#6 {
  \coffin_rotate_vector:nnNN {#3} {#4} \l_coffin_x_dim \l_coffin_y_dim
  \coffin_rotate_vector:nnNN {#5} {#6} 
    \l_coffin_x_prime_dim \l_coffin_y_prime_dim
  \coffin_set_pole:Nnx #1 {#2}
    {
      { \dim_use:N \l_coffin_x_dim } { \dim_use:N \l_coffin_y_dim }
      { \dim_use:N \l_coffin_x_prime_dim }
      { \dim_use:N \l_coffin_y_prime_dim }
    }  
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_rotate_vector:nnNN}
% A rotation function, which needs only an input vector (as dimensions)
% and an output space. The values \cs{l_coffin_cos_fp} and
% \cs{l_coffin_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_nopar:Npn \coffin_rotate_vector:nnNN #1#2#3#4 {
  \fp_set_from_dim:Nn \l_coffin_x_fp {#1}
  \fp_set_from_dim:Nn \l_coffin_y_fp {#2}
  \fp_set_eq:NN \l_coffin_x_prime_fp \l_coffin_x_fp
  \fp_set_eq:NN \l_coffin_tmp_fp     \l_coffin_y_fp
  \fp_mul:Nn \l_coffin_x_prime_fp { \l_coffin_cos_fp }
  \fp_mul:Nn \l_coffin_tmp_fp     { \l_coffin_sin_fp }
  \fp_sub:Nn \l_coffin_x_prime_fp { \l_coffin_tmp_fp } 
  \fp_set_eq:NN \l_coffin_y_prime_fp \l_coffin_y_fp
  \fp_set_eq:NN \l_coffin_tmp_fp     \l_coffin_x_fp
  \fp_mul:Nn \l_coffin_y_prime_fp { \l_coffin_cos_fp }
  \fp_mul:Nn \l_coffin_tmp_fp     { \l_coffin_sin_fp }
  \fp_add:Nn \l_coffin_y_prime_fp { \l_coffin_tmp_fp }
  \dim_set:Nn #3 { \fp_to_dim:N \l_coffin_x_prime_fp }
  \dim_set:Nn #4 { \fp_to_dim:N \l_coffin_y_prime_fp }
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_find_corner_maxima:N}
%\begin{macro}[aux]{\coffin_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_nopar:Npn \coffin_find_corner_maxima:N #1 {
  \dim_set:Nn \l_coffin_top_corner_dim   { -\c_max_dim }
  \dim_set:Nn \l_coffin_right_corner_dim { -\c_max_dim }
  \dim_set:Nn \l_coffin_bottom_corner_dim { \c_max_dim }
  \dim_set:Nn \l_coffin_left_corner_dim   { \c_max_dim }
  \prop_map_inline:cn { l_coffin_corners_ \tex_number:D #1 _prop } 
    { \coffin_find_corner_maxima_aux:nn ##2 }
}
\cs_new_protected_nopar:Npn \coffin_find_corner_maxima_aux:nn #1#2 {
  \dim_set_min:Nn \l_coffin_left_corner_dim   {#1}
  \dim_set_max:Nn \l_coffin_right_corner_dim  {#1}
  \dim_set_min:Nn \l_coffin_bottom_corner_dim {#2}
  \dim_set_max:Nn \l_coffin_top_corner_dim    {#2}
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_find_bounding_shift:}
%\begin{macro}[aux]{\coffin_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_nopar:Npn \coffin_find_bounding_shift: {
  \dim_set:Nn \l_coffin_bounding_shift_dim { \c_max_dim }
  \prop_map_inline:Nn \l_coffin_bounding_prop
    { \coffin_find_bounding_shift_aux:nn ##2 }
}
\cs_new_protected_nopar:Npn \coffin_find_bounding_shift_aux:nn #1#2 {
  \dim_set_min:Nn \l_coffin_bounding_shift_dim {#1}
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_shift_corner:Nnnn}
%\begin{macro}{\coffin_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_nopar:Npn \coffin_shift_corner:Nnnn #1#2#3#4 {
  \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _ prop } {#2}
    {
      {
        \tex_the:D \etex_dimexpr:D #3 - \l_coffin_left_corner_dim
          \scan_stop:
      }
      {
        \tex_the:D \etex_dimexpr:D #4 - \l_coffin_bottom_corner_dim
          \scan_stop:
      }
    }
}
\cs_new_protected_nopar:Npn \coffin_shift_pole:Nnnnnn #1#2#3#4#5#6 {
  \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _ prop } {#2}
    {
      {
        \tex_the:D \etex_dimexpr:D #3 - \l_coffin_left_corner_dim
          \scan_stop:
      }
      {
        \tex_the:D \etex_dimexpr:D #4 - \l_coffin_bottom_corner_dim
          \scan_stop:
      }
      {#5} {#6}
    }
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\subsection{Resizing coffins}
%
%\begin{macro}{\l_coffin_scale_x_fp}
%\begin{macro}{\l_coffin_scale_y_fp}
% Storage for the scaling factors in \( x \) and \( y \), respectively.
%    \begin{macrocode}
\fp_new:N \l_coffin_scale_x_fp
\fp_new:N \l_coffin_scale_y_fp
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\l_coffin_scaled_total_height_dim}
%\begin{macro}{\l_coffin_scaled_width_dim}
% When scaling, the values given have to be turned into absolute values.
%    \begin{macrocode}
\dim_new:N \l_coffin_scaled_total_height_dim
\dim_new:N \l_coffin_scaled_width_dim
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_resize:Nnn}
% 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_nopar:Npn \coffin_resize:Nnn #1#2#3 {
  \coffin_set_user_dimensions:N #1
  \fp_set_from_dim:Nn \l_coffin_scale_x_fp {#2}
  \fp_set_from_dim:Nn \l_coffin_tmp_fp { \Width }
  \fp_div:Nn \l_coffin_scale_x_fp { \l_coffin_tmp_fp }
  \fp_set_from_dim:Nn \l_coffin_scale_y_fp {#3}
  \fp_set_from_dim:Nn \l_coffin_tmp_fp { \TotalHeight }
  \fp_div:Nn \l_coffin_scale_y_fp { \l_coffin_tmp_fp }
  \hbox_set:Nn #1 { \resizebox * {#2} {#3} { \box_use:N #1 } }
  \coffin_resize_common:Nnn #1 {#2} {#3}
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_resize_common:Nnn}
% The poles and corners of the coffin are scaled to the appropriate
% places before actually resizing the underlying box.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \coffin_resize_common:Nnn #1#2#3 {
  \prop_map_inline:cn { l_coffin_corners_ \tex_number:D #1 _prop }
    { \coffin_scale_corner:Nnnn #1 {##1} ##2 }
  \prop_map_inline:cn { l_coffin_poles_ \tex_number:D #1 _prop }
    { \coffin_scale_pole:Nnnnnn #1 {##1} ##2 }
%    \end{macrocode}
% Negative \( x \)-scaling values will place the poles in the wrong
% location: this is corrected here.
%    \begin{macrocode}
  \fp_compare:NNNT \l_coffin_scale_x_fp < \c_zero_fp
    {
      \prop_map_inline:cn { l_coffin_corners_ \tex_number:D #1 _prop }
        { \coffin_x_shift_corner:Nnnn #1 {##1} ##2 }
      \prop_map_inline:cn { l_coffin_poles_ \tex_number:D #1 _prop }
        { \coffin_x_shift_pole:Nnnnnn #1 {##1} ##2 }
    }  
  \coffin_end_user_dimensions:
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_scale:Nnn}
% 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_nopar:Npn \coffin_scale:Nnn #1#2#3 {
  \coffin_set_user_dimensions:N #1
  \fp_set:Nn \l_coffin_scale_x_fp {#2}
  \fp_set:Nn \l_coffin_scale_y_fp {#3}
  \fp_compare:NNNTF \l_coffin_scale_y_fp > \c_zero_fp
    { \l_coffin_scaled_total_height_dim #3 \TotalHeight }
    { \l_coffin_scaled_total_height_dim -#3 \TotalHeight }
  \fp_compare:NNNTF \l_coffin_scale_x_fp > \c_zero_fp
    { \l_coffin_scaled_width_dim -#2 \Width }
    { \l_coffin_scaled_width_dim #2 \Width }
  \hbox_set:Nn #1 { \scalebox  {#2} [#3] { \box_use:N #1 } }
  \coffin_resize_common:Nnn #1 
    { \l_coffin_scaled_width_dim } { \l_coffin_scaled_total_height_dim }
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_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_nopar:Npn \coffin_scale_vector:nnNN #1#2#3#4 {
  \fp_set_from_dim:Nn \l_coffin_tmp_fp {#1}
  \fp_mul:Nn \l_coffin_tmp_fp { \l_coffin_scale_x_fp }
  \dim_set:Nn #3 { \fp_to_dim:N \l_coffin_tmp_fp }
  \fp_set_from_dim:Nn \l_coffin_tmp_fp {#2}
  \fp_mul:Nn \l_coffin_tmp_fp { \l_coffin_scale_y_fp }
  \dim_set:Nn #4 { \fp_to_dim:N \l_coffin_tmp_fp }
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_scale_corner:Nnnn}
%\begin{macro}{\coffin_scale_pole:Nnnnnn}
% Scaling both corners and poles is a simple calculation using the 
% preceding vector scaling.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \coffin_scale_corner:Nnnn #1#2#3#4 {
  \coffin_scale_vector:nnNN {#3} {#4} \l_coffin_x_dim \l_coffin_y_dim
  \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } {#2}
    { { \dim_use:N \l_coffin_x_dim } { \dim_use:N \l_coffin_y_dim } }  
}
\cs_new_protected_nopar:Npn \coffin_scale_pole:Nnnnnn #1#2#3#4#5#6 {
  \coffin_scale_vector:nnNN {#3} {#4} \l_coffin_x_dim \l_coffin_y_dim
  \coffin_set_pole:Nnx #1 {#2}
    {
      { \dim_use:N \l_coffin_x_dim } { \dim_use:N \l_coffin_y_dim }
      {#5} {#6}
    }  
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_x_shift_corner:Nnnn}
%\begin{macro}{\coffin_x_shift_pole:Nnnnnn}
% These functions correct for the \( x \) displacement that takes
% place with a negative horizontal scaling.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \coffin_x_shift_corner:Nnnn #1#2#3#4 {
  \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } {#2}
    { 
      { \the_tex:D \etex_dimexpr:D #3 + \box_wd:N #1 \scan_stop: } {#4}
    }
}
\cs_new_protected_nopar:Npn \coffin_x_shift_pole:Nnnnnn #1#2#3#4#5#6 {
  \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _prop } {#2}
    {
      { \the_tex:D \etex_dimexpr:D #3 + \box_wd:N #1 \scan_stop: } {#4} 
      {#5} {#6} 
    }
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\subsection{Coffin diagnostics}
%
%\begin{macro}{\l_coffin_display_coffin}
%\begin{macro}{\l_coffin_display_coord_coffin}
%\begin{macro}{\l_coffin_display_pole_coffin}
% Used for printing coffins with data structures attached.
%    \begin{macrocode}
\coffin_new:N \l_coffin_display_coffin
\coffin_new:N \l_coffin_display_coord_coffin
\coffin_new:N \l_coffin_display_pole_coffin
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\l_coffin_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_coffin_display_handles_prop
\prop_put:Nnn \l_coffin_display_handles_prop { tl }
  { { b } { r } { -1 } { 1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { thc }
  { { b } { hc } { 0 } { 1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { tr }
  { { b } { l } { 1 } { 1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { vcl }
  { { vc } { r } { -1 } { 0 } }
\prop_put:Nnn \l_coffin_display_handles_prop { vchc }
  { { vc } { hc } { 0 } { 0 } }
\prop_put:Nnn \l_coffin_display_handles_prop { vcr }
  { { vc } { l } { 1 } { 0 } }
\prop_put:Nnn \l_coffin_display_handles_prop { bl }
  { { t } { r } { -1 } { -1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { bhc }
  { { t } { hc } { 0 } { -1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { br }
  { { t } { l } { 1 } { -1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { Tl }
  { { t } { r } { -1 } { -1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { Thc }
  { { t } { hc } { 0 } { -1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { Tr }
  { { t } { l } { 1 } { -1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { Hl }
  { { vc } { r } { -1 } { 1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { Hhc }
  { { vc } { hc } { 0 } { 1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { Hr }
  { { vc } { l } { 1 } { 1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { Bl }
  { { b } { r } { -1 } { -1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { Bhc }
  { { b } { hc } { 0 } { -1 } }
\prop_put:Nnn \l_coffin_display_handles_prop { Br }
  { { b } { l } { 1 } { -1 } }
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\l_coffin_display_offset_dim}
% The standard offset for the label from the handle position when
% displaying handles.
%    \begin{macrocode}
\dim_new:N  \l_coffin_display_offset_dim
\dim_set:Nn \l_coffin_display_offset_dim { 2 pt }
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\l_coffin_display_x_dim}
%\begin{macro}{\l_coffin_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_coffin_display_x_dim
\dim_new:N \l_coffin_display_y_dim
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\l_coffin_display_poles_prop}
% A property list for printing poles: various things need to be deleted
% from this to get a `nice' output.
%    \begin{macrocode}
\prop_new:N \l_coffin_display_poles_prop
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\l_coffin_display_font_tl}
% Stores the settings used to print coffin data: this keeps things 
% flexible.
%    \begin{macrocode}
\tl_new:N  \l_coffin_display_font_tl
\tl_set:Nn \l_coffin_display_font_tl { \sffamily \tiny }
%    \end{macrocode}
%\end{macro}
%    
%\begin{macro}{\l_coffin_show_toks}
% For the package the \LaTeXe\ code can be used.    
%    \begin{macrocode}
\cs_new_eq:NN \l_coffin_show_toks \toks@
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\l_coffin_handles_tmp_prop}
% Used for displaying coffins, as the handles need to be stored in this
% case, at least temporarily.
%    \begin{macrocode}
\prop_new:N \l_coffin_handles_tmp_prop
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\coffin_mark_handle:Nnnn}
%\begin{macro}{\coffin_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_nopar:Npn \coffin_mark_handle:Nnnn #1#2#3#4 {
  \hcoffin_set:Nn \l_coffin_display_pole_coffin
    {
      \color {#4} 
      \rule { 1 pt } { 1 pt } 
      \hbox:n { \tex_vrule:D width 1 pt height 1 pt \scan_stop: } % TEMP
    }
  \coffin_attach_mark:NnnNnnnn #1 {#2} {#3}
    \l_coffin_display_pole_coffin { hc } { vc } { 0 pt } { 0 pt } 
  \hcoffin_set:Nn \l_coffin_display_coord_coffin
    {
      \color {#4} 
      \l_coffin_display_font_tl
      ( \tl_to_str:n { #2 , #3 } )
    }
  \prop_get:NnN \l_coffin_display_handles_prop
    { #2 #3 } \l_coffin_tmp_tl
  \quark_if_no_value:NTF \l_coffin_tmp_tl
    {
      \prop_get:NnN \l_coffin_display_handles_prop
        { #3 #2 } \l_coffin_tmp_tl
      \quark_if_no_value:NTF \l_coffin_tmp_tl
        { 
          \coffin_attach_mark:NnnNnnnn #1 {#2} {#3}
            \l_coffin_display_coord_coffin { l } { vc }
              { 1 pt } { 0 pt }
        }
        {
          \exp_last_unbraced:No \coffin_mark_handle_aux:nnnnNnn
            \l_coffin_tmp_tl #1 {#2} {#3}
        }  
    }
    {
      \exp_last_unbraced:No \coffin_mark_handle_aux:nnnnNnn
        \l_coffin_tmp_tl #1 {#2} {#3}
    }
}
\cs_new_protected_nopar:Npn 
  \coffin_mark_handle_aux:nnnnNnn #1#2#3#4#5#6#7 {
  \coffin_attach_mark:NnnNnnnn #5 {#6} {#7}
    \l_coffin_display_coord_coffin {#1} {#2}
    { #3 \l_coffin_display_offset_dim } 
    { #4 \l_coffin_display_offset_dim }
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_display_handles:Nn}
%\begin{macro}[aux]{\coffin_display_handles_aux:nnnnnn}
%\begin{macro}[aux]{\coffin_display_handles_aux:nnnn}
%\begin{macro}[aux]{\coffin_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_nopar:Npn \coffin_display_handles:Nn #1#2 {
  \hcoffin_set:Nn \l_coffin_display_pole_coffin
    {
      \color {#2} 
      \rule { 1 pt } { 1 pt } 
    }
  \prop_set_eq:Nc \l_coffin_display_poles_prop
    { l_coffin_poles_ \tex_number:D #1 _prop }
  \coffin_get_pole:NnN #1 { H } \l_coffin_pole_a_tl
  \coffin_get_pole:NnN #1 { T } \l_coffin_pole_b_tl  
  \tl_if_eq:NNT \l_coffin_pole_a_tl \l_coffin_pole_b_tl
    { \prop_del:Nn \l_coffin_display_poles_prop { T } }
  \coffin_get_pole:NnN #1 { B } \l_coffin_pole_b_tl
  \tl_if_eq:NNT \l_coffin_pole_a_tl \l_coffin_pole_b_tl
    { \prop_del:Nn \l_coffin_display_poles_prop { B } }
  \coffin_set_eq:NN \l_coffin_display_coffin #1  
  \prop_clear:N \l_coffin_handles_tmp_prop
  \prop_map_inline:Nn \l_coffin_display_poles_prop
    {
      \prop_del:Nn \l_coffin_display_poles_prop {##1}
      \coffin_display_handles_aux:nnnnnn {##1} ##2 {#2}
    }
  \box_use:N \l_coffin_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_nopar:Npn 
  \coffin_display_handles_aux:nnnnnn #1#2#3#4#5#6 {
  \prop_map_inline:Nn \l_coffin_display_poles_prop
    { 
      \bool_set_false:N \l_coffin_error_bool
      \coffin_calculate_intersection:nnnnnnnn {#2} {#3} {#4} {#5} ##2
      \bool_if:NF \l_coffin_error_bool
        {
          \dim_set:Nn \l_coffin_display_x_dim { \l_coffin_x_dim }
          \dim_set:Nn \l_coffin_display_y_dim { \l_coffin_y_dim }
          \coffin_display_attach:Nnnnn
            \l_coffin_display_pole_coffin { hc } { vc }
            { 0 pt } { 0 pt }
          \hcoffin_set:Nn \l_coffin_display_coord_coffin
            {
              \color {#6} 
              \l_coffin_display_font_tl
              ( \tl_to_str:n { #1 , ##1 } )
            }
          \prop_get:NnN \l_coffin_display_handles_prop
            { #1 ##1 } \l_coffin_tmp_tl
          \quark_if_no_value:NTF \l_coffin_tmp_tl
            {
              \prop_get:NnN \l_coffin_display_handles_prop
                { ##1 #1 } \l_coffin_tmp_tl
              \quark_if_no_value:NTF \l_coffin_tmp_tl
                {
                  \coffin_display_attach:Nnnnn 
                    \l_coffin_display_coord_coffin { l } { vc }
                    { 1 pt } { 0 pt }
                }
                {  
                  \exp_last_unbraced:No 
                    \coffin_display_handles_aux:nnnn
                    \l_coffin_tmp_tl
                }
            }
            {
              \exp_last_unbraced:No \coffin_display_handles_aux:nnnn
                \l_coffin_tmp_tl
            }
        }
    }
}
\cs_new_protected_nopar:Npn \coffin_display_handles_aux:nnnn #1#2#3#4 {
  \coffin_display_attach:Nnnnn
    \l_coffin_display_coord_coffin {#1} {#2}
    { #3 \l_coffin_display_offset_dim } 
    { #4 \l_coffin_display_offset_dim }
}
%    \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_nopar:Npn \coffin_display_attach:Nnnnn #1#2#3#4#5 {
  \coffin_calculate_intersection:Nnn #1 {#2} {#3}
  \dim_set:Nn \l_coffin_x_prime_dim { \l_coffin_x_dim }
  \dim_set:Nn \l_coffin_y_prime_dim { \l_coffin_y_dim }
  \dim_set:Nn \l_coffin_offset_x_dim
    { \l_coffin_display_x_dim - \l_coffin_x_prime_dim + #4 }
  \dim_set:Nn \l_coffin_offset_y_dim
    { \l_coffin_display_y_dim - \l_coffin_y_prime_dim + #5 }
  \hbox_set:Nn \l_coffin_aligned_coffin
    {
      \box_use:N \l_coffin_display_coffin
      \tex_kern:D -\box_wd:N \l_coffin_display_coffin
      \tex_kern:D \l_coffin_offset_x_dim
      \box_move_up:nn { \l_coffin_offset_y_dim } { \box_use:N #1 }
    }
  \box_set_ht:Nn \l_coffin_aligned_coffin 
    { \box_ht:N \l_coffin_display_coffin }
  \box_set_dp:Nn \l_coffin_aligned_coffin 
    { \box_dp:N \l_coffin_display_coffin }
  \box_set_wd:Nn \l_coffin_aligned_coffin 
    { \box_wd:N \l_coffin_display_coffin }
  \box_set_eq:NN \l_coffin_display_coffin \l_coffin_aligned_coffin
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\coffin_show_structure:N}
%\begin{macro}{\coffin_show_structure:c}
% 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_nopar:Npn \coffin_show_structure:N #1 {
  \iow_term:x 
    { 
      \iow_newline:
      Size~of~coffin~\token_to_str:N #1 : \iow_newline:
      > ~ ht~=~\dim_use:N \box_ht:N #1 \iow_newline:
      > ~ dp~=~\dim_use:N \box_dp:N #1 \iow_newline:
      > ~ wd~=~\dim_use:N \box_wd:N #1 \iow_newline:
    }
  \toks_clear:N \l_coffin_show_toks
  \cs_if_free:cTF { l_coffin_poles_ \tex_number:D #1 _prop }
    { 
      \iow_term:x { ---~No~poles~found~--- }
      \toks_put_right:Nn \l_coffin_show_toks 
        { Is~this~really~a~coffin? }
    }
    {
      \iow_term:x { Poles~of~coffin~\token_to_str:N #1 : }
      \prop_map_inline:cn { l_coffin_poles_ \tex_number:D #1 _prop }
        {
          \toks_if_empty:NF \l_coffin_show_toks  
            { 
              \toks_put_right:Nx \l_coffin_show_toks 
                { \iow_newline: > ~ } 
            }
          \toks_put_right:Nx \l_coffin_show_toks  
            { ~ \exp_not:n {##1} \c_space_tl => ~ \exp_not:n {##2} }
        } 
    }
  \toks_show:N \l_coffin_show_toks
}
\cs_generate_variant:Nn \coffin_show_structure:N { c }
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\subsection{Messages}
%
%    \begin{macrocode}
\msg_kernel_new:nnnn { coffin } { no-pole-intersection }
  { No~intersection~between~coffin~poles. }
  {
    \l_msg_coding_error_text_tl
    LaTeX~was~asked~to~find~the~intersection~between~two~poles,~
    but~they~do~not~have~a~unique~meeting~point:~
    the~value~(0~pt,~0~pt)~will~be~used.
  }
\msg_kernel_new:nnnn { coffin } { unknown-coffin }
  { Unknown~coffin~'#1'. }
  { The~coffin~'#1'~was~never~defined. }
\msg_kernel_new:nnnn { coffin } { unknown-coffin-pole }
  { Pole~'#1'~unknown~for~coffin~'#2'. }
  {
    \l_msg_coding_error_text_tl
    LaTeX~was~asked~to~find~a~typesetting~pole~for~a~coffin,~
    but~either~the~coffin~does~not~exist~or~the~pole~name~is~wrong.
  }
%    \end{macrocode}
%    
%  \begin{macro}{\exp_two_last_unbraced:Noo}
%    \begin{macrocode}
\cs_new:Npn \exp_last_two_unbraced:Noo #1 #2 #3{
  \exp_after:wN \exp_after:wN \exp_after:wN #1 \exp_after:wN #2 #3
}
%    \end{macrocode}
%  \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
%\end{implementation}
%
%\PrintChanges
%
%\PrintIndex