diff options
author | Norbert Preining <norbert@preining.info> | 2020-08-31 03:02:58 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2020-08-31 03:02:58 +0000 |
commit | 568fe838cef40f671837d9348dd73c93d9ea962b (patch) | |
tree | ba2b2c6ab585927a89adae8c1cc2a594010ab933 /macros/latex/contrib/caption/caption-eng.tex | |
parent | c6a1b1f6422e10f363a9de80c4f103f0c155d8bb (diff) |
CTAN sync 202008310302
Diffstat (limited to 'macros/latex/contrib/caption/caption-eng.tex')
-rw-r--r-- | macros/latex/contrib/caption/caption-eng.tex | 304 |
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} + |