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

% \iffalse 
%%
%% Package `multicap' to use with LaTeX2e
%% Copyright 2002 John Vassilogiorgakis.
%%
%% Contact at: giannis@iris.math.aegean.gr
%%
%%  This program may be distributed and/or modified under the
%%  conditions of the LaTeX Project Public License, either version 1.2
%%  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.2 or later is part of all distributions of LaTeX 
%%  version 1999/12/01 or later.
%%
%<*dtx>
\ProvidesFile{multicap.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{multicap}
%<*driver>
\documentclass{ltxdoc}
\usepackage[english]{babel}
\usepackage{multicol,tabularx,multicap}
\renewcommand{\thetable}{\os{\arabic{table}}}
\newcommand{\os}{\oldstylenums}
\setlength{\columnseprule}{.4pt}
\setlength{\columnsep}{18pt}
\setlength{\textwidth}{39pc}
\setlength{\textheight}{54pc}
\setlength{\parindent}{1em}
\setlength{\parskip}{0pt plus 1pt}
\setlength{\oddsidemargin}{0pc}
\setlength{\marginparwidth}{0pc}
\setlength{\topmargin}{-2.5pc}
\setlength{\headsep}{20pt}
\setlength{\columnsep}{1.5pc}
\setcounter{columnbadness}{7000}
\setcounter{finalcolumnbadness}{7000}
\begin{document}
  \typeout
   {***********************************************************************
 ^^J* multicap.dtx requires  multicol.sty, multicap.sty and tabular.sty *
 ^^J***********************************************************************}
\DocInput{multicap.dtx}
\end{document}
%</driver>
% \fi
% \ProvidesFile{multicap.dtx}
   [2002/05/04 v1.0 formatting captions inside multicols]
%
%% \CheckSum{194}
%
% \MakeShortVerb{\|}
%
% \GetFileInfo{multicap.dtx}
% \title{The \texttt{`multicap'} \LaTeXe\ package\thanks{Version number \fileversion{}. 
% Last revised \filedate{}.}} 
% \author{John Vassilogiorgakis\\
% \texttt{giannis@iris.math.aegean.gr}}
% \date{12th May 2002}
%
% \maketitle
%
% \begin{abstract}
% This is a package for formating captions of column figures and column tabular material which cannot be floats 
% (i.e. outside a \texttt{figure} or \texttt{table} environment in standard \LaTeX) in the \texttt{multicols} 
% environment provided by the \textsf{multicol} 
% package. It also provides an easy way to customize your captions, either in  single column or inside \texttt{multicols}. 
% \end{abstract}
%
% \tableofcontents
%
% \begin{multicols}{2}[\section{Introduction}]\hbadness=10000
% As it is known, the \textsf{multicol} package supports partially floats inside  
% \texttt{multicols} environment. To be exact, only the star versions of the floating environments 
% are supported, excluding the existence of column floats---i.e. only page wide floats can be used \cite{MB}. However, one can 
% put a column image or tabular material 
% with one or another way---with an |\includegraphics| 
% command, or a \texttt{tabularx} environment inside a |center| environment---getting satisfactory 
% results like the following:  
% \begin{center}
% \begin{tabularx}{\linewidth}{p{35pt}>{$}X<{$}>{$}X<{$}}
% \hline
% &\mathbf{x_1}&\mathbf{x_2}\\\hline\hline
% \os{1}.&(x-1,y-1)&(x+1,y+1)\\
% \os{2}.&(x,y-1)&(x,y+1)\\
% \os{3}.&(x+1,y-1)&(x-1,y+1)\\
% \os{4}.&(x-1,y)&(x+1,y)\\
% \hline
% \end{tabularx}
% \end{center}
% The same thing can happen, of course, with `column figures'. The column material  
% is placed outside of a floating environment by simply specifying:
% \begin{center}
% \textit{... text before column material ...}
% \begin{verbatim}
% \begin{center}
% \begin{tabularx}{\linewidth}{...}
%  ...
% \end{tabularx}
% \end{center}
% \end{verbatim}
% \textit{... text after column material ...}
% \end{center} 
% The only thing left, is to add captions to this column material, as we would have done if this material were 
% inside a floating environment. Moreover, we want the numbering of these captions to be handled correctly, even   
% if a star-form of a floating environment appears and even if we are switching between |multicols| and single column layout. 
% Finally, we also want the text specified by the caption to appear in the 
% list of figures or tables and the references to this material to  work correctly.
% \end{multicols}
%
% \begin{multicols}{2}[\section{Usage}]\hbadness=10000
% The package loads with\begin{center}
% \fbox{\cs{usepackage}\texttt{\{multicap\}}}
% \end{center} 
% and it requires the \textsf{ifthen} package.
% The \textsf{multicap} package defines the |\mfcaption| and |\mtcaption| commands,  
% which replace the  |\caption| command outside of a floating environment;   
% for column figures and column tabular 
% material respectively, that are necessary outside of a floating environment inside |multicols|. 
% 
% The syntax of the commands is the same as the one  of |\caption|'s:
% ^^A \DescribeMacro{\mfcaption} 
% \begin{center}
% \fbox{\cs{mfcaption}[\textit{short text}]\{\textit{long text}\}}
% \end{center}
% for formating captions of `column figures' and
% ^^A \DescribeMacro{\mtcaption}
% \begin{center}
% \fbox{\cs{mtcaption}[\textit{short text}]\{\textit{long text}\}}
% \end{center} 
% for formating captions of column tabular material (`column tables'). As in the case of the |\caption| 
% command, the optional argument \textit{short text} goes into the list of figures or tables. If this is not 
% specified, then the mandatory argument \textit{long text} does the job.
% 
% Thus, the previous `orphan' tabular\footnote{Sorry for using the same example again and again.} can now have a caption like this:
% \begin{center}
% \begin{tabularx}{\linewidth}{p{35pt}>{$}X<{$}>{$}X<{$}}
% \hline
% &\mathbf{x_1}&\mathbf{x_2}\\\hline\hline
% \os{1}.&(x-1,y-1)&(x+1,y+1)\\
% \os{2}.&(x,y-1)&(x,y+1)\\
% \os{3}.&(x+1,y-1)&(x-1,y+1)\\
% \os{4}.&(x-1,y)&(x+1,y)\\
% \hline
% \end{tabularx}
% \mtcaption[This captions produced with the \cs{mtcaption} command.]{Caption inside \texttt{multicols}.}
% \end{center}
% The command line arguments were:
% \begin{verbatim}
% \begin{center}
% \begin{tabularx}{\linewidth}{...}
%  ...
% \end{tabularx}
% \mtcaption[This captions produced with the 
%           \mtcaption command.]{Caption inside 
%           \texttt{multicols}.}
% \end{center}
% \end{verbatim}
% It is clear now, that you just put the column material---either this is a tabular material, a figure, a picture 
% loaded with an |\epsfig|, |\includegraphics| or anything relative---followed by an |\mfcaption|, for column `figures', 
% or an |\mtcaption| for `column tables', command inside a |center| environment and thats all. You have a caption for this 
% column material, as if it was inside a floating environment. Moreover, placing the whole stuff inside a \texttt{minipage} and 
% using the |\columnbreak| command, you can achieve good looking results by manually placing the column float 
% at the top or the bottom of the page. 
%
% \subsection{Options and customization}
% A tactic of many well known typographers and something that one encounters very often in well printed books, 
% is that  the comments explaining what is shown in a floating element, are typesetting with a \textsf{sans serif font} and with a 
% completely different lead (baseline skip) and font size than the main document's. For example, you may have a book 
% typeseted in \os{10}/\os{12}, and the captions of the floats to be in \os{9}/\os{11}.\os{5} or something else, depending 
% from the kind of the font. Especially the use of \textsf{unmodulated sans serif fonts} with a smaller font size 
% than the main document's 
% and the appropriate lead, is something that harmonizes well enough with the narrow linewidth of the two column 
% output. 
%
% \subsubsection{The \texttt{normal} option}
% The captions produced by the 
% \verb+\mfcaption+, \verb+\mtcaption+ and \verb+\caption+   
% commands with \textsf{multicap}, are typesetting the |\figurename| (or |\tablename|)  and 
% the mandatory argument \textit{long text} with the 
% \textsf{sans serif font} defined by the 
% |\sfdefault| command. The number that is associated with the column float is typeseted with \textsc{small caps}, 
% if there exists this shape for the \textsf{sans}. If not, a 
% \begin{verbatim}
% \renewcommand{\thefigure}{%
%  \textmormal{\textsc{\arabic{figure}}}}
% \end{verbatim}
% in the preamble solves the problem\footnote{Replace \cs{textsc} with \cs{oldstylenums} if you are typesetting with the 
% Computer Modern fonts.}, typesetting the counter with  small caps but with the normal font this time. This 
% is to deal with the high level typographic demands, that wants the comments explaining what is shown in a float   
% to be typeseted with \textsf{sans} and the number associated with this floating element to be old style. 
%
% ^^A \DescribeMacro{normal}
% If you don't want this perspective, \textsf{multicap} offers the unique package 
% option |normal| that typesets all 
% captions in the usual way. This can be chosen by specifying  
% \begin{center}
% \fbox{\cs{usepackage}\texttt{[normal]\{multicap\}}}
% \end{center}
% in the preamble.
%
% \subsubsection{Changing caption's \cs{fontsize} parameters}
% Package |multicap| offers you also the possibility to easily change the |\fontsize| parameters of the captions.   
% This can be 
% done by simply changing the values of the  
% \begin{center}\fbox{\texttt{mcapsize}}\ \,and\,\ \fbox{\texttt{mcapskip}}\end{center}
% counter variables with the |\setcounter| declaration. What really happens, is that the values of the above counters go 
% into the first and second argument respectively of the |\fontsize| command, that changes locally inside |\mfcaption|, 
% |\mtcaption| and |\caption|. 
% For example, if you want your captions to be typeseted in \os{9}/\os{11}, then you have to do in the 
% preamble the following declarations:
% \begin{verbatim}
% \setcounter{mcapsize}{9}
% \setcounter{mcapskip}{11}.
% \end{verbatim}
%
% We should emphasize at this point, that \textsf{multicap's} options, along with the \texttt{mcapsize} and \texttt{mcapskip} 
% parameters, take effect \textit{and} in the |\caption| command which the package redefines. Thus, the usage of \textsf{multicap}  
% is somehow wider, in the sense that these tuning options were not  given especially for a multicolumn layout. The 
% truth is that in multiple columns such changes fit better, but a novice user can also use them to format his captions 
% of his single  column layout. This is not true for the  parameters discussing in the next sections, which act affects 
% only the two new commands 
% |\mfcaption| and |\mtcaption| and their usage is restricted only for multicolumn output. 
%
% \subsubsection{The \cs{abvmcapskip} length}
% The vertical space added between the column float and the caption produced either by the |\mfcaption| or  
% |\mtcaption| command, is controlled by the 
% \begin{center}\fbox{\cs{abvmcapskip}}\end{center} 
% length parameter, which 
% is equal to the value of \os{10}pt. It is not suggested to  change this value (with the |\setlength| declaration), unless if you want  
% to typeset captions  with an extremely different font size and |\baselineskip|   
% than the main document's. 
% 
% \subsubsection{The \cs{blwmcapskip} length}
% From the other side now, if you decide not to use some of the |\mfcaption| and |\mtcaption| commands that  appear in your 
% code, inside a |center| environment\footnote{I suggest not to do so.} 
% (i.e. you may want to put them inside the range of a |\centering|  
% command or anything of the above,   
% thus giving a more  compact look on your multicolumn layout), there is the 
% possibility of changing the vertical space separating the caption from the following text by changing the 
% \begin{center}\fbox{\cs{blwmcapskip}}\end{center} length parameter (again with |\setlength|). The default value of 
% |\blwmcapskip| is equal to the 
% value of |\parsep|. 
% However, such a change will affect only the captions produced by the |\mfcaption| and |\mtcaption| commands that are 
% outside of a |center| environment. 
% 
% This tuning option is made possible, because placing one of the |\mfcaption| or |\mtcaption| 
% declarations outside of a |center| environment, the vertical space added between the \textit{text before column 
% material} and the column float, will be smaller than the vertical space that follows after the caption and before the 
% \textit{text after the column material}. This way, with the |\blwmcapskip|, you can 
% balance the vertical space before and after the column float.
%
% In any case, if you wish to have a more compact look using the |\centering| command for example, you should specify 
% something like this:
% \begin{center}\textit{... text before column material ...}
% \begin{verbatim}
% \par{\centering
% \begin{tabularx}{\linewidth}{...}
% ... 
% \end{tabularx}}
% \mtcaption{Another caption inside multicols.}
% \end{verbatim} 
% \textit{... text after column material ...}\end{center} 
% leaving the |\mfcaption| or |\mtcaption| declarations outside the range of |\centering|\,\footnote{We would have done 
% the same thing, if we were using the \cs{caption} command.}.^^A \par
% \begin{center}
% \begin{tabularx}{\linewidth}{p{35pt}>{$}X<{$}>{$}X<{$}}
% \hline
% &\mathbf{x_1}&\mathbf{x_2}\\\hline\hline
% \os{1}.&(x-1,y-1)&(x+1,y+1)\\
% \os{2}.&(x,y-1)&(x,y+1)\\
% \os{3}.&(x+1,y-1)&(x-1,y+1)\\
% \os{4}.&(x-1,y)&(x+1,y)\\
% \hline
% \end{tabularx}
% \mtcaption{Another caption inside \texttt{multicols}.}
% \end{center}
%
% \subsection{Numbering} 
% When formating captions in |multicols| using the \textsf{multicap} package and a star-form of a floating 
% environment appears, the |\caption| command keeps 
% numbering the figure or table that spans all columns now correctly, continuing from where a |\mfcaption| or 
% |\mtcaption| command had stopped, depending from the kind of float. The same thing happens when the opposite occurs---when 
% switching from the page-wide float to the column float---and when switching from \texttt{multicols} to single 
% column and back. This happens because the |\mfcaption| uses the |figure| counter to count the column figures and 
% the |\mtcaption| command the |table| counter to number the column tables. So the interchange  between |\mfcaption|, 
% |\mtcaption| and |\caption| and between one and multicolumn mode, does not affect the 
% numbering of the figures or tables that are handled correctly from the package.
% \end{multicols}
%
% \begin{table}[h]
% \begin{center}
% \begin{tabularx}{.66\linewidth}{p{35pt}>{$}X<{$}>{$}X<{$}}
% \hline
% &\mathbf{x_1}&\mathbf{x_2}\\\hline\hline
% \os{1}.&(x-1,y-1)&(x+1,y+1)\\
% \os{2}.&(x,y-1)&(x,y+1)\\
% \os{3}.&(x+1,y-1)&(x-1,y+1)\\
% \os{4}.&(x-1,y)&(x+1,y)\\
% \hline
% \end{tabularx}
% \caption{Table produced by the \texttt{table} environment.}
% \end{center}
% \end{table}
%
% \StopEventually{}
% \begin{multicols}{2}[\section{Implementation}]\hbadness=10000
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}%
\ProvidesPackage{multicap}[2002/05/04 
 v1.0 formatting captions inside multicols]%
%    \end{macrocode}
% The package requires the \textsf{ifthen} package to test some conditions.
%    \begin{macrocode}
\RequirePackage{ifthen}%
%    \end{macrocode}
% We now define the |\@mcaptype| command which will switch between the normal font and the Sans. Next, we 
% define the default (|Sans|) and the the |normal| option, together with a warning for any unknown option to the package.
%    \begin{macrocode}
\newcommand*{\@mcaptype}{\@empty}%
\DeclareOption{Sans}%
  {\renewcommand*{\@mcaptype}{\textsf}}%
\DeclareOption{normal}%
  {\renewcommand*{\@mcaptype}{\relax}}%
\DeclareOption*{%
 \PackageWarning{multicap}{Unknown option 
 `\CurrentOption'.\MessageBreak
 Going into default mode}%
}%
\ExecuteOptions{Sans}%
\ProcessOptions*%
%    \end{macrocode}
% The counter variables |`mcapsize'| and |`mcapskip'| which go to first and second argument of the |\fontsize| command 
% respectively are defined. The |\abvmcapskip| and |\blwmcapskip| lengths are defined too and their default values 
% are being given.
%
%    \begin{macrocode}
\newcounter{mcapsize}%
\newcounter{mcapskip}%
\newlength{\abvmcapskip}%
\newlength{\blwmcapskip}%
\setlength{\abvmcapskip}{10\p@}%
\setlength{\blwmcapskip}{\parsep}%
%    \end{macrocode}
% We define one box for each command |\mfcaption|, |\mtcaption|\ and |\caption|  to make some length tests later. 
%    \begin{macrocode}
\newsavebox{\mf@tempbox}%                                       
\newsavebox{\mt@tempbox}%                                       
\newsavebox{\@temp@box}%
%    \end{macrocode}
% We redefine the |center| environment so as to set the boolean |@cent@er| true when the environment starts and false when it ends.
%    \begin{macrocode}
\newboolean{@cent@er}%
\renewenvironment*{center}{%
 \setboolean{@cent@er}{true}\trivlist%
 \centering\item\relax}%
 {\setboolean{@cent@er}{false}\endtrivlist}%
%    \end{macrocode}
% The command |\@mcap@fs| checks weather the values of the |`mcapsize'| and |`mcapskip'| have change, sends them to |\fontsize| and 
% stores them in the |\@mcap@size| command.
%    \begin{macrocode} 
\DeclareRobustCommand*{\@mcap@size}{\relax}%
\newcommand*{\@mcap@fs}{%
 \ifthenelse{\equal{\value{mcapsize}}{0}%
  \and\equal{\value{mcapskip}}{0}}{}%
  {\renewcommand*{\@mcap@size}{%
    \fontsize{\value{mcapsize}}{%
     \value{mcapskip}%
    }%
    \selectfont%
   }%
  }%
}%
%    \end{macrocode}
% We are  now ready to define the |\mfcaption| command. After an initial skip of |\abvmcapskip| (\os{10}pt) we increment the |figure| 
% counter with |\refstepcounter| so that the references to the column figures will work correctly. We check with |\@mcap@fs|, 
% if the values of 
% the |`mcapsize'| and |`mcapskip'| counters have been changed  
%  and next we add the text specified in the |\mfcaption| command 
% to the list of figures.     
%    \begin{macrocode}
\newcommand*{\mfcaption}[2][\@empty]{%
 \\[\abvmcapskip]%
 \@mcap@fs%
 \refstepcounter{figure}%
 \ifthenelse%
  {\equal{\protect#1}{\protect\@empty}}%
  {\addcontentsline{lof}{figure}%
   {\protect\numberline{\thefigure}#2}}%
  {\addcontentsline{lof}{figure}%
   {\protect\numberline{\thefigure}#1}}%
%    \end{macrocode}
% After the mandatory argument \textit{long text} has been stored in |\mf@tempbox|,   
% we compare the width of the \textit{long text} with that of |\linewidth|. If the comments 
% of the figure (\textit{long text})   
% fit on a line, then they will be centered,  otherwise 
% they will be typeset as a paragraph with width |\linewidth|. 
%    \begin{macrocode}
 \sbox{\mf@tempbox}{%
  \@mcap@size\@mcaptype{%
   \figurename\ \textsc{\thefigure{}:} #2%
  }%
 }%
 \ifthenelse{\lengthtest{%
  \wd\mf@tempbox > \linewidth}}%
  {\begin{minipage}[t]{\linewidth}%
   \@mcap@size\@mcaptype{%
   \figurename\ \textsc{\thefigure{}:} #2}%
   \end{minipage}\par%
  }%
 {{\centering\usebox{\mf@tempbox}\\}}%
%    \end{macrocode}
% An skip of |\blwmcapskip| follows, if we are not inside a 
% |center| environment.
%    \begin{macrocode}
 \ifthenelse{\boolean{@cent@er}}{}%
  {\vspace{\blwmcapskip}}%
}%
%    \end{macrocode}
% The |\mtcaption| command is defined by  exact the same way.
%    \begin{macrocode}
\newcommand*{\mtcaption}[2][\@empty]{%
 \\[\abvmcapskip]%
 \@mcap@fs%
 \refstepcounter{table}%
 \ifthenelse%
  {\equal{\protect#1}{\protect\@empty}}%
  {\addcontentsline{lot}{table}%
   {\protect\numberline{\thetable}#2}}%
  {\addcontentsline{lot}{table}%
   {\protect\numberline{\thetable}#1}}%
 \sbox{\mt@tempbox}{%
  \@mcap@size\@mcaptype{%
   \tablename\ \textsc{\thetable{}:} #2%
  }%
 }%
 \ifthenelse{\lengthtest{%
  \wd\mt@tempbox > \linewidth}}%
  {\begin{minipage}[t]{\linewidth}%
   \@mcap@size\@mcaptype{%
   \tablename\ \textsc{\thetable{}:} #2}%
   \end{minipage}\par%
  }%
 {{\centering\usebox{\mt@tempbox}\\}}%
 \ifthenelse{\boolean{@cent@er}}{}%
  {\vspace{\blwmcapskip}}%
}%
%    \end{macrocode}
% Finally, we redefine the kernel |\@makecaption| command, so as |\caption| can have the same `properties' with the 
% |\mfcaption| and |\mtcaption| commands.
%    \begin{macrocode}
\renewcommand{\@makecaption}[2]{%
 \vspace{10\p@}%
 \@mcap@fs%
 \sbox{\@temp@box}%
  {\@mcap@size\@mcaptype{#1{}\textsc{:} #2}}%
 \ifthenelse{\lengthtest{%
  \wd\@temp@box > \linewidth}}%
  {\@mcap@size\@mcaptype{#1{}\textsc{:} #2}%
   \par%
  }%
  {\centering\@mcap@size\@mcaptype{%
   #1{}\textsc{:} #2%
   }%
  }%
}%
\endinput
%    \end{macrocode}
% \end{multicols}
% \listoftables
% \begin{thebibliography}{8}
% \bibitem{Canny}{M. Goossens, F. Mittelbach and A. Samarin, ``\textit{The \LaTeX\ Companion}'', Addison Wesley, 
% \oldstylenums{1994}.} 
% \bibitem{LTX}{The \textsc{\LaTeX3} Project, ``\textit{\LaTeXe\ for class and package writers}'', \os{1995}--\os{1998}.}
% \bibitem{MB}{Frank Mittelbach, ``\textit{An environment for multicolumn output}'', \textsc{ctan}, file \textit{multicol.dtx}, 
%  March, \os{2001}.}
% \bibitem{RB}{R. Bringhurst, ``\textit{The Elements of Typographic Style}'', Hartley \textit{\&} Marks, \os{1996}.}
% \end{thebibliography}
% \Finale
%% 
%% \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         \~}
%%
\endinput