summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/caption/caption-eng.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-08-31 03:02:58 +0000
committerNorbert Preining <norbert@preining.info>2020-08-31 03:02:58 +0000
commit568fe838cef40f671837d9348dd73c93d9ea962b (patch)
treeba2b2c6ab585927a89adae8c1cc2a594010ab933 /macros/latex/contrib/caption/caption-eng.tex
parentc6a1b1f6422e10f363a9de80c4f103f0c155d8bb (diff)
CTAN sync 202008310302
Diffstat (limited to 'macros/latex/contrib/caption/caption-eng.tex')
-rw-r--r--macros/latex/contrib/caption/caption-eng.tex304
1 files changed, 252 insertions, 52 deletions
diff --git a/macros/latex/contrib/caption/caption-eng.tex b/macros/latex/contrib/caption/caption-eng.tex
index ef9fd38923..8a10baffd0 100644
--- a/macros/latex/contrib/caption/caption-eng.tex
+++ b/macros/latex/contrib/caption/caption-eng.tex
@@ -1,7 +1,7 @@
%
% This is file `caption-eng.tex'.
%
-% Copyright (C) 1994-2012 Axel Sommerfeldt (axel.sommerfeldt@f-m.fm)
+% Copyright (C) 1994-2020 Axel Sommerfeldt (axel.sommerfeldt@f-m.fm)
%
% --------------------------------------------------------------------------
%
@@ -17,14 +17,21 @@
%
% This Current Maintainer of this work is Axel Sommerfeldt.
%
-% This work consists of the files caption.ins, caption.dtx, caption2.dtx,
-% caption3.dtx, bicaption.dtx, ltcaption.dtx, subcaption.dtx, and newfloat.dtx,
-% the derived files caption.sty, caption2.sty, caption3.sty,
-% bicaption.sty, ltcaption.sty, subcaption.sty, and newfloat.sty,
-% and the user manuals caption-deu.tex, caption-eng.tex, and caption-rus.tex.
+% This work consists of the files
+% caption.ins, caption.dtx, caption-light.dtx, caption2.dtx, caption3.dtx,
+% caption-ams-smf.dtx, caption-beamer.dtx, caption-elsarticle.dtx,
+% caption-koma.dtx, caption-memoir.dtx, caption-ntg.dtx,
+% caption-thesis.dtx, bicaption.dtx, ltcaption.dtx, subcaption.dtx,
+% the derived files
+% 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.
%
\NeedsTeXFormat{LaTeX2e}[1994/12/01]
-\ProvidesFile{caption-eng.tex}[2011/11/02 v3.2 The caption package]
+\ProvidesFile{caption-eng.tex}[2020/08/30 v3.5 The caption package]
\hbadness=9999 \newcount\hbadness \hfuzz=20pt % Make TeX shut up.
%\errorcontextlines=3
@@ -187,9 +194,11 @@
\GetFileInfo{caption-eng.tex}
\let\docdate\filedate
+\let\docversion\fileversion
\GetFileInfo{caption.sty}
-\title{Customizing captions of floating environments}
+\title{Customizing captions of floating environments\texorpdfstring{%
+ \thanks{This package has version number \docversion.}}{}}
\author{Axel Sommerfeldt\\
\url{https://gitlab.com/axelsommerfeldt/caption}}
\date{\docdate}
@@ -206,7 +215,7 @@ many other packages.
commands for customizing captions.
If these possibilities are sufficient for you, there is usually no need for
you to use the \package{caption} package at all.
-And if you are just interested in using the command \cs{captionof}, loading of
+And if you are only interested in using the command \cs{captionof}, loading of
the very small \package{capt-of} package is usually sufficient.
\end{abstract}
@@ -218,6 +227,41 @@ the very small \package{capt-of} package is usually sufficient.
% --------------------------------------------------------------------------- %
+\section*{State of this document}
+
+This documentation is outdated.
+
+It documents the options and commands available in version \version{3.1} of the
+\package{caption} package, but many things added later on is missing here. Why?
+\begin{itemize}
+\item
+ I wasn't happy with the structure of the documentation, so I decided to write a new one.
+ So why updating the abandoned documentation?
+ (Unfortunately I never found the time to actually write the new one.)
+\item
+ Since my spare time was extremly limited since version \version{3.1} I didn't
+ wanted to hold improvements and enhancements back for months because of missing
+ documentation.
+\item
+ Since I used to fix bugs in the most recent development version only,
+ I didn't wanted to hold bugfixes back for months because of missing
+ documentation of features.
+ (But since 2015 bugs will usually get fixed for the latest release version as well,
+ and released to CTAN as bug-fixed version afterwards.)
+\end{itemize}
+
+What now?
+\begin{itemize}
+\item
+ I will start revising this documentation in the next weeks, finally bringing it up-to-date.
+\item
+ Until the revised documentation is ready the most recent version could be found at
+ \url{https://gitlab.com/axelsommerfeldt/caption/-/blob/master/doc/caption-eng.pdf}
+ since I will not upload every improvement of the documentation to CTAN immediately.
+\end{itemize}
+
+% --------------------------------------------------------------------------- %
+
\section*{Introduction}
Within the standard \LaTeX\ document classes captions haven't received the
@@ -613,18 +657,18 @@ You can choose one of the following:
Three examples:
\begin{Example}
\begin{quote}
- |format=plain,justification=centerlast|
+ |format=hang,justification=raggedright|
\end{quote}
\captionsetup{skip=0pt}
- \example{format=plain,justification=centerlast}{\exampletext}
+ \example{format=hang,justification=raggedright}{\exampletext}
\end{Example}
\begin{Example}
\begin{quote}
- |format=hang,justification=raggedright|
+ |format=hang,justification=centerlast|
\end{quote}
\captionsetup{skip=0pt}
- \example{format=hang,justification=raggedright}{\exampletext}
+ \example{format=hang,justification=centerlast}{\exampletext}
\end{Example}
\begin{Example}
@@ -761,10 +805,10 @@ Three examples:
\begin{Example}
\begin{quote}
- |labelfont=bf,textfont=it|
+ |labelfont=sc,textfont=it|
\end{quote}
\captionsetup{skip=0pt}
- \example{labelfont=bf,textfont=it}{\exampletext}
+ \example{labelfont=sc,textfont=it}{\exampletext}
\end{Example}
\begin{Example}
@@ -2157,7 +2201,7 @@ This will be achieved by a combination of
% --------------------------------------------------------------------------- %
\clearpage
-\section{Document classes \& Babel support}
+\section{Supported document classes}
\label{classes}
%\NEWdescription{v3.1}
@@ -2369,51 +2413,31 @@ the caption text font with |\caption|\-|body|\-|font|.
Both is still supported unless you use one of the two options
|label|\-|font=| or |text|\-|font=| offered by \thispackage.
-\subsection{frenchb babel option}
-\label{frenchb}
+% --------------------------------------------------------------------------- %
-If you use the \package{frenchb} option of the \package{babel} package
+\clearpage
+\section{Supported babel package options}
+\label{babel}
+
+\NEWfeature{v3.5}
+Since version \version{3.5} of the \package{caption} package the support
+is independent on the load order of \package{caption} and \package{babel}.
+
+\subsection{french babel option}
+\label{french}
+
+If you use the \package{french} option of the \package{babel} package
with one of the three standard \LaTeX{} classes (or a one derived from them)
the default |label|\-|sep=| will be set to |\Caption|\-|Sep|\-|a|\-|ra|\-|tor|
-(offered by \package{frenchb}), overriding the default value set by the
+(offered by \package{french}), overriding the default value set by the
document class.
So redefining |\Caption|\-|Sep|\-|a|\-|ra|\-|tor| will still work, unless you
don't select a different |label|\-|sep=| than the default one.
-\INFO*
-Please load \thispackage\ \emph{after} the \package{babel} package.
-
-\subsection{frenchle and frenchpro packages}
-\label{frenchpro}
-
-If you use the \package{frenchle} or \package{frenchpro} package,
-the default |label|\-|sep=| will be set to |\caption|\-|sep|\-|a|\-|ra|\-|tor|
-(offered by \package{frenchle/pro}) plus \cs{space}, overriding the default
-value set by the document class.
-So redefining |\caption|\-|sep|\-|a|\-|ra|\-|tor| will still work, unless you
-don't select a different |label|\-|sep=| than the default one.
-
-Furthermore the default |text|\-|font=| will be set to |text|\-|font=|\x|it|,
-since this emulates the default setting of |\caption|\-|font| defined by the
-\package{frenchle} or \package{frenchpro} package.
-%If you redefine |\captionfont| after loading the \package{frenchle} or
-%\package{frenchpro} package, this redefinition gets lost.
-Please note that the command |\caption|\-|font| is used by the
-\package{caption} package internally for a different purpose,
-so you should not change it (anymore).
-
-The command |\un|\-|numbered|\-|captions|\marg{figure \emph{or} table} will
-still work, but only unless you don't select a different |label|\-|format=|
-than the default one.
-
-\INFO*
-Please load \thispackage\ \emph{after} the \package{frenchle}
-or \package{frenchpro} package.
-
% --------------------------------------------------------------------------- %
\clearpage
-\section{Package support}
+\section{Supported packages}
\label{packages}
\label{compatibility}
@@ -2680,6 +2704,35 @@ These options will be executed additionally to the regular ones for
|figure| or |table|.
\pagebreak[3]
+\subsection{frenchle and frenchpro packages}
+\label{frenchpro}
+
+If you use the \package{frenchle} or \package{frenchpro} package,
+the default |label|\-|sep=| will be set to |\caption|\-|sep|\-|a|\-|ra|\-|tor|
+(offered by \package{frenchle/pro}) plus \cs{space}, overriding the default
+value set by the document class.
+So redefining |\caption|\-|sep|\-|a|\-|ra|\-|tor| will still work, unless you
+don't select a different |label|\-|sep=| than the default one.
+
+Furthermore the default |text|\-|font=| will be set to |text|\-|font=|\x|it|,
+since this emulates the default setting of |\caption|\-|font| defined by the
+\package{frenchle} or \package{frenchpro} package.
+%If you redefine |\captionfont| after loading the \package{frenchle} or
+%\package{frenchpro} package, this redefinition gets lost.
+Please note that the command |\caption|\-|font| is used by the
+\package{caption} package internally for a different purpose,
+so you should not change it (anymore).
+
+The command |\un|\-|numbered|\-|captions|\marg{figure \emph{or} table} will
+still work, but only unless you don't select a different |label|\-|format=|
+than the default one.
+
+\NEWfeature{v3.5}
+Since version \version{3.5} of the \package{caption} package the support
+is independent on the load order of \package{caption} and \package{frenchle}
+resp~.\package{frenchpro}.
+
+\pagebreak[3]
\subsection{hyperref}
\label{hyperref}
\packagedescription{%
@@ -3811,7 +3864,7 @@ While all the previous versions were designed for usage with the standard
the current version $3.1$ released in 2007 also supports the \AmS,
\KOMAScript, \NTG, and \SmF\ document classes, and the \class{beamer} class
as well.
-Furthermore it was adapted to the \package{frenchb} Babel option,
+Furthermore it was adapted to the \package{french} Babel option,
the \package{frenchle} \& \package{frenchpro} packages,
and the \package{floatflt}, \package{fltpage}, \package{picinpar},
\package{picins}, \package{setspace}, \package{threeparttable},
@@ -4072,6 +4125,152 @@ to the \package{subfig} package instead and do not load \thispackage\ anymore.
% --------------------------------------------------------------------------- %
\clearpage
+\section{Commands for document class authors}
+
+A document class could simply load the \package{caption} package instead
+of defining an own variant of |\@make|\-|caption|. However if the author decides
+not to do this -- for whatever reason -- there is a second option:
+
+\NEWfeature{v3.5}
+If a document class defines |\caption@document|\-|class|, an adaption to the
+\package{caption} package will be loaded as |caption-|\meta{documentclass}|.sto|
+if the \package{caption} kernel is loaded.
+The goal of this adaption file is changing the default settings of the
+\package{caption} package so simply loading it (without any package options)
+will not make any harm to the look at feel of the captions.
+This gives end-users the opportunity to fine-tune certain aspects of the
+appearance of captions by adding package options, without unwanted
+side-effects on other aspects of the appearance.
+
+In both cases the command |\Set|\-|Caption|\-|Default|
+could be used to adapt the \package{caption} package default values:
+
+\DescribeMacro{\SetCaptionDefault}
+The command
+\begin{quote}|\SetCaptionDefault*|\marg{option}\marg{default value}\end{quote}
+changes the default value for the option \meta{option}, for example:
+\begin{quote}
+|\SetCaptionDefault{format}{hang}|\\
+|\SetCaptionDefault{justification}{raggedright}|\\
+|\DeclareCaptionLabelSeparator{silly}{ +++ }|\\
+|\SetCaptionDefault{labelseparator}{silly}|
+\end{quote}
+This command is available for the options
+|box|,
+|font|,
+|format|,
+|justification|,
+|label|\-|font|,
+|label|\-|format|,
+|label|\-|separator|,
+|list|\-|format|,
+|margin|,
+|parbox|,
+|position|,
+|single|\-|line|\-|check|,
+|text|\-|font|,
+|text|\-|format|, and
+|width|.
+
+The starred variant only makes a difference when setting the default length
+of either |margin| or |width|, in this case it will use |\def| internally
+instead of |\edef| to store the value so the actual margin will be calculated
+when used (and not when set).
+
+\DescribeMacro{\AtCaptionPackage}
+The adaption file will be loaded when the \package{caption} kernel |caption3.sty|
+will be loaded so the given adaptions will be done for the \package{floatrow}
+and \package{subfig} packages even if the \package{caption} package isn't loaded.
+
+But some adaptions have to be done for the \package{caption} package,
+and for this reason the hook
+\begin{quote}|\At|\-|Caption|\-|Package|\marg{code}\end{quote}
+is offered to authors of adaption files.
+The \meta{code} inside the hook will be executed right before the given package
+options will be evaluated.
+
+For example the adaption file for the \KOMAScript\ document classes
+uses |\At|\-|Begin|\-|Caption| to re-define the \package{caption} package
+options |figure|\-|position| and |table|\-|position| to issue a warning
+that using these options has little effect here.
+
+% --------------------------------------------------------------------------- %
+
+\clearpage
+\section{Commands for babel language package authors}
+
+\NEWfeature{v3.5}
+\DescribeMacro{\caption@switchdefault}
+If the \package{caption3} kernel package is loaded, the command
+\begin{quote}|\caption@switchdefault|\marg{option}\marg{code with \#1}\marg{new value}\end{quote}
+is available which saves the old default value of the given option using
+\meta{code} and sets the new default value afterwards.
+
+\DescribeMacro{\caption@restoredefault}
+The command
+\begin{quote}|\caption@restoredefault|\marg{option}\marg{old value}\end{quote}
+restores the old default value which was stored in \meta{old value} before.
+
+Example:
+\begin{quote}
+ |\DeclareCaptionLabelSeparator{french}{|\ldots|}|\\
+ |\addto\extrasfrench{%|\\
+ | \caption@switchdefault{labelseparator}{\babel@save #1}{french}}|\\
+ |% Note: \caption@restoredefault isn't needed here|
+\end{quote}
+
+Another example:
+\begin{quote}
+ |\caption@switchdefault{font}{\let\original@captionfont#1}{it}%|\\
+ \ldots\\
+ |\caption@restoredefault{font}{\original@captionfont}%|\\
+\end{quote}
+
+Since boths commands are defined with |\def| inside the \package{caption3}
+kernel, they could be pre-defined with
+\begin{quote}
+ |\providecommand\caption@switchdefault[3]{}|\\
+ |\providecommand\caption@restoredefault[2]{}|
+\end{quote}
+inside the babel language package so their existence doesn't need to be tested
+prior use.
+
+Additionally babel language packages should not re-define |\@make|\-|caption|
+if the \package{caption} package is loaded, i.e.~if |\caption@makecaption| is
+defined. (Unfortunately one cannot use the \LaTeX{} kernel command
+|\@if|\-|package|\-|loaded{caption}| here since it's only available in the
+document preamble.)
+
+Please note that code like
+\begin{quote}
+ |\addto\extraswhatever{%|\\
+ | \@ifundefined{caption@makecaption}{%|\\
+ | \babel@save\@makecaption|\\
+ | \let\@makecaption\my@makecaption|\\
+ | }{%|\\
+ | \caption@switchdefault{|\ldots|}{\babel@save #1}{|\ldots|}%|\\
+ | }}|
+\end{quote}
+would be wrong since it mixes up the presence of the \package{caption3} kernel
+and the \package{caption} package.
+If the \package{caption3} kernel is loaded this does not mean that the
+\package{caption} package is loaded, too, and the latter one re-defines
+|\caption|, |\@caption|, and |\@make|\-|caption| while the \package{caption3}
+kernel does not re-define any of them, instead it only provides (default) values
+for the \package{caption}, \package{floatrow}, and \package{subfig} package.
+
+Currently there is build-in support for the following babel language options:
+|arabic|, |farsi|, |french|, |hungarian|, |latvian|, and |magyar|.
+This support could be deactivated by defining
+\begin{quote}
+ |\def\caption@ifbabel@|\meta{package}|{false}|
+\end{quote}
+where \meta{package} is either |arabi|, |french|, |frenchle|, |hungarian|,
+or |latvian|.
+
+% --------------------------------------------------------------------------- %
+
+\clearpage
\begin{thebibliography}{99}
\bibitem{TLC2}
@@ -4230,3 +4429,4 @@ to the \package{subfig} package instead and do not load \thispackage\ anymore.
% --------------------------------------------------------------------------- %
\end{document}
+