summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/trivfloat/trivfloat.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/trivfloat/trivfloat.dtx')
-rw-r--r--Master/texmf-dist/source/latex/trivfloat/trivfloat.dtx429
1 files changed, 318 insertions, 111 deletions
diff --git a/Master/texmf-dist/source/latex/trivfloat/trivfloat.dtx b/Master/texmf-dist/source/latex/trivfloat/trivfloat.dtx
index dd4268555f6..217bb8d225a 100644
--- a/Master/texmf-dist/source/latex/trivfloat/trivfloat.dtx
+++ b/Master/texmf-dist/source/latex/trivfloat/trivfloat.dtx
@@ -29,7 +29,7 @@
%</driver>
% \fi
%
-% \CheckSum{113}
+% \CheckSum{239}
%
% \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
@@ -49,18 +49,28 @@
%
% \GetFileInfo{\jobname.sty}
%
-% \changes{v1.0}{2007/06/09}{Initial public release}
-% \changes{v1.1}{2007/08/13}{Floats can be generated as package
+%\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}
%
-% \DoNotIndex{\@eha,\@ne,\advance,\begingroup,\csname,\def,\edef}
-% \DoNotIndex{\else,\end,\endcsname,\endgroup,\expandafter,\fi}
-% \DoNotIndex{\ifcase,\jobname,\MakeLowercase,\MakeUppercase}
-% \DoNotIndex{\MessageBreak,\NeedsTeXFormat,\newcommand,\newcount}
-% \DoNotIndex{\noexpand,\or,\PackageError,\PackageInfo}
-% \DoNotIndex{\PackageWarning,\ProvidesPackage,\RequirePackage}
-% \DoNotIndex{\romannumeral,\x}
-% \DoNotIndex{\CurrentOption,\DeclareOption,\ProcessOptions}
+% \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
@@ -69,43 +79,125 @@
% \thanks{E-mail: joseph.wright@morningstar2.co.uk}}
% \date{Released \filedate}
%
-% \maketitle
-%
-% \begin{abstract}
+%\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}
%
-% \end{abstract}
-%
-% \section{Introduction}
+%\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-and-dirty one to
-% set up a new float type with no customisation. This is addressed
-% by the |trivfloat| package.
+% 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}
%
-% \section{Usage}
+% 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.
%
-% \DescribeMacro{\trivfloat}
-% \DescribeMacro{\listoffloat-names}
-% The package provides a single command to produce the new float
-% type, |\trvifloat|. This takes a single argument
-% \marg{float-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 command |\listof|\meta{float-name}|s| is also
-% provided.
+% 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.''
%
-% New floats can also be generated by passing the name of the desired
-% float type to the package as an option. This works in exactly the
-% same way as the \cmd{\trivfloat} command.
+% 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.
%
-% \StopEventually{}
+%\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>
@@ -120,36 +212,45 @@
% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{trivfloat}
- [2007/08/13 v1.1 Quick floats in LaTeX]
-\RequirePackage{float}
+ [2007/08/22 v1.3a 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}
+%\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}
-% \begin{macro}{\tfl@ext@i}
-% 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. Note that |lof|, |log| and |lot| are taken by default,
-% so we don't use them. 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.
+%\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{%
- \expandafter\def\csname tfl@ext@\romannumeral\tfl@floatcount%
- \expandafter\endcsname{%
+ \def\tfl@ext{%
\ifcase\tfl@floatcount%
- \PackageError{trivfloat}%
- {Something's wrong here --- Contact the package author!}%
- \@eha%
+% \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
@@ -181,20 +282,18 @@
\or % 16
lor%
\or % 17
- los%
- \or % 18
lou%
- \or % 19
+ \or % 18
lov%
- \or % 20
+ \or % 19
low%
- \or % 21
+ \or % 20
lox%
- \or % 22
+ \or % 21
loy%
- \or % 23
+ \or % 22
loz%
- \else % 24 or more
+ \else % 23 or more
\PackageWarning{trivfloat}%
{I've run out of extensions \MessageBreak%
I'm using \jobname.xxx to list all future floats}%
@@ -203,77 +302,185 @@
}%
}%
% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \begin{macro}{\tfl@gennamea}
-% \begin{macro}{\tfl@genname}
-% \begin{macro}{\tfl@name@i}
-% The conversion of the supplied float name to a form suitable for
-% using as a title is achieved here. We strip off the first letter,
-% convert to uppercase, then convert the rest to lowercase. Thanks
-% to Martin Heller for the method to strip the first letter off.
+%\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}
-\def\tfl@gennamea#1#2\end{%
- \expandafter\def\csname tfl@name@\romannumeral\tfl@floatcount%
- \expandafter\endcsname{%
- \MakeUppercase{#1}%
- \MakeLowercase{#2}%
- }%
-}%
-\def\tfl@genname#1{%
- \tfl@gennamea#1\end%
-}%
+\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}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \begin{macro}{\tfl@list}
-% \begin{macro}{\listoffloat-names}
-% An auxiliary function is needed to define the
-% \texttt{\textbackslash listof\emph{float-name}s} macros. This is
-% to ensure that expansion occurs properly.
+% The change from the kernel version comes here.
% \begin{macrocode}
-\def\tfl@list#1#2#3{%
- \newcommand*{#1}{\listof{#2}{#3}}%
+ \expandafter}\reserved@a
}%
% \end{macrocode}
-% \end{macro}
-% \end{macro}
+%\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}
+%\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. Notice that a single
-% command for the extension would work. However, the float name does
-% need different commands for each float. So for consistency, both
-% have numerals appended.
+% 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]{%
\advance\tfl@floatcount\@ne%
\tfl@genext%
- \tfl@genname{#1}%
\PackageInfo{trivfloat}%
- {Listing all floats of type #1 in \jobname.%
- \csname tfl@ext@\romannumeral\tfl@floatcount\endcsname}%
+ {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%
- \noexpand\newfloat{#1}{tbp}{%
- \csname tfl@ext@\romannumeral\tfl@floatcount\endcsname%
- }%
- \noexpand\floatname{#1}{%
- \expandafter\noexpand%
- \csname tfl@name@\romannumeral\tfl@floatcount\endcsname%
- }%
- \noexpand\tfl@list{\csname listof#1s\endcsname}{#1}{%
- List of \expandafter\noexpand%
- \csname tfl@name@\romannumeral\tfl@floatcount\endcsname s%
- }%
+ \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}