diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/caption/caption-eng.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/caption/caption-eng.tex | 4458 |
1 files changed, 0 insertions, 4458 deletions
diff --git a/Master/texmf-dist/source/latex/caption/caption-eng.tex b/Master/texmf-dist/source/latex/caption/caption-eng.tex deleted file mode 100644 index 21a61546bef..00000000000 --- a/Master/texmf-dist/source/latex/caption/caption-eng.tex +++ /dev/null @@ -1,4458 +0,0 @@ -% -% This is file `caption-eng.tex'. -% -% Copyright (C) 1994-2020 Axel Sommerfeldt (axel.sommerfeldt@f-m.fm) -% -% -------------------------------------------------------------------------- -% -% This work may be distributed and/or modified under the -% conditions of the LaTeX Project Public License, either version 1.3 -% of this license or (at your option) any later version. -% The latest version of this license is in -% http://www.latex-project.org/lppl.txt -% and version 1.3 or later is part of all distributions of LaTeX -% version 2003/12/01 or later. -% -% This work has the LPPL maintenance status "maintained". -% -% This Current Maintainer of this work is Axel Sommerfeldt. -% -% 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}[2020/09/21 v3.5 The caption package] -\hbadness=9999 \newcount\hbadness \hfuzz=20pt % Make TeX shut up. -%\errorcontextlines=3 - -\documentclass[USenglish]{ltxdoc} -\setlength\parindent{0pt} -\setlength\parskip{\smallskipamount} -\setlength\leftmargini{2em}% default = 2.5em -\makeatletter\g@addto@macro\MacroFont{\normalcolor}\makeatother - -\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{graphicx,longtable,setspace} - -\usepackage{hypdoc} -\ifpdf\usepackage{hypdestopt}\fi -\hypersetup{pdfkeywords={LaTeX, package, caption},pdfstartpage={},pdfstartview={}} -\hypersetup{breaklinks=true} - -\usepackage[listof=0,hypcap=false]{caption}[2008/04/01] - -\DeclareRobustCommand*\eTeX{\texorpdfstring - {\leavevmode\hbox{$\varepsilon$}-\TeX}% - {e-TeX}} -\DeclareRobustCommand*\AmS{\texorpdfstring - {{\protect\usefont{OMS}{cmsy}{m}{n}A\kern-.1667em\lower.5ex\hbox{M}\kern-.125emS}}% - {AMS}} -\DeclareRobustCommand*\KOMAScript{\texorpdfstring - {\textsf{K\kern.05em O\kern.05em M\kern.05em A\kern.1em-\kern.1em Script}}% - {KOMA-Script}} -\DeclareRobustCommand*\NTG{NTG} -\DeclareRobustCommand*\SmF{SMF} - -\usepackage{marvosym} -\makeatletter -\newcommand*\INFO{\@ifstar{\@INFO{}}{\@INFO{\vbox to \ht\strutbox}}} -\newcommand*\@INFO[1]{\MARGINSYM{#1{\LARGE\Info}}} -\makeatother - -\newcommand*\MARGINSYM[1]{\hskip 1sp \marginpar{\raggedleft\textcolor{blue}{{#1}}}} -\newcommand*\NEW[2]{}%\hskip 1sp \marginpar{\footnotesize\sffamily\raggedleft#1\\#2}} - -% \ContinuedFloat -\DeclareCaptionLabelFormat{continued1}{Continued #1~#2} -\DeclareCaptionLabelFormat{continued2}{#1~#2\alph{ContinuedFloat}} -% \DeclareCaptionLabelFormat -\DeclareCaptionLabelFormat{bf-parens}{(\textbf{#2})} -% \DeclareCaptionStyle -\DeclareCaptionStyle{mystyle}[margin=5mm,justification=centering]% - {font=footnotesize,labelfont=sc,margin={10mm,0mm}} -% Example 1 -\DeclareCaptionFormat{myformat1}{#1#2\\#3} -\newlength\myindention -\DeclareCaptionFormat{myformat2}{#1#2\\\hspace*\myindention#3} -\DeclareCaptionOption{myindention}{\setlength\myindention{#1}} -% Example 2 -\DeclareCaptionFormat{reverse}{#3#2#1} -\DeclareCaptionLabelFormat{fullparens}{(\bothIfFirst{#1}{~}#2)} -\DeclareCaptionLabelSeparator{fill}{\hfill} -% Example 3 -\DeclareCaptionFormat{llap}{\llap{#1#2}#3\par} -\DeclareCaptionFormat{llapx}{\llap{\makebox[5em][l]{#1}}#3\par} -% Example 4 -\DeclareCaptionLabelFormat{andtable}{#1~#2 \& \tablename~\thetable} - -\newcommand*\purerm[1]{{\upshape\mdseries\rmfamily #1}} -\newcommand*\puresf[1]{{\upshape\mdseries\sffamily #1}} -\newcommand*\purett[1]{{\upshape\mdseries\ttfamily #1}} -\let\class\puresf \let\package\puresf - -\newcommand*\csmarg[1]{\texttt{\char`\{#1\char`\}}} -\newcommand*\csoarg[1]{\texttt{\char`\[#1\char`\]}} -\newcommand*\version[2][]{v$#2$} -\newcommand*\x{\discretionary{}{}{}} - -\newenvironment{Annotation}% - {\ifvmode\else\unskip\par\fi\pagebreak[2]% - \smallskip - \small(\ignorespaces}{\unskip)\par} -\newenvironment{Annotation*}% - {\ifvmode\else\unskip\par\fi\pagebreak[2]% - \small(\ignorespaces}{\unskip)\par} - -\newenvironment{Example}% - {\ifvmode\else\unskip\par\fi\pagebreak[2]% - \minipage{\linewidth}\smallskip}% - {\smallskip\endminipage\par} - -\makeatletter -\newcommand\example{\@ifstar - {\@example{belowskip=\abovecaptionskip}}% - {\@example{}}} -\def\@example#1{% - \@testopt{\@@example{#1}}{figure}} -\long\def\@@example#1[#2]#3#4{% - \begingroup - \captionsetup{#1,size=small,margin={\leftmargini,10pt},#3}% - \captionof{#2}[]{#4}% - \endgroup} -\makeatother - -\newenvironment{Expert}% - {\ifvmode\else\unskip\par\fi\pagebreak[3]% - \smallskip - \footnotesize\ignorespaces}{\par} -\newenvironment{Expert*}% - {\ifvmode\else\unskip\par\fi\pagebreak[3]% - \footnotesize\ignorespaces}{\par} - -\newenvironment{Note}[1][\DefaultNoteText]% - {\ifvmode\else\unskip\par\fi - \smallskip - \small\emph{#1:}~\ignorespaces}{\par} -\newenvironment{Note*}[1][\DefaultNoteText]% - {\ifvmode\else\unskip\par\fi - \small\emph{#1:}~\ignorespaces}{\par} - -\newenvironment{Options}[1]% - {\list{}{\renewcommand\makelabel[1]{\texttt{##1}\hfil}% - \settowidth\labelwidth{\texttt{#1\space}}% - \setlength\leftmargin{10pt}% - \addtolength\leftmargin{\labelwidth}% - \addtolength\leftmargin{\labelsep}}}% - {\endlist} - -\makeatletter -\def\Ref{\@ifstar{\@Ref\ref}{\@Ref\autoref}} -\def\@Ref#1#2{#1{#2}: \textit{\nameref{#2}}} -\newcommand*\SEE[3][]{\nopagebreak{#1(#2 #3)}} -\newcommand*\SeeUserDefined[1][]{\See{\Ref{declare}#1}} -\makeatother - -\begin{document} -\let\subsectionautorefname\sectionautorefname -\let\subsubsectionautorefname\sectionautorefname - -\def\thispackage{the \package{caption} package} -\def\Thispackage{The \package{caption} package} - -\newcommand*\DefaultNoteText{Note} -\newcommand*\NEWfeature{\NEW{New feature}} -\newcommand*\NEWdescription{\NEW{New description}} -\makeatletter -\newcommand*\See{\@ifstar{\SEE{See}}{\SEE[\small]{See}}} -\newcommand*\see{\@ifstar{\SEE{see}}{\SEE[\small]{see}}} -\makeatother - -% --------------------------------------------------------------------------- % - -\GetFileInfo{caption-eng.tex} -\let\docdate\filedate -\let\docversion\fileversion -\GetFileInfo{caption.sty} - -\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} -\maketitle - -% --------------------------------------------------------------------------- % - -\begin{abstract} -\Thispackage\ offers customization of captions -in floating environments such |figure| and |table| and cooperates with -many other packages. -\par\smallskip -\textit{Please note:} Many document classes already have build-in options and -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 only interested in using the command \cs{captionof}, loading of -the very small \package{capt-of} package is usually sufficient. -\end{abstract} - -\newcommand\exampletext{% - White sand beaches. The pink smoothness of the conch shell. A sea abundant - with possibilities. Duty-free shops filled with Europe's finest gifts and - perfumes. Play your favorite game of golf amidst the tropical greens on one - of the many championship courses.} - -% --------------------------------------------------------------------------- % - -\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 update 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 -attention they deserve. Simply typeset as an ordinary paragraph there is no -remarkable visual difference from the rest of the text, like here: - -\example*{size=normalsize,margin=0pt}{\exampletext} - -There should be possibilities to change this; for example, it would be nice -to make the text of the caption a little bit smaller as the normal -text, add an extra margin, typeset the caption label with the same font -family and shape as your headings etc. Just like this one: - -\example*{size=small,margin=10pt,labelfont=bf,labelsep=endash}{\exampletext} - -You can do this easily with this package as there are many ready-to-use -caption formatting options, but you are free to define your very own stuff, too. - -\bigskip - -\INFO\begin{minipage}[t]{\textwidth} -\small -Please note that \thispackage\ is only controlling the look \& feel of the -captions. It does \emph{not} control the placement of the captions. -(But you could do so by using other packages like the \package{floatrow} - package\cite{floatrow}.) -\end{minipage} - -% --------------------------------------------------------------------------- % - -\clearpage -\tableofcontents - -% --------------------------------------------------------------------------- % - -\clearpage -\section{Using this package} -\label{usage} - -\DescribeMacro{\usepackage} -Insert -\begin{quote} - |\usepackage|\oarg{options}|{caption}[|\texttt{\filedate}|]| -\end{quote} -into the preamble of your document, i.e.~the part of your document -between |\document|\-|class| and |\begin{doc|\-|u|\-|ment}|. -The options control how your captions will look like; e.g., -\begin{quote} - |\usepackage[margin=10pt,font=small,labelfont=bf,|\\ - | labelsep=endash]{caption}|% - %|[|\texttt{\filedate}|]| -\end{quote} -would result in captions looking like the second one in the introduction. - -\DescribeMacro{\captionsetup} -For a later change of options \thispackage\ provides the command -\begin{quote} - |\captionsetup|\oarg{float type}\marg{options}\quad. -\end{quote} -So -\begin{quote} - |\usepackage[margin=10pt,font=small,labelfont=bf]{caption}| -\end{quote} -and -\begin{quote} - |\usepackage{caption}|\\ - |\captionsetup{margin=10pt,font=small,labelfont=bf}| -\end{quote} -are equal in their results. - -It's good to know that |\caption|\-|setup| has an effect on the current -environment only. So if you want to change settings for the -current |figure| or |table| only, just place the |\caption|\-|setup| command -inside the |figure| or |table| right before the |\caption| command. -For example -\begin{quote} - |\begin{figure}|\\ - | |\ldots\\ - | \captionsetup{singlelinecheck=off}|\\ - | \caption{|\ldots|}|\\ - |\end{figure}| -\end{quote} -switches the single-line-check off, but only for this |figure|, -so all the other captions remain untouched. - -\begin{Annotation} -For a detailed description of |\caption|\-|setup| see \Ref{captionsetup}. -\end{Annotation} - -% --------------------------------------------------------------------------- % - -\clearpage -\section{Options} -\label{options} - -\def\OptionLabel{RaggedRight} -\def\UserDefined{\ldots} - -% --------------------------------------------------------------------------- % - -\subsection{Formatting} -\label{formats} - -\DescribeMacro{format=} -A figure or table caption mainly consists of three parts: the caption label, -which says if this object is a `Figure' or `Table' and what number is -associated with it, the caption text itself, which is normally a short -description of contents, and the caption separator which separates the text -from the label. - -The \textit{caption format} determines how this information will be presented; -it is specified with the option -\begin{quote} - |format=|\meta{format name}\quad, -\end{quote} -having the name of the caption format as its argument. - -There are two standard caption formats: -%\footnote{You have the option to -%define your own ones, too. See section \ref{declare}: -%\textit{``Do it yourself!''} for details.} - -\begin{Options}{\OptionLabel} - \item[plain]%\NEWdescription{v3.0h} - Typesets the captions as a normal paragraph. - - \item[hang] - Indents the caption text, so it will `hang' under the first line of the text. - - \item[\UserDefined] - Own formats can be defined using |\Declare|\-|Caption|\-|Format|.\LineBreak - \SeeUserDefined -\end{Options} - -\begin{Example} - An example: Specifying the option - \begin{quote} - |format=hang| - \end{quote} - yields captions like this: - \example{format=hang}{\exampletext} -\end{Example} - -\pagebreak[3] -\DescribeMacro{indention=} -For both formats (\texttt{plain} and \texttt{hang}) you can setup an extra -indention starting at the second line of the caption. You do this with the -option -\begin{quote} - |indention=|\meta{amount}\quad. -\end{quote} - -Two examples: - -\begin{Example} - \begin{quote} - |format=plain,indention=.5cm| - \end{quote} - \captionsetup{skip=0pt} - \example{format=plain,indention=.5cm}{\exampletext} -\end{Example} - -\begin{Example} - \begin{quote} - |format=hang,indention=-0.5cm| - \end{quote} - \captionsetup{skip=0pt} - \example{format=hang,indention=-0.5cm}{\exampletext} -\end{Example} - -\bigskip - -\pagebreak[3] -\DescribeMacro{labelformat=} -With the option -\nopagebreak[3] -\begin{quote} - |labelformat=|\meta{label format name} -\end{quote} -\nopagebreak[3] -%\NEWdescription{v3.0e} -you specify how the caption label will be typeset. -There are five standard caption label formats: - -\begin{Options}{\OptionLabel} - \item[original] - The caption label will be typeset as specified by the document class, - usually this means the name and the number (like \texttt{simple}). - - Until \version{3.4} of \thispackage\ this label format was called `default'. - Since \version{3.5} it is called `original' and usually is the default label - format, so |label|\-|format=|\-|default| will still select this label format, - unless the default was changed by either a document class or babel language package. - - \item[empty] - The caption label will be empty. -\iffalse - (This option makes sense when used together with other options like - \texttt{labelsep=none}.) -\fi - - \item[simple] - The caption label will be typeset as a name and a number. - - \item[brace]\NEWfeature{v3.1f} - The caption label will be closed with a single (right) brace. - - \item[parens] - The number of the caption label will be typeset in parentheses. - - \item[\UserDefined] - Own label formats can be defined using |\Declare|\-|Caption|\-|Label|\-|Format|. - \SeeUserDefined -\end{Options} - -\begin{Example} - An example: Using the options - \begin{quote} - |format=plain,labelformat=parens,labelsep=quad| - \end{quote} - gives captions like this one: - \example{format=plain,labelformat=parens,labelsep=quad}{\exampletext} -\end{Example} - -\medskip - -\begin{Note*} -Some environments, e.g.~the |algorithm| environment offered by the -\package{algorithm2e} package, might react allergic to a change of the -caption label format. -\end{Note*} - -\bigskip - -\pagebreak[3] -\DescribeMacro{labelsep=} -With the option -\begin{quote} - |labelsep=|\meta{label separator name} -\end{quote} -you specify what caption separator will be used.\footnote{% - If the caption label or the caption text is empty, - no separator will be used.} -You can choose one of the following: - -\begin{Options}{\OptionLabel} - \item[none] - There is no caption separator. -\iffalse - (This option makes sense when used together with other options like - \texttt{labelformat=empty}.) -\fi - - \item[colon] - The caption label and text will be separated by a colon and a space. - - \item[period] - The caption label and text will be separated by a period and a space. - - \item[space] - The caption label and text will be separated by a single space. - - \item[quad] - The caption label and text will be separated by a |\quad|. - - \item[newline] - The caption label and text will be separated by a line break (|\\|). - Please note that this separator does not work with all caption - formats (e.g.~|format=|\x|hang|), and you'll get an error message - trying such combination of options. - - \item[endash]\NEWfeature{v3.0h} - The caption label and text will be separated by an en-dash, - surrounded by spaces (\verb*| -- |). - -%\showhyphens{separator} - \item[\UserDefined] - Own separators can be defined using |\Declare|\-|Caption|\-|Label|\-|Sep|\-|a|\-|ra|\-|tor|. - \SeeUserDefined -\end{Options} - -Three examples: -\begin{Example} - \begin{quote} - |format=plain,labelsep=period| - \end{quote} - \captionsetup{skip=0pt} - \example{format=plain,labelsep=period}{\exampletext} -\end{Example} - -\begin{Example} - \begin{quote} - |format=plain,labelsep=newline,singlelinecheck=false| - \end{quote} - \captionsetup{skip=0pt} - \example{format=plain,labelsep=newline,singlelinecheck=false}{\exampletext} -\end{Example} - -\begin{Example} - \begin{quote} - |format=plain,labelsep=endash| - \end{quote} - \captionsetup{skip=0pt} - \example{format=plain,labelsep=endash}{\exampletext} -\end{Example} - -\bigskip - -\pagebreak[3] -\DescribeMacro{textformat=}\NEWfeature{v3.0l} -With the option -\nopagebreak[3] -\begin{quote} - |textformat=|\meta{text format name} -\end{quote} -\nopagebreak[3] -you specify how the caption text will be typeset. -There are two standard caption text formats: - -\begin{Options}{\OptionLabel} - \item[empty] - The caption text will be suppressed. - - \item[simple] - The caption text will be typeset as it is. - - \item[period] - The caption text will be followed by a period. - - \item[\UserDefined] - Own text formats can be defined using |\Declare|\-|Caption|\-|Text|\-|Format|. - \SeeUserDefined -\end{Options} - -% --------------------------------------------------------------------------- % - -\PageBreak -\subsection{Justification} -\label{justification} - -\DescribeMacro{justification=} -As addition to the caption format you could also specify a -\emph{caption justification}; it is specified with the option -\begin{quote} - |justification=|\meta{justification name}\quad. -\end{quote} - -You can choose one of the following: - -\begin{Options}{\OptionLabel} - \item[justified] - Typesets the caption as a normal paragraph. - - \item[centering] - Each line of the caption will be centered. - -% \item[Centering] - - \item[centerlast] - The last line of each paragraph of the caption text will be centered. - - \item[centerfirst] - Only the first line of the caption will be centered. - - \item[raggedright] - Each line of the caption will be moved to the left margin. - -\iffalse - \item[RaggedRight] - Each line of the caption will be moved to the left margin using - the command |\RaggedRight| from the \package{ragged2e} package. -\else - \item[RaggedRight] - Each line of the caption will be moved to the left margin, too. - But this time the command |\RaggedRight| of the \package{ragged2e} - package will be used to achieve this. - The main difference to |raggedright| is that the word breaking - algorithm of \TeX\ will work inside captions.\footnote{% - The need for the \package{ragged2e} package will be detected at - run-time, therefore you maybe need a second \LaTeX\ run if this - option is used for the first time.} -\fi - - \item[raggedleft] - Each line of the caption will be moved to the right margin. - -% \item[RaggedLeft] -% Each line of the caption will be moved to the right margin using -% the command |\RaggedLeft| from the \package{ragged2e} package. - -%\showhyphens{justification} - \item[\UserDefined] - Own justifications can be defined using |\Declare|\-|Caption|\-|Jus|\-|ti|\-|fi|\-|ca|\-|tion|. - \SeeUserDefined -\end{Options} - -Three examples: -\begin{Example} - \begin{quote} - |format=hang,justification=raggedright| - \end{quote} - \captionsetup{skip=0pt} - \example{format=hang,justification=raggedright}{\exampletext} -\end{Example} - -\begin{Example} - \begin{quote} - |format=hang,justification=centerlast| - \end{quote} - \captionsetup{skip=0pt} - \example{format=hang,justification=centerlast}{\exampletext} -\end{Example} - -\begin{Example} - \begin{quote} - |format=plain,labelsep=newline,justification=centering| - \end{quote} - \captionsetup{skip=0pt} - \example*{format=plain,labelsep=newline,justification=centering}{\exampletext} -\end{Example} - -\smallskip - -\PageBreak -\DescribeMacro{singlelinecheck=} -The standard \LaTeX\ document classes (\class{article}, \class{report}, and -\class{book}) automatically center a caption if it fits in one single line: - -\example*{}{A short caption.} - -\INFO -\Thispackage\ adapts this behavior and therefore usually ignores the -justification \& indention you have set with |justification=| \& -|indention=| in such case. -But you can switch this special treatment of such short captions off -with the option -\begin{quote} - |singlelinecheck=|\meta{bool}\quad. -\end{quote} -Using |false|, |no|, |off| or |0| for \meta{bool} switches the -extra centering off: -\begin{quote} - |singlelinecheck=false| -\end{quote} -Doing so the above short caption would look like - -\begingroup - \captionsetup{type=figure} - \ContinuedFloat - \example*{singlelinecheck=false}{A short caption.} -\endgroup - -You switch the extra centering on again by using |true|, |yes|, |on| or |1| -for \meta{bool}. (The default is on.) - -% --------------------------------------------------------------------------- % - -\subsection{Fonts} -\label{fonts} - -\DescribeMacro{font=} -\DescribeMacro{labelfont=} -\DescribeMacro{textfont=} -There are three font options which affects different parts of the caption: -One affecting the whole caption (|font|), one which only affects the caption -label and separator (|label|\-|font|) and at least one which only affects the -caption text (|text|\-|font|). -You set them up using the options -\begin{quote}\begin{tabular}{@{}r@{}ll} - |font=| & \marg{font options} & ,\\ - |labelfont=| & \marg{font options} & , and\\ - |textfont=| & \marg{font options} & ,\\ -\end{tabular}\end{quote} -where \meta{font options} is a list of comma separated font options. - -And these are the available font options: - -\begin{Options}{stretch=\meta{amount}} - \item[scriptsize] {\scriptsize Very small size} - \item[footnotesize] {\footnotesize The size usually used for footnotes} - \item[small] {\small Small size} - \item[normalsize] {\normalsize Normal size} - \item[large] {\large Large size} - \item[Large] {\Large Even larger size} -\end{Options} -\vspace{0pt}\pagebreak[3] -\begin{Options}{stretch=\meta{amount}} - \item[normalfont] {\normalfont Normal shape \& series \& family} - - \item[up] {\upshape Upright shape} - \item[it] {\itshape Italic shape} - \item[sl] {\slshape Slanted shape} - \item[sc] {\scshape Small Caps shape} - - \item[md] {\mdseries Medium series} - \item[bf] {\bfseries Bold series} - - \item[rm] {\rmfamily Roman family} - \item[sf] {\sffamily Sans Serif family} - \item[tt] {\ttfamily Typewriter family} -\end{Options} -\vspace{0pt}\pagebreak[3] -\begin{Options}{stretch=\meta{amount}} - \item[singlespacing] Single spacing \See{\Ref{setspace}} - \item[onehalfspacing] One-and-a-half spacing \See{\Ref{setspace}} - \item[doublespacing] Double spacing \See{\Ref{setspace}} - \item[stretch=\meta{amount}] |\setstretch|\marg{amount} \See{\Ref{setspace}} -\end{Options} -\vspace{0pt}\pagebreak[3] -\begin{Options}{stretch=\meta{amount}} - \item[normalcolor] |\normalcolor| - \item[color=\meta{colour}] |\color|\marg{colour} - {\small(If the \package{color} or \package{xcolor} package is loaded, - see \Ref{declare} for an example)} -\end{Options} -\vspace{0pt}\pagebreak[3] -\begin{Options}{stretch=\meta{amount}} - \item[normal] The combination of the options |normal|\-|color|, - |normal|\-|font|, |normal|\-|size|, and |single|\-|spacing| - - \item[\UserDefined] - Own font options can be defined using |\Declare|\-|Caption|\-|Font|. - \SeeUserDefined -\end{Options} - -If you use only one of these options you can omit the braces; -e.g., the options -%\begin{quote} - |font={small}| -%\end{quote} -and -%\begin{quote} - |font=small| -%\end{quote} -will give the same result. - -Three examples: -\begin{Example} - \begin{quote} - |font=it,labelfont=bf| - \end{quote} - \captionsetup{skip=0pt} - \example{font=it,labelfont=bf}{\exampletext} -\end{Example} - -\begin{Example} - \begin{quote} - |labelfont=sc,textfont=it| - \end{quote} - \captionsetup{skip=0pt} - \example{labelfont=sc,textfont=it}{\exampletext} -\end{Example} - -\begin{Example} - \begin{quote} - |font={small,stretch=0.80}| - \end{quote} - \captionsetup{skip=0pt} - \example{font={small,stretch=0.80}}{\exampletext} -\end{Example} - -\medskip - -\pagebreak[3] -\DescribeMacro{font+=} -\DescribeMacro{labelfont+=} -\DescribeMacro{textfont+=} -\NEWfeature{v3.1f} -You can also add font options to the current ones, so for example -\begin{quote} - |\captionsetup{font=small}|\\ - |\captionsetup{font+=it}| -\end{quote} -is identical to -\begin{quote} - |\captionsetup{font={small,it}}| -\end{quote} - -% --------------------------------------------------------------------------- % - -\subsection{Margins and further paragraph options} -\label{margins} - -\DescribeMacro{margin=} -\DescribeMacro{width=} -For all captions you can specify \emph{either} an extra margin \emph{or} -a fixed width:~\footnote{Only fixed widths are supported here; if you are -looking for a way to limit the width of the caption to the width of the -figure or table, please take a look at the \package{floatrow}\cite{floatrow} -or \package{threeparttable}\cite{threeparttable} package.} -\begin{quote}\begin{tabular}{@{}r@{}ll} - |margin=| & \meta{amount} & \emph{--or--}\\ - |margin=| & |{|\meta{left amount}|,|\meta{right amount}|}| & \emph{--or--}\\ - |width=| & \meta{amount} & \\ -\end{tabular}\end{quote} -\NEWfeature{v3.1} -If you specify just one \meta{amount} for the margin, it will be used for -both, the left and right margin, e.g.~|margin=|\x|10pt| is equivalent to -|margin=|\x|{10pt,10pt}|. -In two-side documents the left and right margin will be swapped on even pages. -\DescribeMacro{oneside} -\DescribeMacro{twoside} -To prevent this you can specify the option |oneside| additionally, -e.g.~|\caption|\-|setup{margin=|\x|{0pt,10pt},|\x|oneside}|.\par -But if you are specifying a width, then both, the left and the right margin, -will have the same amount. - -Three examples will illustrating this: -\begin{Example} - \begin{quote} - |margin=10pt| - \end{quote} - \captionsetup{skip=0pt} - \example{margin=10pt}{\exampletext} -\end{Example} - -\begin{Example} - \begin{quote} - |margin={1cm,0cm}| - \end{quote} - \captionsetup{skip=0pt} - \example{margin={1cm,0cm}}{\exampletext} -\end{Example} - -\begin{Example} - \begin{quote} - |width=.75\textwidth| - \end{quote} - \captionsetup{skip=0pt} - \example{width=.75\textwidth}{\exampletext} -\end{Example} - -\begin{Note} -When the caption is placed beside the contents (for example in a |SC|\-|figure| -environment offered by the \package{sidecap} package\cite{sidecap}) or the -figure is an in-text figure (for example in a |wrap|\-|figure| environment -offered by the \package{wrapfig} package\cite{wrapfig}), the margin setting -will be automatically reset to |0pt| at the very beginning of the environment. -But if you really want to setup an extra margin for these environments, you can -do so by setting this margin either inside the environment itself, of by -specifying a margin for this particular environment, -e.g.~|\caption|\-|setup[SC|\-|figure]{margin=|\x|10pt}|. -\end{Note} - -\begin{Expert} -\DescribeMacro{margin*=}\NEWfeature{v3.1} -There is also a starred variant of the |margin=| option, |margin*=|, which only -changes the margin if no width was set. -\end{Expert} - -\begin{Expert} -\DescribeMacro{minmargin=} -\DescribeMacro{maxmargin=}\NEWfeature{v3.1} -You can also set a minimum or maximum margin amount. This can be useful for -limiting the margin amount in smaller environments, e.g.~|minipage|s. -For example the \SmF\ document classes limit the margin amount to -|maxmargin=|\x|0.1\linewidth|. (See \Ref{SMF}) -\end{Expert} - -\medskip - -\pagebreak[3] -\DescribeMacro{parskip=} -This option is useful for captions containing more than one paragraph. -It specifies the extra vertical space inserted between them: -\begin{quote} - |parskip=|\meta{amount} -\end{quote} -One example: -\begin{Example} - \begin{quote} - |margin=10pt,parskip=5pt| - \end{quote} - \captionsetup{skip=0pt} - \example{margin=10pt,parskip=5pt}{% - First paragraph of the caption. This one contains some test, just to - show how these options affect the layout of the caption.\par - Second paragraph of the caption. This one contains some text, too, to - show how these options affect the layout of the caption.} -\end{Example} - -\pagebreak[3] -\DescribeMacro{hangindent=} -The option -\begin{quote} - |hangindent=|\meta{amount} -\end{quote} -is for setting up a hanging indention starting from the second line of each -paragraph. If the caption contains just a single paragraph, using this option -leads to the same result as the option |indention=|\meta{amount} you already -know about. -But if the caption contains multiple paragraphs you will notice the difference: - -\begin{Example} - \begin{quote} - |format=hang,indention=-.5cm| - \end{quote} - \captionsetup{skip=0pt} - \example{format=hang,indention=-.5cm}{% - First paragraph of the caption. This one contains some test, just to - show how these options affect the layout of the caption.\par - Second paragraph of the caption. This one contains some text, too, to - show how these options affect the layout of the caption.} -\end{Example} - -\begin{Example} - \begin{quote} - |format=hang,hangindent=-.5cm| - \end{quote} - \captionsetup{skip=0pt} - \example{format=hang,hangindent=-.5cm}{% - First paragraph of the caption. This one contains some test, just to - show how these options affect the layout of the caption.\par - Second paragraph of the caption. This one contains some text, too, to - show how these options affect the layout of the caption.} -\end{Example} - -\begin{Note} -If your caption contains more than one paragraph, you have -to specify an alternative caption for the list-of-figures using the -optional argument of |\caption| or |\caption|\-|of|, otherwise you will -get an error message. -\end{Note} - -% --------------------------------------------------------------------------- % - -\PageBreak -\subsection{Styles} -\label{style} - -\DescribeMacro{style=} -A suitable combination of caption options is called \emph{caption style}. -You can compare them more or less to page styles which you set up with -|\page|\-|style|; -the caption style provides all settings for a whole caption layout. - -You switch to an already defined caption style with the option -\begin{quote} - |style=|\meta{style name}\quad. -\end{quote} -\Thispackage\ pre-defines two styles: |base| and |default|. - -\NEWfeature{v3.1} -The |base| style puts all options you already know about to values reflecting -the look of the captions when using one of the base \LaTeX\ document classes -\class{article}, \class{report}, and \class{book}. -This means that specifying the option -\begin{quote} - |style=base| -\end{quote} -has the same effect as specifying all these options: -\begin{quote} - |format=plain,labelformat=default,labelsep=colon,|\\ - |justification=justified,font={},labelfont={},|\\ - |textfont={},margin=0pt,indention=0pt|\\ - |parindent=0pt,hangindent=0pt,singlelinecheck=true| -\end{quote} -\begin{Annotation*} -But |justification=centering,indention=0pt| will be set if -the caption fits into a single line. -\end{Annotation*} - -In contrast the |default| style follows the default values, reflecting -the look of the captions given by the document class you actually use. -This style is selected by default and represents these options: -\begin{quote} - |format=default,labelformat=default,labelsep=default,|\\ - |justification=default,font=default,labelfont=default,|\\ - |textfont=default,margin=0pt,indention=0pt|\\ - |parindent=0pt,hangindent=0pt,singlelinecheck=true| -\end{quote} -\begin{Annotation*} -But again |justification=centering,indention=0pt| will be set if -the caption fits into a single line. -\end{Annotation*} - -So if you use one of the base \LaTeX\ document classes \class{article}, -\class{report}, or \class{book}, both caption styles, |base| and |default|, -point to (nearly) the same settings. - -\begin{Note} -Own caption styles can be defined using |\Declare|\-|Caption|\-|Style|.\LineBreak -\SeeUserDefined -\end{Note} - -% --------------------------------------------------------------------------- % - -\subsection{Skips} -\label{skips} - -\DescribeMacro{skip=}\NEWfeature{v3.0d} -The vertical space between the caption and the figure or table contents is -controlled by the option -\begin{quote} - |skip=|\meta{amount}\quad. -\end{quote} -The standard \LaTeX\ document classes \class{article}, \class{report} and -\class{book} preset it to |skip=|\x|10pt|, but other document classes may -use a different amount. - -\bigskip - -\pagebreak[3] -\DescribeMacro{position=} -The |\caption| command offered by \LaTeX{} has a design flaw: -The command does not know if it stands on the beginning of the figure or -table, or at the end. Therefore it does not know where to put the space -separating the caption from the content of the figure or table. -While the standard implementation always puts the space above the caption -in floating environments (and inconsistently below the caption in -|long|\-|table|s), the implementation offered by this package is more -flexible: -By giving the option -\begin{quote} - |position=top|\quad or\quad |position=above| -\end{quote} -it's assumed that the caption is standing at the \emph{top} of the -environment and therefore the space setup with |skip=|\x\meta{amount} -is placed below the caption. -(Please note that |position=|\x|top| does \emph{NOT} mean that the -caption is actually placed at the top of the figure or table. -Instead the caption is usually placed where you place the |\caption| -command.) -But with -\begin{quote} - |position=bottom|\quad or\quad |position=below| -\end{quote} -it's assumed that the caption is standing at the \emph{bottom} of the -environment and therefore the space is placed above the caption. -And finally with -\begin{quote} - |position=auto|\quad {\small(which is the default setting)} -\end{quote} -\thispackage\ tries its best to determine the actual position of -the caption on its own. Please note that while this is successfully in -most cases, it could give wrong results under rare circumstances. - -\medskip - -\pagebreak[3] -\DescribeMacro{figureposition=}%\NEWfeature{v3.0a} -\DescribeMacro{tableposition=}%\NEWfeature{v3.0a} -The |position| option is especially useful when used together with the -optional argument of the |\caption|\-|setup| command. -\See{also \Ref{captionsetup}}\par -For example -\begin{quote} - |\captionsetup[table]{position=above}| -\end{quote} -causes all captions within tables to be treated as captions \emph{above} -the table (regarding spacing around it). -Because this is a very common setting, \thispackage\ offers -the abbreviating options |figure|\-|position=|\x\meta{pos} and -|table|\-|position=|\x\meta{pos}, e.g. -\begin{quote} - |\usepackage[|\ldots|,tableposition=top]{caption}| -\end{quote} -is equivalent to -\begin{quote} - |\usepackage[|\ldots|]{caption}|\\ - |\captionsetup[table]{position=top}| -\end{quote} - -\medskip - -\INFO -Please note that the options |skip=|, |position=|, |figure|\-|position=|, -and |table|\-|position=| do not always have an effect. -Since it's a matter of the document class to supply the environments -|figure| and |table|, it could use its very own spacing, and could -decide for itself if the caption will be typeset as ``top'' or ``bottom'' -caption. -For example the \KOMAScript\ document classes support the |skip=| -setting, but will always typeset |figure| captions as ``bottom'' captions, -and |table| captions are dependent on the global option -|table|\-|captions|\-|above| resp.\ |table|\-|captions|\-|below|. -\See{\Ref{KOMA}} - -Furthermore some packages control the behavior of the spacing above and -below the caption for themself, e.g.~the \package{float}, the -\package{floatrow}, and the \package{supertabular} package. - -\bigskip - -\begin{Expert*} -Internally the skip between caption and contents is represented by -|\above|\-|caption|\-|skip| (which is always set above the caption in -\LaTeX{}s implementation). -But there is a second value |\below|\-|caption|\-|skip| (usually set to -|0pt| by default) which is set below the caption in \LaTeX{}s implementation, -but on the other side than |\above|\-|caption|\-|skip| by this package. -So technically speaking, this package swaps the meaning of these two skips -when |position=|\x|top| is set. -Please note that there are several packages around which do the same trick -(like the \package{ftcap}, the \package{nonfloat}, and the \package{topcap} -package), so the usage of the \package{caption} option |position=| is not -supported if one of these packages will be used, too. -\end{Expert*} - -% --------------------------------------------------------------------------- % - -\subsection{Lists} -\label{lists} - -\DescribeMacro{list=}\NEWfeature{v3.1} -The |\caption| command usually places an entry in the List of Figures -resp.~List of Tables. You can either suppress that individually by giving an -empty optional argument to |\caption| {\small(see \Ref{caption})}, or -programmatically by saying -\begin{quote} - |list=no|\quad(or any other boolean value instead of |no|)\quad.~\footnote{% - Please note that the \package{subfig} package\cite{subfig} is not supporting - this option, it uses the counters \texttt{lofdepth} \& \texttt{lotdepth} for - this purpose instead.} -\end{quote} - -\pagebreak[3] -\DescribeMacro{listformat=}\NEWfeature{v3.1} -With the option -\nopagebreak[3] -\begin{quote} - |listformat=|\meta{list format name} -\end{quote} -\nopagebreak[3] -you can specify how the |figure| or |table| number will be typeset within -the List of Figures resp.~List of Tables. -There are five standard caption list formats: - -\begin{Options}{\OptionLabel} - \item[empty] - No number will be typeset. - - \item[simple] - The number will be typeset with label prefix. - - \item[parens] - The number will be typeset in parentheses, with label prefix. - - \item[subsimple] - Same as |simple|, but without label prefix. (default) - - \item[subparens] - Same as |parens|, but without label prefix. - - \item[\UserDefined] - Own list formats can be defined using |\Declare|\-|Caption|\-|List|\-|Format|. - \SeeUserDefined -\end{Options} - -The prefix ($=$|\p@figure| resp.~|\p@table|), which runs ahead of the -number ($=$|\the|\-|figure| resp.~|\the|\-|table|) in lists (e.g.~List of -Figure/Table) and references, is usually empty, -so the list formats |simple| and |subsimple| gives equal results; -same with |parens| and |subparens|. -But this can be different for sub-figures or sub-tables listed in the List of -Figures resp.~List of Tables, or when the label prefix is redefined for a -different purpose.\footnote{% - Sub-figures and sub-tables can be typeset using the \package{subcaption} - or \package{subfig} package.} - -% --------------------------------------------------------------------------- % - -\subsection{Names} -\label{names} - -\DescribeMacro{name=}\NEWfeature{v3.1f} -The option -\begin{quote} - |name=|\meta{name} -\end{quote} -changes the name of the \emph{current} environment. -This could be useful in conjunction with the optional argument of -|\caption|\-|setup|, e.g. -\begin{quote} - |\captionsetup[wrapfigure]{name=Fig.}| -\end{quote} -changes the name to ``Fig.'' for all |wrap|\-|figure|s (while all the other -figure captions will still have ``Figure'' as name). - -% --------------------------------------------------------------------------- % - -\subsection{Types} -\label{types} - -\DescribeMacro{type=}\NEWfeature{v3.0d} -The |\caption| command can typeset captions for different types, -e.g.~|figure| and |table|. If you try to use the |\caption| command outside -these environments you will get an error message, because it does not know what -kind of caption do you want to have here. But in such situations you can set -the caption type manually with -\begin{quote} - |type=|\meta{float type} -\end{quote} -prior to the usage of the |\caption| command (and other commands like -|\Continued|\-|Float|, or |\sub|\-|caption|\-|box| offered by the -\package{subcaption} package, or |\sub|\-|float| offered by the -\package{subfig} package\cite{subfig}), -for example within an non-floating environment like |minipage|: -\begin{quote} - |\noindent\begin{minipage}{\textwidth}|\\ - | \captionsetup{type=figure}|\\ - | \subfloat{|\ldots|}|\\ - | |\ldots\\ - | \caption{|\ldots|}|\\ - |\end{minipage}| -\end{quote} - -\begin{Expert} -There is also a starred variant of this option, |type*=|\meta{float type}, -which behaves different than |type=|\meta{float type} if the -\package{hyperref} package\cite{hyperref} is loaded: While |type=| sets an -hyperlink anchor (if |hypcap=|\x|true| is set), |type*=| does not. -(See also \Ref{hyperref}\,) -\end{Expert} -\begin{Expert} -\emph{\DefaultNoteText:} Please don't re-define the internal macro |\@captype| -for yourself, like suggested by some documentations, always use -|\caption|\-|setup{type=|\x\ldots|}| instead. -\end{Expert} - -\medskip - -Own float types can be defined with - |\Declare|\-|Floating|\-|Environment| offered by the \package{newfloat} package, - |\new|\-|float| offered by the \package{float} package\cite{float}, or - |\Declare|\-|New|\-|Float|\-|Type| offered by the \package{floatrow} package\cite{float}. - -\medskip - -\INFO % \NEWdescription{v3.1} -Please note that you should use the option |type=| only -\emph{inside} boxes or environments (like |\par|\-|box| or |mini|\-|page|), -at best one where no page break could happen between contents and caption. -Furthermore some visual side-effects (e.g.~mixed-up figure and table settings -regarding captions) could occur without using a box or environment, -therefore a warning message will be issued if you try to do so.\footnote{% -You only get this warning message if you use \eTeX\ as underlying \TeX\ engine.} - -% --------------------------------------------------------------------------- % - -\clearpage -\section{Commands} - -\subsection{Typesetting captions} -\label{caption} -\label{captionlistentry} - -\DescribeMacro{\caption} -The command -\begin{quote} - |\caption|\oarg{list entry}\marg{heading} -\end{quote} -typesets the caption inside a floating environment like |figure| or |table|. -Well, you already know this, but \thispackage\ offers an extension: -If you leave the argument \meta{list entry} empty, no entry in the list of -figures or tables will be made. For example: -\begin{quote} - |\caption[]{A figure without list entry.}| -\end{quote} - -\begin{Expert} -Please remember that the \meta{heading} is a so-called \emph{moving} argument, -if no \meta{list entry} has been given. But if a \meta{list entry} is given, -this argument is moving instead. -``\emph{Moving} argument'' means that the argument will be written to the -list-of file, make it appearing in the ``List of Figures'' resp. -``List of Tables'', too. -\emph{Moving} arguments are not allowed to contain \emph{fragile} commands, -everything must be \emph{robust}, otherwise the argument could get -\emph{broken}, resulting in strange errors at the next \LaTeX\ run. -Some \emph{fragile} commands could be \emph{protected} by a leading |\protect|, -own definitions could get defined with |\Declare|\-|Robust|\-|Command| instead of -|\new|\-|command| to make them \emph{robust}. - -An example: |\caption{${}^{137}_{\phantom{1}55}$Cs}| will cause errors since -|\phantom| is \emph{fragile}. -So we have either have to use the optional argument \meta{list entry} -(e.g.~|\caption[${}^|\x|{137}_|\x|{55}$|\x|Cs]|\x|{${}^|\x|{137}_|\x|{\phantom{1}55}$|\x|Cs}|) -or add |\protect| to prevent the |\phantom| command from getting \emph{broken}: -|\caption{${}^|\x|{137}_|\x|{|\textcolor{blue}{\cs{protect}}|\phantom{1}55}$|\x|Cs}|. - -But sometimes even this is not sufficient. The reason behind is the so-called -single-line-check: It puts the \meta{heading} into a horizontal box to determine -the width of the caption, and this could cause error messages, too. -An example: -|\caption{A| |scheme.| |\[V_{C}| |\sim| |\left| |\{| |\begin{array}{cc}| -|E_{g}| |&| |\textrm{p-n}| |\\| |e\phi_{B}| |&| |\textrm{M-S}| |\end{array}| -|\right.| |\]}|. -Using |\caption[A| |scheme]{|\ldots|}| is not sufficient here, it's still -leading to errors. (``\texttt{Missing \$ inserted.}'') -So we have to put a |\caption|\-|setup{single|\-|line|\-|check=|\x|off}| -just in front of the |\caption| command additionally. - -For more information about \emph{moving} arguments and \emph{fragile} \& -\emph{robust} commands, take a closer look at your \LaTeX\ manual or visit -\url{http://www-h.eng.cam.ac.uk/help/tpl/textprocessing/teTeX/latex/latex2e-html/fragile.html}. -\end{Expert} - -\medskip - -\pagebreak[3] -\DescribeMacro{\caption*} -The \package{longtable} package defines the command |\caption*| which -typesets the caption without label and without entry in the list of tables. -An example: -\begin{quote} - |\begin{longtable}{|\ldots|}|\\ - | \caption*{A table}\\|\\ - | |\ldots\\ - |\end{longtable}| -\end{quote} -looks like -\DeleteShortVerb{\|} -\vskip\intextsep -\begin{minipage}{\linewidth} - \captionsetup{type=table,position=t} - \caption*{A table} - \centering - \begin{tabular}{r|rr} - & x & y \\\hline - a & 1 & 2 \\ - b & 3 & 4 \\ - \end{tabular} -\end{minipage} -\vskip\intextsep -\MakeShortVerb{\|} -\Thispackage\ offers this feature, too, so you can use this command now within -every floating environment like |figure| or |table|, like: -\begin{quote} - |\begin{table}|\\ - | \caption*{A table}|\\ -% | \begin{tabular}{|\ldots|}|\\ -% | |\ldots\\ -% | \end{tabular}|\\ - | |\ldots\\ - |\end{table}| -\end{quote} - -\pagebreak[3] -\DescribeMacro{\captionof} -\DescribeMacro{\captionof*} -Sometimes you want to typeset a caption \emph{outside} a floating environment, -putting a figure within a non-floating |mini|\-|page| for instance. -For this purpose \thispackage\ offers the command -\begin{quote} - |\captionof|\marg{float type}\oarg{list entry}\marg{heading}\quad. -\end{quote} -Note that the first argument, the \meta{float type}, is mandatory here, because -the |\captionof| command needs to know which name to put into the caption label -(e.g. ``Figure'' or ``Table'') and in which list to put the contents entry. -An example: -\begin{quote} -% |\captionof{figure}{A figure}|\\ - |\captionof{table}{A table}| -\end{quote} -typesets captions like this: -\begin{Example} -% \begingroup -% \captionof{figure}{A figure} -% \endgroup - \captionsetup{position=top} -% \begingroup - \captionof{table}{A table} -% \endgroup -\end{Example} - -The star variant |\caption|\-|of*| has the same behavior as the |\caption*| -command: -It typesets the caption without label and without entry to the list of figures -or tables. - -\INFO % \NEWdescription{v3.1} -Since |\caption|\-|of| uses the option |type| internally, the same -restrictions as for the |type| option apply here, so you should use both -|\caption|\-|of| and |\caption|\-|of*| only \emph{inside} boxes or -environments, too. -\See{\Ref{types}} - -\bigskip - -\pagebreak[3] -\DescribeMacro{\captionlistentry}\NEWfeature{v3.1} -Under certain circumstances it could be useful to make a list-of-figure -(or table) entry on its own. -This could be achieved with -\begin{quote} - |\captionlistentry|\oarg{float type}\marg{list entry}\quad. -\end{quote} - -One example: It's quite easy to have a |long|\-|table| with captions above the -contents and a single list entry which points to the first page of the table: -\begin{quote} - |\begin{longtable}{|\ldots|}|\\ - | \caption{|\ldots|}\\|\\ - |\endfirsthead|\\ - | \caption[]{|\ldots|}\\|\\ - |\endhead|\\ - | |\ldots -\end{quote} -But since the \package{longtable} package does not offer an -|\end|\-|first|\-|foot| command, you cannot easily have captions \emph{below} -the table contents and a single list entry which points to the first page of -the table. -Here is were the |\caption|\-|list|\-|entry| command could be used: -\begin{quote} - |\begin{longtable}{|\ldots|}|\\ - | \caption[]{|\ldots|}\\|\\ - |\endfoot|\\ - | \captionlistentry{|\ldots|}|\\ - | |\ldots -\end{quote} - -\begin{Annotation*} -Another example can be found in \Ref{examples}. -\end{Annotation*} - -\begin{Expert} -There is also a starred variant, |\caption|\-|list|\-|entry*|, which does not -increment the \meta{float type} counter. -(Note that inside |long|\-|table| environments |\caption|\-|list|\-|entry| -never increments the |table| counter. See also \Ref{longtable}.) -\end{Expert} - -\begin{Expert} -Please note that \meta{list entry} is a \emph{moving} argument, so everything -it contains must be \emph{robust}. (See also explanation of |\caption|) -\end{Expert} - -\subsection{Setting options} -\label{captionsetup} - -\DescribeMacro{\captionsetup} -We already know the |\caption|\-|setup| command (see \Ref{usage}), -but this time we get enlighten about its optional argument -\meta{float type}. - -Remember, the syntax of this command is -\begin{quote} - |\captionsetup|\oarg{float type}\marg{options}\quad. -\end{quote} -If a \meta{float type} gets specified, all the \meta{options} don't -change anything at this time. Instead they only get marked for a later use, -when a caption inside of a floating environment of the particular type -\meta{float type} gets typeset. -For example -\begin{quote} - |\captionsetup[figure]|\marg{options} -\end{quote} -forces captions within a |figure| environment to use the given \meta{options}. - -Here comes an example to illustrate this: -\begin{quote} - |\captionsetup{font=small}|\\ - |\captionsetup[figure]{labelfont=bf,textfont=it}| -\end{quote} -gives captions like this: -\begin{Example} - \captionsetup{font=small} - \captionsetup[figure]{labelfont=bf,textfont=it} - \begingroup - \captionof{figure}{A figure} - \endgroup - \captionsetup{position=top} - \begingroup - \captionof{table}{A table} - \endgroup -\end{Example} -As you see the command |\caption|\-|setup[figure]{|\ldots|}| only changes -the look of the |figure| caption labels, not touching the other ones. - -As \meta{float type} you can usually give one of these two only: -|figure| or |table|. -But as we will see later some \LaTeX\ packages (like the \package{floatrow}, -\package{longtable}, and \package{sidecap} package for example) and also -this package offer additional environments with captions and these two -commands can also be used with them. -\See{\Ref{declare} and \Ref{packages}} - -\begin{Expert} -\NEWfeature{v3.1} -There is also a starred variant of |\caption|\-|setup|: -\begin{quote} - |\captionsetup*|\oarg{float type}\marg{options} -\end{quote} -While the non-starred variant can give you warnings---for example if the -\meta{options} are actually not used throughout the document -(e.g.~a |\caption|\-|setup[table]{font=|\x|sf}| without a |table|)---the -starred variant will not. -\iffalse -This can get quite useful when setting generic options which are independent -of a specific document. -\fi -\end{Expert} - -\medskip - -\pagebreak[3] -\DescribeMacro{\clearcaptionsetup} -If you want to get rid of these parameters marked for an automatic use within -a particular environment you can use the command -\begin{quote} - |\clearcaptionsetup|\oarg{option}\marg{float type}\quad. -\end{quote} - -For example |\clearcaptionsetup{figure}| would clear all the extra handling -for figures in the example above: -\begin{quote} - |\captionsetup{font=small}|\\ - |\captionsetup[figure]{labelfont=bf,textfont=it}|\\ - \ldots\\ - | \caption{A figure}|\\ - \ldots\\ - |\clearcaptionsetup{figure}|\\ - \ldots\\ - | \caption{A figure}|\\ - \ldots -\end{quote} -\begin{Example} - \captionsetup{font=small} - \captionsetup[figure]{labelfont=bf,textfont=it} - \begingroup - \captionof{figure}{A figure} - \endgroup - \captionsetup{position=top} - \clearcaptionsetup{figure} - \begingroup - \captionof{figure}{A figure} - \endgroup -\end{Example} - -\pagebreak[3] -\NEWfeature{v3.1} -If an optional argument \meta{option} is given, only the settings regarding -this particular \meta{option} are cleared.\footnote{You can only specify -\emph{one} option here, not a list of options. -If you want to clean more than one option, you need to use more than one -\cs{clear}\-\texttt{caption}\-\texttt{setup}.} -While the example above not only clears the options -|labelfont=bf,|\x|textfont=it| -for figures (but all options for figures instead), -this one would only clear the |labelfont=bf| setting, leaving all other -settings for figures intact: -\begin{quote} - |\captionsetup{font=small}|\\ - |\captionsetup[figure]{labelfont=bf,textfont=it}|\\ - \ldots\\ - | \caption{A figure}|\\ - \ldots\\ - |\clearcaptionsetup[labelfont]{figure}|\\ - \ldots\\ - | \caption{A figure}|\\ - \ldots -\end{quote} -\begin{Example} - \captionsetup{font=small} - \captionsetup[figure]{labelfont=bf,textfont=it} - \begingroup - \captionof{figure}{A figure} - \endgroup - \captionsetup{position=top} - \clearcaptionsetup[labelfont]{figure} - \begingroup - \captionof{figure}{A figure} - \endgroup -\end{Example} -\begin{Expert} -Analogous to |\caption|\-|setup*| there is also a starred form -|\clear|\-|caption|\-|setup*| which suppresses warnings if the given -\meta{option} was not setup for the specified \meta{float type}. -\end{Expert} - -\medskip - -\pagebreak[3] -\DescribeMacro{\showcaptionsetup} -For debugging purposes the command -\nopagebreak[3] -\begin{quote} - |\showcaptionsetup|\marg{float type} -\end{quote} -\nopagebreak[3] -is offered. It generates a log file entry, showing the given options -for the specified \meta{float type}. For example -\begin{quote} - |\captionsetup[figure]{labelfont=bf,textfont=it}|\\ - |\showcaptionsetup{figure}| -\end{quote} -gives the info: -\begin{quote}\small - |Caption Info: Option list on `figure'|\\ - |Caption Data: {labelfont=bf,textfont=it} on input line 5.| -\end{quote} - -\pagebreak[3] -\subsection{Continued floats} -\label{ContinuedFloat} - -\DescribeMacro{\ContinuedFloat} -Sometimes you want to split figures or tables without giving them -their own reference number. This is what the command -\begin{quote} - |\ContinuedFloat| -\end{quote} -is for; it should be used as first command inside the floating environment. -It prevents the incrementation of the relevant counter (usually done by -|\caption|), so a figure or table containing a |\Continued|\-|Float| inside -gets the same reference number as the figure or table before. -An example: -\begin{quote} - |\begin{table}|\\ - | \caption{A table}|\\ - | |\ldots\\ - |\end{table}|\\ - \ldots\\ - |\begin{table}\ContinuedFloat|\\ - | \caption{A table (cont.)}|\\ - | |\ldots\\ - |\end{table}| -\end{quote} -gives the following result: -\begin{Example} - \captionsetup{type=table,position=b,skip=0pt} - \caption{A table} - \centerline{\ldots} -\end{Example} -\begin{Example} - \captionsetup{type=table,position=b,skip=0pt} - \ContinuedFloat - \caption{A table (cont.)} - \centerline{\ldots} -\end{Example} - -\bigskip - -\NEWfeature{v3.1} -Furthermore the |\Continued|\-|Float| command executes options associated with -the type name ``|Continued|\-|Float|''. For example this can be used to switch -to a different label format for continued figures or tables, as shown here: -\begin{quote} - |\DeclareCaptionLabelFormat{continued}{Continued #1~#2}|\\ - |\captionsetup[ContinuedFloat]{labelformat=continued}|\\ - \ldots\\ - |\begin{table}\ContinuedFloat|\\ - | \caption{A table}|\\ - | |\ldots\\ - |\end{table}| -\end{quote} -\begin{Example} - \captionsetup{type=table,position=b,skip=0pt} - \captionsetup[ContinuedFloat]{labelformat=continued1} - \ContinuedFloat - \caption{A table}\label{continued1} - \centerline{\ldots} -\end{Example} -\smallskip -\See{\Ref{declare} for an explanation of - \cs{Declare}\-\texttt{Caption}\-\texttt{Label}\-\texttt{Format}.} - -\medskip - -There is also a \LaTeX\ counter called |Continued|\-|Float| which could be -used for own purposes. -For ordinary (floating) environments it's set to zero, to one for the first -continued float, to two inside the second one, and so on. -So every |\Continued|\-|Float| increments this counter and a floating -environment without |\Continued|\-|Float| command resets this counter to zero. -An example: -\begin{quote} - |\DeclareCaptionLabelFormat{cont}{#1~#2\alph{ContinuedFloat}}|\\ - |\captionsetup[ContinuedFloat]{labelformat=cont}|\\ - \ldots\\ - |\begin{table}\ContinuedFloat|\\ - | \caption{A table}|\\ - | |\ldots\\ - |\end{table}| -\end{quote} -\begin{Example} - \captionsetup{type=table,position=b,skip=0pt} - \captionsetup[ContinuedFloat]{labelformat=continued2} - \ContinuedFloat - \caption{A table}\label{continued2} - \centerline{\ldots} -\end{Example} -\medskip -A reference to this table would still result in the output -``\autoref{continued2}'' since only the caption label format was changed. -If you would like to use the |Continued|\-|Float| counter for the references, -too, you could redefine the command |\the|\-|Continued|\-|Float| instead, -which will be appended to the figure or table counter automatically in -continued floats and is preset to be empty. -\begin{quote} - |\renewcommand\theContinuedFloat{\alph{ContinuedFloat}}|\\ - \ldots\\ - |\begin{table}\ContinuedFloat|\\ - | \caption{A table}|\\ - | |\ldots\\ - |\end{table}| -\end{quote} -\begin{Example} - \captionsetup{type=table,position=b,skip=0pt} - \renewcommand\theContinuedFloat{\alph{ContinuedFloat}} - \ContinuedFloat - \caption{A table}\label{continued3} - \centerline{\ldots} -\end{Example} -\medskip -A reference to that table would result in the output ``\autoref{continued3}''. - -\pagebreak[3] -\DescribeMacro{\ContinuedFloat*} -Suppose you want to start the first figure or table of such a series with a -kind of ``Figure 7a'' and not with ``Figure 7'' (and the second one with -``Figure 7b'' instead of ``Figure 7a''). -This is possible, too, by using the starred variant |\Continued|\-|Float*| -which---just like |\Continued|\-|Float|---executes options associated with the -type name ``|Continued|\-|Float|'' and increments the \LaTeX\ counter -|Continued|\-|Float|, \emph{but} marks the first figure or table of a series -instead: -\begin{quote} - |\renewcommand\theContinuedFloat{\alph{ContinuedFloat}}|\\ - \ldots\\ - |\begin{figure}\ContinuedFloat*|\\ - | |\ldots\\ - | \caption{First figure of a series}|\\ - |\end{figure}|\\ - \ldots\\ - |\begin{figure}\ContinuedFloat|\\ - | |\ldots\\ - | \caption{Second figure of a series}|\\ - |\end{figure}|\\ - \ldots\\ - |\begin{figure}\ContinuedFloat|\\ - | |\ldots\\ - | \caption{Third figure of a series}|\\ - |\end{figure}| -\end{quote} -\begin{Example} - \captionsetup{type=figure,position=b,skip=0pt} - \renewcommand\theContinuedFloat{\alph{ContinuedFloat}} - \begingroup - \ContinuedFloat* - \centerline{\ldots} - \caption{First figure of a series} - \endgroup - \begingroup - \ContinuedFloat - \centerline{\ldots} - \caption{Second figure of a series} - \endgroup - \begingroup - \ContinuedFloat - \centerline{\ldots} - \caption{Third figure of a series} - \endgroup -\end{Example} -\smallskip -\Note{Unfortunately \cs{ContinuedFloat*} is not available if the - \package{subfig} package\cite{subfig} is loaded.} - -\pagebreak[3] -\subsubsection*{A note about longtables} -If you want to have a different caption label in |long|\-|table|s (offered -by the \package{longtable} package\cite{longtable}) after a page break, -this can \emph{not} be archived by using |\Continued|\-|Float|, -but instead you could write something like: -\begin{quote} - |\DeclareCaptionLabelFormat{continued}{Continued #1~#2}|\\ - \ldots\\ - |\begin{longtable}{|\ldots|}|\\ - | \caption{A longtable}\\|\\ - |\endfirsthead|\\ - | \captionsetup{labelformat=continued}|\\ - | \caption[]{A longtable}\\|\\ - |\endhead|\\ - | |\ldots\\ - |\end{longtable}| -\end{quote} - -% --------------------------------------------------------------------------- % - -\clearpage -\section{Own enhancements} -\label{declare} - -A family of commands is provided to allow users to define their own formats -etc. -This enables information on separators, justification, fonts, and styles to -be associated with a name and kept in one place. -(These commands need to appear in the document preamble, -this is the part between |\document|\-|class| and |\begin{document}|.) - -\pagebreak[3] -\DescribeMacro{\DeclareCaption-\\Format} -You can define your own caption formats using the command -\begin{quote} - |\DeclareCaptionFormat|\marg{name}\marg{code using \#1, \#2 and \#3}\mbox{\quad.} -\end{quote} -At usage the system replaces \#1 with the caption label, \#2 with the -separator and \#3 with the text. So the standard format |plain| is -pre-defined by \thispackage\ as -\begin{quote} - |\DeclareCaptionFormat{plain}{#1#2#3\par}|\quad. -\end{quote} -\begin{Expert} -There is also a starred variant, |\Declare|\-|Caption|\-|Format*|, -which causes the code being typeset in \TeX s vertical (instead of -horizontal) mode, but does not support the |indention=| option. -\end{Expert} - -\pagebreak[3] -\DescribeMacro{\DeclareCaption-\\LabelFormat} -Likewise you can define your own caption label formats: -\begin{quote} - |\DeclareCaptionLabelFormat|\marg{name}\marg{code using \#1 and \#2} -\end{quote} -At usage \#1 gets replaced with the name (e.g. ``figure'') and \#2 -gets replaced with the reference number (e.g. ``12''). -An example: -\begin{quote} - |\DeclareCaptionLabelFormat{bf-parens}{(\textbf{#2})}|\\ - |\captionsetup{labelformat=bf-parens,labelsep=quad}| -\end{quote} -\example*{labelformat=bf-parens,labelsep=quad}{\exampletext} - -\pagebreak[3] -\DescribeMacro{\bothIfFirst} -\DescribeMacro{\bothIfSecond} -If you define your own caption label formats and use the -\package{subcaption} or \package{subfig}\cite{subfig} package, -you should take care of empty caption label names. -For this purpose the commands -\begin{quote} - |\bothIfFirst|\marg{first arg}\marg{second arg}\quad and\\ - |\bothIfSecond|\marg{first arg}\marg{second arg} -\end{quote} -are offered. |\bothIfFirst| tests if the first argument exists (means: is -not empty), |\bothIfSecond| tests if the second argument exists. If yes, -both arguments get typeset, otherwise none of them. - -\smallskip - -\pagebreak[3] -For example the standard label format |simple| is \emph{not} defined as -\begin{quote} - |\DeclareCaptionLabelFormat{simple}{#1~#2}|\mbox{\quad,} -\end{quote} -because this could cause an extra space if \#1 is empty. Instead |simple| -is defined as -\begin{quote} - |\DeclareCaptionLabelFormat{simple}%|\\ - | {\bothIfFirst{#1}{~}#2}|\mbox{\quad,} -\end{quote} -causing the space to appear only if the label name is present. - -\smallskip - -\pagebreak[3] -\DescribeMacro{\DeclareCaption-\\TextFormat}\NEWfeature{v3.0l} -Likewise you can define your own caption text formats: -\begin{quote} - |\DeclareCaptionTextFormat|\marg{name}\marg{code using \#1} -\end{quote} -At usage \#1 gets replaced with the caption text. - -\bigskip - -\pagebreak[3] -\DescribeMacro{\DeclareCaption-\\LabelSeparator} -You can define your own caption label separators with -\begin{quote} - |\DeclareCaptionLabelSeparator|\marg{name}\marg{code}\mbox{\quad.} -\end{quote} -Again an easy example taken from \thispackage\ itself: -\begin{quote} - |\DeclareCaptionLabelSeparator{colon}{: }| -\end{quote} -\begin{Expert} -There is also a starred variant, |\Declare|\-|Caption|\-|Label|\-|Separator*|, -which causes the code being typeset without using the |label|\-|font=| setting. -So for example the label separators |quad|, |new|\-|line|, and |en|\-|dash| -are defined in this way. -\end{Expert} - -\bigskip - -\pagebreak[3] -\DescribeMacro{\DeclareCaption-\\Justification} -You can define your own caption justifications with -\begin{quote} - |\DeclareCaptionJustification|\marg{name}\marg{code}\mbox{\quad.} -\end{quote} -The \meta{code} simply gets typeset just before the caption. -E.g.~using the justification |raggedright|, which is defined as -\begin{quote} - |\DeclareCaptionJustification{raggedright}{\raggedright}|\mbox{\quad,} -\end{quote} -typesets captions with all lines moved to the left margin. - -\bigskip - -\pagebreak[3] -\DescribeMacro{\DeclareCaption-\\Font} -You can define your own caption fonts with -\begin{quote} - |\DeclareCaptionFont|\marg{name}\marg{code}\quad. -\end{quote} -For example this package defines the options |small| and |bf| as -\begin{quote} - |\DeclareCaptionFont{small}{\small}|\quad and\\ - |\DeclareCaptionFont{bf}{\bfseries}|\quad. -\end{quote} -\iffalse -The line spacing could be customized using the \package{setspace} package, -for example:%\NEWdescription{v3.0h} -\begin{quote} - |\usepackage{setspace}|\\ - |\DeclareCaptionFont{singlespacing}{\setstretch{1}}|~\footnote{% - \emph{\DefaultNoteText:} Using \cs{singlespacing} does not work here since - it contains a \cs{vskip} command.}\\ - |\DeclareCaptionFont{onehalfspacing}{\onehalfspacing}|\\ - |\DeclareCaptionFont{doublespacing}{\doublespacing}|\\ - |\captionsetup{font={onehalfspacing,small},labelfont=bf}| -\end{quote} -\example{font={onehalfspacing,small},labelfont=bf,singlelinecheck=off}{\exampletext} -\fi -An example which brings color into life: -\begin{quote} - |\usepackage{color}|\\ - |\DeclareCaptionFont{red}{\color{red}}|\\ - |\DeclareCaptionFont{green}{\color{green}}|\\ - |\DeclareCaptionFont{blue}{\color{blue}}|\\ - |\captionsetup{labelfont={blue,bf},textfont=green}| -\end{quote} -\example*{labelfont={color=blue,bf},textfont={color=green},singlelinecheck=off}{\exampletext} -But since \thispackage\ already includes the tricky definition -\begin{quote} - |\DeclareCaptionFont{color}{\color{#1}}| -\end{quote} -you can get the same result simply with -\begin{quote} - |\usepackage{color}|\\ - |\captionsetup{labelfont={color=blue,bf},|\\ - | textfont={color=green}}|\quad. -\end{quote} - -\medskip - -\pagebreak[3] -\DescribeMacro{\DeclareCaption-\\Style} -You can define your own caption styles with -\begin{quote} - |\DeclareCaptionStyle|\marg{name}\oarg{additional options}\marg{options}\mbox{\quad.} -\end{quote} -Remember, caption styles are just a collection of suitable options, saved -under a given name. You can wake up these options at any time with the -option |style=|\meta{style name}. - -All caption styles are based on the |base| set of options. (See \Ref{style} -for a complete list.) So you only need to specify options which are different -to them. - -If you specify \meta{additional options} they get used in addition when -the caption fits into a single line and this check was not disabled with -the option |single|\-|line|\-|check=off|. - -Again a very easy example taken from the core of this package: The -caption style |base| is pre-defined as -\begin{quote} - |\DeclareCaptionStyle{base}%|\\ - | [justification=centering,indention=0pt]{}|\quad. -\end{quote} - -Something more exciting: -\begin{quote} - |\DeclareCaptionStyle{mystyle}%|\\ - | [margin=5mm,justification=centering]%|\\ - | {font=footnotesize,labelfont=sc,margin={10mm,0mm}}|\\ - |\captionsetup{style=mystyle}| -\end{quote} -gives you caption like these ones: -\begin{Example} - \captionsetup{type=figure,style=mystyle,position=b} - \caption{A short caption.} - \caption{A long long long long long long long long long - long long long long long long long long long - long long long long long long long long long caption.} -\end{Example} - -\bigskip - -\pagebreak[3] -\DescribeMacro{\DeclareCaption-\\ListFormat}\NEWfeature{v3.1} -You can define your own caption list formats with -\begin{quote} - |\DeclareCaptionListFormat|\marg{name}\marg{code using \#1 and \#2}\mbox{\quad.} -\end{quote} -At usage \#1 gets replaced with the label prefix (e.g.~|\p@figure|), -and \#2 gets replaced with the reference number (e.g.~|\thefigure|). - -% --------------------------------------------------------------------------- % - -\subsection{Further examples} -\label{examples} - -\subsubsection*{Example 1} - -%\NEWdescription{v3.1} -If you would like to have a line break between caption label and text -you could define it this way: -\begin{quote} - |\DeclareCaptionFormat{myformat}{#1#2\\#3}| -\end{quote} -If you select this format with |\caption|\-|setup{format=|\x|myformat}| -you get captions like this: -%\begin{Example} -% \captionsetup{skip=0pt} - \example{format=myformat1,labelfont=bf}{\exampletext} -%\end{Example} -You could even use an indention with this caption format: -\begin{quote} - |\captionsetup{format=myformat,indention=1cm}| -\end{quote} -This would look like this: -%\begin{Example} -% \captionsetup{skip=0pt} - \example{format=myformat1,indention=1cm,labelfont=bf}{\exampletext} -%\end{Example} -Instead, you would like to have an indention only of the first line of -the caption text? No problem, e.g. -\begin{quote} - |\newlength\myindention|\\ - |\DeclareCaptionFormat{myformat}%|\\ - | {#1#2\\\hspace*{\myindention}#3}|\\ - \ldots\\ - |\setlength\myindention{1cm}|\\ - |\captionsetup{format=myformat}| -\end{quote} -would give you captions like -%\begin{Example} -% \captionsetup{skip=0pt} - \example{format=myformat2,myindention=1cm,labelfont=bf}{\exampletext} -%\end{Example} -But you want to have an caption option for this indention, so you can use -it for example with -|\caption|\-|setup|\x|[figure]|\x|{my|\-|indention=|\x\ldots|}|? -This could be done, too: -\begin{quote} - |\newlength\myindention|\\ - |\DeclareCaptionOption{myindention}%|\\ - | {\setlength\myindention{#1}}|\\ - |\DeclareCaptionFormat{myformat}%|\\ - | {#1#2\\\hspace*{\myindention} #3}|\\ - \ldots\\ - |\captionsetup{format=myformat,myindention=1cm}| -\end{quote} -would give the same result as the example above. - -\subsubsection*{Example 2} - -You want captions to look like this: -%\begin{Example} -% \captionsetup{skip=0pt} - \example{format=reverse,labelformat=fullparens,labelsep=fill,labelfont=it}{\exampletext} -%\end{Example} -\pagebreak[2] -You could do it this way: -\nopagebreak[3] -\begin{quote} - |\DeclareCaptionFormat{reverse}{#3#2#1}|\\ - |\DeclareCaptionLabelFormat{fullparens}%|\\ - | {(\bothIfFirst{#1}{~}#2)}|\\ - |\DeclareCaptionLabelSeparator{fill}{\hfill}|\\ - |\captionsetup{format=reverse,labelformat=fullparens,|\\ - | labelsep=fill,font=small,labelfont=it}| -\end{quote} - -\subsubsection*{Example 3} - -The caption text should go into the left margin? A possible solution would be: -\begin{quote} - |\DeclareCaptionFormat{llap}{\llap{#1#2}#3\par}|\\ - |\captionsetup{format=llap,labelsep=quad,singlelinecheck=no}| -\end{quote} -As a result you would get captions like this: -\example{format=llap,labelsep=quad,singlelinecheck=no,margin=0pt}{\exampletext} - -\medskip - -If the indention into the margin shall be fixed, you could use a combination -of |\llap| and |\makebox|, for example: -\begin{quote} - |\DeclareCaptionFormat{llapx}%|\\ - | {\llap{\makebox[5em][l]{#1}}#3\par}|\\ - |\captionsetup{format=llapx,singlelinecheck=off}| -\end{quote} -\example{format=llapx,singlelinecheck=off,skip=0pt,margin=0pt}{\exampletext} - -\subsubsection*{Example 4} - -This example puts a figure aside a table, but uses only one common caption for both. -This will be achieved by a combination of -|\Declare|\-|Caption|\-|Label|\-|Format| and |\caption|\-|list|\-|entry|: -\begin{quote} - |\DeclareCaptionLabelFormat{andtable}%|\\ - | {#1~#2 \& \tablename~\thetable}|\\ - \ldots\\ - |\begin{figure}|\\ - | \centering|\\ - | \includegraphics{|\ldots|}%|\\ - | \qquad|\\ - | \begin{tabular}[b]{\ldots}|\\ - | |\ldots\\ - | \end{tabular}|\\ - | \captionlistentry[table]{|\ldots|}|\\ - | \captionsetup{labelformat=andtable}|\\ - | \caption{|\ldots|}|\\ - |\end{figure}| -\end{quote} -\DeleteShortVerb{\|}% -\noindent\begin{minipage}{\linewidth} - \captionsetup{type=figure} - \centering - \includegraphics[width=30pt]{cat}% - \qquad - \begin{tabular}[b]{r|rr} - & x & y \\\hline - a & 1 & 2 \\ - b & 3 & 4 \\ - \end{tabular} - \captionlistentry[table]{A figure and a table with a common caption} - \captionsetup{labelformat=andtable} - \caption{A figure and a table with a common caption~\footnotemark} -\end{minipage} -\footnotetext{The picture was taken with permission from the - \LaTeX\ Companion\cite{TLC2} examples.} -\MakeShortVerb{\|} - -(Please remember that |\caption|\-|list|\-|entry| increments the figure - resp.~table counter.) - -% --------------------------------------------------------------------------- % - -\clearpage -\section{Supported document classes} -\label{classes} - -%\NEWdescription{v3.1} -This section will give you an overview of the document classes the -\package{caption} supports, what do they already offer regarding captions, -what side effects will occur when using the \package{caption} package with -them, and what are the `default' settings for them. - -\NEWfeature{v3.1} -The `default' settings depend on the document class you use; they represent -how the class author wanted the captions to look like. So for example -setting |format=|\x|default| can give you different visual designs when used -with different document classes. - -\begingroup\setlength\leftmargini{0.3em}% default = 2.5em -\INFO -If you don't find the document class you use in this section, you usually -don't have to worry: Many document classes (e.g.~the \class{octavo} class) -are derived from one of the standard document classes \class{article}, -\class{report}, or \class{book}, and behave the same regarding captions. -\Thispackage\ automatically does a compatibility check against the document -class used and will give you the clear warning -\begin{quote}\footnotesize - |Package caption Warning: Unsupported document class (or package) detected,|\\ - |(caption) usage of the caption package is not recommended.|\\ - |See the caption package documentation for explanation.| -\end{quote} -if such an incompatibility was detected. -If you don't get such warning everything is fine, but if you get it the -usage of \thispackage\ is not recommended and especially not supported. -\endgroup - -\begin{Expert} -If you get such a compatibility warning but decide to use \thispackage{} -anyway, you should watch carefully what side-effects occur, usually the -look and feel of your captions will change by just including \thispackage{} -without options, meaning they do not look like as intended by the author -of the document class. -If this is fine for you, you should first specify the option |style=|\x|base| -via |\use|\-|package[style=|\x|base]{caption}| or -|\caption|\-|setup{style=|\x|base}| to set \thispackage\ into a well-defined -state. -Afterwards you can start setting your own options additionally and -keep your fingers crossed. -\end{Expert} - -\newcommand*\Option{Option} -\newcommand*\defaultvalue{\texttt{default} value} -\newcommand*\uses{\textit{uses}} -\newcommand*\settings{\textit{settings}} -\newcommand*\nofont{\textit{none}} - -\subsection{Standard \LaTeX: article, report, and book} - -\begin{tabular}{ll} -\Option & \defaultvalue \\\hline -|format=| & |plain| \\ -|labelformat=| & |simple| \\ -|labelsep=| & |colon| \\ -|justification=| & |justified| \\ -|font=| & \nofont \\ -|labelfont=| & \nofont \\ -|textfont=| & \nofont \\ -\end{tabular} - -\begin{Annotation} -This also applies to document classes derived from them. -\end{Annotation} - -\subsection{\AmS: amsart, amsproc, and amsbook} -\label{AMS} - -\begin{tabular}{ll} -\Option & \defaultvalue \\\hline -|format=| & |plain| \\ -|labelformat=| & |simple| \\ -|labelsep=| & |.\enspace| \\ -|justification=| & |justified| \\ -|font=| & |\@captionfont| \\ -|labelfont=| & |\@captionheadfont| \\ -|textfont=| & |\@captionfont\upshape| \\ -\end{tabular} - -\begin{Annotation*} -|\@caption|\-|font| will be set to |\normal|\-|font|, and -|\@caption|\-|head|\-|font| to |\sc|\-|shape| by the \AmS\ document classes. -\end{Annotation*} - -Furthermore the margin will be set to |\caption|\-|indent| for -more-than-one-line captions (which will be set to |3pc| by the \AmS\ classes), -the margin for single-line captions will be set to the half of it instead. -If you want to use a common margin for both, insert -|\clear|\-|caption|\-|setup[margin*]{single|\-|line}| -into the preamble of your document, after loading \thispackage. - -Additionally the options |figure|\-|position=b,|\x|table|\-|position=t| -will be set. You can override these settings by specifying other values for -|figure|\-|position=| or |table|\-|position=| in the option list while -loading \thispackage. - -\subsection{beamer} -\label{beamer} - -\begin{tabular}{ll} -\Option & \defaultvalue \\\hline -|format=| & |plain| \\ -|labelformat=| & \textit{not numbered} \\ -|labelsep=| & |colon| \\ -|justification=| & |raggedright| \\ -|font=| & \class{beamer} ``|caption|'' \settings \\ -|labelfont=| & \class{beamer} ``|caption name|'' \settings \\ -|textfont=| & \nofont \\ -\end{tabular} - -\subsubsection*{Build-in features, and side-effects} -You can setup font and color settings with -|\set|\-|beamer|\-|font{caption}|\marg{options} and -|\set|\-|beamer|\-|font{caption name}|\marg{options}. -This will still work, unless you set a different font with -|\caption|\-|setup{font=|\x\meta{options}|}| or -|\caption|\-|setup{label|\-|font=|\x\meta{options}|}|.\par -Furthermore the \class{beamer} classes offer different caption templates -which can be chosen with -|\set|\-|beamer|\-|template|\x|{caption}|\x|[|\meta{template}|]|. -Since \thispackage\ replaces this caption template mechanism, -|\def|\-|beamer|\-|template*|\x|{caption}|\x\marg{template code} -and -|\set|\-|beamer|\-|template|\x|{caption}|\x|[|\meta{template}|]| -will have no effect when \thispackage\ is used. -(Exception: Selecting the template |default|, |num|\-|bered|, or -|caption| |name| |own| |line| will be recognized by \thispackage and be mapped -to corresponding options.) - -\subsection{\KOMAScript: scrartcl, scrreprt, and scrbook} -\label{KOMA} - -\begin{tabular}{ll} -\Option & \defaultvalue \\\hline -|format=| & \uses\ |\setcapindent| \textit{\&} |\setcaphanging| \settings \\ -|labelformat=| & \textit{like \purett{simple}, but with support of ``autodot''}\\ -|labelsep=| & |\captionformat| \\ -|justification=| & |justified| \\ -|font=| & |\setkomafont{caption}| \settings \\ -|labelfont=| & |\setkomafont{captionlabel}| \settings \\ -|textfont=| & \nofont \\ -\end{tabular} - -\subsubsection*{Build-in features} -The \KOMAScript\ document classes offer many ways to customize the look and -feel of the captions. For an overview and a full description please take a -look at the \KOMAScript\ documentation, section `Tables and Figures'. - -\subsubsection*{Side effects} -The optional argument of |\set|\-|cap|\-|width| is not supported and -will be ignored if used in conjunction with the \package{caption} package. -Furthermore the \KOMAScript\ options |table|\-|caption|\-|above| \& -|table|\-|caption|\-|below| and the commands |\caption|\-|above| \& -|\caption|\-|below| are stronger than the |position=| setting offered by -the \package{caption} package. - -\subsection{\NTG: artikel, rapport, and boek} -\label{NTG} - -\begin{tabular}{ll} -\Option & \defaultvalue \\\hline -|format=| & |plain| \\ -|labelformat=| & |simple| \\ -|labelsep=| & |colon| \\ -|justification=| & |justified| \\ -|font=| & \nofont \\ -|labelfont=| & |\CaptionLabelFont| \\ -|textfont=| & |\CaptionTextFont| \\ -\end{tabular} - -\subsubsection*{Build-in features, and side-effects} -|\Caption|\-|Label|\-|Font| and |\Caption|\-|Text|\-|Font| can be set either -directly or by using |\Caption|\-|Fonts|. -Both is still supported unless you use one of the two options -|label|\-|font=| or |text|\-|font=| offered by \thispackage. - -\subsection{\SmF: smfart and smfbook} -\label{SMF} - -Since the \SmF\ document classes are derived from the \AmS\ document classes -the same default values are valid here. - -Additionally the margin is limited up to the tenth of the |\line|\-|width|. -If you don't like this limitation, you can switch it off with the option -|max|\-|margin=|\x|off| or |max|\-|margin=|\x|false| -(which both means the same). - -\subsection{thesis} -\label{thesis} - -\begin{tabular}{ll} -\Option & \defaultvalue \\\hline -|format=| & |hang| \\ -|labelformat=| & \textit{like \purett{simple}, but with short name}\\ -|labelsep=| & |colon| \\ -|justification=| & |justified| \\ -|font=| & \nofont \\ -|labelfont=| & |\captionheaderfont| \\ -|textfont=| & |\captionbodyfont| \\ -\end{tabular} - -\subsubsection*{Build-in features, and side-effects} -The caption label font can be set with |\caption|\-|header|\-|font|, -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. - -% --------------------------------------------------------------------------- % - -\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{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. - -% --------------------------------------------------------------------------- % - -\clearpage -\section{Supported packages} -\label{packages} -\label{compatibility} - -%\NEWdescription{v3.1} -\Thispackage\ was adapted to the following packages which deals with -captions, too: -\begin{quote} - \package{float}, \package{floatflt}, \package{fltpage}, - \package{hyperref}, \package{hypcap}, \package{listings}, - \package{longtable}, \package{picinpar}, \package{picins}, - \package{rotating}, \package{setspace}, \package{sidecap}, - \package{subfigure}, \package{supertabular}, \package{threeparttable}, - \package{wrapfig}, and \package{xtab} -\end{quote} - -Furthermore the \package{floatrow} package\cite{floatrow}, the -\package{subcaption} package (which is part of the \package{caption} package -bundle), and the \package{subfig} package\cite{subfig} support \thispackage{} -and use its |\caption|\-|setup| interface. - -\bigskip - -\begingroup\setlength\leftmargini{0.3em}% default = 2.5em -\INFO -If a package (or document class) unknown to \thispackage\ redefines -the |\caption| command as well, this redefinition will be preferred -over the one this package offers, providing maximum compatibility and -avoiding conflicts. -If such a potential incompatibility is detected, you will see this -warning message:~\footnote{% - You can suppress this warning by specifying the option - \texttt{compatibility=true} when loading \thispackage.} -\begin{quote}\footnotesize - |Package caption Warning: \caption will not be redefined since it's already|\\ - |(caption) redefined by a document class or package which is|\\ - |(caption) unknown to the caption package.|\\ - |See the caption package documentation for explanation.| -\end{quote} -\endgroup - -As a result, the following features offered by \thispackage\ will not be available: -\begin{itemize} - \item the options |labelformat=|, |position=auto|, |list=|, and |listformat=| - \item |\caption*| (to produce a caption without label) - \item |\caption[]{|\ldots|}| (to produce no entry in the List of Figures or Tables) - \item |\caption{}| (to produce an empty caption without label separator) - \item |\ContinuedFloat| - \item correctly justified captions in environments like \texttt{wide} and - \texttt{addmargin} which add extra margins - \item the \textsf{hypcap} feature \See{\Ref{hyperref}\,} - \item the sub-caption feature \See{\package{subcaption} package documentation} -\end{itemize} - -\DescribeMacro{compatibility=} -You can override this compatibility mode by specifying the option -\begin{quote} - |compatibility=false| -\end{quote} -when loading \thispackage. -But please note that using this option is neither recommended nor supported -since unwanted side-effects or even errors could occur afterwards. -(For that reason you will get a warning about this.) - -\newcommand\packagedescription[1]{% - \ifvmode\else\par\fi - \nopagebreak - \parbox[b]{\linewidth}{\footnotesize\leftskip=10pt\rightskip=10pt\relax#1}\par - \nopagebreak\smallskip\nopagebreak} - -\PageBreak -\subsection{algorithms} -\label{algorithms} -\packagedescription{% -The \package{algorithms} package bundle\cite{algorithms} provides two -environments: The \texttt{algorithmic} environment provides a possibility -for describing algorithms, and the \texttt{algorithm} environment provides -a ``float'' wrapper for algorithms.} - -Since the \texttt{algorithm} environment is implemented via |\new|\-|float| -provided by the \package{float} package\cite{float}, please see \Ref{float}. - -\iffalse -\pagebreak[3] -\subsection{algorithm2e} -\label{algorithm2e} -\packagedescription{% -The \package{algorithm2e} package\cite{algorithm2e} offers an environment for -writing algorithms in LaTeX2e.} - -Since the \package{algorithm2e} package does not use some kind of standard -interface for defining its floating environment (e.g.~|\newfloat| of the -\package{float} package) and typesetting its caption, -the \package{algorithm2e} package is \emph{not} supported by \thispackage. - -So if you want to customize the captions using \thispackage, -you have to build a new environment which uses a supported interface regarding -floats (e.g. using the \package{float} or \package{floatrow} package), -and combine this environment with the internal \package{algorithm2e} code. - -As first step you could define a non-floating environment \texttt{algorithmic}, -for example: -\begin{quote} - |\usepackage{algorithm2e}|\\ - |% save the "algorithm" environment from the algorithm2e package|\\ - |\let\ORIGalgorithm\algorithm|\\ - |\let\ORIGendalgorithm\endalgorithm|\\ - |% define the algorithmic environment|\\ % , based on the saved environment - |\newenvironment{algorithmic}%|\\ - | {\renewenvironment{algocf}[1][h]{}{}% pass over floating stuff|\\ - | \ORIGalgorithm}%|\\ - | {\ORIGendalgorithm}|\\ - \ldots -\end{quote} -Having defined this non-floating environment, you could define your own new -floating environment with |\newfloat| of the \package{float} package -(or |\DeclareNewFloatType| of the \package{floatrow} package), -and use the combination of this floating environment and \texttt{algorithmic} -in its body, just like you would do when you use the -\package{algorithm}/\package{algorithmic} package tandem. - -You could even use the \package{algorithm} package for this purpose, for example: -\begin{quote} - \ldots\\ - |% load the algorithm package to re-define the|\\ - |% floating environment "algorithm" and \listofalgorithms|\\ - |\let\listofalgorithms\undefined|\\ - |\usepackage{algorithm}|\\ - \ldots\\ - |% Example usage:|\\ - |\begin{algorithm}|\\ - |\caption{An algorithm}|\\ - |\begin{algorithmic}|\\ - | \SetVline|\\ - | \eIf{cond1}{|\\ - | a line\;|\\ - | }{|\\ - | another line\;|\\ - | }|\\ - |\end{algorithmic}| -\end{quote} -Now you are finally able to customize the float and caption layout like every -other floating environment defined with the \package{float} package\cite{float}, -please see \Ref{float}. - -\begin{Annotation} -An alternative would be using the \package{algorithmicx} package. -\end{Annotation} -\fi - -\pagebreak[3] -\subsection{float} -\label{float} -\packagedescription{% -The \package{float} package\cite{float} introduces the commands -\cs{restylefloat} to give existing floating environments a new look \& feel -and \cs{newfloat} to define new floating environments. -It also provides the ``\texttt{H}'' float placement option which places -the environments ``here'' instead of letting them floating around.} - -For floating environments defined with \cs{newfloat} or \cs{restylefloat} the -|po|\-|si|\-|tion| option has no effect on the main caption anymore, since its -placement and spacing will be controlled by the selected float style instead. - -A caption style and options defined with the name of the float style will be -executed additionally to the regular ones. -Using this mechanism \thispackage\ emulates the default look \& feel of the -|ruled| captions: It defines the caption style -\begin{quote} - |\DeclareCaptionStyle{ruled}%|\\ - | {labelfont=bf,labelsep=space,strut=off}|\mbox{\quad.} -\end{quote} -So to change this you need either define your own caption style called -|ruled| or use |\caption|\-|setup[ruled]|\marg{options} to specify additional -options.%, -%e.g.~|\caption|\-|setup[ruled]{labelsep=|\x|colon}|. - -Also by using this mechanism the skip between a |boxed| float and its caption -is specified, overriding its global value: -\begin{quote} - |\captionsetup[boxed]{skip=2pt}| -\end{quote} -For changing this, just use |\caption|\-|setup[boxed]{skip=|\x\meta{value}|}| -with an appropriate value. Or if you want to use the global |skip| setting -instead, you can remove the usage of the local setting for these floats with -|\clear|\-|caption|\-|setup[skip]{boxed}|. - -\begin{Note} -Only one single caption can be typeset inside environments defined with -|\new|\-|float| or |\re|\-|style|\-|float|, furthermore these environments -are not behaving exactly like the pre-defined floats |figure| and |table|. -As a consequence many packages do not cooperate well with these. -Furthermore the \package{float} package has some caveats \& limitations, -so if you just want to define a new simple floating environment---behaving -like |figure| or |table|---I recommend using |\Declare|\-|Floating|\-|Environment| -offered by the \package{newfloat} package instead. -And for defining non-simple floating environments and customization I -recommend using |\Declare|\-|New|\-|Float|\-|Type| offered by the -\package{floatrow} package\cite{floatrow}. -\end{Note} - -\iffalse -Please also note that you \emph{don't} need a |\restyle|\-|float| for using -the ``|H|'' float placement specifier. Some docs say so, but they are -wrong. -And |\restyle|\-|float{table}| is a very good method to shoot yourself -in the foot, since many packages using |table| internally are not working -correctly afterwards. -\fi - -\pagebreak[3] -\subsection{floatflt} -\label{floatflt} -\packagedescription{% -The \package{floatflt} package\cite{floatflt} offers figures and tables -which do not span the full width of a page and are float around by text.} - -\NEWfeature{v3.1} -If you want to setup special options for the |float|\-|ing|\-|figure| and -|float|\-|ing|\-|table| environments you can use -\begin{quote} - |\captionsetup[floatingfigure]|\marg{options}\quad\emph{and}\\ - |\captionsetup[floatingtable]|\marg{options}\quad. -\end{quote} -These options will be executed additionally to the regular ones for -|figure| resp.~|table|. - -\begin{Note} -The |margin| resp.~|width| setting will not be used for these figures resp.~tables, -unless you set it explicit with |\caption|\-|setup[floating|\-|figure]{|\ldots|}| -resp.~|\caption|\-|setup[floating|\-|table]{|\ldots|}|. -\end{Note} - -\pagebreak[3] -\subsection{fltpage} -\label{fltpage} -\packagedescription{% -The \package{fltpage} package\cite{fltpage} offers the outhouse of the -caption for |figure|s or |table|s which needs the whole page -for its contents. This will be done by placing the caption on the bottom -of the previous or next page.} - -\iffalse -\NEWfeature{v3.1} -Two options control the links to the environments |FPfigure| and |FPtable|: -\begin{description} -\item{\texttt{FPlist=caption} or \texttt{FPlist=figure}}\\[\smallskipamount] -If set to |caption|, the list entry will link to the caption; if set to -|figure|, it will link to the figure contents. -(The default setting is |FP|\-|list=|\x|caption|.) -\item{\texttt{FPref=caption} or \texttt{FPref=figure}}\\[\smallskipamount] -If set to |caption|, a \cs{ref}, \cs{pageref}, \cs{autoref}, or \cs{nameref} -will link to the caption; if set to |figure|, it will link to the figure contents. -(The default setting is |FP|\-|ref=|\x|figure|.) -\end{description} -\fi - -If you want to setup special options for the |FPfigure| and |FPtable| -environments you can use -\begin{quote} - |\captionsetup[FPfigure]|\marg{options}\quad\emph{and}\\ - |\captionsetup[FPtable]|\marg{options}\quad. -\end{quote} -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{% -The \package{hyperref} package\cite{hyperref} is used to handle cross -referencing commands in LaTeX to produce hypertext links in the document.} - -\NEWfeature{v3.1} -There are two options available to control the placement of hyperlink -anchors:~\footnote{These options are named after the \package{hypcap} package -which they supersede.} -\begin{description} -\item{\texttt{hypcap=true} or \texttt{hypcap=false}}\\[\smallskipamount] -If set to |true| all hyperlink anchors -- where entries in the -List of Figures, |\ref|, and |\auto|\-|ref| will link to -- are placed at -the beginning of the (floating) environment.\par -If set to |false| the hyperlink anchor is (usually) placed at the caption.\par -(The default setting is |hypcap=|\x|true|.) -\item{\texttt{hypcapspace=}\meta{amount}}\\[\smallskipamount] -Because it looks poor if the hyperlink points exactly at the top of -the figure or table, you can specify a vertical distance between -the hyperlink anchor and the (floating) environment itself, -e.g.~|hyp|\-|cap|\-|space=|\x|0pt| removes this distance.\par -(The default setting is |hyp|\-|cap|\-|space=|\x|0.5\base|\-|line|\-|skip|.) -\end{description} - -Both settings have no effect in |lst|\-|listing|s (provided by the -\package{listings} package), |long|\-|table|s (provided by the -\package{longtable} package), |super|\-|tabular|s (provided by the -\package{supertabular} package), and |x|\-|tabular|s (provided by the -\package{xtab} package), within these environments hyperlink -anchors will always be placed as if |hyp|\-|cap=|\x|true| and -|hyp|\-|cap|\-|space=|\x|0pt| would be set. - -\pagebreak[3]Please note:\nopagebreak -\begin{description} -\item{\cs{captionof}\marg{type}\csmarg{\purerm\ldots} - vs.~\cs{captionsetup}\csmarg{type=\textrm{\meta{type}}}$+$\cs{caption}\csmarg{\purerm\ldots}}% -\\[\smallskipamount] -Without \package{hyperref} loaded, both will give you identical results. -But with \package{hyperref} loaded, and with |hyp|\-|cap=|\x|true| requested, -the hyperlink anchor will be placed different. -For example: -\begin{quote} -|\begin{minipage}{\linewidth}|\\ -| |\ldots\\ -| \captionof{figure}{A figure}|\\ -|\end{minipage}| -\end{quote} -will place the hyperlink anchor at the caption. -(And if |hyp|\-|cap=|\x|true| is set, you will get a warning about this.) -But -\begin{quote} -|\begin{minipage}{\linewidth}|\\ -| \captionsetup{type=figure}|\\ -| |\ldots\\ -| \caption{A figure}|\\ -|\end{minipage}| -\end{quote} -will place the hyperlink anchor at the beginning of the |mini|\-|page|, -since |\caption|\-|setup{type=|\x|figure}| does not only set the caption type -to ``figure'' but does place a hyperlink anchor, too. - -\item{\cs{caption}\csoarg{}\csmarg{\purerm\ldots} - vs.~\cs{captionsetup}\csmarg{list=false}$+$\cs{caption}\csmarg{\purerm\ldots}}\\[\smallskipamount] -Again, without \package{hyperref} loaded, both will give you identical results. -But with \package{hyperref} loaded, the difference is in the nuances. -So for example the optional argument of |\caption| will also be written to -the |aux| file, and will be used by the |\name|\-|ref| command. -So if you choose to use |\caption| with empty optional argument, -|\name|\-|ref| will also give you an empty result. -So it's better to use |\caption|\-|setup{list=|\x|false}| if you don't -want an entry in the List of Figures or List of Tables. -\end{description} - -\pagebreak[3] -\subsection{hypcap} -\label{hypcap} -\packagedescription{% -The \package{hyp\-cap} package\cite{hypcap} offers a solution to the problem -that links to a float using \package{hyper\-ref} may anchors to the caption -rather than the beginning of the float. -Since \thispackage\ \version{3.1} already solves this problem for itself, -the \package{hypcap} package is usually not needed.} -%, at least when you use \thispackage.} - -If the \package{hyp\-cap} package is loaded additionally to the -\package{hyper\-ref} package, it takes over the control of the hyperlink -anchor placement from \thispackage, overriding the options |hyp|\-|cap=| -and |hyp|\-|cap|\-|space=|. - -So for a manual placement of hyperlink anchors -|\caption|\-|setup{type=|\x\meta{type}|}| is not sufficient anymore, -instead you need to use |\cap|\-|start| (provided by the \package{hyp\-cap} -package) for this. - -Regarding the automatically placement the \package{hypcap} package offers good -placement of hyperlink anchors for the floating environments |figure| and -|table| only. In contrast the |hypcap=|\x|true| option of \thispackage\ also -offers good placements of hyperlink anchors for -|floating|\-|figure|s (provided by the \package{float\-flt} package), -|FP|\-|figure|s \& |FPtable|s (provided by the \package{flt\-page} package), -|fig|\-|window|s (provided by the \package{pic\-in\-par} package), -|par|\-|pic|s (provided by the \package{pic\-ins} package), -|SC|\-|figure|s (provided by the \package{side\-cap} package), -|three|\-|part|\-|table|s (provided by the \package{three\-part\-table} package), -and |wrapfigure|s (provided by the \package{wrap\-fig} package).%---% -%so by loading the \package{hypcap} package additionally you will -%loose that. - -\pagebreak[3] -\subsection{listings} -\label{listings} -\packagedescription{% -The \package{listings} package\cite{listings} typesets programming code.} - -If you want to setup special options for the |lst|\-|listing| environment -you can use -\begin{quote} - |\captionsetup[lstlisting]|\marg{options}\quad. -\end{quote} - -Please note that the \package{listings} package has its very own options -for controlling the position and the skips of the caption: -|caption|\-|pos=|, |above|\-|caption|\-|skip=|, and |below|\-|caption|\-|skip=|. -\See{\package{listings} documentation for details.} -These \package{listings} options override the \package{caption}'s ones, but -can be again overwritten by |\caption|\-|setup[lst|\-|listing]{|\ldots|}|, -e.g.%~ -\begin{quote}|\caption|\-|setup[lst|\-|listing]{skip=|\x|10pt}|\quad.\end{quote} - -\pagebreak[3] -\subsection{longtable} -\label{longtable} -\packagedescription{% -The \package{longtable} package\cite{longtable} offers an environment -which behaves similar to the \texttt{tabular} environment, but the table -itself can span multiple pages.} - -If you want to setup special options for the |long|\-|table| environment -you can use -\begin{quote} - |\captionsetup[longtable]|\marg{options}\quad. -\end{quote} -These options will be executed additionally to the regular ones for -|table|. - -The |margin| and |width| settings usually override |\LT|\-|cap|\-|width|, -so you get an equal look \& feel of the captions in |table|s and -|long|\-|table|s. -But if you set |\LT|\-|cap|\-|width| to a value different than its default -$=$ |4in|, \thispackage\ will follow that. -(But |\LT|\-|cap|\-|width| will be overwritten by -|\caption|\-|setup[long|\-|table]{width=|\x\meta{value}|}|, -even if it is set to a value different than |4in|.) - -\begin{Note} -|\caption|\-|of| and |\Continued|\-|Float| do \emph{not} work for |long|\-|table|s. -Furthermore neither |\caption| nor |\caption|\-|list|\-|entry| will increment -the |table| counter here; it's incremented by the |long|\-|table| environment -instead. -\NEWfeature{v3.1} -If you need a |long|\-|table| which does not increment the |table| counter -please use the |long|\-|table*| environment (offered by the -\package{ltcaption} package which is part of \thispackage\ bundle and will be -loaded automatically). -\end{Note} - -\pagebreak[3] -\subsection{picinpar} -\label{picinpar} -\packagedescription{% -Similar to the \package{floatflt} package the \package{picinpar} -package\cite{picinpar} offers figures and tables which do not span the full -width of a page and are float around by text. -For a detailed discussion about the differences between these packages -please take a look at The \LaTeX\ Companion\cite{TLC2}.} - -\NEWfeature{v3.1} -If you want to setup special options for the |fig|\-|window| and -|tab|\-|window| environments you can use -\begin{quote} - |\captionsetup[figwindow]|\marg{options}\quad\emph{and}\\ - |\captionsetup[tabwindow]|\marg{options}\quad. -\end{quote} -These options will be executed additionally to the regular ones for -|figure| or |table|. - -\begin{Note} -The |margin| resp.~|width| setting will not be used for these figures and tables, -unless you set it explicit with |\caption|\-|setup[fig|\-|window]{|\ldots|}| or -|\caption|\-|setup[fig|\-|table]{|\ldots|}|. -\end{Note} - -\pagebreak[3] -\subsection{picins} -\label{picins} -\packagedescription{% -Similar to the \package{floatflt} and \package{picinpar} package the -\package{picins} package\cite{picins} offers figures and tables which do not -span the full width of a page and are float around by text. -For a detailed discussion about the differences between these packages -please take a look at The \LaTeX\ Companion\cite{TLC2}.} - -\NEWfeature{v3.1} -If you want to setup special options for the |par|\-|pic| environment you can use -\begin{quote} - |\captionsetup[parpic]|\marg{options}\quad. -\end{quote} -These options will be executed additionally to the regular ones for -|figure| or |table|. - -Furthermore |\pic|\-|caption[]{|\ldots|}| produce no entry in the List of Figures, -and |\pic|\-|caption*{|\ldots|}| gives an unlabeled \& unnumbered caption. - -\begin{Note} -The |margin| resp.~|width| setting will not be used for these figures and tables. -\iffalse -if |pic|\-|caption|\-|side| or |pic|\-|caption|\-|top|\-|side| is used. -The |width| setting will not be used (but the |margin| setting will) if -|pic|\-|caption|\-|out|\-|side| or |pic|\-|caption|\-|in|\-|side| is used. -\fi -But you can override this by setting it explicit with -|\caption|\-|setup[par|\-|pic]{|\ldots|}|. -\end{Note} - -If you want to have a |\pic|\-|caption| of another type as |figure|, please -do \emph{not} re-define |\@cap|\-|type| as suggested by the \package{picins} -documentation. Please use the |\pic|\-|caption|\-|type|\marg{type} command -which is offered by \thispackage\ instead, e.g.: -\begin{quote} - |\piccaptiontype{table}|\\ - |\piccaption{An example table}|\\ - |\parpic(50mm,10mm)[s]{|\ldots|}| -\end{quote} - -\pagebreak[3] -\subsection{rotating} -\label{rotating} -\packagedescription{% -The \package{rotating} package\cite{rotating} offers the floating -environments \texttt{side\-ways\-figure} and \texttt{side\-ways\-table} which -are just like normal figures and tables but rotated by 90 resp.~270 degree. -Furthermore a command \cs{rot\-caption} is offered for rotated captions only.} - -\iffalse % No, we don't do that -If you want to setup special options for the |side|\-|ways|\-|figure| and -|side|\-|ways|\-|table| environments you can use -\begin{quote} - |\captionsetup[sidewaysfigure]|\marg{options}\\ - |\captionsetup[sidewaystable]|\marg{options}\quad. -\end{quote} -These options will be executed additionally to the regular ones for -|figure| or |table|. -\fi - -The command |\rot|\-|caption| will be extended by \thispackage, so -|\rot|\-|caption*| and |\rot|\-|caption|\-|of| can be used analogous to -|\caption*| and |\caption|\-|of|. - -\pagebreak[3] -\subsection{setspace} -\label{setspace} -\packagedescription{% -The \package{setspace} package\cite{setspace} offers options and commands -to change the spacing, -e.g.\ \cs{usepackage}\x\csoarg{one\-half\-spacing}\x\csmarg{set\-space} -causes the document to be typeset in one-and-a-half spacing.} - -If the \package{setspace} package is used in conjunction with \thispackage, -the caption will be typeset with single spacing as default. This can be changed -by specifying either |font=|\x|one|\-|half|\-|spacing|, -|font=|\x|double|\-|spacing|, or |font={stretch=|\x\meta{amount}|}|. -\See{also \Ref{fonts}} - -\pagebreak[3] -\subsection{sidecap} -\label{sidecap} -\packagedescription{% -The \package{sidecap} package\cite{sidecap} offers the floating environments -\texttt{SC\-figure} and \texttt{SC\-table} which are like usual figures -and tables but the caption will be put \emph{beside} the contents.} - -If you want to setup special options for the |SCfigure| and |SCtable| -environments you can use -\begin{quote} - |\captionsetup[SCfigure]|\marg{options}\quad\emph{and}\\ - |\captionsetup[SCtable]|\marg{options}\quad. -\end{quote} -These options will be executed additionally to the regular ones for -|figure| or |table|. - -\pagebreak[3] -\begin{Note} -The \package{sidecap} package offers its own options for justification. -If set, they will override the one specified with the caption option -|jus|\-|ti|\-|fi|\-|ca|\-|tion=| for captions beside their contents. -\end{Note} - -\begin{Note} -The |margin| resp.~|width| setting will not be used for these figures and tables, -unless you set it explicit with |\caption|\-|setup[SC|\-|figure]{|\ldots|}| -or |\caption|\-|setup[SC|\-|table]{|\ldots|}|. -\end{Note} - -\medskip - -\begin{Annotation*} -Instead of using the \package{sidecap} package you can also use the more -powerful and flexible \package{floatrow} package\cite{floatrow} for typesetting -captions beside the contents. -\end{Annotation*} - -\pagebreak[3] -\subsubsection*{Undocumented features} -The \package{sidecap} package \version{1.6} has some undocumented package -options and commands which allow further customization of the side-captions: - -\pagebreak[3] -\DescribeMacro{margincaption} -The package option -\begin{quote} - |margincaption|\qquad{\small(e.g.~|\usepackage[margincaption]{sidecap}|)} -\end{quote} -causes all side-captions to be placed into the margin. - -\pagebreak[3] -\DescribeMacro{\sidecaptionvpos} -The command -\begin{quote} - |\sidecaptionvpos|\marg{float type}\marg{pos} -\end{quote} -sets the vertical position of the side-caption. \meta{pos} can be either `|t|' -(for top alignment), `|b|' (for bottom alignment), or `|c|' (for center alignment). -The default setting for |table| is `|t|', for |figure| and all other ones -defined with |\Declare|\-|Floating|\-|Environment| it's `|b|'. - -\pagebreak[3] -\subsection{subfigure} -\label{subfigure} -\packagedescription{% -The \package{subfigure} package\cite{subfigure} provides support for small or -`sub' figures and tables within a single figure or table environment. -This package is obsolete, new users should use \package{subfig} instead.} - -Since the \package{subfigure} package is obsolete it will only be supported in -a way that old documents (which have used \thispackage\ \version{1.x} during -development) should still compile as expected. - -Please use the \package{subfig} or \package{subcaption} package instead which both supports \thispackage\ -\version{3.x}. - -\See{the \package{subfig} package\cite{subfig} documentation for details.} - -\pagebreak[3] -\subsection{supertabular and xtab} -\label{supertabular} -\packagedescription{% -The \package{supertabular}\cite{supertabular} and \package{xtab}\cite{xtab} -packages offer an environment which can span multiple pages and is quite -similar to the \texttt{long\-table} environment provided by the -\package{longtable} package\cite{longtable}. -For a detailed discussion about the differences between these powerful -packages please take a look at The \LaTeX\ Companion\cite{TLC2}.} - -If you want to setup special options for the |super|\-|tabular| -resp.~|x|\-|tabular| environment you can use -\begin{quote} - |\captionsetup[supertabular]|\marg{options}\quad\emph{resp.}\\ - |\captionsetup[xtabular]|\marg{options}\quad. -\end{quote} -These options will be executed additionally to the regular ones for -|table|. - -\begin{Note} -|\Continued|\-|Float| does not work for |super|\-|tabular|s and |x|\-|tabular|s. -\end{Note} - -\pagebreak[3] -\subsection{threeparttable} -\label{threeparttable} -\packagedescription{% -The \package{threeparttable} package\cite{threeparttable} provides a scheme -for tables that have a structured note section after the table contents and -the caption. -This scheme provides an answer to the old problem of putting footnotes in -tables---by making footnotes entirely unnecessary.} - -\NEWfeature{v3.1} -If you want to setup special options for the |three|\-|part|\-|table| and -|measured|\-|figure| environments you can use -\begin{quote} - |\captionsetup[threeparttable]|\marg{options}\quad\emph{and}\\ - |\captionsetup[measuredfigure]|\marg{options}\quad. -\end{quote} -These options will be executed additionally to the regular ones for -|table| or |figure|. - -\begin{Note} -Since the caption will have the same width as the contents here, -the |margin| resp.~|width| setting will not be used for these figures and tables, -at least unless you set it explicit with -|\caption|\-|setup[three|\-|part|\-|table]{|\ldots|}| or -|\caption|\-|setup[measured|\-|figure]{|\ldots|}|. -\end{Note} - -\medskip - -\begin{Annotation*} -Instead of using the \package{threeparttable} package you can -also use the \package{floatrow} package\cite{floatrow} for this purpose. -\end{Annotation*} - -\pagebreak[3] -\subsection{wrapfig} -\label{wrapfig} -\packagedescription{% -Similar to the \package{floatflt}, the \package{picinpar}, and the -\package{picins} package the \package{wrapfig} package\cite{wrapfig} offers -figures and tables which do not span the full width of a page and are float -around by text. -For a detailed discussion about the differences between these packages -please take a look at The \LaTeX\ Companion\cite{TLC2}.} - -\NEWfeature{v3.1} -If you want to setup special options for the |wrap|\-|figure| and -|wrap|\-|table| environments you can use -\begin{quote} - |\captionsetup[wrapfigure]|\marg{options}\quad\emph{and}\\ - |\captionsetup[wraptable]|\marg{options}\quad. -\end{quote} -These options will be executed additionally to the regular ones for -|figure| or |table|. - -\begin{Note} -The |margin| resp.~|width| setting will not be used for these figures and -tables, unless you set it explicit with -|\caption|\-|setup[wrap|\-|figure]{|\ldots|}| -or |\caption|\-|setup[wrap|\-|table]{|\ldots|}|. -\end{Note} - -% --------------------------------------------------------------------------- % - -\clearpage -\section{Further reading} - -I recommend the following documents for further reading: - -\begin{itemize} -\item - The \TeX\ FAQ -- Frequently asked questions about \TeX\ and \LaTeX: - \begin{quote}\url{http://faq.tug.org/}\end{quote} - -\item - A French FAQ can be found at - \begin{quote}\url{http://www.grappa.univ-lille3.fr/FAQ-LaTeX/}\end{quote} - -\item - ``What is a minimal working example?'' from Christian Faulhammer and Ulrich Schwarz: - \begin{quote}\url{http://www.minimalbeispiel.de/mini-en.html}\end{quote} - -\item - \textsf{epslatex} from Keith Reckdahl contains many tips around - including graphics in \LaTeXe\ documents. - You will find this document in the directory - \begin{quote}\url{http://mirror.ctan.org/info/epslatex/}\end{quote} -\end{itemize} - -% --------------------------------------------------------------------------- % - -\pagebreak[3] -\section{Thanks} - -I would like to thank Katja Melzner, -Steven D. Cochran, Frank Mittelbach, Olga Lapko, -David Carlisle, Carsten Heinz, Keith Reckdahl, Markus Kohm, -Heiko Oberdiek, and Herbert Vo\ss. -Thanks a lot for all your help, ideas, patience, spirit, and support! - -Also I would like to thank -Harald Harders, -Peter L\"offler, -Peng Yu, -Alexander Zimmermann, -Matthias Pospiech, -J\"urgen Wieferink, -Christoph Bartoschek, -Uwe St\"ohr, -Ralf Stubner, -Geoff Vallis, -Florian Keiler, -J\"urgen G\"obel, -Uwe Siart, -Sang-Heon Shim, -Henrik Lundell, -David Byers, -William Asquith, -Prof.~Dr.~Dirk Hoffmann, -Frank Martini, -Danie Els, -Philipp Woock, -Fadi Semmo, -Matthias Stevens, and -Leo Liu -who all helped to make this package a better one. - -% --------------------------------------------------------------------------- % - -\clearpage\appendix -\section{Alphabetical Reference} - -%\newenvironment{Warnings}% -% {\begin{trivlist}% -% \def\Message{\pagebreak[3]\leftskip=0pt\relax\item[]\color{blue}}% -% \def\Description{\nopagebreak\par\nopagebreak\color{black}\leftskip=1.5em\nopagebreak}% -% }% -% {\color{black}\end{trivlist}} -\makeatletter -\newenvironment{Warnings}{% - \newif\ifMessage - \def\Message{% - \ifMessage\end{minipage}\par\vspace\itemsep\pagebreak[3]\fi - \begin{minipage}{\linewidth}% - \setlength\parindent{0pt}% - \setlength\parskip{\smallskipamount}% - \setlength\leftskip{0pt}% - \color{blue}% - \Messagetrue}% - \def\Description{% - \par\color{black}\leftskip=1.5em}% - \def\Or{\@testopt\@Or{or}}% - \def\@Or[##1]{% - \\{\small\color{black}\hspace{1.5em}\textit{-- ##1 --}}\\}% -}{% - \ifMessage\end{minipage}\par\fi -} -\makeatother - -\subsection{Options} -%\enlargethispage{10ex} -\newcommand\preambleoption{~% - \begingroup\def\thefootnote{\fnsymbol{footnote}}% - \footnotemark[2]% - \endgroup} -\newcommand\preambleoptiontext{% - \begingroup\def\thefootnote{\fnsymbol{footnote}}% - \footnotetext[2]{These options are only available in the preamble of the document.}% - \endgroup} - -\begin{longtable*}{lll} -Option & Short description & Section \\ -\hline -\endhead -|aboveskip| & sets the skip above caption & \ref{skips} \\ -|belowskip| & sets the skip below caption & \ref{skips} \\ -|compatibility|\preambleoption & force (non-)compatibility & \ref{compatibility} \\ -%|config| & & \ref{x} \\ -|figureposition|\preambleoption & gives a hint about the figure caption position & \ref{skips} \\ -|font|(|+|) & sets the font & \ref{fonts} \\ -|format| & sets the format & \ref{formats} \\ -\iffalse -|FPlist| & To where the list entry of a FPfigure should link? & \ref{fltpage} \\ -|FPref| & To where a |\ref| to a FPfigure should link? & \ref{fltpage} \\ -\fi -|hangindent| & sets the hang indention & \ref{margins} \\ -|hypcap| & selects `hypcap' feature & \ref{hyperref} \\ -|hypcapspace| & sets the distance between hyperlink and contents & \ref{hyperref} \\ -|indention| & sets the indention & \ref{margins} \\ -|justification| & sets the justification & \ref{justification} \\ -|labelfont|(|+|) & sets the font of the caption label & \ref{fonts} \\ -|labelformat| & sets the format of the caption label & \ref{formats} \\ -|labelsep| & sets the label separator & \ref{formats} \\ -|labelseparator| & --same as |labelsep|-- & \ref{formats} \\ -|list| & switches the entries in the List on or off & \ref{lists} \\ -|listformat| & sets the `List of Figure/Table' entry format & \ref{lists} \\ -|margin| & sets the margin & \ref{margins} \\ -|margin*| & sets the margin, but only if no width is set & \ref{margins} \\ -|maxmargin| & sets the max. margin & \ref{margins} \\ -|minmargin| & sets the min. margin & \ref{margins} \\ -|name| & sets the name of the current environment & \ref{names} \\ -|oneside| & selects the one-side mode & \ref{margins} \\ -|options| & executes the given option list & \\ -|parindent| & sets the paragraph indention & \ref{margins} \\ -|parskip| & sets the skip between paragraphs & \ref{margins} \\ -|position| & gives a hint about the caption position & \ref{skips} \\ -|singlelinecheck| & switches the single-line-check on or off & \ref{justification} \\ -%|size| & sets the size of font & \ref{x} \\ -|skip| & sets the skip between content and caption & \ref{skips} \\ -|strut| & switches the usage of |\strut|s on or off & \ref{formats} \\ -|style| & sets the caption style & \ref{style} \\ -%|style*| & sets the caption style & \ref{style} \\ -|subtype| & sets the sub-caption type & \phantom{t}--~\footnotemark \\ -|tableposition|\preambleoption & gives a hint about the table caption position & \ref{skips} \\ -|textfont|(|+|) & sets the font of the caption text & \ref{fonts} \\ -|textformat| & sets the format of the caption text & \ref{formats} \\ -|twoside| & selects the two-side mode & \ref{margins} \\ -|type| & sets the caption type \& places a hyperlink anchor & \ref{types} \\ -|type*| & sets the caption type only & \ref{types} \\ -|width| & sets a fixed caption width & \ref{margins} \\ -\end{longtable*} -\preambleoptiontext -\footnotetext{The option \texttt{subtype} is explained in the - \package{subcaption} package documentation.} - -\nopagebreak\parbox[t]{\linewidth}{% prevent from page break -\begin{Note*} - Obsolete options are not listed here. See - \Ref{caption1} and - \Ref{caption2} for a list of these options. -\end{Note*}} - -\pagebreak[3] -\subsection{Commands} - -\begin{longtable*}{lll} -Command & & Section \\ -\hline -\endhead -|\abovecaptionskip| & & \ref{skips} \\ -%|\AtBeginCaption| & & \ref{hooks} \\ -%|\AtEndCaption| & & \ref{hooks} \\ -|\belowcaptionskip| & & \ref{skips} \\ -|\caption| & & \ref{caption} \\ -|\caption*| & & \ref{caption} \\ -|\captionlistentry| & & \ref{captionlistentry} \\ -|\captionof| & & \ref{caption} \\ -|\captionof*| & & \ref{caption} \\ -|\captionsetup| & & \ref{captionsetup} \\ -|\captionsetup*| & & \ref{captionsetup} \\ -|\centerfirst| & & \ref{justification} \\ -|\centerlast| & & \ref{justification} \\ -|\clearcaptionsetup| & & \ref{captionsetup} \\ -|\clearcaptionsetup*| & & \ref{captionsetup} \\ -|\ContinuedFloat| & & \ref{ContinuedFloat} \\ -|\DeclareCaptionFont| & & \ref{declare} \\ -|\DeclareCaptionFormat| & & \ref{declare} \\ -|\DeclareCaptionFormat*| & & \ref{declare} \\ -|\DeclareCaptionJustification| & & \ref{declare} \\ -|\DeclareCaptionLabelFormat| & & \ref{declare} \\ -|\DeclareCaptionLabelSeparator| & & \ref{declare} \\ -|\DeclareCaptionLabelSeparator*| & & \ref{declare} \\ -|\DeclareCaptionListFormat| & & \ref{declare} \\ -|\DeclareCaptionOption| & & \ref{declare} \\ -|\DeclareCaptionStyle| & & \ref{declare} \\ -|\DeclareCaptionSubType| & & --~\footnotemark \\ -|\DeclareCaptionTextFormat| & & \ref{declare} \\ -|\showcaptionsetup| & & \ref{captionsetup} \\ -\end{longtable*} -\footnotetext{\cs{DeclareCaptionSubType} is explained in the - \package{subcaption} package documentation.} - -\clearpage -\subsection{Warnings} - -\begin{Warnings} - -\Message - |\caption outside box or environment.| -\Or - |\captionsetup{type=...} outside box or environment.| -\Or - |\captionsetup{type*=...} or \captionof outside box|\\ - | or environment.| -\Description - You have placed a |\caption|, |\caption|\-|of|, or - |\caption|\-|setup{type=|\x\meta{type}|}| command outside an box, group, - or environment. - You should not do this since it could cause some bad side-effects. - \par\See{\Ref{types} and \Ref{caption}} - -\Message - |\caption will not be redefined since it's already|\\ - |redefined by a document class or package which is|\\ - |unknown to the caption package.| -\Description - If \thispackage\ detects that some (unknown) document class or - package has enhanced |\caption|, it will not redefine - |\caption|, too, since this would simply kill the enhancement. - As a result some features, like |\caption*|, |\Continued|\-|Float|, - using the optional argument of |\caption|\-|setup|, - or the options |list=| and |hypcap=| will not be available.\par - If you don't care about the original enhancements but would - like to use the full range of features of \thispackage\ instead - you can give the unsupported(!) option |compatibility=|\x|false| - a try and keep your fingers crossed. - (But you will get the next warning instead.) - \par\See{\Ref{classes} and \Ref{compatibility}} - -\Message - |Forced redefinition of \caption since the|\\ - |unsupported(!) package option `compatibility=false'|\\ - |was given.| -\Description - Since you were so keen to specify the option |compatibility=|\x|false| - \thispackage\ will try to do its best to fulfill your wishes. - But depending on the document class or other packages you use that - can end in non-functional features or even errors. So keep your - fingers crossed! - \par\See{\Ref{compatibility}} - -\Message - |Hyperref support is turned off because hyperref has|\\ - |stopped early.| -\Description - If the \package{hyperref} package stops early during loading - (because of what-ever reason), the \package{hyperref} support of - \thispackage\ will not be available. As a result you could get - \package{hyperref} warnings and non-functional hyperlinks to figures - or tables. - \par\See{\Ref{hyperref}\,} - -\Message - |Ignoring optional argument [|\meta{pos}|] of \setcapwidth.| -\Description - \Thispackage\ tries to emulate the \KOMAScript\ commands regarding - captions as best as it can. But the optional argument of the - \KOMAScript\ command |\setcapwidth| is not (yet) working if you use - this package, so if you try to use it anyway, you will get this warning. - \par\See{\Ref{KOMA}} - -\Message - |Internal Warning: |\meta{warning message}|.| -\Description - You should never see this warning, either you use a package which redefines - |figure| or |table| and which is unknown to \thispackage, or this is a bug - in \thispackage. - Please send me an e-mail reporting this issue. - -\Message - |\label without proper \caption| -\Description - Regarding |\label| the floating environments behave differently than its - non-floating counterparts: The internal reference will not be generated - at the beginning of the environment, but at |\caption| instead. - So you have to place the |\label| command either just \emph{after} or - \emph{inside} the caption text (mandatory argument of |\caption|). - -\Message - |Option `|\meta{option}|' was not in list `|\meta{option list}|'.| -\Description -%\showhyphens{position} - If you try to remove a specific option of an option list, - for example with |\clear|\-|caption|\-|setup[po|\-|si|\-|tion]{table}|, - and this option can not be found inside the option list, you will - get this warning. If this is not because of a typo and you would like - to suppress this warning, use |\clear|\-|caption|\-|setup*| instead of - |\clear|\-|caption|\-|setup|. - \par\See{\Ref{captionsetup}} - -\Message - |Option list `|\meta{option list}|' undefined.| -\Description -%\showhyphens{format} - If you try to remove a specific option of an option list, - for example with |\clear|\-|caption|\-|setup[for|\-|mat]{figure}|, - and this option list is not defined (yet), you will - get this warning. If this is not because of a typo and you would like - to suppress this warning, use |\clear|\-|caption|\-|setup*| instead of - |\clear|\-|caption|\-|setup|. - \par\See{\Ref{captionsetup}} - -\Message - |Obsolete option `ignoreLTcapwidth' ignored.| -\Description - The \package{caption2} package option |ignoreLTcapwidth| will not be - emulated by this version of \thispackage, usually you can simply wipe it - away. - \par\See{\Ref{caption2} and \Ref{longtable}} - -\Message - |`ragged2e' support has been changed. Rerun to get|\\ - |captions right.| -\Description - The \package{ragged2e} package will only be loaded by \thispackage\ if it - is actually needed. - At least two \LaTeX\ runs are needed for that, so on the first run you could - get this warning. - Just compile your document again and this warning should go away. - \par\See{\Ref{justification}} - -\Message - |Reference on page |\meta{page no.}| undefined.| -\Description - If you use a |twoside| page layout, \thispackage\ needs to track the - page numbers to get the margins right. - At least two \LaTeX\ runs are needed for that, on the first run you could get - this warning. - Just compile your document again and this warning should go away. - \par\See{\Ref{margins}} - -\Message - |The caption type was already set to `|\meta{type}|'.| -\Description - This warning informs you about mixed caption options. For example if - you use a |\caption|\-|setup{type=|\x|table}| or - |\caption|\-|of{table}{|\ldots|}| inside a |figure| environment, - this would result in using both option sets for that specific caption, - the one for |figure| (specified with |\caption|\-|setup[figure]{|\ldots|}|) - and the one for |table| (specified with |\caption|\-|setup[table]{|\ldots|}|) - as well.\par - {\small(You can suppress this warning by using the starred form - |\caption|\-|setup*{type=|\x\ldots|}|.)\par} - \par\See{\Ref{captionsetup}} - -\Message - |The option `hypcap=true' will be ignored for this|\\ - |particular \caption.| -\Description - \Thispackage\ hasn't found a proper hyperlink anchor for this particular - caption, so it decides to ignore the setting |hypcap=|\x|true| (which is set by - default). As a result a link to this caption (e.g.~in the List of Figures, - or set by |\ref| or |\auto|\-|ref|) will link you to the caption of the figure - or table, not to the figure or table itself.\par - This can happen if you use |\caption|\-|of| inside a non-floating environment, - but also if you use some package which redefines |figure| or |table|, and - which is unknown to \thispackage.\par - If this is ok for you but you want to suppress this warning, simply place a - |\caption|\-|setup{hyp|\-|cap=|\x|false}| just before the |\caption| or - |\caption|\-|of| command which is causing the warning. - If this is not ok for you, you can set a hyperlink anchor with - |\caption|\-|setup{type=|\x\meta{float type}|}| for yourself. - \par\See{\Ref{hyperref}\,} - -\Message - |Unsupported document class (or package) detected,|\\ - |usage of the caption package is not recommended.| -\Description - Either the document class you use is unknown to \thispackage, or you - have included a package in your document which redefines |\@make|\-|caption| - (which is responsible for typesetting the caption internally) as well. - This means \thispackage\ will either change the design of captions in an - unwanted way, or it even refuses to work correctly at all. - \par\See{\Ref{classes} and \Ref{compatibility}} - -\Message - |Unused \captionsetup[|\meta{type}|].| -\Description - You have specified options with |\caption|\-|setup[|\meta{type}|]| which are - not used later on. - This can be because of a typo in \meta{type}, - or because you use a package which redefines |figure| or |table| and - which is unknown to \thispackage, or simply because you don't have any usage - of the environment \meta{type} after this line. - (If you want to suppress this warning you can use |\caption|\-|setup*| - instead of |\caption|\-|setup|.) - \par\See{\Ref{captionsetup}} - -\Message - |Usage of the |\meta{package}| package together with the|\\ - |caption package is strongly not recommended.|\\ - |Instead of loading the |\meta{package}| package you should|\\ - |use the caption package option `tableposition=top'.| -\Description - The package \meta{package} is dealing with caption skips as well. - Please decide which one do you actually want to use, \thispackage\ or the - other one, using both can lead to wrong skips above or below the caption. - \par\See{\Ref{skips}} - -\end{Warnings} - -\pagebreak[3] -\subsection{Errors} - -\begin{Warnings} - -\Message - |Argument of \@caption has an extra }.| -\Or - |Paragraph ended before \@caption was complete.| -\Description - If you want to typeset something special (like a tabular) as caption, - you need to give an optional argument to |\caption| resp.~|\caption|\-|of| - for the List of Figures resp.~List of Tables, too, even if you don't - use such list. - \par\See{\Ref{caption}, \Ref{lists}, and \Ref{hyperref}\,} - -\Message - |\caption outside float.| -\Description - You have placed a |\caption| command outside a floating environment, or - a |long|\-|table| or |wrap|\-|figure|. - If this is what you want to, please use either - |\caption|\-|setup{type=|\x\meta{type}|}| $+$ |\caption| or - |\caption|\-|of|. - \par\See{\Ref{caption}} - -\Message - |\ContinuedFloat outside float.| -\Description - You have placed a |\Continued|\-|Float| command outside a floating - environment. % or |long|\-|table|. - If this is what you want to, please use the combination - |\caption|\-|setup{type=|\x\meta{type}|}| $+$ |\Continued|\-|Float|.\par - Please note that |\Continued|\-|Float| inside a |long|\-|table| is not - working, but maybe using the |long|\-|table*| environment, which - typesets a |long|\-|table| without incrementing the |table| counter, - if sufficient for you. - \par\See{\Ref{ContinuedFloat} and \Ref{longtable}} - -\Message - |Continued `|\meta{type}|' after `|\meta{type}|'.| -\Description - Continued figures or tables are not allowed to be interrupted by a floating - environment (or |long|\-|table|) of another type, - e.g.~a table between a figure and a continued figure. - \par\See{\Ref{ContinuedFloat}} - -\Message - |For a successful cooperation we need at least version|\\ - |`|\meta{date}|' of package |\meta{package}|, but only version|\\ - |`|\meta{old-date}|' is available.| -\Description - \Thispackage\ does not work with such an outdated package, please update it - to a more recent version, at least to the one requested. - -\Message - |Internal Error: |\meta{error message}|.| -\Description - You should never see this error. - Please send me an e-mail reporting this issue. - -\Message - |No float type '|\meta{type}|' defined.| -\Description - The \meta{type} you have specified in |\caption|\-|setup{type=|\x\meta{type}|}|, - |\caption|\-|of|\marg{type}, or |\Declare|\-|Caption|\-|Sub|\-|Type| is - not defined. - \meta{type} should be either `\texttt{figure}' or `\texttt{table}', or - any other floating environment defined with - |\Declare|\-|Floating|\-|Environment| offered by the \package{newfloat} package, - |\new|\-|float| offered by the \package{float} package\cite{float}, or - |\Declare|\-|New|\-|Float|\-|Type| offered by the \package{floatrow} package\cite{floatrow}. - -\Message - |Not allowed in longtable* environment.| -\Description - The usage of |\caption| is not allowed inside the |long|\-|table*| environment. - Please use either |\caption*| for a caption without label or use the regular - |long|\-|table| environment instead. - -\Message - |Not available in compatibility mode.| -\Description - The feature required is not supported in compatibility mode. - `compatibility mode' means that \thispackage\ has detected either an - incompatible document class or an incompatible package which also - extents the |\caption| command. Leaving the original extension intact, - some features of \thispackage\ are not supported. - \par\See{\Ref{compatibility}} - -\Message - |Only one \caption can be placed in this environment.| -\Description - Inside the environments offered by the \package{fltpage} and \package{sidecap} - package only \emph{one} caption can be placed. (This is due implementation design.) - -\Message - |Option clash for package caption.| -\Or[but sometimes also] - |Missing \begin{document}.| -\Description - \Thispackage\ has already been loaded by some other \LaTeX\ package, - so you can't do that again specifying different options. - A candidate causing this could be the \package{subfig} package; if this is - the case, please load \thispackage\ \emph{before} the \package{subfig} - package or specify the option |caption=|\x|false| while loading the - \package{subfig} package. - \par\See{the \package{subfig} package\cite{subfig} documentation} - -\Message - |Paragraph ended before \caption@makecurrent was complete.| -\Or - |Paragraph ended before \caption@prepareanchor was complete.| -\Description - If you want to typeset multi-paragraph captions, you need to give an - optional argument to |\caption| resp.~|\caption|\-|of| for the List of - Figures resp.~List of Tables, too, even if you don't use such list. - \par\See{\Ref{caption}, \Ref{lists}, and \Ref{hyperref}\,} - -\Message - |Something's wrong--perhaps a missing \caption|\\ - |in the last figure or table.| -\Description - It seems that you have used a |\sub|\-|caption| command (or a different one - which has typeset a sub-caption) without a corresponding |\caption| command. - This is not supported. - -\Message - |The option `labelsep=|\meta{name}|' does not work|\\ - |with `format=hang'.| -\Or - |The option `labelsep=|\meta{name}|' does not work|\\ - |with \setcaphanging (which is set by default).| -\Description - A caption label separator which contains a |\\| command (like - |labelsep=|\x|newline|) can not be combined with a hanging caption format - (like |format=|\x|hang|). - Please select either another caption label separator - (e.g.~|labelsep=|\x|colon|) or another caption format - (e.g.~|format=|\x|plain|). - \par\See{\Ref{formats} resp.~\Ref{KOMA}} - -\Message - |The package option `caption=false' is obsolete.|\\ - |Please pass this option to the subfig package instead|\\ - |and do *not* load the caption package anymore.| -\Description - You have specified the option |caption=|\x|false|. This used to be a workaround - for not using the whole \package{caption} package (leaving the caption stuff - offered by the document class or other packages intact), but keeping the - \package{subfig} package working. This mechanism is obsolete and not offered - anymore, please pass this option to the \package{subfig} package instead and - do not load \thispackage\ anymore. - \par\See{the \package{subfig} package\cite{subfig} documentation} - -\Message - |Undefined boolean value `|\meta{value}|'.| -\Description - You tried to set a boolean option (like |singlelinecheck=| or |hypcap=|) - with an improper value. Only |false|, |no|, |off|, |0| or |true|, |yes|, - |on|, |1| is allowed here. - -\Message - |Undefined format `|\meta{name}|'.| -\Description - You tried to set a caption format which does not exists. - Maybe a typo!? - \par\See{\Ref{formats}} - -\Message - |Undefined label format `|\meta{name}|'.| -\Description - You tried to set a caption label format which does not exists. - Maybe a typo!? - \par\See{\Ref{formats}} - -\Message - |Undefined label separator `|\meta{name}|'.| -\Description - You tried to set a caption label separator which does not exists. - Maybe a typo!? - \par\See{\Ref{formats}} - -\Message - |Undefined list format `|\meta{name}|'.| -\Description - You tried to set a caption list-of format which does not exists. - Maybe a typo!? - \par\See{\Ref{lists}} - -\Message - |Undefined position `|\meta{name}|'.| -\Description - You tried to set a caption position with an improper value. - Maybe a typo!? - \par\See{\Ref{skips}} - -\Message - |Undefined style `|\meta{name}|'.| -\Description - You tried to set a caption style which does not exists. - Maybe a typo!? - \par\See{\Ref{style}} - -\Message - |Usage of the `position' option is incompatible|\\ - |to the `|\meta{package}|' package.| -\Description -% (ftcap,nonfloat,topcapt) - The given package is dealing with caption skips as well. - Please decide which one do you actually want to use: The |position=| option - of \thispackage\ or the mechanism of the other one; using both this way - would lead to wrong skips above or below the caption and is therefore - not supported. - \par\See{\Ref{skips}} - -\Message - |Undefined text format `|\meta{name}|'.| -\Description - You tried to set a caption text format which does not exists. - Maybe a typo!? - \par\See{\Ref{formats}} - -\Message - |You can't use both, the (obsolete) caption2 *and*|\\ - |the (current) caption package.| -\Description - This error message says it all, you simply can't do that. - Please use only \thispackage. - \par\See{\Ref{caption2}} - -\end{Warnings} - -% --------------------------------------------------------------------------- % - -\clearpage -\section{Version history} -\label{history} - -The version $1.0$ was written in 1994 and was offering a handful of options -to customize the look \& feel of the captions. -Furthermore this version already supported the \package{rotating} and -\package{subfigure} packages. -Version $1.1$ introduced the |center|\-|last| option; -version $1.2$ added the support of the \package{float} package. -Version $1,3$ offered a better support of the \package{subfigure} package, -while version $1.4$ came with the new option |nooneline|. - -The \package{caption2} package $2.0$ was an experimental side-version of -the regular \package{caption} package. It was made public as beta test version -without proper documentation in 1995 because of the strong demand for new -features and adaptations to additional packages like the \package{longtable} -package. -Furthermore it offered a revised support of the \package{subfigure} package. -(An improved version $2.1$ was offered in 2002.) - -In 2003 I finally found some time, so a new regular release $3.0$ -of the \package{caption} package could be build in cooperation with -Frank Mittelbach and Steven Cochran. -It was released in December 2003 and superseded the neglected -\package{caption2} package. -Main parts were re-written and it provided a complete re-work of -the user interface. -Furthermore it supported the \package{hyperref}, \package{hypcap}, -\package{listings}, \package{sidecap}, and \package{supertabular} packages -additionally. - -While all the previous versions were designed for usage with the standard -\LaTeX\ document classes \class{article}, \class{report}, and \class{book}, -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{french} Babel option, -the \package{frenchle} \& \package{frenchpro} packages, -and the \package{floatflt}, \package{fltpage}, \package{picinpar}, -\package{picins}, \package{setspace}, \package{threeparttable}, -and \package{wrapfig} packages. -New options and commands were introduced as well, among other things -|font+|, |figure|\-|within| \& |table|\-|within|, -|list| \& |list|\-|format|, |max|\-|margin| \& |min|\-|margin|, -|\caption|\-|list|\-|entry|, |\Declare|\-|Caption|\-|List|\-|Format|. -Further benefits are the new compatibility check \see*{\Ref{compatibility}}, -the new ``hypcap'' feature \see*{\Ref{hyperref}\,}, and the sub-caption -feature \see*{\package{subcaption} package documentation}. - -% --------------------------------------------------------------------------- % - -\clearpage -\section{Compatibility to older versions} - -\subsection{caption v\texorpdfstring{$1.x$}{1.x}} -\label{caption1} - -This version of \thispackage\ still supports the old options -and commands provided by the version $1.0$ to $1.4$ of this package. -So there shouldn't occur any problems compiling old documents, but please -don't mix old options and commands with the new ones. This isn't supported -and can cause ugly side effects. - -Here comes a short oversight of the obsolete options and how -they have been replaced within this version of \thispackage: - -\begin{center}\small -\begin{tabular}{ll} -\package{caption} \version{1.x} & \package{caption} \version{3.x}\\ -\hline -%\endhead -|normal| & |format=plain|\\ -|hang| & |format=hang|\\ -|isu| & |format=hang|\\ -|center| & |justification=centering|\\ -|centerlast| & |justification=centerlast|\\ -|nooneline| & |singlelinecheck=off|\\ -|scriptsize| & |font=scriptsize|\\ -|footnotesize| & |font=footnotesize|\\ -|small| & |font=small|\\ -|normalsize| & |font=normalsize|\\ -|large| & |font=large|\\ -|Large| & |font=Large|\\ -|up| & |labelfont=up|\\ -|it| & |labelfont=it|\\ -|sl| & |labelfont=sl|\\ -|sc| & |labelfont=sc|\\ -|md| & |labelfont=md|\\ -|bf| & |labelfont=bf|\\ -|rm| & |labelfont=rm|\\ -|sf| & |labelfont=sf|\\ -|tt| & |labelfont=tt|\\ -\end{tabular} -\end{center} - -Beside the options for setting up the desired font there were also -the commands |\caption|\-|size| resp.~|\caption|\-|font| and -|\caption|\-|label|\-|font| who could be redefined with -|\re|\-|new|\-|command| and allowed an alternate and more flexible way to -change the font used for captions. -This mechanism was replaced by the commands -\begin{quote} - |\DeclareCaptionFont{|\ldots|}{|\ldots|}|\qquad and\\ - |\captionsetup{font=|\ldots|,labelfont=|\ldots|}|\qquad. -\end{quote} -\SeeUserDefined - -Setting the margin for captions was done in \version{1.x} with -\begin{quote} - |\setlength{\captionmargin}{|\ldots|}|\quad. -\end{quote} -This was replaced by -\begin{quote} - |\captionsetup{margin=|\ldots|}|\qquad. -\end{quote} -\See{\Ref{margins}} - -For example the old-style code -\begin{quote} - |\usepackage[hang,bf]{caption}|\\ - |\renewcommand\captionfont{\small\sffamily}|\\ - |\setlength\captionmargin{10pt}| -\end{quote} -will still work fine, but should be written today as -\begin{quote} - |\usepackage[format=hang,labelfont=bf,font={small,sf},|\\ - | margin=10pt]{caption}| -\end{quote} -or -\begin{quote} - |\usepackage{caption}|\\ - |\captionsetup{format=hang,labelfont=bf,font={small,sf},|\\ - | margin=10pt}|\qquad. -\end{quote} - -The quite exotic option |ruled| which allowed a partial usage of -the caption settings for |ruled| floats defined with the -\package{float} package will be emulated by this version of the -caption package, too. -But using this option is not recommended anymore since this -version of \thispackage\ offers a more flexible way -for changing the captions of these floating environments: -\begin{quote} - |\DeclareCaptionStyle{ruled}{|\ldots|}| -\end{quote} -resp. -\begin{quote} - |\captionsetup[ruled]{|\ldots|}|\qquad. -\end{quote} -\SeeUserDefined[, \Ref{captionsetup}, and \Ref{float}] - -\subsection{caption2 v\texorpdfstring{$2.x$}{2.x}} -\label{caption2} - -Although they do very similar stuff, the packages \package{caption} and -its experimental and now obsolete variant \package{caption2} have a -very different implementation design. -Therefore a full compatibility could not be offered. -For that reason you will still find a file called |caption2.sty| in -this package distribution, so old documents using the \package{caption2} -package will still compile fine. - -Newly created documents should use the actual version of -\thispackage\ instead. In most cases it's sufficient to replace the command -\begin{quote} - |\usepackage[...]{caption2}| -\end{quote} -by -\begin{quote} - |\usepackage[...]{caption}|\qquad. -\end{quote} -But some options and commands will not be emulated, so you can get -error messages afterwards. This section will hopefully help you removing -these errors. If you have problems migrating from \package{caption2} -to \package{caption} please don't hesitate to send me an e-mail asking -for help. - -In addition to the obsolete options shown in the last section -these ones will be emulated, too: - -\begin{center}\small -\begin{tabular}{ll} -\package{caption2} \version{2.x} & \package{caption} \version{3.x}\\ -\hline -%\endhead -|flushleft| & |justification=raggedright|\\ -|flushright| & |justification=raggedleft|\\ -|oneline| & |singlelinecheck=on|\\ -\end{tabular} -\end{center} - -Setting the margin for captions was done in \version{2.x} with -\begin{quote}\leavevmode\hbox{% - |\setcaptionmargin{|\ldots|}| resp. - |\setcaptionwidth{|\ldots|}|\quad. -}\end{quote} -This was replaced by -\begin{quote}\leavevmode\hbox{% - |\captionsetup{margin=|\ldots|}| resp. - |\captionsetup{width=|\ldots|}|\quad. -}\end{quote} -\See{\Ref{margins}} - -Setting an indention was done in \version{2.x} with -\begin{quote} - |\captionstyle{indent}|\\ - |\setlength\captionindent{|\ldots|}|\quad. -\end{quote} -\pagebreak[3] -This is now done with -\nopagebreak[3] -\begin{quote} - |\captionsetup{format=plain,indention=|\ldots|}|\quad. -\end{quote} - -The so-called single-line-check was controlled by the commands -|\oneline|\-|captions|\-|false| (for switching the check off) and -|\oneline|\-|captions|\-|true| (for switching the check on). -This was replaced by -|\caption|\-|setup{single|\-|line|\-|check=|\x|off}| -resp. -|\caption|\-|setup{single|\-|line|\-|check=|\x|on}|\quad. -\See{\Ref{justification}} - -The commands -\begin{quote} - |\captionlabeldelim|, |\captionlabelsep|, |\captionstyle|,\\ - |\defcaptionstyle|, |\newcaptionstyle|, and |\renewcaptionstyle| -\end{quote} -do not have a simple replacement and therefore will not be emulated -by this version of \thispackage. (So using them will -cause error messages.) Rewriting such code is not always easy and -straight-ahead, but by conscientious reading of this manual you should -be able to find appropriate options and commands instead. - -\iffalse -... (some examples) -\fi - -The \version{2.x} option |ignore|\-|LT|\-|cap|\-|width| do not have a -replacement, too. -But in most cases you can simply drop using that option because -in this version of \thispackage\ the value of |\LT|\-|cap|\-|width| -will be ignored anyway (unless you set it to a different value than the -default one which is |4in|). -\See{\Ref{longtable}} - -\subsection{caption v\texorpdfstring{$3.0$}{3.0}} -\label{caption3} - -%\NEWdescription{v3.1} -\Thispackage\ \version{3.0} did not support any document classes -other than the standard \LaTeX\ ones: \class{article}, \class{report}, -and \class{book}. -Therefore the default settings used to be fixed, but now \thispackage{} -supports more classes, therefore they are now set in dependence on the -document class used. - -For example: While in \version{3.0} the default caption -|jus|\-|ti|\-|fi|\-|ca|\-|tion| used to be always |jus|\-|ti|\-|fied|, -it's now still |jus|\-|ti|\-|fied| when using one of the standard document -classes, but |ragged|\-|right| will be used as default format when used -with the \class{beamer} document class. - -%An easy way to select the `old' defaults---if desired---is using the option -An easy way to select the `old' defaults is using the option -|style=base| when loading \thispackage\ (or later on using |\caption|\-|setup|). - -\medskip - -Another new feature is the automatic check for compatibility; if an -incompatibility will be found, a warning message will be issued and if a strong -incompatibility was found some features of \thispackage\ will be disabled. -Please note that only this check was added to \thispackage, so if you get -such warning message, the previous versions of \thispackage\ were incompatible -as well, but did not issued such warning, they were ``only'' having -side-effects or causing problems. -So these warnings only say that some bad side effects or problems could -happen, but not that they actually will happen. -Anyway, if you use \thispackage\ in such circumstances, -you should use it with care. - -\bigskip - -\begin{Note*} -\Thispackage\ \version{3.0} offered the option |caption=|\x|false|, -which used to be a workaround for not using the whole \package{caption} package -(leaving the caption stuff offered by the document class or other packages -intact), but keeping the \package{subfig} package\cite{subfig} working. -This mechanism is obsolete and not offered anymore, please pass this option -to the \package{subfig} package instead and do not load \thispackage\ anymore. -%\par\See{the \package{subfig} package documentation} -\end{Note*} - -% --------------------------------------------------------------------------- % - -\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{\SetCaptionFallback} -The command -\begin{quote} - |\SetCaptionFallback|\marg{option}\marg{fallback value} -\end{quote} -changes the fallback value for the option \meta{option}, for example: -\begin{quote} - |\SetCaptionFallback{labelformat}{simple}| -\end{quote} -Currently only the pre-defined label format `original' uses a fallback -value when |\fnum@|\meta{environment} is not defined for the current (floating) -environment. - -\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}|\AtCaptionPackage|\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 have little effect here. - -\DescribeMacro{\AfterCaptionPackage} -The additional hook -\begin{quote}|\AfterCaptionPackage|\marg{code}\end{quote} -is offered to authors of adaption files as well. -The \meta{code} inside the hook will be executed at the very end of the -\package{caption} package. - -% --------------------------------------------------------------------------- % - -\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} - Frank Mittelbach and Michel Goossens:\\ - \newblock {\em The {\LaTeX} Companion (2nd.~Ed.)},\\ - \newblock Addison-Wesley, 2004. - - \bibitem{beamer} - Till Tantau:\\ - \href{http://www.ctan.org/pkg/beamer}% - {\emph{User Guide to the Beamer Class, Version 3.07}},\\ - March 11, 2007 - - \bibitem{KOMAScript} - Markus Kohm \& Jens-Uwe-Morawski:\\ - \href{http://www.ctan.org/pkg/koma-script}% - {\emph{KOMA-Script -- a versatile \LaTeXe\ bundle}},\\ - 2007-01-09 - - \bibitem{NTG} - Victor Eijkhout:\\ - \href{http://www.ctan.org/pkg/ntgclass}% - {\emph{An introduction to the Dutch \LaTeX\ document classes}},\\ - 3 September 1989 - - \bibitem{algorithms} - Rog\'erio Brito:\\ - \href{http://www.ctan.org/pkg/algorithms}% - {\emph{Algorithms}},\\ - June 2, 2006 - -\iffalse - \bibitem{algorithm2e} - Christophe Fiorio:\\ - \href{http://www.ctan.org/pkg/algorithm2e}% - {\emph{algorithm2e.sty -- package for algorithms}},\\ - March 11, 2007 -\fi - - \bibitem{float} - Anselm Lingnau:\\ - \href{http://www.ctan.org/pkg/float}% - {\emph{An Improved Environment for Floats}},\\ - 2001/11/08 - - \bibitem{floatflt} - Mats Dahlgren:\\ - \href{http://www.ctan.org/pkg/floatflt}% - {\emph{Welcome to the floatflt package}},\\ - 1998/06/05 - - \bibitem{floatrow} - Olga Lapko:\\ - \href{http://www.ctan.org/pkg/floatrow}% - {\emph{The floatrow package documentation}},\\ - 2007/12/24 - - \bibitem{fltpage} - Sebastian Gross:\\ - \href{http://www.ctan.org/pkg/fltpage}% - {\emph{Welcome to the beta test of fltpage package!}},\\ - 1998/11/13 - - \bibitem{hyperref} - Sebastian Rahtz \& Heiko Oberdiek:\\ - \href{http://www.ctan.org/pkg/hyperref}% - {\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}},\\ - 2007/04/09 - - \bibitem{listings} - Carsten Heinz \& Brooks Moses:\\ - \href{http://www.ctan.org/pkg/listings}% - {\emph{The Listings Package}},\\ - 2007/02/22 - - \bibitem{longtable} - David Carlisle:\\ - \href{http://www.ctan.org/pkg/longtable}% - {\emph{The longtable package}},\\ - 2004/02/01 - - \bibitem{picinpar} - Friedhelm Sowa:\\ - \href{http://www.ctan.org/pkg/picinpar}% - {\emph{Pictures in Paragraphs}},\\ - July 13, 1993 - - \bibitem{picins} - Joachim Bleser and Edmund Lang:\\ - \href{http://www.ctan.org/pkg/picins}% - {\emph{PicIns-Benutzerhandbuch Version 3.0}},\\ - September~1992 - - \bibitem{rotating} - Sebastian Rahtz and Leonor Barroca:\\ - \href{http://www.ctan.org/pkg/rotating}% - {\emph{A style option for rotated objects in \LaTeX}},\\ - 1997/09/26 - - \bibitem{setspace} - Erica M. S. Harris \& Geoffrey Tobin:\\ - \href{http://www.ctan.org/pkg/setspace}% - {\emph{LaTeX Document Package ``setspace''}},\\ - 1 December 2000 - - \bibitem{sidecap} - Rolf Niepraschk \& Hubert G\"a\ss lein:\\ - \href{http://www.ctan.org/pkg/sidecap}% - {\emph{The sidecap package}},\\ - 2003/06/06 - - \bibitem{subfigure} - Steven D. Cochran:\\ - \href{http://www.ctan.org/pkg/subfigure}% - {\emph{The subfigure package}},\\ - 2002/07/02 - - \bibitem{subfig} - Steven D. Cochran:\\ - \href{http://www.ctan.org/pkg/subfig}% - {\emph{The subfig package}},\\ - 2005/07/05 - - \bibitem{supertabular} - Johannes Braams and Theo Jurriens:\\ - \href{http://www.ctan.org/pkg/supertabular}% - {\emph{The supertabular environment}},\\ - 2002/07/19 - - \bibitem{threeparttable} - Donald Arseneau:\\ - \href{http://www.ctan.org/pkg/threeparttable}% - {\emph{Three part tables: title, tabular environment, notes}},\\ - 2003/06/13 - - \bibitem{wrapfig} - Donald Arseneau:\\ - \href{http://www.ctan.org/pkg/wrapfig}% - {\emph{WRAPFIG.STY ver 3.6}},\\ - 2003/01/31 - - \bibitem{xtab} - Peter Wilson:\\ - \href{http://www.ctan.org/pkg/xtab}% - {\emph{The xtab package}},\\ - 2004/05/24 - -\end{thebibliography} - -% --------------------------------------------------------------------------- % - -\end{document} - |