Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2016 by Philippe Faist <[email protected]>
4 % -------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3 or later is part of all distributions of LaTeX
14 % version 2005/12/01 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{phffullpagefigure.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
23 %<package>\ProvidesPackage{phffullpagefigure}
24 %<*package>
25 [2016/08/15 v1.0 phffullpagefigure package]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{xcolor}
31 \usepackage{phffullpagefigure}
32 \usepackage[preset=xpkgdoc]{phfnote}
33 \EnableCrossrefs
34 \CodelineIndex
35 \RecordChanges
36 \begin{document}
37 \DocInput{phffullpagefigure.dtx}
38 \end{document}
39 %</driver>
40 % \fi
41 %
42 % \CheckSum{0}
43 %
44 % \CharacterTable
45 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
46 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
47 % Digits \0\1\2\3\4\5\6\7\8\9
48 % Exclamation \! Double quote \" Hash (number) \#
49 % Dollar \$ Percent \% Ampersand \&
50 % Acute accent \' Left paren \( Right paren \)
51 % Asterisk \* Plus \+ Comma \,
52 % Minus \- Point \. Solidus \/
53 % Colon \: Semicolon \; Less than \<
54 % Equals \= Greater than \> Question mark \?
55 % Commercial at \@ Left bracket \[ Backslash \\
56 % Right bracket \] Circumflex \^ Underscore \_
57 % Grave accent \` Left brace \{ Vertical bar \|
58 % Right brace \} Tilde \~}
59 %
60 %
61 % \changes{v1.0}{2016/04/20}{Initial version}
62 %
63 % \GetFileInfo{phffullpagefigure.dtx}
64 %
65 % \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef,\xdef,\if,\else,\fi,\ifx}
66 %
67 % \title{\phfqitltxPkgTitle{phffullpagefigure}}
68 % \author{Philippe Faist\quad\email{[email protected]}}
69 % \date{\pkgfmtdate\filedate}
70 % \maketitle
71 %
72 % \begin{abstract}
73 % \pkgname{phffullpagefigure}---Figures which fill up a full page of a document.
74 % \end{abstract}
75 %
76 % \inlinetoc
77 %
78 % \section{Introduction}
79 %
80 % The package \pkgname{phffullpagefigure} provides an implementation for figures which are
81 % to be displayed to occupy a full page.
82 %
83 % A typical use case: suppose you have a figure in PDF format of the size of the document
84 % paper, for example, and wants to include it as a figure.
85 %
86 % This package takes care to display the caption of the figure on the preceeding page,
87 % with a caption of the form ``Figure X (on facing page): \meta{caption}.''
88 %
89 % For two-sided documents, you may specify on which (odd/even) page side
90 % you want the figure to appear. If the document is not two-sided, the
91 % figure may appear on any page.
92 %
93 % A number of options allow you to set the exact figure contents (usually a
94 % PDF file, but it can be constructed from arbitrary \LaTeX{} commands),
95 % the figure caption placement (top, own page, bottom), the caption and
96 % label as usual, and the formatting of the caption if you want to replace
97 % the default ``(on facing page)'' or ``(on next page).''
98 %
99 %
100 % \section{The Full-Page-Figure Environment}
101 %
102 % \DescribeEnv{fullpagefigure} The |\begin{fullpagefigure}| |...|
103 % |\end{fullpagefigure}| environment starts a full-page-figure. Inside
104 % this environment, only the following commands may be used:
105 % \begin{itemize}
106 % \item one of the |\fig***| commands;
107 % \item the |\caption| command, to provide a figure caption as for regular
108 % figures;
109 % \item the |\label| command to set a label for text references to this
110 % figure, also as for regular figures.
111 % \end{itemize}
112 %
113 % A simple example to get started:
114 %
115 % \begin{verbatim}
116 % \begin{fullpagefigure}
117 % \figpdf{fig/my-figure} % my PDF file
118 % \caption{A colorful figure with letters and words. The table
119 % design may remind you of going to the optician.}
120 % \label{fig:test}
121 % \end{fullpagefigure}
122 % \end{verbatim}
123 %
124 % \begin{fullpagefigure}%
125 % \iffalse meta-comment
126 % In this documentation code, we cheat and provide LaTeX code for the
127 % figure instead of a PDF file. This is really just so that we don't
128 % have to ship an extra PDF file (and for no other reason).
129 %
130 % See a trick in http://tex.stackexchange.com/a/278101/32188 and
131 % http://tex.stackexchange.com/a/40503/32188 .
132 % \fi
133 % \figcontents{\newpage\thispagestyle{empty}\relax
134 % \newgeometry{margin=0.25in}\relax
135 % \sffamily\fontsize{36pt}{42pt}\fontseries{bx}\selectfont
136 % \hbox to 0.9\textwidth{\fcolorbox{red}{yellow}{\vbox to 0.99\textheight{\vfil\vfil\vfil\centering
137 % \leavevmode\noindent\hbox to 0.8\textwidth{ \color{red!50!black} T H I S }\par\vfil
138 % \vfil
139 % \leavevmode\noindent\hbox to 0.8\textwidth{ \color{green!70!red} F I G U R E }\par\vfil
140 % \vfil
141 % \leavevmode\noindent\hbox to 0.8\textwidth{ \color{black!40!blue} F I L L S }\par\vfil
142 % \vfil
143 % \leavevmode\noindent\hbox to 0.8\textwidth{ \color{green!40!blue} U P }\par\vfil
144 % \vfil
145 % \leavevmode\noindent\hbox to 0.8\textwidth{ \color{red!50!gray} T H E }\par\vfil
146 % \vfil
147 % \leavevmode\noindent\hbox to 0.8\textwidth{ \color{blue} W H O L E }\par\vfil
148 % \vfil
149 % \leavevmode\noindent\hbox to 0.8\textwidth{ \color{red!50!yellow} P A G E }\par\vfil
150 % \vfil\vfil\vfil}}}%
151 % \clearpage\aftergroup\restoregeometry}%
152 % \caption{A colorful figure with letters and words. The table design
153 % may remind you of going to the optician.}%
154 % \label{fig:test}%
155 % \end{fullpagefigure}
156 %
157 % The |\figpdf| command sets the PDF file to be displayed in full page (see
158 % more details below). You may contemplate the result of this code in
159 % \autoref{fig:test}.
160 %
161 % Some wizard once told me that old wise men had determined that the
162 % |fullpagefigure| environment should be placed at the beginning of a
163 % paragraph, or on its own paragraph. (TODO: I'm not too sure why this is
164 % the case or if this is still relevant.)
165 %
166 %
167 % The contents and appearance of the figure can be adjusted by the
168 % following commands, which must be issued within the |fullpagefigure|
169 % environment.
170 %
171 % \DescribeMacro{\figcontents} Specify the contents of the figure by calling
172 % |\figcontents|\marg{\LaTeX{} commands}. The contents can be any \LaTeX{}
173 % commands which will generate the figure content. These commands will be
174 % called within an |afterpage| block.\footnote{See documentation for the
175 % \pkgname{afterpage} package}
176 %
177 % If you want a figure to occupy several pages, you may use for example
178 % |\figcontents{\includepdf{pdf-1}\includepdf{pdf-2}}|, and request that
179 % the figure start on an even-side page with |\figpageside{even}|.
180 %
181 % If the \meta{\LaTeX{} commands} are not |\includepdf| instructions
182 % and want to change the page geometry for the figure and you're using
183 % the \pkgname{geometry} package, have a look at these \texttt{TeX.SX}
184 % answers\footnote{\url{http://tex.stackexchange.com/a/278101/32188}
185 % and \url{http://tex.stackexchange.com/a/40503/32188}} for getting
186 % the |\newgeometry| and
187 % |\restoregeometry| commands right. You might use, for example:\\[1ex]
188 % \noindent|\figcontents{\newpage\thispagestyle{empty}%|\\
189 % \hspace*{2em}|\newgeometry{margin=0.25in}% or 0in for no margins|\\
190 % \hspace*{2em}\meta{\ldots{} \LaTeX{} commands to draw figure contents ...}\\
191 % \hspace*{2em}|\clearpage\aftergroup\restoregeometry}|.
192 %
193 %
194 %
195 % \DescribeMacro{\figpdf} As a shorthand, you may use
196 % |\figpdf|\oarg{options}\marg{pdf-file} as a shorthand for
197 % |\figcontents{\includepdf|\oarg{options}\marg{pdf-file}|}|.
198 %
199 % You should explore the options provided by |\includepdf| (from the
200 % \pkgname{pdfpages} package\footnote{See documentation at
201 % \url{https://www.ctan.org/pkg/pdfpages}}). For example, the figure can
202 % be resized to fill the page, pages may be selected individually from a
203 % mult-page PDF, the image may be rotated, etc.
204 %
205 %
206 % \DescribeMacro{\caption} \DescribeMacro{\label} The |\caption|\oarg{short
207 % caption}\marg{caption} and |\label|\marg{identifier} macros may be used
208 % as for a normal figure. Be warned, though, that some dark manipulations
209 % occur here, so it may be for example that the code passed as argument to
210 % these commands is expanded only later.
211 %
212 % \DescribeMacro{\figpageside} Use the commands |\figpageside{odd}|,
213 % |\figpageside{}|, or |\figpageside{even}| to specify on which side the
214 % figure should appear on if the document is two-sided. This command has
215 % no effect if the document is not two-sided (|twoside| class option for
216 % the |article| or |book| classes, for example). Calling |\figpageside{}|,
217 % i.e.\@ with an empty argument, instructs |fullpagefigure| to use either
218 % side, whichever is more convenient.
219 %
220 % \DescribeMacro{\figplacement} Specify the figure caption placement with
221 % |\figplacement||{b|$\mid$|t|$\mid$|p}|. Each of |b| (bottom), |t| (top)
222 % and |p| (own page) work as for usual LaTeX floats. If you specify |p|,
223 % do NOT combine it with any other option. You may leave the argument
224 % empty (|\figplacement{}|) to use defaults.
225 %
226 % The figure placement can also be specified as an optional argument to the
227 % environment (e.g., |\begin{fullpagefigure}[p]| \ldots{} |\end{fullpagefigure}|).
228 %
229 % \DescribeMacro{\figcapmaxheight} Specify the maximum estimated height of
230 % the caption with |\figcapmaxheight|\marg{length}. This is used to see
231 % whether the figure caption still fits on the current page.
232 %
233 % TODO: This is ugly, the height of the caption should be calculated
234 % automatically\ldots{} for next time.
235 %
236 % By default (if no |\figcapmaxheight| is present), the figure will never
237 % be assumed to fit in the remainder of the page.
238 %
239 % \DescribeMacro{\fullpagefigurecaptionfmt}
240 % The figure label in the caption may be changed (e.g. ``Figure X (on facing page): \ldots'') by
241 % redefining the command |\fullpagefigurecaptionfmt|. See the default implementation for
242 % more info (\autoref{sec:impl}).
243 %
244 % \DescribeMacro{\FlushAllFullPageFigures} If you need to make sure that
245 % all full-page-figures have been placed up to a certain point, you may
246 % issue the command |\FlushAllFullPageFigures|. (You may wish to do so
247 % before starting a new chapter.) An optional argument
248 % |\FlushAllFullPageFigures[\clearpage]| or
249 % |\FlushAllFullPageFigures[\cleardoublepage]| specifies whether to
250 % continue on any page or on an odd-side page only.
251 %
252 %
253 %
254 % \section{Package Options}
255 %
256 % Only a single package option is recognized:
257 %
258 % \begin{verbatim} \usepackage[nopdfpages]{phffullpagefigure} \end{verbatim}
259 %
260 % If this package option is given, then the \pkgname{pdfpages} package
261 % is not loaded, and the command |\figpdf| is not made available. You
262 % may use this package option if the \pkgname{pdfpages} package
263 % conflicts with your setup.
264 %
265 %
266 %
267 %
268 %
269 %
270 %
271 %
272 % \StopEventually{\PrintChangesAndIndex}
273 %
274 % \section{Implementation}
275 % \label{sec:impl}
276 %
277 % Include some general useful packages first.
278 % \begin{macrocode}
279 \RequirePackage{etoolbox}
280 \RequirePackage{ifoddpage}
281 \RequirePackage{afterpage}
282 % \end{macrocode}
283 %
284 % The \pkgname{placeins} package provies the |\FloatBarrier| command,
285 % which we use to ensure that no other float gets in the way.
286 % \begin{macrocode}
287 \RequirePackage{placeins}
288 % \end{macrocode}
289 %
290 % \begin{macro}{phffpf@internal@pending}
291 % Counter which stores how many full-page-figures still haven't been
292 % placed. Used for |\FlushAllFullPageFigures| as well as making sure
293 % that the full-page-figures don't interfere with one another.
294 % \begin{macrocode}
295 \newcounter{phffpf@internal@pending}
296 \setcounter{phffpf@internal@pending}{0}
297 % \end{macrocode}
298 % \end{macro}
299 %
300 % \begin{macro}{\phffpfFloatBarrier}
301 % Redefine this if you don't want to use a |\FloatBarrier|. Be warned of
302 % the following points:
303 %
304 % \begin{itemize}
305 % \item |\FloatBarrier| introduces automatically a new paragraph.
306 % Nothing you can do about that a priori.
307 %
308 % \item If you remove |\FloatBarrier|, you need to either be sure that
309 % there are no floats which can mess up placement of the
310 % fullpagefigure. Alternatively, you need to provide your own
311 % mechanism that ensures that.
312 % \end{itemize}
313 %
314 % \begin{macrocode}
315 \def\phffpfFloatBarrier{\FloatBarrier}
316 % \end{macrocode}
317 % \end{macro}
318 %
319 %
320 % \subsection{The Main Environment Definition}
321 %
322 % \begin{environment}{fullpagefigure}
323 % The main |fullpagefigure| environment.
324 % \begin{macrocode}
325 \newenvironment{fullpagefigure}[1][b]{%
326 % \end{macrocode}
327 %
328 % Remember that we have a float pending to be placed:
329 % \begin{macrocode}
330 \addtocounter{phffpf@internal@pending}{1}%
331 % \end{macrocode}
332 %
333 % Don't allow any other floats to meddle with our calculations.
334 % \begin{macrocode}
335 \phffpfFloatBarrier%
336 %[YYY]% -- debugging [where is a space being inserted?]
337 % \end{macrocode}
338 %
339 % The following variables will store the relevant values of options
340 % collected in the definition of the figure with e.g. |\figplacement|,
341 % |\figcontents|, etc.
342 %
343 % NOTE TO SELF: If you add a |\phffpf@val@...| storage variable, don't
344 % forget to fix that value in |\phffpf@takecareofplacingfigure|.
345 %
346 % \begin{macrocode}
347 \xdef\phffpf@val@pageside{\phffpf@side@}%
348 \gdef\phffpf@val@captionopt{}%
349 \gdef\phffpf@val@caption{}%
350 \gdef\phffpf@val@label{}%
351 \gdef\phffpf@val@placement{#1}%
352 \gdef\phffpf@val@capmaxheight{\paperheight}%
353 \gdef\phffpf@val@figcontents{}%
354 % \end{macrocode}
355 %
356 % If this document is two-sided (facing odd/even pages), then by default
357 % place the float on an odd page. Otherwise, we don't care.
358 %
359 % \begin{macrocode}
360 \if@twoside%
361 \xdef\phffpf@val@pageside{\phffpf@side@odd}%
362 \else\fi%
363 % \end{macrocode}
364 %
365 % Provide a set of commands within this figure block which allow to specify
366 % the figure contents and appearance:
367 % \begin{macrocode}
368 \begingroup%
369 \let\figcontents\phffpf@impl@figcontents%
370 \let\figpageside\phffpf@impl@figpageside%
371 \let\caption\phffpf@impl@caption%
372 \let\label\phffpf@impl@label%
373 \let\figplacement\phffpf@impl@placement%
374 \let\figcapmaxheight\phffpf@impl@capmaxheight%
375 % \end{macrocode}
376 %
377 % Provide |\figpdf| as a shorthand, but only if applicable (i.e., the
378 % |nopdfpages| package option was not specified and the
379 % \pkgname{pdfpages} package was loaded):
380 % \begin{macrocode}
381 \phffpf@provide@figpdf%
382 % \end{macrocode}
383 %
384 % Finally, ignore any spaces following this command, as well as after the
385 % |\endenvironment| command.
386 % \begin{macrocode}
387 \ignorespacesafterend%
388 \ignorespaces%
389 }
390 % \end{macrocode}
391 %
392 % Now, the definitions for the end of the environment:
393 % \begin{macrocode}
394 {%
395 % \end{macrocode}
396 %
397 % Remove any spaces which might have been inserted.
398 % \begin{macrocode}
399 \ifhmode\unskip\fi%
400 % \end{macrocode}
401 %
402 % Restore |\caption|, |\label|, etc.\@ to their original meaning:
403 % \begin{macrocode}
404 \endgroup%
405 % \end{macrocode}
406 %
407 % Finally we should actually take care of placing the figure.
408 % \begin{macrocode}
409 \phffpf@takecareofplacingfigure%
410 % \end{macrocode}
411 %
412 % Finally finally, ignore any spaces following this command. Note that
413 % because the expansion of |\endfullpagefigure| is inside the definition of
414 % \LaTeX' ``|\end|'' and has internal commands after that, we can't just
415 % simply issue a |\ignorespaces|.
416 %
417 % \begin{macrocode}
418 \phfpf@useignorespacesandallpars%
419 }
420 % \end{macrocode}
421 % \end{environment}
422 %
423 % \begin{macro}{\phffpf@useignorespacesandallpars}
424 % Utility to ignore spaces and paragraphs after the
425 % |\end{fullpagefigure}| command.\footnote{This solution was adapted from
426 % \url{http://tex.stackexchange.com/a/179034/32188} and
427 % \url{http://tex.stackexchange.com/a/23101/32188}.}
428 % \begin{macrocode}
429 \def\phfpf@useignorespacesandallpars#1\ignorespaces\fi{%
430 #1\fi\phffpf@ignorespacesandallpars}
431 \def\phffpf@ignorespacesandallpars{%
432 \begingroup%
433 \catcode`\^^M=10\relax%
434 \catcode`\^^J=10\relax%
435 \@ifnextchar\par%
436 {\endgroup\expandafter\phffpf@ignorespacesandallpars\@gobble}%
437 {\endgroup}%
438 }
439 % \end{macrocode}
440 % \end{macro}
441 %
442 %
443 %
444 % \begin{macro}{\fullpagefigurecaptionfmt}
445 % \begin{macro}{\fullpagefigurecaptionfmt@paren@O}
446 % \begin{macro}{\fullpagefigurecaptionfmt@paren@E}
447 % \begin{macro}{\fullpagefigurecaptionfmt@paren@x}
448 % The macro |\fullpagefigurecaptionfmt| is called to generate the text
449 % which is prepended to the figure caption. It should essentially say
450 % ``Figure X (on next page): ''.
451 %
452 % The argument to |\fullpagefigurecaptionfmt| is |#1| = |O|, |E| or |x|
453 % for if the figure is on an odd page, an even page, or an unspecified
454 % page.
455 % \begin{macrocode}
456 \def\fullpagefigurecaptionfmt#1{%
457 \figurename\nobreakspace\thefigure\nobreakspace%
458 (\csname fullpagefigurecaptionfmt@paren@#1\endcsname)%
459 }
460 \def\fullpagefigurecaptionfmt@paren@O{on facing page} % for odd page figures
461 \def\fullpagefigurecaptionfmt@paren@E{on next page} % for even page figures
462 \def\fullpagefigurecaptionfmt@paren@x{on next page} % for next-page figures
463 % \end{macrocode}
464 % \end{macro}
465 % \end{macro}
466 % \end{macro}
467 % \end{macro}
468 %
469 %
470 %
471 % \subsection{Implementation of \phfverb{\fig}\phfverb{****} Commands}
472 %
473 % These macros really just store their values for later use.
474 %
475 % \begin{macro}{\figcontents}
476 % This macro will become |\figcontents| inside the |fullpagefigure|
477 % environment.
478 % \begin{macrocode}
479 \newtoks\phffpf@tmp@toks
480 \long\def\phffpf@impl@figcontents#1{%
481 \phffpf@tmp@toks={#1}%
482 \xdef\phffpf@val@figcontents{\the\phffpf@tmp@toks}%
483 \ignorespaces%
484 }
485 % \end{macrocode}
486 % \end{macro}
487 %
488 % \begin{macro}{\phffpf@side@odd}
489 % \begin{macro}{\phffpf@side@even}
490 % \begin{macro}{\phffpf@side@}
491 % These hold one-character codes to signify ``odd side,'' ``even side,''
492 % or ``no specification.''
493 %
494 % \begin{macrocode}
495 \def\phffpf@side@odd{O}
496 \def\phffpf@side@even{E}
497 \def\phffpf@side@{x}
498 % \end{macrocode}
499 % \end{macro}
500 % \end{macro}
501 % \end{macro}
502 %
503 % \begin{macro}{\figpageside}
504 % This will become |\figpageside| inside the |fullpagefigure|
505 % environment.
506 % \begin{macrocode}
507 \def\phffpf@impl@figpageside#1{%
508 \ifcsname phffpf@side@#1\endcsname%
509 \xdef\phffpf@val@pageside{\csname phffpf@side@#1\endcsname}%
510 \else%
511 \PacakgeError{phffullpagefigure}{Unknown page side designation:
512 '#1'. Please use 'odd', 'even', or '' for no preference.}%
513 \fi%
514 \ignorespaces%
515 }
516 % \end{macrocode}
517 % \end{macro}
518 %
519 % \begin{macro}{\caption}
520 % This will become |\caption| inside the |fullpagefigure| environment.
521 % \begin{macrocode}
522 \def\phffpf@NOARG{}
523 \def\phffpf@test@NOARG{\phffpf@NOARG}
524 \newcommand\phffpf@impl@caption[2][\phffpf@NOARG]{%
525 \gdef\phffpf@val@captionopt{#1}%
526 \gdef\phffpf@val@caption{#2}%
527 \ignorespaces%
528 }
529 % \end{macrocode}
530 % \end{macro}
531 %
532 % \begin{macro}{\label}
533 % This will become |\label| inside the |fullpagefigure| environment.
534 % \begin{macrocode}
535 \def\phffpf@impl@label#1{%
536 \gdef\phffpf@val@label{#1}%
537 \ignorespaces%
538 }
539 % \end{macrocode}
540 % \end{macro}
541 %
542 % \begin{macro}{\figplacement}
543 % This will become |\figplacement| inside the |fullpagefigure| environment.
544 % \begin{macrocode}
545 \def\phffpf@impl@placement#1{%
546 \gdef\phffpf@val@placement{#1}%
547 \ignorespaces%
548 }
549 % \end{macrocode}
550 % \end{macro}
551 %
552 % \begin{macro}{\figcapmaxheight}
553 % This will become |\figcapmaxheight| inside the |fullpagefigure|
554 % environment.
555 % \begin{macrocode}
556 \def\phffpf@impl@capmaxheight#1{%
557 \gdef\phffpf@val@capmaxheight{#1}%
558 \ignorespaces%
559 }
560 % \end{macrocode}
561 % \end{macro}
562 %
563 %
564 %
565 % \subsection{Placing the figures}
566 %
567 % Here's the gory details of how the figures are placed.
568 %
569 %
570 % \begin{macro}{\phffpf@place@pending@figs@code}
571 % This macro will store code to be executed after the next figure has
572 % been placed. This can be used to queue other figures to be placed
573 % later.
574 % \begin{macrocode}
575 \def\phffpf@place@pending@figs@code{\phffpf@place@pending@figs@code@start}
576 % \end{macrocode}
577 % \end{macro}
578 %
579 % \begin{macro}{\phffpf@place@pending@figs@code@start}
580 % When another figure is placed, and the
581 % |\phffpf@place@pending@figs@code| is updated, then the macro
582 % |\phffpf@place@pending@figs@code@start| contains the code which
583 % reinitializes |\phffpf@place@pending@figs@code|.
584 %
585 % This reinitialization code consists in precisely making sure that a
586 % future execution of |\phffpf@place@pending@igs@code@start| will start
587 % by reinitializing that macro.
588 % \begin{macrocode}
589 \def\phffpf@place@pending@figs@code@start{%
590 \gdef\phffpf@place@pending@figs@code{\phffpf@place@pending@figs@code@start}}
591 % \end{macrocode}
592 % \end{macro}
593 %
594 %
595 % \begin{macro}{\phffpf@impl@figcode}
596 % The code to be inserted to generate the figure.
597 %
598 % The argument |#1| is the prefix for macro names where to look up the
599 % contents of the figure and values of the figure settings. The macro
600 % names are determined as |\csname #1@|\meta{field-name}|\endcsname|.
601 % \begin{macrocode}
602 \gdef\phffpf@impl@figcode#1{%
603 % \end{macrocode}
604 %
605 % Do we have a figure placement position request (|p|, |t|, |b|)? If yes,
606 % then define a macro which we will expand in front of the |\begin{figure}|
607 % command for the caption. If no, then that macro should be left blank
608 % (first case below):
609 % \begin{macrocode}
610 \expandafter\ifblank\expandafter{\csname #1@placement\endcsname}{%
611 \edef\phffpf@tmp@figplacementarg{}%
612 }{%
613 \edef\phffpf@tmp@figplacementarg{[\csname #1@placement\endcsname]}%
614 }
615 % \end{macrocode}
616 %
617 % Invoke the |figure| environment, which we use to typeset the caption.
618 % Use specified placement if applicable. Set up some basic stuff in the
619 % figure: the contents, caption and label.
620 % \begin{macrocode}
621 \expandafter\figure\phffpf@tmp@figplacementarg%
622 \centering%
623 \begingroup%
624 \def\fnum@figure{\fullpagefigurecaptionfmt{\csname #1@pageside\endcsname}}%
625 \expandafter\afterpage\expandafter{\csname #1@figcontents\endcsname}%
626 \expandafter\ifx\csname #1@captionopt\endcsname\phffpf@test@NOARG%
627 \expandafter\caption\expandafter{\csname #1@caption\endcsname}%
628 \else%
629 \def\phffpf@tmp@captioncmdopt{%
630 \expandafter\caption\expandafter[\csname #1@captionopt\endcsname]}%
631 \expandafter\phffpf@tmp@captioncmdopt\expandafter{\csname #1@caption\endcsname}%
632 \fi%
633 \expandafter\notblank\expandafter{\csname #1@label\endcsname}{%
634 \expandafter\label\expandafter{\csname #1@label\endcsname}%
635 }{%
636 }
637 \endgroup%
638 \endfigure%
639 % \end{macrocode}
640 %
641 % Now we have placed the |figure|, so decrease our ``pending-to-be-placed''
642 % counter.
643 % \begin{macrocode}
644 \addtocounter{phffpf@internal@pending}{-1}%
645 % \end{macrocode}
646 %
647 % \ldots{} and execute the code to place any other pending figures. (We
648 % set |\ifphffpf@flag@forcenextmaybequeuetoplacefigure| to TRUE to force
649 % the next figure in queue to be placed now.)
650 % \begin{macrocode}
651 \afterpage{%
652 \phffpf@flag@forcenextmaybequeuetoplacefiguretrue%
653 \phffpf@place@pending@figs@code%
654 }%
655 }
656 % \end{macrocode}
657 % \end{macro}
658 %
659 %
660 % Now, all options have been set etc., the fullpagefigure environment has finished, so
661 % calculate the commands to place the figure appropriately.
662 %
663 %
664 % \begin{macro}{\phffpf@takecareofplacingfigure}
665 % First, fix the values of the contents and settings (in case another
666 % full-page-figure comes along and messes up the |\phffpf@val@...|
667 % commands).
668 %
669 % After the values have been fixed (in fact they are stored in the form
670 % of ``restore code''), then we delegate to
671 % |\phffpf@maybequeuefigurecode|, which checks whether we can place a
672 % figure or if we should queue.
673 % \begin{macrocode}
674 \def\phffpf@takecareofplacingfigure{%
675 % \end{macrocode}
676 %
677 % A tricky part: make sure we save the values of |phffpf@val@|\meta{field}
678 % in a fixed way so that several figures won't overwrite each other's
679 % values.
680 %
681 % We build a bunch of tokens which are in fact restore code for the given
682 % variables, i.e., which is a list of commands of the form
683 % |\gdef\phffpf@val@|\meta{field}|{|\meta{first-level-expanded-value-of-this-field}|}|.
684 % This set of tokens have the values of these variables expanded to the
685 % first level, so that it is OK if the variables |\phffpf@val@|\meta{field}
686 % are overwritten.
687 % \begin{macrocode}
688 \edef\phffpf@tmp@fixallfieldvalues{%
689 \noexpand\gdef\noexpand\phffpf@val@pageside{\expandonce\phffpf@val@pageside}%
690 \noexpand\gdef\noexpand\phffpf@val@captionopt{\expandonce\phffpf@val@captionopt}%
691 \noexpand\gdef\noexpand\phffpf@val@caption{\expandonce\phffpf@val@caption}%
692 \noexpand\gdef\noexpand\phffpf@val@label{\expandonce\phffpf@val@label}%
693 \noexpand\gdef\noexpand\phffpf@val@placement{\expandonce\phffpf@val@placement}%
694 \noexpand\gdef\noexpand\phffpf@val@capmaxheight{\expandonce\phffpf@val@capmaxheight}%
695 \noexpand\gdef\noexpand\phffpf@val@figcontents{\expandonce\phffpf@val@figcontents}%
696 }%
697 % \end{macrocode}
698 %
699 % Finally, relay the call to
700 % |\phffpf@maybequeuefigurecode|\marg{restore-code-for-figure-settings}\hspace{0pt}\marg{full-figure-code}.
701 % \begin{macrocode}
702 \edef\phffpf@tmp@figcodetwoargs{%
703 {\expandonce\phffpf@tmp@fixallfieldvalues}%
704 {\noexpand\phffpf@impl@figcode{phffpf@val}}%
705 }%
706 \expandafter\phffpf@maybequeuefigurecode\phffpf@tmp@figcodetwoargs%
707 }
708 % \end{macrocode}
709 % \end{macro}
710 %
711 % \begin{macro}{\phffpf@maybequeuefigurecode}
712 % USAGE: |\phffpf@maybequeuefigurecode|\marg{restore-code-for-figure-settings}\hspace{0pt}\marg{full-figure-code}.
713 %
714 % Checks if we can place the figure; if yes then place it on the right
715 % page, if no, then add it to the queue.
716 %
717 % The arguments are: |#1| = code to restore correct |\phffpf@val@XYZ|
718 % values; |#2| = figure code. Make sure it's expanded.
719 % \begin{macrocode}
720 \long\def\phffpf@maybequeuefigurecode#1#2{%
721 % \end{macrocode}
722 %
723 % Possibly we have been told to place the next figure now via the flag
724 % |\ifphffpf@flag@forcenextmaybequeuetoplacefigure|. In this case, reset
725 % the flag and place the figure now (relay to |\phffpf@doplacefigure|).
726 % \begin{macrocode}
727 \ifphffpf@flag@forcenextmaybequeuetoplacefigure%
728 \phffpf@flag@forcenextmaybequeuetoplacefigurefalse
729 \phffpf@doplacefigure{#1}{#2}%
730 %
731 \else
732 % \end{macrocode}
733 %
734 % See if there are other figures waiting to be placed first. If so, add
735 % ours to the queue.
736 % \begin{macrocode}
737 \ifnum\value{phffpf@internal@pending}>1\relax%
738 \xdef\phffpf@place@pending@figs@code{%
739 \expandonce\phffpf@place@pending@figs@code%
740 \unexpanded{\phffpf@maybequeuefigurecode{#1}{#2}}%
741 }%
742 %\show\phffpf@place@pending@figs@code
743 %[figure queued: \texttt{\detokenize{#1}}]% -- DEBUGGING
744 \else%
745 % \end{macrocode}
746 %
747 % If not, deal with placing the figure now:
748 % \begin{macrocode}
749 \phffpf@doplacefigure{#1}{#2}%
750 %[figure placed: \texttt{\detokenize{#1}}] -- DEBUGGING
751 \fi%
752 \fi%
753 }
754 % \end{macrocode}
755 %
756 % Define also the flag which will force a next call to
757 % |\phffpf@maybequeuefigurecode| to place the next figure in the queue.
758 % \begin{macrocode}
759 \newif\ifphffpf@flag@forcenextmaybequeuetoplacefigure
760 \phffpf@flag@forcenextmaybequeuetoplacefigurefalse
761 % \end{macrocode}
762 % \end{macro}
763 %
764 %
765 % \begin{macro}{\phffpf@doplacefigure}
766 % Place the figure now. Determine the correct number of |\afterpage|'s
767 % to use so that the figure caption ends up on the correct page side.
768 %
769 % The arguments to this macro are: |#1| = code to restore correct
770 % |phffpf@val@XYZ| values, |#2| = the figure code. Make sure it's
771 % expanded.
772 % \begin{macrocode}
773 \long\def\phffpf@doplacefigure#1#2{%
774 % \end{macrocode}
775 %
776 % Make sure the correct values of |phffpf@val@XYZ| are restored, because we
777 % need e.g. |\phffpf@val@pageside|. They may be wrong because this might
778 % be called after a figure has been queued.
779 % \begin{macrocode}
780 #1%
781 % \end{macrocode}
782 %
783 % Now, determine where exactly to place the figure code. There are no other pending
784 % figures. If there is no side preference, just place the figure pretty much now.
785 % \begin{macrocode}
786 \ifx\phffpf@val@pageside\phffpf@side@%
787 \let\phffpf@tmp@doplace\@firstofone%
788 \else%
789 % \end{macrocode}
790 %
791 % If, however, we have a side preference, then check everything more
792 % carefully. Use the helper macros
793 % |\phffpf@placecode@on|\meta{\phfverb{same}$\mid$\phfverb{other}}|parity|.
794 % (The latter essentially expand to the correct number of |\afterpage|'s.)
795 % \begin{macrocode}
796 \ifx\phffpf@val@pageside\phffpf@side@odd%
797 %[CHECK DONE HERE/WANT ODD] % -- for debugging
798 \checkoddpage\ifoddpage%
799 %[IS ODD] % -- for debugging
800 \let\phffpf@tmp@doplace\phffpf@placecode@onotherparity%
801 \else%
802 %[IS NOT ODD] % -- for debugging
803 \let\phffpf@tmp@doplace\phffpf@placecode@onsameparity%
804 \fi%
805 \else%
806 %[CHECK DONE HERE/WANT EVEN] % -- for debugging
807 \checkoddpage\ifoddpage%
808 %[IS ODD] % -- for debugging
809 \let\phffpf@tmp@doplace\phffpf@placecode@onsameparity%
810 \else%
811 %[IS NOT ODD] % -- for debugging
812 \let\phffpf@tmp@doplace\phffpf@placecode@onotherparity%
813 \fi%
814 \fi%
815 \fi%
816 % \end{macrocode}
817 %
818 % I think an |\hbox{}| might help to place the anchor which determines
819 % which page side we are currently on. Note that this starts a new
820 % paragraph and enters horizontal mode.
821 % \begin{macrocode}
822 \leavevmode\hbox{}%
823 % \end{macrocode}
824 %
825 % Now, do place the figure somewhere.
826 % \begin{macrocode}
827 \phffpf@tmp@doplace{#1#2}%
828 }
829 % \end{macrocode}
830 % \end{macro}
831 %
832 %
833 % \begin{macro}{\phffpf@placecode@onsameparity}
834 % Place the figure code on the same parity (page side) as we are
835 % currently. If enough space remains on the current page, place the
836 % figure immediately. Otherwise, use two |\afterpage|'s so as the figure
837 % caption to appear in two pages.
838 %
839 % \begin{macrocode}
840 \newdimen\phffpf@tmp@spaceleft
841 \newdimen\phffpf@tmp@compareto
842 \long\def\phffpf@placecode@onsameparity#1{%
843 % \end{macrocode}
844 %
845 % First, see if the caption itself requires to be on its own page (and thus
846 % no height calculations are necessary, and an additional |\clearpage| is
847 % required)
848 %
849 % \begin{macrocode}
850 \def\@tmpa{p}%
851 \ifx\phffpf@val@placement\@tmpa%
852 \afterpage{\vspace*{0pt}\afterpage{#1\clearpage}}%
853 \else%
854 % \end{macrocode}
855 %
856 % Otherwise, the figure caption is there along with some text on the page.
857 %
858 % See if there is enough place left on this page to place the figure
859 % caption; otherwise use two |\afterpage|'s.
860 % \begin{macrocode}
861 %[PLACING FIG CODE ON SAME PARITY]% -- debugging
862 \phffpf@tmp@spaceleft=\textheight\relax%
863 \phffpf@tmp@compareto=\phffpf@val@capmaxheight\relax%
864 \advance\phffpf@tmp@spaceleft by -\pagetotal%
865 %[DIM LEFT: \the\phffpf@tmp@spaceleft]%
866 \ifdim\phffpf@tmp@spaceleft>\phffpf@tmp@compareto%
867 %[ENOUGH DIM LEFT.] % -- debugging
868 #1%\phffpf@tmp@figcode%
869 \else%
870 %[*NOT ENOUGH* DIM LEFT.] % -- debugging
871 \afterpage{\vspace*{0pt}\afterpage{#1}}%
872 \fi%
873 \fi%
874 }
875 % \end{macrocode}
876 % \end{macro}
877 %
878 % \begin{macro}{\phffpf@placecode@onotherparity}
879 % Place the figure caption on the opposite parity as the current page.
880 % This just requires one |\afterpage| so as the figure code to appear on
881 % the following page.
882 %
883 % \begin{macrocode}
884 \def\phffpf@placecode@onotherparity#1{%
885 %[PLACING FIG CODE ON OTHER PARITY]% -- debugging
886 % \end{macrocode}
887 %
888 % First, see if the caption requires to be on its own page (and thus no
889 % height calculations are necessary, and an additional |\clearpage| is
890 % required).
891 % \begin{macrocode}
892 \def\@tmpa{p}%
893 \ifx\phffpf@val@placement\@tmpa%
894 \afterpage{#1\clearpage}%
895 \else%
896 % \end{macrocode}
897 %
898 % The figure caption is not on its own page. Just use a simple |\afterpage|.
899 % \begin{macrocode}
900 \afterpage{#1}%
901 \fi%
902 }
903 % \end{macrocode}
904 % \end{macro}
905 %
906 %
907 % \subsection{Commands to Flush All Full-Page-Figures}
908 %
909 %
910 % Here are a set of commands which can be used to ensure that all full-page
911 % figure floats have been placed.
912 %
913 % \begin{macro}{\FlushAllFullPageFigures}
914 % The name is pretty self-explanatory. The command is documented in the user doc above.
915 % \begin{macrocode}
916 \newcommand\FlushAllFullPageFigures[1][\phffpf@clearpage]{%
917 % \end{macrocode}
918 %
919 % As long as there are full-page-figures pending, clear pages until those
920 % figures have been placed.
921 % \begin{macrocode}
922 \ifnumcomp{\value{phffpf@internal@pending}}{>}{0}{%
923 \clearpage%
924 %[page cleared.]% DEBUG
925 \FlushAllFullPageFigures[#1]% recurse again.
926 }{%
927 % \end{macrocode}
928 %
929 % All figures placed, all fine. We still need to flush one last time
930 % because at this point the figure code (ie. caption) has been placed only,
931 % and we want the text that follows to come after the figure itself. Here
932 % finally we use the clear command in |#1| to continue on any page or on an
933 % odd-side page only.
934 % \begin{macrocode}
935 #1%
936 }%
937 }
938 \def\phffpf@clearpage{\if@twoside\cleardoublepage\else\clearpage\fi}
939 % \end{macrocode}
940 % \end{macro}
941 %
942 %
943 %
944 % \subsection{Package Option Parsing}
945 %
946 % Note the singular form of the word ``option.''
947 %
948 % \begin{macrocode}
949 \def\phffpf@provide@figpdf{}
950 \newcommand\phffpf@impl@figpdf[2][]{%
951 \figcontents{\includepdf[#1]{#2}}%
952 }
953 \def\phffpf@do@pdfpages{%
954 \RequirePackage{pdfpages}%
955 \def\phffpf@provide@figpdf{\let\figpdf\phffpf@impl@figpdf}%
956 }
957 %
958 \DeclareOption{nopdfpages}{\def\phffpf@do@pdfpages{}}
959 \DeclareOption*{%
960 \@unknownoptionerror%
961 }
962 \ProcessOptions\relax
963 %
964 \phffpf@do@pdfpages
965 % \end{macrocode}
966 %
967 %\Finale
968 \endinput