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

% \iffalse meta-comment
%
% Copyright (C) 2005 by Wybo Dekker <wybo@servalys.nl>
% -------------------------------------------------------
%
% This file 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
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{ctable.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{ctable}
%<*package>
    [2008/04/13 v1.12 ctable package]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{carom,ctable,txfonts}
\usepackage[
   verbose,
   pdftex,
   paper=a4paper,
   bottom=30mm,
   nohead
]{geometry}
\usepackage{hyperref}
\graphicspath{{./doc/}}
\definecolor{vbgreen}{rgb}{0,.6,0}
\definecolor{B}{rgb}{0.77, 0.90, 0.96}
\definecolor{Y}{rgb}{1,1,.878}
\def\URL#1{http://www.ctan.org/tex-archive/help/Catalogue/entries/#1.html}
\def\REF#1{\href{\URL{#1}}{\texttt{#1}}}
\parindent0pt\parskip1ex
\newcommand{\ROW}[3]{\noindent\parskip0pt%
  %\fboxsep0pt
  \colorbox{#1}{%
    \parbox{.98\hsize}{%
      \rule{0pt}{1.5ex}\\
      \parbox{.5\hsize}{\includegraphics{#2}}
      \parbox{.5\hsize}{\centering{\includegraphics{#3}}}
      \\\rule{0pt}{1.5ex}
    }
  }\par
}
\AtBeginDocument{\RecordChanges}
\AtEndDocument{\PrintChanges}
\EnableCrossrefs
\hypersetup{
   colorlinks = true,
     pdftitle = The ctable package,
    pdfauthor = Wybo Dekker,
   pdfsubject = {Typesetting centered, right, and left aligned table and figure
                 floats, with many configuration options},
  pdfkeywords = {
                 table floats,
                 figure floats,
                 key=value options,
                 footnotes,
                 booktabs,
                 tabularx,
                 threeparttable
                },
  bookmarksopen
}
\begin{document}
\DocInput{ctable.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{348}
%
% \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         \~}
%
%
% \changes{v1.00}{2000/06/01}{First release.}
% \changes{v1.01}{2001/03/17}{Making use of booktabs package}
% \changes{v1.02}{2002/06/24}{Using keyval to reduce args to 4}
% \changes{v1.03}{2002/07/16}{Many syntactic corrections,
%                            thanks to Johannes Braams}
% \changes{v1.04}{2003/08/11}{Caption, if empty, will not be typeset
%                            rotate option added
%                            star option added to use table* and figure*
%                            environments}
% \changes{v1.06}{2004/03/20}{left, right and center options added
%                            frame{sep,rule,fg,bg} options added
%                            error in width-setting corrected}
% \changes{v1.05}{2003/10/03}{maxwidth option added}
% \changes{v1.06a}{2004/04/01}{two errors corrected:
%                            made setting fboxsep and fboxrule only temporary
%                            removed superfluous space after tabulars}
% \changes{v1.06b}{2004/06/19}{Added several % at eol to remove superfluous
%                             whitespace occurring sometimes}
% \changes{v1.07}{2005/08/09}{Added option sideways, option rotate now obsolete;
%                            added option captionskip}
% \changes{v1.08}{2006/04/10}{Standardized file setup following
%                            http://www.ctan.org/tex-archive/info/dtxtut/dtxtut.pdf
%                            mincapwidth option added
%                            Moved newdimen definition outside ctable macro
%                           }
% \changes{v1.09}{2007/03/04}{Added option nosuper;
%                            corrected incorrect positioning when table is wider than
%                            mincapwidth}
% \changes{v1.10}{2007/08/17}{Footnote markers now stay superscript with nosuper.
%                             Documentation: added many examples for the options.
%                             Corrected some unwanted white space in captions.
%                             Caption package included to correct booktabs
%                             errors in caption position. And for later use of
%                             its facilities. *Captionskip option redefined*: 0pt
%                             value now corresponds to LaTeX defaults
%                            }
% \changes{v1.11}{2007/09/07}{Added some percent signs at EOL to prevent
%                             whitespace, 
%                             Removed xspace usage - caused overfull badness
%                            }
% \changes{v1.12}{2008/04/12}{Option notespar added}
%
% \GetFileInfo{ctable.dtx}
%
% \DoNotIndex{     \newcommand,   \\,             \,,
% \def,            \definecolor,  \hbox,          \raggedright,
% \else,           \ifdim,        \sbox,          \empty,
% \ifx,            \setkeys,      \end,           \label,
% \specialrule,    \fboxrule,     \let,           \tabularnewline,
% \PackageError,   \fboxsep,      \newbox,        \textit,
% \PackageWarning, \fcolorbox,    \newcolumntype, \usebox,
% \RequirePackage, \fi,           \newdimen,      \vspace,
% \begin,          \footnotesize, \normalfont,    \wd,
% \define@key,
% }
%
% \title{The \textsf{ctable} package\thanks{This document
%   corresponds to \textsf{ctable}~\fileversion, dated \filedate.}}
% \author{Wybo Dekker \\ \texttt{wybo@servalys.nl}}
%
% \maketitle
% \begin{abstract}\noindent
% The \texttt{ctable} package provides a \texttt{ctable}
% command for the typesetting of table and figure floats. You will
% not need to type the usual nested begin...end sequences, as
% \texttt{ctable} is a command, not an environment. \texttt{ctable}
% has only 4 arguments, but the optional first one may hold many
% \textsl{key=value} pairs and makes \texttt{ctable} very flexible
% and extensible. It uses Simon Fear's \REF{booktabs} package for
% better vertical spacing around horizontal rules and it provides
% facilities for making table footnotes.
% \end{abstract}
%
% \section{Purpose} The |ctable| package lets you easily typeset
% captioned table and figure floats with optional
% footnotes. Both caption and footnotes will normally be forced within the
% width of the table.
% If the width of the table is specified, then \REF{tabularx} will be used
% to typeset it, and one or more |X| column specifiers should be specified.
% Otherwise tabular will be used.
%
% This package defines the commands |\ctable|,
% |\tnote| and |\tmark|, as well as four |\tabularnewline| generating
% commands. The latter generate reasonable amounts of whitespace
% around horizontal rules and are also useful for tabulars outside
% this package.
%
% Since the |ctable| package imports the \REF{array} and \REF{booktabs}
% packages, all commands from those packages are available as well.
%
% Note that, in line with the comments that Simon Fear made
% describing his \REF{booktabs} package, vertical rules for column
% separation can be produced with |\ctable|, but no provisions are
% made to have them make contact with horizontal rules.
%
% \section{Usage}
% \DescribeMacro{\ctable}
% |\ctable| is called with 4 parameters, of which the first is optional: \\
%
% |\ctable[options]       % key=value,...|\\
% |       {coldefs}       % for \begin{tabular}|\\
% |       {foottable}     % zero or more \tnote commands (see below)|\\
% |       {table rows}    % rows for the table|\\
%
% Options are given as key=value pairs, separated by comma's.
% Extra comma's, including one behind the last pair, don't hurt.
% Arguments to option should be put between braces if they contain
% comma's or equals signs.
% Currently the following option keys have been defined:
% \\[2ex]
% \begin{tabularx}{\hsize}{@{}lX@{}}
% |caption={...}|& table caption; the braces are needed only if your
%                   caption contains a comma or an equals sign.\NN[1ex]
%
% |cap={...}|    & for a short caption to go to the |\listoftables|.\NN[1ex]
%
% |captionskip=...| & moves the caption relative to the table;
%                  the default is |0ex|, which puts captions at
%                  their default \LaTeX\ positions: a top
%                  caption's baseline at |1ex| above the top rule
%                  position of the table and a bottom caption's
%                  baseline at |4ex| below the bottom rule
%                  position.\NN[1ex]
%
% |mincapwidth=...| & sets the minimum width of the float. Without
%                  this option, the width is set to that of the
%                  tabular, and the caption and footnotes are
%                  typeset within that width. This may be a
%                  problem with very narrow tables; |mincapwidth|
%                  can then be used to give the float a minimum
%                  width. The tabular will be centered in it.\NN[1ex]
%
% |pos=...|      & float position, default: |tbp|.\NN[1ex]
%
% |label=...|    & for |\label|\NN[1ex]
%
% |width=...|    & \REF{tabularx} will be used to typeset the table at the
%                  specified width\,---\,one or more |X| column
%                  specifiers must be provided.\NN[1ex]
%
% |maxwidth=...| & like the \textsl{width} option, but any |X| column
%                  specifiers will be replaced with |l| if the resulting
%                  table width would thus stay within the specified
%                  maximum width. This is especially useful where the
%                  \LaTeX\ source is generated by a script.\NN[1ex]
%
% |center|       & center the table in the available text width; this is
%                  the default.\NN[1ex]
%
% |left|         & left align the table in the available text width.\NN[1ex]
%
% |right|        & right align the table in the available text width.\NN[1ex]
%
% |figure|       & produce a figure float instead of a table float.\NN[1ex]
%
% |botcap|       & put the caption at the bottom of the float instead
%                  of on top of it.\NN[1ex]
%
% |sideways|     & rotate table or figure by 90 degrees anticlockwise
%                  and put it on a separate page. With the twoside option
%                  for the standard \LaTeX\ document classes, rotation
%                  will be -90 on even pages. If you use this option,
%                  the |pos| option is not allowed.\NN[1ex]
%
% |star|         & use the starred versions of the |table| and |figure|
%                  environments, which place the float over two columns
%                  when the |twocolumn| option or the |\twocolumn|
%                  command is active.\NN[1ex]
%
% |nosuper|      & in the footnote table, typeset footnote markers on
%                  the line, instead of superscripted.\NN[1ex]
%
% |notespar|     & typeset footnotes in a parapgraph instead of in a table.\NN[1ex]
%
% |framerule=...|& draw a frame around the table with the given rule
%                  thickness. The default is |0pt|, so that no frame
%                  will be seen.\NN[1ex]
%
% |framesep=...| & set the distance between the frame and the table
%                 to the given dimension. The default is |0pt|.\NN[1ex]
%
% |framefg=|\sl r g b & set the foreground color of the frame (the
%                 rule color) to the given triplet of
%                 \textsl{rgb}-values. The values should be numbers
%                 between 0 and 1. The default is |0 0 0| (black).\NN[1ex]
%
% |framebg=|\sl r g b & set the background color of the frame (the
%                 color inside the frame) to the given triplet of
%                 \textsl{rgb}-values. The values should be numbers
%                 between 0 and 1. The default is |1 1 1| (white).\NN[1ex]
% \end{tabularx}
% \\[2ex]
% The footnotes are placed under the table, without a rule.
% You therefore probably will want to use the |\LL| (last line)
% command if you use footnotes.
% \DescribeMacro{\tnote}
% |\tnote[label]{footnote text}| places {\footnotesize
% \textsuperscript{\normalfont\textit{label}}\,footnote text}
% under the table.
% Can only be used in the foottable parameter described above. The
% label is optional, the default label is a single $a$. For more
% detailed control, you can also replace this command with something
% like |labeltext&footnotetext\NN|.
% \par
% \DescribeMacro{\tmark}
% |\tmark[label]| this command places the superscripted label in the
% table. It is equivalent with |$^{label}$|.
% The label is optional, the default label is a single $a$.
% \par
% The newline generating commands are a combination of
% |\tabularnewline| and zero or one of \REF{booktabs} |\toprule|,
% |\midrule| or |\bottomrule|. These combinations have been made, and
% short names have been defined, because source texts for complex
% tables often become very crowded:
% \par
% \DescribeMacro{\NN} Normal Newline, generates just a normal new line.
% An optional dimen parameter inserts extra vertical space under the
% line.
% \par
% \DescribeMacro{\FL} First Line, generates a new line and a thick
% rule with some extra space under it.
% An optional dimen parameter sets the line width; the default is 0.08em.
% \par
% \DescribeMacro{\ML} Middle Line: generates a new line and a thin
% rule with some extra space over and under it.
% An optional dimen parameter sets the line width; the default is 0.05em.
% \par
% \DescribeMacro{\LL} Last Line:  generates a new line and a thick
% rule with some extra space over it.
% An optional dimen parameter sets the line width; the default is 0.08em.
% \par
% These macros can be used outside |\ctable| constructs.
% \par
% Finally, for completeness, here are some of \REF{booktabs}' commands
% that may be useful:
% \par
% \DescribeMacro{\toprule} |\toprule[<wd>]|
% where |<wd>| is the optional thinkness of the rule.
% \par
% \DescribeMacro{\midrule} |\midrule[<wd>]|.
% \par
% \DescribeMacro{\bottomrule} |\bottomrule[<wd>]|.
% \par
% \DescribeMacro{\cmidrule} |\cmidrule[<wd>](<trim>){a-b}|
% where |<trim>| can be |r|, |l|, or |rl|
% and the rule is drawn over columns |a| through |b|.
% \par
% \DescribeMacro{\morecmidrules} |\morecmidrules|
% must be used to separate two successive cmidrules.
% \par
% \DescribeMacro{\addlinespace} |\addlinespace[<wd>]|
% inserts extra space between rows.
% \par
% \DescribeMacro{\specialrule}
% |\specialrule{<wd>}{<abovespace>}{<belowspace>}|.
% \par
% See the \REF{booktabs} documentation for details.
%
% \subsection{The width and maxwidth options}
% When \LaTeX-sources containing tables are generated automatically by a
% script, it is often not known in advance what the maximum size of an
% |l|~column will be. A good solution for this is to use an |X|~specifier,
% typesetteing the table at the text width with the \REF{tabularx} package.
% However, this will result in too much white space in cases where the
% column contains small texts only. This problem can be solved by using
% the maxwidth option instead of the width option. The |X|~specifiers will
% then be replaced with |l| as long as the width of the resulting table
% stays with the specified maximum width.
%
% \section{Examples}
% Table~\ref{nowidth} is an example taken from the related package
% \REF{threeparttable} by Donald Arseneau, with an extra footnote.
% It was typeset with:
% \color{vbgreen}
% \begin{verbatim}
% \ctable[
%    cap     = The Skewing Angles,
%    caption = The Skewing Angles ($\beta$) for
%              $\fam0 Mu(H)+X_2$ and $\fam0 Mu(H)+HX$~\tmark,
%    label   = nowidth,
% ]{rlcc}{
%    \tnote{for the abstraction reaction,
%           $\fam0 Mu+HX \rightarrow MuH+X$.}
%    \tnote[b]{1 degree${} = \pi/180$ radians.}
%    \tnote[c]{this is a particularly long note, showing that
%              footnotes are set in raggedright mode as we don't like
%              hyphenation in table footnotes.}
% }{                                                          \FL
%   &            & $\fam0 H(Mu)+F_2$     & $\fam0 H(Mu)+Cl_2$ \ML
%   &$\beta$(H)  & $80.9^\circ$\tmark[b] & $83.2^\circ$       \NN
%   &$\beta$(Mu) & $86.7^\circ$          & $87.7^\circ$       \LL
% }
% \end{verbatim}
% \color{black}
% \ctable[
%    cap     = The Skewing Angles,
%    caption = The Skewing Angles ($\beta$) for
%              $\fam0 Mu(H)+X_2$ and $\fam0 Mu(H)+HX$~\tmark,
%    label   = nowidth,
% ]{rlcc}{
%    \tnote{for the abstraction reaction,
%           $\fam0 Mu+HX \rightarrow MuH+X$.}
%    \tnote[b]{1 degree${} = \pi/180$ radians.}
%    \tnote[c]{this is a particularly long note, showing that
%              footnotes are set in raggedright mode as we don't like
%              hyphenation in table footnotes.}
% }{                                                          \FL
%   &            & $\fam0 H(Mu)+F_2$     & $\fam0 H(Mu)+Cl_2$ \ML
%   &$\beta$(H)  & $80.9^\circ$\tmark[b] & $83.2^\circ$       \NN
%   &$\beta$(Mu) & $86.7^\circ$          & $87.7^\circ$       \LL
% }
% Table~\ref{width} is an example with a width specification,
% taken from the \REF{tabularx} documentation, with the vertical rules
% removed. 
% By using the trimming parameters of the \REF{booktabs} |\cmidrule|
% command, some of the horizontal splitting was regained.
% The |left| option left aligns the table. It was typeset with:
% \color{vbgreen}
% \begin{verbatim}
% \ctable[
%    caption = Example with a specified width of 100mm,
%    label   = width,
%    width   = 100mm,
%    pos     = h,
%    left
% ]{c>{\raggedright}Xc>{\raggedright}X}{
%    \tnote{footnotes are placed under the table}
% }{                                                         \FL
%    \multicolumn{4}{c}{Example using tabularx}              \ML
%    \multicolumn{2}{c}{Multicolumn entry!} & THREE & FOUR   \NN
%        \cmidrule(r){1-2}\cmidrule(rl){3-3}\cmidrule(l){4-4}
%    one&
%    The width of this column depends on the width of the
%        table.\tmark &
%    three&
%    Column four will act in the same way as
%    column two, with the same width.                        \LL
% }
% \end{verbatim}
% \color{black}
% \ctable[
%    caption = Example with a specified width of 100mm,
%    label   = width,
%    width   = 100mm,
%    pos     = h,
%    left
% ]{c>{\raggedright}Xc>{\raggedright}X}{
%    \tnote{footnotes are placed under the table}
% }{                                                         \FL
%    \multicolumn{4}{c}{Example using tabularx}              \ML
%    \multicolumn{2}{c}{Multicolumn entry!} & THREE & FOUR   \NN
%        \cmidrule(r){1-2}\cmidrule(rl){3-3}\cmidrule(l){4-4}
%    one&
%    The width of this column depends on the width of the
%        table.\tmark &
%    three&
%    Column four will act in the same way as
%    column two, with the same width.                        \LL
% }
%
% Figures, even single ones, are always put in tabular cells. This is not
% particularly handy for single pictures, but it eases the construction
% of arrays of pictures, including sub-captions, delineation, and spacing.
% Figure~\ref{fig} shows a figure that has been produced with the |\ctable|
% command, in combination with
% |\usepackage|\{%
% \href{http://tug.ctan.org/obsolete/macros/latex/contrib/xymtex/carom.sty}{\texttt{carom}}\}
% it has been typeset with:
% \color{vbgreen}
% \begin{verbatim}
% \ctable[
%    figure,
%    botcap,
%    pos       = h,
%    caption   = The di- and tri-bromobenzenes,
%    label     = fig,
%    framebg   = .53 .81 .92,
%    framerule = 1pt,
%    framesep  = 4ex,
% ]{ccc}{}{                     \NN
%    \bzdrv{1==Br;2==Br}&
%    \bzdrv{1==Br;3==Br}&
%    \bzdrv{1==Br;4==Br}        \NN
%    1,2 & 1,3 & 1,4            \NN[3ex]
%    \bzdrv{1==Br;2==Br;3==Br}&
%    \bzdrv{1==Br;2==Br;4==Br}&
%    \bzdrv{1==Br;3==Br;5==Br}  \NN
%    1,2,3 & 1,2,4 & 1,3,5
% }
% \end{verbatim}
% \color{black}
% \ctable[
%    figure,
%    botcap,
%    pos       = h,
%    caption   = The di- and tri-bromobenzenes,
%    label     = fig,
%    framebg   = .53 .81 .92,
%    framerule = 1pt,
%    framesep  = 4ex,
% ]{ccc}{}{                     \NN
%    \bzdrv{1==Br;2==Br}&
%    \bzdrv{1==Br;3==Br}&
%    \bzdrv{1==Br;4==Br}        \NN
%    1,2 & 1,3 & 1,4            \NN[3ex]
%    \bzdrv{1==Br;2==Br;3==Br}&
%    \bzdrv{1==Br;2==Br;4==Br}&
%    \bzdrv{1==Br;3==Br;5==Br}  \NN
%    1,2,3 & 1,2,4 & 1,3,5
% }
% (The excessive whitespace at the left of the figure is caused by
% the bounding boxes generated by the |carom| package.)
%
% \section{Option examples}
% In the following, small examples will be shown illustrating the effect of
% options. In the left column the relevant part of the source is shown, in the
% right column you see the result. In most cases you see a standard example on a
% light yellow background, followed by one or more variations on a light blue
% background. Where necessary, the example will show boxes to indicate the page
% and the text body.
%
% \newpage
% \subsection{\ttfamily\bfseries center, left, right}
% These options align the float in the page; the default is |center|:
% \medskip\\
% \ROW{Y}{s02k}{02k}
% \ROW{B}{s02l}{02l}
% \ROW{B}{s02m}{02m}
% 
% \subsection{\ttfamily\bfseries nosuper}
% Footnote markers in |ctable| are typeset superscripted by default. Use the
% |nosuper| option to place them on the base line:
% \medskip\\
% \ROW{Y}{s07a}{07a}
% \ROW{B}{s07b}{07b}
% 
% \subsection{\ttfamily\bfseries notespar}
% Footnotes in |ctable| are typeset in a paragraph, instead of a table: 
% \medskip\\
% \ROW{Y}{s12a}{12a}
% \ROW{B}{s12b}{12b}
% 
% \newpage
% \subsection{\ttfamily\bfseries mincapwidth}
% |ctable| forces caption and footnotes to stay within the width of the table.
% Sometimes, however, tables are so narrow, that this is not really what you want.
% In such cases, use the |mincapwidth| option to give caption and footnotes some
% extra room:
% \medskip\\
% \ROW{Y}{s05a}{05a}
% \ROW{B}{s05b}{05b}
% \medskip
% You can set |mincapwidth| to a large value, say |\hsize|, if you want a one-line
% caption. Note, however, that this may influence the horizontal positioning of
% the table: values larger than |\hsize| will move a centered table out of the
% center, a value of |\hsize| will prevent the |left| and |right| options to do
% their work, because the table is already captured between the left and right
% margins.
% 
% \subsection{\ttfamily\bfseries maxwidth}
% When \LaTeX-sources containing tables are generated automatically by a
% script, it is often not known in advance what the maximum size of an |l|
% column will be. A good solution for this is to use an |X| specifier,
% typesetting the table at the text width with the \REF{tabularx} package.
% However, this will result in too much white space in cases where the
% column contains small texts only. This problem can be solved by using
% the maxwidth option instead of the width option. The |X| specifiers will
% then be replaced with |l| as long as the width of the resulting table
% stays with the specified maximum width.
% \medskip\\
% \ROW{Y}{s06a}{06a}
% \ROW{B}{s06b}{06b}
% 
% \newpage
% \subsection{\ttfamily\bfseries framerule}
% The following examples show the use of frames and backgrounds. Every table
% is typeset by |ctable| with a frame around it, but the frame is, by default,
% drawn with a zero width line, and is therefore invisible. You can make it
% visible by either changing the linewidth to a positive value or by giving it a
% background color, which will be used to fill the frame.
% 
% Here is a simple table without a frame, followed by one with a red, |1pt| thick
% frame:
% \medskip\\
% \ROW{Y}{s08a}{08a}
% \ROW{B}{s08b}{08b}
% \medskip
% As you see, the frame fits closely to the first (|\FL|) and last (|\LL|) table
% lines. This can be a reason to either remove those lines, or to introduce some
% whitespace between the frame and the table with the |framesep| option:
% \medskip\\
% \ROW{B}{s09b}{09b}
% \medskip
% And finally, we could also frame the table by giving it a, say, yellow backgound
% instead of a red frame line, or even do both:
% \medskip\\
% \ROW{Y}{s10a}{10a}
% \ROW{B}{s10b}{10b}
% 
% \newpage
% \subsection{\ttfamily\bfseries captionskip}
% The distance between a top caption and the table is \texttt{2ex},
% but it can be varied with \texttt{captionskip}:
% \medskip\\
% \ROW{Y}{s03a}{03a}
% \ROW{B}{s03b}{03b}
% \medskip
% This works for bottom caption, too:
% \medskip\\
% \ROW{Y}{s04a}{04a}
% \ROW{B}{s04b}{04b}
% 
% \subsection{\ttfamily\bfseries figure, botcap}
% By default, |ctable| generates a table float, but with the |figure| option, a
% figure float is generated instead. The caption stays on top, so if you are
% accustomed to have bottom caption for your figures, you will probably also need
% the |botcap| option:
% \medskip\\
% \ROW{Y}{s01a}{01a}
% \ROW{B}{s01b}{01b}
% 
% \newpage
% \subsection{\ttfamily\bfseries sideways}
% The |sideways| option creates a landscape table with its head pointing at the
% spine\,---\,when the documentclass' twoside option has been used, that is. The
% following examples show the effect of the |sideways| option, first on page one,
% then on page 2. Note that the |caption| option has not been used, so no caption
% appears:
% \medskip\\
% \ROW{Y}{s11k}{11k}
% \ROW{B}{s11l}{11l}
% \ROW{B}{s11m}{11m}
% 
% \newpage
% \StopEventually{}
%
% \section{Implementation}
% \begin{macrocode}
\RequirePackage{color,xkeyval,array,tabularx,booktabs,rotating,caption}
\def\NN{\tabularnewline}
\def\FL{\toprule}
\def\ML{\NN\midrule}
\def\LL{\NN\bottomrule}
\def\@ctblfgcolor#1 #2 #3={\definecolor{@ctblframefg}{rgb}{#1,#2,#3}}
\def\@ctblbgcolor#1 #2 #3={\definecolor{@ctblframebg}{rgb}{#1,#2,#3}}
\let\@cttextsuperscript\@textsuperscript
\def\@ctcopy#1{\footnotesize #1}
\newdimen\@ctblframesep
\newdimen\@ctblframerule
\newdimen\@ctblwidth
\newdimen\@ctblcaptionskip
\newdimen\@ctblmaxwidth
\newdimen\@ctblmincapwidth
\newdimen\@ctblw % the final width
\newdimen\@ctblfloatwidth
\newdimen\@ctbloldsep
\newdimen\@ctbloldrule
%    \end{macrocode}
%    Allocate box registers so that we can determine the widths of the
%    tables
%    \begin{macrocode}
\newbox\ctbl@t          % tabular saved and measured here
%    \end{macrocode}
% Option setting commands from keyval. The table position (here, top,
% bottom, page) gets a special treatment, since \LaTeX\ does not expand
% commands there. So instead of putting things like \texttt{tbp} in a
% command like |\@ctblbegin| we put
% |\begin{table}[tbp]| in it.
%    \begin{macrocode}
\define@key{ctbl}{caption}{\def\@ctblcaption{#1}}
\define@key{ctbl}{cap}{\def\@ctblcap{#1}}
\define@key{ctbl}{label}{\def\@ctbllabel{#1}}
\define@key{ctbl}{pos}{\def\@ctblpos{#1}\def\@ctblbegin{\@ctblbeg[#1]}}
\define@key{ctbl}{width}{\@ctblwidth=#1}
\define@key{ctbl}{maxwidth}{\@ctblmaxwidth=#1}
\define@key{ctbl}{mincapwidth}{\@ctblmincapwidth=#1}
\define@key{ctbl}{botcap}[]{\def\@ctblbotcap{1}}
\define@key{ctbl}{sideways}[]{\def\@ctblsideways{sideways}}
\define@key{ctbl}{rotate}[]{\def\@ctblsideways{sideways}
                            \PackageWarning{ctable}{
                              using obsolete option 'rotate', use 'sideways' instead}
                            }
\define@key{ctbl}{figure}[]{\def\@ctbltaborfig{figure}}
\define@key{ctbl}{center}[]{\def\@ctblalign{center}}
\define@key{ctbl}{right}[]{\def\@ctblalign{flushright}}
\define@key{ctbl}{left}[]{\def\@ctblalign{flushleft}}
\define@key{ctbl}{star}[]{\def\@ctblstarred {*}}
\define@key{ctbl}{framerule}{\@ctblframerule=#1}
\define@key{ctbl}{framesep}{\@ctblframesep=#1}
\define@key{ctbl}{framefg}{\@ctblfgcolor#1=}
\define@key{ctbl}{framebg}{\@ctblbgcolor#1=}
\define@key{ctbl}{captionskip}{\@ctblcaptionskip=#1}
\define@key{ctbl}{nosuper}[]{\let\@cttextsuperscript\@ctcopy}
\define@key{ctbl}{notespar}[]{\def\@ctblnotespar{1}}
%    \end{macrocode}
% a caption will only be generated if the \textsl{caption} option was used:
%    \begin{macrocode}
\def\@ctblCaption{
   \ifx\@ctblcap\empty\let\@ctblcap\@ctblcaption\fi
   \ifx\@ctblcaption\empty\else
      \caption[\@ctblcap]{\label{\@ctbllabel}\@ctblcaption}
   \fi
}
\def\@ctblframe#1#2#3{%
   \@ctbloldsep\fboxsep\fboxsep\@ctblframesep%
   \@ctbloldrule\fboxrule\fboxrule\@ctblframerule%
   \fcolorbox{#1}{#2}{\fboxsep\@ctbloldsep\fboxrule\@ctbloldrule #3}%
}
\newcommand{\tnote}[2][a]{%
   \ifx\@ctblnotespar\empty%
     \hbox{\@cttextsuperscript{\normalfont\textit{#1}}}&#2\NN
   \else%
     \@cttextsuperscript{\normalfont\textit{#1}}\,#2
   \fi
}
\newcommand{\tmark}[1][a]{%
   \hbox{\textsuperscript{\normalfont\textit{#1}}}}
\newcommand{\ctable}[4][]{%
   \def\@ctbltaborfig{table}%
   \def\@ctblalign   {center}%
   \def\@ctblsideways  {}%
   \def\@ctblpos     {}%
   \def\@ctblcaption {}%
   \def\@ctblcap     {}%
   \def\@ctbllabel   {}%
   \def\@ctblbeg     {\begin{\@ctblsideways\@ctbltaborfig\@ctblstarred}}%
   \def\@ctblbegin   {\@ctblbeg}%
   \def\@ctblend     {\end{\@ctblsideways\@ctbltaborfig\@ctblstarred}}%
   \def\@ctblbotcap  {}%
   \def\@ctblstarred {}%
   \def\@ctblnotespar{}%
   \definecolor{@ctblframefg}{rgb}{0,0,0}%
   \definecolor{@ctblframebg}{rgb}{1,1,1}%
   \@ctblframerule0pt
   \@ctblcaptionskip0ex
   \@ctblframesep0pt
   \@ctblwidth=0pt
   \@ctblmaxwidth=0pt
   \@ctblmincapwidth=0pt
   \setkeys{ctbl}{#1}%
%    \end{macrocode}
% It makes no sense to use \textsl{width} together with \textsl{maxwidth} or
% \textsl{pos} together with \textsl{sideways}
%    \begin{macrocode}
   \ifdim\@ctblwidth=0pt\else
      \ifdim\@ctblmaxwidth=0pt\else
         \PackageError{ctable}{
            You may not use the width and maxwidth options together}{
            Use either width or maxwidth}
      \fi
   \fi
   \ifx\@ctblpos\empty\else
      \ifx\@ctblsideways\empty\else
      \PackageError{ctable}{
         You may not use the pos and sideways options together}{
         Rotated tables and figures are always typeset on a separate page}
      \fi
   \fi
%    \end{macrocode}
% It makes no sense to label a captionless table, because the label can't
% be placed, leaving the user wondering why references to the table get a ??
%    \begin{macrocode}
   \ifx\@ctblcaption\empty
      \ifx\@ctbllabel\empty\else
         \PackageError{ctable}{
            You may not label a captionless table}{
            Such a label can't be referenced}
      \fi
   \fi
   \newcolumntype{Y}{X}% save the X type
%    \end{macrocode}
% save the table contents in a box, so we can determine its width,
% initially, save the table typeset with the tabular environment:
%    \begin{macrocode}
   \sbox\ctbl@t{%
      \newcolumntype{X}{l}% temporarily make  type X = l
      \@ctblframe{@ctblframefg}{@ctblframebg}{%
         \begin{tabular}{#2}
            #4%
         \end{tabular}%
      }%
   }%
%    \end{macrocode}
% then look if we'll need the tabularx environment:
%    \begin{macrocode}
   \newif\if@ctblusex\@ctblusexfalse
   \ifdim\@ctblmaxwidth=0pt
      \ifdim\@ctblwidth=0pt
      \else
         \@ctblusextrue
      \fi
   \else
      \ifdim\wd\ctbl@t>\@ctblmaxwidth
         \@ctblusextrue
      \fi
   \fi
%
% if so, replace tabular with tabularx:
%
   \if@ctblusex
      \sbox\ctbl@t{%
         \newcolumntype{X}{Y}% restore X
         \@ctblframe{@ctblframefg}{@ctblframebg}{%
            \begin{tabularx}{\ifdim\@ctblwidth>0pt\@ctblwidth\else\@ctblmaxwidth\fi}{#2}
               #4%
            \end{tabularx}%
         }%
      }%
   \fi
%    \end{macrocode}
% the |ctbl@t| box now contains the table as we want to typeset it;
% determine its width:
%    \begin{macrocode}
   \@ctblw=\wd\ctbl@t
%    \end{macrocode}
% Now find the width of the float, |\@ctblfloatwidth|; everything in it will
% be centered within that width.
% Normally we'll use the width of the table, |\@ctblw|, but if the
% mincapwidth, |\@ctblmincapwidth| was set wider than the table, that will be used:
%    \begin{macrocode}
   \@ctblfloatwidth=\ifdim\@ctblmincapwidth>\@ctblw
      \@ctblmincapwidth
   \else
      \@ctblw
   \fi
%    \end{macrocode}
% |\@ctblbegin| is now defined as something like |\begin{table}[tbp]|.
%    \begin{macrocode}
   \@ctblbegin
      \begin{\@ctblalign}
         \begin{minipage}{\@ctblfloatwidth}\parindent0pt
            \ifx\@ctblbotcap\empty\@ctblCaption\vskip\@ctblcaptionskip\fi
            \centering{\usebox\ctbl@t} % insert the tabular
            \def\@ctblfootnotes{#3}%
            \ifx#3\empty\else % append footnotes, if any
               \ifx\@ctblnotespar\empty%
                  \\
                  \begin{tabularx}{\hsize}{r@{\,}>{\footnotesize\raggedright}X}
                     #3%
                  \end{tabularx}%
               \else%
                  \\[.2ex]
                  \begin{minipage}{\hsize}\footnotesize\raggedright%
                     #3%
                  \end{minipage}%
               \fi
            \fi
            \ifx\@ctblbotcap\empty\else\vskip\@ctblcaptionskip\@ctblCaption\fi
         \end{minipage}
      \end{\@ctblalign}
   \@ctblend
}
%    \end{macrocode}
% \Finale
\endinput
$Id: ctable.dtx,v 1.58 2008/04/13 15:58:14 wybo Exp $