Debian Codegraph @

texmf-dist/source/latex/capt-of/capt-of.dtx

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