% \iffalse
%% File xcoffins.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}
\GetIdInfo$Id: xcoffins.dtx 2097 2010-12-05 21:59:21Z mittelba $
          {Coffins}
%</driver|package>
%<*driver>
%\fi
\ProvidesFile{\filename.\filenameext}
  [\filedate\space v\fileversion\space\filedescription]
%\iffalse
\documentclass{l3doc}
\usepackage{\jobname} % This file uses coffins!
\NewCoffin \ExampleCoffin
\NewCoffin \SmallCoffin
\NewCoffin \OutputCoffin
\NewCoffin \RedCoffin
\NewCoffin \BlueCoffin
\NewCoffin \GreenCoffin
\NewCoffin \YellowCoffin
\NewCoffin \OrangeCoffin
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
%\fi
%
%\title{^^A
%  The \LaTeX3 kernel: design-level 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.
% This module contains the design-level code to implement this scheme.
%\end{abstract}
%
%\tableofcontents
%
%\begin{documentation}
%
%\section{Introduction: the coffin concept}
%
% In \LaTeX3 terminology, a `coffin' is a box containing
% typeset material. Along with the box itself, the coffin structure
% includes information on the size and shape of the box, which makes
% it possible to align two or more coffins easily. This is achieved
% by providing a series of `poles' for each coffin. These
% are horizontal and vertical lines through the coffin at defined
% positions, for example the top or horizontal centre. The points
% where these poles intersect are called `handles'. Two
% coffins can then be aligned by describing the relationship between
% a handle on one coffin with a handle on the second. In words, an 
% example might then read
%\begin{quote}
%  Align the top-left handle of coffin A with the bottom-right
%  handle of coffin B.
%\end{quote}
%
% The locations of coffin handles are much easier to understand
% visually. Figure~\ref{fgr:handles} shows the standard handle 
% positions for a coffin typeset in horizontal mode (left) and in 
% vertical mode (right). Notice that the later case results in a greater
% number of handles being available. As illustrated, each handle
% results from the intersection of two poles. For example, the centre
% of the coffin is marked `(hc,vc), \emph{i.e.}~it is the
% point of intersection of the horizontal centre pole with the 
% vertical centre pole. New handles are generated automatically when
% poles are added to a coffin: handles are `dynamic'
% entities.
%\begin{figure}
%  \hfil
%  \begin{minipage}{0.4\textwidth}
%    \SetHorizontalCoffin\ExampleCoffin 
%      {\color{black!10!white}\rule{1 in}{1 in}}
%    \DisplayCoffinHandles\ExampleCoffin{blue}
%  \end{minipage}
%  \hfil
%  \begin{minipage}{0.4\textwidth}
%    \SetVerticalCoffin\ExampleCoffin{1 in}
%      {\color{black!10!white}\rule{1 in}{1 in}}
%    \DisplayCoffinHandles\ExampleCoffin{blue}
%  \end{minipage}
%  \hfil
%  \caption{Standard coffin handles: left, horizontal coffin; right,
%    vertical coffin}
%  \label{fgr:handles}  
%\end{figure}
% 
%\section{Creating and setting coffins}
%
% Before any alignment can take place, coffins must be created and
% their contents must be created. All coffin operations are local
% to the current \TeX\ group with the exception of coffin creation.
% Coffins are also `colour safe': in contrast to the code-level
% \cs{box_\ldots} functions there is no need to add additional grouping
% to coffins when dealing with colour.
%
%\begin{function}{ \NewCoffin }
%  \begin{syntax}
%    \cs{NewCoffin} \meta{coffin}
%  \end{syntax}
%  Before a \meta{coffin} can be used, it must be allocated using 
%  \cs{NewCoffin}. The name of the \meta{coffin} should be a
%  control sequence (starting with the escape character, usually
%  "\"), for example
%  \begin{verbatim}
%    \NewCoffin\MyCoffin
%  \end{verbatim}
%  Coffins are allocated globally, and an error will be raised if the
%  name of the \meta{coffin} is not globally-unique.
%\end{function}
%
%\begin{function}{ \SetHorizontalCoffin }
%  \begin{syntax}
%    \cs{SetHorizontalCoffin} \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}{ \SetVerticalCoffin }
%  \begin{syntax}
%    \cs{SetVerticalCoffin} \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}
%
%\section{Controlling coffin poles}
%
% A number of standard poles are automatically generated when the coffin
% is set or an alignment takes place. The standard poles for all coffins
% are:
%\begin{itemize}[font = \ttfamily]
%  \item[l] a pole running along the left-hand edge of the bounding
%    box of the coffin;
%  \item[hc] a pole running vertically through the centre of the coffin
%    half-way between the left- and right-hand edges of the bounding
%      box (\emph{i.e}~the `horizontal centre');
%  \item[r] a pole running along the right-hand edge of the bounding
%    box of the coffin;
%  \item[b] a pole running along the bottom edge of the bounding
%    box of the coffin;
%  \item[vc] a pole running horizontally through the centre of the 
%    coffin half-way between the bottom and top edges of the bounding
%      box (\emph{i.e}~the `vertical centre');
%  \item[t] a pole running along the top edge of the bounding
%    box of the coffin;
%  \item[H] a pole running along the baseline of the typeset material
%    contained in the coffin.
%\end{itemize}
% In addition, coffins containing vertical-mode material also 
% feature poles which reflect the richer nature of these systems:
%\begin{itemize}
%  \item[B] a pole running along the baseline of the material at the
%    bottom of the coffin.
%  \item[T] a pole running along the baseline of the material at the top
%    of the coffin.
%\end{itemize}
%
%\begin{function}{ \SetHorizontalPole }
%  \begin{syntax}
%    \cs{SetHorizontalPole} \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}. For example, to create a pole running 
%  horizontally through the coffin at one third of the distance from 
%  the base of the coffin to the top, the appropriate instruction would
%  be \begin{verbatim}
%    \SetHorizontalPole \MyCoffin {height/3} {\TotalHeight/3}
%  \end{verbatim}
%  Note that poles which run \emph{horizontally} are described in terms
%  of their \emph{vertical} location in the coffin. Also notice that
%  the total height of the coffin is described by the sum of 
%  \cs{Height} and \cs{Depth}: these are both measured from the
%  horizontal baseline of the material in the coffin.
%\end{function}
%
%\begin{function}{ \SetVerticalPole }
%  \begin{syntax}
%    \cs{SetVerticalPole} \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}. For example, to create a pole running vertically
%  through the coffin at one third of the distance from the left-hand 
%  edge, the appropriate instruction would be
%  \begin{verbatim}
%    \SetVerticalPole \MyCoffin {width/3} {\Width/3}
%  \end{verbatim}
%  Note that poles which run \emph{vertically} are described in terms
%  of their \emph{horizontal} location in the coffin.
%\end{function}
%
%\begin{function}{ \TotalHeight }
%  \begin{syntax}
%    \cs{TotalHeight}
%  \end{syntax}
%  Within the \meta{offset} argument of \cs{SetHorizontalPole} and
%  \cs{SetVerticalPole}, \cs{TotalHeight} will give the distance from 
%  the base to the top of the bounding box of the relevant coffin.
%\end{function}
%
%\begin{function}{ \Height }
%  \begin{syntax}
%    \cs{Height}
%  \end{syntax}
%  Within the \meta{offset} argument of \cs{SetHorizontalPole} and
%  \cs{SetVerticalPole}, \cs{Height} will give the distance from the
%  baseline to the top of the bounding box of the relevant coffin.
%\end{function}
%
%\begin{function}{ \Depth }
%  \begin{syntax}
%    \cs{Depth}
%  \end{syntax}
%  Within the \meta{offset} argument of \cs{SetHorizontalPole} and
%  \cs{SetVerticalPole}, \cs{Depth} will give the distance from the
%  baseline to the bottom of the bounding box of the relevant coffin.
%\end{function}
%
%\begin{function}{ \Width }
%  \begin{syntax}
%    \cs{Width}
%  \end{syntax}
%  Within the \meta{offset} argument of \cs{SetHorizontalPole} and
%  \cs{SetVerticalPole}, \cs{Width} will give the distance from the
%  right edge to the left edge of the bounding box of the relevant
%  coffin.
%\end{function}
%
%\section{Rotating coffins}
%
%\begin{function}{ \RotateCoffin }
%  \begin{syntax}
%    \cs{RotateCoffin} \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.
%  
%  The effect of rotation on a coffin is illustrated in 
%  Figure~\ref{fgr:rotation}. As is shown, the coffin handles will
%  remain correctly positioned relative to the content of the coffin.
%  The `top' of a rotated coffin may of course no longer be the
%  edge closest to the top of the physical page.
%  \begin{figure}
%    \hfil
%    \SetHorizontalCoffin\ExampleCoffin 
%      {^^A
%        \color{black!10!white}\rule{0.5 in}{1 in}^^A
%        \color{black!20!white}\rule{0.5 in}{1 in}^^A
%      }
%    \begin{minipage}{0.4\textwidth}
%      \DisplayCoffinHandles\ExampleCoffin{blue}
%    \end{minipage}
%    \hfil
%    \begin{minipage}{0.4\textwidth}
%      \RotateCoffin\ExampleCoffin{45}
%      \DisplayCoffinHandles\ExampleCoffin{blue}
%    \end{minipage}
%    \hfil
%    \caption{Coffin rotation: left, unrotated; right, rotated by
%      \( 45 \)\textdegree.}
%    \label{fgr:rotation}  
%  \end{figure}
%\end{function}
%
%\section{Resizing coffins}
%
%\begin{function}{ \ResizeCoffin }
%  \begin{syntax}
%    \cs{RotateCoffin} \meta{coffin} \Arg{width} \Arg{total-height}
%  \end{syntax}
%  Resized the \meta{coffin} to \meta{width} and \meta{total-height},
%  both of which should be given as dimension expressions. These 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}{ \ScaleCoffin }
%  \begin{syntax}
%    \cs{ScaleCoffin} \meta{coffin} \Arg{x-scale} \Arg{y-scale}
%  \end{syntax}
%  Scales the \meta{coffin} by a factors \meta{x-scale} and 
%  \meta{y-scale} in the horizontal and vertical directions, 
%  respectively. The two scale factors should be given as real numbers.
%\end{function}
%
% \cs{ResizeCoffin} and \cs{ScaleCoffin} can be used interchangeably:
% whether scale factors or absolute values are the best form for the
% resizing will depend upon the context (Figure~\ref{fgr:resizing}).
%\begin{figure}
%  \hfil
%  \SetHorizontalCoffin\ExampleCoffin 
%    {^^A
%      \color{black!10!white}\rule{0.5 in}{1 in}^^A
%      \color{black!20!white}\rule{0.5 in}{1 in}^^A
%    }
%  \begin{minipage}{0.4\textwidth}
%    \ResizeCoffin \ExampleCoffin {4 cm} {3 cm}
%    \DisplayCoffinHandles \ExampleCoffin {blue}
%  \end{minipage}
%  \hfil
%  \begin{minipage}{0.4\textwidth}
%    \ScaleCoffin \ExampleCoffin {2.0} {0.5}
%    \DisplayCoffinHandles \ExampleCoffin {blue}
%  \end{minipage}
%  \hfil
%  \caption{Coffin resizing: left, resized to exactly \( 4 \)\,cm by
%  \( 6 \)\,cm; right, scaled a factors of \( 2 \) and \( 0.5 \) in
%  \( x \) and \( y \), respectively (example coffin as in 
%  Figure~\ref{fgr:rotation}).}
%  \label{fgr:resizing}  
%\end{figure}
%
%\section{Joining coffins}
%
% The key operation for coffins is joining coffins to each other. This
% is always carried out such that the first coffin is the 
% `parent', and is updated by the alignment. The second
% `child' coffin is not altered by the alignment process.
% 
%\begin{function}{ \JoinCoffins }
%  \begin{syntax}
%    \cs{JoinCoffins} *
%    ~~\meta{coffin1} [ \meta{coffin1-pole1} , \meta{coffin1-pole2} ] 
%    ~~\meta{coffin2} [ \meta{coffin2-pole1} , \meta{coffin2-pole2} ]
%    ~~( \meta{x-offset} , \meta{y-offset} ) 
%  \end{syntax}
%  Joining of two coffins is carried out by the \cs{JoinCoffins} 
%  function, which takes two mandatory arguments: the `parent'
%  \meta{coffin1} and the `child' \meta{coffin2}. All of the
%  other arguments shown are optional.
%  
%  The standard \cs{JoinCoffins} functions joins \meta{coffin2} to
%  \meta{coffin1} such that the bounding box of \meta{coffin1} after the
%  process will expand. The new bounding box will be the smallest 
%  rectangle covering the bounding boxes of the two input coffins. 
%  When the starred variant of \cs{JoinCoffins} is used, the bounding
%  box of \meta{coffin1} is not altered, \emph{i.e.}~\meta{coffin2} may
%  protrude outside of the bounding box of the updated \meta{coffin1}.
%  The difference between the two forms of alignment is best illustrated
%  using a visual example. In Figure~\ref{fgr:alignment}, the two
%  processes are contrasted. In both cases, the small red coffin has been
%  aligned with the large grey coffin. In the left-hand illustration, 
%  the \cs{JoinCoffins} function was used, resulting in an expanded
%  bounding box. In contrast, on the right \cs{AttachCoffin} was used,
%  meaning that the bounding box does not include the area of the
%  smaller coffin. 
%  \begin{figure}
%    \fboxsep 0 pt\relax
%    \SetHorizontalCoffin\ExampleCoffin 
%      {\color{black!20!white}\rule{1 in}{1 in}}
%    \SetHorizontalCoffin \SmallCoffin 
%      {\color{red!20!white}\rule{0.1 in}{0.1 in}}
%    \hfil
%    \begin{minipage}{0.4\textwidth}
%      \centering
%      \JoinCoffins\ExampleCoffin[vc,r]\SmallCoffin[vc,l]
%      \fbox{\TypesetCoffin\ExampleCoffin}
%    \end{minipage}
%    \hfil
%    \begin{minipage}{0.4\textwidth}
%      \centering
%      \JoinCoffins*\ExampleCoffin[vc,r]\SmallCoffin[vc,l]
%      \fbox{\TypesetCoffin\ExampleCoffin}%
%    \end{minipage}
%    \hfil
%    \caption{Contrast between \cs{JoinCoffins} (left) and 
%      \cs{JoinCoffins*} (right); the bounding box of the coffin is show
%      in black.}
%    \label{fgr:alignment}  
%  \end{figure}
%  
%  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}. If the two
%  \meta{poles} are not specified, \cs{JoinCoffins} will use the
%  default value "(H,l)", \emph{i.e.}~the reference point used by \TeX\
%  for the underlying box. Once the two \meta{handles} have been
%  located, \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}. This
%  \meta{offset} is an optional argument, and if it is not given then
%  "(0 pt, 0 pt)" is used.
%\end{function}
%
% Notice that when \cs{JoinCoffins} is used the new bounding box is
% the smallest rectangle containing the bounding boxes of the two input 
% coffins. As a result, it will include additional white space unless
% one coffin entirely overlaps the other (Figure~\ref{fgr:bounding}, 
% left). Rotation of coffins will take account of the extent of the
% material after rotation when re-calculating the bounding box. This
% means that no \emph{unnecessary} white space will be added on 
% rotation (Figure~\ref{fgr:bounding}, right).
%\begin{figure}
%  \fboxsep 0 pt\relax
%  \SetHorizontalCoffin\ExampleCoffin 
%    {\color{black!20!white}\rule{1 in}{1 in}}
%  \SetHorizontalCoffin\SmallCoffin 
%    {\color{red!20!white}\rule{0.1 in}{0.1 in}}
%  \JoinCoffins\ExampleCoffin[vc,r]\SmallCoffin[vc,l]
%  \hfil
%  \begin{minipage}{0.4\textwidth}
%    \centering
%    \fbox{\TypesetCoffin\ExampleCoffin}
%  \end{minipage}
%  \hfil
%  \begin{minipage}{0.4\textwidth}
%    \centering
%    \RotateCoffin\ExampleCoffin{135}
%    \fbox{\TypesetCoffin\ExampleCoffin}
%  \end{minipage}
%  \hfil
%  \caption{The effect of rotation of a joined coffin: the black line
%    shows the coffin bounding box.}
%  \label{fgr:bounding}  
%\end{figure}
%
% As part of the joining procedure, the poles of the two input coffins
% are preserved within the structure of the updated coffin. In this way
% it is possible to carry out complex alignment procedures. The poles of
% a coffin after alignment may therefore be divided into three groups:
%\begin{enumerate}
%  \item The `native' poles of the updated coffin, such as
%    \texttt{l}, \texttt{r}, \texttt{hc}, \emph{etc}.
%  \item Poles derived from \meta{coffin1}, such as 
%    \texttt{\meta{coffin1}-l},  \texttt{\meta{coffin1}-r},
%     \texttt{\meta{coffin1}-hc}, \emph{etc.}
%  \item Poles derived from \meta{coffin2}, such as 
%    \texttt{\meta{coffin2}-l},  \texttt{\meta{coffin2}-r},
%     \texttt{\meta{coffin2}-hc}, \emph{etc.}
%\end{enumerate}
% 
% Applying this ability allows a series of joining operations to
% take place, as illustrated in Figure~\ref{fgr:nested}. In this
% example, the scheme used for alignment was as follows:
%\begin{verbatim}
%  \SetHorizontalCoffin\OutputCoffin{}
%  \SetHorizontalCoffin\RedCoffin 
%    {\color{red!20!white}\rule{0.2 in}{0.2 in}}
%  \JoinCoffins\OutputCoffin[vc,hc]\RedCoffin[vc,hc]
%  \SetHorizontalCoffin\BlueCoffin 
%    {\color{blue!20!white}\rule{0.2 in}{0.2 in}}
%  \JoinCoffins\OutputCoffin[\RedCoffin-vc,\RedCoffin-hc]
%    \BlueCoffin[b,l]
%  \SetHorizontalCoffin\GreenCoffin 
%    {\color{green!20!white}\rule{0.2 in}{0.2 in}}
%  \JoinCoffins\OutputCoffin[\BlueCoffin-vc,\BlueCoffin-hc]
%    \GreenCoffin[b,l]
%  \SetHorizontalCoffin\YellowCoffin 
%    {\color{yellow!20!white}\rule{0.2 in}{0.2 in}}
%  \JoinCoffins\OutputCoffin[\GreenCoffin-vc,\GreenCoffin-hc]
%    \YellowCoffin[b,l]
%  \SetHorizontalCoffin \OrangeCoffin 
%    {\color{orange!20!white}\rule{0.2 in}{0.2 in}}
%  \JoinCoffins\OutputCoffin[\BlueCoffin-t,\BlueCoffin-l]
%    \OrangeCoffin[b,r]
%  \TypesetCoffin\OutputCoffin
%\end{verbatim}
% This process begins by setting up \cs{OutputCoffin} to hold the joined
% output. Each join then takes place placing the new addition relative
% to the previous one. As each coffin joined has a unique name it is
% possible to align relative to each one of the component parts of the
% assembly. This is illustrated by the addition of the final 
% \cs{OrangeCoffin} based on the earlier placement of the
% \cs{BlueCoffin}.
%\begin{figure}
%  \centering
%  \SetHorizontalCoffin\OutputCoffin{}
%  \SetHorizontalCoffin\RedCoffin 
%    {\color{red!20!white}\rule{0.2 in}{0.2 in}}
%  \JoinCoffins\OutputCoffin[vc,hc]\RedCoffin[vc,hc]
%  \SetHorizontalCoffin\BlueCoffin 
%    {\color{blue!20!white}\rule{0.2 in}{0.2 in}}
%  \JoinCoffins\OutputCoffin[\RedCoffin-vc,\RedCoffin-hc]
%    \BlueCoffin[b,l]
%  \SetHorizontalCoffin\GreenCoffin 
%    {\color{green!20!white}\rule{0.2 in}{0.2 in}}
%  \JoinCoffins\OutputCoffin[\BlueCoffin-vc,\BlueCoffin-hc]
%    \GreenCoffin[b,l]
%  \SetHorizontalCoffin\YellowCoffin 
%    {\color{yellow!20!white}\rule{0.2 in}{0.2 in}}
%  \JoinCoffins\OutputCoffin[\GreenCoffin-vc,\GreenCoffin-hc]
%    \YellowCoffin[b,l]
%  \SetHorizontalCoffin \OrangeCoffin 
%    {\color{orange!20!white}\rule{0.2 in}{0.2 in}}
%  \JoinCoffins\OutputCoffin[\BlueCoffin-t,\BlueCoffin-l]
%    \OrangeCoffin[b,r]
%  \TypesetCoffin\OutputCoffin
%  \caption{Aligning coffins using poles from previous operations.}
%  \label{fgr:nested}  
%\end{figure}
%
%\section{Typesetting coffins}
%
%\begin{function}{ \TypesetCoffin }
%  \begin{syntax}
%    \cs{TypesetCoffin} 
%    ~~\meta{coffin} [ \meta{pole1} , \meta{pole2} ]
%    ~~( \meta{x-offset} , \meta{y-offset} ) 
%  \end{syntax}
%  Typesetting is carried out by first calculating \meta{handle}, the
%  point of intersection of \meta{pole1} and \meta{pole2}. This is an
%  optional argument, and if not given then "(H, l)", the \TeX\
%  reference point of the underlying box, is used. 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}. This \meta{offset} is
%  optional, and if not given "(0 pt, 0 pt)" is used. Typesetting a
%  coffin is therefore analogous to carrying out an alignment where the
%  `parent' coffin is the current insertion point.
%\end{function}
%
%\section{Diagnostic functions}
%
% Diagnostic data for following the coffin-building process is 
% available both graphically and at the terminal. This reflects the
% fact that coffins are visual constructs.
%
%\begin{function}{ \DisplayCoffinHandles }
%  \begin{syntax}
%    \cs{DisplayCoffinHandles} \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}{ \MarkCoffinHandle }
%  \begin{syntax}
%    \cs{MarkCoffinHandle} \meta{coffin} 
%    ~~[ \meta{pole1} , \meta{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. If no \meta{poles} are
%  give, the default "(H,l)" is used.
%\end{function}
%
%\begin{function}{ \ShowCoffinStructure }
%  \begin{syntax}
%    \cs{ShowCoffinStructure} \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. For example, for the rotated coffin in 
%  Figure~\ref{fgr:rotation}, the output of \cs{ShowCoffinStructure}
%  is:
%  \begin{verbatim}
%    Size of coffin \ExampleCoffin:
%    > ht = 102.2052pt
%    > dp = 0.0pt
%    > wd = 102.2052pt
%    
%    Poles of coffin \ExampleCoffin:
%    >  b => {51.1026pt}{0.0pt}{707.10678pt}{707.10678pt}
%    >  t => {0.0pt}{51.1026pt}{707.10678pt}{707.10678pt}
%    >  vc => {25.5513pt}{25.5513pt}{707.10678pt}{707.10678pt}
%    >  r => {102.2052pt}{51.1026pt}{-707.10678pt}{707.10678pt}
%    >  hc => {76.6539pt}{25.5513pt}{-707.10678pt}{707.10678pt}
%    >  T => {51.1026pt}{0.0pt}{707.10678pt}{707.10678pt}
%    >  H => {51.1026pt}{0.0pt}{707.10678pt}{707.10678pt}
%    >  B => {51.1026pt}{0.0pt}{707.10678pt}{707.10678pt}
%    >  l => {51.1026pt}{0.0pt}{-707.10678pt}{707.10678pt}.
%    \coffin_show_structure:N ...N \l_coffin_show_toks 
%  \end{verbatim}
%  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}
\RequirePackage{l3coffins,xparse}  
%    \end{macrocode}
%
% A lot of this is more-or-less just passing data straight through.
% 
%\begin{macro}{\NewCoffin}
% This is a very easy conversion.
%    \begin{macrocode}
\NewDocumentCommand \NewCoffin { m } {
  \coffin_new:N #1
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\SetHorizontalCoffin}
%\begin{macro}{\SetVerticalCoffin}
% These are again straight-forward translations.
%    \begin{macrocode}
\NewDocumentCommand \SetHorizontalCoffin { m +m } {
  \hcoffin_set:Nn #1 {#2}
}
\NewDocumentCommand \SetVerticalCoffin { m m +m } {
  \vcoffin_set:Nnn #1 {#2} {#3}
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\SetHorizontalPole}
%\begin{macro}{\SetVerticalPole}
% Again straight-forward
%    \begin{macrocode}
\NewDocumentCommand \SetHorizontalPole { m m m } {
  \coffin_set_horizontal_pole:Nnn #1 {#2} {#3}
}
\NewDocumentCommand \SetVerticalPole { m m m } {
  \coffin_set_vertical_pole:Nnn #1 {#2} {#3}
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\JoinCoffins}
% The \cs{JoinCoffins} function needs to do a bit of work on the input
% syntax, as there are a number of optional arguments to worry about.
% The idea here is that \cs{JoinCoffins} can be used to either expand
% the bounding box of \meta{coffin1} or add \meta{coffin2} without any
% expansion of the bounding box. There are also the two handle positions
% and the offset to sort out.
%    \begin{macrocode}
\NewDocumentCommand \JoinCoffins
  {
    s
    m
    > { \SplitArgument { 1 } { , } } O { H , l }
    m
    > { \SplitArgument { 1 } { , } } O { H , l }
    > { \SplitArgument { 1 } { , } } D ( ) { 0 pt , 0 pt }
  }
  {
    \IfBooleanTF #1
      { \coffin_attach:NnnNnnnn #2 #3 #4 #5 #6 }
      { \coffin_join:NnnNnnnn #2 #3 #4 #5 #6 }
  }
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\TypesetCoffin}
% For typesetting coffins there are two optional arguments, both of
% which need to be split. This is a simpler case of the code needed for
% \cs{JoinCoffins}.
%    \begin{macrocode}
\NewDocumentCommand \TypesetCoffin 
  {
     m 
     > { \SplitArgument { 1 } { , } } O { H , l } 
     > { \SplitArgument { 1 } { , } } D ( ) { 0 pt , 0 pt }
  } 
  { \coffin_typeset:Nnnnn #1 #2 #3 }
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\RotateCoffin}
%\begin{macro}{\ResizeCoffin}
%\begin{macro}{\ScaleCoffin}
% Mores straight-forward copies.
%    \begin{macrocode}
\NewDocumentCommand \RotateCoffin  { m m } {
  \coffin_rotate:Nn #1 {#2}
}
\NewDocumentCommand \ResizeCoffin  { m m m } {
  \coffin_resize:Nnn #1 {#2} {#3}
}
\NewDocumentCommand \ScaleCoffin  { m m m } {
  \coffin_scale:Nnn #1 {#2} {#3}
}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\begin{macro}{\DisplayCoffinHandles}
% Displaying all of the handles is a bit easier, as there is no need
% to worry about the handle.
%    \begin{macrocode}
\NewDocumentCommand \DisplayCoffinHandles { m m } {
  \cs_if_exist:cTF { l_coffin_poles_ \tex_number:D #1 _prop }
    { \coffin_display_handles:Nn #1 {#2} }
    { \msg_kernel_error:nx { unknown-coffin } { \token_to_str:N #1 } }
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\MarkCoffinHandle}
% Marking a handle requires a bit of work with the input, so that 
% the design-level interface is `nice'.
%    \begin{macrocode}
\NewDocumentCommand \MarkCoffinHandle 
  { m > { \SplitArgument { 1 } { , } } O { H , l } m }
  {
    \cs_if_exist:cTF { l_coffin_poles_ \tex_number:D #1 _prop }
      { \coffin_mark_handle:Nnnn #1 #2 {#3} }
      { \msg_kernel_error:nx { unknown-coffin } { \token_to_str:N #1 }
  }
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\ShowCoffinStructure}
% Back again to easy-to-implement functions.
%    \begin{macrocode}
\NewDocumentCommand \ShowCoffinStructure { m } {
  \coffin_show_structure:N #1
}
%    \end{macrocode}
%\end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
%\end{implementation}
%
%\PrintChanges
%
%\PrintIndex