% \iffalse meta-comment
%
%% File: l3coffins.dtx Copyright(C) 2010-2014 The 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 "l3kernel 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>
\documentclass[full]{l3doc}
%</driver>
%<*driver|package>
\GetIdInfo$Id: l3coffins.dtx 5354 2014-08-23 01:35:39Z bruno $
  {L3 Coffin code layer}
%</driver|package>
%<*driver>
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \textsf{l3coffins} package\\ Coffin code layer^^A
%   \thanks{This file describes v\ExplFileVersion,
%     last revised \ExplFileDate.}^^A
% }
%
% \author{^^A
%  The \LaTeX3 Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released \ExplFileDate}
%
% \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} will
%   initially be empty.
% \end{function}
%
% \begin{function}[added = 2011-08-17]{\coffin_clear:N, \coffin_clear:c}
%   \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}[added = 2011-08-17]
%  {\coffin_set_eq:NN, \coffin_set_eq:Nc, \coffin_set_eq:cN, \coffin_set_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} within the current \TeX\ group level.
% \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{box}
%     \cs{coffin_if_exist:NTF} \meta{box} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Tests whether the \meta{coffin} is currently defined.
% \end{function}
%
% \section{Setting coffin content and poles}
%
% All coffin functions create and manipulate coffins locally within the
% current \TeX\ group level.
%
% \begin{function}[added = 2011-08-17, updated = 2011-09-03]
%   {\hcoffin_set:Nn, \hcoffin_set: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]
%   {\hcoffin_set:Nw, \hcoffin_set:cw, \hcoffin_set_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 = 2012-05-22]
%   {\vcoffin_set:Nnn, \vcoffin_set: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 = 2012-05-22]
%   {\vcoffin_set:Nnw, \vcoffin_set:cnw, \vcoffin_set_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]
%   {\coffin_set_horizontal_pole:Nnn, \coffin_set_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} 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.
% \end{function}
%
% \begin{function}[added = 2012-07-20]
%   {\coffin_set_vertical_pole:Nnn, \coffin_set_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} 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.
% \end{function}
%
% \section{Joining and using coffins}
%
% \begin{function}
%   {
%     \coffin_attach:NnnNnnnn, \coffin_attach:cnnNnnnn,
%     \coffin_attach:Nnncnnnn, \coffin_attach: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 <coffin_2> to <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}
%   {
%     \coffin_join:NnnNnnnn, \coffin_join:cnnNnnnn,
%     \coffin_join:Nnncnnnn, \coffin_join: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 <coffin_2> to <coffin_1> such that the bounding box
%   of \meta{coffin_1} may expand. The new bounding
%   box will cover 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{dimension expression}.
% \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{dimension expression}.
% \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{dimension expression}.
% \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} will be 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} will be 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 = 2012-09-09]
%   {\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}
%
% \subsection{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}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3coffins} Implementation}
%
%    \begin{macrocode}
%<*initex|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_new:N \c_@@_corners_prop
\prop_put:Nnn \c_@@_corners_prop { tl } { { 0 pt } { 0 pt } }
\prop_put:Nnn \c_@@_corners_prop { tr } { { 0 pt } { 0 pt } }
\prop_put:Nnn \c_@@_corners_prop { bl } { { 0 pt } { 0 pt } }
\prop_put:Nnn \c_@@_corners_prop { br } { { 0 pt } { 0 pt } }
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\c_@@_poles_prop}
%   Pole positions are given for horizontal, vertical and reference-point
%   based values.
%    \begin{macrocode}
\prop_new:N \c_@@_poles_prop
\tl_set:Nn \l_@@_internal_tl { { 0 pt } { 0 pt } { 0 pt } { 1000 pt } }
\prop_put:Nno \c_@@_poles_prop { l }  { \l_@@_internal_tl }
\prop_put:Nno \c_@@_poles_prop { hc } { \l_@@_internal_tl }
\prop_put:Nno \c_@@_poles_prop { r }  { \l_@@_internal_tl }
\tl_set:Nn \l_@@_internal_tl { { 0 pt } { 0 pt } { 1000 pt } { 0 pt } }
\prop_put:Nno \c_@@_poles_prop { b }  { \l_@@_internal_tl }
\prop_put:Nno \c_@@_poles_prop { vc } { \l_@@_internal_tl }
\prop_put:Nno \c_@@_poles_prop { t }  { \l_@@_internal_tl }
\prop_put:Nno \c_@@_poles_prop { B }  { \l_@@_internal_tl }
\prop_put:Nno \c_@@_poles_prop { H }  { \l_@@_internal_tl }
\prop_put:Nno \c_@@_poles_prop { T }  { \l_@@_internal_tl }
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_slope_x_fp}
% \begin{variable}{\l_@@_slope_y_fp}
%   Used for calculations of intersections.
%    \begin{macrocode}
\fp_new:N \l_@@_slope_x_fp
\fp_new:N \l_@@_slope_y_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, pTF]{\coffin_if_exist:N, \coffin_if_exist:c}
%   Several of the higher-level coffin functions will 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 { l_@@_poles_ \__int_value:w #1 _prop }
          { \prg_return_true: }
          { \prg_return_false: }
      }
      { \prg_return_false: }
  }
\cs_generate_variant:Nn \coffin_if_exist_p:N { c }
\cs_generate_variant:Nn \coffin_if_exist:NT  { c }
\cs_generate_variant:Nn \coffin_if_exist:NF  { c }
\cs_generate_variant:Nn \coffin_if_exist:NTF { c }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_if_exist:NT}
%   Several of the higher-level coffin functions will 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_kernel_error:nnx { kernel } { unknown-coffin }
          { \token_to_str:N #1 }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\coffin_clear:N, \coffin_clear: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 }
%    \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. 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:Npn \coffin_new:N #1
  {
    \box_new:N #1
    \prop_clear_new:c { l_@@_corners_ \__int_value:w #1 _prop }
    \prop_clear_new:c { l_@@_poles_   \__int_value:w #1 _prop }
    \prop_gset_eq:cN { l_@@_corners_ \__int_value:w #1 _prop }
      \c_@@_corners_prop
    \prop_gset_eq:cN { l_@@_poles_ \__int_value:w #1 _prop }
      \c_@@_poles_prop
  }
\cs_generate_variant:Nn \coffin_new:N { c }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\hcoffin_set:Nn, \hcoffin_set: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_group_begin:
              \color_ensure_current:
              #2
            \color_group_end:
          }
        \@@_reset_structure:N #1
        \@@_update_poles:N #1
        \@@_update_corners:N #1
      }
  }
\cs_generate_variant:Nn \hcoffin_set:Nn { c }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\vcoffin_set:Nnn, \vcoffin_set:cnn}
%   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
  {
    \@@_if_exist:NT #1
      {
        \vbox_set:Nn #1
          {
            \dim_set:Nn \tex_hsize:D {#2}
%<*package>
            \dim_set_eq:NN \linewidth   \tex_hsize:D
            \dim_set_eq:NN \columnwidth \tex_hsize:D
%</package>
            \color_group_begin:
              #3
            \color_group_end:
          }
        \@@_reset_structure:N #1
        \@@_update_poles:N #1
        \@@_update_corners:N #1
        \vbox_set_top:Nn \l_@@_internal_box { \vbox_unpack:N #1 }
        \@@_set_pole:Nnx #1 { T }
          {
            { 0 pt }
            {
              \dim_eval:n
                { \box_ht:N #1 - \box_ht:N \l_@@_internal_box }
            }
            { 1000 pt }
            { 0 pt }
          }
        \box_clear:N \l_@@_internal_box
      }
  }
\cs_generate_variant:Nn \vcoffin_set:Nnn { c }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\hcoffin_set:Nw, \hcoffin_set:cw}
% \begin{macro}{\hcoffin_set_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_group_begin: \color_ensure_current:
          \cs_set_protected_nopar:Npn \hcoffin_set_end:
            {
                \color_group_end:
              \hbox_set_end:
              \@@_reset_structure:N #1
              \@@_update_poles:N #1
              \@@_update_corners:N #1
            }
      }
  }
\cs_new_protected_nopar:Npn \hcoffin_set_end: { }
\cs_generate_variant:Nn \hcoffin_set:Nw { c }
%    \end{macrocode}
%
% \end{macro}\end{macro}
%
% \begin{macro}{\vcoffin_set:Nnw, \vcoffin_set:cnw}
% \begin{macro}{\vcoffin_set_end:}
%   The same for vertical coffins.
%    \begin{macrocode}
\cs_new_protected:Npn \vcoffin_set:Nnw #1#2
  {
    \@@_if_exist:NT #1
      {
        \vbox_set:Nw #1
          \dim_set:Nn \tex_hsize:D {#2}
%<*package>
            \dim_set_eq:NN \linewidth   \tex_hsize:D
            \dim_set_eq:NN \columnwidth \tex_hsize:D
%</package>
          \color_group_begin: \color_ensure_current:
          \cs_set_protected:Npn \vcoffin_set_end:
            {
                \color_group_end:
              \vbox_set_end:
              \@@_reset_structure:N #1
              \@@_update_poles:N #1
              \@@_update_corners:N #1
              \vbox_set_top:Nn \l_@@_internal_box { \vbox_unpack:N #1 }
              \@@_set_pole:Nnx #1 { T }
                {
                  { 0 pt }
                  {
                    \dim_eval:n
                      { \box_ht:N #1 - \box_ht:N \l_@@_internal_box }
                  }
                  { 1000 pt }
                  { 0 pt }
                }
              \box_clear:N \l_@@_internal_box
            }
      }
  }
\cs_new_protected_nopar:Npn \vcoffin_set_end: { }
\cs_generate_variant:Nn \vcoffin_set:Nnw { c }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}
%   {
%     \coffin_set_eq:NN, \coffin_set_eq:Nc,
%     \coffin_set_eq:cN, \coffin_set_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
        \@@_set_eq_structure:NN #1 #2
      }
  }
\cs_generate_variant:Nn \coffin_set_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.
%    \begin{macrocode}
\coffin_new:N \c_empty_coffin
\hbox_set:Nn  \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}
%   The usual scratch space.
%    \begin{macrocode}
\coffin_new:N \l_tmpa_coffin
\coffin_new:N \l_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
      { l_@@_poles_ \__int_value:w #1 _prop } {#2} #3
      {
        \__msg_kernel_error:nnxx { kernel } { 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}{\@@_reset_structure:N}
%   Resetting the structure is a simple copy job.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_reset_structure:N #1
  {
    \prop_set_eq:cN { l_@@_corners_ \__int_value:w #1 _prop }
      \c_@@_corners_prop
    \prop_set_eq:cN { l_@@_poles_ \__int_value:w #1 _prop }
      \c_@@_poles_prop
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_set_eq_structure:NN,\@@_gset_eq_structure:NN}
% Setting coffin structures equal simply means copying the property
% list.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_set_eq_structure:NN #1#2
  {
    \prop_set_eq:cc { l_@@_corners_ \__int_value:w #1 _prop }
      { l_@@_corners_ \__int_value:w #2 _prop }
    \prop_set_eq:cc { l_@@_poles_ \__int_value:w #1 _prop }
      { l_@@_poles_ \__int_value:w #2 _prop }
  }
\cs_new_protected:Npn \@@_gset_eq_structure:NN #1#2
  {
    \prop_gset_eq:cc { l_@@_corners_ \__int_value:w #1 _prop }
      { l_@@_corners_ \__int_value:w #2 _prop }
    \prop_gset_eq:cc { l_@@_poles_ \__int_value:w #1 _prop }
      { l_@@_poles_ \__int_value:w #2 _prop }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {\coffin_set_horizontal_pole:Nnn, \coffin_set_horizontal_pole:cnn}
% \begin{macro}{\coffin_set_vertical_pole:Nnn,\coffin_set_vertical_pole:cnn}
% \begin{macro}{\@@_set_pole:Nnn, \@@_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:Npn \coffin_set_horizontal_pole:Nnn #1#2#3
  {
    \@@_if_exist:NT #1
      {
        \@@_set_pole:Nnx #1 {#2}
          {
            { 0 pt } { \dim_eval:n {#3} }
            { 1000 pt } { 0 pt }
          }
      }
  }
\cs_new_protected:Npn \coffin_set_vertical_pole:Nnn #1#2#3
  {
    \@@_if_exist:NT #1
      {
        \@@_set_pole:Nnx #1 {#2}
          {
            { \dim_eval:n {#3} } { 0 pt }
            { 0 pt } { 1000 pt }
          }
      }
  }
\cs_new_protected:Npn \@@_set_pole:Nnn #1#2#3
  { \prop_put:cnn { l_@@_poles_ \__int_value:w #1 _prop } {#2} {#3} }
\cs_generate_variant:Nn \coffin_set_horizontal_pole:Nnn { c }
\cs_generate_variant:Nn \coffin_set_vertical_pole:Nnn { c }
\cs_generate_variant:Nn \@@_set_pole:Nnn { Nnx }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@@_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:Npn \@@_update_corners:N #1
  {
    \prop_put:cnx { l_@@_corners_ \__int_value:w #1 _prop } { tl }
      { { 0 pt } { \dim_use:N \box_ht:N #1 } }
    \prop_put:cnx { l_@@_corners_ \__int_value:w #1 _prop } { tr }
      { { \dim_use:N \box_wd:N #1 } { \dim_use:N \box_ht:N #1 } }
    \prop_put:cnx { l_@@_corners_ \__int_value:w #1 _prop } { bl }
      { { 0 pt } { \dim_eval:n { - \box_dp:N #1 } } }
    \prop_put:cnx { l_@@_corners_ \__int_value:w #1 _prop } { br }
      { { \dim_use:N \box_wd:N #1 } { \dim_eval:n { - \box_dp:N #1 } } }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_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:Npn \@@_update_poles:N #1
  {
    \prop_put:cnx { l_@@_poles_ \__int_value:w #1 _prop } { hc }
      {
        { \dim_eval:n { 0.5 \box_wd:N #1 } }
        { 0 pt } { 0 pt } { 1000 pt }
      }
    \prop_put:cnx { l_@@_poles_ \__int_value:w #1 _prop } { r }
      {
        { \dim_use:N \box_wd:N #1 }
        { 0 pt } { 0 pt } { 1000 pt }
      }
    \prop_put:cnx { l_@@_poles_ \__int_value:w #1 _prop } { vc }
      {
        { 0 pt }
        { \dim_eval:n { ( \box_ht:N #1 - \box_dp:N #1 ) / 2 } }
        { 1000 pt }
        { 0 pt }
      }
    \prop_put:cnx { l_@@_poles_ \__int_value:w #1 _prop } { t }
      {
        { 0 pt }
        { \dim_use:N \box_ht:N #1 }
        { 1000 pt }
        { 0 pt }
      }
    \prop_put:cnx { l_@@_poles_ \__int_value:w #1 _prop } { b }
      {
        { 0 pt }
        { \dim_eval:n { - \box_dp:N #1 } }
        { 1000 pt }
        { 0 pt }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Coffins: calculation of pole intersections}
%
% \begin{macro}{\@@_calculate_intersection:Nnn}
% \begin{macro}[aux]{\@@_calculate_intersection:nnnnnnnn}
% \begin{macro}[aux]{\@@_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: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_kernel_error:nn { kernel } { 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'$ will be 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 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_@@_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 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_@@_y_dim {#6} }
              {
                \@@_calculate_intersection_aux:nnnnnN
                  {#1} {#5} {#6} {#7} {#8} \l_@@_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_@@_y_dim {#2}
            \dim_compare:nNnTF {#8} = { \c_zero_dim }
              { \bool_set_true:N \l_@@_error_bool }
              {
                \dim_compare:nNnTF {#7} = \c_zero_dim
                  { \dim_set:Nn \l_@@_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}
                  {
                    \@@_calculate_intersection_aux:nnnnnN
                      {#2} {#6} {#5} {#8} {#7} \l_@@_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_@@_x_dim {#5}
                \@@_calculate_intersection_aux:nnnnnN
                  {#5} {#1} {#2} {#3} {#4} \l_@@_y_dim
              }
              {
                \dim_compare:nNnTF {#8} = \c_zero_dim
                  {
                    \dim_set:Nn \l_@@_y_dim {#6}
                    \@@_calculate_intersection_aux:nnnnnN
                      {#6} {#2} {#1} {#4} {#3} \l_@@_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:Nn \l_@@_slope_x_fp
                      { \dim_to_fp:n {#4} / \dim_to_fp:n {#3} }
                    \fp_set:Nn \l_@@_slope_y_fp
                      { \dim_to_fp:n {#8} / \dim_to_fp:n {#7} }
                    \fp_compare:nNnTF
                      \l_@@_slope_x_fp = \l_@@_slope_y_fp
                      { \bool_set_true:N \l_@@_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}
                      {
                        \dim_set:Nn \l_@@_x_dim
                          {
                            \fp_to_dim:n
                              {
                                (
                                      \dim_to_fp:n {#1} * \l_@@_slope_x_fp
                                  - ( \dim_to_fp:n {#5} * \l_@@_slope_y_fp )
                                  -   \dim_to_fp:n {#2}
                                  +   \dim_to_fp:n {#6}
                                )
                                /
                                ( \l_@@_slope_x_fp - \l_@@_slope_y_fp )
                            }
                          }
                        \@@_calculate_intersection_aux:nnnnnN
                          { \l_@@_x_dim }
                          {#5} {#6} {#8} {#7} \l_@@_y_dim
                      }
                  }
              }
          }
      }
  }
%    \end{macrocode}
%   The formula for finding the intersection point is in most cases the
%   same. The formula here is
%   \[
%     \#6 = \#4 \cdot \left( \frac { \#1 - \#2 } { \#5 } \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:Npn \@@_calculate_intersection_aux:nnnnnN
    #1#2#3#4#5#6
  {
    \dim_set:Nn #6
      {
        \fp_to_dim:n
          {
            \dim_to_fp:n {#4} *
            ( \dim_to_fp:n {#1} - \dim_to_fp:n {#2} ) /
            \dim_to_fp:n {#5}
            + \dim_to_fp:n {#3}
          }
      }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsection{Aligning and typesetting of coffins}
%
% \begin{macro}
%   {
%     \coffin_join:NnnNnnnn, \coffin_join:cnnNnnnn,
%     \coffin_join:Nnncnnnn , \coffin_join:cnncnnnn
%   }
%   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:Npn \coffin_join:NnnNnnnn #1#2#3#4#5#6#7#8
  {
    \@@_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 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_@@_aligned_coffin
      {
        \dim_compare:nNnT { \l_@@_offset_x_dim } < \c_zero_dim
          { \tex_kern:D -\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
          { \tex_kern:D -\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
      { l_@@_corners_ \__int_value:w \l_@@_aligned_coffin _ prop }
    \@@_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
%   will then depend 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 } { 0 pt }
        \@@_offset_poles:Nnn #4 { 0 pt } { \l_@@_offset_y_dim }
        \@@_offset_corners:Nnn #1 { -\l_@@_offset_x_dim } { 0 pt }
        \@@_offset_corners:Nnn #4 { 0 pt } { \l_@@_offset_y_dim }
      }
      {
        \@@_offset_poles:Nnn #1 { 0 pt } { 0 pt }
        \@@_offset_poles:Nnn #4
          { \l_@@_offset_x_dim } { \l_@@_offset_y_dim }
        \@@_offset_corners:Nnn #1 { 0 pt } { 0 pt }
        \@@_offset_corners:Nnn #4
          { \l_@@_offset_x_dim } { \l_@@_offset_y_dim }
      }
    \@@_update_vertical_poles:NNN #1 #4 \l_@@_aligned_coffin
    \coffin_set_eq:NN #1 \l_@@_aligned_coffin
  }
\cs_generate_variant:Nn \coffin_join:NnnNnnnn { c , Nnnc , cnnc }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \coffin_attach:NnnNnnnn, \coffin_attach:cnnNnnnn,
%     \coffin_attach:Nnncnnnn, \coffin_attach:cnncnnnn
%   }
% \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:Npn \coffin_attach: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 }
    \@@_reset_structure:N \l_@@_aligned_coffin
    \prop_set_eq:cc
      { l_@@_corners_ \__int_value:w \l_@@_aligned_coffin _prop }
      { l_@@_corners_ \__int_value:w #1 _prop }
    \@@_update_poles:N  \l_@@_aligned_coffin
    \@@_offset_poles:Nnn #1 { 0 pt } { 0 pt }
    \@@_offset_poles:Nnn #4
      { \l_@@_offset_x_dim } { \l_@@_offset_y_dim }
    \@@_update_vertical_poles:NNN #1 #4 \l_@@_aligned_coffin
    \coffin_set_eq:NN #1 \l_@@_aligned_coffin
  }
\cs_new_protected:Npn \coffin_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
  }
\cs_generate_variant:Nn \coffin_attach:NnnNnnnn { c , Nnnc , cnnc }
%    \end{macrocode}
% \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
%   will depend 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
        \tex_kern:D -\box_wd:N #1
        \tex_kern:D \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}[aux]{\@@_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:Npn \@@_offset_poles:Nnn #1#2#3
  {
    \prop_map_inline:cn { l_@@_poles_ \__int_value:w #1 _prop }
      { \@@_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:Nnx \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}[aux]{\@@_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 { l_@@_corners_ \__int_value:w #1 _prop }
      { \@@_offset_corner:Nnnnn #1 {##1} ##2 {#2} {#3} }
  }
\cs_new_protected:Npn \@@_offset_corner:Nnnnn #1#2#3#4#5#6
  {
    \prop_put:cnx
      { l_@@_corners_ \__int_value:w \l_@@_aligned_coffin _prop }
      { #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}[aux]{\@@_update_T:nnnnnnnnN}
% \begin{macro}[aux]{\@@_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: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:Nnx #9 { T }
          { { 0 pt } {#6} { 1000 pt } { 0 pt } }
      }
      {
        \@@_set_pole:Nnx #9 { T }
          { { 0 pt } {#2} { 1000 pt } { 0 pt } }
      }
  }
\cs_new_protected:Npn \@@_update_B:nnnnnnnnN #1#2#3#4#5#6#7#8#9
  {
    \dim_compare:nNnTF {#2} < {#6}
      {
        \@@_set_pole:Nnx #9 { B }
          { { 0 pt } {#2}  { 1000 pt } { 0 pt } }
      }
      {
        \@@_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, \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
  {
    \hbox_unpack:N \c_empty_box
    \@@_align:NnnNnnnnN \c_empty_coffin { H } { l }
      #1 {#2} {#3} {#4} {#5} \l_@@_aligned_coffin
    \box_use: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 { 2 pt }
%    \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
%<*initex>
\tl_set:Nn \l_@@_display_font_tl { } % TODO
%</initex>
%<*package>
\tl_set:Nn \l_@@_display_font_tl { \sffamily \tiny }
%</package>
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\coffin_mark_handle:Nnnn, \coffin_mark_handle:cnnn}
% \begin{macro}[aux]{\@@_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
      {
%<*initex>
        \hbox:n { \tex_vrule:D width 1 pt height 1 pt \scan_stop: } % TODO
%</initex>
%<*package>
        \color {#4}
        \rule { 1 pt } { 1 pt }
%</package>
      }
    \coffin_attach_mark:NnnNnnnn #1 {#2} {#3}
      \l_@@_display_pole_coffin { hc } { vc } { 0 pt } { 0 pt }
    \hcoffin_set:Nn \l_@@_display_coord_coffin
      {
%<*initex>
        % TODO
%</initex>
%<*package>
        \color {#4}
%</package>
        \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
          {
            \coffin_attach_mark:NnnNnnnn #1 {#2} {#3}
              \l_@@_display_coord_coffin { l } { vc }
                { 1 pt } { 0 pt }
          }
          {
            \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
  {
    \coffin_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}[aux]{\@@_display_handles_aux:nnnnnn}
% \begin{macro}[aux]{\@@_display_handles_aux:nnnn}
% \begin{macro}[aux]{\@@_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
      {
%<*initex>
        \hbox:n { \tex_vrule:D width 1 pt height 1 pt \scan_stop: } % TODO
%</initex>
%<*package>
        \color {#2}
        \rule { 1 pt } { 1 pt }
%</package>
      }
    \prop_set_eq:Nc \l_@@_display_poles_prop
      { l_@@_poles_ \__int_value:w #1 _prop }
    \@@_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: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 }
              { 0 pt } { 0 pt }
            \hcoffin_set:Nn \l_@@_display_coord_coffin
              {
%<*initex>
                % TODO
%</initex>
%<*package>
                \color {#6}
%</package>
                \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 }
                      { 1 pt } { 0 pt }
                  }
                  {
                    \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
        \tex_kern:D -\box_wd:N \l_@@_display_coffin
        \tex_kern:D \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}
%   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 #1
  {
    \@@_if_exist:NT #1
      {
        \__msg_show_variable:Nnn #1 { coffins }
          {
            \prop_map_function:cN
              { l_@@_poles_ \__int_value:w #1 _prop }
              \__msg_show_item_unbraced:nn
          }
      }
  }
\cs_generate_variant:Nn \coffin_show_structure:N { c }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Messages}
%
%    \begin{macrocode}
\__msg_kernel_new:nnnn { kernel } { no-pole-intersection }
  { No~intersection~between~coffin~poles. }
  {
    \c__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 { kernel } { unknown-coffin }
  { Unknown~coffin~'#1'. }
  { The~coffin~'#1'~was~never~defined. }
\__msg_kernel_new:nnnn { kernel } { unknown-coffin-pole }
  { Pole~'#1'~unknown~for~coffin~'#2'. }
  {
    \c__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.
  }
\__msg_kernel_new:nnn { kernel } { show-coffins }
  {
    Size~of~coffin~\token_to_str:N #1 : \\
    > ~ ht~=~\dim_use:N \box_ht:N #1 \\
    > ~ dp~=~\dim_use:N \box_dp:N #1 \\
    > ~ wd~=~\dim_use:N \box_wd:N #1 \\
    Poles~of~coffin~\token_to_str:N #1 :
  }
%    \end{macrocode}
%
%    \begin{macrocode}
%</initex|package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex