summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/caption/subcaption.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-07-29 03:00:48 +0000
committerNorbert Preining <norbert@preining.info>2023-07-29 03:00:48 +0000
commit68c7c6f998e30e40017dae0faded16f93773c786 (patch)
tree66ad2c81e1296e370bd968ff224a5f3e70e956bc /macros/latex/contrib/caption/subcaption.dtx
parent1e45d661b659c3025746d3a41119300ab90d1dcd (diff)
CTAN sync 202307290300
Diffstat (limited to 'macros/latex/contrib/caption/subcaption.dtx')
-rw-r--r--macros/latex/contrib/caption/subcaption.dtx173
1 files changed, 63 insertions, 110 deletions
diff --git a/macros/latex/contrib/caption/subcaption.dtx b/macros/latex/contrib/caption/subcaption.dtx
index 0283d91eef..ac8c14a4dc 100644
--- a/macros/latex/contrib/caption/subcaption.dtx
+++ b/macros/latex/contrib/caption/subcaption.dtx
@@ -31,67 +31,23 @@
%
% \fi
%
-% \CheckSum{513}
+% \CheckSum{511}
%
% \iffalse
%<*driver>
\NeedsTeXFormat{LaTeX2e}[1994/12/01]
-\ProvidesFile{subcaption.drv}[2023/02/19 v1.6 Adds a sub-caption feature to the caption package]
-\hbadness=9999 \newcount\hbadness \hfuzz=74pt % Make TeX shut up.
+\ProvidesFile{subcaption.drv}[2023/07/10 v1.6 Adds a sub-caption feature to the caption package]
%\errorcontextlines=3
%
-\documentclass{ltxdoc}
-\setlength\parindent{0pt}
-\setlength\parskip{\smallskipamount}
-\addtolength\marginparwidth{15pt}
-%
-\usepackage{ifpdf}
-\ifpdf
- \usepackage{mathptmx,courier}
- \usepackage[scaled=0.90]{helvet}
-\fi
-%
-\usepackage[bottom]{footmisc}
-\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={}}
+\documentclass{captiondoc}
+\hypersetup{pdfkeywords={LaTeX, package, subcaption}}
%
\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\cls\puresf \let\pkg\puresf
-\let\env\purett \let\opt\purett
-%
-\newcommand*\csmarg[1]{\texttt{\char`\{#1\char`\}}}
-\newcommand*\csoarg[1]{\texttt{\char`\[#1\char`\]}}
-\newcommand*\version[2][]{v$#2$}
-%
-\usepackage{marvosym}
-\makeatletter
-\newcommand*\INFO{\@ifstar{\@INFO{}}{\@INFO{\vbox to \ht\strutbox}}}
-\newcommand*\@INFO[1]{\MARGINSYM{#1{\LARGE\Info}}}
-\makeatother
-%
-\usepackage[alpine]{ifsym}
-\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[1]{\@ifstar{\@NEW{#1}{\vskip2pt}}{\@NEW{#1}{}}}
-\newcommand*\@NEW[3]{\MARGINSYM{#2\footnotesize#1\\#3}}
-\makeatother
-%
-\newcommand*\PageBreak{\pagebreak[3]}
-\newcommand*\changenote[1]{}
+\usepackage{array,diagbox,graphicx,overpic,pict2e,stackengine,tikz}
%
\begin{document}
\DocInput{subcaption.dtx}
@@ -99,21 +55,9 @@
%</driver>
% \fi
%
-% \let\subsectionautorefname\sectionautorefname
-% \let\subsubsectionautorefname\sectionautorefname
-%
% \def\thispackage{the \pkg{subcaption} package}
% \def\Thispackage{The \pkg{subcaption} package}
%
-% \newcommand\NEWfeature{\NEW{New feature}}
-% \newcommand\NEWdescription{\NEW{New description}}
-%
-% \makeatletter
-% \def\Ref{\@ifstar{\@Ref\ref}{\@Ref\autoref}}
-% \def\@Ref#1#2{#1{#2}: \textit{\nameref{#2}}}
-% \makeatother
-% \def\See#1{\nopagebreak{\small (See #1)}}
-%
% \GetFileInfo{subcaption.drv}
% \let\docdate\filedate
% \let\docversion\fileversion
@@ -283,7 +227,7 @@
%
% \DescribeMacro\subcaptionbox
% 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.
+% It automatically aligns the sub-figures or sub-tables by their very first caption line.
%
% \pagebreak[3]
% Its syntax is:
@@ -449,8 +393,8 @@
% \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 contents at the
-% very top resp.~bottom. (In contrast `t' and `b' align the contents at the
-% top resp.~bottom \textit{baseline}.)
+% very top or bottom. (In contrast `t' and `b' align the contents at the
+% top or bottom \textit{baseline}.)
%
% \bigskip
%
@@ -521,13 +465,13 @@
% 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}}
+% \See{\longref{hypcap}}
% \end{itemize}
%
% \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|.)
+% The |sub|\-|caption|\-|block| environment is also offered as |sub|\-|figure| or |sub|\-|table|.
+% (And prior version $1.5$ of \thispackage\ it was only available as |sub|\-|figure| or |sub|\-|table|.)
%
% 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.
@@ -782,11 +726,28 @@
%
% \bigskip
%
+% \pagebreak[3]
% \INFO
% {\small Please note that you need to surround redefinitions of |\p@|\-\meta{counter}
-% with |\makeatletter| and |\makeatother|. See
+% with |\make|\-|at|\-|letter| and |\make|\-|at|\-|other|. See
% \url{http://tex.stackexchange.com/questions/8351/}
-% for details.}
+% for details.
+%
+% Since October 2019 |\p@|\-\meta{counter} could be redefined using |\label|\-|format| instead,
+% dropping the need to use |\make|\-|at|\-|letter| and |\make|\-|at|\-|other|.
+% Furthermore not only prefixes could be specified this way,
+% instead the counter representation could be used at any position in the text.
+% So for example
+% \begin{quote}
+% |\makeatletter|\\
+% |\renewcommand\p@subfigure{\thefigure}|\\
+% |\makeatother|\\
+% \end{quote}
+% (which prefixes the subfigure counter representation with the figure counter representation)
+% could be replaced by
+% \begin{quote}
+% |\labelformat{subfigure}{\thefigure #1}|
+% \end{quote}}
%
% \pagebreak[3]
% \subsection{The \cs{subref} command}
@@ -860,7 +821,7 @@
% instead of |\caption|.
%
% |\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
+% does not generate any output but increases the sub-figure or sub-table counter
% and gives you an anchor for a |\label| command which can be placed after it.
%
% \pagebreak[3]
@@ -910,10 +871,10 @@
%
% |\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
+% the sub-figure or 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.
+% of figures or tables.
%
% \pagebreak[3]
% An example:
@@ -941,14 +902,14 @@
%
% 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 increments the sub-figure or sub-table counter and generates an internal reference which could be used with |\label|
+% \item It puts an entry into the list of figures or 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.
+% result, for example a sub-figure or sub-table counter which was incremented more than once.
%
% \DescribeMacro\captiontext
% In these cases the |\caption| command could be split into
@@ -964,11 +925,11 @@
% |\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
+% as opposite to |\caption| it does not increase the sub-figure or 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}.
+% For example code please take a look at \longref{inside}.
%
% \pagebreak[3]
% \subsection{Where to place the \cs{label} command?}
@@ -1068,14 +1029,14 @@
% 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 The caption could already be part of the image. (This case is already handled in \longref{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,
+% Note that the commands or 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
+% |\phantomcaption| or |\captionlistentry| should be used outside the command or environment and
% |\captiontext| should be used inside it.
-% See also \Ref{without2}
+% See also \longref{without2}
% \item The options |skip=| and |margin=| could be used to place the caption onto the image.
% \end{itemize}
%
@@ -1083,7 +1044,7 @@
% \subsection{Using the overpic package}
% \label{overpic}
%
-% The same example as in section \Ref{without}, but using the \env{overpic} environment
+% The same example as in section \longref{without}, but using the \env{overpic} environment
% offered by the \pkg{overpic} package~\cite{overpic}
% to place the captions inside the pictures:
% \begin{quote}
@@ -1128,13 +1089,13 @@
% \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.
+% the usage of |\phantom|\-|caption| or |\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}}
+% \See{\longref{subcaption}}
%
% \begin{quote}
% |\usepackage{overpic}|\\
@@ -1155,7 +1116,7 @@
% \subsection{Using the stackengine package}
% \label{stackengine}
%
-% The same example as in section \Ref{without}, but using the |\stack|\-|inset| command
+% The same example as in section \longref{without}, but using the |\stack|\-|inset| command
% offered by the \pkg{stackengine} package~\cite{stackengine}
% to place the captions inside the pictures:
% \begin{quote}
@@ -1213,7 +1174,7 @@
% \subsection{Using the tikz package}
% \label{tikz}
%
-% The same example as in section \Ref{without}, but using the \env{tikzpicture} environment
+% The same example as in section \longref{without}, but using the \env{tikzpicture} environment
% offered by the \pkg{tikz} package~\cite{tikz}
% to place the captions inside the pictures:
% \begin{quote}
@@ -1293,7 +1254,7 @@
% 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:
+% The same example as in section \longref{without}, but using the |skip=|\ldots and |margin=|\ldots options:
% \begin{quote}
% |\begin{figure}|\\
% | \centering|\\
@@ -1452,12 +1413,12 @@
% \ldots
% \end{quote}
%
-% See also: \Ref{sec:caption}
+% See also: \longref{sec:caption}
%
% \subsection{Pittfall \#2: Expecting \cs{caption} to increment the counter}
%
% \pagebreak[3]
-% Usually |\caption| increments the figure resp.~table counter and therefore
+% Usually |\caption| increments the figure or table counter and therefore
% it is usally safe to assume that the counter was not incremented yet in code
% used before |\caption|:
% \begin{quote}
@@ -1499,7 +1460,7 @@
% 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.
+% tricky stuff with the figure or table counter within figures or tables.
%
% \iffalse
% --------------------------------------------------------------------------- %
@@ -1514,7 +1475,7 @@
% \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}}
+% As we have seen in sections {\longref{overpic}, \longref{stackengine}, and \longref{tikz}}
% it's sometimes inconvenient to use the commands and environments
% described so far.
%
@@ -1631,10 +1592,11 @@
% 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 |\phantomsubcaption| command needs at least \pkg{caption} \version{3.2}.
+% \item The |\subcaptionlistentry| command needs at least \pkg{caption} \version{3.3}.
% \item The |\subfloat| emulation needs at least \pkg{caption} \version{3.4}.
+% \item The |\subcaptiontext| command needs at least \pkg{caption} \version{3.6}.
+% \item The |\subcaptionsetup| command needs at least \pkg{caption} \version{3.6l}.
% \end{itemize}
%
% \iffalse
@@ -1873,7 +1835,7 @@
%
% Identify the current version of the package.
% \begin{macrocode}
-\ProvidesPackage{subcaption}[2023/02/19 v1.6 Sub-captions (AR)]
+\ProvidesPackage{subcaption}[2023/07/28 v1.6b Sub-captions (AR)]
% \end{macrocode}
%
% Since we base on the \pkg{caption} package we load it here.
@@ -1930,17 +1892,6 @@
%
% \subsection{Main code}
%
-% \begin{macro}{\subcaptionsetup}
-% \changes{v1.6}{2023/02/19}{This macro definition added}
-% |\subcaptionsetup*|\oarg{environment}\marg{options}
-% is an abbreviation for |\caption|\-|setup*[sub|\meta{environment}|]|\marg{options},
-% especially |\sub|\-|caption|\-|setup|\marg{options} sets options valid for all sub-captions.
-% \begin{macrocode}
-\newcommand*\subcaptionsetup[1][]{%
- \@ifstar{\captionsetup*[{sub#1}]}{\captionsetup[{sub#1}]}}
-% \end{macrocode}
-% \end{macro}
-%
% \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}
@@ -2284,15 +2235,17 @@
% \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)}
+% \changes{v1.6b}{2023/07/28}{Adapted to the \pkg{subfig} package}
% |\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}% caption3 v2.x
{\@ifundefined{caption@lfmt@#1}% caption3 v1.x
- {\subcaption@Error{Undefined label format `#1'}}%
+ {\@ifundefined{caption@subreffmt@#1}{\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}}
+ {\expandafter\let\expandafter\subcaption@reffmt\csname caption@labelformat@#1\endcsname}%
+ \@ifundefined{caption@subreffmt@#1}{}{\caption@setsubrefformat{#1}}} % subfig v1.3
% \end{macrocode}
% \begin{macrocode}
\subcaption@setrefformat{simple}
@@ -2315,8 +2268,8 @@
% \begin{macrocode}
\let\caption@setkeys@ORI\caption@setkeys
\@ifundefined{caption@SetupOptions} % caption3 v1.3
- {\renewcommand\caption@setkeys[2]{\subcaptionsetup{#2}}}
- {\caption@SetupOptions{subcaption}{\subcaptionsetup{#2}}}
+ {\renewcommand\caption@setkeys[2]{\captionsetup[sub]{#2}}}
+ {\caption@SetupOptions{subcaption}{\captionsetup[sub]{#2}}}
% \end{macrocode}
% \begin{macrocode}
\@ifundefined{caption@smaller} % caption3 v1.7-169