From 049f485bdf6f9dbd4880051384aaf239d85ba83e Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 24 Aug 2007 18:34:07 +0000 Subject: trvfloat 1.3 (21aug07) git-svn-id: svn://tug.org/texlive/trunk@4795 c570f23f-e606-0410-a88d-b1316a301751 --- .../source/latex/trivfloat/trivfloat.dtx | 429 +++++++++++++++------ 1 file changed, 318 insertions(+), 111 deletions(-) (limited to 'Master/texmf-dist/source/latex/trivfloat/trivfloat.dtx') 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 @@ % % \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} -- cgit v1.2.3