summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/trivfloat/trivfloat.dtx
blob: 33b68d767d596746c84f7ee28568b01b83097ed6 (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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
% \iffalse meta-comment
%
% Copyright (C) 2007 by
%    Joseph Wright <joseph.wright@morningstar2.co.uk>
%
% 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.''
%
% The current maintainer of this work is Joseph Wright.
%
% This work consists of the main source files trivfloat.dtx
% and trivfloat.ins and the derived files trivfloat.sty and
% trivfloat.pdf.
%
%<*driver>
\PassOptionsToClass{a4paper}{article}
\documentclass{ltxdoc}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
%\OnlyDescription
\usepackage[T1]{fontenc}
\usepackage[english,UKenglish]{babel}
\usepackage{mathpazo,booktabs,array,url,graphicx,courier,unitsdef}
\usepackage{upgreek,ifpdf}
\usepackage[scaled=0.95]{helvet}
\usepackage[version=3]{mhchem}
\usepackage[final]{microtype}
% Some tricks from Heiko Oberdiek
\ifpdf
  \usepackage{embedfile}
  \embedfile[%
    stringmethod=escape,%
    mimetype=plain/text,%
    desc={LaTeX docstrip source archive for package `\jobname'}%
    ]{\jobname.dtx}
\fi
\usepackage{\jobname}
\usepackage[numbered]{hypdoc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{240}
%
% \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         \~}
%
% \GetFileInfo{\jobname.sty}
%
%\changes{v1.0}{2007/06/09}{Initial public release}
%\changes{v1.1}{2007/08/13}{Floats can be generated as package
%   options}
%\changes{v1.2}{2007/08/20}{Added \texttt{memoir} support}
%\changes{v1.2}{2007/08/20}{Improved emulation of default floats}
%\changes{v1.3b}{2007/09/20}{Fixed error with \texttt{hyperref}}
%\changes{v1.3b}{2007/09/20}{Licence changed from GPL to LPPL}
%
% \DoNotIndex{\@arabic,\@chapter,\@gobble,\@ifclassloaded,\@ne}
% \DoNotIndex{\@onlypreamble,\@smemfront,\@smemmain,\@uclclist}
% \DoNotIndex{\@undefined,\addtocontents,\addtodef,\addvspace}
% \DoNotIndex{\advance,\backmatter,\begingroup,\c@chapter}
% \DoNotIndex{\cftsetindents,\chapter,\counterwithin,\counterwithout}
% \DoNotIndex{\csname,\CurrentOption,\DeclareOption,\def,\edef,\else}
% \DoNotIndex{\endcsname,\endgroup,\expandafter,\fi,\floatname}
% \DoNotIndex{\g@addto@macro,\i,\ifartopt,\ifcase,\ifnum,\ifx}
% \DoNotIndex{\insertchapterspace,\j,\jobname,\KOMAScriptVersion}
% \DoNotIndex{\let,\listof,\MakeUppercase,\MessageBreak}
% \DoNotIndex{\NeedsTeXFormat,\newcommand,\newcount,\newfloat}
% \DoNotIndex{\newlistentry,\newlistof,\noexpand,\or,\PackageInfo}
% \DoNotIndex{\PackageWarning,\ProcessOptions,\protect}
% \DoNotIndex{\protected@edef,\ProvidesPackage,\relax,\renewcommand}
% \DoNotIndex{\RequirePackage,\reserved@a,\reserved@b,\setcounter}
% \DoNotIndex{\thechapter,\uppercase,\x,\z@,\DeclareRobustCommand}
%
% \title{Quick floats in LaTeX%
%   \thanks{This file describes version \fileversion, last revised
%           \filedate.}}
% \author{Joseph Wright%
%   \thanks{E-mail: joseph.wright@morningstar2.co.uk}}
% \date{Released \filedate}
%
%\maketitle
%
%\begin{abstract}
% The |trivfloat| package provides a quick method for defining new
% float types in LaTeX.  A single command sets up a new float in the
% same style as the LaTeX kernel |figure| and |table| float types.
%\end{abstract}
%
%\begin{multicols}{2}
%\tableofcontents
%\end{multicols}
%
%\section{Introduction}
%
% The LaTeX kernel provides the |figure| and |table| floating
% environment, but does not provide an easy method for defining new
% float types.  This problem is addressed by the |float| package,
% which provides an array of commands to create new float types.
% However, the one command missing is a quick one to set up a new
% float type with no customisation.  This is addressed by the
% |trivfloat| package.
%
%\section{Usage}
%
%\DescribeMacro{\trivfloat}
% The package itself provides only a single command to the user,
% \cmd{\trivfloat}.  This takes a single argument \marg{name}, which
% will be the name of the new floating environment.  The new
% environment can be used as normal; the new floats should behave
% exactly the same as |figure| and |table| environments.  The
% |trivfloat| package works hard to ensure that the newly-produced
% floats behave exactly like pre-defined ones.  The exact behaviour
% of the new floats is dependant on the document class used:
% |trivfloat| knows about the standard classes, |memoir| and
% \textsc{koma}-Script.  The \cmd{\trivfloat} command should only be
% used in the preamble of the document; LaTeX will complain if you
% use it later. New floats can also be generated by passing the name
% of the desired float type to the package as an option.  In this way
% several new floats can be produced in on go.  The new floats will
% respect the normal position modifiers, \texttt{t}, \texttt{b},
% \texttt{h}, \texttt{p} and (if |memoir| is not in use) \texttt{H}
% for \emph{really} here.
%
% The |trivfloat| package defines a new environment \meta{float} for
% each new float, which should be used in the same way as a figure or
% table environment.  The command \texttt{\textbackslash
% \meta{float}name} is provided for the naming of float captions.  In
% analogy to \cmd{\figurename} and \cmd{\tablename}, the default
% value is ``\emph{Float}.''  Secondly, the \texttt{\textbackslash
% listof\meta{float}s} command is defined.  This will produce a list
% of the new float types, in the same way as \cmd{\listoffigures}
% gives a figure listing.  The title text for this is stored in
% \texttt{\textbackslash list\meta{float}name}, and defaults to
% ``List of \emph{Float}s.''  Both can be redefined either by the
% user or using the |babel| \cmd{\addto} method if
% needed.\footnote{For a recent discussion of controlling
% \texttt{babel} see: \emph{Enjoying babel}, E.~Gregorio,
% \emph{TUGboat}, \textbf{2007}, \emph{28}, 247--255.}  Notice that
% the capitalisation of the float name for the naming commands only
% alters the first letter of the name given.
%
% An example of the use of the package would be to create a new float
% type for charts, by having |\trivfloat{chart}| in the preamble.  In
% the body of the document, one can then use |\begin{chart}| \ldots
% |\end{chart}| to have a floating chart.  This will result in
% \cmd{\chartname} having the value ``Chart,'' and
% \cmd{\listchartname} taking the value ``List of Charts.''  A
% listing of all of the charts in the document would be obtained
% using \cmd{\listofcharts} (needing two LaTeX runs as normal).
%
%\section{Known issues}
%
% Some of the issues known to the package author are quite
% complicated, and most users will probably never encounter them.
% They are marked with a ``dangerous bend'' sign, and should be
% skipped by inexperienced TeX users.
%
% The name passed to \cmd{\trivfloat} should contain only the letters
% A--Z and a--z.  This ensures that there are no strange errors
% generated by TeX. Correctly handling non-English words is not
% possible using an automated system, and so after defining a new
% float type the macros \texttt{\textbackslash\meta{float}name} and
% \texttt{\textbackslash list\meta{float}name} should be corrected to
% give the desired names.  If you \emph{really} need to use other
% characters, read the ``dangerous bend.''
%
% The |babel| system provides support for a wide range of
% language-specific strings.  It also makes changes to the typography
% of documents.  The changes made by |babel| can be in almost any
% area, and so floats created with |trivfloat| may not act like the
% standard ones once |babel| is loaded.  For example, the |french|
% option for babel alters the internal function used to make float
% captions.  Users should search through the
% \texttt{\meta{language}.ldf} file for the languages they use for
% ``figure'' and ``lof'' to see what changes |babel| makes to the
% standard floats.  The user can then correct the behaviour of the
% new floats as needed.
%
%\iffalse meta-comment
% The following is a quick hack for a ``dangerous bend'' text.
% No text scaling or anything like that is done!
%\fi
%\font\manual=manfnt
%\def\dbend{{\manual\char127}}
%\def\danger{\begin{trivlist}\item[]\noindent
%\begingroup\hangindent=3pc\hangafter=-2\small
%\def\par{\endgraf\endgroup}
%\hbox to0pt{\hskip-\hangindent\dbend\hfill}\ignorespaces}
%\def\enddanger{\par\end{trivlist}}
%\begin{danger}
% The float-forming mechanism \emph{will} accept characters which are
% not regarded by TeX as ``letters'' as it uses \cmd{\csname} \ldots
% \cmd{\endcsname} to generate the new float type.  However, very odd
% and hard to locate errors may occur if this is done.  With some
% document classes (\emph{e.g.}~|article|) all seems to work, but
% other classes (\emph{e.g.}~|book|) cause TeX to complain. As a
% result, all characters passed to \cmd{\trivfloat} should be have a
% catcode of 11. If you attempt to use character that is not a single
% character (say for example \cmd{\ss} for \ss) things will go badly
% wrong.  Stick to letters.
%\end{danger}
%
%\StopEventually{}
%
% \iffalse
%<*package>
% \fi
%
% \section{Implementation}
%
% \subsection{Setup code}
%
% The first part of the package is concerned with basic
% identification and loading support packages.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{trivfloat}
  [2007/09/20 v1.3b Quick floats in LaTeX]
%    \end{macrocode}
% |memoir| has its own \cmd{\newfloat} mechanism, and so |float| is
% used only if |memoir| is not loaded.
%    \begin{macrocode}
\@ifclassloaded{memoir}
  {}
  {\RequirePackage{float}}
%    \end{macrocode}
%
% \subsection{Internal macros}
%
%\begin{macro}{\tfl@floatcount}
% A new counter is needed to track how many floats have been
% generated by |trivfloat|.
%    \begin{macrocode}
\newcount\tfl@floatcount%
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\tfl@genext}
%\changes{v1.2}{2007/08/20}{Removed \texttt{los} from list of possible
%  extensions}
%\begin{macro}{\tfl@ext}
% Each float type needs a list to store entries when generating a
% contents listing.  Rather than try complex things with the initial
% characters of the float name, an arbitrary file extension is used.
% The extensions |lof|, |log| and |lot| are taken by default, so we
% don't use them.  The |chemscheme| package uses |los|, so this is
% left alone as well. Also notice that if people try to make too many
% new float types, then extension |xxx| will be used.  This is very
% unlikely, but odd things might happen so we warn them.
%    \begin{macrocode}
\def\tfl@genext{%
  \def\tfl@ext{%
    \ifcase\tfl@floatcount%
%    \end{macrocode}
% Zero is not a possibility for \cmd{\tfl@floatcount} is not a
% possibility, so this is skipped over.
%    \begin{macrocode}
    \or % 1
      loa%
    \or % 2
      lob%
    \or % 3
      loc%
    \or % 4
      lod%
    \or % 5
      loe%
    \or % 6
      loh%
    \or % 7
      loi%
    \or % 8
      loj%
    \or % 9
      lok%
    \or % 10
      lol%
    \or % 11
      lom%
    \or % 12
      lon%
    \or % 13
      loo%
    \or % 15
      loq%
    \or % 16
      lor%
    \or % 17
      lou%
    \or % 18
      lov%
    \or % 19
      low%
    \or % 20
      lox%
    \or % 21
      loy%
    \or % 22
      loz%
    \else % 23 or more
      \PackageWarning{trivfloat}%
        {I've run out of extensions \MessageBreak%
         I'm using \jobname.xxx to list all future floats}%
      xxx%
    \fi%
  }%
}%
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\begin{macro}{\tfl@uppercase}
%\changes{v1.3a}{2007/08/22}{New macro}
% To get the correct kerning, a customised version of
% \cmd{\MakeUppercase} is needed.  Normally you are not supposed to
% use \cmd{\reserved@a} and \cmd{\reserved@b}, but the code here is a
% very minor alteration of the LaTeX kernel code, so these macros are
% retained. The use of \cmd{\DeclareRobustCommand} here is essential.
%    \begin{macrocode}
\DeclareRobustCommand\tfl@uppercase[1]{%
  {%
    \def\i{I}\def\j{J}%
    \def\reserved@a##1##2{\let##1##2\reserved@a}%
    \expandafter\reserved@a\@uclclist\reserved@b{\reserved@b\@gobble}%
    \protected@edef\reserved@a{\uppercase{#1}}%
%    \end{macrocode}
% The change from the kernel version comes here.
%    \begin{macrocode}
  \expandafter}\reserved@a
}%
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\tfl@upperfirst}
%\changes{v1.2}{2007/08/20}{Made names change case correctly}
%\changes{v1.3}{2007/08/21}{Replaces \cs{tfl@genname} and
%  \cs{tfl@gennamea}}
%\changes{v1.3}{2007/08/21}{New macro}
%\changes{v1.3a}{2007/08/22}{Uses modified version of
%  \cs{MakeUppercase}}
% As suggested by Ulrich Diez, this is an improved method for making
% case changes than the previous version (v1.2).  Notice that it does
% mean that the user is responsible for the case of everything except
% the first letter.
%    \begin{macrocode}
\def\tfl@upperfirst#1{%
  \protect\@gobble\noexpand\tfl@uppercase#1%
}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\tfl@chapter}
%\begin{macro}{\tfl@orig@chapter}
%\begin{macro}{\tfl@chapter@hook}
% A method to add to the \cmd{\@chapter} macro is needed.  This is
% not compatible with \cmd{\g@addto@macro} directly, so a more
% complex method is used by providing a suitable hook.
%    \begin{macrocode}
\ifx\chapter\@undefined\else
  \def\tfl@chapter@hook{\relax}
  \let\tfl@orig@chapter\@chapter
  \def\tfl@chapter{\tfl@chapter@hook\tfl@orig@chapter}
  \let\@chapter\tfl@chapter
\fi
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%
% \subsection{User space macros}
%
%\begin{macro}{\trivfloat}
% The only user-facing macro we need is |\trivfloat|. This does the
% work of setting up the new float type. Thanks to Heiko Oberdiek for
% the method to expand arguments correctly: needed so that
% \cmd{\tfl@ext} has the correct value.
%\changes{v1.3}{2007/08/21}{Removed redundant numeral-based code}
%    \begin{macrocode}
\newcommand*{\trivfloat}[1]{%
  \AtBeginDocument{%
    \advance\tfl@floatcount\@ne%
    \tfl@genext%
    \PackageInfo{trivfloat}%
      {Listing all ``#1'' floats in \jobname.\tfl@ext}%
%    \end{macrocode}
% The first step for forming a new float type is to create the
% \texttt{\textbackslash \meta{float}name} and
% \texttt{\textbackslash list\meta{float}name} macros.
%\changes{v1.2}{2007/08/20}{Create ``name'' commands rather than
%  using text directly}
%\changes{v1.3}{2007/08/21}{Use \cs{newcommand*} for ``name''
%  commands}
%    \begin{macrocode}
    \expandafter\newcommand\expandafter*\expandafter%
      {\csname #1name\endcsname}
      {\noexpand\tfl@upperfirst#1}
    \expandafter\newcommand\expandafter*\expandafter%
      {\csname list#1name\endcsname}
        {List of \noexpand\tfl@upperfirst#1s}
    \begingroup%
    \edef\x{\endgroup%
%    \end{macrocode}
%\changes{v1.2}{2007/08/20}{Added \texttt{memoir}-specific code}
% The |memoir|-dependent code now occurs.  The case when |memoir|
% is in use is handled first.
%    \begin{macrocode}
      \@ifclassloaded{memoir}
        {\noexpand\newfloat[chapter]{#1}{\tfl@ext}
          {\csname #1name\endcsname}
        \noexpand\newlistof{listof#1s}{\tfl@ext}
          {\csname list#1name\endcsname}
%    \end{macrocode}
% The following deals with the vertical space in list of float tables
% that occurs between each chapter.
%    \begin{macrocode}
        \noexpand\addtodef{\noexpand\insertchapterspace}{}%
          {\noexpand\addtocontents%
            {\tfl@ext}
            {\noexpand\protect\noexpand\addvspace{10pt}}}
        \noexpand\newlistentry[chapter]{#1}
          {\tfl@ext}{0}}
%    \end{macrocode}
% The creation of new floats needs to know if the document class is
% using chapters, when |memoir| is not in use.
%\changes{v1.2}{2007/08/20}{Added chapter detection}
%    \begin{macrocode}
        {\ifx\chapter\@undefined
          \noexpand\newfloat{#1}{tbp}{\tfl@ext}
        \else
          \noexpand\newfloat{#1}{tbp}{\tfl@ext}[chapter]
        \fi
%    \end{macrocode}
%\changes{v1.2}{2007/08/20}{Removed auxiliary macro \cs{tfl@list}}
% The naming of floats for captions and generation of a list of
% floats is now handled.
%    \begin{macrocode}
        \noexpand\floatname{#1}{\csname #1name\endcsname}%
        \noexpand\newcommand{\csname listof#1s\endcsname}%
          {\noexpand\listof{#1}{\csname list#1name\endcsname}}%
        \ifx\chapter\@undefined\else
          \noexpand\g@addto@macro{\noexpand\tfl@chapter@hook}
            {\noexpand\addtocontents%
              {\tfl@ext}
              {\noexpand\protect\noexpand\addvspace{10pt}}}
        \fi}
      }%
    \x%
%    \end{macrocode}
% Except for \textsc{koma}-Script, all of the supported document
% classes need some further hacks to get behaviour equivalent to the
% normal float types.  None of these need to have access to the
% \cmd{\tfl@ext}, so are safe outside the \cmd{\edef} above. |memoir|
% does various low-level things, which are reproduced first.  Here,
% \cmd{\@ifclassloaded} can be used as |\iftfl@memoir| leads to |\if|
% nesting errors.
%    \begin{macrocode}
    \@ifclassloaded{memoir}
      {\expandafter\renewcommand\expandafter{\csname the#1\endcsname}%
        {\thechapter.\expandafter\@arabic\csname c@#1\endcsname}
      \addtodef{\@smemfront}{}{\counterwithout{#1}{chapter}}
      \addtodef{\@smemmain}{}{%
        \ifartopt\else
          \counterwithin{#1}{chapter}
        \fi}
      \addtodef{\backmatter}{}{%
        \ifartopt\else
          \counterwithout{#1}{chapter}
          \setcounter{#1}{0}
        \fi}
      \ifartopt
        \counterwithout{#1}{chapter}
      \fi
      \cftsetindents{#1}{0em}{2.3em}}
%    \end{macrocode}
% The standard document classes do not print the chapter number
% in captions if it is not greater than zero.
%    \begin{macrocode}
    {\ifx\chapter\@undefined\else
      \ifx\KOMAScriptVersion\@undefined
        \expandafter\renewcommand\expandafter{\csname the#1\endcsname}%
          {\ifnum\c@chapter>\z@ \thechapter.\fi
            \expandafter\@arabic\csname c@#1\endcsname}
    \fi\fi}
  }
}%
%    \end{macrocode}
%\changes{v1.2}{2007/08/20}{Only in preamble}
% The necessary patching can only be done in the preamble, so
% \cmd{\trivfloat} is banned elsewhere.
%    \begin{macrocode}
\@onlypreamble\trivfloat
%    \end{macrocode}
% \end{macro}
%
% \subsection{Package options}
%
% Any package options given are assumed to be new float types.
% Every option is therefore passed to \cmd{\trivfloat}.
%    \begin{macrocode}
\DeclareOption*{\expandafter\trivfloat\expandafter{\CurrentOption}}
\ProcessOptions
%    \end{macrocode}
%
% \iffalse
%</package>
% \fi
% \PrintChanges
% \PrintIndex
% \Finale