From ed6913bb5d71e9779f8714d469d5903b9d328020 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 31 Jul 2011 18:28:13 +0000 Subject: l3experimental (5jun11) git-svn-id: svn://tug.org/texlive/trunk@23284 c570f23f-e606-0410-a88d-b1316a301751 --- .../latex/l3experimental/xcoffins/l3coffins.dtx | 2084 ++++++++++++++++++++ .../latex/l3experimental/xcoffins/xcoffins.dtx | 855 ++++++++ .../latex/l3experimental/xcoffins/xcoffins.ins | 41 + 3 files changed, 2980 insertions(+) create mode 100644 Master/texmf-dist/source/latex/l3experimental/xcoffins/l3coffins.dtx create mode 100644 Master/texmf-dist/source/latex/l3experimental/xcoffins/xcoffins.dtx create mode 100644 Master/texmf-dist/source/latex/l3experimental/xcoffins/xcoffins.ins (limited to 'Master/texmf-dist/source/latex/l3experimental/xcoffins') diff --git a/Master/texmf-dist/source/latex/l3experimental/xcoffins/l3coffins.dtx b/Master/texmf-dist/source/latex/l3experimental/xcoffins/l3coffins.dtx new file mode 100644 index 00000000000..5bd7eefbd77 --- /dev/null +++ b/Master/texmf-dist/source/latex/l3experimental/xcoffins/l3coffins.dtx @@ -0,0 +1,2084 @@ +% \iffalse meta-comment +% +%% File: l3coffins.dtx Copyright(C) 2010,2011 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 "l3experimental 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,graphicx,xcolor} +\GetIdInfo$Id: l3coffins.dtx 2488 2011-06-30 19:19:20Z joseph $ + {L3 Experimental coffins} +% +%<*driver> +\documentclass[full]{l3doc} +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +% +% \fi +% +% \title{^^A +% The \textsf{l3coffins} package\\ Coffins^^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. +% +% \section{Code-level coffin functions} +% +% \begin{function}{\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}{\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} +% {\coffin_set_eq:NN, \coffin_set_eq:Nc, \coffin_set_eq:cN, \coffin_set_eq:cc} +% \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, \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}{\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} +% {\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; 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, \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; 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, \coffin_rotate:cn} +% \begin{syntax} +% \cs{coffin_rotate:Nn} \meta{coffin} \Arg{angle} +% \end{syntax} +% Rotates the \meta{coffin} by the given \meta{angle} (given in +% degrees counter-clockwise). This process 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, \coffin_attach:cnnNnnnn, +% \coffin_attach:Nnncnnnn, \coffin_attach:cnncnnnn +% } +% \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, \coffin_join:cnnNnnnn, +% \coffin_join:Nnncnnnn, \coffin_join:cnncnnnn +% } +% \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, \coffin_typeset:cnnnn} +% \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 +% \enquote{parent} coffin is the current insertion point. +% \end{function} +% +% \begin{function}{\coffin_display_handles:cn, \coffin_display_handles:cn} +% \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, \coffin_mark_handle:cnnn} +% \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, \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} +% +% \end{documentation} +% +% \begin{implementation} +% +% \section{\pkg{l3coffins} Implementation} +% +% \begin{macrocode} +%<*package> +% \end{macrocode} +% +% \begin{macrocode} +\ProvidesExplPackage + {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription} +% \end{macrocode} +% +% \subsection{Coffins: data structures and general variables} +% +% \begin{variable}{\l_coffin_tmp_box} +% \begin{variable}{\l_coffin_tmp_dim} +% \begin{variable}{\l_coffin_tmp_fp} +% \begin{variable}{\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{variable} +% \end{variable} +% \end{variable} +% \end{variable} +% +% \begin{variable}{\c_coffin_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_coffin_corners_prop +\prop_put:Nnn \c_coffin_corners_prop { tl } { { 0 pt } { 0 pt } } +\prop_put:Nnn \c_coffin_corners_prop { tr } { { 0 pt } { 0 pt } } +\prop_put:Nnn \c_coffin_corners_prop { bl } { { 0 pt } { 0 pt } } +\prop_put:Nnn \c_coffin_corners_prop { br } { { 0 pt } { 0 pt } } +% \end{macrocode} +% \end{variable} +% +% \begin{variable}{\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{variable} +% +% \begin{variable}{\l_coffin_calc_a_fp} +% \begin{variable}{\l_coffin_calc_b_fp} +% \begin{variable}{\l_coffin_calc_c_fp} +% \begin{variable}{\l_coffin_calc_d_fp} +% \begin{variable}{\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{variable} +% \end{variable} +% \end{variable} +% \end{variable} +% \end{variable} +% +% \begin{variable}{\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{variable} +% +% \begin{variable}{\l_coffin_offset_x_dim} +% \begin{variable}{\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{variable} +% \end{variable} +% +% \begin{variable}{\l_coffin_pole_a_tl} +% \begin{variable}{\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{variable} +% \end{variable} +% +% \begin{variable}{\l_coffin_sin_fp} +% \begin{variable}{\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{variable} +% \end{variable} +% +% \begin{variable}{\l_coffin_x_dim} +% \begin{variable}{\l_coffin_y_dim} +% \begin{variable}{\l_coffin_x_prime_dim} +% \begin{variable}{\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{variable} +% \end{variable} +% \end{variable} +% \end{variable} +% +% \begin{variable}{\l_coffin_x_fp} +% \begin{variable}{\l_coffin_y_fp} +% \begin{variable}{\l_coffin_x_prime_fp} +% \begin{variable}{\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{variable} +% \end{variable} +% \end{variable} +% \end{variable} +% +% \begin{variable}{\l_coffin_Depth_dim} +% \begin{variable}{\l_coffin_Height_dim} +% \begin{variable}{\l_coffin_TotalHeight_dim} +% \begin{variable}{\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{variable} +% \end{variable} +% \end{variable} +% \end{variable} +% +% \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_if_exist_execute:Nn} +% 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} +\cs_new_protected:Npn \coffin_if_exist_execute:Nn #1#2 + { + \cs_if_exist:NTF #1 + { + \cs_if_exist:cTF { l_coffin_poles_ \int_value:w #1 _prop } + { #2 } + { + \msg_kernel_error:nnx { coffin } { unknown-coffin } + { \token_to_str:N #1 } + } + } + { + \msg_kernel_error:nnx { coffin } { 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_nopar:Npn \coffin_clear:N #1 + { + \coffin_if_exist_execute:Nn #1 + { + \box_clear:N #1 + \coffin_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_nopar:Npn \coffin_new:N #1 + { + \box_new:N #1 + \prop_clear_new:c { l_coffin_corners_ \int_value:w #1 _prop } + \prop_clear_new:c { l_coffin_poles_ \int_value:w #1 _prop } + \prop_gset_eq:cN { l_coffin_corners_ \int_value:w #1 _prop } + \c_coffin_corners_prop + \prop_gset_eq:cN { l_coffin_poles_ \int_value:w #1 _prop } + \c_coffin_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 + { + \coffin_if_exist_execute:Nn #1 + { + \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 + } + } +\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. +% \begin{macrocode} +\cs_new_protected:Npn \vcoffin_set:Nnn #1#2#3 + { + \coffin_if_exist_execute:Nn #1 + { + \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 } } + } + } +\cs_generate_variant:Nn \vcoffin_set:Nnn { c } +% \end{macrocode} +% \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_nopar:Npn \coffin_set_eq:NN #1#2 + { + \coffin_if_exist_execute:Nn #1 + { + \box_set_eq:NN #1 #2 + \coffin_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_coffin_aligned_coffin} +% \begin{variable}{\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{variable} +% \end{variable} +% \end{variable} +% +% \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_new_protected_nopar:Npn \coffin_get_pole:NnN #1#2#3 + { + \prop_get:cnN { l_coffin_poles_ \int_value:w #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_ \int_value:w #1 _prop } + \c_coffin_corners_prop + \prop_set_eq:cN { l_coffin_poles_ \int_value:w #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_ \int_value:w #1 _prop } + { l_coffin_corners_ \int_value:w #2 _prop } + \prop_set_eq:cc { l_coffin_poles_ \int_value:w #1 _prop } + { l_coffin_poles_ \int_value:w #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, \coffin_set_horizontal_pole:cnn} +% \begin{macro}{\coffin_set_vertical_pole:Nnn,\coffin_set_vertical_pole:cnn} +% \begin{macro}{\coffin_set_pole:Nnn, \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_if_exist_execute:Nn #1 + { + \coffin_set_user_dimensions:N #1 + \coffin_set_pole:Nnx #1 {#2} + { + { 0 pt } { \dim_eval:n {#3} } + { 1000 pt } { 0 pt } + } + \coffin_end_user_dimensions: + } + } +\cs_new_protected_nopar:Npn \coffin_set_vertical_pole:Nnn #1#2#3 + { + \coffin_if_exist_execute:Nn #1 + { + \coffin_set_user_dimensions:N #1 + \coffin_set_pole:Nnx #1 {#2} + { + { \dim_eval:n {#3} } { 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_ \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 \coffin_set_pole:Nnn { Nnx } +% \end{macrocode} +% \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_ \int_value:w #1 _prop } { tl } + { { 0 pt } { \dim_use:N \box_ht:N #1 } } + \prop_put:cnx { l_coffin_corners_ \int_value:w #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_ \int_value:w #1 _prop } { bl } + { { 0 pt } { \dim_use:N \l_coffin_tmp_dim } } + \prop_put:cnx { l_coffin_corners_ \int_value:w #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_ \int_value:w #1 _prop } { hc } + { { \dim_use:N \l_coffin_tmp_dim } { 0 pt } { 0 pt } { 1000 pt } } + \prop_put:cnx { l_coffin_poles_ \int_value:w #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_ \int_value:w #1 _prop } { vc } + { { 0 pt } { \dim_use:N \l_coffin_tmp_dim } { 1000 pt } { 0 pt } } + \prop_put:cnx { l_coffin_poles_ \int_value:w #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_ \int_value:w #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, \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_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_ \int_value:w \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 + } +\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_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_ \int_value:w \l_coffin_aligned_coffin _prop } + { l_coffin_corners_ \int_value:w #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 + } +\cs_generate_variant:Nn \coffin_attach:NnnNnnnn { c , Nnnc , cnnc } +% \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_ \int_value:w #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_ \int_value:w #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_ \int_value:w \l_coffin_aligned_coffin _prop } + { #1 - #2 } + { + { \dim_eval:n { #3 + #5 } } + { \dim_eval:n { #4 + #6 } } + } + } +% \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, \coffin_typeset:cnnnn} +% 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_generate_variant:Nn \coffin_typeset:Nnnnn { c } +% \end{macrocode} +% \end{macro} +% +% \subsection{Rotating coffins} +% +% \begin{variable}{\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{variable} +% +% \begin{variable}{\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{variable} +% +% \begin{variable}{\l_coffin_left_corner_dim} +% \begin{variable}{\l_coffin_right_corner_dim} +% \begin{variable}{\l_coffin_bottom_corner_dim} +% \begin{variable}{\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{variable} +% \end{variable} +% \end{variable} +% \end{variable} +% +% \begin{macro}{\coffin_rotate:Nn, \coffin_rotate:cn} +% 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_ \int_value:w #1 _prop } + { \coffin_rotate_corner:Nnnn #1 {##1} ##2 } + \prop_map_inline:cn { l_coffin_poles_ \int_value:w #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_ \int_value:w #1 _prop } + { \coffin_shift_corner:Nnnn #1 {##1} ##2 } + \prop_map_inline:cn { l_coffin_poles_ \int_value:w #1 _prop } + { \coffin_shift_pole:Nnnnnn #1 {##1} ##2 } + } +\cs_generate_variant:Nn \coffin_rotate:Nn { c } +% \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_ \int_value:w #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_ \int_value:w #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_ \int_value:w #1 _ prop } {#2} + { + { \dim_eval:n { #3 - \l_coffin_left_corner_dim } } + { \dim_eval:n { #4 - \l_coffin_bottom_corner_dim } } + } + } +\cs_new_protected_nopar:Npn \coffin_shift_pole:Nnnnnn #1#2#3#4#5#6 + { + \prop_put:cnx { l_coffin_poles_ \int_value:w #1 _ prop } {#2} + { + { \dim_eval:n { #3 - \l_coffin_left_corner_dim } } + { \dim_eval:n { #4 - \l_coffin_bottom_corner_dim } } + {#5} {#6} + } + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \subsection{Resizing coffins} +% +% \begin{variable}{\l_coffin_scale_x_fp} +% \begin{variable}{\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{variable} +% \end{variable} +% +% \begin{variable}{\l_coffin_scaled_total_height_dim} +% \begin{variable}{\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{variable} +% \end{variable} +% +% \begin{macro}{\coffin_resize:Nnn, \coffin_resize:cnn} +% 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} + } +\cs_generate_variant:Nn \coffin_resize:Nnn { c } +% \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_ \int_value:w #1 _prop } + { \coffin_scale_corner:Nnnn #1 {##1} ##2 } + \prop_map_inline:cn { l_coffin_poles_ \int_value:w #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_ \int_value:w #1 _prop } + { \coffin_x_shift_corner:Nnnn #1 {##1} ##2 } + \prop_map_inline:cn { l_coffin_poles_ \int_value:w #1 _prop } + { \coffin_x_shift_pole:Nnnnnn #1 {##1} ##2 } + } + \coffin_end_user_dimensions: + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\coffin_scale:Nnn, \coffin_scale:cnn} +% 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 } + } +\cs_generate_variant:Nn \coffin_scale:Nnn { c } +% \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_ \int_value:w #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_ \int_value:w #1 _prop } {#2} + { + { \dim_eval:n { #3 + \box_wd:N #1 } } {#4} + } + } +\cs_new_protected_nopar:Npn \coffin_x_shift_pole:Nnnnnn #1#2#3#4#5#6 + { + \prop_put:cnx { l_coffin_poles_ \int_value:w #1 _prop } {#2} + { + { \dim_eval:n #3 + \box_wd:N #1 } {#4} + {#5} {#6} + } + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \subsection{Coffin diagnostics} +% +% \begin{variable}{\l_coffin_display_coffin} +% \begin{variable}{\l_coffin_display_coord_coffin} +% \begin{variable}{\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{variable} +% \end{variable} +% \end{variable} +% +% \begin{variable}{\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{variable} +% +% \begin{variable}{\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{variable} +% +% \begin{variable}{\l_coffin_display_x_dim} +% \begin{variable}{\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{variable} +% \end{variable} +% +% \begin{variable}{\l_coffin_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_coffin_display_poles_prop +% \end{macrocode} +% \end{variable} +% +% \begin{variable}{\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{variable} +% +% \begin{variable}{\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{variable} +% +% \begin{macro}{\coffin_mark_handle:Nnnn, \coffin_mark_handle:cnnn} +% \begin{macro}[aux]{\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: } + } + \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 } + } +\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]{\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_ \int_value:w #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 } + } +\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_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, \coffin_show_structure:c} +% \begin{macro}[aux]{\coffin_show_aux:n} +% \begin{macro}[aux]{\coffin_show_aux:w} +% 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 + { + \cs_if_exist:cTF { l_coffin_poles_ \int_value:w #1 _prop } + { + \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: + } + \iow_term:x { Poles~of~coffin~\token_to_str:N #1 : } + \tl_set:Nx \l_coffin_tmp_tl + { + \prop_map_function:cN + { l_coffin_poles_ \int_value:w #1 _prop } + \coffin_show_aux:nn + } + \etex_showtokens:D \exp_after:wN \exp_after:wN \exp_after:wN + { \exp_after:wN \coffin_show_aux:w \l_coffin_tmp_tl } + } + { + \iow_term:x { ---~No~poles~found~--- } + \tl_show:n { Is~this~really~a~coffin? } + } + } +\cs_new:Npn \coffin_show_aux:nn #1#2 + { + \iow_newline: > \c_space_tl \c_space_tl + #1 \c_space_tl \c_space_tl => \c_space_tl \c_space_tl \exp_not:n {#2} + } +\cs_new_nopar:Npn \coffin_show_aux:w #1 > ~ { } +\cs_generate_variant:Nn \coffin_show_structure:N { c } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Messages} +% +% \begin{macrocode} +\msg_kernel_new:nnnn { coffin } { 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 { 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'. } + { + \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. + } +% \end{macrocode} +% +% \begin{macrocode} +% +% \end{macrocode} +% +% \end{implementation} +% +% \PrintIndex \ No newline at end of file diff --git a/Master/texmf-dist/source/latex/l3experimental/xcoffins/xcoffins.dtx b/Master/texmf-dist/source/latex/l3experimental/xcoffins/xcoffins.dtx new file mode 100644 index 00000000000..8d66d6f6bed --- /dev/null +++ b/Master/texmf-dist/source/latex/l3experimental/xcoffins/xcoffins.dtx @@ -0,0 +1,855 @@ +% \iffalse meta-comment +% +%% File: xcoffins.dtx Copyright(C) 2010,2011 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 "l3experimental 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{xparse,l3coffins} +\GetIdInfo$Id: xcoffins.dtx 2349 2011-05-11 18:44:37Z joseph $ + {L3 Experimental design-level coffins} +% +%<*driver> +\documentclass[full]{l3doc} +\usepackage{xcoffins} % Not yet part of expl3, so not in l3doc +\NewCoffin \ExampleCoffin +\NewCoffin \SmallCoffin +\NewCoffin \OutputCoffin +\NewCoffin \RedCoffin +\NewCoffin \BlueCoffin +\NewCoffin \GreenCoffin +\NewCoffin \YellowCoffin +\NewCoffin \OrangeCoffin +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +% +% \fi +% +% \title{^^A +% The \textsf{xcoffins} package\\ Design-level coffins^^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} +% +% \section{Introduction: the coffin concept} +% +% In \LaTeX3 terminology, a \enquote{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 \enquote{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 \enquote{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 \enquote{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 \enquote{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 \enquote{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 \enquote{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 +% \enquote{parent}, and is updated by the alignment. The second +% \enquote{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 \enquote{parent} +% \meta{coffin1} and the \enquote{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 \enquote{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 +% \enquote{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 = 72.26999pt +% > dp = 0.0pt +% > wd = 72.26999pt +% +% Poles of coffin \ExampleCoffin: +% > l => {0pt}{0pt}{0pt}{1000pt} +% > B => {0pt}{0pt}{1000pt}{0pt} +% > H => {0pt}{0pt}{1000pt}{0pt} +% > T => {0pt}{0pt}{1000pt}{0pt} +% > hc => {36.135pt}{0pt}{0pt}{1000pt} +% > r => {72.26999pt}{0pt}{0pt}{1000pt} +% > vc => {0pt}{36.135pt}{1000pt}{0pt} +% > t => {0pt}{72.26999pt}{1000pt}{0pt} +% > b => {0pt}{0.0pt}{1000pt}{0pt}. +% ...ffin_show_aux:w \l_coffin_tmp_tl } +% \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 + {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription} +% \end{macrocode} +% +% +% \begin{variable} +% { +% \l_coffin_A_hpole_tl , +% \l_coffin_A_vpole_tl , +% \l_coffin_B_hpole_tl , +% \l_coffin_B_vpole_tl , +% \l_coffin_bound_box_grow_bool , +% \l_coffin_hoffset_dim , +% \l_coffin_voffset_dim +% } +% Key--value definitions for the alignment system. With the exception +% of \texttt{grow-bounding-box}, all of these have to be given with a +% value. +% \begin{macrocode} +\keys_define:nn { coffin } + { + coffin1-hpole .tl_set:N = \l_coffin_A_hpole_tl , + coffin1-hpole .value_required: , + coffin1-vpole .tl_set:N = \l_coffin_A_vpole_tl , + coffin1-vpole .value_required: , + coffin2-hpole .tl_set:N = \l_coffin_B_hpole_tl , + coffin2-hpole .value_required: , + coffin2-vpole .tl_set:N = \l_coffin_B_vpole_tl , + coffin2-vpole .value_required: , + grow-bounding-box .bool_set:N = \l_coffin_bound_box_grow_bool , + grow-bounding-box .default:n = true , + hoffset .dim_set:N = \l_coffin_hoffset_dim , + hoffset .value_required: , + voffset .dim_set:N = \l_coffin_voffset_dim , + voffset .value_required: + } +\keys_set:nn { coffin } + { + coffin1-hpole = H , + coffin1-vpole = l , + coffin2-hpole = H , + coffin2-vpole = l , + grow-bounding-box = true , + hoffset = 0 pt , + voffset = 0 pt + } +% \end{macrocode} +% \end{variable} +% +% 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 + { + o + s + m + > { \SplitArgument { 1 } { , } } O { H , l } + m + > { \SplitArgument { 1 } { , } } O { H , l } + > { \SplitArgument { 1 } { , } } D ( ) { 0 pt , 0 pt } + } + { + \IfNoValueTF {#1} + { + \IfBooleanTF #2 + { \coffin_attach:NnnNnnnn #3 #4 #5 #6 #7 } + { \coffin_join:NnnNnnnn #3 #4 #5 #6 #7 } + } + { + \group_begin: + \keys_set:nn { coffin } {#1} + \tl_set:Nx \l_coffin_tmp_tl + { + \group_end: + \bool_if:NTF \l_coffin_bound_box_grow_bool + { \coffin_join:NnnNnnnn } + { \coffin_attach:NnnNnnnn } + \exp_not:N #3 + { \exp_not:o { \l_coffin_A_hpole_tl } } + { \exp_not:o { \l_coffin_A_vpole_tl } } + \exp_not:N #5 + { \exp_not:o { \l_coffin_B_hpole_tl } } + { \exp_not:o { \l_coffin_B_vpole_tl } } + { \dim_use:N \l_coffin_hoffset_dim } + { \dim_use:N \l_coffin_voffset_dim } + } + \l_coffin_tmp_tl + } + } +% \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_ \int_value:w #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 \enquote{nice}. +% \begin{macrocode} +\NewDocumentCommand \MarkCoffinHandle + { m > { \SplitArgument { 1 } { , } } O { H , l } m } + { + \cs_if_exist:cTF { l_coffin_poles_ \int_value:w #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} +% +% \end{macrocode} +% +% \end{implementation} +% +% \PrintIndex \ No newline at end of file diff --git a/Master/texmf-dist/source/latex/l3experimental/xcoffins/xcoffins.ins b/Master/texmf-dist/source/latex/l3experimental/xcoffins/xcoffins.ins new file mode 100644 index 00000000000..cbe6c5f74af --- /dev/null +++ b/Master/texmf-dist/source/latex/l3experimental/xcoffins/xcoffins.ins @@ -0,0 +1,41 @@ +\iffalse meta-comment + +File xcoffins.ins Copyright (C) 2010,2011 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 "xpackage 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. + +\fi + +\input docstrip.tex +\askforoverwritefalse + +\preamble + +EXPERIMENTAL CODE + +Do not distribute this file without also distributing the +source files specified above. + +Do not distribute a modified version of this file. + +\endpreamble +% stop docstrip adding \endinput +\postamble +\endpostamble + +\keepsilent + +\generate{\file{l3coffins.sty} {\from{l3coffins.dtx} {package}}} +\generate{\file{xcoffins.sty} {\from{xcoffins.dtx} {package}}} + +\endbatchfile -- cgit v1.2.3