summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/capt-of/capt-of.dtx
blob: d2e06dfba922b029ad3d3182eec45b3989ab69eb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
% ^^A ignore the tedious stuff when typesetting
%
% \CheckSum{6}
%
% \iffalse
%  Copyright 1996, 1999, 2010 Robin Fairbairns (rf10@cam.ac.uk)
%
%   This program may redistributed and/or modified under the terms
%   of the LaTeX Project Public License Distributed from CTAN
%   archives in directory macros/latex/base/lppl.txt; either
%   version 1.3 of the License, or (at your option) any later version.
%
%    \begin{macrocode}
%<*!debugins>
\NeedsTeXFormat{LaTeX2e}
%</!debugins>
%<*dtx>
\ProvidesFile{capt-of.dtx}%
%</dtx>
%<package>\ProvidesPackage{capt-of}%
        [2009/12/29 v0.2
%<package>     standard captions outside of floats%
%<*dtx>
               capt-of package source file%
%</dtx>
         ]% $Id: footmisc.dtx,v 4.20 2005/03/17 13:41:58 rf Exp rf10 $
%    \end{macrocode}
%
% Driver for compiling this file on its own
%    \begin{macrocode}
%<*driver>
\setcounter{errorcontextlines}{999}
\documentclass{ltxdoc}
\GetFileInfo{capt-of.dtx}
\EnableCrossrefs
% to get documented source of the package, comment out the next line,
% and uncomment the following one; otherwise, create yourself
% (somewhere on your LaTeX input path) a file ltxdoc.cfg that contains
% simply          \AtBeginDocument{\AlsoImplementation}
\OnlyDescription
%\AlsoImplementation
\setcounter{StandardModuleDepth}{1}
\begin{document}
\DocInput{capt-of.dtx}
\end{document}
%</driver>
%    \end{macrocode}
%
% \fi
%
% \title{The \textsf{capt-of} package}
% \author{Robin Fairbairns\thanks{Email: \emph{rf10@cam.ac.uk}}}
% \maketitle
%
% \section{Why this package?}
%
% \LaTeX{} provides a command (\cs{caption}) for adding a caption to a
% float environment (that is to say, a \texttt{figure} or a
% \texttt{table}, ``out of the box'').
%
% The command is a good one, and many users want to use it.  Often,
% they end up using a float environment, in a case where it's not
% strictly necessary, and get entangled in the positioning problems
% that floats pose for the innocent user.  Using this package, the
% user can have standard-looking captions without the need of a float
% environment.
%
% This package defines an alternative command, \cs{captionof}, which
% sets things up so that \cs{caption} will work outside of a float.
%
% The \textsf{float} package provides an alternative to
% \cs{captionof}, in the float \texttt{[H]} option
% (``place the environment \emph{here} without doing any of this
% floating stuff'').  So why use \textsf{capt-of}? --- its great
% advantage is simplicity; you load it, and it defines \emph{one}
% macro, while \textsf{float} defines lots and lots.  (Of course, if
% you need others of \textsf{float}'s capabilities, \textsf{capt-of}
% loses its advantage...).
%
% \section{The potential problem}
%
% \cs{captionof} defines a caption in text; it also steps the
% \texttt{figure} (or \texttt{table} or whatever) counter.  The float
% environments do the same.
%
% Now, consider the sequence:
% \begin{quote}
% \begin{verbatim}
% <earlier text>
% \begin{figure}
%   <figure stuff>
%   \caption{...}
% \end{figure}
% ...
% <intervening text>
% ...
% <inline figure stuff>
% \captionof{figure}{...}
% \end{verbatim}
% \end{quote}
% and suppose the \texttt{figure} environment doesn't fit anywhere
% between where it's specified and the inline figure (so that it will
% float to somewhere later).
%
% We will then see a document with
% \begin{quote}
% \meta{earlier text}\\
% \dots\\
% \meta{intervening text}\\
% \dots\\
% \meta{inline figure stuff}\\
% Figure \meta{n+1}: \dots\\
% \dots\\
% \meta{yet more text}\\
% \dots\\
% \meta{figure stuff}\\
% Figure \meta{n}: \dots
% \end{quote}
% That is, the figure numbers have got out of order, because the
% floating figure was specified before the inline figure.
%
% \LaTeX{} won't do this when everything is specified as a float: it
% keeps floats of the same type in order (which is why floats stack up
% if a single one won't fit).
%
% The moral of that little tale is to say: don't use \cs{captionof}
% and floats of the same type in the same document.  (Or be
% extra-specially careful about what's happening if you must.)
% \AlsoImplementation
% \StopEventually{}
%
% \section{The code (such as it is)}
%
% \begin{macro}{\captionof}
% Usage: \cs{captionof}\marg{type}\oarg{move}\marg{caption}
% \begin{description}
% \item[\normalfont\itshape type] is `\texttt{figure}' or
%   `\texttt{table}' (or some type you've defined with the
%   \textsf{float} package)
% \item[\normalfont\itshape move] is the optional moving argument of
%   \cs{caption} (the thing that goes to the list of tables/figures)
% \item[\normalfont\itshape caption] is the text of the caption
% \end{description}
%
% It's probably best to use \cs{captionof} within an enclosing group
% (e.g., \cs{begin}\marg{center} \emph{figure}
% \cs{captionof}\texttt{\char`{figure\char`}}\marg{blah blah} \cs{end}\marg{center})
%    \begin{macrocode}
\newcommand\captionof[1]{\def\@captype{#1}\caption}
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\endinput
%</package>
%    \end{macrocode}
%
% \Finale
%
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
\endinput