path: root/Master/texmf-dist/source/latex/trivfloat/trivfloat.dtx

% \iffalse meta-comment
%
% Copyright (C) 2007 by
%    Joseph Wright <joseph.wright@morningstar2.co.uk>
%
% Released under the GNU General Public License v2
% See http://www.gnu.org/licenses/gpl.txt
%
% This work consists of the main source file chemextra.dtx
% and the derived files
%
%<*driver>
\documentclass{ltxdoc}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
%\OnlyDescription
\usepackage[T1]{fontenc}
\usepackage[english,UKenglish]{babel}
\usepackage{mathpazo,booktabs,array,url,graphicx,courier,unitsdef}
\usepackage{upgreek}
\usepackage[scaled=0.95]{helvet}
\usepackage[version=3]{mhchem}
\usepackage[final]{microtype}
\usepackage{\jobname}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \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
%   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}
%
% \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}
%
%\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/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}
% 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]{%
  \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