% \iffalse
%%
%% (C) Copyright 1999-2000 Frank Mittelbach, David Carlisle, Chris Rowley
%% All rights reserved.
%%
%% Not for general distribution. In its present form it is not allowed
%% to put this package onto CD or an archive without consulting the
%% the authors.
%% 
% \fi
%

%    \begin{macrocode}
\def\@tempa#1: #2.dtx,v #3 #4 #5 #6 #7${
  \ProvidesPackage{#2}[#4 #3 #5 #6]}
\@tempa$Id: xo-capt.dtx,v 1.13 2000/08/11 07:14:03 latex3 Exp $
%    \end{macrocode}
%
% Ignore white space in this package.
%    \begin{macrocode}
\IgnoreWhiteSpace
%    \end{macrocode}
%
%
% \subsection{Modifying the caption command}
%
% \begin{macro}{\@caption}
% |\caption| just saves its main argument in a token register. It also
% has |\unskip| and |\ignorespaces| to cope with hmode.
% The format of the token register is:\\
% \marg{type}\marg{number}\marg{caption text}\marg{extra info}\\
% The \meta{type} is something like `figure', used to generate the
% relevant command names. \meta{number} is the fully expanded version of
% |\the|\ldots. The last group is unused by the current definition
% but extended packages may use it to pass extra information to the 
% float handler, as required.
%    \begin{macrocode}
\def\caption{\@dblarg{\@caption\float@type}}

\long\def\@caption#1[#2]#3{%
  \unskip
%    \end{macrocode}
%    We use the old \LaTeX{} interface with |\addcontentsline| for the
%    moment.\footnote{FIX!!}
%    \begin{macrocode}
  \addcontentsline{\csname toc@extension@#1\endcsname}{#1}
%    \end{macrocode}
%    The counter used is not |#1| but given by (|\foat@counter|) which
%    should perhaps be passed along but isn't:
%    \begin{macrocode}
    {\protect\numberline{\csname the\float@counter\endcsname}
    {\ignorespaces #2}}
  \global\toks\@currbox{#3}
  \ignorespaces
  }
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Adding captions to float boxes}
%
% This should really be a template instance.
% Must \emph{copy} the float body in |\this@float@box|
% into |\this@captioned@float| adding the caption text.
% May use |\this@area|, |\this@area@col@number| and other information, to be
% determined \ldots
%
% \begin{macro}{\append@caption@to@float}
%    Combine float body and caption of the current float (``this
%    float'') and store it in |\this@captioned@float|.
%    \begin{macrocode}
\def\append@caption@to@float{
  \typeset@some@floatbox
      \this@type\this@area
      \this@float@box{\csname caption@\this@type\endcsname}
      \this@usercnt\this@caption\this@span@number
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\append@here@caption@to@float}
%    Combine float body and caption of the current here float and
%    store it in |\this@captioned@float|.
%    \begin{macrocode}
\def\append@here@caption@to@float{
  \typeset@some@floatbox
      \here@type{h\the\curr@col@count 1}
      \here@float@box{\csname caption@\here@type\endcsname}
      \here@usercnt\here@caption\here@span@number
}
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\typeset@this@float@and@caption}
%    Combine float body and caption of the current float (``this
%    float'') and output it into the current list.
%    \begin{macrocode}
\def\typeset@this@float@and@caption{
  \append@caption@to@float
  \box\this@captioned@float
}
%    \end{macrocode}
% \end{macro}
%
%
%
% \section{Some primitive templates for testing}
%
% prove of concept only --- not even prototype
%    
%
% \begin{macro}{\typeset@some@floatbox}
%    The macro |\typeset@some@floatbox| take 7 arguments as follows:
%    \begin{description}
%    \item[type] type of the float to be typeset
%    \item[area] area in which to format the float
%    \item[floatbody box] box register in which the body of the float
%       is stored
%    \item[caption heading] fixed text like ``Figure''
%    \item[caption number] caption number of the float
%    \item[caption text] caption text of the float
%    \item[span count] span count (normally deducable from the area
%    but\ldots
%    \end{description}
%    The first two arguments are used to decide which formatting
%    instance to call, the remaining arguments are passed to that
%    instance.
%
%    The logic is (at the moment) as follows: if a template instance
%    (type \texttt{buildfloat}) with the name
%    \meta{type}|-|\meta{area}\footnote{The ``here'' areas are
%    denoted as \texttt{h}\meta{col}\texttt{1}.}
%    is defined then this instance is used,
%    otherwise we look if there is an instance with just the name of
%    the \meta{area}, otherwise we try an instance with the name
%    \meta{type} and if this isn't defined either we try the instance
%    named |default|.
%    \begin{macrocode}
\def\typeset@some@floatbox#1#2{ % type area

  \IfExistsInstanceTF{buildfloat}
                     { #1 - #2 }
    {\def\use@instance@named{#1 - #2}}
    {
      \IfExistsInstanceTF{buildfloat}
                         { #2 }
        {\def\use@instance@named{#2}}
        {
        \IfExistsInstanceTF{buildfloat}
                           { #1 }
          {\let\use@instance@named#1 }   % we know this is a token
          {\def\use@instance@named{default}}
        }
    }
  \UseInstance{buildfloat}\use@instance@named
}
%    \end{macrocode}
% \end{macro}
%
%
%   
%    \begin{macrocode}
% #1 body box
% #2 fixed text
% #3 counter value
% #4 caption
% #5 span number
\DeclareTemplateType{buildfloat}{5}
%    \end{macrocode}
%    
%    \begin{macrocode}
\DeclareTemplate{buildfloat}{centeredabove}{5}
 {
   body-caption-sep =l [10pt] \belowcaptionskip,
 }
 {
  \DoParameterAssignments

  \@parboxrestore

  \hsize=#5\columnwidth

  \global\setbox\this@captioned@float\vbox{
    \sbox\@tempboxb{#2~ #3:~ #4}
    \ifdim \wd\@tempboxb >\hsize
      #2~ #3:~ #4\par
    \else
      \hb@xt@\hsize{\hfil\box\@tempboxb\hfil}%
    \fi
    \vskip\belowcaptionskip
    \centerline{
     \copy#1
    }
    \kern\z@
  }
 }
%    \end{macrocode}
%    
%    \begin{macrocode}
\newbox\@tempboxb
%    \end{macrocode}
%    
%    \begin{macrocode}
\DeclareTemplate{buildfloat}{centeredbelow}{5}
 {
   body-caption-sep =l [10pt] \abovecaptionskip,
 }
 {
  \DoParameterAssignments

  \@parboxrestore

  \hsize=#5\columnwidth

  \global\setbox\this@captioned@float\vbox{
    \centerline{\copy#1}
    \vskip\abovecaptionskip
    \sbox\@tempboxb{#2~ #3:~ #4}
    \ifdim \wd\@tempboxb >\hsize
      #2~ #3:~ #4\par
    \else
      \hb@xt@\hsize{\hfil\box\@tempboxb\hfil}%
    \fi
  }
 }
%    \end{macrocode}
%    
%    \begin{macrocode}
\DeclareTemplate{buildfloat}{bottomright}{5}
 {
   body-caption-sep =l [10pt] \abovecaptionskip,
 }
 {
  \DoParameterAssignments

  \@parboxrestore

  \hsize=#5\columnwidth

  \global\setbox\this@captioned@float\vbox{
    \@@line{\hss\vbox{\copy#1\kern0pt}
      \rlap{
        \hskip\abovecaptionskip
%    \end{macrocode}
%    rubbish as far as it goes: this should be turned into a real
%    template probably using coffins
%    \begin{macrocode}
        \parbox[b]{\marginparwidth
                   +(#5\columnwidth-\wd#1)/2}{
           \raggedright
           #2~ #3:~ #4
        }
      }\hss
    }
    \kern0pt
  }
 }
%    \end{macrocode}
%    
%
%
% \subsection{Some test instances}
%
%    \begin{macrocode}
\DeclareInstance{buildfloat}{default}{centeredabove}{}

\DeclareInstance{buildfloat}{figure}{centeredbelow}{}

\DeclareInstance{buildfloat}{t31}{bottomright}{}
\DeclareInstance{buildfloat}{t22}{bottomright}{}
\DeclareInstance{buildfloat}{t13}{bottomright}{}
%    \end{macrocode}
%
% \endinput
\endinput
%
% $Log: xo-capt.dtx,v $
% Revision 1.13  2000/08/11 07:14:03  latex3
% added header
%
% Revision 1.12  2000/08/11 06:47:53  latex3
% untabify
%
% Revision 1.11  2000/07/19 15:55:53  latex3
% used \float@type rather than \@captype
% extended buildfloat template to 5 arguments
%
% Revision 1.10  2000/07/10 18:45:23  latex3
% some normalisation of caption attachment code -- needs more work
%
% Revision 1.9  2000/06/13 20:53:55  latex3
% docu update
% renamed template type builtfloat to buildfloat
%
% Revision 1.8  2000/05/03 20:16:59  latex3
% added more arguments to the caption template
%
% Revision 1.7  2000/05/03 20:03:59  latex3
% fixed typo in macro name
%
% Revision 1.6  2000/05/03 18:52:44  latex3
% enabling write of toc entries
% adding a prove of concept for caption templates
%