diff options
author | Karl Berry <karl@freefriends.org> | 2011-11-06 23:24:43 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2011-11-06 23:24:43 +0000 |
commit | e678d3b58e25f99b6c7aa3e828add9502768371c (patch) | |
tree | 5ce7df892e6657936807337df43e08ea66cba374 /Master/texmf-dist/source/latex/caption/caption-eng.tex | |
parent | 91348b19948d3b43f8e39cdd834970482dd5f062 (diff) |
caption (6nov11)
git-svn-id: svn://tug.org/texlive/trunk@24525 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/caption/caption-eng.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/caption/caption-eng.tex | 4273 |
1 files changed, 4273 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/caption/caption-eng.tex b/Master/texmf-dist/source/latex/caption/caption-eng.tex new file mode 100644 index 00000000000..45efb2896a6 --- /dev/null +++ b/Master/texmf-dist/source/latex/caption/caption-eng.tex @@ -0,0 +1,4273 @@ +% +% This is file `caption-eng.tex'. +% +% Copyright (C) 1994-2011 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, caption2.dtx, +% caption3.dtx, bicaption.dtx, ltcaption.dtx, subcaption.dtx, and newfloat.dtx, +% the derived files caption.sty, caption2.sty, caption3.sty, +% bicaption.sty, ltcaption.sty, subcaption.sty, and newfloat.sty, +% and the user manuals caption-deu.tex, caption-eng.tex, and caption-rus.tex. +% +\NeedsTeXFormat{LaTeX2e}[1994/12/01] +\ProvidesFile{caption-eng.tex}[2011/11/02 v3.2 The caption package] +\hbadness=9999 \newcount\hbadness \hfuzz=20pt % Make TeX shut up. +%\errorcontextlines=3 + +\documentclass[USenglish]{ltxdoc} +\usepackage{fixltx2e} +\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} +\IfFileExists{test/tlc2/cat.eps}{\graphicspath{{test/tlc2/}}}{}% + +\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 +\newcommand*\Ref{\@ifstar{\@Ref\ref}{\@Ref\autoref}} +\newcommand*\@Ref[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 +\GetFileInfo{caption.sty} + +\title{Customizing captions of floating environments + using the caption package\texorpdfstring{\thanks{% + This package has version number \fileversion, + last revised \filedate.}}{}} +\author{Axel Sommerfeldt\\ + \href{mailto:axel.sommerfeldt@f-m.fm}{\texttt{axel.sommerfeldt@f-m.fm}}} +\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 just 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*{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[default] + The caption label will be typeset as specified by the document class, + usually this means the name and the number (like \texttt{simple}). + (This is the default behaviour.) + + \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=plain,justification=centerlast| + \end{quote} + \captionsetup{skip=0pt} + \example{format=plain,justification=centerlast}{\exampletext} +\end{Example} + +\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=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=bf,textfont=it| + \end{quote} + \captionsetup{skip=0pt} + \example{labelfont=bf,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} + \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{Document classes \& Babel support} +\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. + +\subsection{frenchb babel option} +\label{frenchb} + +If you use the \package{frenchb} option of the \package{babel} package +with one of the three standard \LaTeX{} classes (or a one derived from them) +the default |label|\-|sep=| will be set to |\Caption|\-|Sep|\-|a|\-|ra|\-|tor| +(offered by \package{frenchb}), overriding the default value set by the +document class. +So redefining |\Caption|\-|Sep|\-|a|\-|ra|\-|tor| will still work, unless you +don't select a different |label|\-|sep=| than the default one. + +\INFO* +Please load \thispackage\ \emph{after} the \package{babel} package. + +\subsection{frenchle and frenchpro packages} +\label{frenchpro} + +If you use the \package{frenchle} or \package{frenchpro} package, +the default |label|\-|sep=| will be set to |\caption|\-|sep|\-|a|\-|ra|\-|tor| +(offered by \package{frenchle/pro}) plus \cs{space}, overriding the default +value set by the document class. +So redefining |\caption|\-|sep|\-|a|\-|ra|\-|tor| will still work, unless you +don't select a different |label|\-|sep=| than the default one. + +Furthermore the default |text|\-|font=| will be set to |text|\-|font=|\x|it|, +since this emulates the default setting of |\caption|\-|font| defined by the +\package{frenchle} or \package{frenchpro} package. +%If you redefine |\captionfont| after loading the \package{frenchle} or +%\package{frenchpro} package, this redefinition gets lost. +Please note that the command |\caption|\-|font| is used by the +\package{caption} package internally for a different purpose, +so you should not change it (anymore). + +The command |\un|\-|numbered|\-|captions|\marg{figure \emph{or} table} will +still work, but only unless you don't select a different |label|\-|format=| +than the default one. + +\INFO* +Please load \thispackage\ \emph{after} the \package{frenchle} +or \package{frenchpro} package. + +% --------------------------------------------------------------------------- % + +\clearpage +\section{Package support} +\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.} + +\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} + +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{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{ftp://tug.ctan.org/pub/tex/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, and +Matthias Stevens +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} \\ +|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} \\ +|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}} + +\iffalse +\Message + |Possibly superfluous \restylefloat{|\meta{type}|} detected.|\\ + |If you think that this warning is unjustified,|\\ + |you can switch it off using the caption package|\\ + |option `restylefloatcheck=off'.| +\Description + \TODO +\fi + +\Message + |`ragged2e' package not loaded, therefore|\\ + |substituting \raggedright for \RaggedRight.| +\Description + The caption option |justification=|\x|RaggedRight| is only full functional + if you have the \package{ragged2e} package installed in your \TeX\ system. + If not, you will get this warning, and |justification=|\x|RaggedRight| + will be treated as |justification=|\x|raggedright|. + \par\See{\Ref{justification}} + +\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{frenchb} 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|\\ +%|anne| & |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 +\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://tug.ctan.org/tex-archive/macros/latex/contrib/beamer/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/beamer/doc/beameruserguide.pdf}% + {\emph{User Guide to the Beamer Class, Version 3.07}},\\ + March 11, 2007 + + \bibitem{KOMAScript} + Markus Kohm \& Jens-Uwe-Morawski:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/koma-script/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/koma-script/scrguien.pdf}% + {\emph{KOMA-Script -- a versatile \LaTeXe\ bundle}},\\ + 2007-01-09 + + \bibitem{NTG} + Victor Eijkhout:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/ntgclass/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/ntgclass/classdoc.pdf}% + {\emph{An introduction to the Dutch \LaTeX\ document classes}},\\ + 3 September 1989 + + \bibitem{algorithms} + Rog\'erio Brito:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/algorithms/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/algorithms/algorithms.pdf}% + {\emph{Algorithms}},\\ + June 2, 2006 + +\iffalse + \bibitem{algorithm2e} + Christophe Fiorio:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/algorithm2e/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/algorithm2e/algorithm2e.pdf}% + {\emph{algorithm2e.sty -- package for algorithms}},\\ + March 11, 2007 +\fi + + \bibitem{float} + Anselm Lingnau:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/float/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/float/float.pdf}% + {\emph{An Improved Environment for Floats}},\\ + 2001/11/08 + + \bibitem{floatflt} + Mats Dahlgren:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/floatflt/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/floatflt/floatflt.pdf}% + {\emph{Welcome to the floatflt package}},\\ + 1998/06/05 + + \bibitem{floatrow} + Olga Lapko:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/floatrow/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/floatrow/floatrow.pdf}% + {\emph{The floatrow package documentation}},\\ + 2007/12/24 + + \bibitem{fltpage} + Sebastian Gross:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/fltpage/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/fltpage/fltpage.pdf}% + {\emph{Welcome to the beta test of fltpage package!}},\\ + 1998/11/13 + + \bibitem{hyperref} + Sebastian Rahtz \& Heiko Oberdiek:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/hyperref/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/hyperref/hyperref.pdf}% + {\emph{Hypertext marks in \LaTeX}},\\ + November 12, 2007 + + \bibitem{hypcap} + Heiko Oberdiek:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/oberdiek/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/oberdiek/hypcap.pdf}% + {\emph{The hypcap package -- Adjusting anchors of captions}},\\ + 2007/04/09 + + \bibitem{listings} + Carsten Heinz \& Brooks Moses:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/listings/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/listings/listings.pdf}% + {\emph{The Listings Package}},\\ + 2007/02/22 + + \bibitem{longtable} + David Carlisle:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/required/tools/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/required/tools/longtable.pdf}% + {\emph{The longtable package}},\\ + 2004/02/01 + + \bibitem{picinpar} + Friedhelm Sowa:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex209/contrib/picinpar/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex209/contrib/picinpar/}% + {\emph{Pictures in Paragraphs}},\\ + July 13, 1993 + + \bibitem{picins} + Joachim Bleser and Edmund Lang:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex209/contrib/picins/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex209/contrib/picins/mpic.dvi}% + {\emph{PicIns-Benutzerhandbuch Version 3.0}},\\ + September~1992 + + \bibitem{rotating} + Sebastian Rahtz and Leonor Barroca:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/rotating/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/rotating/}% + {\emph{A style option for rotated objects in \LaTeX}},\\ + 1997/09/26 + + \bibitem{setspace} + Erica M. S. Harris \& Geoffrey Tobin:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/setspace/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/setspace/}% + {\emph{LaTeX Document Package ``setspace''}},\\ + 1 December 2000 + + \bibitem{sidecap} + Rolf Niepraschk \& Hubert G\"a\ss lein:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/sidecap/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/sidecap/sidecap.pdf}% + {\emph{The sidecap package}},\\ + 2003/06/06 + + \bibitem{subfigure} + Steven D. Cochran:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/subfigure/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/subfigure/subfigure.pdf}% + {\emph{The subfigure package}},\\ + 2002/07/02 + + \bibitem{subfig} + Steven D. Cochran:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/subfig/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/subfig/subfig.pdf}% + {\emph{The subfig package}},\\ + 2005/07/05 + + \bibitem{supertabular} + Johannes Braams and Theo Jurriens:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/supertabular/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/supertabular/supertabular.pdf}% + {\emph{The supertabular environment}},\\ + 2002/07/19 + + \bibitem{threeparttable} + Donald Arseneau:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/misc/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/misc/threeparttable.sty}% + {\emph{Three part tables: title, tabular environment, notes}},\\ + 2003/06/13 + + \bibitem{wrapfig} + Donald Arseneau:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/wrapfig/}% +% \href{ftp://tug.ctan.org/tex-archive/macros/latex/contrib/wrapfig/wrapfig.sty}% + {\emph{WRAPFIG.STY ver 3.6}},\\ + 2003/01/31 + + \bibitem{xtab} + Peter Wilson:\\ + \href{http://tug.ctan.org/tex-archive/macros/latex/contrib/xtab/}% + {\emph{The xtab package}},\\ + 2004/05/24 + +\end{thebibliography} + +% --------------------------------------------------------------------------- % + +\end{document} |