diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/marginfix/marginfix.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/marginfix/marginfix.dtx | 1194 |
1 files changed, 929 insertions, 265 deletions
diff --git a/Master/texmf-dist/source/latex/marginfix/marginfix.dtx b/Master/texmf-dist/source/latex/marginfix/marginfix.dtx index b0686483fd7..1e7b43ea06b 100644 --- a/Master/texmf-dist/source/latex/marginfix/marginfix.dtx +++ b/Master/texmf-dist/source/latex/marginfix/marginfix.dtx @@ -12,10 +12,10 @@ % %<package>\NeedsTeXFormat{LaTeX2e} %<package>\ProvidesPackage{marginfix}% - [2010/08/28 v0.9.1 Fix Margin Paragraphs] + [2013/09/08 v1.1 Fix Margin Paragraphs] %<*driver> \documentclass{ltxdoc} -\CheckSum{546} +\CheckSum{1197} %\OnlyDescription % (un)comment this line to show (hide) source code \RecordChanges \EnableCrossrefs @@ -53,6 +53,23 @@ % {(SDH) Initial CTAN version.} % \changes{v0.9.1}{2010/08/28} % {(SDH) Fix bug where we alternated sides in article.} +% \changes{v1.0}{2013/09/01} +% {(Dario Buttari) Alternate order of \cs{marginpar} arguments to be +% consistent with the original macro.} +% \changes{v1.0}{2013/09/01} +% {(Dario Buttari) Fix bug in deferred note spacing.} +% \changes{v1.0}{2013/09/01} +% {(Dario Buttari) Fix issues with \cs{marginheightadjustment} and +% \cs{extendmargin} not being applied and reset consistently.} +% \changes{v1.0}{2013/09/01} +% {(SDH) Stop gobbling vertical stretch on page. Margin notes will +% not line up properly if page is stretched.} +% \changes{v1.0}{2013/09/01} +% {(SDH) Add margin phantoms.} +% \changes{v1.1}{2013/09/08} +% {(SDH) Globally calculate margin phantoms over 4 passes.} +% \changes{v1.1}{2013/09/08} +% {(SDH) Add \cs{topskip} to notes at the top of the margin.} % % \GetFileInfo{marginfix.dtx} % \title{\Lopt{marginfix} package documentation} @@ -72,14 +89,16 @@ % unsatisfying for short textual notes, and standard marginpars cannot % be mixed with sidebars. This package implements a solution to % make marginpars "just work" by keeping a list of floating inserts and -% arranging them intelligently in the output routine. +% arranging them intelligently in the output routine. The credit for the +% concept behind this algorithm goes to Prof. Andy Ruina, who employed me +% to work on some of his textbook macros in 2007--9. % % \section{Options} % There are currently no options that do anything yet. % % \section{Commands} -% For the most part, this is a drop-in replacement. Simply add -% |\usepackage{marginfix}| to the preamble, use \cs{marginpar} +% For the most part, this is a drop-in replacement. Simply include +% a call to |\usepackage{marginfix}| to the preamble, use \cs{marginpar} % normally and hope for the best. % In the event, however, that it doesn't work exactly as hoped, % there are a number of tweaks that the user can apply. @@ -108,9 +127,9 @@ % % \DescribeMacro{\mparshift} % To adjust the position of a single note, use \cs{mparshift}\marg{length} -% before \cs{marginpar}. Positive lengths move it down the page. This -% essentially shifts the call-out location, so the actual position of the -% note might not change if the margin is sufficiently crowded. +% before a call to \cs{marginpar}. Positive lengths move it down the page. +% This essentially shifts the call-out location, so the actual position of +% the note might not change if the margin is sufficiently crowded. % Multiple calls before the same note are cumulative. % % \DescribeMacro{\marginheightadjustment} @@ -122,15 +141,38 @@ % \cs{extendmargin} on every page. % % \DescribeMacro{\marginposadjustment} -% Similarly, if all the margins are in the wrong place, the callout -% positions can be adjusted by assigning a non-zero value to the dimension -% register \cs{marginposadjustment}. This is effectively the same as a call -% to \cs{mparshift} before every note. This is particularly useful at -% present because the height of the line on which the margin note is called +% Similarly, if all the margin notes are in the wrong place, the callout +% positions can be adjusted globally by assigning a non-zero value to the +% dimension register \cs{marginposadjustment}. This is effectively the same +% as a call to \cs{mparshift} before every note. This is particularly useful +% at present because the height of the line on which the margin note is called % is currently only estimated, and appears to be off by a point or two. % This may get fixed in the future, but until then, the adjustment is % possibly the easiest workaround. % +% \DescribeMacro{\blockmargin}\DescribeMacro{\unblockmargin} +% As of version 1.0, we now support ``margin phantoms'': sections of the +% margin in which no notes will be placed, which can be useful for large +% figures that jut into the margin (note: margins already move out of the +% way of floats, regardless of whether or not they extend into the margin; +% this is mainly for in-place figures or equations). The easiest way to +% block off part of the margin is to call \cs{blockmargin} before the +% extended content and \cs{unblockmargin} afterwards. No margin notes +% will be placed between these two points (though one must be careful: +% if one of these is called in horizontal mode, the toggle will occur at +% the \emph{top} of the current line). Each of these commands takes an +% optional argument: \cs{blockmargin}\oarg{pos} will begin the margin +% block at a position \emph{pos} below the current position (or above +% if \emph{pos} is negative), and \cs{unblockmargin}\oarg{pos} will +% likewise end the block at a position \emph{pos} below the current +% position. +% +% \DescribeMacro{\marginphantom} +% Margin phantoms may also be called out in place with a known size +% using \cs{marginphantom}\oarg{pos}\marg{size}, which is essentially +% equivalent to \cs{blockmargin}\oarg{pos}\cs{unblockmargin}\oarg{pos$+$size}. +% Either argument may be negative to refer upward rather than downward. +% % \section{Interaction with other packages} % \subsection{memoir} % There are no known issues with \Lopt{memoir} at present, provided that @@ -151,10 +193,14 @@ % Here is a list of things to possibly look forward to in a future version. % If any of them are particularly important, please let me know. % \begin{itemize} -% \item Margin phantoms. % \item Use of pdf\TeX's \cs{pdfsavepos} and \cs{pdflastypos} for more % accurate margin placement. % \item \cs{vadjust} to correct inconsistencies with \cs{@pageht}. +% \item Margin note placement is irrespective of vertical stretch. +% Previously we gobbled any vertical stretch, but now that we have +% fixed that bug, there's the possibility of wrong alignment since +% we don't know where the positions will ultimately end up. This +% may be fixed by \cs{pdfsavepos} as well. % \item Better interaction with floats. % (We can set a default one way % or the other and then allow a macro to override it (presumably with a @@ -170,18 +216,11 @@ % \makeatletter % \part*{Implementation} % \section{Initial Setup} -% \begin{macros}{\@ight,\f@ur,\@C} -% Make the |@|-sign into a letter for use in macro names. We also -% define a few other (hopefully) obvious and unambiguous macros that -% other packages won't destructively clobber. +% Make the |@|-sign into a letter for use in macro names. % \begin{macrocode} %<*package> \makeatletter -\chardef\@ight=8 -\chardef\f@ur=4 -\chardef\@c=100 % \end{macrocode} -% \end{macros} % % \begin{macros}{\MFX@debug} % We have some optionally-included code for debugging. \cs{MFX@debug} @@ -189,15 +228,22 @@ % The newline can be suppressed with a |*|. We'll also ask for more % error context in the debug mode. % \begin{macrocode} -%<debug>\def\MFX@debug{\@ifstar\message{\message{^^JMFX:}\message}} -%<debug>\errorcontextlines=20 +%<*debug> +\def\MFX@debug{\message{^^JMFX:}\message} +\errorcontextlines=20 +\def\MFX@mac#1{\expandafter\MFX@@mac\meaning#1>>>} +\def\MFX@@mac#1->{<<<} +\def\MFX@htdp#1{\ht#1=\the\ht#1, \dp#1=\the\dp#1} +\showboxbreadth=100 +\showboxdepth=10 +%</debug> % \end{macrocode} % \end{macros} % % The reader might begin to note at this point a convention we % adopt throughout this package. While we strive to avoid introducing -% new names as much as possible (using the \pkg{inlinedef} package -% whenever we can), any new names we do introduce will be prefixed +% new names as much as possible (with clever usages of \cs{expandafter}), +% any new names we do introduce will be prefixed % by |\MFX@|, |\Mfx@|, or |\mfx@|, depending on the type of name. % The all-capitol |\MFX@| is used for fully-constant macros. The % initial-caps |\Mfx@| is used for control sequences that are @@ -208,6 +254,7 @@ % % \section{Options} % Here we define the various package options. +% \iffalse - CURRENTLY UNIMPLEMENTED % \begin{macros}{\ifmfx@ypos} % The \Lopt{ypos} option signifies that we should use the pdf{\TeX} % primitives \cs{pdfsavepos} and \cs{pdflastypos} to improve positioning @@ -219,6 +266,7 @@ \DeclareOption{ypos}{\mfx@ypostrue} % \end{macrocode} % \end{macros} +% END IFFALSE - \else There are no options yet. \fi % % Now we actually process the options. % \begin{macrocode} @@ -235,6 +283,21 @@ % \end{macrocode} % \end{macros} % +% \begin{macros}{\mfx@inject,\Mfx@inject@insert} +% These are used to hijack \cs{marginpar} to inject arbitrary code +% into the output routine, rather than actually set a note. To +% inject code, we unshift two copies of this dummy insert onto +% \cs{@freelist} for \cs{marginpar} to pull off. We append +% whatever code we want to inject into \cs{mfx@inject} and then +% call \cs{marginpar}. Then our custom \cs{@addmarginpar} will +% recognize the dummy inserts and run the code instead of setting +% a margin note. +% \begin{macrocode} +\let\mfx@injected\@empty +\newinsert\Mfx@inject@insert +% \end{macrocode} +% \end{macros} +% % \begin{macros}{\Mfx@marginbox} % While we're building the margin, we need to put it in a box % before we can attach it to the main columm. @@ -243,24 +306,52 @@ % \end{macrocode} % \end{macros} % -% \begin{macros}{\Mfx@marginboxspace,\Mfx@marginpos} -% While we build up the margin box, we need to keep track of both -% where we are in the margin (\cs{Mfx@marginpos}) and how -% much of that space is incompressible (\cs{Mfx@marginboxspace}). +% \begin{macros}{\Mfx@marginpos@min,\Mfx@marginpos@max,\Mfx@marginspace} +% While we build up the margin piece boxes, we need to keep track of the +% possible range of positions. The pair \cs{Mfx@marginpos@min} and +% \cs{Mfx@marginpos@max} are used to accumulate how much material has +% been added so far, with the difference that \cs{Mfx@marginpos@min} doesn't +% take into account compressible space, while \cs{Mfx@marginpos@max} does. +% Finally, \cs{Mfx@marginspace} is the amount of (incompressible) space +% since the last note, which allows skips to span margin phantoms. % \begin{macrocode} -\newdimen\Mfx@marginboxspace -\newdimen\Mfx@marginpos +\newdimen\Mfx@marginpos@min +\newdimen\Mfx@marginpos@max +\newdimen\Mfx@marginspace % \end{macrocode} % \end{macros} % % \begin{macros}{\Mfx@marginheight} % Because the margin height can be altered by, \cs{extendmargin}, % we must maintain a dimension for the height of the current margin. +% This dimension is reused in several different ways in the shipout-time +% margin building routines, keeping track of how much much space is left +% in (for the global passes) and the end position of the end of (for the +% piecewise passes) the current piece. % \begin{macrocode} \newdimen\Mfx@marginheight % \end{macrocode} % \end{macros} % +% \begin{macros}{\mfx@marginstart,\mfx@marginpieces, +% \Mfx@piece@content,\Mfx@piece@count,\ifmfx@in@phantom} +% These control sequences keep track of the margin phantoms. When the +% margin is unblocked then \cs{mfx@marginstart} is not \cs{relax}. When +% a phantom begins, the current \cs{mfx@marginstart} and page position +% are stored as a pair in \cs{mfx@marginpieces}, which is iterated over +% while building individual pieces of the margin. We also define a box +% to keep the content of each margin piece, and a counter to keep track +% of how many pieces we have. Finally, we define a switch for use in +% the second pass to indicate that we're inside a phantom. +% \begin{macrocode} +\def\mfx@marginstart{0pt} +\let\mfx@marginpieces\@empty +\newbox\Mfx@piece@content +\newcount\Mfx@piece@count +\newif\ifmfx@in@phantom +% \end{macrocode} +% \end{macros} +% % \begin{macros}{\Mfx@mparshift} % We store the current shift in a dimension register. % \begin{macrocode} @@ -372,7 +463,7 @@ % \@combinefloats % add \@texttop and \@textbottom to \@outputbox (default no-op) % \@opcol: -% \@outputpage (of \@outputdblcol in twocolumn mode) +% \@outputpage (or \@outputdblcol in twocolumn mode) % let \@mparbottom := \@textfloatsheight := 0 % \@floatplacement % \@startcolumn: @@ -398,22 +489,29 @@ % output routine so that we can get ahold of the current page % position. Even if we have a better idea of the page position % (e.g. from pdf\TeX), we still might as well do this in the OR. +% In addition to actually setting the margin note, we also use this +% routine to inject arbitrary code into the OR (see \cs{MFX@inject}). % \begin{macrocode} \def\@addmarginpar{% - \@next\@marbox\@currlist{}\MFX@bug -%<debug>\MFX@debug{addmarginpar (running insert) \@marbox/\@currbox at -%<debug> \the\c@page:\the\@pageht, marginlist=\meaning\mfx@marginlist}% + \@next\@marbox\@currlist{}\MFX@AssertionError +%<debug>\MFX@debug{addmarginpar (running insert) \@marbox/ \@currbox at +%<debug> \the\c@page:\the\@pageht, marginlist=\MFX@mac\mfx@marginlist}% +%<debug>\MFX@debug{addmarginpar outputpenalty=\the\outputpenalty}% \MFX@getypos - \MFX@cons\mfx@marginlist{% TODO: later this will be a run@marginlist - \noexpand\mfx@margin@note\@marbox\@currbox{\mfx@ypos}% (^i.e. for phantoms) - \noexpand\mfx@margin@skip{\the\marginparpush}% - }% -%<debug>\MFX@debug{addmarginpar (exit): marginlist=\meaning\mfx@marginlist}% + \expandafter\ifx\@marbox\Mfx@inject@insert + \mfx@injected\global\let\mfx@injected\@empty + \else + \MFX@cons\mfx@marginlist{% + \noexpand\mfx@build@note\@currbox\@marbox{\mfx@ypos}% + \noexpand\mfx@build@skip{\the\marginparpush}% + }% + \fi +%<debug>\MFX@debug{addmarginpar (exit): marginlist=\MFX@mac\mfx@marginlist}% } % \end{macrocode} % \end{macros} % -% \begin{macros}{\MFX@cons,\MFX@snoc} +% \begin{macros}{\MFX@cons,\MFX@snoc,\MFX@run@clear} % In passing we'll define the cons macro, which fully-expands % its second argument, but makes sure to only expand the first % one once, so that any fragile control sequences in it are @@ -435,11 +533,35 @@ \expandafter\expandafter\expandafter{\expandafter\temp@#1}% } % \end{macrocode} +% Finally, \cs{MFX@run@clear} is a quick trick to expand the +% contents of a macro and then clear it (to \cs{@empty}) before +% any of its tokens are consumed. +% \begin{macrocode} +\def\MFX@run@clear#1{% + \expandafter\global\expandafter\let\expandafter#1\expandafter\@empty#1% +} +% \end{macrocode} +% \end{macros} +% +% \begin{macros}{\MFX@inject} +% As mentioned earlier, \cs{@addmarginpar} is also a hook for injecting +% arbitrary code into the output routine, i.e. to get a vertical position +% for blocking the margin. We define \cs{MFX@inject} to facilitate this. +% \begin{macrocode} +\def\MFX@inject#1{ + \expandafter\def\expandafter\@freelist\expandafter{% + \expandafter\@elt\expandafter\Mfx@inject@insert + \expandafter\@elt\expandafter\Mfx@inject@insert + \@freelist}% + \expandafter\def\expandafter\mfx@injected\expandafter{\mfx@injected#1}% + \marginpar{}% +} +% \end{macrocode} % \end{macros} % % \begin{macros}{\MFX@getypos,\mfx@ypos} % We now need to settle on a way to determine the vertical position. -% Ultimately this will be an option, and will depend on a variety +% Someday this may be an option, and will depend on a variety % of factors. But for starters, we define the simplest version. % Note the subtraction of \cs{Mfx@strutheight}. Ideally we would simply % grab a copy of \cs{@holdpg} from the middle of \cs{@specialoutput} @@ -450,14 +572,16 @@ % within \cs{@specialoutput}, and it's not worth the risky job of % performing surgery on it (which is unfortunately brittle if anyone % else has a similar idea), we instead resort to this approximation. -% And since this will ultimately be only a fallback for when -% \cs{pdflastypos} isn't available, it should be good enough. -% NOTE: we might be able to use a \cs{vadjust} instead here? +% And since this should ultimately be only a fallback for when +% \cs{pdflastypos} isn't available, it's good enough. +% (NOTE: we might be able to use a \cs{vadjust} instead here?) % \begin{macrocode} \def\MFX@getypos{% - \edef\mfx@ypos{% - \the\dimexpr\@pageht - \Mfx@strutheight - + \marginposadjustment + \Mfx@mparshift\relax}% + \dimen@\dimexpr\@pageht+\@pagedp+\marginposadjustment+\Mfx@mparshift\relax + \ifnum\outputpenalty=-10002\relax + \advance\dimen@-\Mfx@strutheight + \fi + \edef\mfx@ypos{\the\dimen@}% \global\Mfx@mparshift\z@ } % \end{macrocode} @@ -490,14 +614,17 @@ % % \cs{MFX@combinefloats@before} is then responsible for picking the % needed notes from \cs{mfx@marginlist}, building them into a box, and -% attaching said box onto the correct side of \cs{@outputbox}. This is -% also a convenient place to reset \cs{Mfx@marginheight} to zero (since -% we reuse the register for one-time extensions). +% attaching that box onto the correct side of \cs{@outputbox}. We also +% add any global \cs{marginheightadjustment} to \cs{Mfx@marginheight} +% before building the margin, and then reset it back to zero at the end. +% This allows any calls to \cs{extendmargin} during the page itself to +% work as expected. % \begin{macrocode} \def\MFX@combinefloats@before{% + \advance\Mfx@marginheight\marginheightadjustment \MFX@buildmargin \MFX@attachmargin - \Mfx@marginheight\marginheightadjustment + \global\Mfx@marginheight\z@ } % \end{macrocode} % \end{macros} @@ -512,218 +639,312 @@ % First, we need to make sure that the boxes we're combining are the % same size. % \begin{macrocode} - \ifdim\ht\@outputbox<\ht\Mfx@marginbox - \setbox\@outputbox\vbox to \ht\Mfx@marginbox{% - \box\@outputbox - \vfill - }% - \else - \setbox\Mfx@marginbox\vbox to \ht\@outputbox{% - \unvbox\Mfx@marginbox - \vfill - }% - \fi +%<debug>\MFX@debug{attachmargin: \MFX@htdp\@outputbox, \MFX@htdp\Mfx@marginbox}% + %<debug>\showbox\@outputbox + %<debug>\showbox\Mfx@marginbox + \setbox\Mfx@marginbox\vtop{% + \vskip\z@\unvbox\Mfx@marginbox}% + %% \ifdim\ht\@outputbox<\ht\Mfx@marginbox + %% \setbox\Mfx@marginbox\vbox to \ht\@outputbox{% + %% \unvbox\Mfx@marginbox + %% \vskip\z@ shrink 1filll\relax + %% }% + %% \else + %% \setbox\Mfx@marginbox\vbox to \ht\@outputbox{% + %% \unvbox\Mfx@marginbox + %% \vfill + %% }% + %% \fi % \end{macrocode} % Next we need to figure out which side of \cs{@outputbox} to attach -% the \cs{Mfx@marginbox} on. -% \begin{macrocode} - \setbox\@outputbox\vbox to \ht\@outputbox{% - \hbox to \wd\@outputbox{% - \if\MFX@leftmargin - \llap{\box\Mfx@marginbox\hskip\marginparsep}% - \box\@outputbox - \else - \box\@outputbox - \rlap{\hskip\marginparsep\box\Mfx@marginbox}% - \fi - }}% +% the \cs{Mfx@marginbox} on. We now use \cs{columnwidth} instead of +% \cs{wd}\cs{@outputbox} to set the right-hand margins, since tufte-\LaTeX +% sometimes makes too-wide output boxes. If this becomes a problem, +% we'll need to consider making this configurable elsewhere. We should +% also pay attention to whether adding a box at the top of \cs{@outputbox} +% might have unintended consequences w.r.t. any glue being retained that +% should have been swallowed. This will require further investigation. +% \begin{macrocode} + \setbox\@outputbox\vbox{% to \ht\@outputbox{% + \begingroup + \setbox\@tempboxa\vbox{% to \ht\@outputbox{% + \hbox{% to \wd\@outputbox{% + \if\MFX@leftmargin + \llap{\box\Mfx@marginbox\hskip\marginparsep}% + \else + \hskip\columnwidth + \rlap{\hskip\marginparsep\box\Mfx@marginbox}% + \fi + }}% + \ht\@tempboxa\z@ + \dp\@tempboxa\z@ + \box\@tempboxa + \endgroup + \unskip + \unvbox\@outputbox + }% + %<debug>\showbox\@outputbox } % \end{macrocode} % \end{macros} % % \begin{macros}{\MFX@buildmargin} % When \cs{MFX@buildmargin} is called, we have a list of tokens in -% \cs{mfx@marginlist} that need to be processed. After it's done -% working, \cs{mfx@marginlist} should have the first $n>0$ of these -% removed, and leaving only notes that were deferred to the next -% page. Additionally, \cs{Mfx@marginbox} must contain a -% box the same height as \cs{@outputbox}. We do this in several -% steps. We start with a height of \cs{@colroom} rather than -% \cs{textheight} because \cs{@colroom} has already subtracted -% off the top/bottom floats that have been set. Eventually we -% will want to encroach on these floats, particularly if they -% don't encroach on the margin, but that will be tricky... +% \cs{mfx@marginlist} that need to be processed: combinations of +% \cs{mfx@build@note}, \cs{mfx@build@skip}, and \cs{mfx@build@clear}, +% with various parameters to indicate what material still needs to be +% set in the margin. This macro therefore must pull off the first $n>0$ +% of these commands to set on the current page ($n$ must be positive to +% prevent infinite loops), and leave the rest to be deferred. We do not +% currently support taking notes out of order, though that is a possible +% feature to allow in the future, on an opt-in basis. The typeset +% material will be left in \cs{Mfx@marginbox}, which must have the same +% height as \cs{@outputbox} (although because we \cs{unvbox}\cs{@outputbox} +% in \cs{MFX@attachmargin}, we can't guarantee that this will correctly +% line up the notes with their callouts). This procedure happens in +% four passes. But first, we initialize \cs{Mfx@marginheight} to +% \cs{@colroom}, which is the height of the page minus any floats that +% have been added to the top of bottom (these floats may extend into the +% margins: in the future we may look into detecting this and using the +% whole page, with overwide floats blocked off as phantoms). We add +% \cs{@colroom} rather than assigning it because any global or per-page +% adjustments have already been added to \cs{Mfx@marginheight}. We +% can then close out any still-open margin pieces (this is the typical +% case, where the margin is not blocked across a page boundary, so that +% \cs{mfx@marginstart} will hold a position, rather than \cs{relax}). +% After this, \cs{Mfx@marginheight} is no longer necessary, so we reuse +% it for keeping track of available space in individual margin pieces. % \begin{macrocode} \def\MFX@buildmargin{% \advance\Mfx@marginheight\@colroom -%<debug>\MFX@debug{buildmargin: marginheight=\the\Mfx@marginheight}% - \MFX@buildmargin@down - \MFX@buildmargin@up + \ifx\mfx@marginstart\relax + \else + \MFX@cons\mfx@marginpieces{% + \noexpand\@elt{\mfx@marginstart}{\the\Mfx@marginheight}}% + \gdef\mfx@marginstart{0pt}% + \global\advance\Mfx@piece@count\@ne + \fi +%<debug>\MFX@debug{buildmargin: marginheight=\the\Mfx@marginheight, +%<debug> marginlist=\MFX@mac\mfx@marginlist, +%<debug> marginpieces=\MFX@mac\mfx@marginpieces}% +% \end{macrocode} +% We now execute the four passes. First is a global downward pass, +% whose purpose is to determine the maximum number of notes (and other +% material) that can fit in the margin, taking any phantoms into +% consideration. Every note identified by \cs{MFX@buildmargin@down} +% is guaranteed to show up on this page, so we free its inserts back +% to \cs{@freelist}. The second pass is the global upward pass, in +% which we determine the lowest possible margin piece each note may +% go into without causing lower notes to fall off the bottom. The +% third pass is the piecewise downward pass. For each piece, we +% figure out where in the piece each note will go by inserting +% compressible spaces between the notes. If a note is called out +% past the end of the piece and does not need to go into the piece +% (as determined by pass 2), it will be deferred to a later piece. +% The fourth pass is the piecewise upward pass, in which the compressible +% spaces are shrunk just enough to fit everything into the piece. The +% last two (piecewise) passes both occur in each piece before the next +% piece is addressed. The whole process is bypassed if there are +% no eligible margin pieces. +% \begin{macrocode} + \ifx\mfx@marginpieces\@empty\else + \MFX@buildmargin@down + \MFX@buildmargin@up + \MFX@buildmargin@pieces + \fi } % \end{macrocode} % \end{macros} % -% \subsection{First pass} -% \begin{macros}{\MFX@buildmargin@down} -% The first step is the ``down'' step, in which we move the notes -% that will go on the current page into \cs{mfx@marginout} in reverse order, -% and anything that will be deferred gets put back in -% \cs{mfx@marginlist}. This behavior is configured by changing -% the meaning of \cs{mfx@margin@note}, \cs{mfx@margin@skip}, and -% \cs{mfx@margin@clear}. Note that during the course of processing -% \cs{mfx@marginlist}, these meanings will continue to change. +% \subsection{First pass: global downward} +% \begin{macros}{\MFX@buildmargin@down,\mfx@pieceheights} +% The first step is the global ``down'' step, in which we move the +% notes that will fit on the current page into \cs{mfx@marginout} in +% reverse order (to prepare for the second, upward, pass), and anything +% that doesn't fit is deferred back into \cs{mfx@marginlist}. We do +% this by changing the meaning of \cs{mfx@build@note}, \cs{mfx@build@skip}, +% and \cs{mfx@build@clear}, which delimit the different types of material +% in \cs{mfx@marginlist}. Note that as we continue processing, these +% macros will change from time to time (i.e. changing \cs{mfx@build@skip} +% to actually doing something once we find a note, rather than gobbling +% so as to remove skips at page boundaries; or changing them to save +% material back onto \cs{mfx@marginlist} once the margin fills up). +% The first thing we need to do is iterate over the piece positions +% to get the list of heights. % \begin{macrocode} \def\MFX@buildmargin@down{% -%<debug>\MFX@debug{buildmargin@down: ENTRY}% -%<debug>\MFX@debug{marginlist=\meaning\mfx@marginlist}% - \let\mfx@margin@note\MFX@margin@note@down - \let\mfx@margin@skip\@gobble - \let\mfx@margin@clear\MFX@margin@clear@down - \let\mfx@marginout\@empty + \let\mfx@pieceheights\@empty + \def\@elt##1##2{% + \MFX@cons\mfx@pieceheights{\noexpand\@elt{\the\dimexpr##2-##1}}}% + \mfx@marginpieces + \MFX@popdimen\Mfx@marginheight\mfx@pieceheights % \end{macrocode} -% We do a little bit of \cs{expandafter} trickery here to first expand -% the current meaning of \cs{mfx@marginlist}, then clear it before -% actually executing anything. +% Now we run forwards over the \cs{mfx@marginlist} to actually +% operate on each thing in the margin. % \begin{macrocode} - \expandafter\global\expandafter\let - \expandafter\mfx@marginlist\expandafter\@empty - \mfx@marginlist -%<debug>\MFX@debug{buildmargin@down: RETURN}% -%<debug>\MFX@debug{marginlist=\meaning\mfx@marginlist}% + \let\mfx@build@note\MFX@margin@note@down + \let\mfx@build@skip\@gobble + \let\mfx@build@clear\MFX@build@clear@down + \let\mfx@marginout\@empty + \MFX@run@clear\mfx@marginlist +%<debug>\MFX@debug{buildmargin@down: RETURN +%<debug> marginout=\MFX@mac\mfx@marginout, +%<debug> marginlist=\MFX@mac\mfx@marginlist}% } % \end{macrocode} % \end{macros} % -% We must now define the different meanings for the -% |\mfx@margin@...| macros. -% \begin{macros}{\MFX@margin@note@down,\MFX@whichbox,% -% \MFX@margin@skip@down,\MFX@margin@clear@down} -% We'll dive right into the notes first. When we see a note in the -% \cs{marginlist}, we need to do several things. +% \begin{macros}{\MFX@margin@note@down,\MFX@margin@skip@down, +% \MFX@margin@clear@down} +% We now define the various |\MFX@margin@...@down| macros. +% At this stage in the game, the only difference between notes +% and skips is that we ignore skips before any notes by setting +% \cs{mfx@build@note} initially to \cs{@gobble}. Once we've +% seen the first note, skips are treated exactly the same: as +% fixed-height material. If there is room in the current piece +% for the given height, then we prepend it to \cs{mfx@marginout}, +% decrement the remaining height, and arrange for the boxes to +% be freed. If not, we unshift the next piece height from +% \cs{mfx@pieceheights} and try again, until \cs{mfx@pieceheights} +% is empty and we simply defer everything to later pages. +% +% Upon seeing a note, we must do several things: % \begin{enumerate} -% \item optionally add a \emph{compressible} skip before it, of length -% $|#3| - \cs{Mfx@marginpos}$, to line it up with the callout -% location -% \item figure out which box we need for the current page, not yet freeing -% the allocated boxes, since we may still end up deferring -% \item add the height of the correct box to \cs{Mfx@marginboxspace} and -% \cs{Mfx@marginpos} -% \item if \cs{Mfx@marginboxspace} exceeds \cs{Mfx@marginheight}, then -% we defer this note and change the meaning of \cs{mfx@margin@note} -% to defer all remaining notes -% \item otherwise, we add tokens to construct the box to \cs{toks@} and -% free the allocated inserts. -% \item redefine \cs{mfx@margin@skip} to \cs{MFX@margin@skip@down}, now -% that we've gotten a real note (it starts out as \cs{@gobble} since -% we don't want to apply skips at the very beginning). +% \item determine which box (left or right) is needed for the +% current page, by calling \cs{MFX@whichbox} +% \item if the box fits, free both boxes, prepend \cs{mfx@marginout} +% with a call to \cs{mfx@build@note}, and re-enable skips +% \item otherwise, defer the current note and all future notes % \end{enumerate} +% The latter two steps are taken care of by \cs{MFX@margin@fit}, +% which takes the height and two blocks of material: one to prepend +% to \cs{mfx@marginout} if it fits, the other to append to +% \cs{mfx@marginlist} if it doesn't. % \begin{macrocode} \def\MFX@margin@note@down#1#2#3{% -%<debug>\MFX@debug{note@down: ENTRY: #1/#2 at #3}% - \ifdim#3>\Mfx@marginpos - \dimen@\dimexpr#3-\Mfx@marginpos\relax -%<debug>\MFX@debug{note@down: adding compressible \the\dimen@}% - \MFX@snoc\mfx@marginout{\noexpand\mfx@margin@compressible{\the\dimen@}}% - \advance\Mfx@marginpos\the\dimen@ - \fi - \MFX@whichbox#1#2% - \advance\Mfx@marginboxspace\dimexpr\ht\@marbox+\dp\@marbox\relax - \ifdim\Mfx@marginboxspace>\Mfx@marginheight -% \end{macrocode} -% We've run out of margin space, so we now defer every following box, -% which means appending them back to \cs{mfx@marginlist}, except with -% a callout position of zero, since we want them as high up as possible -% (also, the position should be monotonic). -% \begin{macrocode} -%<debug>\MFX@debug{note@down: out of space: -%<debug> \the\Mfx@marginboxspace>\the\Mfx@marginheight}% - \advance\Mfx@marginboxspace\dimexpr-\ht\@marbox-\dp\@marbox\relax - \mfx@margin@clear - \mfx@margin@note#1#2{#3}% - \else -% \end{macrocode} -% At this point, the box is definitely going onto this page, so we can -% arrange for the boxes to be freed and then add the correct box to the -% output list. -% \begin{macrocode} -%<debug>\MFX@debug{note@down: adding \@marbox -%<debug> ht \the\ht\@marbox dp \the\dp\@marbox}% - \advance\Mfx@marginpos\dimexpr\ht\@marbox+\dp\@marbox\relax +%<debug>\MFX@debug{margin@note@down: ENTRY: #1/ #2 at #3}% + \MFX@whichbox\@marbox#1#2% + \if\MFX@check@fit{}{\ht\@marbox+\dp\@marbox}% \MFX@snoc\mfx@marginout{% - \noexpand\mfx@margin@note\@marbox \noexpand\@cons\noexpand\@freelist#1% \noexpand\@cons\noexpand\@freelist#2% - }% + \noexpand\mfx@build@note\@marbox{#3}}% + \let\mfx@build@skip\MFX@margin@skip@down + \else + \mfx@build@clear + \mfx@build@note{#1}{#2}{#3}% \fi - \let\mfx@margin@skip\MFX@margin@skip@down -%<debug>\MFX@debug{note@down: RETURN space=\the\Mfx@marginboxspace, -%<debug> pos=\the\Mfx@marginpos}% } % \end{macrocode} % -% We need to figure out which box to set. This macro calls -% \cs{MFX@leftmargin} and then sets the correct box into -% \cs{@marbox} for use by \cs{MFX@margin@box@down}. +% Skips are similar. A skip needs only to save itself back into +% \cs{mfx@marginout}, provided it fits. If not, there is no need +% to defer it because it will just get gobbled at the top of the +% next page anyway. % \begin{macrocode} -\def\MFX@whichbox#1#2{% - \if\MFX@leftmargin - \def\@marbox{#1}% +\def\MFX@margin@skip@down#1{% +%<debug>\MFX@debug{margin@skip@down #1}% + \if\MFX@check@fit{}{#1}% + \MFX@snoc\mfx@marginout{\noexpand\mfx@build@skip{#1}}% \else - \def\@marbox{#2}% + \mfx@build@clear \fi -%<debug>\MFX@debug{whichbox: \@marbox}% } % \end{macrocode} % -% The next macro we'll write is the skip. This one just has to save itself -% onto whichever list we're working on (output or deferred) and in the case -% of output, update \cs{@Mfx@marginpos}. +% Finally, \cs{MFX@margin@clear@down} is the only place we actually +% need to handle full-margin clears, since the downward pass does not +% ever push \cs{mfx@build@clear} onto \cs{mfx@marginout}. When we +% see this, we simply redefine all three commands to append themselves +% back to \cs{mfx@marginlist}. % \begin{macrocode} -\def\MFX@margin@skip@down#1{% -%<debug>\MFX@debug{skip@down #1}% - \advance\Mfx@marginpos#1\relax - \advance\Mfx@marginboxspace#1\relax - \MFX@snoc\mfx@marginout{\noexpand\mfx@margin@skip{#1}}% +\def\MFX@build@clear@down{% +%<debug>\MFX@debug{clear@down}% + \def\mfx@build@note##1##2##3{% + \MFX@cons\mfx@marginlist{\noexpand\mfx@build@note##1##2{\MFX@minus@inf}}}% + \def\mfx@build@skip##1{% + \MFX@cons\mfx@marginlist{\noexpand\mfx@build@skip{##1}}}% + \def\mfx@build@clear{% + \MFX@cons\mfx@marginlist{\noexpand\mfx@build@clear}}% } % \end{macrocode} +% \end{macros} % -% Finally, \cs{MFX@margin@clear@down} simply signals the end of this -% margin. All further material will be deferred, so we redefine -% \cs{mfx@margin@note}, \cs{mfx@margin@skip}, and \cs{mfx@margin@clear} -% to defer. +% \begin{macros}{\MFX@check@fit,\MFX@popdimen} +% We factored out some of the common functionality between the +% note and skip routines, so that must now be defined. The +% \cs{MFX@check@fit} macro acts as a conditional and should be +% used as \cs{if}\cs{MFX@check@fit}\marg{piece-hook}\marg{size}. +% It takes care of iterating through the list of heights and +% accumulating the total size of material encountered so far. +% The \emph{piece-hook} is executed each time a new piece height +% is popped. % \begin{macrocode} -\def\MFX@margin@clear@down{% -%<debug>\MFX@debug{clear@down}% - \def\mfx@margin@note##1##2##3{% - \MFX@cons\mfx@marginlist{\noexpand\mfx@margin@note##1##2{\MFX@minus@inf}}}% - \def\mfx@margin@skip##1{% - \MFX@cons\mfx@marginlist{\noexpand\mfx@margin@skip{##1}}}% - \def\mfx@margin@clear{% - \MFX@cons\mfx@marginlist{\noexpand\mfx@margin@clear}}% +\def\MFX@check@fit#1#2{% + 00\fi % close out the \if +%<debug>\MFX@debug{check@fit{\unexpanded{#1}}{#2=\the\dimexpr#2} ENTRY: +%<debug> marginheight=\the\Mfx@marginheight}% + \@tempswafalse + \ifdim\dimexpr#2<\Mfx@marginheight % it fits + \advance\Mfx@marginheight-\dimexpr#2\relax % deduct the size + \@tempswatrue + \else % didn't fit: check the next piece +%<debug>\MFX@debug{check@fit overflow: pieceheights=\MFX@mac\mfx@pieceheights}% + \ifx\mfx@pieceheights\@empty\else % make sure there's anything there + #1% + \MFX@popdimen\Mfx@marginheight\mfx@pieceheights + \if\MFX@check@fit{#1}{#2}\fi + \fi + \fi +%<debug>\MFX@debug{check@fit RETURN \meaning\if@tempswa: +%<debug> marginheight=\the\Mfx@marginheight,}% + \if@tempswa % start a new \if +} +% \end{macrocode} +% Here is a quick convenience routine. \cs{MFX@popdimen}\marg{dimen}% +% \marg{list} removes the first dimension from \emph{list} and stores +% it into \emph{dimen}. +% \begin{macrocode} +\def\MFX@popdimen#1#2{% + \def\@elt##1{% + #1##1\relax + \def\@elt####1{% + \MFX@cons#2{\noexpand\@elt{####1}}% + }% + }% + \MFX@run@clear#2% } % \end{macrocode} % \end{macros} % -% \begin{macros}{\MFX@minus@inf} -% Note that when we added deferred boxes to the list, we put them -% at \cs{MFX@minus@inf}. We'll define that to be a large negative -% dimension. +% \begin{macros}{\MFX@whichbox,\MFX@leftmargin} +% We also need to determine which box should be used, since they +% may have different heights. The macro \cs{MFX@whichbox}% +% \marg{target-box}\marg{left-box}\marg{right-box} checks which margin +% we're setting and stores the correct box into \emph{target-box}. +% Note that \emph{target-box} must be a single control sequence. % \begin{macrocode} -\def\MFX@minus@inf{-4000pt} +\def\MFX@whichbox#1#2#3{% + \if\MFX@leftmargin + \def#1{#2}% + \else + \def#1{#3}% + \fi +%<debug>\MFX@debug{whichbox: \@marbox (\the\dimexpr\ht#1+\dp#1)}% +} % \end{macrocode} -% \end{macros} % -% \begin{macros}{\MFX@leftmargin} -% Here we figure out which box to use based on the page number and -% other flags. This is a conditional that should be used after -% \cs{if}, as in \cs{if}\cs{MFX@leftmargin}\ldots\cs{else}\ldots\cs{fi}. +% And here is the logic to figure out which margin were in, based +% on the page number and other flags. This is another conditional-like +% macro, and should be used after an \cs{if}, as in +% \cs{if}\cs{MFX@leftmargin}\ldots\cs{else}\ldots\cs{fi}. % % This is different from the corresponding code in the {\LaTeX} % routines because we don't support double columns. In addition, we % would ideally allow \cs{if@reversemargin} to work on a per-note % basis (i.e. at callout time) but we also need something working at % shipout time so we can figure out which margin to use. Thus, until -% we figure out how to use multiple margins. +% we figure out how to use multiple margins, this will have to do. % \begin{macrocode} \def\MFX@leftmargin{% 00\fi % close out the \if @@ -742,84 +963,445 @@ % \end{macrocode} % \end{macros} % -% \subsection{Second pass} -% \begin{macros}{\MFX@buildmargin@up} -% Next is the ``up'' step. Here we simply take the reversed -% list in \cs{mfx@marginout} and prepend each item in turn to -% \cs{Mfx@marginbox}. We start by automatically discarding any -% skips, though we can't do this with a simple \cs{@gobble} anymore -% since we need to deduct them from \cs{Mfx@marginpos}. Once we -% hit a note, we'll change the skips to be their normal meanings. -% Note that there are no clears in \cs{mfx@marginout}. +% \begin{macros}{\MFX@minus@inf} +% Finally, note that when deferring notes to the next page, we +% adjust their position to the top of the page, rather than the +% callout position. This is a large negative dimension (near +% \TeX's maximum), but we may reconsider making this zero or even +% a small positive amount, since there seems to be a small amount +% of space before the first paragraph in normal text, though I'm +% not sure where that comes from. +% \begin{macrocode} +\def\MFX@minus@inf{-4000\p@} +% \end{macrocode} +% \end{macros} +% +% \subsection{Second pass: global upward} +% \begin{macros}{\MFX@buildmargin@up,\mfx@phantomheights} +% The next step is the global ``up'' step, in which we figure out the +% lowest piece a note can possibly occupy (without pushing later notes +% off the bottom) and add this information to the \cs{mfx@build@note} in +% \cs{mfx@marginout}. We start similar to \cs{MFX@buildmargin@down}, +% except we need the list of heights to be backwards. We also need a +% list of phantom heights, in order to handle skips properly, which we +% intersperse as negative heights. % \begin{macrocode} \def\MFX@buildmargin@up{% -%<debug>\MFX@debug{buildmargin@up: excess=\the\dimexpr -%<debug> \Mfx@marginpos-\Mfx@marginheight\relax}% -%<debug>\MFX@debug{marginout=\meaning\mfx@marginout} - \let\mfx@margin@note\MFX@margin@note@up - \let\mfx@margin@compressible\MFX@margin@skip@gobble@up - \let\mfx@margin@skip\MFX@margin@skip@gobble@up - \mfx@marginout +%<debug>\MFX@debug{buildmargin@up: ENTRY +%<debug> marginpieces=\MFX@mac\mfx@marginpieces, +%<debug> marginout=\MFX@mac\mfx@marginout}% + \let\mfx@pieceheights\@empty + \let\mfx@phantomheights\@empty + \let\temp@@\relax + \def\@elt##1##2{% +%<debug>\MFX@debug{ -> piece (##1,##2), temp@@=\meaning\temp@@}% + \MFX@snoc\mfx@pieceheights{\noexpand\@elt{\the\dimexpr##2-##1}}% + \ifx\temp@@\relax\else +%<debug>\MFX@debug{ -> phantom (\temp@@,##1)}% + \MFX@snoc\mfx@phantomheights{\noexpand\@elt{\the\dimexpr##1-\temp@@}}% + \fi + \def\temp@@{##2}% + }% + \mfx@in@phantomfalse + \mfx@marginpieces +% \end{macrocode} +% The piece counter, \cs{Mfx@piece@count} has not been touched yet, +% so now we will start decrementing it for each piece to keep track +% of where we are. Note that \cs{mfx@marginout} will never contain +% \cs{mfx@build@clear} so we don't need to reassign it. Since we +% don't do any deferrals here, we don't need to empty out a new target +% list. Instead, we operate ``in-place'' in \cs{mfx@marginout}, after +% popping off the first height. +% \begin{macrocode} + \MFX@popdimen\Mfx@marginheight\mfx@pieceheights + \let\mfx@build@note\MFX@margin@note@up + \let\mfx@build@skip\@gobble + \MFX@run@clear\mfx@marginout +%<debug>\MFX@debug{buildmargin@up: RETURN marginout=\MFX@mac\mfx@marginout}% } % \end{macrocode} % \end{macros} % -% \begin{macros}{\MFX@margin@skip@gobble@up} -% In case we have any skips at the beginning of \cs{mfx@marginout}, -% we'll gobble them and deduct their lenghts from \cs{Mfx@marginpos}. +% \begin{macros}{\MFX@margin@note@up,\MFX@margin@skip@up} +% We must again define the specific behavior of each build command. +% These macros simply reuse \cs{MFX@check@fit}, but ask it to +% decrement the piece counter when a piece runs out of space. +% Aside from that, the only thing that actually happens here is +% that we append the current piece to each note, and also end +% up reversing the contents by again prepending everything. +% We are guaranteed that \cs{MFX@check@fit} will never fail. +% Since we cannot put notes in a phantom, we start by ensuring +% we're not in one. +% \begin{macrocode} +\def\MFX@margin@note@up#1#2{% +%<debug>\MFX@debug{margin@note@up: #1at #2, marginheight=\the\Mfx@marginheight}% + \ifmfx@in@phantom + \MFX@popdimen\Mfx@marginheight\mfx@pieceheights + \advance\Mfx@piece@count\m@ne + \mfx@in@phantomfalse + \fi +% \end{macrocode} +% Now we're guaranteed to be in a piece, rather than a phantom, we +% look for a piece that can fit this note, making sure to decrement +% the piece count and pop off a phantom for each new piece we check. +% Once it's found, we add the note back to \cs{mfx@marginout} with +% the corect piece. % \begin{macrocode} -\def\MFX@margin@skip@gobble@up#1{% -%<debug>\MFX@debug{skip@gobble@up: #1}% - \advance\Mfx@marginpos-#1\relax + \if\MFX@check@fit{\advance\Mfx@piece@count\m@ne + \MFX@popdimen\dimen@\mfx@phantomheights}{\ht#1+\dp#1}% + \MFX@snoc\mfx@marginout{% + \noexpand\mfx@build@note{#1}{#2}{\the\Mfx@piece@count}}% + \let\mfx@build@skip\MFX@margin@skip@up + \else\MFX@AssertionError\fi +} +% \end{macrocode} +% Skips are similar, but we have the added complication of handling +% margin phantoms. When we cross between phantom and piece, we split +% the skip so that we can use the simplest recursion possible. +% \begin{macrocode} +\def\MFX@margin@skip@up#1{% +%<debug>\MFX@debug{margin@skip@up: #1}% + \dimen@#1\relax + \advance\Mfx@marginheight-\dimen@ + \ifdim\Mfx@marginheight<\z@ +% \end{macrocode} +% This skip was bigger than the piece, so we need to split this skip, +% adding the overflow back, and try again. Since we're done with this +% piece, we'll pop the next one and recurse on whatever's left. This +% looks slightly different depending on whether or not we're in a phantom. +% \begin{macrocode} + \advance\dimen@\Mfx@marginheight + \MFX@snoc\mfx@marginout{% + \noexpand\mfx@build@skip{\the\dimen@}{\the\Mfx@piece@count}}% + \dimen@-\Mfx@marginheight + \ifmfx@in@phantom + \MFX@popdimen\Mfx@marginheight\mfx@pieceheights + \advance\Mfx@piece@count\m@ne + \mfx@in@phantomfalse + \else + \MFX@popdimen\Mfx@marginheight\mfx@phantomheights + \mfx@in@phantomtrue + \fi + \mfx@build@skip\dimen@ + \else +% \end{macrocode} +% This skip fit entirely within the phantom, so we simply emit it. +% \begin{macrocode} + \MFX@snoc\mfx@marginout{% + \noexpand\mfx@build@skip{\the\dimen@}{\the\Mfx@piece@count}}% + \fi } % \end{macrocode} % \end{macros} % -% \begin{macros}{\MFX@margin@note@up} -% Once we actually do hit a note, we need to set it in \cs{Mfx@marginbox}. -% We also redefine \cs{mfx@margin@skip} and \cs{mfx@margin@compressible} -% here. Hopefully any skips aren't being dropped by our \cs{unvbox}ing. +% \subsection{Margin pieces} +% \begin{macros}{\MFX@buildmargin@pieces,\MFX@buildmargin@piece} +% Before we can start the third and fourth passes, we need to set up +% a loop over the pieces so that each piece can do these passes at +% one time. In case we didn't use up all the pieces in the second +% phase, we'll reset \cs{Mfx@piece@count} to zero. We also reset +% \cs{Mfx@marginspace} and \cs{Mfx@marginbox}. +% \begin{macrocode} +\def\MFX@buildmargin@pieces{% + \Mfx@piece@count\z@ + \Mfx@marginspace\z@ + \setbox\Mfx@marginbox\vbox{\vskip\z@}% TODO - do we need this? +% \end{macrocode} +% Now we run over the individual margin pieces, clearing it out as we +% build up the contents of \cs{Mfx@marginbox}. Once we're done with +% that, we need to do a bit of clean-up before finishing. % \begin{macrocode} -\def\MFX@margin@note@up#1{% -%<debug>\MFX@debug{note@up: #1}% - \setbox\Mfx@marginbox\vbox{\box#1\unvbox\Mfx@marginbox}% - \let\mfx@margin@skip\MFX@margin@skip@up - \let\mfx@margin@compressible\MFX@margin@compressible@up + \let\@elt\MFX@buildmargin@piece + \MFX@run@clear\mfx@marginpieces + \let\@elt\relax + \Mfx@piece@count\z@ +} +% \end{macrocode} +% +% The \cs{MFX@buildmargin@piece} macro is called for each piece of +% the margin, and is passed the top and bottom positions of the piece. +% Here we need to do a few things. First, if the output so far is +% smaller than the top of the piece (this is generally true, except +% sometimes for the first piece) then we need to insert padding into +% \cs{Mfx@marginbox} before continuing. We accumulate this padding +% into \cs{Mfx@marginspace}, which allows skips to do double-duty +% across phantoms. +% \begin{macrocode} +\def\MFX@buildmargin@piece#1#2{% +%<debug>\MFX@debug{buildmargin@piece: ENTRY (#1, #2)}% + \ifdim\ht\Mfx@marginbox<#1\relax + \dimen@\dimexpr#1-\ht\Mfx@marginbox\relax +%<debug>\MFX@debug{buildmargin@piece: padding \the\dimen@}% + \setbox\Mfx@marginbox\vbox{% + \unvbox\Mfx@marginbox + \vskip\dimen@ + }% + \advance\Mfx@marginspace\dimen@ + \fi +% \end{macrocode} +% Now that \cs{Mfx@marginbox} has been padded, we proceed to set +% things up for our down and up passes, and then run them to build +% \cs{Mfx@piece@content}. +% \begin{macrocode} + \Mfx@marginpos@min#1\relax + \Mfx@marginpos@max#1\relax + \Mfx@marginheight#2\relax + \advance\Mfx@piece@count\@ne + \MFX@buildpiece@down + \MFX@buildpiece@up +% \end{macrocode} +% Once \cs{Mfx@piece@content} has been built, we append it to the +% \cs{Mfx@marginbox}. +% \begin{macrocode} + \setbox\Mfx@marginbox\vbox{% + \unvbox\Mfx@marginbox + \box\Mfx@piece@content + \vskip\z@ + }% } % \end{macrocode} % \end{macros} % -% \begin{macros}{\MFX@margin@skip@up} -% This one is even easier---all we have to do is add a skip to the -% margin output box. We also need to make sure it's not getting dropped, -% which might entail adding some \cs{vbox}\lit\{\lit\}s. +% \subsection{Third pass: piecewise downward} +% \begin{macros}{\MFX@buildpiece@down,\mfx@pieceout} +% The next pass is another downward pass. This is very similar +% to the first (global downward) pass, except we're now moving +% the first several notes from \cs{mfx@marginout} into +% \cs{mfx@pieceout} (again, inverting the order) and deferring +% the rest back into \cs{mfx@marginout}. % \begin{macrocode} -\def\MFX@margin@skip@up#1{% -%<debug>\MFX@debug{skip@up: #1}% - \setbox\Mfx@marginbox\vbox{\vskip#1\relax\unvbox\Mfx@marginbox}% +\def\MFX@buildpiece@down{% +%<debug>\MFX@debug{buildpiece@down: ENTRY piece=\the\Mfx@piece@count, +%<debug> marginpos=(\the\Mfx@marginpos@min, \the\Mfx@marginpos@max), +%<debug> marginspace=\the\Mfx@marginspace, +%<debug> marginout=\MFX@mac\mfx@marginout}% + \let\mfx@build@note\MFX@piece@note@down + \let\mfx@build@skip\MFX@piece@skip@down + \let\mfx@pieceout\@empty + \MFX@run@clear\mfx@marginout +%<debug>\MFX@debug{buildpiece@down: RETURN pieceout=\MFX@mac\mfx@pieceout, +%<debug> marginout=\MFX@mac\mfx@marginout}% } % \end{macrocode} % \end{macros} % -% \begin{macros}{\MFX@margin@compressible@up} -% This token gets put into \cs{mfx@marginout} during the first pass. -% When it executes, it inserts a \cs{vskip} depending on how -% much extra margin space (stored in \cs{Mfx@marginpos}) -% we need to excise. If also updates \cs{Mfx@marginpos}. +% \begin{macros}{\MFX@piece@note@down,\MFX@piece@skip@down,\MFX@piece@clear} +% We again define each of our building macros. First, the note builder. +% When we encounter a note, we first zero out \cs{Mfx@marginspace}. Then +% we need to decide whether to put it in the current piece, or whether +% to defer it to the next piece, based on a few signals. A note will only +% be deferred for one of two reasons. In either case, we store the decision +% to defer in |@tempswa|, so we'll start by clearing it. % \begin{macrocode} -\def\MFX@margin@compressible@up#1{% -%<debug>\MFX@debug{compressible@up: #1, excess=\the\dimexpr -%<debug> \Mfx@marginpos-\Mfx@marginheight\relax}% - \dimen@#1\relax - \ifdim\Mfx@marginpos>\Mfx@marginheight - \advance\dimen@\dimexpr\Mfx@marginheight-\Mfx@marginpos\relax - \ifdim\dimen@<\z@ - \dimen@\z@ +\def\MFX@piece@note@down#1#2#3{% +%<debug>\MFX@debug{piece@note@down: ENTRY: #1at #2, lowest=#3, +%<debug> marginpos=(\the\Mfx@marginpos@min,\the\Mfx@marginpos@max, +%<debug> marginspace=\the\Mfx@marginspace}% + \Mfx@marginspace\z@ + \@tempswafalse +% \end{macrocode} +% The first reason to defer is if its callout position (|#2|) +% is beneath the end of the current piece (\cs{Mfx@marginheight}) \emph{and} +% if its lowest-possible-piece (|#3|, as computed in the second pass) is +% \emph{after} the current one (\cs{Mfx@piece@count}). +% \begin{macrocode} + \ifdim#2>\Mfx@marginheight + \ifnum#3>\Mfx@piece@count + \@tempswatrue \fi - \advance\Mfx@marginpos\dimexpr\dimen@-#1\relax \fi +% \end{macrocode} +% The second possibility is that we've run out of room in this piece. +% In this case, there's no need to check |#3|, since that number was +% computed assuming everything that fit was as low as possible. +% \begin{macrocode} + \ifdim\dimexpr\ht#1+\dp#1+\Mfx@marginpos@min>\Mfx@marginheight + \@tempswatrue + \fi +% \end{macrocode} +% If a note is deferred, then we push it and everything after it +% back onto \cs{mfx@marginout}. +% \begin{macrocode} + \if@tempswa +%<debug>\MFX@debug{piece@note@down: clearing margin}% + \MFX@piece@clear + \mfx@build@note{#1}{#2}{#3}% + \else +% \end{macrocode} +% Otherwise, we have decided the note is going into this piece. In this +% case, we now need to check if any compressible space is needed above it. +% In order to get better alignment for deferred notes, we check for the +% case that the current position is zero and the note's callout position +% is \cs{MFX@minus@inf}. In this case, we change the callout position +% to instead be the greater of 0 or $\cs{topskip}-\cs{ht}\#1$. +% \begin{macrocode} + \dimen@#2\relax + \ifdim\dimen@=\MFX@minus@inf + \ifdim\Mfx@marginpos@max=\z@ + \dimen@\topskip + \advance\dimen@-\ht#1\relax + \ifdim\dimen@<\z@ \dimen@\z@ \fi + \fi + \fi + \advance\dimen@-\Mfx@marginpos@max + \ifdim\dimen@>\z@ +%<debug>\MFX@debug{piece@note@down: adding compressible \the\dimen@}% + \MFX@snoc\mfx@pieceout{\noexpand\mfx@build@compressible{\the\dimen@}}% + \advance\Mfx@marginpos@max\dimen@ + \fi +% \end{macrocode} +% After (maybe) adding the compressible space, we now add the +% (incompressible) box itself, and accumulate its height in both position +% registers. We no longer need the piece index or the position, so we +% only store the box itself here. +% \begin{macrocode} + \MFX@snoc\mfx@pieceout{\noexpand\mfx@build@note{#1}}% + \advance\Mfx@marginpos@min\dimexpr\ht#1+\dp#1\relax + \advance\Mfx@marginpos@max\dimexpr\ht#1+\dp#1\relax + \fi +} +% \end{macrocode} +% +% Skips are a bit more complicated now. We no longer gobble the +% initial skips (since the skips at the top and bottom of the page +% have already been eaten). Instead, we need to look at +% \cs{Mfx@marginspace}: if it's nonzero, we substract it from the +% skip length before adding it incompressibly (if there's any left). +% While we have piece number information here, we just pass it on +% to the upward pass, which can choose to ``late-defer'' initial +% (i.e. the bottom-most) skips in a piece. +% \begin{macrocode} +\def\MFX@piece@skip@down#1#2{% + \dimen@#1\relax + \ifdim\Mfx@marginspace>\z@ + \advance\dimen@-\Mfx@marginspace + \ifdim\dimen@<\z@ \dimen@\z@ \fi + \advance\Mfx@marginspace-\dimen@ + \fi +% \end{macrocode} +% At this point, \cs{dimen@} now stores any further incompressible +% skip we need to add, which is now relative to the top of this piece. +% In that case (note that \cs{Mfx@marginspace} is now necessarily zero), +% we need to check that it actually fits in the current piece, and if +% not, defer it. +% \begin{macrocode} \ifdim\dimen@>\z@ - \MFX@margin@skip@up\dimen@ + \ifdim\dimexpr#1+\Mfx@marginpos@min>\Mfx@marginheight + \MFX@piece@clear + \mfx@build@skip{\the\dimen@}{#2}% + \else +% \end{macrocode} +% If the skip \emph{does} fit, we need to add it to \cs{mfx@pieceout} +% and advance the position registers. +% \begin{macrocode} + \MFX@snoc\mfx@pieceout{\noexpand\mfx@build@skip{\the\dimen@}{#2}}% + \advance\Mfx@marginpos@min\dimen@ + \advance\Mfx@marginpos@max\dimen@ + \fi + \fi +} +% \end{macrocode} +% +% Finally, we need to handle the case of deferring material. By +% analogy with the previous two passes, we'll continue to refer to +% this as clearing. In this case, we need to redefine the note and +% skip macros to save themselves back to \cs{mfx@marginout}. +% \begin{macrocode} +\def\MFX@piece@clear{% +%<debug>\MFX@debug{piece@clear}% + \def\mfx@build@note##1##2##3{% + \MFX@cons\mfx@marginout{\noexpand\mfx@build@note##1{##2}{##3}}}% + \def\mfx@build@skip##1##2{% + \MFX@cons\mfx@marginout{\noexpand\mfx@build@skip{##1}{##2}}}% +} +% \end{macrocode} +% \end{macros} +% +% \subsection{Fourth pass: piecewise upward} +% \begin{macros}{\MFX@buildpiece@up} +% We are now ready for the final pass, where we take the reversed +% list of notes for this piece and stack them up, compressing as much +% compressible space as necessary to make them all fit. Since this +% is the last pass, we can finally prepend all the boxes into +% \cs{Mfx@piece@content}. Because it is still possible for pieces +% to have skips at the bottom, we need to worry about which piece +% these skips belong in. Since we've passed forward the lowest-piece +% information from pass 2, we can choose at the last possible moment +% to defer the bottom-most skips of a piece to the next piece (by +% prepending it to \cs{mfx@marginout}. Note that compressible spaces +% will \emph{never} be at the beginning of \cs{mfx@pieceout}. We +% store the excess space in \cs{Mfx@marginheight}. +% \begin{macrocode} +\def\MFX@buildpiece@up{% + \Mfx@marginheight\dimexpr\Mfx@marginpos@max-\Mfx@marginheight\relax + \ifdim\Mfx@marginheight<\z@\Mfx@marginheight\z@\fi +%<debug>\MFX@debug{buildpiece@up: excess=\the\Mfx@marginheight}% + \let\mfx@build@note\MFX@piece@note@up + \let\mfx@build@compressible\MFX@piece@compressible@up + \let\mfx@build@skip\MFX@piece@skip@maybedefer + \MFX@run@clear\mfx@pieceout\relax +} +% \end{macrocode} +% \end{macros} +% +% \begin{macros}{\MFX@piece@skip@maybedefer} +% As mentioned earlier, the initial skips in a piece may be deferred +% to later pieces, provided they can possibly go there. Here we +% check the |#2| argument against \cs{Mfx@piece@count} and defer if +% it is larger. Otherwise, we switch back to the standard behavior +% defined in \cs{MFX@piece@skip@up}. Deferred skips do not need to +% be subtracted from the excess because they were never compressible +% in the first place. +% \begin{macrocode} +\def\MFX@piece@skip@maybedefer#1#2{% + \ifnum#2>\Mfx@piece@count +%<debug>\MFX@debug{piece@skip deferring: #1, #2 (\the\Mfx@piece@count)}% + \MFX@snoc\mfx@marginout{\noexpand\mfx@build@skip{#1}{#2}}% + \else + \let\mfx@build@skip\MFX@piece@skip@up + \mfx@build@skip{#1}{#2}% + \fi +} +% \end{macrocode} +% \end{macros} +% +% \begin{macros}{\MFX@piece@note@up,\MFX@piece@skip@up} +% Now that we've taken care of late deferrals, we can define the +% standard behavior without worrying as much about that. +% These macros finally set their contents into \cs{Mfx@piece@content}, +% as well as reset \cs{mfx@build@skip} back to its standard value. +% \begin{macrocode} +\def\MFX@piece@note@up#1{% +%<debug>\MFX@debug{piece@note@up: #1}% + \setbox\Mfx@piece@content\vbox{% + \box#1% + \unvbox\Mfx@piece@content}% + \let\mfx@build@skip\MFX@piece@skip@up +} +% \end{macrocode} +% Skips are also straightforward. +% \begin{macrocode} +\def\MFX@piece@skip@up#1#2{% +%<debug>\MFX@debug{skip@up: #1=\the\dimexpr#1\relax (#2)}% + \setbox\Mfx@piece@content\vbox{% + \vskip#1\relax + \unvbox\Mfx@piece@content}% +} +% \end{macrocode} +% \end{macros} +% +% \begin{macros}{\MFX@piece@compressible@up} +% Finally we come to the compressible space. Here, as long as +% there's excess space (\cs{Mfx@marginheight}) we drop the +% compressible space. Once the excess is exhausted, we insert +% them as normal skips. +% \begin{macrocode} +\def\MFX@piece@compressible@up#1{% +%<debug>\MFX@debug{compressible@up: #1, excess=\the\Mfx@marginheight}% + \advance\Mfx@marginheight-#1\relax + \ifdim\Mfx@marginheight<\z@ + \MFX@piece@skip@up{-\Mfx@marginheight}\relax + \Mfx@marginheight\z@ \fi } % \end{macrocode} @@ -840,11 +1422,13 @@ %<debug>\MFX@debug{dumpmargins}% \loop \unless\ifx\mfx@marginlist\@empty +%<debug>\MFX@debug{dumpmargins: marginlist=\MFX@mac\mfx@marginlist}% \let\temp@\mfx@marginlist \vbox{}\clearpage \ifx\temp@\mfx@marginlist \PackageError{marginfix}{lost some margin notes% -%<debug>: \meaning\mfx@marginlist + \ifx\mfx@marginstart\relax\ (missing \noexpand\unblockmargin)\fi +%<debug>: \MFX@mac\mfx@marginlist }\@eha \let\mfx@marginlist\@empty % be nicer by just dropping one? % TODO: also, set an emergency mode to allow oversized notes @@ -859,10 +1443,10 @@ % % \begin{macros}{\marginskip} % Inserting a skip in the margin list is simple. We need only -% append \cs{mfx@margin@skip} to \cs{mfx@marginlist}. +% append \cs{mfx@build@skip} to \cs{mfx@marginlist}. % \begin{macrocode} \def\marginskip#1{% - \MFX@cons\mfx@marginlist{\noexpand\mfx@margin@skip{#1}}% + \MFX@cons\mfx@marginlist{\noexpand\mfx@build@skip{#1}}% } % \end{macrocode} % \end{macros} @@ -871,7 +1455,7 @@ % Likewise, \cs{clearmargin} is easy too. % \begin{macrocode} \def\clearmargin{% - \MFX@cons\mfx@marginlist{\noexpand\mfx@margin@clear}% + \MFX@cons\mfx@marginlist{\noexpand\mfx@build@clear}% } % \end{macrocode} % While we call \cs{softclearmargin} a ``clear margin'', it's @@ -904,6 +1488,86 @@ % \end{macrocode} % \end{macros} % +% \begin{macros}{\blockmargin,\MFX@blockmargin} +% We need two macros to process the optional bracket argument. +% Essentially, \cs{blockmargin} just checks that +% \cs{mfx@marginstart} is defined and then appends a new item to +% the \cs{mfx@marginpieces} list to indicate a piece that starts +% at \cs{mfx@marginstart} and ends at the current position, potentially +% modified by the argument. It then resets \cs{mfx@marginstart} to +% \cs{relax} and optionally adds a \cs{softclearmargin} if there was no +% star, to keep margin material separated on either side of the phantom. +% \begin{macrocode} +\def\blockmargin{% + \@ifnextchar[%] + \MFX@blockmargin + {\MFX@blockmargin[0\p@]}% +} +\def\MFX@blockmargin[#1]{% + \MFX@inject{% + \ifx\mfx@marginstart\relax + \PackageError{marginfix}{two \\blockmargin with no \\unblockmargin}\@eha + \else + \MFX@cons\mfx@marginpieces{\noexpand + \@elt{\mfx@marginstart}{\expandafter\dimexpr\mfx@ypos+#1\relax}}% + \global\let\mfx@marginstart\relax + \global\advance\Mfx@piece@count\@ne + \fi + }% +} +% \end{macrocode} +% \end{macros} +% +% \begin{macros}{\unblockmargin,\MFX@unblockmargin} +% This is the other half of \cs{blockmargin}. It ensures that the +% margin is currently blocked, and if so, sets \cs{mfx@marginstart} +% back to a real dimension (the current page position, plus the optional +% modifier). +% \begin{macrocode} +\def\unblockmargin{% + \@ifnextchar[%] + \MFX@unblockmargin + {\MFX@unblockmargin[0\p@]}% +} +\def\MFX@unblockmargin[#1]{% + \MFX@inject{% + \ifx\mfx@marginstart\relax + \xdef\mfx@marginstart{\dimexpr\mfx@ypos+#1\relax}% + \else + \PackageError{marginfix}{\\unblockmargin with no \\blockmargin}\@eha + \fi + }% +} +% \end{macrocode} +% \end{macros} +% +% \begin{macros}{\marginphantom,\MFX@marginphantom} +% The \cs{marginphantom} command is basically just a concatenation of +% \cs{blockmargin} and \cs{unblockmargin}. We reimplement it from the +% ground up mainly so that the error messages make more sense. +% \begin{macrocode} +\def\marginphantom{% + \@ifnextchar[%] + \MFX@marginphantom + {\MFX@marginphantom[0\p@]}% +} +\def\MFX@marginphantom[#1]#2{% + \ifdim#2<\z@\MFX@marginphantom[#1+#2]{-#2}\else + \MFX@inject{% + \ifx\mfx@marginstart\relax + \PackageError{marginfix}{\\marginphantom while margin blocked}\@eha + \else + \MFX@cons\mfx@marginpieces{\noexpand + \@elt{\mfx@marginstart}{\expandafter\dimexpr\mfx@ypos+#1\relax}}% + \xdef\mfx@marginstart{\dimexpr\mfx@ypos+#1+#2\relax}% + \global\advance\Mfx@piece@count\@ne + \fi + }% + \fi +} +% \end{macrocode} +% \end{macros} +% % \section{Random scribbles} % % Later we'll get fancier with putting notes next to top/bottom @@ -917,7 +1581,7 @@ % now that's all we'll do. % % \section{Parting words} -% Finish it up +% Finish it up. % \begin{macrocode} \makeatother %</package> |