Debian Codegraph @

texmf-dist/source/latex/fewerfloatpages/fewerfloatpages.dtx

raw
1 % \iffalse meta-comment
2 %
3 %% File: fewerfloatpages.dtx (C) Copyright 2019-2021 Frank Mittelbach
4 %
5 % It may be distributed and/or modified under the conditions of the
6 % LaTeX Project Public License (LPPL), either version 1.3c of this
7 % license or (at your option) any later version. The latest version
8 % of this license is in the file
9 %
10 % https://www.latex-project.org/lppl.txt
11 %
12 % The development version of the bundle can be found below
13 %
14 % https://github.com/FrankMittelbach/fmitex/
15 %
16 % for those people who are interested or want to report an issue.
17 %
18
19 \def\fewerfloatpagesdate {2021/03/02}
20 \def\fewerfloatpagesversion{v1.0b}
21
22
23 %<*driver>
24 \documentclass
25 [final]
26 {l3doc-TUB}
27 \hfuzz=1.6pt % not even one tt character, don't worry.
28
29 \makeatletter
30 \@mparswitchfalse
31 \makeatother
32
33 \setcounter{page}{1}
34
35 \newcommand\ctr[1]{\texttt{\upshape#1}}
36 \newcommand\option[1]{\texttt{\upshape#1}}
37 \newcommand\mnote[1]{\marginpar{\raggedleft\em #1}}
38
39 \usepackage{csquotes}
40 \EnableCrossrefs
41 \CodelineIndex
42
43
44 \begin{document}
45 \DocInput{fewerfloatpages.dtx}
46 \addtolength\signaturewidth{42pt}
47 \makesignature
48 \end{document}
49 %</driver>
50 %
51 % \fi
52 %
53 %
54 % \title{The \texttt{fewerfloatpages} package\thanks{The current
55 % package version is \texttt{\fewerfloatpagesversion} dated
56 % \fewerfloatpagesdate.}}
57 % \author{Frank Mittelbach}
58 % \address{Mainz, Germany}
59 % \netaddress{https://www.latex-project.org}
60 % \personalURL{https://ctan.org/pkg/fewerfloatpages}
61 %
62 % \maketitle
63 %
64 %
65 % \begin{abstract}
66 %
67 % \LaTeX{}'s float algorithm has the tendency to produce fairly
68 % empty float pages, i.e., pages containing only floats but with a
69 % lot of free space remaining that could easily be filled with nearby
70 % text. There are good reasons for this behavior; nevertheless, the
71 % results look unappealing and in many cases documents are
72 % unnecessarily enlarged.
73 %
74 % The \pkg{fewerfloatpages} package provides an extended algorithm
75 % that improves on this behavior without the need for manual intervention by
76 % the user.
77 %
78 % \end{abstract}
79 %
80 % \microtypesetup{protrusion=false}
81 % \tableofcontents
82 % \microtypesetup{protrusion=true}
83 %
84 % \DoNotIndex{\@fpmin}
85 % \DoNotIndex{\@testwrongwidth}
86 % \DoNotIndex{\@cons}
87 % \DoNotIndex{\@currbox}
88 % \DoNotIndex{\@currtype}
89 % \DoNotIndex{\@elt}
90 % \DoNotIndex{\@empty}
91 % \DoNotIndex{\@gobble}
92 % \DoNotIndex{\@ne}
93 % \DoNotIndex{\@next}
94 % \DoNotIndex{\@spaces}
95 % \DoNotIndex{\@tempcnta}
96 % \DoNotIndex{\@tempcntb}
97 % \DoNotIndex{\@tempdima}
98 % \DoNotIndex{\@tempdimb}
99 % \DoNotIndex{\@testtrue}
100 % \DoNotIndex{\@undefined}
101 % \DoNotIndex{\@vtryfc}
102 % \DoNotIndex{\@xxxii}
103 % \DoNotIndex{\@ztryfc}
104 % \DoNotIndex{\fl@trace}
105 % \DoNotIndex{\@bitor}
106 % \DoNotIndex{\NeedsTeXFormat}
107 % \DoNotIndex{\TeX}
108 % \DoNotIndex{\advance}
109 % \DoNotIndex{\begingroup}
110 % \DoNotIndex{\bx@B}
111 % \DoNotIndex{\bx@D}
112 % \DoNotIndex{\bx@I}
113 % \DoNotIndex{\count}
114 % \DoNotIndex{\def}
115 % \DoNotIndex{\divide}
116 % \DoNotIndex{\else}
117 % \DoNotIndex{\endgroup}
118 % \DoNotIndex{\fi}
119 % \DoNotIndex{\gdef}
120 % \DoNotIndex{\global}
121 % \DoNotIndex{\ht}
122 % \DoNotIndex{\if@test}
123 % \DoNotIndex{\if@twocolumn}
124 % \DoNotIndex{\ifdim}
125 % \DoNotIndex{\ifnum}
126 % \DoNotIndex{\ifodd}
127 % \DoNotIndex{\ifx}
128 % \DoNotIndex{\let}
129 % \DoNotIndex{\maxdimen}
130 % \DoNotIndex{\multiply}
131 % \DoNotIndex{\newcommand}
132 % \DoNotIndex{\newcount}
133 % \DoNotIndex{\newcounter}
134 % \DoNotIndex{\providecommand}
135 % \DoNotIndex{\relax}
136 % \DoNotIndex{\renewcommand}
137 % \DoNotIndex{\reserved@a}
138 % \DoNotIndex{\sixt@@n}
139 % \DoNotIndex{\space}
140 % \DoNotIndex{\string}
141 % \DoNotIndex{\the}
142 % \DoNotIndex{\tw@}
143 % \DoNotIndex{\typeout}
144 % \DoNotIndex{\xdef}
145 % \DoNotIndex{\z@}
146 %
147 %
148 % \section{Introduction}
149
150 % We start by giving a quick overview of \LaTeX{}'s float algorithm
151 % and the problems that result from the approach used.
152 %
153 % We then look in some detail into possible alterations and
154 % improvements to that algorithm and discuss possible issues that
155 % need to be resolved. In this section we also describe all
156 % configuration possibilities of the extended algorithm.
157 %
158 % The final section then documents the code changes that are
159 % necessary to \LaTeX{} kernel macros to implement the extension.
160 %
161 % \subsection{A quick overview of \LaTeX's float algorithm}
162 %
163 % \LaTeX{}'s output routine uses a greedy algorithm to place floats
164 % near to their call-outs in the source document. The decision of how
165 % to place a float is made when the float is first encountered. If
166 % possible it is placed onto the current page, either in mid-text,
167 % on top or into the bottom area, depending on what is allowed for
168 % the float and how many floats are already placed into those
169 % areas.
170 %
171 % If the float can't be placed immediately, it goes into a defer
172 % list, and in order to not accumulate too many unplaced floats
173 % \LaTeX{} tries to empty that list whenever there is a chance. This
174 % chance comes after the next page break: \LaTeX{} then starts a
175 % special ``float page'' algorithm in which it examines the defer
176 % list and from it forms float pages (i.e., pages that contain only
177 % floats). If necessary, it generates several float pages and only
178 % stops if there are no floats waiting to be placed, or there are
179 % too few floats to form a float page, or there are only floats left
180 % that are for one or another reason not allowed to be placed in
181 % this way.
182 %
183 % Finally \LaTeX{} looks at the remaining floats and tries to place
184 % as many of them as possible into the top and bottom area of the
185 % next page. Then it continues to process further text to fill the
186 % text part of that page. Details on the exact behavior of the
187 % algorithm are discussed in \cite{fmi:floatplacement}.
188 %
189 %
190 % \subsection{The typical float page and its problems}
191 %
192 % \LaTeX{} considers a float page to be successfully built if its
193 % floats take up more than \cs{floatpagefraction} of the whole
194 % page. By default this parameter is set to \texttt{.5} which means
195 % that such float pages may end up being half empty.
196 %
197 % Many users think that this is not a good value and try to improve on
198 % it by enforcing a higher percentage (such as 80\%) only to find
199 % that this prevents \LaTeX{} in many cases from successfully
200 % generating any float page, with the effect that all floats are
201 % suddenly piling up at the end of the document.
202 %
203 % Why is this the case? In a nutshell, because a higher percentage
204 % makes it much more likely that a float can't be
205 % placed, because it is not big enough to be used on its
206 % own and no other nearby floats can be combined with
207 % it, because their combination violates some other restriction,
208 % e.g., together they are bigger than a page, not all of them are
209 % allowed to go on float pages, etc. The moment that happens this
210 % float prevents the placement of all later floats of the same
211 % class too (i.e., all figures) and disaster is ensured. In most
212 % cases these floats will then never get placed, because they need a
213 % float of the right size from a different class to appear, which
214 % may in theory happen but is, unfortunately, unlikely.
215 %
216 % Thus,\mnote{Tinkering with the parameter settings will usually
217 % produce unwanted effects} while tempting, tinkering with this
218 % parameter by making it larger is usually not a good idea, unless
219 % you are prepared to place most if not all of your floats
220 % manually, by overwriting the placement algorithm on the level of
221 % individual floats (e.g., using \texttt{!}\@ syntax and/or
222 % shifting its position in the source document).
223 %
224 % Why does the current algorithm have these problems? To some extent,
225 % because it offers only global parameters that need to fit
226 % different scenarios and thus settings that are suitable when many
227 % floats need to be placed result in sub-optimal paginations in
228 % document parts that contain only a few floats, and vice versa.
229 % To overcome this problem, either one can try to develop
230 % algorithms with many more configurable parameters that act
231 % differently in different scenarios or one can let the algorithm
232 % follow a main strategy, configurable with only a few parameters
233 % (like today), but monitor the process and make more local
234 % adjustments and corrections depending on the actual outcome of
235 % that base strategy and additional knowledge of the actual
236 % situation in a given document part. This is the
237 % approach taken by the extension implemented in this package.
238 %
239 % \section{Improvements to the float page algorithm}
240 %
241 % A simple way to improve on the existing algorithm, without
242 % compromising its main goal of placing the floats as fast as
243 % possible and as close as possible to their call-outs, is the
244 % following: as long as there are many floats waiting to be placed,
245 % generate float pages as necessary to get them placed (using the
246 % current algorithm and its parameters).
247
248 % Once we are unable to build further float pages, do some level
249 % of backtracking by checking if we have actually succeeded in
250 % placing all floats. If there are still floats waiting to be
251 % placed then assume that what has been done so far is the best
252 % possible way to place as many floats as possible (which it
253 % probably is). However, if we have been able to place all floats
254 % onto float pages then check if the last float page is
255 % sufficiently full; if not, undo that float page and instead
256 % redistribute its floats into the top and bottom area of the next
257 % upcoming page. This way the floats will be combined with further
258 % text and we avoid a possible half-empty float page.
259 %
260 % This approach will not resolve all the problematic scenarios
261 % where we find that \LaTeX{} has decided to favor fairly empty
262 % float pages over some tighter type of placement. It will,
263 % however, help to improve typical cases that do not involve too
264 % many floats. For\mnote{A typical case where we don't really want
265 % \LaTeX{} to make a float page} a example, if a single (larger)
266 % float appears near the end of a page, then using the standard
267 % algorithm it can't be immediately placed (because there isn't
268 % enough free space on the current page). It is therefore moved to
269 % the defer list and at the page break it is then placed onto a
270 % float page (possibly by itself, if it is large enough to allow
271 % for that) even though it could perfectly well go into the top or
272 % bottom area of the next page and thus be combined with textual
273 % material on that page.
274 %
275 % With the new algorithm this float page is reexamined and unless
276 % it is pretty much filled up already, it is unraveled and its
277 % floats are redistributed into the top and bottom areas of the
278 % next page. If, however, we have many floats waiting on the defer
279 % list, the normal float page algorithm will first place as many of
280 % them as possible into float pages and only the last of these
281 % pages will be subject to a closer inspection and a possible
282 % unraveling.
283 %
284 % An extension of this idea (and the one that we actually
285 % implement) is to monitor the whole float page generation process
286 % and instead of just considering the last float page in the sequence
287 % for unraveling, we look at each prospective float page in turn and
288 % based on the current situation (e.g., number of floats still
289 % being unplaced, free space on the float page, etc.)\@ decide
290 % whether this float page should be produced or whether we should
291 % stop making float pages and instead place the pending floats into
292 % top and bottom areas of the upcoming page.
293 %
294 %
295 % \subsection{Details on the extended algorithm}
296 %
297 % The main idea of the extended algorithm is to avoid unnecessary cases of
298 % float pages especially if those float pages are fairly
299 % empty.\mnote{Don't unravel a float page if there are too many
300 % floats on the defer list}
301 % Natural candidates are single float pages, but even in cases where
302 % the current \LaTeX{} algorithm produces several sequential float
303 % pages the extended algorithm may decide to replace them by normal
304 % pages under certain conditions.
305 % However, the main goal
306 % is and should remain to place as many floats as soon as possible
307 % and so generating float pages when many floats are waiting is
308 % usually essential.
309 %
310 % \begin{variable}{floatpagedeferlimit}
311 % \begin{syntax}
312 % \cs{setcounter}\{floatpagedeferlimit\}\Arg{number}
313 % \end{syntax}
314 % Whether or not unraveling for a float page is considered at all
315 % is guided by the counter \ctr{floatpagedeferlimit}. As long as
316 % there are more floats waiting on the defer list than this number,
317 % float pages are not considered for unraveling. The default is
318 % \texttt{3} which corresponds to the default value for
319 % \ctr{totalnumber}, i.e., with that setting the unraveling of a
320 % floating page has a fighting chance to place all floats into the
321 % top and bottom areas on the current page.
322 % It would also resolve cases for up to three floats, each larger than
323 % \cs{floatpagefraction}, where the standard \LaTeX{} algorithm would
324 % produce three individual float pages.\strut
325 % \end{variable}
326 %
327 % If you set the counter to \texttt{1} then only the last float
328 % page in a sequence is considered, and only if it contains only a
329 % single float and if there are no other floats that are still
330 % waiting to be placed. If you set it to \texttt{0}, then the
331 % extension is disabled, because float pages are produced only if
332 % there was at least one float on the defer list.
333 %
334 % Even\mnote{Don't unravel if the float page contains many floats}
335 % if we set \ctr{floatpagedeferlimit} to a fairly high value, we
336 % may not want to unravel float pages that contain many floats. To
337 % support this case there is a second counter that guides the
338 % algorithm in this respect.
339 %
340 % \begin{variable}{floatpagekeeplimit}
341 % \begin{syntax}
342 % \cs{setcounter}\{floatpagekeeplimit\}\Arg{number}
343 % \end{syntax}
344 % Whenever the float page contains at least
345 % \ctr{floatpagekeeplimit} floats it will not be unraveled. The
346 % default is also \texttt{3} so that float pages with three or more
347 % floats are not touched. Obviously the counter can have any effect
348 % only if it has a value less than or equal to
349 % \ctr{floatpagedeferlimit} because this is tested first.\strut
350 % \end{variable}
351 %
352 %
353 % There are, however, a number of other situations in which we
354 % shouldn't unravel a float page even if the above checks for the
355 % size of the defer list were passed successfully.\mnote{Don't
356 % unravel if the float page contains at least one \texttt{\upshape
357 % [p]} float} The most important one is the case when the float
358 % page contains at least one float that is allowed \emph{only} on
359 % float pages (i.e., has a \texttt{[p]} argument). Such a float
360 % would not be placeable in a top/bottom area on any page and thus
361 % would be repeatedly sent back to the defer list (possibly forever).
362 %
363 % The other case where unraveling would normally be
364 % counterproductive is when the particular float page is nearly or
365 % completely filled up with floats.\mnote{Don't unravel if the
366 % float page is nearly filled} If we unravel it, then it is
367 % certain that we can place only some of the floats into the top or
368 % bottom area of the next page, while some would end up on the defer
369 % list. That in turn means that these deferred floats float even
370 % further away from their call-out positions than need be.
371 %
372 % \begin{variable}{\floatpagekeepfraction}
373 % \begin{syntax}
374 % \cs{renewcommand}\cs{floatpagekeepfraction}\Arg{decimal}
375 % \end{syntax}
376 % So what is a good way to determine if a float page is ``full
377 % enough''? A possible answer is that if the remaining free space
378 % on that page is less than \cs{textfraction} we consider it full
379 % enough to stay. \cs{textfraction} defines the minimum amount of
380 % space that has to be occupied by text on a normal page, thus if
381 % all floats together need so much space that this amount of text
382 % could not fit, then trying to place all floats onto a
383 % normal page can't succeed and some of them would get deferred for
384 % sure. To allow for further flexibility the algorithm uses
385 % the variable \cs{floatpagekeepfraction} (defaulting to
386 % \cs{textfraction}) so if desired a lower (or even a higher)
387 % boundary can be set.\strut
388 % \end{variable}
389 %
390 % The above parameters give some reasonable configuration
391 % possibilities to guide the algorithm as to when and when not to unravel
392 % a possible float page and instead produce further normal pages.
393 % It should be noted, however, that except for the case of setting
394 % \ctr{floatpagedeferlimit} to \texttt{1}, there is always a chance
395 % that floats drift further away from their call-outs, because they
396 % may not be immediately placeable due to other parameter settings
397 % of the float algorithm. For example, the counter
398 % \texttt{topnumber} (default value 2) limits the number of floats
399 % that can be placed in the top area on a normal page and if more
400 % remain after unraveling only two can immediately go in this area.
401 %
402 %
403 % \subsection{Possible pitfalls and how to avoid them}
404 %
405 % The algorithm detects if a float is allowed only on float pages
406 % (i.e., is given in the source as \texttt{[p]}) and it will ensure
407 % that float pages containing such floats are not unraveled.
408 %
409 % However, if you have a float with the default specifier
410 % \texttt{[tbp]} whose size is larger than the allowed size of the
411 % top or bottom area (e.g., larger than \cs{topfraction}
412 % \texttimes{} \cs{textheight}), then this effectively means it can
413 % only be placed on a float page.
414 %
415 % However, according to the specifier the float is allowed to go
416 % into the top or bottom area, so the algorithm, as explained so
417 % far, would be allowed to unravel and when that float later is
418 % considered for top or bottom placement it will get again deferred
419 % and thus move from one page to the next, most likely messing up
420 % the whole float placement.
421 %
422 % There\mnote{\option{checktb} (option)} are two possible ways to
423 % improve the algorithm to avoid this disaster. One way
424 % would be to check the float size when it is initially encountered
425 % and remove any specifier that is technically not possible because
426 % of the parameter settings and the float size. A possible
427 % disadvantage is that this determination will be done once and any
428 % later (temporary) change to the float parameters will have no
429 % effect. This is currently the package default. It can be
430 % explicitly selected by specifying the option \option{checktb}. In
431 % this case you might see warnings like
432 %\begin{verbatim}
433 % LaTeX Warning: Float too large for top area: t changed to p on line ...
434 %\end{verbatim}
435 %
436 % Another\mnote{\option{addbang} (option)} possibility is that we automatically add a
437 % \texttt{!}\@ specifier to all floats during unraveling, i.e., when
438 % we send them back for reevaluation. This way such floats become
439 % placeable into top and bottom areas regardless of their size. This
440 % may result in fewer pages at the cost of violating the area size
441 % restrictions once in a while. It is specified with the option \option{addbang}.
442 %
443 % If\mnote{\option{nocheck} (option)} you prefer no automatic
444 % adjustment of the specifiers, add the option \option{nocheck}.
445 % In this case you might find that floats of certain sizes are
446 % unplaceable and thus get delayed to the end of the document. If
447 % that happens, the remedy is either to explicitly specify
448 % \texttt{[p]} or \texttt{[hp]} for such a float (to ensure that
449 % they aren't subject to unraveling) or to manually add an
450 % exclamation specifier, e.g., \texttt{[!tp]} so that \LaTeX{}
451 % doesn't use the size restrictions in its algorithm.
452 %
453 %
454 %
455 % \subsection{Tracing the algorithm}
456 %
457 % The\mnote{\option{trace} (option)} package offers the option
458 % \option{trace}, which if used, will result in messages such as
459 %\begin{verbatim}
460 % [1]
461 % fewerfloatpages: PAGE: trying to make a float page
462 % fewerfloatpages: ----- \@deferlist: \bx@B \bx@D
463 % fewerfloatpages: starting with \bx@B
464 % fewerfloatpages: --> success: \bx@B \bx@D
465 % fewerfloatpages: ----- current float page unraveled
466 % (free space 192.50336pt > 109.99832pt)
467 % [2]
468 %\end{verbatim}
469 % which means that the algorithm is trying to make a float page
470 % from the defer list which at that point contained two floats (the
471 % float boxes \cs[no-index]{bx@B} and \cs[no-index]{bx@D}), that it
472 % was able to produce a float page containing just
473 % \cs[no-index]{bx@B} and \cs[no-index]{bx@D}, and that the extended
474 % algorithm then decided to unravel that float page, because it has
475 % an unused space of \texttt{192.5pt}, i.e., roughly 16 text lines. With the current
476 % \cs{floatpagekeepfraction} that is too much empty space on the
477 % page.
478 %
479 % Or it might say
480 %\begin{verbatim}
481 % fewerfloatpages: PAGE: trying to make a float page
482 % fewerfloatpages: ----- \@deferlist: \bx@D \bx@F \bx@G \bx@H \bx@I
483 % fewerfloatpages: starting with \bx@D
484 % fewerfloatpages: --> success: \bx@D \bx@F
485 % fewerfloatpages: ----- too many deferred floats for unraveling (5 > 3)
486 % [3]
487 %\end{verbatim}
488 % which means that the algorithm made a float page out of the first
489 % two floats from the defer list (i.e., 3 remained).
490 % That
491 % page was kept regardless of the amount of free space it contained
492 % because we have a total of 5 floats on the defer list and the
493 % counter \ctr{floatpagedeferlimit} has its default value of \texttt{3}.
494 %
495 % The above tracing messages are both from the same test
496 % document. What they also (implicitly) show is that the unraveling
497 % that happened after page~1 resulted in only one float (\cs[no-index]{bx@B})
498 % being placed on page~2, because we see the second one (\cs[no-index]{bx@D})
499 % reappearing in the defer list after page~2 got finished. In other
500 % words it was moved one page further away from its call-out: the
501 % price for getting a nicely filled page~2 instead of a fairly empty
502 % float page with roughly 200 points left empty.
503 % The final part of that test document then exhibits another
504 % type of message:
505 %\begin{verbatim}
506 % fewerfloatpages: PAGE: trying to make a float page
507 % fewerfloatpages: ----- \@deferlist: \bx@G \bx@H \bx@I
508 % fewerfloatpages: starting with \bx@G
509 % fewerfloatpages: --> success: \bx@G \bx@H \bx@I
510 % fewerfloatpages: ----- all floats placed on float page(s)
511 % fewerfloatpages: ----- current float page kept, full enough
512 % (free space 38.99496pt < 109.99832pt)
513 % [4]
514 %\end{verbatim}
515 % This means that the remaining floats (that were left unplaced
516 % after float page~3 got constructed) formed a float
517 % page and that float page was the last in sequence (i.e., all
518 % floats have been placed). However, this time the algorithm decided not
519 % to unravel it, because it is nicely full: there are only 39 points
520 % of free space left on that page.
521 %
522 % Three other possible messages are shown in this sequence of
523 % tracing lines from a second test document (which is using some uncommon
524 % settings: \ctr{floatpagedeferlimit} is \texttt{10} and
525 % \ctr{floatpagekeeplimit} is \texttt{5}):
526 %\begin{verbatim}
527 % [1]
528 % fewerfloatpages: PAGE: trying to make a float page
529 % fewerfloatpages: ----- \@deferlist: \bx@B \bx@C \bx@D \bx@E \bx@F \bx@G \bx@H
530 % fewerfloatpages: starting with \bx@B
531 % fewerfloatpages: --> success: \bx@B \bx@C \bx@D \bx@E \bx@F \bx@G \bx@H
532 % fewerfloatpages: ----- current float page kept (contains at least 5 floats)
533 % [2] [3]
534 %\end{verbatim}
535 % In this case 7 floats have been waiting on the defer list and the
536 % algorithm was able to construct a float page using all of them.
537 % The algorithm then keeps that page because it has 5 or more floats
538 % in it (the value of the \ctr{floatpagekeeplimit} counter).
539 %
540 % The next message in that test document shows what happens
541 % when there are not enough floats waiting or they are simply too
542 % small (to even get past the \cs{floatpagefraction} limit):
543 %\begin{verbatim}
544 % fewerfloatpages: PAGE: trying to make a float page
545 % fewerfloatpages: ----- \@deferlist: \bx@I \bx@J
546 % fewerfloatpages: starting with \bx@I
547 % fewerfloatpages: --> fail
548 % fewerfloatpages: starting with \bx@J
549 % fewerfloatpages: --> fail
550 % fewerfloatpages: --> fail: no float page made
551 % [4]
552 %\end{verbatim}
553 % So no float page was made, but for some reason (that becomes clear
554 % later) the two floats also didn't got distributed into the top or
555 % bottom area of the next page. Instead they remained on the
556 % defer list and during processing of page~4 one more float was
557 % found so that after that page the defer list had grown to
558 % length~3:
559 %
560 %\begin{verbatim}
561 % fewerfloatpages: PAGE: trying to make a float page
562 % fewerfloatpages: ----- \@deferlist: \bx@I \bx@J \bx@K
563 % fewerfloatpages: starting with \bx@I
564 % fewerfloatpages: --> success: \bx@I \bx@J \bx@K
565 % fewerfloatpages: ----- current float page kept, contains a float
566 % fewerfloatpages: with p but no t or b specifier
567 % [5]
568 %\end{verbatim}
569 % This time all floats could be placed, but again the float page
570 % wasn't unraveled (even though in the test document it contained a
571 % lot of white space) because of the fact that one of its floats (in fact
572 % the first though that can only be deduced implicitly) was
573 % specified as a \enquote{float page only} float. This explains why
574 % on page~4 \cs[no-index]{bx@I} couldn't be placed into the top or bottom
575 % area and then all following floats of the same class (the test
576 % document contained only \env{figure} floats) couldn't be placed
577 % either.
578 %
579 % If\mnote{Detailed tracing of the complete algorithm} you want
580 % detailed tracing of the complete algorithm, also load the
581 % \pkg{fltrace} package and enable the tracing with
582 % \cs{tracefloats} anywhere in your document. Note, however, that
583 % the resulting output is very detailed but rather low-level and
584 % unpolished.
585 %
586 %
587 %
588 %
589 %
590 % \subsection{Local (manual) adjustments}
591 %
592 % If the extended algorithm is used you will get fewer float pages
593 % that contain a noticeable amount of white space. By adjusting
594 % \cs{floatpagekeepfraction} and the counters \ctr{floatpagekeeplimit} and
595 % \ctr{floatpagedeferlimit} you can direct the algorithm to unravel more or
596 % fewer of the otherwise generated float pages. However, in some cases
597 % it might happen that redistribution of the floats into the top and
598 % bottom areas of the next page(s) may result in some of them
599 % drifting too far away from their call-outs. If that happens, you can
600 % either try to change the general parameters or you could help the
601 % algorithm along by using the optional argument of individual float
602 % environments.
603 % The two main tools at your disposal are
604 % \begin{itemize}
605 % \item
606 % using the \texttt{[!..]} notation to allow the float to go into
607 % the top or bottom area even if it would be normally prevented by
608 % other restrictions;
609 % \item
610 % using \texttt{[p]} to force a float into a float page as that
611 % prevents the algorithm from unravelling the float page which contains
612 % that float.
613 % \end{itemize}
614 % As an alternative you can, of course, temporarily alter the
615 % definition of the command \cs{floatpagekeepfraction} or the values
616 % of two counters in mid-document, but remember that they are not
617 % looked at when a float is encountered in the source but when we
618 % are at a page break and \LaTeX{} attempts to empty the defer list,
619 % which is usually later and unfortunately somewhat asynchronous,
620 % i.e., not easy to predict.
621 %
622 %
623 % \StopEventually{
624 % \begin{thebibliography}{1}
625 % \raggedright
626 % \bibitem{fmi:floatplacement}
627 % Frank Mittelbach.
628 % \newblock How to influence the position of float environments like figure and table in \LaTeX?
629 % \newblock \textsl{TUG}boat 35:3, 2014.\\
630 % \newblock \url{https://www.latex-project.org/publications/indexbytopic/2e-floats/}
631 % \bibitem{source2e}
632 % \LaTeX{} Project Team.
633 % \newblock The \LaTeXe{} Sources (660+ pages), 2020.\\
634 % \newblock \url{https://www.latex-project.org/help/documentation}
635 % \end{thebibliography}
636 % \ifx\thisissuepageref\undefined ^^A is this TUB production ??? if not gen index
637 % \setlength\IndexMin{200pt} \PrintIndex
638 % \fi
639 %}
640 %
641 %
642 %
643 % \section{The implementation}
644 %
645 % We start off with the package announcement. Requiring a fairly new
646 % \LaTeX{} kernel is not absolutely necessary but it will help to
647 % ensure that we patch what we think we patch and in the future it
648 % means that will can be assured that the rollback functionality of
649 % the kernel is available in case will need to support several
650 % releases of the package.
651 % \begin{macrocode}
652 %<*package>
653 \NeedsTeXFormat{LaTeX2e}[2018-04-01]
654 % \end{macrocode}
655 %
656 % \begin{macrocode}
657 \ProvidesPackage{fewerfloatpages}
658 [\fewerfloatpagesdate\space \fewerfloatpagesversion\space
659 improve float page generation (FMi)]
660 % \end{macrocode}
661 %
662 % \subsection{Option handling}
663 %
664 % This release of the package has four options: \option{trace}
665 % for tracing the algorithm, \option{addbang} and
666 % \option{checktb} to handle cases where the float size in
667 % combination with the float specifiers makes it difficult if not
668 % impossible to place the floats, and \option{nocheck} to not make
669 % adjustments for that case.
670 %
671 % The option \option{trace} enables tracing of the algorithm and is
672 % implemented by giving the command \cs[no-index]{fl@trace} (which is also
673 % used by the \pkg{fltrace} package) a suitable definition.
674 %
675 % To handle the case that the \pkg{fltrace} package is loaded
676 % first, we use \cs[no-index]{providecommand}, so that its definition is not
677 % overwritten, but used if it is already available. If the package is
678 % loaded later everything works fine because it unconditionally
679 % defines \cs[no-index]{fl@trace}, i.e., overwrites whatever
680 % \pkg{fewerfloatpages} has defined.
681 %
682 % \begin{macrocode}
683 \DeclareOption{trace}
684 {\providecommand\fl@trace[1]%
685 {{\let\@elt\@empty\typeout{fewerfloatpages: #1}}}}
686 % \end{macrocode}
687 %
688 % The other three options are mutually exclusive so we number them 0
689 % to 2 in the command \cs[no-index]{fp@strategy} to ensure that
690 % only one is ever active. Option \option{nocheck} does nothing, with
691 % the cost that some floats may float to the end of the
692 % document. Option \option{addbang} adds a \texttt{!}\@ to floats
693 % that are sent back for reevaluation when a float page gets
694 % unraveled. Option \option{checktb} implements a different
695 % approach to handling problematic floats: the vertical
696 % size of a float is checked, and if it is too large to be allowed
697 % into the top or the bottom area, any \texttt{t} or \texttt{b}
698 % specifier is replaced by \texttt{p} (or dropped if \texttt{p} is
699 % already specified).
700 % \begin{macrocode}
701 \def\fp@strategy{0}%
702 \DeclareOption{nocheck}{\def\fp@strategy{0}} % better name?
703 \DeclareOption{addbang}{\def\fp@strategy{1}}
704 \DeclareOption{checktb}{\def\fp@strategy{2}}
705 % \end{macrocode}
706 % The actual implementation is done later. The default is
707 % currently \option{checktb} but this may change to
708 % \option{addbang} based on user feedback.
709 % \begin{macrocode}
710 \ExecuteOptions{checktb}
711 \ProcessOptions
712 % \end{macrocode}
713 %
714 %
715 % \subsection{Tracing code}
716 %
717 % \begin{macro}[internal]{\fl@trace}
718 % The command \cs[no-index]{fl@trace} is used to output tracing information.
719 % By default the tracing of the algorithm is turned off, so
720 % \cs[no-index]{fl@trace} will simply swallow its argument. But if
721 % \pkg{fltrace} is loaded or the option \option{trace} is given
722 % then the command already has a definition so we don't change it
723 % here.
724 % \begin{macrocode}
725 \providecommand\fl@trace[1]{}
726 % \end{macrocode}
727 % \end{macro}
728 %
729 %
730 % \subsection{User-level interfaces}
731 %
732 % For the most part the packages provides internal code that
733 % extends the float algorithm of \LaTeX{}. There are, however, also
734 % three new parameters that guide this algorithm; they are defined
735 % in this section.
736 %
737 % \begin{macro}[var]{\floatpagekeepfraction}
738 % The fraction that the algorithm uses to decide whether a given float
739 % page is so full that it would be pointless to unravel it for the
740 % reasons outlined above. The default is whatever fraction has been
741 % chosen as the minimum amount of text that needs to be on a normal
742 % page (i.e., \cs{textfraction}).
743 % \begin{macrocode}
744 \newcommand\floatpagekeepfraction{\textfraction}
745 % \end{macrocode}
746 % \end{macro}
747 %
748 %
749 % \begin{macro}[var]{floatpagedeferlimit,\c@floatpagedeferlimit}
750
751 % The algorithm will only consider unraveling float pages if there
752 % are not too many floats on the defer list. The definition of
753 % \enquote{too many} is provided through the counter
754 % \ctr{floatpagedeferlimit} if there are more floats waiting to be
755 % placed; float pages are generated until their number falls below
756 % this level. Thus, a value of \texttt{0} will disable the whole
757 % algorithm and a value of \texttt{1} means that only float pages
758 % with a single float might get unraveled and only if there aren't
759 % others still waiting to be placed.
760 % \begin{macrocode}
761 \newcounter{floatpagedeferlimit} \setcounter{floatpagedeferlimit}{3}
762 % \end{macrocode}
763 % \end{macro}
764
765
766
767 % \begin{macro}[var]{floatpagekeeplimit,\c@floatpagekeeplimit}
768 %
769 % A float page that contains at least this number of floats will
770 % also be kept. The default is \texttt{3} but if you have a lot of
771 % small floats it might be better to set this to a higher
772 % value.
773 % \begin{macrocode}
774 \newcounter{floatpagekeeplimit} \setcounter{floatpagekeeplimit}{3}
775 % \end{macrocode}
776 % \end{macro}
777
778
779
780
781
782 % \subsection{Patching the \LaTeX{} kernel commands}
783 %
784
785
786 %
787 % \begin{macro}[internal]{\@tryfcolumn}
788 % The main macro we have to patch to extend \LaTeX's algorithm is
789 % \cs{@tryfcolumn}. That command is changed when \pkg{fltrace}
790 % gets loaded, so we make our definition as late as possible to
791 % ensure that it will survive.
792 % \begin{macrocode}
793 \AtBeginDocument{%
794 % \end{macrocode}
795 %
796 % \begin{macrocode}
797 \def \@tryfcolumn #1{%
798 \global \@fcolmadefalse
799 \ifx #1\@empty
800 \else
801 \fl@trace{PAGE: trying to make a float
802 \if@twocolumn column/page\else page\fi}%
803 \fl@trace{----- \string #1: #1}%
804 \xdef\@trylist{#1}%
805 \global \let \@failedlist \@empty
806 \begingroup
807 \let \@elt \@xtryfc \@trylist
808 \endgroup
809 % \end{macrocode}
810 % Up to this point the definition is the same as in the original
811 % algorithm. At this point the switch \cs[no-index]{if@fcolmade} tells us if making a
812 % float page was successful and the original algorithm then called
813 % \cs[no-index]{@vtryfc} and removed the floats used for this float page from the defer list.
814 %
815 % In the extended algorithm this is the place where things start to
816 % differ as we may not want that float page to actually come into
817 % existence.
818 % \begin{macrocode}
819 \if@fcolmade
820 % \end{macrocode}
821 % As a first step we count the number of floats in the defer list
822 % and save the result in \cs{fp@candidates}.
823 % \begin{macrocode}
824 \fp@candidates\z@
825 \def\@elt##1{\advance\fp@candidates\@ne}%
826 #1%
827 \let\@elt\relax
828 % \end{macrocode}
829 % Now we compare this number with the values of the counter \ctr{floatpagedeferlimit}
830 % and if it is higher we definitely want to keep the float
831 % page. The rationale is that if we unravel now, then all floats from
832 % the defer list need to go into the top/bottom areas (or get
833 % deferred again but to a later page) and so a high number means the defer list will
834 % not get shortened very much and too many floats will get delayed further.
835 % \begin{macrocode}
836 \ifnum \fp@candidates >\c@floatpagedeferlimit
837 \fl@trace{----- too many deferred floats for unraveling
838 (\the\fp@candidates\space> \the\c@floatpagedeferlimit)}%
839 \else
840 % \end{macrocode}
841 %
842 % Otherwise we do a bit more testing. First we set \cs[no-index]{if@fcolmade}
843 % back to false; after all our goal is to not keep the float page. If
844 % during the tests we decide otherwise we set it back to true, which
845 % then signals that it should stay.
846 %
847 % We also count the floats on the float page, reusing \cs[no-index]{fp@candidates}
848 % for that, which is why we initialize it to zero.
849 % \begin{macrocode}
850 \global\@fcolmadefalse
851 \fp@candidates\z@
852 % \end{macrocode}
853 % The actual checking is done with
854 % \cs{fp@analyse@floats@for@unraveling} and it loops over
855 % \cs{@flsucceed}, i.e., the floats for that float page. This
856 % checks if any float for that page has only a \texttt{[p]}
857 % specifier and if so it sets \cs[no-index]{if@fcolmade} back to
858 % \texttt{true} and as a side effect it also does the counting for
859 % us. Furthermore, it also changes the switch to true if it finds
860 % at least \ctr{floatpagekeeplimit} floats on that page.
861 % \begin{macrocode}
862 \let\@elt\fp@analyse@floats@for@unraveling
863 \@flsucceed
864 \let\@elt\relax
865 % \end{macrocode}
866 % Now we recheck the state of the switch and if it still says
867 % \texttt{false}, all tests so far indicate that we don't want the float
868 % page.
869 % \begin{macrocode}
870 \if@fcolmade \else
871 % \end{macrocode}
872 % But we aren't done yet: the float page might be nicely filled,
873 % in which case it would be a shame to unravel it. During the above
874 % loop we also measured the free space on the float page and stored
875 % it in \cs{fp@unused@space} (see \cs{@xtryfc} below). We now
876 % compare that to the maximum free space that we consider to be
877 % still okay and if there is more we finally do the unraveling.
878 % \begin{macrocode}
879 \@tempdima\floatpagekeepfraction\@colht
880 \ifdim \fp@unused@space >\@tempdima
881 \fl@trace{----- current float page unraveled^^J%
882 \@spaces\@spaces\@spaces\space\space\space
883 (free space \fp@unused@space\space > \the\@tempdima)}%
884 % \end{macrocode}
885 % For this we basically return all floats back to the
886 % defer list. The switch is still \texttt{false} so it doesn't need
887 % changing.
888 % \begin{macrocode}
889 \xdef #1{\@failedlist\@flsucceed\@flfail}%
890 % \end{macrocode}
891 % However, we may also want to add a \texttt{!}\@ specifier to each of
892 % the floats (if the \option{addbang} option was given)
893 % so we loop over all the floats once more to get this
894 % done.\footnote{This could have been integrated with
895 % \cs{fp@analyse@floats@for@unraveling} but there is not much gain if
896 % any and by keeping it separate the processing logic seems clearer to me.}
897 % \begin{macrocode}
898 \let\@elt\fp@maybe@add@bang
899 \@flsucceed
900 \let\@elt\relax
901 \else
902 % \end{macrocode}
903 % But if we want to keep the float page after all, we have to set
904 % the switch back to \texttt{true} so that the rest of the
905 % algorithm proceeds correctly.
906 % \begin{macrocode}
907 \global \@fcolmadetrue
908 \fl@trace{----- current float page kept, full enough^^J%
909 \@spaces\@spaces\@spaces\space\space\space
910 (free space \fp@unused@space\space < \the\@tempdima)}%
911 \fi
912 \fi
913 \fi
914 % \end{macrocode}
915 % The next \cs[no-index]{else} matches the first \cs[no-index]{if@fcolmade}, i.e., the
916 % case that the algorithm wasn't able to make any float page. If
917 % we are tracing the algorithm, we want to tell the user about this.
918 % \begin{macrocode}
919 \else
920 \fl@trace{ --> fail: no float page made}%
921 \fi
922 % \end{macrocode}
923 %
924 % Finally, at this point we are back in the original algorithm. Now the
925 % switch tells the truth about whether or not we want to make a float
926 % page, and if so, we go ahead and produce it.
927 % \begin{macrocode}
928 \if@fcolmade
929 \@vtryfc #1%
930 \fi
931 \fi}%
932 }% -- END of \AtBeginDocument
933 % \end{macrocode}
934 % \end{macro}
935 %
936 % \pagebreak
937 %
938 %
939 % \begin{macro}[internal]{\@makefcolumn}
940 %
941 % In contrast to \cs{@tryfcolumn} this macro will always make float
942 % pages out of the deferred floats. It is used by \cs{clearpage}
943 % when we really need the floats to get out because there is no further
944 % text coming up. Thus, in that case we should not unravel the
945 % float pages. That would happen with the kernel definition of
946 % \cs{@makefcolumn} as that calls \cs{@tryfcolumn} which we just
947 % changed above. We therefore modify its definition to include the
948 % original code for \cs{@tryfcolumn} instead of calling our updated
949 % version.
950 %
951 % Again this change is made at \verb=\begin{document}= so that it
952 % is not overwritten in case \pkg{fltrace} is loaded afterwards.
953 % \begin{macrocode}
954 \AtBeginDocument{%
955 \def\@makefcolumn #1{%
956 \begingroup
957 \@fpmin -\maxdimen
958 \let \@testfp \@gobble
959 % \end{macrocode}
960 % At this point the original definition called \cs[no-index]{@tryfcolumn} and
961 % the lines above ensured that it was always succeeding in making
962 % a float page. However, since we have changed that command to do unraveling
963 % we had better not use it any more. Instead we replace it by its original
964 % definition (with the addition of two tracing lines).
965 % \begin{macrocode}
966 \global \@fcolmadefalse
967 \ifx #1\@empty
968 \else
969 \fl@trace{PAGE: trying to make a float
970 \if@twocolumn column/page\else page\fi}%
971 \fl@trace{----- \string #1: #1}%
972 \xdef\@trylist{#1}%
973 \global \let \@failedlist \@empty
974 \begingroup
975 \let \@elt \@xtryfc \@trylist
976 \endgroup
977 \if@fcolmade
978 \@vtryfc #1%
979 \fi
980 \fi
981 \endgroup
982 }%
983 }% -- END of \AtBeginDocument
984 % \end{macrocode}
985 % \end{macro}
986 %
987 %
988 %
989 %
990 % \begin{macro}[internal]{\@xtryfc}
991 % The only change to \cs{@xtryfc} is the addition of the
992 % \cs[no-index]{fl@trace} calls. But this extra tracing info is generally
993 % useful and should also be done in the \pkg{fltrace} package.
994 %
995 % The macro initiates a float page trial starting with the first
996 % float in \cs{@trylist}. More detailed explanations can be found
997 % in the documented sources of the \LaTeX{} kernel~\cite{source2e}.
998 % \begin{macrocode}
999 \def\@xtryfc #1{%
1000 \fl@trace{ starting with \string#1}%
1001 \@next\reserved@a\@trylist{}{}%
1002 \@currtype \count #1%
1003 \divide\@currtype\@xxxii
1004 \multiply\@currtype\@xxxii
1005 \@bitor \@currtype \@failedlist
1006 \@testfp #1%
1007 \@testwrongwidth #1%
1008 \ifdim \ht #1>\@colht
1009 \@testtrue
1010 \fi
1011 \if@test
1012 \@cons\@failedlist #1%
1013 \fl@trace{ --> fail}%
1014 \else
1015 \@ytryfc #1%
1016 \fi
1017 }%
1018 % \end{macrocode}
1019 % \end{macro}
1020 %
1021 %
1022 %
1023 %
1024 %
1025 %
1026 % \begin{macro}[internal]{\@ytryfc}
1027 %
1028 % The command \cs{@ytryfc}, which is also part of the code in the
1029 % kernel, loops through the defer list and tries to build a float
1030 % page starting with the float passed to it in |#1|. If it succeeds,
1031 % the floats that are part of the float page are listed in
1032 % \cs{@flsucceed} and the switch \cs[no-index]{if@fcolmade} is set to
1033 % \texttt{true}. Also of interest to us is that inside the code
1034 % \cs[no-index]{@tempdima} holds the size taken up by the floats, so we can
1035 % use this to calculate the unused space on the float page and
1036 % store it in \cs{fp@unused@space} for use in our extended
1037 % algorithm.
1038 % \begin{macrocode}
1039 \def\@ytryfc #1{%
1040 \begingroup
1041 \gdef\@flsucceed{\@elt #1}%
1042 \global\let\@flfail\@empty
1043 \@tempdima\ht #1%
1044 \let\@elt\@ztryfc
1045 \@trylist
1046 \ifdim \@tempdima >\@fpmin
1047 \global\@fcolmadetrue
1048 % \end{macrocode}
1049 % This branch is executed when the floats together are big enough
1050 % to form a float page. Thus, this is the right place to calculate
1051 % the free space by subtracting the used space from the column
1052 % height (which may not be the full height if there are spanning
1053 % floats in two column mode).
1054 % \begin{macrocode}
1055 \@tempdimb\@colht
1056 \advance\@tempdimb-\@tempdima
1057 \xdef\fp@unused@space{\the\@tempdimb}%
1058 % \end{macrocode}
1059 % The remaining code is again unchanged except that we added two
1060 % additional tracing lines (though those should be added to
1061 % the \pkg{fltrace} package too one of these days).
1062 % \begin{macrocode}
1063 \else
1064 \@cons\@failedlist #1%
1065 \fl@trace{ --> fail}%
1066 \fi
1067 \endgroup
1068 \if@fcolmade
1069 \let\@elt\@gobble
1070 \fl@trace{ --> success: \@flsucceed}%
1071 \fi}
1072 % \end{macrocode}
1073 % \end{macro}
1074 %
1075 %
1076 %
1077 %
1078 % \begin{macro}[internal]{\@largefloatcheck}
1079 %
1080 % The final kernel macro we need to patch is
1081 % \cs{@largefloatcheck}. This is called when a float box is
1082 % constructed and it checks if that box is larger than the available
1083 % \cs{textheight}, which would mean it could never be placed
1084 % anywhere, not even on a float page. The code therefore reduces
1085 % the box size as necessary and issues a warning.
1086 %
1087 % This macro is therefore a natural candidate to also check if the
1088 % float size is too large for the float to go into top or bottom
1089 % areas (if the option \option{checktb} is used).
1090 % \begin{macrocode}
1091 \def \@largefloatcheck{%
1092 \ifdim \ht\@currbox>\textheight
1093 \@tempdima -\textheight
1094 \advance \@tempdima \ht\@currbox
1095 \@latex@warning {Float too large for page by \the\@tempdima}%
1096 \ht\@currbox \textheight
1097 \fi
1098 % \end{macrocode}
1099 % The \cs{fp@maybe@check@tb} does the checking (or nothing if the
1100 % option is not given).
1101 % \begin{macrocode}
1102 \fp@maybe@check@tb
1103 }
1104 % \end{macrocode}
1105 % \end{macro}
1106 %
1107 %
1108 %
1109 %
1110 %
1111 % \subsection{Internal helper commands and parameters}
1112 %
1113 %
1114 % \begin{macro}[internal]{\fp@candidates}
1115 % We use an internal counter to count the number of floats in the
1116 % defer list and on a float page under construction.
1117 % \begin{macrocode}
1118 \newcount\fp@candidates
1119 % \end{macrocode}
1120 % \end{macro}
1121 %
1122 %
1123 %
1124 % \begin{macro}[internal]{\fp@unused@space}
1125 % In \cs{fp@unused@space} we store the amount of free space
1126 % on the current float page.
1127 % \begin{macrocode}
1128 \def\fp@unused@space{}
1129 % \end{macrocode}
1130 % \end{macro}
1131 %
1132 %
1133 %
1134 % \begin{macro}[internal]{\fp@analyse@floats@for@unraveling}
1135 % With \cs{fp@analyse@floats@for@unraveling} we loop over the
1136 % floats on the float page, i.e., |#1| will be one such float.
1137 %
1138 % One of its tasks is to count the floats (in \cs{fp@candidates}) and
1139 % check if
1140 % there are at least \ctr{floatpagekeeplimit} of them (which means
1141 % the float page should definitely be kept).
1142 %
1143 % Its most important task, however, is to check if one of the floats
1144 % has only a \texttt{p} specifier but no other. In that case it is
1145 % essential that we not unravel the float page because such a
1146 % float would then only go back onto the defer list as it has no
1147 % place to go except a float page.
1148 % \begin{macrocode}
1149 \def\fp@analyse@floats@for@unraveling#1{%
1150 \advance\fp@candidates\@ne
1151 \ifnum \fp@candidates <\c@floatpagekeeplimit
1152 % \end{macrocode}
1153 % So far we haven't got enough floats to know that this float page
1154 % should be kept so we check the given float specifiers.
1155 %
1156 % The test may look a little weird,\footnote{\enquote{Little} might
1157 % be an understatement. Encoding a lot of information in individual
1158 % bits of the counter value associated with a float was a great way
1159 % in the early days of \LaTeX{} to preserve macro space (and
1160 % absolutely essential back then), but these days \ldots{} Anyway,
1161 % it is the way it is and that part can't really be changed without
1162 % breaking a lot of packages.} but what we want to know is this:
1163 % is there a \texttt{p} (third bit) but neither a \texttt{b}
1164 % (second bit) nor a \texttt{t} (first bit). We don't care about
1165 % \texttt{h} or \texttt{!} which are the next two bits in the float
1166 % counter nor any of its higher bits (which encode the type of
1167 % float). So we divide the integer number by 8, which drops
1168 % the two least significant bits (think of the integer
1169 % represented in binary format), and then multiply it again by 8. As
1170 % a result the first two bits are zeroed out. We then compare the
1171 % result with the original value and if the two values are the same
1172 % then the \texttt{b} and \texttt{t} bits must both have been zero
1173 % from the start. And since the float was on a float page we also
1174 % know that it had a \texttt{p} specifier.
1175 % \begin{macrocode}
1176 \@tempcntb\count#1%
1177 \divide\@tempcntb 8\relax
1178 \multiply\@tempcntb 8\relax
1179 \ifnum \count#1=\@tempcntb
1180 % \end{macrocode}
1181 % In that case we set \cs[no-index]{if@fcolmade} to \texttt{true}
1182 % to signal that this float page should be kept, generate a tracing
1183 % message and change \cs[no-index]{@elt} to become
1184 % \cs[no-index]{@gobble} to quickly jump over any remaining floats
1185 % in the loop without doing further tests or generate further
1186 % tracing messages.
1187 % \begin{macrocode}
1188 \global \@fcolmadetrue
1189 \fl@trace{----- current float page kept, contains a float}%
1190 \fl@trace{\@spaces\space\space with p but no t or b specifier}%
1191 \let\@elt\@gobble
1192 \fi
1193 % \end{macrocode}
1194 % On the other hand, if we have seen enough floats we also know
1195 % that the float page should be kept, so change the switch, give
1196 % some tracing info and stop checking:
1197 % \begin{macrocode}
1198 \else
1199 \global \@fcolmadetrue
1200 \fl@trace{----- current float page kept
1201 (contains at least \the\fp@candidates\space floats)}%
1202 \let\@elt\@gobble
1203 \fi
1204 }
1205 % \end{macrocode}
1206 % \end{macro}
1207 %
1208 %
1209 %
1210 %
1211 % \begin{macro}[internal]{\fp@maybe@add@bang}
1212 %
1213 % The helper \cs{fp@maybe@add@bang} is used to loop through all of
1214 % the floats of a float page (receiving each as |#1| in turn) and
1215 % add a \texttt{!}\@ specifier if there wasn't one before.
1216 %
1217 % However, we only define it if we implement strategy 1 which is
1218 % option \option{addbang}.
1219 % \begin{macrocode}
1220 \ifnum\fp@strategy=1
1221 \def\fp@maybe@add@bang#1{%
1222 % \end{macrocode}
1223 % Find out if the fourth bit is set (which means no \texttt{!}\@)
1224 % and if so subtract 16 from the float counter which means setting
1225 % it to zero.
1226 % \begin{macrocode}
1227 \@boxfpsbit #1\sixt@@n
1228 \ifodd \@tempcnta
1229 \global\advance\count#1-\sixt@@n
1230 \fi
1231 }
1232 \else
1233 \let\fp@maybe@add@bang\@gobble
1234 \fi
1235 % \end{macrocode}
1236 % \end{macro}
1237 %
1238 %
1239 %
1240 %
1241 % \begin{macro}[internal]{\fp@maybe@check@tb}
1242 % The code in \cs{fp@maybe@check@tb} is used in
1243 % \cs{@largefloatcheck} to test if the float has a \texttt{t} or
1244 % \texttt{b} specifier but is too large to fit into the
1245 % respective area. This test is not made by default but only if the
1246 % option \option{checktb} is used, i.e., strategy~2.
1247 % \begin{macrocode}
1248 \ifnum\fp@strategy=2
1249 \def\fp@maybe@check@tb{%
1250 % \end{macrocode}
1251 % Again this is a case of
1252 % looking at various bits in the float counter value in binary
1253 % notation.
1254 % If the specifier contained a \texttt{!}\@ we are ok and it would
1255 % be wrong to change the specifier, because in
1256 % that case size restrictions for areas do not apply. For this we
1257 % have to test the fourth bit which means dividing by 16 and then
1258 % checking if the result is odd or even (odd means there was no
1259 % \texttt{!}\@).\footnote{I'm sure we had good reasons to
1260 % implement it this way in 1992\Dash we probably saved a few bytes
1261 % which was important back then. But it is certainly odd that for
1262 % \texttt{!}\@ a value of zero means that it was specified on the
1263 % float while for all other specifiers a value of \texttt{1}
1264 % indicates that the specifier was given.} The kernel
1265 % \cs{@getfpsbit} does this for us and stores the result in
1266 % \cs[no-index]{@tempcnta} so we can test this with \cs[no-index]{ifodd} to see if the
1267 % bit was set.
1268 % \begin{macrocode}
1269 \@getfpsbit \sixt@@n
1270 \ifodd \@tempcnta
1271 % \end{macrocode}
1272 % If there was no \texttt{!}\@ we check if the height of the
1273 % float is too large to fit into the top area.
1274 % \begin{macrocode}
1275 \ifdim \ht\@currbox>\topfraction\textheight
1276 % \end{macrocode}
1277 %
1278 % If that is the case we also check the first bit of the float
1279 % counter to see if a \texttt{t} was specified. For this we use
1280 % \cs{@getfpsbit} again but this time with \texttt{2} as the argument
1281 % since we test the first bit.
1282 % \begin{macrocode}
1283 \@getfpsbit \tw@
1284 \ifodd \@tempcnta
1285 % \end{macrocode}
1286 % If \texttt{t} was specified we need to remove it (next line) and
1287 % add (if not already present) a \texttt{p} instead. This is done
1288 % by \cs[no-index]{fp@add@p@bit}. Finally we add a warning for the user about
1289 % the change.
1290 % \begin{macrocode}
1291 \global\advance\count\@currbox -\tw@
1292 \fp@add@p@bit
1293 \@latex@warning {Float too large for top area: t changed to p}%
1294 \fi
1295 \fi
1296 % \end{macrocode}
1297 % A similar test and action is needed for bottom floats; here we
1298 % need to look at and zero out the second bit (i.e., using 4 as a value).
1299 % \begin{macrocode}
1300 \ifdim \ht\@currbox>\bottomfraction\textheight
1301 \@getfpsbit 4\relax
1302 \ifodd \@tempcnta
1303 \global\advance\count\@currbox -4\relax
1304 \fp@add@p@bit
1305 \@latex@warning {Float too large for bottom area:
1306 b changed to p}%
1307 \fi
1308 \fi
1309 \fi
1310 }
1311 % \end{macrocode}
1312 % In all other cases \cs{fp@maybe@check@tb} does nothing.
1313 % \begin{macrocode}
1314 \else \let\fp@maybe@check@tb\relax \fi
1315 % \end{macrocode}
1316 % \end{macro}
1317 %
1318 %
1319 %
1320 % \begin{macro}[internal]{\fp@add@p@bit}
1321 % The command \cs{fp@add@p@bit} adds the \texttt{p} specifier which
1322 % means checking the third bit and if not set, adding 8 to the float counter.
1323 % \begin{macrocode}
1324 \def\fp@add@p@bit{%
1325 \@getfpsbit 8\relax
1326 \ifodd \@tempcnta \else \global\advance\count\@currbox 8\relax \fi}
1327 % \end{macrocode}
1328 % \end{macro}
1329 %
1330 %
1331 % \ifx\thisissuepageref\undefined ^^A is this TUB production ??? if not gen index
1332 % \subsection{Patches that will eventually go into \pkg{fltrace}}
1333 %
1334 % The \pkg{fewerfloatpages} package added some additional general
1335 % tracing info into some of the kernel functions which isn't
1336 % currently available when using only the \pkg{fltrace} package. As
1337 % that tracing info is generally useful for understanding what the
1338 % base part of the float algorithm does, it should also be added to
1339 % the latter package.
1340 %
1341 % \fi
1342 %
1343 % \begin{macrocode}
1344 %<*package>
1345 % \end{macrocode}
1346 % \Finale
1347 %
1348
1349
1350 \endinput