jfbu/colorframed

LaTeX package extending framed.sty breakable boxes with colour compatibility

colorframed's Issues

Placement of title by \CustomFBox is not same as in original and also there is extra top whitespace below title above contents

I was well aware of that but completely forgot about it when I decided to make the release: when I started colorframed (the day before, intermingled with and as a derivative to various professional duties), I had not yet analyzed all changes needed in framed code base, and initially I locally modified rather \@frameb@x, then I saw I needed to fix \CustomFBox used by oframed, and that I could then recycle it as substitute to \fbox so I dropped my custom \@frameb@x and then mainly focused on checking things were ok with "framed" environment, and decided I had spent enough time on colorframed and it was time to get rid of it.

Thus I ended up for reasons of recycling \CustomFBox with a

        \hrule\@height#3\relax
        \kern-#3\relax
        #1%

where the original does not have the \kern (this \kern serves to make rules overlap rather than touch). Didn't I initially put the \kern after #1? Perhaps this was intermingled with the time when I saw that titled-frame (which I had never used) was broken, and traced it back to the upstream LaTeX change to \smash?

Whatever the reason explaining I released it this way, it induces a breaking change.

This is original:

This is the colorframed 0.9(a) version:

The original places the title underneath a top rule of 2pt height, my version places the title in a way hiding this top rule, so basically cancelling visually.

Side note: the titled-frame environment, which is the only one in framed.sty using \CustomFBox with a non-empty #1, has been anyhow broken for a few years as LaTeX has modified \smash (see a screenshot below for illustration).

I could probably place the kern this way

        \hrule\@height#3\relax
        #1%
        \kern-#3\relax

which would match the symmetric handling of #2 which follows:

        \hrule\@height#3\relax
        #1%
        \kern-#3\relax
        \copy\z@ % deliberate overlap hrules+vrules to avoid anti-aliasing artefacts
        \kern-#4\relax
        #2%
        \hrule\@height#4\relax

Here is what this would give:

Testing with a big border width, one sees however that the "titled-frame" horizontal placement of the title (which is same in colorframed as in original) is arguably broken.

Indeed, here is what happens with original framed.sty if one renew the environment to use \fboxrule22pt in place of \fboxrule2pt:

and one sees the title horizontal location ignores blissfully the border width (I have also included in the snapshot the breakage of continuation label related to the \smash matter). AND vertical placement looks fishy too!

the "titled-frame" environment with \fboxrule=22pt rather than \fboxrule=2pt should also be modified to use \advance\hsize-60pt rather than -20pt but this is unrelated to the title placement seen above, and besides here our contents are too wide anyhow to fit together with the border in the linewidth

Testing the same modification (i.e. \fboxrule22pt in titled-frame environment) with colorframed one would get with the "corrected placement of the negative \kern":

The overlap is deliberate to avoid anti-aliasing effects in some pdf viewers. But we see it clashes with (strange) horizontal placement of the title.

Meanwhile, with current colorframed 0.9, 0.9a one would get with \fboxrule=22pt in titled-frame this:

It does not overwrite the left part of the title, but it displays some obvious problem of a big extra vertical whitespace. The value of this extra space is equal to the height of the title line (as configured by the \TF@Title macro from framed.sty), because here this height is less than the border width, so the presence of the title line induces a vertical shift downwards of what follows by the value of this height. Indeed what follows deliberately incorporates whitespace of height equal to border width so the distance to the bottom of this top border ends up being incremented by the vertical space occupied by the title box, as long as this vertical space is at most the top border width. Once this height becomes larger than top border width the extra whitespace stabilizes to the border width itself. With a small \fboxrule of 2pt as is the default we thus have a 2pt amount of extra separation from contents to bottom of title, because the title height is more than 2pt.

In the default situation with titled-frame using \fboxrule=2pt the title line (which draws via \TF@Title some background coloured rule) completely hides the top border, and the extra space is present but only equal to \fboxrule value, so is more discrete (but clearly this is some other buggy aspect of current 0.9a placement of \kern).

Thus, if I want to modify the (a bit too hastily released) current code I might end up having to also patch one more framed.sty macro, which is \TF@Title. Things are easier if I renounce overlapping vrules on hrule but the code is used for \fbox substitute used in "framed" environment, and this is deliberate.

But this is all related to trying to maintain compatibility with something which is broken in various ways anyhow... so possibly I should place the \kern after the #1 insertion as it should have been from the start (and I think was still a bit before a last minute change before release) but the user wanting to employ "titled-frame" with a large border width will have to think about rewriting \TF@Title as well... With the default \fboxrule of 2pt the deliberate overlap of vrules done by colorframed own \CustomFBox does not cause collision with the title as its glyphs are shifted to the right by 0.8ex + \fboxsep=8pt in the \TF@Title original code, which is not touched by colorframed.

[Upstream] titled-frame wrong horizontal placement of both title and continuation label seen with higher border width

If we modify titled-frame with an increased border-width, we see that not only title looks wrongly positioned but also continuation label. In the image, we see the continuation label because \smash does \leavevmode with recent LaTeX, otherwise it would have become invisible from being swallowed into the border.

I used

\renewenvironment{titled-frame}[1]{%
  \def\FrameCommand{\fboxsep8pt\fboxrule16pt
     \TitleBarFrame{\textbf{#1}}}%
  \def\FirstFrameCommand{\fboxsep8pt\fboxrule16pt
     \TitleBarFrame[\rule{4pt}{4pt}]{\textbf{#1}}}%
  \def\MidFrameCommand{\fboxsep8pt\fboxrule16pt
     \TitleBarFrame[\rule{4pt}{4pt}]{\textbf{#1\ (cont)}}}%
  \def\LastFrameCommand{\fboxsep8pt\fboxrule16pt
     \TitleBarFrame{\textbf{#1\ (cont)}}}%
  \MakeFramed{\advance\hsize-48pt \FrameRestore}}% 48=16+8+8+16
 {\endMakeFramed}

and obtained (the contents were trimmed to be sure they fit together with thick borders in linewidth, but anyhow the image showing only the frame, we do not see it fits exactly in the linewidth)

I used a 4pt x 4pt rule as continuation label.

With colorframed (including fix of #2) we get this

As commented in #2, the start of title is partly covered. The continuation label is configured here to use colour purple (as is used for TFTitleColor) and the \smash problem is fixed and we see the label in the border. But clearly this is wrong location.

I feel that at some point of development of framed.sty macro \TF@Title and \TF@conlab, it might be that D. A. had another \CustomFBox which would draw the vertical rules in such a way that the hboxes had their left border at the right edge of the west rule. Because if both Title and Continuation Label were shifted to the right by one \fboxrule more we would not have the above problems.

I had started commenting this in my edited \TF@Title but I am moving these comments here out of the colorframed.sty, so that they are recorded somewhere but don't take room in the macro file:

% The titled-frame environment depends in part on this macro,
% whose original in framed.sty has various colour problems.
% We have indicated the modifications, additionally to using
% our modified \CustomFBox.
% Original let the continuation label use same colour as frame.
% Let make this customizable.
\let\colorframedTFconlabcolorcommand\empty
\renewcommand\TitleBarFrame[3][]{\begingroup
  \ifx\delimiter#1\delimiter
    \let\TF@conlab\@empty
  \else
    \def\TF@conlab{%
     \nointerlineskip
     \hbox{%<<<< ADDED (needed due to \smash doing \leavevmode nowadays)
           \colorframedTFconlabcolorcommand%<<<< ADDED
% ADDED COMMENT (JFB, 2022/09/24)
% The horizontal placement of #1 done here is very likely a bug.  The
% \@tempboxa has a width which incorporates 2\fboxsep, but no \fboxrule.  The
% left boundary of hboxes is at **left** edge of left (west) border.  So this
% means that #1 is positioned to the right by \fboxsep of the **left** edge of
% the right (east) border.  For example if \fboxrule is much bigger than
% \fboxsep, this places the label entirely inside the border; and as
% framed.sty draws it with the frame colour, it becomes invisble.  Clearly a
% bug.  It should probably be here 2\fboxrule and then perhaps \fboxsep, or
% some other spacing.
%
% OR, PERHAPS: this code was done at time the \CustomFBox (the one of framed.sty)
% was done in such a way that reference point was to the right of the west
% border.  This would ALSO explain the problem with the \TF@Title placement of
% the title, see my github #2 for related comments.  I have been careful to
% check my analysis using pristine framed.sty, as things could have been
% caused by my own version of \CustomFBox, which boxes things differently.
     \smash{\rlap{\kern\wd\@tempboxa\kern\fboxrule\kern\fboxsep #1}}}%
          }%<<<< ADDED
  \fi
  %\let\TF@savecolor\current@color%<<<< REMOVED
  %\textcolor{TFFrameColor}{%      <<<< REMOVED
  \def\colorframedbordercolorcommand{\color{TFFrameColor}}%<<<< ADDED
  \CustomFBox
    {\TF@Title{#2}}{\TF@conlab}%
    \fboxrule\fboxrule\fboxrule\fboxrule
    {%\let\current@color\TF@savecolor\set@color%<<<< REMOVED
    #3}%
  %}%                              <<<< REMOVED
  \endgroup
}

Another issue we see above with the title is that its vertical placement looks poor when the border is thick like here.

[Upstream] Can not use snugshade (or framed) immediately following first list `\item`, and for next ones placement is wrong

Test file

\documentclass[a4paper]{article}
\usepackage{geometry}
\usepackage{framed}
\usepackage{color}
\definecolor{shadecolor}{gray}{0.9}
\begin{document}
\begin{enumerate}
\item A
\item
  \begin{snugshade}
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
    aaa bbb ccc
  \end{snugshade}
\end{enumerate}
\end{document}

Produces:

And without the first \item A it is even worse:

! LaTeX Error: Something's wrong--perhaps a missing \item.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.26   \end{snugshade}
                      
? S
OK, entering \scrollmode...

[DOC] the mention that titled-frame uses \fboxrule is not helping the reader, as it uses it after having set it!

Documentation says "titled-frame" uses \fboxrule but it should better have said that the border width is actually not customizable, as the framed.sty package "titled-frame" environment sets \fboxrule to a hard-coded 2pt. Only way is to renew the original environment.

[Upstream] with "titled-frame" a long title will not wrap and will stick in the margin with its background

For example:

Now if we use the colorframed the output is also similarly bad, with furthermore contents shited to the right:

In fact I am creating this issue as I did with #3 as an overt political manoeuvre which will justify my next "reset" move. Not commenting more with real-life analogies as I would end up banned and black-listed, certainly.