\documentclass[a4paper,dvipdfmx,10pt,english]{article}
\usepackage{babel}
\usepackage[T1]{fontenc}
\usepackage{geometry}
\usepackage[straightquotes,ttzdefault]{newtxtt}
% Copied from xint manual source:
% In ts1newtxttz.fd 2024/03/03 reference to newtcxttz are made.
% Presumably tc = text companion but the fonts do not exist.
% kpathsea: Running mktexmf newtcxttza
% ! I can't find file `newtcxttza'.
% The problem is with \textbullet used by the itemize environment.
% (the \textasciigrave does not cause problems thanks to using
% the straightquotes option).
% As we had no time to really investigate anyfurther we did
% this at release 1.0 to work around the issue.
\AtBeginDocument{\def\textbullet{\ensuremath{\bullet}}}

\usepackage{framed}
\usepackage[dvipsnames,table]{xcolor}% table: for \rowcolors
\usepackage{colorframed}
% we put this here but it does not have to be in preamble of
% course
% titled-frame
\colorlet{TFFrameColor}{teal!20}
\definecolor{TFTitleColor}{rgb}{.5,0,.2}
\def\colorframedTFconlabcolorcommand{\color{TFTitleColor}}
% shaded
%\colorlet{shadecolor}{orange!10}
\colorlet{shadecolor}{lightgray!25}

% framed
\FrameRule5pt\relax
\FrameSep9pt\relax % this is framed.sty default anyhow, 3\fboxsep
% attention that \FrameSep influences framed but also shaded, shaded* and
% oframed, which is not so clear from reading only framed documentation
\def\colorframedbordercolorcommand{\color{red!20}}

\title{The \colorframed package%
\vadjust{\vtop to 0pt{\hbox
    to\linewidth{\strut\footnotesize Release 1.1 of
      2026/11/16\hss report issues at \url{https://github.com/jfbu/colorframed/issues}}\vss}}%
}
\author{Jean-François Burnol}
\date{}
\usepackage{shortvrb}\MakeShortVerb\|
%\usepackage{url}\urlstyle{same}
\usepackage{hyperref}
\def\ctanpackage#1{\href{https://ctan.org/pkg/#1}{#1}}
\hypersetup{%
  breaklinks=true,%
  colorlinks=true,%
%  linkcolor={blue},%
  urlcolor={blue},%
%  citecolor={red},%
  pdfstartview=FitH,%
  pdfpagemode=UseNone,%
}

\usepackage{amssymb}

\usepackage{parskip}
\usepackage{xspace}
\usepackage{metalogo}
\setlogokern{La}{-0.258em}
\setlogokern{aT}{-0.08em}
\setlogokern{eL}{-0.1em}
%\setlogokern{X2}{0em}
\usepackage{enumitem}

\definecolor{joli}{RGB}{225,95,0}
\definecolor{JOLI}{RGB}{225,95,0}
\newcommand\colorframed{%
        \texorpdfstring{{\color{joli}\bfseries colorframed}}{colorframed}\xspace}


% ATTENTION: dvipdfmx syntax here!
{\makeatletter
     \sbox0{\color{Brown}%
            \xdef\verbatimpushcolor{\special{color push \current@color}}}%
}
\def\verbatimpopcolor{\special{color pop}}
\AddToHook{env/verbatim/before}{\verbatimpushcolor}
\AddToHook{env/verbatim/end}{\verbatimpopcolor}
% verbatim blocks (not the inline verbatim) are in \small
\AddToHook{env/verbatim/begin}{\small}

\newcommand\ghissue[2][]{\href{https://github.com/jfbu/colorframed/issues/#2}{#1\##2}}

\makeatletter
  %\show\verbatim@font % pas changé at begin doc
  \def\verbatim@font{\normalfont\ttfamily\color{Brown}}%
\makeatother

\begin{document}
\maketitle

\vskip-1.75\baselineskip

{\footnotesize
\halign{\tabskip1em\bfseries#\unskip&\hfil(#\unskip)\hfil&#\unskip\hfil\cr
0.9  & 2022/09/22 & initial release.\cr
0.9a & 2022/09/23 & doc fixes, mention \ctanpackage{longfbox}.\cr
0.9b & 2022/10/01 & - fix "placement of titled-frame title
                                  is not backwards compatible" (\ghissue{2}).\cr
\omit&\omit& - |\colorframedTitleBarFrame| as workaround to upstream
                issues with titled-frame (\ghissue{3}, \ghissue{4}).\cr
\omit&\omit& - add link to \ghissue{5} for usage with list items,
               other doc improvements such as \ghissue{1}.\cr
1.0 & 2026/11/12 & tagging support (section~\ref{sec:tagging}).\cr
1.1 & 2026/11/16 & tagging: \cr
\omit&\omit& - each environment (inc.\@ `leftbar') is a |Sect|,\cr
\omit&\omit& - the title of a
                     titled-frame is its |Caption| (\ghissue{6}).\cr
\omit&\omit& titled-frame:\cr
\omit&\omit& - defaults provided for |shadecolor|, |TFFrameColor| and
               |TFTitleColor| (\ghissue{9}),\cr
\omit&\omit& - \emph{\bfseries breaking change} it now uses |\colorframedTitleBarFrame|,
hence ceases\cr
\omit&\omit& \phantom{-} producing exact same output as \ctanpackage{framed}'s original (this is reversible by user),\cr
\omit&\omit& - new customization macros, inclusive of layout parameters,\cr
\omit&\omit& - the continuation mark does not require \ctanpackage{amssymb} anymore but
uses its\cr
\omit&\omit& \phantom{-}  |\blacktriangleright| if loaded.\cr
\omit&\omit& doc: summary of the customization interface (section~\ref{sec:summary}).\cr
}}

\vskip-\baselineskip\vskip0pt\relax

\section{Description}


This package, originally delivered in 2022, fixes multiple sources of
potential colour leaks one encounters with the environments from the original
package \ctanpackage{framed}.

In November 2026, with releases |1.0| and |1.1|, it got extended with tagging
support. Thanks to Fable 5.2, Matthew Bertucci and Ulrike Fischer.
See section~\ref{sec:tagging}.

Release |1.1| slightly modifies the layout of the `titled-frame' environment
(earlier releases mentioned to the user some issues with the title rendering
macro used by the original package, and provided a replacement
|\colorframedTitleBarFrame| but did not use it per default).

\begin{titled-frame}{Technical brief on the colour leaks}
  Typically, colour leaks occurred if using |\color| at top level or with a
  scope including what will be a page break inside the rendered environments,
  or more subtly also when using |\textcolor| with an argument ending up being
  split at a page break.

  This latter type of colour leak (or colour disappearance) is the
  more challenging one as the fix requires modifications or
  replacements not only of some of the \ctanpackage{framed}.sty
  macros (such as its |\CustomFBox|, which \colorframed overwrites)
  but also to some \LaTeX{} internals, as some environments of
  \ctanpackage{framed}.sty rely on usage of |\fbox| or |\colorbox|.
  Rather than overwriting internal \LaTeX{} macros such as
  |\@frameb@x| or |\color@b@x|, \colorframed simply replaces |\fbox|
  and |\colorbox| in the \ctanpackage{framed}.sty environments by
  appropriate substitutes.

  I am aware \ctanpackage{tcolorbox} package documentation explains at
  least one colour issue which looks similar to those fixed
  here in \ctanpackage{framed} context, and that the fix overthere uses
  an extra colour stack, hence is not \XeLaTeX{} compatible
  currently.

  The problems are solved here without involving an extra
  colour stack, hence the fixes work also with \XeLaTeX.  None of the
  \LaTeX{} internals are modified.
\end{titled-frame}

\section{The environments from \ctanpackage{framed}}

  We advise the reader to first read the \ctanpackage{framed} 
  documentation to become familiar with the interface, prior to
  continue with this documentation.  But the people in a hurry can
  also check directly Section~\ref{sec:summary}.

\begin{titled-frame}{A list of the environments from package \ctanpackage{framed}}
  This list indicates which boxing macros are
  used in the original, and their replacement (this technical information has no
  direct relevance to user level usage).
% (investigate later why something such as shortverb |#| in
% preamble does not work)
\halign{\bfseries#\hfil&(#\unskip)~\hfil&#\hfil\cr
%
  framed & |\fbox| & Replaced by specialization of own \rlap{\expandafter|\string\CustomFBox|.}\cr
%
  oframed & |\CustomFBox| & \colorframed uses a redefined |\CustomFBox|.\cr
%
  titled-frame & |\CustomFBox| & \emph{id.}\cr
%
  shaded & |\colorbox| & Replaced by |\colorframedcolorbox|.\cr
%
  shaded* & |\colorbox| & \emph{id.}\cr
%
  snugshade & |\colorbox| & \emph{id.}\cr
%
  snugshade* & |\colorbox| & \emph{id.}\cr
%
  leftbar & none & This one does not use any boxing macro.\cr
}
\end{titled-frame}
The previous box was an example of use of the `titled-frame' environment.
\begin{titled-frame}{THE CONTINUATION LABEL AND \ctanpackage{amssymb}}
  The continuation label used by the `titled-frame' environment of
  \ctanpackage{framed} is |$\blacktriangleright$|
  (which despite its name reacts to current text colour setting).
  It requires to
  the best of the author knowledge loading \ctanpackage{amssymb} or
  some other math symbols package, and without it a `titled-frame' crossing
  a page gave an ``Undefined control sequence'' error.

  Since release |1.1| the label is |\colorframedContinuationMark|.  Its
  default uses |$\blacktriangleright$| if this symbol is defined at
  |\begin{document}|, and else
  |$\triangleright$|, which needs no package.

  % TODO: maybe restructure the documentation so that user does not have
  % to actually read the one of the original \ctanpackage{framed} package.
\end{titled-frame}
%
  `titled-frame' is an environment with
  one mandatory argument which provides the title of the
  frame, which is repeated after a page break with |(cont)|
  appended. 

  \colorframed adds the possibility to colorize separately the continuation
  label.  For example we used
\begin{verbatim}
\renewcommand\colorframedTFconlabcolorcommand{\color{TFTitleColor}}
\end{verbatim}
  and the default definition of this macro is to do nothing (and then the
  symbol obeys the |TFFrameColor|).
 
  `titled-frame' uses the colours |TFFrameColor| and |TFTitleColor|.  Since
  release |1.1|, if the document does not define them, they default to
  those used here (|teal!20| in \ctanpackage{xcolor} notation, and a dark
  purple, |rgb| |.5,0,.2|); formerly, and following on the original package,
  they were left undefined.  Using `titled-frame' in the document
  without having defined them caused \ctanpackage{color} (or \ctanpackage{xcolor})
  to report an error.

  Similarly, the original package leaves undefined the |shadecolor| used by
  the `shaded' and `snugshade' environments. It now defaults to
  |lightgray!25|.

  These colour defaults are set at |\begin{document}|, if the
  colours have been left undefined til then.

\medskip
% check why topsep influences separation of item 1 and 2
% it shouldn't? hmm... ah yes I think framed itself uses \topsep...
%\begin{enumerate}[noitemsep,topsep=6pt,font=\normalcolor]
% j'utilise enumitem+noitemsep sinon je vois dans la partie ombrée
% de l'espace supplémentaire au début de l'item (peut-être aussi
% lié à l'emploi du package parskip)
% \colorlet{shadecolor}{lightgray!25}


%\begin{footnotesize}
\begin{itemize}[noitemsep,topsep=3pt,% influences strangely item separation
                         parsep=3pt]
\begin{shaded}
\item
\emph{%
    The current box is an example of \emph{`shaded'}
    environment. See the
    \ghissue[repository issue ]{5} for some comments about how to use
    such environment with list items, if the environment is to start
    at start of the item, as here.
}
\end{shaded}

\begin{snugshade}
\item \emph{This is an example of \emph{`snugshade'}
    environment. It shares with \emph{`shaded'} the usage of |shadecolor|.}
\end{snugshade}

\begin{snugshade*}
\item \emph{This is an example of \emph{`snugshade*'}.}
\end{snugshade*}

% \begin{snugshade}
% \item
% %
%   The `titled-frame' environment was in effect broken in recent \LaTeX\ which
%   has modified how |\smash| behaves (the continuation label created a blank
%   line interrupting the framing); \colorframed fixes this infelicity in
%   passing.

%   Since release |1.1| three things which the definition of `titled-frame'
%   in \ctanpackage{framed}.sty hard-codes are macros.  Here they are with
%   their defaults:
% \begin{verbatim}
% % the mark at the bottom right of a frame continued on the next page
% \newcommand\colorframedContinuationMark{%
%   \ifdefined\blacktriangleright $\blacktriangleright$\else $\triangleright$\fi}
% % the title after a page break, from the title of the frame
% \newcommand\colorframedContinuedTitle[1]{#1\ (cont)}
% % what is applied to the title: a command with one argument
% \newcommand\colorframedTitleFormat{\textbf}
% \end{verbatim}
%   For example:
% \begin{verbatim}
% \renewcommand\colorframedContinuedTitle[1]{#1 (suite)}
% \renewcommand\colorframedTitleFormat[1]{\textsf{\bfseries #1}}
% \end{verbatim}

%   The thickness of the frame and its separation from the contents were
%   hard-coded too, and are now also macros.  They are not length registers:
%   change them with |\renewcommand|, not with |\setlength|.
% \begin{verbatim}
% \newcommand\colorframedTitledFrameRule{2pt}
% \newcommand\colorframedTitledFrameSep{8pt}
% \end{verbatim}

%   The expert user who has read the original \ctanpackage{framed} package
%   documentation (|texdoc framed|) will have no difficulty starting from the
%   actual definition in this package source code of the `titled-frame'
%   environment to define one's own environment.
% \end{snugshade}

% \begin{shaded} % nesting does not work
\begin{framed}
\item
\emph{(one can not nest environments of \ctanpackage{framed}.sty, else we would
  have done so here.)}

\textcolor{blue}{(Here is an attempt to use the {`framed'} environment
  around a list item; we can see an unexpected
  induced indentation of the
  paragraph. And, by the way, there is no {`snugframe'} environment which would
  let the border fit not the whole width but only the indented item.)}
\end{framed}
% \end{shaded} % nesting does not work

\begin{snugshade}
\item The layout of the |\TitleBarFrame| of \ctanpackage{framed} has
  problems, which show up for example if |\fboxsep| and |\fboxrule| are
  given other values than those of `titled-frame' (see on this the
  repository issues \ghissue{3} and \ghissue{4}).  So \colorframed |0.9b|
  provided a replacement, which handles differently the horizontal and
  vertical placement of the title, and lets a long title use several lines.

  Its name is |\colorframedTitleBarFrame|.

  {\bfseries Since release |1.1| the `titled-frame' environment uses this
  replacement:} formerly this had to be opted-for via a redefinition of the
  environment.  Compared to release |1.0| the title and the continuation
  mark are thus placed a bit differently.  The former layout is recovered
  with
\begin{verbatim}
\let\colorframedTitleBarFrame\TitleBarFrame
\end{verbatim}

%   The layout of |\colorframedTitleBarFrame| obeys three macros (again not
%   length registers), shown here with their defaults:
% \begin{verbatim}
% % horizontal distance between the frame and the title, on each side
% \newcommand\colorframedTitleBarHSep{\fboxsep}
% % vertical space above and below the title in its bar
% \newcommand\colorframedTitleBarVSep{0.8ex}
% % horizontal distance between the frame and the continuation mark
% \newcommand\colorframedContinuationMarkSep{3pt}
% \end{verbatim}
%   The first and the third replace two macros of release |0.9b|, which
%   are their actual defaults, so that a document redefining these old names
%   still works:
% \begin{verbatim}
% \colorframedTFtitlesep
% \colorframedTFconlabsep
% \end{verbatim}
%   Inside `titled-frame' the value of |\fboxsep| is the separation between
%   frame and contents: with the defaults the title is thus aligned with the
%   contents of the frame.

\end{snugshade}
\end{itemize}

%\end{footnotesize}



% The aim of \colorframed regarding \ctanpackage{framed} existing
% code base is strictly limited to fixing the colour leak issues,
% there is no general intent to modify the existing environments of
% \ctanpackage{framed} for them to acquire additional capabilities and
% customizability.

Already we have mentioned
|\colorframedTFconlabcolorcommand|
whose default definition let it expands to nothing at all (the continuation label
then inherits the |TFFrameColor| colour).

Regarding the `framed' environment, \colorframed adds
|\colorframedbordercolorcommand|
which expands by default to |\normalcolor|.  It influences the colour of the
framing done by environment `framed', the original having no such
customizability.  Do not redefine it to do nothing, it always should set some
colour, else the borders may display colour loss after a page break.

For example
\begin{verbatim}
\setlength{\FrameRule}{5pt}
\setlength{\FrameSep}{9pt}
\renewcommand\colorframedbordercolorcommand{\color{gray!50}}
\end{verbatim}
configures the next usage of `framed'.

\setlength{\FrameRule}{5pt}
\setlength{\FrameSep}{9pt}
\renewcommand\colorframedbordercolorcommand{\color{gray!50}}
\begin{framed}
  This environment allows indeed customization of the border width
  and of the separation with contents, via |\FrameRule| and
  |\FrameSep|.

  The length |\FrameSep| influences also `oframed', `shaded', and `shaded*',
  but `snugshade' and `snugshade*' employ |\fboxsep| rather.

  |\FrameRule| influences both `framed' and `oframed'.
\end{framed}

\section{Summary of the customization interface}
\label{sec:summary}

This section was written on November 16 by Fable 5.2 (send complaints
to \url{mailto:fable@anthropic.com}, subhject line |colorframed|).  The human
intervened minimally afterwards.

It lists the colours and the commands which matter for
customizing the environments.  What has a name starting with |\colorframed|
is provided by \colorframed, all the rest by \ctanpackage{framed}, whose
documentation (|texdoc framed|) is the reference for it.

\subsection{The `titled-frame' environment}

The macros of table~\ref{tab:titledframe} exist since release |1.1| and are
changed with |\renewcommand|.  Those giving dimensions are macros, not
length registers.

\begin{table}[!htb]
\centering
\rowcolors{2}{}{lightgray!25}
\begin{tabular}{l>{\raggedright\arraybackslash}p{.52\linewidth}}
  \emph{command}&\emph{role and default}\\[2pt]
  |\colorframedTitleFormat|&has one argument: is applied to the title;
     default |\textbf|\\
  |\colorframedContinuedTitle|&has one argument, the title: gives the title
     used after a page break; default |#1\ (cont)|\\
  |\colorframedContinuationMark|&the mark at the bottom right of a frame
     which continues on the next page; default |$\blacktriangleright$|\\
  |\colorframedTitledFrameRule|&the thickness of the frame; default |2pt|\\
  |\colorframedTitledFrameSep|&the separation between frame and contents;
     default |8pt|\\
  |\colorframedTitleBarHSep|&the horizontal distance between the frame and
     the title, on each side; default |\fboxsep|\\
  |\colorframedTitleBarVSep|&the vertical space above and below the title
     in its bar; default |0.8ex|\\
  |\colorframedContinuationMarkSep|&the horizontal distance between the
     frame and the continuation mark; default |3pt|\\
\end{tabular}
\caption{The macros of `titled-frame'}\label{tab:titledframe}
\vspace*{2\baselineskip}\hrule height 0pt width \linewidth
\end{table}

The default continuation mark is |$\triangleright$| if |\blacktriangleright|
is not defined.  The last three macros of the table are parameters of the
command which draws the frame (see table~\ref{tab:colorframedcommands}).
For the colours see tables~\ref{tab:colours} and~\ref{tab:colourcommands}.

\subsection{Colours}

The colours (table~\ref{tab:colours}) are changed with |\definecolor| or
|\colorlet|.  The defaults exist since release |1.1| and are from \colorframed: they are set at
|\begin{document}| for those of the three colours which the preamble has
not defined.

\begin{table}[!htb]
\centering
\rowcolors{2}{}{lightgray!25}
\begin{tabular}{l>{\raggedright\arraybackslash}p{.45\linewidth}l}
  \emph{colour}&\emph{used by}&\emph{default}\\[2pt]
  |shadecolor|&`shaded', `shaded*', `snugshade', `snugshade*': the
                background&|lightgray!25|\\
  |TFFrameColor|&`titled-frame': the frame and the title bar&|teal!20|\\
  |TFTitleColor|&`titled-frame': the text of the title&|rgb| |.5,0,.2|\\
\end{tabular}
\caption{The colours}\label{tab:colours}
\vspace*{2\baselineskip}\hrule height 0pt width \linewidth
\end{table}

Two commands set colours (table~\ref{tab:colourcommands}).  They are changed
with |\renewcommand|.

\begin{table}[!htb]
\centering
\rowcolors{2}{}{lightgray!25}
\begin{tabular}{l>{\raggedright\arraybackslash}p{.3\linewidth}l}
  \emph{command}&\emph{used by}&\emph{default}\\[2pt]
  |\colorframedbordercolorcommand|&`framed', `oframed': the colour of the
     rules&|\normalcolor|\\
  |\colorframedTFconlabcolorcommand|&`titled-frame': the colour of the
     continuation mark&empty\\
\end{tabular}
\caption{The commands setting colours}\label{tab:colourcommands}
\end{table}

The one for the rules must always set a colour.  If the one for the
continuation mark is empty, this mark has the colour |TFFrameColor|.

\subsection{Dimensions}

In table~\ref{tab:dimensions} the first four are lengths, to be changed with
|\setlength|; the last one is a macro.

\begin{table}[!htb]
\centering
\rowcolors{2}{}{lightgray!25}
\begin{tabular}{l>{\raggedright\arraybackslash}p{.55\linewidth}l}
  \emph{name}&\emph{used by}&\emph{default}\\[2pt]
  |\FrameRule|&`framed', `oframed': the thickness of the rules&|\fboxrule|\\
  |\FrameSep|&`framed', `oframed', `shaded', `shaded*': the separation
     between frame and contents&|3\fboxsep|\\
  |\fboxsep|&`snugshade', `snugshade*': the same separation&|3pt|\\
  |\OuterFrameSep|&all environments: the vertical space before and
     after&|\topsep|\\
  |\FrameHeightAdjust|&all environments: the height of the frame above the
     baseline at the top of a page&|6pt|\\
\end{tabular}
\caption{The dimensions}\label{tab:dimensions}
\end{table}

The `titled-frame' environment obeys none of |\FrameRule| and |\FrameSep|:
it has its own parameters, see next.  The bar of `leftbar' (|3pt|) and its
distance to the contents (|10pt|) are fixed in its definition.


\subsection{Commands for defining environments}

See the documentation of \ctanpackage{framed} for the general method.  It
provides the commands of table~\ref{tab:framedcommands}, and \colorframed
adds those of table~\ref{tab:colorframedcommands}.

\begin{table}[!htb]
\centering
\rowcolors{2}{}{lightgray!25}
\begin{tabular}{l>{\raggedright\arraybackslash}p{.52\linewidth}}
  \emph{command}&\emph{role}\\[2pt]
  |\MakeFramed{<settings>}|&starts the framed material\\
  |\endMakeFramed|&ends it\\
  |\FrameRestore|&for the \emph{settings}: restores some text settings\\
  |\width|&for the \emph{settings}: the width added by the frame\\
  |\FrameCommand|&draws the frame around its argument\\
  |\FirstFrameCommand|&the same for the first piece of a frame split across
     pages; the default is to use |\FrameCommand|\\
  |\MidFrameCommand|&the same for the middle pieces\\
  |\LastFrameCommand|&the same for the last piece\\
  |\CustomFBox|&has seven arguments: a frame whose four rules have
     independent thicknesses (redefined by \colorframed)\\
  |\OpenFBox{<top>}{<bottom>}|&a frame, with the given thicknesses of the
     top and bottom rules\\
  |\TitleBarFrame[<mark>]{<title>}|&a frame with a title bar and an
     optional continuation mark (redefined by \colorframed)\\
\end{tabular}
\caption{Commands of \ctanpackage{framed} for defining environments}\label{tab:framedcommands}
\end{table}

\begin{table}[!htb]
\centering
\rowcolors{2}{}{lightgray!25}
\begin{tabular}{l>{\raggedright\arraybackslash}p{.52\linewidth}}
  \emph{command}&\emph{role}\\[2pt]
  |\colorframedcolorbox{<colour>}|&a coloured background; to be used in
     place of |\colorbox|\\
  |\colorframedTitleBarFrame|&same syntax as |\TitleBarFrame|: a variant
     with another placement of the title, used by `titled-frame'; for its
     parameters see table~\ref{tab:titledframe}\\
\end{tabular}
\caption{Commands of \colorframed for defining environments}\label{tab:colorframedcommands}
\end{table}

A frame command should not use |\fbox|, |\colorbox| or |\fcolorbox|: they
are what causes the colour leaks which this package fixes.

\section{Tagged PDF}
\label{sec:tagging}

\begin{shaded}
\emph{The tagging support (the added code, the test files and tools of the
repository, and the present section) was written by Claude, the AI model of
Anthropic (Claude Fable 5.2) on 2026/11/12.  It was then finalized by the
same AI on 2026/11/16.}
\end{shaded}

Since release |1.0| the environments of \ctanpackage{framed}, as modified by
\colorframed, can be used in a document which activates the tagging of the PDF
via |\DocumentMetadata| (with |tagging=on|).  This was developed and tested
with pdf\LaTeX{} and \LuaLaTeX, using the \LaTeX{} release |2026-11-01| and
\ctanpackage{tagpdf} |1.0i| and |1.0j|.  Two of the test files of the repository were
also compiled with success using \XeLaTeX.

There is nothing to do on user side, and no new user command.  A document not
using |\DocumentMetadata| is not concerned at all: none of the code added for
tagging is executed, and its output is the same as if this code did not
exist.

Here is what happens in a tagged document:
\begin{itemize}[noitemsep,topsep=3pt,parsep=3pt]
\item Each environment is a |Sect| structure, which contains what the
  contents of the environment give when tagged as they would be without it.
  This is what \ctanpackage{tcolorbox} does for its boxes.  It applies to
  all environments, `leftbar' included.  (At release |1.0| no environment
  had a structure.)
\item With pdf\LaTeX{} a paragraph which \ctanpackage{framed} had split
  across two pages was wrongly tagged (its marked content was left open at the
  bottom of the first page and its continuation on the next page was not
  tagged at all).  This is fixed.  \LuaLaTeX{} had no such problem.
\item The title of a `titled-frame' (more generally, the title argument of
  |\TitleBarFrame| or of |\colorframedTitleBarFrame|) was not tagged.  It is
  now a |Caption| structure, the first child of the |Sect| of its frame,
  again as with \ctanpackage{tcolorbox}.  The title may contain mathematics
  or |\emph|.  (At release |1.0| it was a paragraph before those of the
  frame.)
\item The titles repeated after page breaks (those with |(cont)| appended)
  and the continuation labels are marked as artifacts.  This applies to the
  titles coming from |\MidFrameCommand| and |\LastFrameCommand|.
\item The rules and the coloured backgrounds drawn by the environments are
  marked as artifacts.  This is needed with pdf\LaTeX{} only, as \LuaLaTeX{}
  does it on its own for all material which is not tagged.
\end{itemize}

%\begin{footnotesize}
\begin{snugshade}
  \textbf{Technical notes.}
\begin{itemize}[noitemsep,topsep=3pt,parsep=3pt]
\item A title is typeset when the frame is drawn, hence after the contents of
  the frame.  To let it nevertheless come first in the structure tree, the
  package must know at the start of the environment that there will be a
  title, and it knows it only from the previous compilation.  So a document
  with titled frames needs one more compilation; as long as this information
  is missing the |Caption| comes after the contents of its frame and this
  warning is issued:
\begin{verbatim}
Package colorframed Warning: Titles of frames are not at their place in the
(colorframed)                structure tree. Rerun to get them right.
\end{verbatim}
\item All of the above also applies to an environment of your own if its
  |\FrameCommand| is built with |\CustomFBox| or |\colorframedcolorbox|, or
  with one of the two title bar macros.  If it is built with |\fbox| or
  |\fcolorbox| (which should be avoided anyhow, see the next section) then,
  with pdf\LaTeX, the rules they draw are not marked as artifacts.  This is
  not specific to frames: with pdf\LaTeX{} the \LaTeX{} kernel currently
  also leaves the rules of a |tabular| unmarked.
\item In a tagged document (and only there) \colorframed redefines the
  `leftbar' environment and these internal macros of
  \ctanpackage{framed}.sty:
\begin{verbatim}
\fb@put@frame, \fb@putboxa, \fb@sizeofframe, \TF@Title
\end{verbatim}
  and it adds code at the start of |\MakeFramed| and at the end of
  |\endMakeFramed| (for the |Sect| structure).
  The frame commands which \ctanpackage{framed} executes only to measure the
  frame are executed with tagging suspended.
\item Only public commands of \ctanpackage{tagpdf} are used.  One of them
  needed a workaround (the package creates a variable which
  \ctanpackage{tagpdf} should have created), see
  \href{https://github.com/latex3/tagpdf/issues/152}{tagpdf issue \#152}.
  This is fixed in \ctanpackage{tagpdf} |1.0j|; the workaround only acts
  with |1.0i|.
\item The repository contains test files (|test_tagging_*.tex|), a script
  compiling them with both engines and checking the tagging of the resulting
  PDFs, and a memo (|TAGGING_MEMO.md|) with more details.  The PDFs
  were not submitted to a PDF/UA validator.
\end{itemize}
\end{snugshade}
%\end{footnotesize}

\section{Technicalities, musings about future}

\begin{snugshade}
I first developed the analysis of the colour leaks/losses at page breaks with
\ctanpackage{framed} on occasion of some contributions I made to
the \href{https://github.com/sphinx-doc/sphinx}{Sphinx project} and I am
transferring here the gained knowledge.

The key thing is that the boxes handled by \ctanpackage{framed}.sty may
contain isolated colour push or colour pop.  We must make
sure an isolated colour push, if followed by colour changes,
is always followed by paired ones, and never by a colour pop
from a colour command originated "prior" and symmetrically that a sole
colour pop does not follow a yet unpaired colour push from some other
colour command related to the framing.

This means we can not ever use things such as |\fbox|, |\colorbox| or
|\fcolorbox| (whether or not \ctanpackage{xcolor} is loaded) as they will
cause colour pops after a possibly isolated colour push contained in the
(already boxed) contents which are fetched to them as arguments by
\ctanpackage{framed}.sty internals.  We must re-implement them otherwise.
This is what is done here, without touching the \LaTeX\ internal macros
themselves.

Some portion of the macro file is occupied with the
`titled-frame' environment of \ctanpackage{framed}.sty, which was broken by an
upstream LaTeX change related to |\smash|, and has obvious problems
apart from that.
Further "obvious problems" do exist for the other \ctanpackage{framed}.sty
environments but it is not the matter of this package to fix them.
Perhaps in future another package will be provided based upon the
work here and adding a completely new environment fixing the "obvious
problems" (some of them being simply lack of customizability).

The author has developed based upon usage of \ctanpackage{pict2e}
breakable boxes with round corners, background colour, optional
shadow (possibly inset), and other goodies and was planning on
incorporating this environment into the package at some time in future.

% Hopefully this addition will be done when time will permit.

% \thispagestyle{empty}
% \enlargethispage{2\baselineskip}

%\colorlet{shadecolor}{lightgray!50}
% \footnotesize
  But after initial release made it to CTAN on
  2022/09/22 I became aware of \ctanpackage{longfbox} which
  provides already such \ctanpackage{pict2e} breakable boxes with
  rounded corners (even elliptical arcs), and furthermore with a
  CSS-like interface which is exactly what I had done on my side
  too... I need to check more \ctanpackage{longfbox} before a
  decision is made here!  Perhaps it will be better to keep
  \colorframed as it is currently and
  extras such as new \ctanpackage{pict2e}-based boxes with a key-value
  interface to `inline' or `display' boxing macros and environments
  should make it to another package (loading \colorframed of course).

  Of course, such a package would remain limited in its graphics abilities
  (and customizability) in comparison to the customizable boxing environments
  provided by package \ctanpackage{mdframed} or \ctanpackage{tcolorbox} but
  testing with my own \ctanpackage{pict2e}-based boxes showed significant
  speed-up in build time compared to using \ctanpackage{framed}+|\tcbox| or
  the "breakable" option of \ctanpackage{tcolorbox}.

\end{snugshade}
\centerline{\hrulefill documentation ends here\hrulefill}
\end{document}
