summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/caption/subcaption.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/caption/subcaption.dtx')
-rw-r--r--Master/texmf-dist/source/latex/caption/subcaption.dtx1868
1 files changed, 1524 insertions, 344 deletions
diff --git a/Master/texmf-dist/source/latex/caption/subcaption.dtx b/Master/texmf-dist/source/latex/caption/subcaption.dtx
index 3dc8cca22e0..38104d18ce3 100644
--- a/Master/texmf-dist/source/latex/caption/subcaption.dtx
+++ b/Master/texmf-dist/source/latex/caption/subcaption.dtx
@@ -2,7 +2,7 @@
%
% This is file `subcaption.dtx'.
%
-% Copyright (C) 2007-2020 Axel Sommerfeldt (axel.sommerfeldt@f-m.fm)
+% Copyright (C) 2007-2022 Axel Sommerfeldt (axel.sommerfeldt@f-m.fm)
%
% --------------------------------------------------------------------------
%
@@ -27,53 +27,47 @@
% caption.sty, caption-light.sty, caption2.sty, caption3.sty,
% caption-ams-smf.sto, caption-beamer.sto, caption-elsarticle.sto,
% caption-koma.sto, caption-memoir.sto, caption-ntg.sto,
-% caption-thesis.sto, bicaption.sty, ltcaption.sty, subcaption.sty,
-% and the user manuals
-% caption-deu.tex, caption-eng.tex, caption-rus.tex.
+% caption-thesis.sto, bicaption.sty, ltcaption.sty, subcaption.sty.
%
% \fi
-% \CheckSum{221}
+%
+% \CheckSum{468}
%
% \iffalse
%<*driver>
\NeedsTeXFormat{LaTeX2e}[1994/12/01]
-\ProvidesFile{subcaption.drv}[2020/08/24 v1.3 Adds a sub-caption feature to the caption package]
+\ProvidesFile{subcaption.drv}[2022/02/20 v1.5 Adds a sub-caption feature to the caption package]
\hbadness=9999 \newcount\hbadness \hfuzz=74pt % Make TeX shut up.
%\errorcontextlines=3
%
\documentclass{ltxdoc}
\setlength\parindent{0pt}
\setlength\parskip{\smallskipamount}
+\addtolength\marginparwidth{15pt}
%
-\newcommand\LineBreak{\linebreak[3]}
-\newcommand\PageBreak{\pagebreak[3]}
\usepackage{ifpdf}
\ifpdf
\usepackage{mathptmx,courier}
\usepackage[scaled=0.90]{helvet}
- \addtolength\marginparwidth{15pt}
- \ifdim\paperheight=297mm % a4paper
- \renewcommand\LineBreak{\\}
- \renewcommand\PageBreak{\clearpage}
- \fi
\fi
%
\usepackage[bottom]{footmisc}
-\usepackage{array,graphicx,overpic,pict2e,diagbox}
+\usepackage{array,diagbox,graphicx,overpic,pict2e,stackengine,tikz}
%
\PassOptionsToPackage{breaklinks=true}{hyperref}
\usepackage{hypdoc}
\ifpdf\usepackage{hypdestopt}\fi
\hypersetup{pdfkeywords={LaTeX, package, subcaption},pdfstartpage={},pdfstartview={}}
%
-\usepackage{subcaption}[2011/08/01] % needs v1.1 or newer
+\usepackage{caption}[2022/01/07] % needs v3.6 or newer to typeset this document
+\usepackage{subcaption}[2022/01/07] % needs v1.5 or newer to typeset this document
\DeclareCaptionSubType*[arabic]{table}
\captionsetup[subtable]{labelformat=simple,labelsep=colon}
%
\newcommand*\purerm[1]{{\upshape\mdseries\rmfamily #1}}
\newcommand*\puresf[1]{{\upshape\mdseries\sffamily #1}}
\newcommand*\purett[1]{{\upshape\mdseries\ttfamily #1}}
-\let\package\puresf
+\let\pkg\puresf
\let\env\purett \let\opt\purett
%
\newcommand*\csmarg[1]{\texttt{\char`\{#1\char`\}}}
@@ -90,8 +84,14 @@
\newenvironment{background}{\par\bigskip\csname background*\endcsname}{\csname endbackground*\endcsname}
\newenvironment{background*}{\small\MARGINSYM{\Mountain}\ignorespaces}{\par}
%
+\makeatletter
\newcommand*\MARGINSYM[1]{\hskip 1sp \marginpar{\raggedleft\textcolor{blue}{{#1}}}}
-\newcommand*\NEW[2]{\MARGINSYM{\vskip2pt\footnotesize#1\\#2}}
+\newcommand*\NEW[1]{\@ifstar{\@NEW{#1}{\vskip2pt}}{\@NEW{#1}{}}}
+\newcommand*\@NEW[3]{\MARGINSYM{#2\footnotesize#1\\#3}}
+\makeatother
+%
+\newcommand*\PageBreak{\pagebreak[3]}
+\newcommand*\changenote[1]{}
%
\begin{document}
\DocInput{subcaption.dtx}
@@ -102,8 +102,8 @@
% \let\subsectionautorefname\sectionautorefname
% \let\subsubsectionautorefname\sectionautorefname
%
-% \def\thispackage{the \package{subcaption} package}
-% \def\Thispackage{The \package{subcaption} package}
+% \def\thispackage{the \pkg{subcaption} package}
+% \def\Thispackage{The \pkg{subcaption} package}
%
% \newcommand\NEWfeature{\NEW{New feature}}
% \newcommand\NEWdescription{\NEW{New description}}
@@ -128,8 +128,7 @@
% \maketitle
%
% \begin{abstract}
-% This package supports typesetting of sub-captions
-% (by using the the sub-caption feature of the \package{caption} package).
+% This package offers an user interface to typeset sub-captions.
% \end{abstract}
%
% \begin{background}
@@ -141,21 +140,27 @@
% \end{background}
%
% \begin{background*}
-% This package demonstrates the usage of |\Declare|\-|Caption|\-|Sub|\-|Type|,
-% |\caption|\-|setup{sub|\-|type}|, and the internal hook
-% |\caption@sub|\-|type|\-|hook| (offered by the \package{caption} package).
+% Since version $3.1$ the \pkg{caption} package offers a low-level interface to typeset sub-captions:
+% |\Declare|\-|Caption|\-|Sub|\-|Type| defines the required counters and internal commands,
+% |\set|\-|caption|\-|sub|\-|type| switches to the sub-caption mode, and
+% |\caption@sub|\-|type|\-|hook| could be extended to apply own code when a switch to the sub-caption mode is in progress.
+%
+% This package demonstrates its usage by offering a high-level user interface additionally.
% \end{background*}
%
% \bigskip
-% \INFO*
+% \INFO
% \emph{Please note:}
-% This package is incompatible with the \package{subfigure} and \package{subfig}
-% packages.
+% This package is incompatible with the \pkg{subfigure} and \pkg{subfig} packages.
%
% \clearpage
% \setcounter{tocdepth}{2}
% \tableofcontents
%
+% \iffalse
+% --------------------------------------------------------------------------- %
+% \fi
+%
% \clearpage
% \section{Loading the package}
%
@@ -163,7 +168,7 @@
% \begin{quote}
% |\usepackage|\oarg{options}|{subcaption}|\quad.
% \end{quote}
-% The options for \thispackage\ are the same ones as for the \package{caption}
+% The options for \thispackage\ are the same ones as for the \pkg{caption}
% package, but specify settings which are used for sub-captions
% \emph{additionally}.
% In fact
@@ -178,12 +183,13 @@
%
% \bigskip
%
-% The default settings for |sub|captions are:
+% \pagebreak[3]
+% The default settings for sub-captions are:
% \begin{quote}
% |margin=0pt,font+=smaller,labelformat=parens,labelsep=space,|\\
% |skip=6pt,list=false,hypcap=false|~\footnote{%^^A
% This means that sub-captions are not listed in the List of Figures
-% or Tables by default, but you can enable that by
+% or Tables by default, but you can enable it by
% specifying the option \texttt{list=true}.}
% \end{quote}
%
@@ -209,6 +215,8 @@
% \item Local `sub' settings
% {\small(|\captionsetup{|\ldots|}| inside |sub|\-|figure| or |sub|\-|table|)}
% \end{enumerate}
+%
+% \pagebreak[3]
% An example:
% \begin{quote}
% |\usepackage[labelsep=quad,indention=10pt]{caption}|\\
@@ -224,14 +232,18 @@
% |labelfont=bf,list=true,textfont=sf|\quad.
% \end{quote}
%
+% \iffalse
+% --------------------------------------------------------------------------- %
+% \fi
+%
% \PageBreak
% \section{The \cs{subcaptionbox} command}
%
% \DescribeMacro\subcaptionbox
-% The easiest way to apply a sub-caption is by using the
-% |\sub|\-|caption|\-|box| command, which automatically aligns the
-% sub-figures resp.~sub-tables by their very first caption line.
+% The |\sub|\-|caption|\-|box| command typesets given content and caption.
+% It automatically aligns the sub-figures resp.~sub-tables by their very first caption line.
%
+% \pagebreak[3]
% Its syntax is:
% \begingroup
% \leftmargini=12pt
@@ -241,29 +253,28 @@
% \end{quote}
% \endgroup
% \begin{small}
-% The arguments \meta{list entry} \& \meta{heading} will be used for
-% typesetting the |\caption|.\par
-% \meta{width} is the width of the resulting |\par|\-|box|; the default value is
-% the width of the contents.\par
-% \meta{inner-pos} specifies how the contents will be justified inside the
-% resulting |\parbox|;
+% The arguments \meta{list entry} \& \meta{heading} will be used for typesetting the |\caption|.
+%
+% \meta{width} is the width of the resulting |\par|\-|box|; the default value is the width of the contents.
+%
+% \meta{inner-pos} specifies how the contents will be justified inside the resulting |\parbox|;
% it can be either `c' (for |\centering|), `l' (for |\ragged|\-|right|),
% `r' (for |\ragged|\-|left|), or `s' (for no special justification).
% The default is `c'.
% (But you can use any justification defined with
% |\Declare|\-|Caption|\-|Jus|\-|ti|\-|fi|\-|ca|\-|tion| as well,
-% e.g.~`|center|\-|last|'.)
+% e.g.: `|center|\-|last|')
% \end{small}
%
% \bigskip
%
-% Using |\sub|\-|caption|\-|box|, the baseline of the resulting box will be placed
-% right between contents and heading, so usually you don't have to care about the
+% When using |\sub|\-|caption|\-|box|, the baseline of the resulting box will be placed
+% right between contents and heading. So usually you don't have to care about the
% vertical alignment of the sub-figures for yourself.
-% Also the hyperlink anchor is placed properly with respect to the |hyp|\-|cap=|
-% setting.
+% Also the hyperlink anchor is placed properly with respect to the |hyp|\-|cap=| setting.
%
-% One example:
+% \pagebreak[3]
+% An example:
% \begin{quote}
% |\begin{figure}|\\
% | \centering|\\
@@ -274,14 +285,13 @@
% | \caption{Two animals}\label{animals}|\\
% |\end{figure}|
% \end{quote}
-% gives the result:\par
% \noindent\begin{minipage}{\linewidth}
-% \setcaptiontype{figure}
+% \captionsetup{type=figure}
% \centering
% \subcaptionbox{A cat\label{cat}}
% {\includegraphics[width=30pt]{cat}}
% \subcaptionbox{An elephant\label{elephant}}
-% {\includegraphics[width=.4\textwidth]{elephant}}
+% {\includegraphics[width=140pt]{elephant}}
% \caption[Two animals]{Two animals~\footnotemark}\label{animals}
% \end{minipage}
% \footnotetext{The pictures were taken with permission from the
@@ -300,12 +310,12 @@
% | |\ldots
% \end{quote}
% \noindent\begin{minipage}{\linewidth}
-% \setcaptiontype{figure}
+% \captionsetup{type=figure}
% \centering
% \subcaptionbox{A cat\label{cat2}}
% [2.5cm]{\includegraphics[width=30pt]{cat}}
% \subcaptionbox{An elephant\label{elephant2}}
-% {\includegraphics[width=.4\textwidth]{elephant}}
+% {\includegraphics[width=140pt]{elephant}}
% \caption{Two animals}\label{animals2}
% \end{minipage}
%
@@ -318,176 +328,295 @@
% \begin{quote}
% | |\ldots\\
% | \subcaptionbox{A cat\label{cat}}|\\
-% | |\textcolor{blue}{\csoarg{.4\cs{linewidth}}}|{\includegraphics{cat}}%|\\
+% | |\textcolor{blue}{\csoarg{.4\cs{textwidth}}}|{\includegraphics{cat}}%|\\
% | \subcaptionbox{An elephant\label{elephant}}|\\
-% | |\textcolor{blue}{\csoarg{.4\cs{linewidth}}}|{\includegraphics{elephant}}|\\
+% | |\textcolor{blue}{\csoarg{.4\cs{textwidth}}}|{\includegraphics{elephant}}|\\
% | |\ldots
% \end{quote}
% \noindent\begin{minipage}{\linewidth}
-% \setcaptiontype{figure}
+% \captionsetup{type=figure}
% \centering
% \subcaptionbox{A cat\label{cat3}}
-% [.4\linewidth]{\includegraphics[width=39.34724pt]{cat}}%^^A
+% [.4\textwidth]{\includegraphics[width=30pt]{cat}}%^^A
% \subcaptionbox{An elephant\label{elephant3}}
-% [.4\linewidth]{\includegraphics[width=.4\textwidth]{elephant}}
+% [.4\textwidth]{\includegraphics[width=140pt]{elephant}}
% \caption{Two animals}\label{animals3}
% \end{minipage}
%
% \bigskip
%
-% \iffalse
+% \begin{background}
+% The |\sub|\-|caption|\-|box| is a |\par|\-|box| with
+% |\set|\-|caption|\-|sub|\-|type| as first contents line.
+% \end{background}
+%
+% \subsection{Comparison with \cs{captionbox}}
+%
+% Both, |\caption|\-|box| (offered by the \pkg{caption} package) and |\sub|\-|caption|\-|box|,
+% put its contents and caption into a |\par|\-|box| of either natural or given width and share the
+% same (mandatory and optional) arguments, but while |\caption|\-|box| uses a regular caption,
+% |\sub|\-|caption|\-|box| uses a sub-caption instead, like ``(a)'' or ``2.1''.
+%
+% \pagebreak[3]
+% So for example the last example would look like this when using |\caption|\-|box|
+% instead of |\sub|\-|caption|\-|box|:
+% \begin{quote}
+% |\begin{figure}|\\
+% | \centering|\\
+% | \captionbox{A cat\label{cat}}|\\
+% | |\csoarg{.4\cs{textwidth}}|{\includegraphics{cat}}%|\\
+% | \captionbox{An elephant\label{elephant}}|\\
+% | |\csoarg{.4\cs{textwidth}}|{\includegraphics{elephant}}|\\
+% |\end{figure}|
+% \end{quote}
% \noindent\begin{minipage}{\linewidth}
-% \setcaptiontype{figure}
+% \captionsetup{type=figure}
% \centering
-% \hbox{\subcaptionbox{An elephant\label{elephant4}}
-% {\includegraphics[width=.4\textwidth]{elephant}}%^^A
-% \vbox{\subcaptionbox{Cat 1\label{cat4.1}}
-% {\includegraphics[width=30pt]{cat}}\par
-% \subcaptionbox{Cat 2\label{cat4.2}}
-% {\includegraphics[width=30pt]{cat}}}}%^^A
-% \caption{Two animals}\label{animals4}
+% \captionbox{A cat\label{cat3.1}}
+% [.4\textwidth]{\includegraphics[width=30pt]{cat}}%^^A
+% \captionbox{An elephant\label{elephant3.1}}
+% [.4\textwidth]{\includegraphics[width=140pt]{elephant}}
% \end{minipage}
-% \bigskip
-% \fi
%
-% \begin{background}
-% The |\sub|\-|caption|\-|box| is a |\par|\-|box| with
-% |\set|\-|caption|\-|sub|\-|type| as first contents line.
% \iffalse
-% Prepared with |\Declare|\-|Caption|\-|Sub|\-|Type| (offered by the
-% \package{caption} package), the caption package command |\set|\-|caption|\-|sub|\-|type|
-% becames available.
-% Analogous to the |\set|\-|caption|\-|type| command of the \package{caption} package,
-% the |\set|\-|caption|\-|sub|\-|type| command sets the sub-type of the box or environment
-% (so |\caption| will typeset a sub-caption instead of an ordinary one),
-% places a proper hyperlink anchor (non-starred variant only),
-% executes options associated with the sub-type etc.
+% --------------------------------------------------------------------------- %
% \fi
-% \end{background}
%
% \PageBreak
-% \section{The subfigure \& subtable environments}
+% \section{The \env{subcaptionblock} environment}
%
-% \DescribeEnv{subfigure}
-% \DescribeEnv{subtable}
-% After loading \thispackage\ the new environments |sub|\-|figure| and
-% |sub|\-|table| are available, which have the same (optional \& mandatory)
-% arguments as the |mini|\-|page| environment:
-% \begin{quote}
-% |\begin{subfigure}|\oarg{outer-pos}\oarg{height}\oarg{inner-pos}\marg{width}\\
-% \ldots\\
-% |\end{subfigure}|
-% \end{quote}
-% and
+% \DescribeEnv{subcaptionblock}
+% \NEWfeature*{v1.5}
+% The |sub|\-|caption|\-|block| environment makes a box with given width.
+% Inside this box the regular caption commands (like |\caption|, |\phantom|\-|caption|, \ldots) could be used to typeset sub-captions.
+%
+% \pagebreak[3]
+% |sub|\-|caption|\-|block| has the same (optional \& mandatory) arguments as the |mini|\-|page| environment:
+% \begingroup
+% \leftmargini=12pt
% \begin{quote}
-% |\begin{subtable}|\oarg{outer-pos}\oarg{height}\oarg{inner-pos}\marg{width}\\
-% \ldots\\
-% |\end{subtable}|
+% |\begin{subcaptionblock}|\oarg{outer-pos}\oarg{height}\oarg{inner-pos}\marg{width}\\
+% | |\ldots\\
+% |\end{subcaptionblock}|
% \end{quote}
-% Inside these environments you use the ordinary |\caption| command
-% for typesetting captions. So this example is the same as the last one,
-% but uses the |sub|\-|figure| environment:
+% \endgroup
+%
+% The default value for \meta{outer-pos} is `b' and the default value for \meta{inner-pos} is `s'.
+% (Note that the default value for \meta{outer-pos} has changed from `c' to `b' in version $1.5$ of \thispackage.)
+%
+% \NEWfeature{v1.2}
+% Beside the \meta{outer-pos} values of `c', `t', and `b', \thispackage\ also offers the
+% values `T' and `B' additionally which align the |sub|\-|figure| at the
+% very top resp.~bottom. (In contrast `t' and `b' align the |sub|\-|figure| at the
+% top resp.~bottom \textit{baseline}.)
+%
+% \bigskip
+%
+% \pagebreak[3]
+% The same example as \autoref{animals3}, but this time using the |sub|\-|caption|\-|block| environment
+% instead of |\sub|\-|caption|\-|box|:
% \begin{quote}
% |\begin{figure}|\\
-% | \begin{|\textcolor{blue}{\texttt{subfigure}}|}[b]{.5\linewidth}|\\
-% | \centering\large A|\\
-% | |\textcolor{blue}{\cs{caption}}|{A subfigure}\label{fig:1a}|\\
-% | \end{|\textcolor{blue}{\texttt{subfigure}}|}%|\\
-% | \begin{|\textcolor{blue}{\texttt{subfigure}}|}[b]{.5\linewidth}|\\
-% | \centering\large B|\\
-% | |\textcolor{blue}{\cs{caption}}|{Another subfigure}\label{fig:1b}|\\
-% | \end{|\textcolor{blue}{\texttt{subfigure}}|}|\\
-% | \caption{A figure}\label{fig:1}|\\
+% | \centering|\\
+% | |\textcolor{blue}{\cs{begin}\csmarg{subcaptionblock}\csmarg{.4\cs{textwidth}}}\\
+% | \centering|\\
+% | \includegraphics{cat}|\\
+% | |\textcolor{blue}{\cs{caption}}|{A cat}\label{cat}|\\
+% | |\textcolor{blue}{\cs{end}\csmarg{subcaptionblock}}|%|\\
+% | |\textcolor{blue}{\cs{begin}\csmarg{subcaptionblock}\csmarg{.4\cs{textwidth}}}\\
+% | \centering|\\
+% | \includegraphics{elephant}|\\
+% | |\textcolor{blue}{\cs{caption}}|{An elephant}\label{elephant}|\\
+% | |\textcolor{blue}{\cs{end}\csmarg{subcaptionblock}}|%|\\
+% | \caption{Two animals}\label{animals}|\\
% |\end{figure}|
% \end{quote}
+% \noindent\begin{minipage}{\linewidth}
+% \captionsetup{type=figure}
+% \centering
+% \begin{subcaptionblock}{.4\textwidth}
+% \centering
+% \includegraphics[width=30pt]{cat}
+% \caption{A cat}\label{cat4}
+% \end{subcaptionblock}%
+% \begin{subcaptionblock}{.4\textwidth}
+% \centering
+% \includegraphics[width=140pt]{elephant}
+% \caption{An elephant}\label{elephant4}
+% \end{subcaptionblock}
+% \caption{Two animals}\label{animals4}
+% \end{minipage}
+%
+% \medskip
+%
+% \pagebreak[3]
% Some additional notes:
% \begin{itemize}
-% \item You can override the setttings for a specific subcaption
-% with a |\caption|\-|setup| inside the |sub|\-|figure| or |sub|\-|table| environment, e.g.:
+% \item
+% You can override the setttings for a specific subcaption
+% with a |\caption|\-|setup| inside the |sub|\-|caption|\-|block|, e.g.:
% \begin{quote}
-% |\begin{subfigure}[b]{.5\linewidth}|\\
-% | \centering\large A|\\
+% |\begin{subcaptionblock}{.4\textwidth}|\\
+% | \centering|\\
+% | \includegraphics{owl}|\\
% | |\textcolor{blue}{\cs{captionsetup}\csmarg{skip=3pt}}\\
-% | \caption{A subfigure}\label{fig:1a}|\\
-% |\end{subfigure}|\\
+% | \caption{An owl}\label{owl}|\\
+% |\end{subcaptionblock}|
% \end{quote}
-% \item Hyperlinks targeted to this subfigure will jump to the beginning
-% of the subfigure, and not to the caption of the subfigure
+% \item
+% Just like |figure| or |table|, a |sub|\-|caption|\-|block| could have multiple captions, e.g.:
+% \begin{quote}
+% |\begin{subcaptionblock}{.4\textwidth}|\\
+% | \centering|\\
+% | \includegraphics{cat}|\\
+% | \caption{A cat}\label{cat}|\\
+% | \medskip|\\
+% | \includegraphics{elephant}|\\
+% | \caption{An elephant}\label{elephant}|\\
+% |\end{subcaptionblock}|
+% \end{quote}
+% \item
+% Hyperlinks targeted to this sub-figure will jump to the beginning
+% of the |sub|\-|caption|\-|block|, and not to the |\caption| inside it
% (if |hypcap=true| is set for sub-captions).
% \See{\Ref{hypcap}}
% \end{itemize}
%
-% \NEWfeature{v1.2}
-% Beside the \meta{outer-pos} values of `c', `t', and `b', \thispackage\ also offers the
-% values `T' and `B' additionally which align the |sub|\-|figure| at the
-% very top resp.~bottom. (In contrast `t' and `b' align the |sub|\-|figure| at the
-% top resp.~bottom \textit{baseline}.)
+% \DescribeEnv{subfigure}
+% \DescribeEnv{subtable}
+% The |sub|\-|caption|\-|block| environment is also offered as |sub|\-|figure| resp.~|sub|\-|table|.
+% (And prior version $1.5$ of \thispackage\ it was only available as |sub|\-|figure| resp.~|sub|\-|table|.)
%
-% \bigskip
+% There is no difference in them except the environment name should match the current floating environment,
+% i.e. inside a |figure| a |sub|\-|figure| should be used, and inside a |table| a |sub|\-|table| should be used.
+% Using the wrong sub-environment will cause a warning since \version{1.5} of the \pkg{subcaption} package.
+%
+% So if in doubt, or when writing own \LaTeX\ commands which should work in every floating environment,
+% using |sub|\-|caption|\-|block| is the correct choice.
+%
+% \smallskip
%
% \begin{background}
-% The |subfigure| \& |subtable| environments are just simple |minipage|
+% The |sub|\-|caption|\-|block|, |sub|\-|figure|, and |sub|\-|table| environments are |mini|\-|page|
% environments with |\set|\-|caption|\-|sub|\-|type| as first contents line.
-% These environments are defined with the help of
-% |\For|\-|Each|\-|Caption|\-|Sub|\-|Type|, which executes code for every sub-type
-% declared with |\Declare|\-|Caption|\-|Sub|\-|Type|.
+%
+% |sub|\-|figure| and |sub|\-|table| are defined with the help of
+% |\For|\-|Each|\-|Caption|\-|Sub|\-|Type| offered by the \pkg{caption} package,
+% which executes code for every sub-type declared with |\Declare|\-|Caption|\-|Sub|\-|Type|.
% \end{background}
%
-% \iffalse\PageBreak\fi
-% \section{The \cs{subcaption} command}
+% \iffalse
+% --------------------------------------------------------------------------- %
+% \fi
%
-% \DescribeMacro\subcaption
-% The most flexible way to apply a sub-caption is by using the
-% |\subcaption| command. Its syntax is analogous to the one of the |\caption|
-% command and shares its features:
+% \PageBreak
+% \section{The \env{subcaptiongroup} environment}
+%
+% \DescribeEnv{subcaptiongroup}
+% \NEWfeature*{v1.5}
+% The |sub|\-|caption|\-|group| environment is only switching to the sub-caption mode inside an own \TeX\ group.
+% Inside this environment the regular caption commands (like |\caption|, |\phantom|\-|caption|, \ldots) could be used to typeset sub-captions.
+%
+% \pagebreak[3]
+% Its syntax is:
+% \begingroup
+% \leftmargini=12pt
% \begin{quote}
-% |\subcaption|\oarg{list entry}\marg{heading}\\
-% |\subcaption*|\marg{heading}
+% |\begin{subcaptiongroup}|\\
+% | |\ldots\\
+% |\end{subcaptiongroup}|
% \end{quote}
-% Please note that the |\subcaption| command \emph{must} be applied inside
-% its own box or environment.
+% \endgroup
%
-% An example:
+% \pagebreak[3]
+% There is a starred variant of this environment as well which uses |\set|\-|caption|\-|sub|\-|type*|
+% instead of |\set|\-|caption|\-|sub|\-|type| internally:
+% \begingroup
+% \leftmargini=12pt
+% \begin{quote}
+% |\begin{subcaptiongroup*}|\\
+% | |\ldots\\
+% |\end{subcaptiongroup*}|
+% \end{quote}
+% \endgroup
+%
+% While this gives you great flexibility, it also offers you no help formatting its contents.
+%
+% \pagebreak[3]
+% The same example as \autoref{animals4}, but this time using the |sub|\-|caption|\-|group| environment
+% instead of |\sub|\-|caption|\-|block|:
% \begin{quote}
% |\begin{figure}|\\
-% | \begin{minipage}[b]{.5\linewidth}|\\
-% | \centering\large A|\\
-% | \subcaption{A subfigure}\label{fig:1a}|\\
-% | \end{minipage}%|\\
-% | \begin{minipage}[b]{.5\linewidth}|\\
-% | \centering\large B|\\
-% | \subcaption{Another subfigure}\label{fig:1b}|\\
-% | \end{minipage}|\\
-% | \caption{A figure}\label{fig:1}|\\
+% | \centering|\\
+% | |\textcolor{blue}{\cs{begin}\csmarg{subcaptiongroup}}\\
+% | \centering|\\
+% | \parbox[b]{.4\textwidth}{%|\\
+% | \centering|\\
+% | \includegraphics{cat}|\\
+% | \caption{A cat}\label{cat}}%|\\
+% | \parbox[b]{.4\textwidth}{%|\\
+% | \centering|\\
+% | \includegraphics{elephant}|\\
+% | \caption{An elephant}\label{elephant}}%|\\
+% | |\textcolor{blue}{\cs{end}\csmarg{subcaptiongroup}}\\
+% | \caption{Two animals}\label{animals}|\\
+% |\end{figure}|
+% \end{quote}
+% --or--
+% \begin{quote}
+% |\begin{figure}|\\
+% | \centering|\\
+% | |\textcolor{blue}{\cs{begin}\csmarg{subcaptiongroup}}\\
+% | \centering|\\
+% | \begin{minipage}[b]{.4\textwidth}|\\
+% | \centering|\\
+% | \includegraphics{cat}|\\
+% | \caption{A cat}\label{cat}|\\
+% | \end{minipage}%|\\
+% | \begin{minipage}[b]{.4\textwidth}|\\
+% | \centering|\\
+% | \includegraphics{elephant}|\\
+% | \caption{An elephant}\label{elephant}|\\
+% | \end{minipage}|\\
+% | |\textcolor{blue}{\cs{end}\csmarg{subcaptiongroup}}\\
+% | \caption{Two animals}\label{animals}|\\
% |\end{figure}|
% \end{quote}
-% gives the result:
-% \par\bigskip
% \noindent\begin{minipage}{\linewidth}
-% \setcaptiontype{figure}
-% \begin{minipage}[b]{.5\linewidth}
-% \centering\large A
-% \subcaption{A subfigure}\label{fig:1a}
-% \end{minipage}%^^A
-% \begin{minipage}[b]{.5\linewidth}
-% \centering\large B
-% \subcaption{Another subfigure}\label{fig:1b}
-% \end{minipage}
-% \caption{A figure}\label{fig:1}
+% \captionsetup{type=figure}
+% \centering
+% \begin{subcaptiongroup}
+% \centering
+% \begin{minipage}[b]{.4\textwidth}
+% \centering
+% \includegraphics[width=30pt]{cat}
+% \caption{A cat}\label{cat5}
+% \end{minipage}%
+% \begin{minipage}[b]{.4\textwidth}
+% \centering
+% \includegraphics[width=140pt]{elephant}
+% \caption{An elephant}\label{elephant5}
+% \end{minipage}
+% \end{subcaptiongroup}
+% \caption{Two animals}\label{animals5}
% \end{minipage}
%
% \bigskip
%
% \begin{background}
-% The |\subcaption| command is just a simple combination of
-% |\set|\-|caption|\-|sub|\-|type*| and |\caption|.
+% The |sub|\-|caption|\-|group| environment is a \LaTeX\ environment
+% with |\set|\-|caption|\-|sub|\-|type| as first contents line.
% \end{background}
%
+% \iffalse
+% --------------------------------------------------------------------------- %
+% \fi
+%
% \PageBreak
% \section{The \cs{DeclareCaptionSubType} command}
%
% \DescribeMacro\DeclareCaptionSubType
-% For using the sub-caption feature of the \package{caption} package some
+% For using the sub-caption feature of the \pkg{caption} package some
% commands and counters must be prepared. This is done with
% \begin{quote}
% |\DeclareCaptionSubType|\oarg{numbering scheme}\marg{type}\\
@@ -495,30 +624,35 @@
% \end{quote}
% For the environments |figure| \& |table|, and all the ones
% defined with |\Declare|\-|Floating|\-|Environment| offered by the
-% \package{newfloat} package, this will be done automatically,
+% \pkg{newfloat} package, this will be done automatically,
% but for other environments (e.g.~the ones defined with |\newfloat| offered by the
-% \package{float} package or |\Declare|\-|New|\-|Float|\-|Type| offered by the
-% \package{floatrow} package) this has to be done manually.
+% \pkg{float} package or |\Declare|\-|New|\-|Float|\-|Type| offered by the
+% \pkg{floatrow} package) this has to be done manually.
%
% \medskip
%
% The starred variant provides the sub-caption numbering format
-% \meta{type}|.|\meta{subtype} (e.g.~`|1.2|') while the non-starred variant
-% simply uses \meta{subtype} (e.g.~`|a|').
+% \meta{type}|.|\meta{subtype} (for example `|1.2|') while the non-starred variant
+% simply uses \meta{subtype} (for example `|a|').
%
-% \begin{small}
-% Own numbering formats can be created by redefining |\thesub|\meta{type}, e.g.
-% \begin{quote}|\DeclareCaptionSubType*{figure}|\\
-% |\renewcommand\thesubfigure{\thefigure\alph{subfigure}}|\end{quote}
+% \pagebreak[3]
+% Own numbering formats can be created by redefining |\thesub|\meta{type}, e.g.:
+% \begingroup
+% \leftmargini=12pt
+% \begin{quote}
+% |\DeclareCaptionSubType*{figure}|\\
+% |\renewcommand\thesubfigure{\thefigure\alph{subfigure}}|
+% \end{quote}
+% \endgroup
% would give you sub-caption numbers like `|1b|'.
-% \end{small}
%
% The default numbering scheme is |alph|, but you can use any \LaTeX\ (or self-defined)
-% command name here which converts a counter to a text value, e.g. |arabic|, |roman|,
+% command name here which converts a counter to a text value, e.g.: |arabic|, |roman|,
% |Roman|, |alph|, |Alph|, |fnsymbol|, \ldots
%
+% \pagebreak[3]
% But |\DeclareCaptionSubType| is not only for defining new sub-caption types,
-% you can use this command for re-definitions as well, e.g.
+% you can use this command for re-definitions as well, e.g.:
% \begingroup
% \leftmargini=12pt
% \begin{quote}
@@ -530,7 +664,7 @@
% will give you sub-captions in |table|s like these ones:
% \par\bigskip
% \noindent\begin{minipage}{\linewidth}
-% \setcaptiontype{table}
+% \captionsetup{type=table}
% \centering
% \caption{Two tables}
% \subcaptionbox{Table one}[3cm][c]{\begin{tabular}{cc}A & B\\ C & D\\ \end{tabular}}
@@ -539,11 +673,16 @@
%
% \begin{background}
% |\Declare|\-|Caption|\-|Sub|\-|Type| and |\For|\-|Each|\-|Caption|\-|Sub|\-|Type|
-% are integral parts of the \package{caption} package kernel.
+% are integral parts of the \pkg{caption} package kernel.
% \end{background}
%
+% \iffalse
+% --------------------------------------------------------------------------- %
+% \fi
+%
% \PageBreak
-% \section{References}
+% \section{Cross Referencing}
+% \label{crossreferencing}
%
% The macro |\the|\-\meta{counter} is not only responsible for the look of the \meta{counter},
% but for the look of the references typeset with |\ref|, too. References will be prefixed by
@@ -554,6 +693,7 @@
% |\Declare|\-|Caption|\-|Sub|\-|Type| will give you some options to control the
% internal (re-)definition of |\the|\-\meta{counter} and |\p@|\-\meta{counter}.
%
+% \pagebreak[3]
% \DescribeMacro\thesubfigure
% \DescribeMacro\p@subfigure
% For example |\thesubfigure| and |\p@subfigure| are (as default) internally defined as
@@ -596,23 +736,26 @@
% |\captionsetup[subfigure]{labelformat=opening}|
% \end{quote}
%
-% {\small(Please note that you need to surround redefinitions of |\p@|\-\meta{counter}
+% \bigskip
+%
+% \INFO
+% {\small Please note that you need to surround redefinitions of |\p@|\-\meta{counter}
% with |\makeatletter| and |\makeatother|. See
% \url{http://tex.stackexchange.com/questions/8351/}
-% for details.)}
+% for details.}
%
% \pagebreak[3]
% \subsection{The \cs{subref} command}
% \label{subref}
%
-% While |\ref|\marg{key} (and |\ref*|\marg{key}, if the \package{hyperref}
+% While |\ref|\marg{key} (and |\ref*|\marg{key}, if the \pkg{hyperref}
% package is used) usually gives a combined result representing the main
% caption counter and the sub-caption one, it is sometimes useful to have
% a reference to the sub-caption only. For this purpose you can use
% \begin{quote}
% |\subref|\marg{key}\\
% |\subref*|\marg{key}~\footnote{%^^A
-% Like \cs{ref*}, \cs{subref*} is only available if the \package{hyperref}
+% Like \cs{ref*}, \cs{subref*} is only available if the \pkg{hyperref}
% package\cite{hyperref} is used.}%^^A
% \qquad.
% \end{quote}
@@ -635,12 +778,15 @@
% \label{subrefformat}
%
% \DescribeMacro{subrefformat=}
-% \NEWfeature{v1.1}
+% \NEWfeature*{v1.1}
% By applying |\Declare|\-|Caption|\-|Sub|\-|Type|, or by redefining |\the|\-\meta{counter}
% and |\p@|\-\meta{counter}, you will change the look of references typeset with |\ref|
% \emph{and} |\sub|\-|ref|.
+%
% But maybe you only want to change the output of |\sub|\-|ref| without
% affecting the references typeset with |\ref|?
+%
+% \pagebreak[3]
% This is possible, too, by using the option \opt{subrefformat}:
% \begin{quote}
% |\captionsetup{subrefformat=|\meta{label format}|}|
@@ -650,6 +796,7 @@
% The default one is |simple| which has no decorative elements but simply typeset
% the reference as it is.
%
+% \pagebreak[3]
% For example
% \begin{quote}
% |\captionsetup{subrefformat=parens}|
@@ -658,95 +805,179 @@
% (typeset with |\subref|) like `|(a)|'.
%
% \subsection{Referencing sub-figures without sub-captions}
+% \label{without}
%
-% \DescribeMacro\phantomsubcaption
% \DescribeMacro\phantomcaption
-% \NEWfeature{v1.1}
-% If you don't want to give a sub-figure a caption, because the picture itself
-% already contains the caption, or for some other reason, you can use the command
+% If you don't want to give a sub-figure a caption (yet), because the picture itself
+% already contains the caption, or for some other reason, you could use the command
% \begin{quote}
-% |\phantomsubcaption|
+% |\phantomcaption|
% \end{quote}
-% instead of |\sub|\-|caption|, or
-% -- when inside a |sub|\-|figure| or |sub|\-|table| environment --
-% |\phantom|\-|caption| instead of |\caption|.
-% |\phantom|\-|sub|\-|caption| and |\phantom|\-|caption| do not have any arguments, and
-% they do not generate any output, but give you an anchor for a |\label| command
-% which can be placed afterwards.
-% Furthermore it increases the sub-figure resp. sub-table counter.
+% instead of |\caption|.
%
-% Please note that -- just like |\sub|\-|caption| -- the |\phantom|\-|sub|\-|caption|
-% command \emph{must} be applied inside its own group, box, or environment.
+% |\phantom|\-|caption| is offered by the \pkg{caption} package since version $3.2$ and
+% does not generate any output but increases the sub-figure resp.~sub-table counter
+% and gives you an anchor for a |\label| command which can be placed after it.
%
% \pagebreak[3]
% An example:
% \begin{quote}
% |\begin{figure}|\\
% | \centering|\\
-% | {\includegraphics{cat_with_a}|\\
-% | \phantomsubcaption\label{cat}}|\\
-% | {\includegraphics{elephant_with_b}|\\
-% | \phantomsubcaption\label{elephant}}|\\
-% | \caption{Two animals: \subref{cat} a huge cat,|\\
+% | \begin{subcaptiongroup}|\\
+% | \includegraphics{cat_with_a}|\\
+% | |\textcolor{blue}{\cs{phantomcaption}}|\label{cat}|\\
+% | \includegraphics{elephant_with_b}|\\
+% | |\textcolor{blue}{\cs{phantomcaption}}|\label{elephant}|\\
+% | \end{subcaptionblock}|\\
+% | \captionsetup{subrefformat=parens}|\\
+% | \caption{Two animals: \subref{cat} a cat,|\\
% | and \subref{elephant} an elephant}|\\
+% | \label{animals}|\\
% |\end{figure}|
% \end{quote}
-%
% \noindent\begin{minipage}{\linewidth}
-% \setcaptiontype{figure}
+% \captionsetup{type=figure}
% \centering
-% {\begin{overpic}[width=60pt]{cat}
-% \put(40,34){(a)}
-% \end{overpic}
-% \phantomsubcaption\label{cat6.3}}
-% {\begin{overpic}[width=.4\textwidth]{elephant}
-% \put(60,50){(b)}
-% \end{overpic}
-% \phantomsubcaption\label{elephant6.3}}
+% \begin{subcaptiongroup}
+% \phantomcaption\label{cat6.3}
+% \begin{overpic}[width=30pt]{cat}
+% \put(40,34){\captiontext*{}}
+% \end{overpic}
+% \phantomcaption\label{elephant6.3}
+% \begin{overpic}[width=140pt]{elephant}
+% \put(58,40){\captiontext*{}}
+% \end{overpic}
+% \end{subcaptiongroup}
% \captionsetup{subrefformat=parens}
-% \caption{Two animals: \subref{cat6.3} a huge cat, and \subref{elephant6.3} an elephant}
+% \caption{Two animals: \subref{cat6.3} a cat, and \subref{elephant6.3} an elephant}
% \end{minipage}
%
+% \bigskip
+%
+% \pagebreak[3]
+% \DescribeMacro\captionlistentry
+% If you don't want to give a sub-figure a caption (yet), because the picture itself
+% already contains the caption, or for some other reason, you could also use the command
+% \begin{quote}
+% |\captionlistentry|\marg{list entry}
+% \end{quote}
+% instead of |\caption|.
+%
+% |\caption|\-|list|\-|entry| is offered by the \pkg{caption} package since version $3.3$ and
+% (just like |\phantom|\-|caption|) does not generate any output but increases
+% the sub-figure resp.~sub-table counter
+% and gives you an anchor for a |\label| command which can be placed after it.
+% Additionally to |\phantom|\-|caption| this command puts an entry into the list
+% of figures resp.~tables.
+%
+% \pagebreak[3]
+% An example:
+% \begin{quote}
+% |\begin{figure}|\\
+% | \centering|\\
+% | \begin{subcaptiongroup}|\\
+% | \includegraphics{cat_with_a}|\\
+% | |\textcolor{blue}{\cs{captionlistentry}\csmarg{A cat}}\\
+% | \label{cat}|\\
+% | \includegraphics{elephant_with_b}|\\
+% | |\textcolor{blue}{\cs{captionlistentry}\csmarg{An elephant}}\\
+% | \label{elephant}|\\
+% | \end{subcaptionblock}|\\
+% | \captionsetup{subrefformat=parens}|\\
+% | \caption{Two animals: \subref{cat} a cat,|\\
+% | and \subref{elephant} an elephant}|\\
+% | \label{animals}|\\
+% |\end{figure}|
+% \end{quote}
+%
+% \pagebreak[3]
+% \subsection{Typesetting sub-captions without generating a (new) reference}
+% \label{without2}
+%
+% The |\caption| command is a multi-purpose command:
+% \begin{enumerate}
+% \item It increments the sub-figure resp.~sub-table counter and generates an internal reference which could be used with |\label|
+% \item It puts an entry into the list of figures resp.~tables
+% \item It finally typesets a caption
+% \end{enumerate}
+%
+% When put into a command or into an environment which either evaluates its content more than once or
+% does not like one of the first two actions (for whatever reason), the result could be either an error message or an incorrect
+% result, for example a sub-figure resp.~sub-table counter which was incremented more than once.
+%
+% \DescribeMacro\captiontext
+% In these cases the |\caption| command could be split into
+% |\phantom|\-|caption| which performs step one only (or |\caption|\-|list|\-|entry| which performs steps one and two),
+% and |\caption|\-|text| which performs step three only.
+% This way critical steps could be out-sourced from the target command or environment,
+% for example by prepending |\phantom|\-|caption| and using |\caption|\-|text| inside.
+%
+% \pagebreak[3]
+% The syntax of |caption|\-|text| is
+% \begin{quote}
+% |\captiontext|\oarg{number}\marg{text of sub-caption}\\
+% |\captiontext*|\oarg{number}\marg{text of sub-caption}
+% \end{quote}
+% |\caption|\-|text| is offered by the \pkg{caption} package since version $3.6$ and
+% as opposite to |\caption| it does not increase the sub-figure resp.~sub-table counter
+% and does not give you an anchor for a |\label| command.
+% It typesets the caption only, using existing counter values unless a \meta{number} is given explicitly.
+%
+% For example code please take a look at \Ref{inside}.
+%
% \pagebreak[3]
% \subsection{Where to place the \cs{label} command?}
% \label{label}
%
-% When using |\sub|\-|caption| or |\phantom|\-|sub|\-|caption|,
-% or |\caption| or |\phantom|\-|caption| inside a |sub|\-|figure| or |sub|\-|table| environment,
-% the |\label| can be either placed inside the caption text or right after the |\sub|\-|caption| or
-% |\caption| command, e.g:
+% When |\caption|
+% inside a |caption|\-|sub|\-|block|, |sub|\-|figure|, |sub|\-|table|, or |caption|\-|sub|\-|group| environment,
+% the |\label| can be either placed inside the caption text or right after the command, e.g.:
% \begin{quote}
-% |\subcaption{Some text here\label{label1}}|\\
+% |\caption{Some text here\label{text}}|\\
% \ldots\\
-% |\subcaption{Some other text}\label{label2}}|\\
+% |\caption{Some other text}\label{othertext}|\\
% \ldots\\
-% |\subcaption{Something different}|\\
-% |\label{label3}|
+% |\caption{Something completely different}|\\
+% |\label{differenttext}|
% \end{quote}
%
-% When using the |\sub|\-|caption|\-|box| command, the |\label| should be placed inside
+% When using |\phantom|\-|caption| or |\caption|\-|list|\-|entry|
+% inside a |caption|\-|sub|\-|block|, |sub|\-|figure|, |sub|\-|table|, or |caption|\-|sub|\-|group| environment,
+% the |\label| should be placed right after the command, e.g.:
+% \begin{quote}
+% |\phantomcaption\label{this}|\\
+% \ldots\\
+% |\phantomcaption|\\
+% |\label{that}|
+% \end{quote}
+%
+% But when using the |\sub|\-|caption|\-|box| command, the |\label| should be placed inside
% the caption text, e.g.:
% \begin{quote}
-% |\subcaptionbox{A description here\label{label4}}|\\
+% |\subcaptionbox{A description here\label{todo1}}|\\
% | {Some content here}|\\
% \ldots\\
% |\subcaptionbox[List-of-Figures entry]|\\
-% | {A description here\label{label5}}|\\
+% | {A description here\label{todo2}}|\\
% | {Some content here}|
% \end{quote}
+% Placing |\label| outside the |\sub|\-|caption|\-|box| would produce an incorrect reference.
%
% \pagebreak[3]
% \subsection{Where do hyperlinks jump?}
% \label{hypcap}
%
-% For the |subfigure| \& |subtable| environments and |\subcaptionbox| boxes
-% (and own constructs which use |\set|\-|caption|\-|sub|\-|type|) the
-% hyperlink anchors will be placed in respect to the |hypcap=| setting.
+% For the |caption|\-|sub|\-|block|, |sub|\-|figure|, |sub|\-|table|, and |caption|\-|sub|\-|group| environments,
+% and for the |\sub|\-|caption|\-|box| command (and all other constructs which use |\set|\-|caption|\-|sub|\-|type|)
+% the hyperlink anchors will be placed in respect to the |hypcap=| setting.
% While usage of this option is straight-forward for ordinary captions,
% the usage for sub-captions depends on the setting regarding the main captions.
-% This table gives you an overview where the hyperlinks will jump:\par
+%
+% This table gives you an overview where the hyperlinks will jump:
%
% \bigskip
+%
% \begin{small}
% \centering
% \DeleteShortVerb{\|}
@@ -767,27 +998,565 @@
% \end{small}
% \bigskip
%
-% But if |\subcaption| is used and |hypcap=true| is set for sub-captions,
+% But if the |caption|\-|sub|\-|group*| environment is used
+% (or a different construct which uses |\set|\-|caption|\-|sub|\-|type*|)
+% and |hypcap=true| is set for sub-captions,
% \thispackage\ does not know where the sub-figure or sub-table actually
% begins, so it will jump to the sub-caption instead.
%
% \medskip
-% \emph{Remember:} If you use the \package{hypcap} package\cite{hypcap},
+% \emph{Remember:} If you use the \pkg{hypcap} package\cite{hypcap},
% it controls the placement of the hyperlink anchors, making the rules
% above invalid.
%
% \bigskip
-% {\small(See also the documentation of the \package{caption} package,
-% sections about \package{hyperref} \& \package{hypcap}.)}
+% {\small(See also the documentation of the \pkg{caption} package,
+% sections about \pkg{hyperref} \& \pkg{hypcap}.)}
+%
+% \iffalse
+% --------------------------------------------------------------------------- %
+% \fi
+%
+% \PageBreak
+% \section{Captions inside sub-figures}
+% \label{inside}
+%
+% Nearly all code examples so far have placed the caption either above or below the sub-figure.
+% But it is possible to put the caption inside the sub-figure, too:
+% \begin{itemize}
+% \item The caption could already be part of the image. (This case is already handled in \Ref{without}.)
+% \item \LaTeX\ packages like \pkg{overpic}, \pkg{stackengine}, or \pkg{tikz} could be used.
+% Note that the commands resp.~environments offered by these packages usually evaluate their content more than once,
+% resulting in either errors or wrong reference counters.
+% For this reason |\caption| should not be used here, instead
+% |\phantomcaption| or |\captionlistentry| should be used outside the command resp.~environment and
+% |\captiontext| should be used inside it.
+% See also \Ref{without2}
+% \item The options |skip=| and |margin=| could be used to place the caption onto the image.
+% \end{itemize}
+%
+% \pagebreak[3]
+% \subsection{Using the overpic package}
+% \label{overpic}
+%
+% The same example as in section \Ref{without}, but using the \env{overpic} environment
+% offered by the \pkg{overpic} package~\cite{overpic}
+% to place the captions inside the pictures:
+% \begin{quote}
+% |\usepackage{overpic}|\\
+% \ldots\\
+% |\begin{figure}|\\
+% | \centering|\\
+% | \begin{subcaptiongroup}|\\
+% | |\textcolor{blue}{\cs{subcaptionlistentry}\csmarg{A cat}}\\
+% | \label{cat}|\\
+% | \begin{overpic}[width=60pt]{cat}|\\
+% | \put(40,34){|\textcolor{blue}{\cs{captiontext*}\csmarg{}}|}|\\
+% | \end{overpic}|\\
+% | |\textcolor{blue}{\cs{subcaptionlistentry}\csmarg{An elephant}}\\
+% | \label{elephant}|\\
+% | \begin{overpic}[width=140pt]{elephant}|\\
+% | \put(58,40){|\textcolor{blue}{\cs{captiontext*}\csmarg{}}|}|\\
+% | \end{overpic}|\\
+% | \end{subcaptiongroup}|\\
+% | \captionsetup{subrefformat=parens}|\\
+% | \caption{Two animals: \subref{cat} a huge cat,|\\
+% | and \subref{elephant} an elephant}|\\
+% |\end{figure}|
+% \end{quote}
+% \noindent\begin{minipage}{\linewidth}
+% \captionsetup{type=figure}
+% \centering
+% \begin{subcaptiongroup}
+% \subcaptionlistentry{A cat}\label{cat7.1}
+% \begin{overpic}[width=60pt]{cat}
+% \put(40,34){\captiontext*{}}
+% \end{overpic}
+% \subcaptionlistentry{An elephant}\label{elephant7.1}
+% \begin{overpic}[width=140pt]{elephant}
+% \put(58,40){\captiontext*{}}
+% \end{overpic}
+% \end{subcaptiongroup}
+% \captionsetup{subrefformat=parens}
+% \caption{Two animals: \subref{cat7.1} a huge cat, and \subref{elephant7.1} an elephant}
+% \end{minipage}
+%
+% \bigskip
+%
+% If neither a reference to the sub-figures nor an entry in the List of Figures is needed,
+% the usage of |\phantom|\-|caption| resp.~|\caption|\-|list|\-|entry| could be dropped.
+% Since this leaves |\caption|\-|text| without a valid sub-figure number value it must be
+% given to it explicitly as optional argument.
+%
+% Furthermore the usage of the |sub|\-|caption|\-|group| environment could be dropped here,
+% instead it would be sufficient to replace |\caption|\-|text| with |\sub|\-|caption|\-|text|.
+% \See{\Ref{subcaption}}
+%
+% \begin{quote}
+% |\usepackage{overpic}|\\
+% \ldots\\
+% |\begin{figure}|\\
+% | \centering|\\
+% | \begin{overpic}[width=60pt]{cat}|\\
+% | \put(40,34){|\textcolor{blue}{\cs{subcaptiontext*}\csoarg{1}\csmarg{}}|}|\\
+% | \end{overpic}|\\
+% | \begin{overpic}[width=140pt]{elephant}|\\
+% | \put(58,40){|\textcolor{blue}{\cs{subcaptiontext*}\csoarg{2}\csmarg{}}|}|\\
+% | \end{overpic}|\\
+% | \caption{Two animals: A huge cat and an elephant}|\\
+% |\end{figure}|
+% \end{quote}
+%
+% \pagebreak[3]
+% \subsection{Using the stackengine package}
+% \label{stackengine}
+%
+% The same example as in section \Ref{without}, but using the |\stack|\-|inset| command
+% offered by the \pkg{stackengine} package~\cite{stackengine}
+% to place the captions inside the pictures:
+% \begin{quote}
+% |\usepackage{stackengine}|\\
+% \ldots\\
+% |\begin{figure}|\\
+% | \centering|\\
+% | \begin{subcaptiongroup}|\\
+% | |\textcolor{blue}{\cs{subcaptionlistentry}\csmarg{A cat}}\\
+% | \label{cat}|\\
+% | \stackinset{l}{25pt}{b}{20pt}{|\textcolor{blue}{\cs{captiontext*}\csmarg{}}|}|\\
+% | {\includegraphics[width=60pt]{cat}}|\\
+% | |\textcolor{blue}{\cs{subcaptionlistentry}\csmarg{An elephant}}\\
+% | \label{elephant}|\\
+% | \stackinset{l}{80pt}{b}{60pt}{|\textcolor{blue}{\cs{captiontext*}\csmarg{}}|}|\\
+% | {\includegraphics[width=140pt]{elephant}}|\\
+% | \end{subcaptiongroup}|\\
+% | \captionsetup{subrefformat=parens}|\\
+% | \caption{Two animals: \subref{cat} a huge cat,|\\
+% | and \subref{elephant} an elephant}|\\
+% |\end{figure}|
+% \end{quote}
+% \noindent\begin{minipage}{\linewidth}
+% \captionsetup{type=figure}
+% \centering
+% \begin{subcaptiongroup}
+% \subcaptionlistentry{A cat}\label{cat7.2}
+% \stackinset{l}{25pt}{b}{20pt}{\captiontext*{}}{\includegraphics[width=60pt]{cat}}
+% \subcaptionlistentry{An elephant}\label{elephant7.2}
+% \stackinset{l}{80pt}{b}{60pt}{\captiontext*{}}{\includegraphics[width=140pt]{elephant}}
+% \end{subcaptiongroup}
+% \captionsetup{subrefformat=parens}
+% \caption{Two animals: \subref{cat7.2} a huge cat, and \subref{elephant7.2} an elephant}
+% \end{minipage}
+%
+% \bigskip
+%
+% \pagebreak[3]
+% If neither a reference to the sub-figures nor an entry in the List of Figures is needed,
+% this code could be simpified to:
+% \begin{quote}
+% |\usepackage{stackengine}|\\
+% \ldots\\
+% |\begin{figure}|\\
+% | \centering|\\
+% | \stackinset{l}{25pt}{b}{20pt}{|\textcolor{blue}{\cs{subcaptiontext*}\csoarg{1}\csmarg{}}|}|\\
+% | {\includegraphics[width=60pt]{cat}}|\\
+% | \stackinset{l}{80pt}{b}{60pt}{|\textcolor{blue}{\cs{subcaptiontext*}\csoarg{2}\csmarg{}}|}|\\
+% | {\includegraphics[width=140pt]{elephant}}|\\
+% | \caption{Two animals: A huge cat and an elephant}|\\
+% |\end{figure}|
+% \end{quote}
+%
+% \pagebreak[3]
+% \subsection{Using the tikz package}
+% \label{tikz}
+%
+% The same example as in section \Ref{without}, but using the \env{tikzpicture} environment
+% offered by the \pkg{tikz} package~\cite{tikz}
+% to place the captions inside the pictures:
+% \begin{quote}
+% |\usepackage{tikz}|\\
+% \ldots\\
+% |\begin{figure}|\\
+% | \centering|\\
+% | \begin{subcaptiongroup}|\\
+% | |\textcolor{blue}{\cs{subcaptionlistentry}\csmarg{A cat}}\\
+% | \label{cat}|\\
+% | \begin{tikzpicture}|\\
+% | \node (cat) at (0,0)|\\
+% | {\includegraphics[width=60pt]{cat}};|\\
+% | \node at (0.1,-0.1) {|\textcolor{blue}{\cs{captiontext*}\csmarg{}}|};|\\
+% | \end{tikzpicture}|\\
+% | |\textcolor{blue}{\cs{subcaptionlistentry}\csmarg{An elephant}}\\
+% | \label{elephant}|\\
+% | \begin{tikzpicture}|\\
+% | \node (elephant) at (0,0)|\\
+% | {\includegraphics[width=140pt]{elephant}};|\\
+% | \node at (0.5,-0.1) {|\textcolor{blue}{\cs{captiontext*}\csmarg{}}|};|\\
+% | \end{tikzpicture}|\\
+% | \end{subcaptiongroup}|\\
+% | \captionsetup{subrefformat=parens}|\\
+% | \caption{Two animals: \subref{cat} a huge cat,|\\
+% | and \subref{elephant} an elephant}|\\
+% |\end{figure}|
+% \end{quote}
+%
+% \noindent\begin{minipage}{\linewidth}
+% \captionsetup{type=figure}
+% \centering
+% \begin{subcaptiongroup}
+% \subcaptionlistentry{A cat}\label{cat7.3}
+% \begin{tikzpicture}
+% \node (cat) at (0,0) {\includegraphics[width=60pt]{cat}};
+% \node at (0.1,-0.1) {\captiontext*{}};
+% \end{tikzpicture}
+% \subcaptionlistentry{An elephant}\label{elephant7.3}
+% \begin{tikzpicture}
+% \node (cat) at (0,0) {\includegraphics[width=140pt]{elephant}};
+% \node at (0.5,-0.1) {\captiontext*{}};
+% \end{tikzpicture}
+% \end{subcaptiongroup}
+% \captionsetup{subrefformat=parens}
+% \caption{Two animals: \subref{cat7.3} a huge cat, and \subref{elephant7.3} an elephant}
+% \end{minipage}
+%
+% \bigskip
+%
+% \pagebreak[3]
+% If neither a reference to the sub-figures nor an entry in the List of Figures is needed,
+% this code could be simpified to:
+% \begin{quote}
+% |\usepackage{tikz}|\\
+% \ldots\\
+% |\begin{figure}|\\
+% | \centering|\\
+% | \begin{tikzpicture}|\\
+% | \node (cat) at (0,0)|\\
+% | {\includegraphics[width=60pt]{cat}};|\\
+% | \node at (0.1,-0.1) {|\textcolor{blue}{\cs{subcaptiontext*}\csoarg{1}\csmarg{}}|};|\\
+% | \end{tikzpicture}|\\
+% | \begin{tikzpicture}|\\
+% | \node (elephant) at (0,0)|\\
+% | {\includegraphics[width=140pt]{elephant}};|\\
+% | \node at (0.5,-0.1) {|\textcolor{blue}{\cs{subcaptiontext*}\csoarg{2}\csmarg{}}|};|\\
+% | \end{tikzpicture}|\\
+% | \caption{Two animals: A huge cat and an elephant}|\\
+% |\end{figure}|
+% \end{quote}
+%
+% \pagebreak[3]
+% \subsection{Using the skip and margin options}
+% For a particular sub-caption the |skip=|\ldots could be set to a negative value so it will overlap with the image.
+% Combined with |singlelinecheck=off| (to switch off the centering of short captions) and |margin=|\ldots it could be placed
+% at a specific horizontal position within the image, too.
+%
+% \pagebreak[3]
+% The same example as in section \Ref{without}, but using the |skip=|\ldots and |margin=|\ldots options:
+% \begin{quote}
+% |\begin{figure}|\\
+% | \centering|\\
+% | \captionsetup[subfigure]|\\
+% | {skip=-28pt,slc=off,margin={25pt,0pt}}|\\
+% | \subcaptionbox{\label{cat}}|\\
+% | {\includegraphics[width=60pt]{cat}}|\\
+% | \captionsetup[subfigure]|\\
+% | {skip=-60pt,slc=off,margin={80pt,0pt}}|\\
+% | \subcaptionbox{\label{elephant}}|\\
+% | {\includegraphics[width=140pt]{elephant}}|\\
+% | \captionsetup{subrefformat=parens}|\\
+% | \caption{Two animals: \subref{cat} a huge cat,|\\
+% | and \subref{elephant} an elephant}|\\
+% |\end{figure}|
+% \end{quote}
+%
+% \noindent\begin{minipage}{\linewidth}
+% \captionsetup{type=figure}
+% \centering
+% \captionsetup[subfigure]{skip=-28pt,slc=off,margin={25pt,0pt}}
+% \subcaptionbox{\label{cat7.4}}{\includegraphics[width=60pt]{cat}}
+% \captionsetup[subfigure]{skip=-60pt,slc=off,margin={80pt,0pt}}
+% \subcaptionbox{\label{elephant7.4}}{\includegraphics[width=140pt]{elephant}}
+% \captionsetup{subrefformat=parens}
+% \caption{Two animals: \subref{cat7.4} a huge cat, and \subref{elephant7.4} an elephant}
+% \end{minipage}
+%
+% \iffalse
+% --------------------------------------------------------------------------- %
+% \fi
+%
+% \PageBreak
+% \section{Numbering}
+%
+% \subsection{Pittfall \#1: Using multiple main captions}
+%
+% When multiple main captions are used within a figure or table, and sub-captions
+% are used as well, how does the \pkg{subcaption} package know which
+% sub-captions belong to which caption, i.e. what is the main counter value for
+% the sub-captions?
+%
+% \pagebreak[3]
+% Let's illustrate this problem with an example document:
+% \begin{quote}
+% |\documentclass{article}|\\
+% |\usepackage{graphicx,subcaption}|\\
+% |\begin{document}|\\
+% |\begin{figure}|\\
+% | \centering|\\
+% | \includegraphics[width=4cm]{example-image-c}|\\
+% | \caption{Caption no. 1}|\\
+% | \bigskip|\\
+% | \subcaptionbox|\\
+% | {\label{fig:2a}}|\\
+% | {\includegraphics[width=2cm]{example-image-a}}|\\
+% | \subcaptionbox|\\
+% | {\label{fig:2b}}|\\
+% | {\includegraphics[width=2cm]{example-image-b}}|\\
+% | \caption{Caption no. 2}|\\
+% |\end{figure}|\\
+% |Look at sub-figures \ref{fig:2a} and \ref{fig:2b}.|\\
+% |\end{document}|
+% \end{quote}
+%
+% It's obvious that the sub-captions belong to 2nd caption, and therefore
+% |\ref{fig:2a}| will become ``2a'', isn't it?
+% But since the \pkg{subcaption} package is only involved when using
+% \LaTeX\ commands either defined or patched by the \pkg{caption} or
+% \pkg{subcaption} package, this is what the \pkg{caption} package
+% is aware of:
+% \begin{quote}
+% |\usepackage{subcaption}|\\
+% |\begin{document}|\\
+% |\begin{figure}|\\
+% | \caption{Caption no. 1}|\\
+% | \subcaptionbox|\\
+% | {\label{fig:2a}}|\\
+% | {|\meta{unknown content}|}|\\
+% | \subcaptionbox|\\
+% | {\label{fig:2b}}|\\
+% | {|\meta{unknown content}|}|\\
+% | \caption{Caption no. 2}|\\
+% |\end{figure}|\\
+% |\end{document}|
+% \end{quote}
+%
+% So from \pkg{caption}s point of view it's not easy to decide if the
+% sub-captions belong to the 1st or 2nd main caption since they are placed
+% between them. (Note: The \pkg{subcaption} package is only offering
+% an user interface to the sub-caption feature of the \pkg{caption} package,
+% and therefore this decision is the responsibility of the \pkg{caption} package.)
+%
+% But how does the \pkg{caption} package makes a decision?
+% If in doubt, it rather clings to the past than to the future, i.e.~in this
+% case it decides that the sub-captions belong to the 1st caption and therefore
+% the result of |\ref{fig:2a}| is not ``2a'' but ``1a''.
+% If the \pkg{caption} package is unsure about its decision (like in this
+% case), a warning will be issued:
+% \begingroup
+% \leftmargini=12pt
+% \begin{quote}
+% |Package caption Warning: Ambiguous sub-caption(s),|\\
+% | use \nextfloat on input line 15.|\\
+% |See the caption package documentation for explanation.|
+% \end{quote}
+% \endgroup
+%
+% \pagebreak[3]
+% How to fix it? Use |\next|\-|float| to tell the \pkg{caption} package
+% where the 2nd figure within the |figure| environment starts:
+% \begin{quote}
+% |\documentclass{article}|\\
+% |\usepackage{graphicx,subcaption}|\\
+% |\begin{document}|\\
+% |\begin{figure}|\\
+% | \centering|\\
+% | \includegraphics[width=4cm]{example-image-c}|\\
+% | \caption{Caption no. 1}|\\
+% | \bigskip|\\
+% ||\textcolor{blue}{\cs{nextfloat}}\\
+% | \subcaptionbox|\\
+% | {\label{fig:2a}}|\\
+% | {\includegraphics[width=2cm]{example-image-a}}|\\
+% | \subcaptionbox|\\
+% | {\label{fig:2b}}|\\
+% | {\includegraphics[width=2cm]{example-image-b}}|\\
+% | \caption{Caption no. 2}|\\
+% |\end{figure}|\\
+% |Look at sub-figures \ref{fig:2a} and \ref{fig:2b}.|\\
+% |\end{document}|
+% \end{quote}
+%
+% \INFO
+% Note that the |\next|\-|float| command was introduced in \pkg{caption} package
+% \version{3.6}.
+% Previous versions of the \pkg{caption} package have bound the decision to the
+% |position=| setting of the floating environment instead, i.e.~sub-captions belonged to
+% the caption above if |position=top| was set and they belonged to the caption below
+% if |position=below| was set.
+% While this would be beneficial in this case, there were several cases were it was not
+% and especially it was not always comprehensible to the user why his references got an
+% incorrect numbering.
+%
+% Furthermore the new decision algorithm always succeeds if there is only one caption
+% within the figure or table (which is the case most of the time) while the old one did not.
+%
+% \pagebreak[3]
+% If you still prefer the old decision algorithm (for example because you want to process
+% an already existing document), you need to specify the \pkg{caption} package version
+% explicitly, for example:
+% \begin{quote}
+% |\documentclass{article}|\\
+% |\usepackage{caption}[=v3.5]|\\
+% |\usepackage{graphicx,subcaption}|\\
+% \ldots
+% \end{quote}
+%
+% See also: \Ref{sec:caption}
+%
+% \subsection{Pittfall \#2: Expecting \cs{caption} to increment the counter}
+%
+% \pagebreak[3]
+% Usually |\caption| increments the figure resp.~table counter and therefore
+% it is usally safe to assume that the counter was not incremented yet in code
+% used before |\caption|:
+% \begin{quote}
+% |\documentclass{article}|\\
+% |\begin{document}|\\
+% |\begin{figure}|\\
+% | Figure counter before caption: \thefigure|\\
+% | \caption{Some text}|\\
+% | Figure counter after caption: \thefigure|\\
+% |\end{figure}|\\
+% |\end{document}|
+% \end{quote}
+%
+% Unsurprisingly the results are 0 and 1 for the counter values.
+%
+% \pagebreak[3]
+% But this happens if we use the \pkg{subcaption} package:
+% \begin{quote}
+% |\documentclass{article}|\\
+% |\usepackage{subcaption}|\\
+% |\begin{document}|\\
+% |\begin{figure}|\\
+% | \subcaptionbox{}{some content}|\\
+% | \subcaptionbox{}{some content}|\\
+% | Figure counter before caption: \thefigure|\\
+% | \caption{Some text}|\\
+% | Figure counter after caption: \thefigure|\\
+% |\end{figure}|\\
+% |\end{document}|
+% \end{quote}
+%
+% Here the results are 1 and 1 for the counter values. Why?
+%
+% Since the \pkg{caption} package assumes that there will be a |\caption|
+% following |\sub|\-|caption|\-|box| it decides that the sub-captions belong
+% to the upcoming main caption and therefore share the same main counter value
+% which needs to be incremented before its use.
+% Therefore the first |\sub|\-|caption|\-|box| in the figure increments the
+% figure counter while the second one and especially the |\caption| does not.
+%
+% Usually this is no problem at all but keep this in mind if you are doing
+% tricky stuff with the figure resp.~table counter within figures resp.~tables.
+%
+% \iffalse
+% --------------------------------------------------------------------------- %
+% \fi
+%
+% \PageBreak
+% \section{Abbreviatory commands}
+% \label{subcaption}
+%
+% \DescribeMacro\subcaption
+% \DescribeMacro\phantomsubcaption
+% \DescribeMacro\subcaptionlistentry
+% \DescribeMacro\subcaptiontext
+% \hskip1pt %^^A work-around for bug in \DescribeMacro to prevent red colored margin note
+% As we have seen in sections {\Ref{overpic}, \Ref{stackengine}, and \Ref{tikz}}
+% it's sometimes inconvenient to use the commands and environments
+% described so far.
+%
+% \pagebreak[3]
+% For example it would be inconvenient to use \env{captiongroup} just for
+% a single |\caption|\-|text| in this particular case:
+% \begin{quote}
+% \ldots\\
+% |\begin{overpic}[width=60pt]{cat}|\\
+% | \put(40,34)|\\
+% | {\begin{captiongroup*}|\\
+% | \captiontext*[1]{}|\\
+% | \end{captiongroup*}}|\\
+% |\end{overpic}|\\
+% \ldots
+% \end{quote}
+%
+% \pagebreak[3]
+% Since |\caption|\-|text| is already used in an extra environment (|overpic|)
+% we don't need an extra |caption|\-|group*| here,
+% instead using |\set|\-|caption|\-|sub|\-|type*| (which switches into the
+% sub-caption mode without making an \pkg{hyperref} anchor) would be sufficient:
+% \begin{quote}
+% \ldots\\
+% |\begin{overpic}[width=60pt]{cat}|\\
+% | \put(40,34)|\\
+% | {\setcaptionsubtype*|\\
+% | \captiontext*[1]{}}|\\
+% |\end{overpic}|\\
+% \ldots
+% \end{quote}
+%
+% \pagebreak[3]
+% But this is still inconvenient when used many times, and therefore \thispackage\ defines
+% several extra commands which are prefixed with |\set|\-|caption|\-|sub|\-|type*|:
+%
+% \medskip
+%
+% \begin{minipage}{\textwidth}
+% \centering
+% \begin{tabular}{l|l|l}
+% Regular command & with \cs{setcaptionsubtype*} & available since \\
+% \hline
+% |\caption| & |\subcaption| & \version{1.0} \\
+% |\phantomcaption| & |\phantomsubcaption| & \version{1.1} \\
+% |\captionlistentry| & |\subcaptionlistentry| & \version{1.5} \\
+% |\captiontext| & |\subcaptiontext| & \version{1.5} \\
+% \end{tabular}
+% \end{minipage}
+%
+% \bigskip
%
% \pagebreak[3]
+% This way our code snipped above could be simplified to:
+% \begin{quote}
+% \ldots\\
+% |\begin{overpic}[width=60pt]{cat}|\\
+% | \put(40,34){\subcaptiontext*[1]{}}|\\
+% |\end{overpic}|\\
+% \ldots
+% \end{quote}
+%
+% \INFO
+% Since |\set|\-|caption|\-|sub|\-|type| should only be used within an
+% extra group or environment, the same applies to these commands as well.
+% (In this case |\sub|\-|caption|\-|text| is encapsulated by the
+% |overpic| environment, so we are ok here.
+%
+% \begin{background}
+% The |\sub|\-|caption| command is just a simple combination of
+% |\set|\-|caption|\-|sub|\-|type*| and |\caption|. Same for all other
+% abbreviatory commands here.
+% \end{background}
+%
+% \iffalse
+% --------------------------------------------------------------------------- %
+% \fi
+%
+% \PageBreak
% \section{The \cs{subfloat} command}
% \label{subfloat}
%
% \DescribeMacro\subfloat
-% \NEWfeature{v1.3}
-% To allow a smoother transition from the \package{subfig} package
-% (which is unmaintained for over 14 years)
+% \NEWfeature*{v1.3}
+% To allow a smoother transition from the \pkg{subfig} package~\cite{subfig}
+% (which is unmaintained for over 16 years)
% this package also offers |\sub|\-|float| with the same syntax:
% \begin{quote}
% |\subfloat|\oarg{list\_entry}\oarg{sub-caption}\marg{body}
@@ -797,24 +1566,55 @@
% --------------------------------------------------------------------------- %
% \fi
%
+% \section{Required packages}
+% \label{sec:caption}
+%
+% \NEWfeature{v1.4}
+% Starting with version $1.4$ the \pkg{subcaption} package requires at least version $3.1$
+% of the \pkg{caption} package and loads it automatically.
+% (Older versions of the \pkg{subcaption} package have required exactly the version of the
+% \pkg{caption} package which was released with it.)
+%
% \pagebreak[3]
+% If you need to use a specific version of the \pkg{caption} package you need to load it
+% \emph{before} the \pkg{subcaption} package, e.g.:
+% \begin{quote}
+% |\usepackage[| \ldots |]{caption}[=v3.5]|\\
+% |\usepackage[| \ldots |]{subcaption}|
+% \end{quote}
+%
+% \pagebreak[3]
+% Note that there are limitations if an older version of the \pkg{caption} package
+% is used:
+% \begin{itemize}
+% \item The |\phantomsubcaption| command need at least \pkg{caption} \version{3.2}.
+% \item The |\subcaptionlistentry| command need at least \pkg{caption} \version{3.3}.
+% \item The |\subcaptiontext| command need at least \pkg{caption} \version{3.6}.
+% \item The |\subfloat| emulation needs at least \pkg{caption} \version{3.4}.
+% \end{itemize}
+%
+% \iffalse
+% --------------------------------------------------------------------------- %
+% \fi
+%
+% \PageBreak
% \section{Beyond this package}
% \label{keyfloat}\label{floatrow}
%
% For a more advanced usage of the sub-caption feature of the
-% \package{caption} package, please take a look at the excellent
-% \package{keyfloat} package\cite{keyfloat} which provides the environments
+% \pkg{caption} package, please take a look at the excellent
+% \pkg{keyfloat} package\cite{keyfloat} which provides the environments
% |key|\-|sub|\-|figs|, |key|\-|sub|\-|tabs|, and |key|\-|sub|\-|floats| for
% typesetting sub-figures and sub-tables.
%
-% Furthermore the \package{floatrow} package\cite{floatrow} provides the
+% Furthermore the \pkg{floatrow} package\cite{floatrow} provides the
% |sub|\-|float|\-|row| environment for typesetting sub-figures.
%
% \iffalse
% --------------------------------------------------------------------------- %
% \fi
%
-% \pagebreak[3]
+% \PageBreak
% \section{Thanks}
%
% I would like to thank
@@ -827,37 +1627,66 @@
%
% \StopEventually{%^^A
% \begin{thebibliography}{9}
+%
% \bibitem{TLC2}
% Frank Mittelbach and Michel Goossens:\\
-% \newblock {\em The {\LaTeX} Companion (2nd.~Ed.)},
+% \newblock {\em The {\LaTeX} Companion (2nd.~Ed.)},\\
% \newblock Addison-Wesley, 2004.
+%
+% \bibitem{caption}
+% Axel Sommerfeldt:\\
+% \href{http://www.ctan.org/pkg/caption}%
+% {\emph{Customizing captions of floating environments}},\\
+% 2022/01/07
+%
% \bibitem{floatrow}
% Olga Lapko:\\
% \href{http://www.ctan.org/pkg/floatrow}%
-% {\emph{The floatrow package documentation}},
+% {\emph{The floatrow package documentation}},\\
% 2007/12/24
+%
% \bibitem{hyperref}
% Sebastian Rahtz \& Heiko Oberdiek:\\
% \href{http://www.ctan.org/pkg/hyperref}%
-% {\emph{Hypertext marks in \LaTeX}},
+% {\emph{Hypertext marks in \LaTeX}},\\
% November 12, 2007
+%
% \bibitem{hypcap}
% Heiko Oberdiek:\\
% \href{http://www.ctan.org/pkg/hypcap}%
-% {\emph{The hypcap package -- Adjusting anchors of captions}},
+% {\emph{The hypcap package -- Adjusting anchors of captions}},\\
% 2007/04/09
+%
% \bibitem{keyfloat}
% Brian Duun:\\
% \href{http://www.ctan.org/pkg/keyfloat}%
-% {\emph{The \LaTeX\ keyfloat Package}},
+% {\emph{The \LaTeX\ keyfloat Package}},\\
% 2019/09/23
-% \iffalse
+%
+% \bibitem{overpic}
+% Rolf Niepraschk:\\
+% \href{http://www.ctan.org/pkg/overpic}%
+% {\emph{The overpic package}},\\
+% 2020/02/22
+%
+% \bibitem{stackengine}
+% Steven B. Segletes:\\
+% \href{http://www.ctan.org/pkg/stackengine}%
+% {\emph{The stackengine Package}},\\
+% July 22, 2021
+%
+% \bibitem{tikz}
+% Till Tantau:\\
+% \href{http://www.ctan.org/pkg/tikz}%
+% {\emph{The TikZ and PGF Packages}},\\
+% May 15, 2021
+%
% \bibitem{subfig}
% Steven D. Cochran:\\
% \href{http://www.ctan.org/pkg/subfig}%
-% {\emph{The subfig package}},
+% {\emph{The subfig package}},\\
% 2005/07/05
-% \fi
+%
% \end{thebibliography}
% }
%
@@ -887,6 +1716,7 @@
% \DoNotIndex{\hangindent,\hbox,\hfil,\hsize,\hskip,\hspace,\hss}
% \DoNotIndex{\ifcase,\ifdim,\ifnum,\ifodd,\ifvoid,\ifvmode}
% \DoNotIndex{\ifx,\ignorespaces,\itshape}
+% \DoNotIndex{\kernel@ifnextchar}
% \DoNotIndex{\Large,\large,\leavevmode,\leftmargini,\leftskip,\let,\linewidth}
% \DoNotIndex{\llap,\long,\m@ne,\margin,\mdseries,\message}
% \DoNotIndex{\newcommand,\newdimen,\newlength,\newline,\newif,\newsavebox}
@@ -914,7 +1744,7 @@
% \setlength{\parskip}{0pt plus 1pt}
% \changes{v0.1}{2007/09/01}{First demo}
% \changes{v0.2}{2007/11/11}{\cs{subcaptionbox} added}
-% \changes{v0.3}{2007/12/06}{Adapted to \package{caption} package \version{3.1f}}
+% \changes{v0.3}{2007/12/06}{Adapted to \pkg{caption} package \version{3.1f}}
% \changes{v1.0}{2008/03/16}{\cs{subfloat} added}
% \changes{v1.0}{2010/10/27}{An error message will be issued when the subfigure or subfig package is loaded}
% \changes{v1.0}{2011/01/22}{Undocumented command \cs{subfloat} removed}
@@ -927,23 +1757,51 @@
%
% \clearpage
% \section{The implementation}
+%
% \iffalse
%<*package>
% \fi
%
% \subsection{Identification}
%
+% We need at least \LaTeX2e\ version 1994/12/01.
% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[1994/12/01]
-\ProvidesPackage{subcaption}[2020/10/07 v1.3j Sub-captions (AR)]
+% \end{macrocode}
+%
+% Bypass the release declarations in case the \LaTeX\ kernel doesn’t know how to deal with them
+% (as suggested by \url{https://www.latex-project.org/publications/2018-FMi-TUB-tb122mitt-version-rollback.pdf}).
+% \begin{macrocode}
+\providecommand\DeclareRelease[3]{}
+\providecommand\DeclareCurrentRelease[2]{}
+% \end{macrocode}
+%
+% Declare all supported releases.
+% \begin{macrocode}
+\DeclareCurrentRelease{v1}{2007/12/06}
+% \end{macrocode}
+%
+% Identify the current version of the package.
+% \begin{macrocode}
+\ProvidesPackage{subcaption}[2022/01/07 v1.5 Sub-captions (AR)]
+% \end{macrocode}
+%
+% Since we base on the \pkg{caption} package we load it here.
+% \begin{macrocode}
+\RequirePackage{caption}[2010/01/09] % we need at least v3.1m
% \end{macrocode}
%
% \subsection{Initial code}
%
-% Since we base on the \package{caption} package we load it here.
+% \begin{macro}{\subcaption@Warning}
+% \changes{v1.5}{2022/01/06}{This macro added}
+% |\subcaption@Warning|\marg{message}\\
+% issues an warning message (with code line indication).
% \begin{macrocode}
-\RequirePackage{caption}[2020/09/28] % needs v3.5c or newer
+\newcommand*\subcaption@Warning{%
+ \PackageWarning{subcaption}}
% \end{macrocode}
+% \end{macro}
%
% \begin{macro}{\subcaption@Error}
% \changes{v1.3h}{2020/09/28}{This macro added}
@@ -953,25 +1811,34 @@
\newcommand*\subcaption@Error[1]{%
\PackageError{subcaption}{#1}{\caption@@eh{subcaption}}}
% \end{macrocode}
+% \begin{macrocode}
+\providecommand*\caption@@eh[1]{%
+ If you do not understand this error, please take a closer look\MessageBreak
+ at the documentation of the `#1' package, especially the\MessageBreak
+ section about errors.\MessageBreak\@ehc}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\subcaption@OutsideFloat}
+% \changes{v1.5}{2022/01/07}{This macro definition added}
+% |\subcaption@OutsideFloat}| issues a ``\meta{command} outside float'' error.
+% \begin{macrocode}
+\newcommand*\subcaption@OutsideFloat[1]{%
+ \subcaption@Error{\string#1 outside float}}
+% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\subcaption@CheckCompatibility}
% \changes{v1.1}{2011/09/01}{Compatibility error added}
-% \changes{v1.1}{2016/05/22}{The presence of \package{subfigure} or \package{subfig} will be checked \cs{AtBeginDocument}, too}
-% \changes{v1.3g}{2020/08/01}{Error text adapted to \package{caption} package~\version{4.0}}
+% \changes{v1.1}{2016/05/22}{The presence of \pkg{subfigure} or \pkg{subfig} will be checked \cs{AtBeginDocument}, too}
+% \changes{v1.3g}{2020/08/01}{Error text adapted to \pkg{caption} package~\version{4.0}}
+% \changes{v1.4}{2020/12/22}{Adapted to fallback concept}
% Since we are incompatible to them an error message will be issued when
-% the \package{subfigure} or \package{subfig} package is loaded.
+% the \pkg{subfigure} or \pkg{subfig} package is loaded.
% \begin{macrocode}
\newcommand*\subcaption@CheckCompatibility{%
% \end{macrocode}
% \begin{macrocode}
- \caption@ifcompatibility{%
- \subcaption@Error
- {This package does not work with\MessageBreak
- caption option `compatibility=v1'}%
- \endinput}{}%
-% \end{macrocode}
-% \begin{macrocode}
\@ifpackageloaded{subfigure}{%
\subcaption@Error
{This package can't be used in cooperation\MessageBreak
@@ -998,87 +1865,71 @@
%
% \subsection{Main code}
%
-% \pagebreak[3]
-% \subsubsection{The \cs{subcaption} command}
-%
-% \begin{macro}{\subcaption}
-% \changes{v1.1}{2012/04/06}{\cs{newcommand} changed to \cs{def} so it works with the \package{memoir} document class, too}
-% \changes{v1.3h}{2020/09/28}{Usage of \cs{caption@Error} replaced by \cs{subcaption@Error}}
-% Without a prefacing |\set|\-|caption|\-|sub|\-|type|, |\sub|\-|caption| is some kind
-% of |\caption|\-|of{sub|\-|\@cap|\-|type}|.
-% \Note{Like \cs{captionof}, this command is designed to be used inside an
-% own group!}
+% \begin{macro}{\setcaptionsubtype}
+% \changes{v1.4}{2020/12/24}{This macro definition added}
+% \changes{v1.5}{2022/01/07}{Check added if used inside a floating environment}
+% |\setcaptionsubtype| is available since \pkg{caption} package \version{3.2},
+% so we need to define it first if only an older version is loaded (in fallback mode).
% \begin{macrocode}
-\def\subcaption{%
+\providecommand\setcaptionsubtype{%
\caption@iftype
- {\setcaptionsubtype*\caption}%
- {\subcaption@Error{\noexpand\subcaption outside float}%
- \caption@gobble}}%
-% \end{macrocode}
-% But with a prefacing |\set|\-|caption|\-|sub|\-|type|, |\sub|\-|caption| is simply
-% |\caption|.
-% \begin{macrocode}
-\g@addto@macro\caption@subtypehook{%
- \let\subcaption\caption}
+ {\@ifstar{\captionsetup{subtype*}}{\captionsetup{subtype}}}%
+ {\subcaption@OutsideFloat\setcaptionsubtype}}
% \end{macrocode}
% \end{macro}
%
-% \pagebreak[3]
-% \subsubsection{The \cs{phantomsubcaption} command}
+% \subsubsection{The \env{subcaptiongroup} environment}
%
-% \begin{macro}{\phantomsubcaption}
-% \changes{v1.1}{2011/08/17}{This macro added}
-% \changes{v1.3h}{2020/09/28}{Usage of \cs{caption@Error} replaced by \cs{subcaption@Error}}
-% Same as |\phantom|\-|caption|, but for subfigures.
+% \begin{environment}{subcaptiongroup}
+% \changes{v1.5}{2022/01/07}{This environment definition added}
+% \env{subcaptiongroup} is the simplest of all environments or commands this package has to offer.
+% It's simply an environment containing |\set|\-|caption|\-|sub|\-|type|, that's all.
+% A starred variant of this environment is available, too, which uses |\set|\-|caption|\-|sub|\-|type*|.
% \begin{macrocode}
-\newcommand*\phantomsubcaption{%
- \caption@iftype
- {\setcaptionsubtype*\phantomcaption}%
- {\subcaption@Error{\noexpand\phantomsubcaption outside float}}}%
+\newenvironment{subcaptiongroup}
+ {\caption@iftype
+ {\setcaptionsubtype\relax}%
+ {\subcaption@OutsideFloat{subcaptiongroup}}}
+ {}
% \end{macrocode}
% \begin{macrocode}
-\g@addto@macro\caption@subtypehook{%
- \let\phantomsubcaption\phantomcaption}
+\newenvironment{subcaptiongroup*}
+ {\caption@iftype
+ {\setcaptionsubtype*}%
+ {\subcaption@OutsideFloat{subcaptiongroup*}}}
+ {}
% \end{macrocode}
-% \end{macro}
+% \end{environment}
%
-% \pagebreak[3]
-% \subsubsection{The subfigure \& subtable environments}
+% \subsubsection{The \env{subcaptionblock} environment (and aliases)}
%
-% \begin{macro}{subfigure}
-% \begin{macro}{subtable}
+% \begin{macro}{\subcaption@minipage}
% \changes{v1.2}{2016/02/21}{Optional argument values `B' and `T' added}
% \changes{v1.3d}{2020/01/22}{Definition and usage of \cs{@subfloatboxreset} added}
-% \changes{v1.3e}{2020/07/29}{Uses \cs{ForEachCaptionSubType} (instead of \cs{caption@For}) to define the environments now}
-% This is just an ordinary \env{minipage} environment with
-% |\setcaptionsubtype| as first contents line.
-% It will be defined using the helper macro |\For|\-|Each|\-|Caption|\-|Sub|\-|Type|
-% offered by the \package{caption} kernel, so for every caption sub-type
-% declared with |\Declare|\-|Caption|\-|Sub|\-|Type| a corresponding
-% `sub' environment will be defined automatically.
-% \begin{macrocode}
-\ForEachCaptionSubType{%
- \newenvironment{#1}%
- {\@ifnextchar[%]
- \subcaption@iminipage
- {\subcaption@iminipage[c]}}%
- {\subcaption@endminipage
- \endminipage}}
+% \changes{v1.5}{2022/01/07}{This macro definition out-sourced from \cs{subcaption@newminipage}}
+% \changes{v1.5}{2022/01/07}{Usage of \cs{@ifnextchar} replaced by \cs{@testopt}}
+% \changes{v1.5}{2022/01/07}{Default value of \meta{outer-pos} changes from `c' to `b'}
+% This is a \env{minipage} with |\set|\-|caption|\-|sub|\-|type| as first contents line.
+% \begin{macrocode}
+\newcommand*\subcaption@minipage{%
+ \@testopt\subcaption@iminipage b}
% \end{macrocode}
% We pass all other optional arguments using the generic helper macro
-% |\caption@with|\-|opt|\-|args| offered by the \package{caption} kernel).
+% |\caption@with|\-|opt|\-|args| offered by the \pkg{caption} kernel).
% \begin{macrocode}
\def\subcaption@iminipage[#1]{%
- \caption@withoptargs{\subcaption@iiminipage{#1}}}
+% \caption@withoptargs{\subcaption@iiminipage{#1}}} % would need at least caption3 v1.5
+ \def\subcaption@tempa{\subcaption@iiminipage{#1}}%
+ \caption@withoptargs\subcaption@tempa}
% \end{macrocode}
% `B' and `T' will add a |\vspace{0pt}|, all other values (and additional
% optional arguments) will be passed unseen to the |minipage| environment.
% \begin{macrocode}
\newcommand*\subcaption@iiminipage[3]{%
- \let\subcaption@endminipage\@empty
+ \let\subcaption@endminipage@hook\@empty
\if#1B%
\minipage[b]#2{#3}%
- \def\subcaption@endminipage{\vspace{0pt}}%
+ \def\subcaption@endminipage@hook{\vspace{0pt}}%
\else\if#1T%
\minipage[t]#2{#3}%
\vspace{0pt}%
@@ -1089,31 +1940,170 @@
\setcaptionsubtype\relax}
% \end{macrocode}
% \begin{macrocode}
+\newcommand*\subcaption@endminipage{%
+ \subcaption@endminipage@hook
+ \endminipage}
+% \end{macrocode}
+% \begin{macrocode}
\providecommand*\@subfloatboxreset{}
% \end{macrocode}
% \end{macro}
+%
+% \begin{environment}{subcaptionblock}
+% \changes{v1.5}{2022/01/07}{This environment definition added}
+% \env{subcaptionblock} is a \env{minipage} with |\set|\-|caption|\-|sub|\-|type| as first contents line.
+% \begin{macrocode}
+\newenvironment{subcaptionblock}{\subcaption@minipage}{\subcaption@endminipage}
+% \end{macrocode}
+% \end{environment}
+%
+% \begin{macro}{\subcaption@newminipage}
+% \changes{v1.4d}{2022/01/04}{Test of environment name added, should match `sub\cs{@captype}'}
+% \changes{v1.5}{2022/01/06}{Test of environment name revised, results in a warning now instead of an error}
+% \changes{v1.5}{2022/01/07}{This command renamed from \cs{subcaption@newenvironment} to \cs{subcaption@newminipage} and revised}
+% |\subcaption@newminipage|\marg{name of new environment}\\
+% defines a new environment containing |\sub|\-|caption@mini|\-|page| and |\sub|\-|caption@end|\-|mini|\-|page|.
+% Furthermore a test will be included which checks if the environment name matches |sub\@captype|.
+% \begin{macrocode}
+\newcommand*\subcaption@newminipage[1]{%
+ \newenvironment{#1}{\subcaption@minipage@{#1}}{\subcaption@endminipage}}
+% \end{macrocode}
+% \begin{macrocode}
+\newcommand*\subcaption@minipage@[1]{%
+ \caption@iftype
+ {\edef\caption@tempa{#1}%
+ \edef\caption@tempb{sub\@captype}%
+ \ifx\caption@tempa\caption@tempb \else
+ \subcaption@Warning{%
+ `\caption@tempa' is treated as `\caption@tempb'\MessageBreak}%
+ \fi}%
+ {\subcaption@OutsideFloat{#1}}%
+ \subcaption@minipage}
+% \end{macrocode}
% \end{macro}
%
-% \pagebreak[3]
+% \begin{environment}{subfigure}
+% \begin{environment}{subtable}
+% \changes{v1.3e}{2020/07/29}{Uses \cs{ForEachCaptionSubType} (instead of \cs{caption@For}) to define the environments now}
+% The sub-environments will be defined using the helper macro |\For|\-|Each|\-|Caption|\-|Sub|\-|Type|
+% offered by the \pkg{caption} kernel v1.13 (2020/07/29), so for every caption sub-type
+% declared with |\Declare|\-|Caption|\-|Sub|\-|Type| a corresponding `sub' environment will be defined automatically.
+% (If the \pkg{caption} kernel v1.13 is not available we use \cs{caption@For} as fallback.)
+% \begin{macrocode}
+\@ifundefined{ForEachCaptionSubType} % caption3 v1.13
+ {\caption@For{subtypelist}{\subcaption@newminipage{sub#1}}}
+ {\ForEachCaptionSubType{\subcaption@newminipage{#1}}}
+% \end{macrocode}
+% \end{environment}
+% \end{environment}
+%
% \subsubsection{The \cs{subcaptionbox} command}
%
% \begin{macro}{\subcaptionbox}
-% \changes{v1.0}{2008/05/06}{Adapted to the \opt{rule} option of the \package{caption} package}
+% \changes{v1.0}{2008/05/06}{Adapted to the \opt{rule} option of the \pkg{caption} package}
% \changes{v1.0}{2008/08/31}{Definition and usage of \cs{subcaption@hrule} added}
% \changes{v1.0}{2010/12/17}{Uses \cs{caption@box} now}
% \changes{v1.1}{2011/08/16}{Adapted to actual version of \cs{caption@box}}
% \changes{v1.1}{2012/04/09}{Adapted to actual version of \cs{caption@ibox}}
-% A |\parbox| with contents and sub-caption, separated by an invisible |\hrule|.
+% \changes{v1.4}{2020/12/24}{Fallback definition of \cs{caption@ibox} added}
+% A |\parbox| with contents and sub-caption, separated by an invisible |\hrule|.\par
+% The code of this macro was moved to the \pkg{caption} package \version{3.2}
+% (so it could offer it as |\caption|\-|box| as well), so since then it's
+% sufficient to simply use |\caption@ibox| here.\par
+% But if only \pkg{caption} package \version{3.1} is available (since the user
+% decided to use this particular fallback version), we still must define the code
+% on our own.
+% \begin{macrocode}
+\@ifundefined{caption@ibox}{%
+% \end{macrocode}
+% \begin{macrocode}
+ \newcommand*\subcaptionbox{% caption v3.1
+ \def\subcaption@tempa{\caption@ibox\setcaptionsubtype\relax}%
+ \caption@withoptargs\subcaption@tempa}
+% \end{macrocode}
% \begin{macrocode}
-\newcommand*\subcaptionbox{%
- \caption@withoptargs{\caption@ibox\setcaptionsubtype}}
+ \newcommand\caption@ibox[3]{%
+ \kernel@ifnextchar[%]
+ {\caption@iibox{#1}{#2}{#3}}%
+ {\caption@iibox@{#1}{#2}{#3}}}
+% \end{macrocode}
+% \begin{macrocode}
+ \long\def\caption@iibox#1#2#3[#4]{%
+ \@testopt{\caption@iiibox{#1}{#2}{#3}[{#4}]}\captionbox@innerpos@default}
+% \end{macrocode}
+% \begin{macrocode}
+ \long\def\caption@iibox@#1#2#3#4{%
+ \setbox\@tempboxa\hbox{#4}%
+ \caption@iiibox{#1}{#2}{#3}%
+ [\wd\@tempboxa]%
+ [\captionbox@innerpos@default]%
+ {\unhbox\@tempboxa}}
+% \end{macrocode}
+% \begin{macrocode}
+ \long\def\caption@iiibox#1{%
+ \caption@iiiibox{#1}\vbox\vtop}
+% \end{macrocode}
+% \begin{macrocode}
+ \long\def\caption@iiiibox#1#2#3#4#5[#6][#7]#8{%
+ \@ifundefined{caption@hj@#7}%
+ {\subcaption@Error{Undefined justification `#7'}\@gobble}%
+ {\@firstofone}%
+ {\begingroup
+ #1*% set \caption@position so \caption@iftop expands correctly
+ \caption@iftop{%
+ \endgroup
+ \parbox[t]{#6}{%
+ #1\relax
+ \caption@setposition t%
+ #2{\caption#4{#5}}%
+ \captionbox@hrule
+ \csname caption@hj@#7\endcsname
+ #8}%
+ }{%
+ \endgroup
+ \parbox[b]{#6}{%
+ #1\relax
+ \caption@setposition b%
+ \csname caption@hj@#7\endcsname
+ #8%
+ \captionbox@hrule
+ #3{\caption#4{#5}}}%
+ }}}
+% \end{macrocode}
+% \begin{macrocode}
+ \newcommand*\captionbox@innerpos@default{c}
+ \newcommand*\captionbox@hrule{\hrule\@height\z@\relax}
+% \end{macrocode}
+% \begin{macrocode}
+ \providecommand*\caption@hj@c{\centering}
+ \providecommand*\caption@hj@l{\raggedright}
+ \providecommand*\caption@hj@r{\raggedleft}
+ \providecommand*\caption@hj@s{}
+% \end{macrocode}
+% \begin{macrocode}
+}{\@ifundefined{caption@iiibox}{%
+% \end{macrocode}
+% \begin{macrocode}
+ \newcommand*\subcaptionbox{% caption v3.2
+ \def\captionbox@type{subtype}%
+ \let\captionbox@settype\setcaptionsubtype
+ \caption@withoptargs\caption@box}
+% \end{macrocode}
+% \begin{macrocode}
+}{%
+% \end{macrocode}
+% \begin{macrocode}
+ \newcommand*\subcaptionbox{% caption >= v3.3
+ \caption@withoptargs{\caption@ibox\setcaptionsubtype}}
+% \end{macrocode}
+% \begin{macrocode}
+}}
% \end{macrocode}
% \end{macro}
%
-% \pagebreak[3]
% \subsubsection{The \cs{subref} command}
%
-% At |\captionsetup{subtype}|, we redefine |\label|.
+% We redefine |\label| to |\subcaption@label| at |\setcaptionsubtype|.
% \begin{macrocode}
\g@addto@macro\caption@subtypehook{%
\ifx\label\subcaption@label \else
@@ -1123,11 +2113,13 @@
% \end{macrocode}
%
% \begin{macro}{\subcaption@label}
-% \changes{v1.1}{2011/09/12}{Redefinition of \cs{SK@} added}
+% \changes{v1.1}{2011/09/12}{Adapted to the \pkg{showkeys} package}
% \changes{v1.1}{2011/09/12}{Uses \cs{caption@withoptargs} now}
% \changes{v1.1}{2016/02/20}{Unwanted space removed}
+% \changes{v1.4b}{2021/01/08}{Local re-definitions of \cs{@bsphack} and \cs{@esphack} added}
+% \changes{v1.4c}{2021/04/10}{Adaption to the \pkg{showkeys} package out-sourced to \cs{subcaption@prepare@label}}
% When a label will be placed for a sub-caption, we automatically place
-% a second one for |\subref|, too. This second label will contain
+% a second one for |\sub|\-|ref|, too. This second label will contain
% the sub-type counter only.
% \begin{macrocode}
\newcommand*\subcaption@label{%
@@ -1136,14 +2128,41 @@
% \begin{macrocode}
\newcommand*\subcaption@@label[2]{%
\@bsphack\begingroup
+ \let\@bsphack\relax
+ \let\@esphack\relax
+% \end{macrocode}
+% Label |\@currentlabel| by expanding the original |\label| code.
+% \begin{macrocode}
\subcaption@ORI@label#1{#2}%
- \let\SK@\@gobbletwo
+% \end{macrocode}
+% Set |\@currentlabel| to the `sub' counter value and expand the original |\label| code again.
+% (But this time without optional arguments.)
+% \begin{macrocode}
+ \subcaption@prepare@label
\protected@edef\@currentlabel{\csname thesub\@captype\endcsname}%
- \subcaption@ORI@label#1{sub@#2}%
+ \subcaption@ORI@label{sub@#2}%
\endgroup\@esphack}
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\subcaption@prepare@label}
+% \changes{v1.4c}{2021/04/10}{This macro added}
+% \changes{v1.4c}{2021/04/10}{Adapted to the \pkg{showlabels} package}
+% \begin{macrocode}
+\newcommand*\subcaption@prepare@label{%
+% \end{macrocode}
+% Adaption to the \pkg{showkeys} package: Hide the `sub' label from it.
+% \begin{macrocode}
+ \let\SK@\@gobbletwo
+% \end{macrocode}
+% Adaption to the \pkg{showlabels} package: Hide the `sub' label from it
+% by expanding to the original definition saved to |\SL@orig#1|
+% (with |#1| $=$ |\SL@orig|\-|label|, \ldots).
+% \begin{macrocode}
+ \def\SL@showlabels##1{\@nameuse{SL@orig##1}}}
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\subref}
% \changes{v1.1}{2011/08/14}{Caption option \opt{subrefformat=} added}
% \changes{v1.1}{2011/08/18}{Uses \cs{caption@setoptions*} now}
@@ -1157,7 +2176,7 @@
{\caption@withoptargs\subcaption@ref*}%
{\caption@withoptargs\@subref}}
\newcommand*\@subref[2]{%
- \caption@ifundefined\hyperref
+ \@ifundefined{hyperref}%
{\subcaption@ref{#1}{#2}}%
{\hyperref[{#2}]{\subcaption@ref{*#1}{#2}}}}
% \end{macrocode}
@@ -1178,21 +2197,24 @@
% \end{macrocode}
%
% \begin{macro}{\subcaption@setrefformat}
-% \changes{v1.3g}{2020/07/27}{Adapted to \package{caption3} v2.0}
+% \changes{v1.3g}{2020/07/27}{Adapted to \pkg{caption3} v2.0}
% \changes{v1.3h}{2020/09/28}{Usage of \cs{caption@Error} replaced by \cs{subcaption@Error}}
% \changes{v1.3j}{2020/10/07}{Definition of the label formats \texttt{subsimple} and \texttt{subparens} added}
+% \changes{v1.4}{2020/12/24}{Adapted to older versions of the caption package (fallback)}
% |\subcaption@setrefformat|\marg{name}\par
% Selecting a subref format simply means saving the code (in |\subcaption@reffmt|).
% \begin{macrocode}
\newcommand*\subcaption@setrefformat[1]{%
- \@ifundefined{caption@labelformat@#1}%
- {\subcaption@Error{Undefined label format `#1'}}%
+ \@ifundefined{caption@labelformat@#1}% caption3 v2.x
+ {\@ifundefined{caption@lfmt@#1}% caption3 v1.x
+ {\subcaption@Error{Undefined label format `#1'}}%
+ {\expandafter\let\expandafter\subcaption@reffmt\csname caption@lfmt@#1\endcsname}}%
{\expandafter\let\expandafter\subcaption@reffmt\csname caption@labelformat@#1\endcsname}}
% \end{macrocode}
% \begin{macrocode}
\subcaption@setrefformat{simple}
% \end{macrocode}
-% To offer a smooth transition from the \package{subfig} to the \package{subcaption} package
+% To offer a smooth transition from the \pkg{subfig} to the \pkg{subcaption} package
% we offer the options |sub|\-|ref|\-|format=sub|\-|simple| and |sub|\-|ref|\-|format=sub|\-|parens|, too.
% \begin{macrocode}
\DeclareCaptionLabelFormat{subsimple}{#2}
@@ -1202,50 +2224,154 @@
%
% \subsection{Execution of options}
%
-% \changes{v1.1}{2018/05/01}{Option \texttt{font+=smaller} changed to \texttt{size=smaller}}
-% \changes{v1.3e}{2020/07/27}{Option \texttt{size=smaller} changed back to \texttt{font+=smaller}}
+% \changes{v1.1}{2018/05/01}{Option \texttt{font+=small} changed to \texttt{font+=smaller}} \changenote{released 2018/05/02}
+% \changes{v1.2}{2018/05/13}{Option \texttt{font+=smaller} changed to \texttt{size=smaller}} \changenote{merged from former SVN/trunk 2019/03/16, released 2019/08/18}
+% \changes{v1.3e}{2020/07/27}{Option \texttt{size=smaller} changed back to \texttt{font+=smaller}} \changenote{merged from feature/documentclass 2020/07/29, released 2020/08/30}
% We use |\caption@Execute|\-|Options| and |\caption@Process|\-|Options| here to add
% the options to the `|sub|' option list instead of executing them immediately.
% \begin{macrocode}
-\caption@SetupOptions{subcaption}{\captionsetup[sub]{#2}}%
-\caption@ExecuteOptions{subcaption}{%
- font+=smaller,labelformat=parens,labelsep=space,skip=6pt,list=0,hypcap=0}
+\let\caption@setkeys@ORI\caption@setkeys
+\@ifundefined{caption@SetupOptions} % caption3 v1.3
+ {\renewcommand\caption@setkeys[2]{\captionsetup[sub]{#2}}}
+ {\caption@SetupOptions{subcaption}{\captionsetup[sub]{#2}}}
+% \end{macrocode}
+% \begin{macrocode}
+\@ifundefined{caption@smaller} % caption3 v1.7-169
+ {\caption@ExecuteOptions{subcaption}{%
+ font+=small,labelformat=parens,labelsep=space,skip=6pt,list=0,hypcap=0}}
+ {\caption@ExecuteOptions{subcaption}{%
+ font+=smaller,labelformat=parens,labelsep=space,skip=6pt,list=0,hypcap=0}}
+% \end{macrocode}
+% \begin{macrocode}
\caption@ProcessOptions*{subcaption}
% \end{macrocode}
+% \begin{macrocode}
+\let\caption@setkeys\caption@setkeys@ORI
+\let\caption@setkeys@ORI\@undefined
+% \end{macrocode}
%
-% \changes{v1.1}{2011/10/30}{Adapted to the newfloat package}
-% We call |\Declare|\-|Caption|\-|Sub|\-|Type| for |figure|, |table|,
+% We call |\Declare|\-|Caption|\-|Sub|\-|Type| for |figure| and |table|,
% and each floating environment declared with |\Declare|\-|Floating|\-|Environment| here.
% \begin{macrocode}
-\ForEachCaptionType{\DeclareCaptionSubType{#1}}
+\@ifundefined{ForEachCaptionType} % caption3 v1.13
+ {\@ifundefined{caption@ForEachType} % caption3 v1.4a
+ {\@ifundefined{c@figure}{}{\DeclareCaptionSubType{figure}}%
+ \@ifundefined{c@table}{}{\DeclareCaptionSubType{table}}%
+ \caption@For{typelist}{\DeclareCaptionSubType{#1}}}
+ {\caption@ForEachType{\DeclareCaptionSubType{#1}}}}
+ {\ForEachCaptionType{\DeclareCaptionSubType{#1}}}
% \end{macrocode}
%
% \subsection{Bonus material}
%
+% \subsubsection{The \cs{subcaption}, \cs{phantomsubcaption}, \cs{subcaptionlistentry}, and \cs{subcaptiontext} commands}
+%
+% \begin{macro}{\subcaption@newabbreviation}
+% \changes{v1.5}{2022/01/07}{This macro added}
+% |\subcaption@newabbreviation|\marg{new command}\marg{existing command}\marg{extra code in case of error}\\
+% defines a new command as abbreviation of |\set|\-|caption|\-|sub|\-|type*| plus \meta{command}.
+% (With a prefacing |\set|\-|caption|\-|sub|\-|type|, \meta{new command} is reduced to \meta{command}.
+% Unfortunately we have to do this on our own since using |\set|\-|caption|\-|sub|\-|type| multiple times
+% is not suppressed until \pkg{caption} package \version{3.6}.)
+% \Note{Since \cs{setcaptionsubtype} is used, the new command is designed to be used inside an own group!}
+% \begin{macrocode}
+\newcommand*\subcaption@newabbreviation[3]{%
+% \end{macrocode}
+% \begin{macrocode}
+ \newcommand*{#1}{%
+ \caption@iftype
+ {\setcaptionsubtype*#2}%
+ {\subcaption@OutsideFloat#1#3}}%
+% \end{macrocode}
+% \begin{macrocode}
+ \g@addto@macro\caption@subtypehook{\let#1#2}}% needed for caption < 3.6
+% \end{macrocode}
+% \begin{macrocode}
+\@onlypreamble\subcaption@newabbreviation
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\caption@gobble}
+% \changes{v1.4}{2020/12/24}{This macro added}
+% |\caption@gobble*|\oarg{arg}\oarg{\ldots}\marg{arg}\\
+% is similar to |\@gobble| but gobbles a star and optional arguments as well.
+% \begin{macrocode}
+\@ifundefined{caption@gobble}{%
+ \DeclareRobustCommand*\caption@gobble{% caption3 < v1.4
+ \caption@withoptargs\@gobbletwo}%
+}{}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\subcaption}
+% \changes{v1.1}{2012/04/06}{Overwrites the definition defined by the \pkg{memoir} document class}
+% |\subcaption| is an abbreviation of |\set|\-|caption|\-|sub|\-|type*| plus |\caption|.
+% \begin{macrocode}
+\@ifclassloaded{memoir}{\let\subcaption\undefined}{}
+\subcaption@newabbreviation\subcaption\caption\caption@gobble
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\phantomsubcaption}
+% \changes{v1.1}{2011/08/17}{This macro added}
+% \changes{v1.3h}{2020/09/28}{Usage of \cs{caption@Error} replaced by \cs{subcaption@Error}}
+% |\phantom|\-|sub|\-|caption| is an abbreviation of |\set|\-|caption|\-|sub|\-|type*| plus |\phantom|\-|caption|.
+% \Note{This commands needs at least \pkg{caption} package \version{3.2}.}
+% \begin{macrocode}
+\subcaption@newabbreviation\phantomsubcaption\phantomcaption\relax
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\subcaptionlistentry}
+% \changes{v1.5}{2022/01/05}{This macro added}
+% |\sub|\-|caption|\-|list|\-|entry| is an abbreviation of |\set|\-|caption|\-|sub|\-|type*| plus |\caption|\-|list|\-|entry|.
+% \Note{This commands needs at least \pkg{caption} package \version{3.3}.}
+% \begin{macrocode}
+\subcaption@newabbreviation\subcaptionlistentry\captionlistentry\caption@gobble
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\subcaptiontext}
+% \changes{v1.5}{2022/01/05}{This macro added}
+% |\sub|\-|caption|\-|text| is an abbreviation of |\set|\-|caption|\-|sub|\-|type*| plus |\caption|\-|text|.
+% \Note{This commands needs at least \pkg{caption} package \version{3.6}.}
+% \begin{macrocode}
+\subcaption@newabbreviation\subcaptiontext\captiontext\caption@gobble
+% \end{macrocode}
+% \end{macro}
+%
% \subsubsection{The \cs{subfloat} command}
%
% \begin{macro}{\subfloat}
% \changes{v0.4}{2008/03/01}{This macro added}
-% \changes{v1.0c}{2011/01/22}{This macro removed since it's too incompatible with the one from \package{subfig}}
+% \changes{v1.0c}{2011/01/22}{This macro removed since it's too incompatible with the one from \pkg{subfig}}
% \changes{v1.3}{2019/08/31}{This macro re-added and revised}
% \changes{v1.3a}{2019/09/01}{\cs{ignorespaces} copied from \cs{sf@@@subfloat}}
% \changes{v1.3b}{2020/01/03}{Previous definition of \cs{subfloat} will be overwritten}
% \changes{v1.3f}{2020/07/29}{Bugfix: Usage of \cs{caption@hj@default} replaced by \cs{captionbox@innerpos@default}}
% \changes{v1.3i}{2020/09/28}{This macro will be defined with \cs{providecommand} now to preserve an original definition}
+% \changes{v1.4}{2020/12/24}{Usage of \cs{caption@getlabel} replaced by \cs{subcaption@getlabel}}
+% \changes{v1.4a}{2020/12/26}{Clearance of \cs{caption@thelabel} replaced by \cs{subcaption@clrlabel}}
+% \changes{v1.5}{2022/01/07}{Usage of \cs{@ifnextchar} replaced by \cs{kernel@ifnextchar}}
+% \changes{v1.5}{2022/01/07}{Overwrites the definition defined by the \pkg{memoir} document class}
% |\subfloat|\oarg{list\_entry}\oarg{sub-caption}\marg{body}\par
% If \meta{sub-caption} is given, we map this to |\sub|\-|caption|\-|box|
% but transfer the |\label| from \meta{body} to \meta{sub-caption}.
% If not, we do the same as |\sub|\-|caption|\-|box| does, but use |\phantom|\-|caption| instead of |\caption|.
% In both cases we do a |\ignore|\-|spaces| at the end since the original implementation of |\sub|\-|float| does this, too.
% \begin{macrocode}
-\caption@AtBeginDocument{\providecommand*\subfloat{%
- \@ifnextchar[%]
- \subcaption@subfloat
- \subcaption@subfloat@}}
+\@ifclassloaded{memoir}{\let\subfloat\undefined\let\endsubfloat\undefined}{}
+% \end{macrocode}
+% \begin{macrocode}
+\caption@AtBeginDocument{%
+ \providecommand*\subfloat{%
+ \kernel@ifnextchar[%]
+ \subcaption@subfloat
+ \subcaption@subfloat@}}
% \end{macrocode}
% \begin{macrocode}
\long\def\subcaption@subfloat[#1]{%
- \@ifnextchar[%]
+ \kernel@ifnextchar[%]
{\subcaption@@subfloat{#1}}%
{\subcaption@@@subfloat\subcaptionbox{#1}}}
% \end{macrocode}
@@ -1255,9 +2381,9 @@
% \end{macrocode}
% \begin{macrocode}
\long\def\subcaption@@@subfloat#1#2#3{%
- \caption@getlabel{#3}%
+ \subcaption@getlabel{#3}%
#1{#2\caption@thelabel}{\let\label\caption@gobble#3}%
- \global\let\caption@thelabel\relax
+ \subcaption@clrlabel
\ignorespaces}
% \end{macrocode}
% \begin{macrocode}
@@ -1274,6 +2400,60 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\subcaption@getlabel}
+% \changes{v1.4}{2020/12/24}{This macro added}
+% |\subcaption@getlabel|\marg{text}\\
+% gets the label command out of the given caption text and stores it to |\caption@the|\-|label|.
+% It uses |\caption@get|\-|label| for this purpose which interface unfortunately has changed over time.
+% (Changing the interface was a bad idea in the first place but now it is as it is).
+% \begin{macrocode}
+\@ifundefined{caption@getlabel}{%
+% \end{macrocode}
+% \begin{macrocode}
+ \newcommand\subcaption@getlabel[1]{% caption3 < v1.7
+ \subcaption@Error{\noexpand\subfloat needs at least caption v3.4}%
+ \let\caption@thelabel\relax}
+% \end{macrocode}
+% \begin{macrocode}
+}{\@ifundefined{caption@@@@getlabel}{%
+% \end{macrocode}
+% \begin{macrocode}
+ \newcommand\subcaption@getlabel[1]{% caption3 >= v1.7
+ \caption@getlabel#1\label{}\@nil}
+% \end{macrocode}
+% \begin{macrocode}
+}{%
+% \end{macrocode}
+% \begin{macrocode}
+ \newcommand*\subcaption@getlabel{% caption3 >= v2.0
+ \caption@getlabel}
+% \end{macrocode}
+% \begin{macrocode}
+}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\subcaption@clrlabel}
+% \changes{v1.4a}{2020/12/26}{This macro added}
+% |\subcaption@clrlabel|\\
+% resets |\caption@the|\-|label| to |\relax|.
+% \begin{macrocode}
+\@ifundefined{caption@clrlabel}{%
+% \end{macrocode}
+% \begin{macrocode}
+ \newcommand*\subcaption@clrlabel{\let\caption@thelabel\relax} % caption3 < v2.3
+% \end{macrocode}
+% \begin{macrocode}
+}{%
+% \end{macrocode}
+% \begin{macrocode}
+ \newcommand*\subcaption@clrlabel{\caption@clrlabel} % caption3 >= v2.3
+% \end{macrocode}
+% \begin{macrocode}
+}
+% \end{macrocode}
+% \end{macro}
+%
% \iffalse
%</package>
% \fi