% \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-here.dtx,v 1.12 2000/08/11 07:14:21 latex3 Exp $
%    \end{macrocode}
%
% Ignore white space in this package.
%    \begin{macrocode}
\IgnoreWhiteSpace
%    \end{macrocode}
%
%
% Most of the code in this file is temporary in the sense that the
% interfaces are not fixed or the intended functionality is not fully
% implemented. It is sort of the proof of concept stuff.
%
%
%
% \begin{macro}{\requirespace}
%    The |\requirespace| command is an interface function for other
%    parts of a a class file. It issues a here point which ensures
%    that there is at least |#1| amount of space still available in
%    the current column. If not it results in carrying the here point,
%    including the previous line(s), to the next column. This could,
%    for example, be used by a heading to ensure that there is a
%    certain amount of minimal space following it.
%
%    The precise (?) definition of ``previous line(s)'' is as follows:
%    the internal algorithm will split the so far collected column material
%    trying reach the latest possible break point before the here
%    point. It is theoretically possible to construct examples where
%    \TeX{} decides to take an earlier split point but it is
%    guaranteed the the here point is not losing contact with the
%    material directly preceeding it (unless a legal breakpoint was
%    added in front of it).
%    If the here point was added via |\vadjust| in horizontal mode,
%    this means that the line immediately before it will be after the
%    split (since there will be no other legal break point inbetween).
%    \begin{macrocode}
\def\requirespace #1 {
  \ifhmode
    \@bsphack
  \fi
  \@next\@currbox\@freelist{}{}
%    \end{macrocode}
%    We are only interested in the type really:
%    \begin{macrocode}
  \global\toks\@currbox{{}{}
                        {}
                        {}
                        {}
                        {rspace}
                        {}
   }
  \here@point\@currbox{#1}     
  \@ignorefalse
  \@esphack
}
%    \end{macrocode}
% \end{macro}   
%
%    
% \begin{macro}{\marginpar}
%    The current implementation of the document command |\marginpar|
%    is only a proof of concept draft. It doesn't cover the full
%    flexibility of the \LaTeXe{} version yet (and perhaps one wants
%    even an extension of that).
%    \begin{macrocode}
\def\marginpar #1 {
  \ifhmode
    \@bsphack
  \fi
  \@next\@currbox\@freelist{}{}
  \@savemarbox\@currbox{#1}
%    \end{macrocode}
%    We are only interested in the type really:
%    \begin{macrocode}
  \global\toks\@currbox{{}{}
                        {}
                        {}
                        {}
                        {mpar}
                        {}
   }
%    \end{macrocode}
%    How far is a marginpar allowed to move past the bottom of the
%    text area? Or say it differently: how much space does a marginpar
%    need to reserve on the page?
%
%    The code below works differently than the \LaTeXe{} one: it will
%    move the marginpar including the line it was issued on to the
%    next column if its text will otherwise fall more than a
%    baselineskip below the page bottom.
%    \begin{macrocode}
  \@tempdima\ht\@currbox
  \advance\@tempdima\dp\@currbox
  \advance\@tempdima -\baselineskip   % allow to run long
  \ifdim\@tempdima< \z@ \@tempdima\z@ \fi
  \here@point\@currbox{\the\@tempdima}     
  \@ignorefalse
  \@esphack
}
%    \end{macrocode}
% \end{macro}   
%
%    
%    
%    
%    
%    
%    
%    
% \begin{macro}{\typeset@a@marginpar}
%    The |\typeset@a@marginpar| code is called when a marginpar is
%    finally added to the current page (either in a trial or in the
%    final run).
%
%    It should be templated!
%
%    Current code is only working for two column setup (!) and lacks
%    any modification possibilities depending on the final position
%    for the marginpar.
%
%    \begin{macrocode}
\def \typeset@a@marginpar{
 \kern-\pagedepth
 \vtop to\pagedepth{\baselineskip\pagedepth
     \lineskip\z@
     \vss
     \dimen@\dp\@currbox
  \ifnum \curr@col@count = \@ne
%    \end{macrocode}
%    Since this perhaps only a trial setting we have to |\copy| and
%    not to |\box|!\footnote{FIX: Should clear those boxes somewhere
%    else to save space!}
%    \begin{macrocode}
     \llap{\copy\@currbox\kern\marginparsep}
  \else
     \ifnum \curr@col@count = \col@count
       \rlap{\kern\columnwidth\kern\marginparsep\copy\@currbox}
     \else
       \ERROR-NOT-SUPPORTED
     \fi
  \fi
  \kern-\dimen@
  \null}
}
%    \end{macrocode}
% \end{macro}   
%
%    
%    
%    
%
% \begin{macro}{\check@and@typeset@a@here@float}
%
%    When we reach |\check@and@typeset@a@here@float| we are trying to
%    place a float from the active list into some area and have
%    encountered a here point while grabbing the column text for this
%    trial placement. In |\check@and@typeset@a@here@float| we check if
%    the type of the here point is the same as the current float and
%    if so whether or not it would conflict with that trial
%    placement. This is the case if
%    \begin{itemize}
%    \item
%      the here float and the float under trial have the same type
%    \item
%      and their ordering gets out of sync.
%    \end{itemize}
%    \begin{macrocode}
\def\check@and@typeset@a@here@float{
%<*trace>
  \@tracepush{check@and@typeset@a@here@float}
%</trace>
%    \end{macrocode}
%    If we don't run with floats then no check are necessary (in fact,
%    the checks would produce incorrect results), so we skip them and
%    immediately typeset the here float.
%    \begin{macrocode}
  \ifrun@with@floats
%    \end{macrocode}
%    If the current float under trial has the same sequence class as the here
%    object we have to look at the spatial relationship in more detail.
%    \begin{macrocode}
    \ifx\here@class\this@class
%<*trace>
      \tr@ce{here:~ here@class~ =~ this@class~ =~ \this@class}
%</trace>
%    \end{macrocode}
%    If the float under trial has a larger sequence number than the
%    here float we have to ensure that the area we place it in follows
%    the here point, i.e., is either a later column or if it is in the
%    same column comes at the bottom.
%    \begin{macrocode}
      \ifnum \this@sequence@number > \here@sequence@number \relax
%<*trace>
        \tr@ce{here:~ target~ area~ should~ be~ after~ here~ point!}
%</trace>
%    \end{macrocode}
%    Like in the case of checking call-out relations we use the column
%    number returned in |\count@| by |calculate@target@fl@column|
%    rather than always using the start column of the area.
%    \begin{macrocode}
        \calculate@target@fl@column
        \ifnum \count@ > \curr@col@count
%<*trace>
          \tr@ce{OK:~ target~ area column~ later}
%</trace>
        \else
          \ifnum \count@ = \curr@col@count
%<*trace>
            \tr@ce{??:~ target~ area~ target~ column~ identical}
%</trace>
%    \end{macrocode}
%    So in case we are in the same column at the top we fail the trial.
%    \begin{macrocode}
            \if t \this@area@type
%<*trace>
              \tr@ce{Fail:~ target~ area~ is~ before~ here~ point}
%</trace>
              \@failtrue
%<*trace>
            \else
              \tr@ce{OK:~ target~ area~ is~ after~ here~ point}
%</trace>
            \fi
          \else
%    \end{macrocode}
%    And we fail the trial if we tried to place the float into an
%    earlier column.
%    \begin{macrocode}
%<*trace>
            \tr@ce{Fail:~ target~ area~  column~ earlier~
                   (\the\count@ < \the\curr@col@count)}
%</trace>
            \@failtrue
          \fi
        \fi
%    \end{macrocode}
%    If the float sequence number of the current float is smaller than
%    the one of the here float then we should always handle it via
%    flushing the float out. So the |\else| case is really only there
%    for debugging
%    \begin{macrocode}
%<*debug>
      \else
        \tr@ce{here:~ target~ area~ should~ be~ before~ here~ point!}
        \ifnum \this@area@col@number > \curr@col@count
          \tr@ce{Problem:~ target~ area~  column~ after~ here~ point
                 (\this@area@col@number > \the\curr@col@count)}
        \else
          \ifnum \this@area@col@number = \curr@col@count
            \tr@ce{??:~ target~ area~ target~ column~ identical}
            \if t \this@area@type
              \tr@ce{OK:~ target~ area~ is~ before~ here~ point}
            \else
              \tr@ce{Problem:~ target~ area~ is~ after~ here~ point}
            \fi
          \else
            \tr@ce{OK:~ target~ area~ is~ before~ here~ point}
          \fi
        \fi
%</debug>
      \fi
    \fi
  \fi
  \if@fail
%    \end{macrocode}
%    If the test above failed we report progress claiming that the
%    reason is due to the current float being placed before the here
%    float. As mentioned above this should be the only possibility why
%    things fail.
%    \begin{macrocode}
%<*progress>
    \progress@failed{\this@area\space before~here~float~
                 (\here@type\space \here@sequence@number)~
                 in~ column~ \the\curr@col@count}
%</progress>
    \global\curr@col@count\col@count
%<*trace>
    \tr@ce{Failed:~ here~ float~ out~ of~ sync}
%</trace>
  \else
    \typeset@a@here@float
  \fi
%<*trace>
  \@tracepop{check@and@typeset@a@here@float}
%</trace>
}
%    \end{macrocode}
% \end{macro}
%    
%    
%    
% \begin{macro}{\typeset@a@here@float}
%    The |\typeset@a@here@float| is called when a here float is
%    finally added to the current page (either in a trial or in the
%    final run).
%
%    The caption is attached by the usual method where the here
%    area is denoted by |h|\meta{col}|1|. This allows to have
%    different caption placements depending, for example, on the
%    column being near the one of outer margins.
%
%    The float is separated from preceeding and following text by the
%    current value of |\pagesetup@float@inline@sep| as defined in the
%    page setup template plus or minus a certain amount to allow
%    grid-based typesetting  if desired.
%    \begin{macrocode}
\def \typeset@a@here@float{
%    \end{macrocode}
%    Attach the caption to the float body and store the result in
%    |\this@captioned@float|.
%    \begin{macrocode}
 \append@here@caption@to@float
%    \end{macrocode}
%    If we are not doing grid typesetting we simply put
%    |\pagesetup@float@inline@sep| before and after the formatted
%    float.
%    \begin{macrocode}
 \ifdim \pagesetup@grid@point@sep = \z@
   \@tempskipa\pagesetup@float@inline@sep
 \else
%    \end{macrocode}
%    Otherwise we have to work a little harder since now we need to
%    put exactly the right amount of space before and after the float
%    to stay within the grid. So we measure the size of the formatted
%    float and store the value in |\@tempdima|.
%    \begin{macrocode}
   \@tempdima\ht\this@captioned@float
   \advance\@tempdima\dp\this@captioned@float
%    \end{macrocode}
%    To this we add twice |\pagesetup@float@inline@sep| which gives us
%    the target size for whole object including surrounding space.
%    \begin{macrocode}
   \advance\@tempdima\tw@\pagesetup@float@inline@sep
%    \end{macrocode}
%    Calculate the difference to the nearest grid point\ldots
%    \begin{macrocode}
   \snap@to@grid \@tempdima  \pagesetup@grid@point@sep 
%    \end{macrocode}
%    \ldots and decide which grid point is closest. If the smaller one
%    is closer use it if we are allowed to shrink the white space by
%    the necessary amount.
%    \begin{macrocode}
   \ifdim \returned@lower@delta@size < \returned@delta@size \relax
     \ifdim \returned@lower@delta@size < 2\pagesetup@float@inline@shrink
%    \end{macrocode}
%    Note that for the lower delta size we have to use the
%    negation since we want to backup by this amount and delta sizes
%    are always given in absolute values.
%    \begin{macrocode}
       \xdef \returned@delta@size {-\returned@lower@delta@size }
     \fi
   \fi
%    \end{macrocode}
%    Now set up the amount of white space we need around the float by
%    starting with the |\returned@delta@size| divided by two (i.e.,
%    equal amount contributed to both sides of the float and then add
%    |\pagesetup@float@inline@sep|. Notice, that we used a skip
%    register for the calculation so that any minus or plus parts will
%    survive. This is useful in case we are not doing grid typesetting
%    and want to allow for some flexibility.\footnote{This needs perhaps
%    rethinking it the light of extended grid implementation concept!}
%    \begin{macrocode}
   \@tempskipa \returned@delta@size \relax
   \divide  \@tempskipa \tw@
   \advance \@tempskipa \pagesetup@float@inline@sep
%<*trace>
   \tr@ce{GRID:~ here~float:~ use~ \the\@tempskipa \space above~ and~ below}
%</trace>
 \fi
%    \end{macrocode}
%    Finally typeset the float and its surrounding space which is by
%    now stored in |\@tempskipa|.\footnote{Perhaps make the space
%    above and below specifiable individually. One day, perhaps!}
%    \begin{macrocode}
 \vskip\@tempskipa
 \box\this@captioned@float
 \vskip\@tempskipa
}
%    \end{macrocode}
% \end{macro}   
%
%
% \begin{macro}{\setup@here@float}
%    Absolutely temp!!!!!\footnote{FIX!!!!}
%    \begin{macrocode}
\def \setup@here@float {
 \@tempskipa 2\pagesetup@float@inline@sep   %FMi arbitrary value TMP
 \advance\@tempskipa\ht\@currbox      %FMi arbitrary value TMP
 \advance\@tempskipa\dp\@currbox      %FMi arbitrary value TMP
 \advance\@tempskipa5\baselineskip    %FMi arbitrary value TMP
 \here@point\@currbox{\the\@tempskipa}     
}
%    \end{macrocode}
% \end{macro}   
%
%    
%    
%
% \endinput
\endinput
%
% $Log: xo-here.dtx,v $
% Revision 1.12  2000/08/11 07:14:21  latex3
% added header
%
% Revision 1.11  2000/08/04 10:19:09  latex3
% added init of here floats (temp version)
%
% Revision 1.10  2000/07/19 16:05:41  latex3
% introduced float sequence class concept
%
% Revision 1.9  2000/07/10 19:13:34  latex3
% template here floats and support grid typesetting for them.
%
% Revision 1.8  2000/06/29 17:18:44  latex3
% introduced \setup@this@area
%
% Revision 1.7  2000/06/18 14:58:32  latex3
% use \calculate@target@fl@column to determine the target column ti
% check if here float and current float are in sync
%
% Revision 1.6  2000/06/15 15:23:05  latex3
% untabify
%
% Revision 1.5  2000/06/13 20:45:47  latex3
% docu updates
%
% Revision 1.4  2000/05/03 18:58:56  latex3
% provide caption template support
%
% Revision 1.3  2000/04/27 19:51:45  latex3
% bug fix: need to copy boxes in trials :-)
% moved \check@and@typeset@a@here@float to this file
%
% Revision 1.2  2000/04/21 19:01:13  latex3
% added documentation
%
% Revision 1.1  2000/04/21 10:19:07  latex3
% Initial revision
%
