The offset of \SetHorizontalPole

[zepinglee]

The documentation of xcoffins says the offset of \SetHorizontalPole is from the bottom edge of the bounding box.

latex3/l3experimental/xcoffins/xcoffins.dtx

Lines 181 to 187 in 8b3fee5

	% \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

In this test case, I create a coffin with height of 24pt and depth of 48pt. Then I create a horizontal test pole with 12pt offset (\SetHorizontalPole \tmpa {test} {12pt}). It is supposed to be 12pt above the b pole according to the documentation. However the actual test pole is 12 pt above the H pole, which is contradictory to the documentation.

\documentclass{article}
\usepackage{xcoffins}
\usepackage{expl3}

\begin{document}

\NewCoffin\tmpa
\SetVerticalCoffin \tmpa {72pt} {%
  \noindent
  \rule [-48pt] {0pt} {72pt}%
}
\SetHorizontalPole \tmpa {test} {12pt}
\DisplayCoffinHandles \tmpa {black}

\vskip 80pt

\ExplSyntaxOn
\vcoffin_set:Nnn \l_tmpa_coffin { 72pt }
  {
    \noindent
    \rule [ -48pt ] { 0pt } { 72pt }
  }
\coffin_set_horizontal_pole:Nnn \l_tmpa_coffin { test } { 12pt }
\coffin_display_handles:Nn \l_tmpa_coffin { black }
\ExplSyntaxOff

\end{document}

Package: expl3 2022-01-21 L3 programming layer (loader) 
Package: xcoffins 2021-11-12 L3 Experimental design level coffins

[josephwright]

Looks like a documentation error to me: the pole is supposed to be at 12pt above the baseline.

[zepinglee]

Looks like a documentation error to me: the pole is supposed to be at 12pt above the baseline.

Yes, I suppose so.

[josephwright]

I've altered the docs, but I'll see what other team members think here before a release.

[FrankMittelbach]

The change is correct I would say and from the real baseline you can get to "b" via \Depth. Maybe it would have been nice/better if one could have made the starting point another argument so that you can offset from an existing pool.
Anyway, not having looked at this for a long time :-) I wonder if the graphics are not a bit misleading, showing H at b --- while this is correct for the given graphics it is not that helpful. Perhaps a bit richer graphic with content inside that has 4 lines would be more helpful, show T/B/H in different positions (and not = b). Maybe worth a note for a rainy day.