Welcome to the beta test of fltpage^{∗} package!

Sebastian Gross^{†}

beta 0.3 – 1998/11/13

Abstract This package defines the new environments FPfigure and FPtable, analogous to figure and table. In twoside mode the caption will be set on the opposite page of a figure/table which needs a whole page. In oneside mode the caption will be set on the preceding or following page.

1 Introduction

In some cases, there is just enough space to place a figure or table on a page, unfortunately there is no space left for the caption below or above. Moreover, it is might be impossible to decrease the size (for example, due to a fixed scale of a map) or the use of longtable is inappropriate. In these (rare) cases it seems acceptable to place the caption on the opposite page in twoside mode or on the preceding/following page in oneside mode. For this purpose the package fltpage provides the new environments FPfigure and FPtable in the sense of ‘generic markup’. The basic idea is to use two floats, which follow directly and contain the figure/table and the caption respectively. For correct positioning on odd or even pages in twoside mode at least two compilation runs are required.

2 Usage

To use this package just type in the preamble of your document

      \usepackage[⟨option⟩]{fltpage}.

The order of caption and figure/table are controlled one of the following options:

closeFloats the float using the whole page is placed on the next page. When the current page is even the caption is placed on the bottom, when it is odd the caption is placed at the bottom of the page after the float. In any case the caption appears on opposite page in twoside mode of document or the page before in oneside mode.

rightFloats, CaptionBefore the big float appears always on the right page and the caption afterwards. leftFloats, CaptionAfterwards the big float appears always on the left page

∗Sorry for the crippled name fltpage! I just did not have a better and compelling idea.

†e-mail: seppel@zedat.fu-berlin.de.

and the caption afterwards.

To distinguish the ‘isolated’ caption from the text a separator line: noSeparatorLine With this option the the separator will be suppressed

To clarify the connection of caption to the float on an other page it might be helpful to give a hint like ‘Fig. N (on the facing page):’. The following options control, how this is implemented: german So far only German is implemented as other language. varioref Reference texts are already implemented for many languages in the

standard package varioref, which implements slightly different expressions, too. With this option these texts will be used.

noHints When this option is used, any hint from the float caption to the float is disabled.

Moreover the following global options (probably declared with the document class) will be evaluated: draft causes placing of margin notes, where in the running text the one

of the new environments is inserted.

oneside, twoside just to decide mode of document…

FPfigure FPtable In your Document you simply use the new environments instead of the standard

environments table or figure with the usual \begin{} and \end{} commands:

      \begin{FPtable} ... \end{FPtable}
      \begin{FPfigure} ... \end{FPfigure}

Be sure that there are not more than one or two ‘small’ pending floats, otherwise the results will become unpredictable. Moreover you should not use more than one of the new environment on a page. The contents of the second will probably overwrite the contents of the first!

Example The following example will produce a caption below and an almost empty facing page:

      \usepackage[rightFloats]{fltpage}
      ...
      \begin{FPfigure}
       \caption{A caption alone ... figure without a caption!}
       \fbox{\rule[-10cm]{0pt}{\textheight}Frame ... page.\hspace{5cm}}
      \end{FPfigure}

2.1 Requirements

The present version of fltpage (v.0.3) has been developed and tested with L^{A}TEX 2ε of 1998/06/01 using emTEX 4b running TEX 3.14159 under Windows 3.1, using

Figure 1 (following page): A caption alone on a page will belong to the following figure without a caption!

2 USAGE 3 Frame symbolizing figure on a whole page. the article document class. It requires the standard L^{A}TEX package ifthen vers. 1.0n of 1997/11/02 and tools package afterpage vers. 1.08 of 1995/10/27. Maybe it will work with older versions, maybe not…

With the option varioref the tools package varioref is needed, as well.

2.2 Compatibility

This package was developed and tested with following versions of the other packages:

package version date
sidecap 1.00  1997/05/08
caption 1.4b  1995/04/05
booktabs 1.00  1995/11/06

Again it may work with older versions or not…

3 Known problems and limitations

This package is rather a quick and dirty solution to a problem than a sophisticated mechanism for placing captions and floats. It should be regarded as an experiment, rather than a utility. It was written by Sebastian Gross not only for it utility value, but as part of the process of learning LaTeX. Therefore it is far from being perfect, and comments are welcome. Your remarks and ideas are welcome to improve the concept and implementation in future releases.

Probably most problems will arose from pending floats, which should be cleared with \clearpage. So far, no attempt is done!

When unpredicted suites of caption and floats result, you must first assure two compilations of your document. An unresolved problem happens for example when the current page is even and the caption should be placed on the bottom of the page, but there is not enough space for it. It will be moved to the next page (odd) and the long float will be on next even page, which means caption and float are separated! To inquire this problem the option draft is provided, which causes the a margin note, where the FPfloat was inserted in the text.

The simple design employed does not allow any floats on the odd text page following the big float before the caption is resolved.

Also there is no solution implemented, when two of the new environments occur within a short interval. This is especially dangerous when they are called on one page: The contents of the second will overwrite the contents of the first!

In some cases the capacity of TEX might be exceeded (main memory). This happens for example, when the table itself is too big. It is assumed that tables included by files up to approximately 30 KB will fill one page, even with \tiny. Though, bigger tables may be included with the standard table environment…

This package does not work correctly with the showkeys package. Apparently the behaviour of the \isodd{} command of the standard ifthen package is disabled.

4 ACKNOWLEGMENTS 5

4 Acknowlegments

This package was partly based on the contributions to de.comp.text.tex, particulary of Hans Steffani, Heiko Oberdiek, Martin Schröder, Stefan Ulrich. I have to admit, the exploitation of Rolf Niepraschk’s sidecap package, especially how to write a documented style file.

5 The documentation driver file

The next bit of code contains the documentation driver file for TEX i. e., the file that will produce the documentation you are currently reading. It will be extracted from this file by the docstrip program.

1 ⟨∗driver⟩

 2 \documentclass{ltxdoc}
 3 \setlength\hfuzz{5pt}    % ignore small overfull boxes
 4 \GetFileInfo{fltpage.sty}
 5 %\CodelineIndex
 6 %\EnableCrossrefs    % Will prepare and index
 7 %\DisableCrossrefs   % Say \DisableCrossrefs if index is ready
 8 %\OnlyDescription    % comment out for implementation details
 9 %\RecordChanges      % Gather update information
10 \usepackage[rightFloats]{fltpage}
11 \MakeShortVerb{\|}
12 \begin{document}
13 \DocInput{fltpage.dtx}
14 \end{document}

15 ⟨/driver⟩

6 The implementation

6.1 File and Package Identification

16 ⟨∗package⟩

17 \NeedsTeXFormat{LaTeX2e}
18 \ProvidesPackage{fltpage}[1998/10/29 v.0.3 Floats on full page (SMU)]

6.2 Necessary files

19 \RequirePackage{ifthen}
20 \RequirePackage{afterpage}

6.3 Some internal variables and macros

FP@figureC FP@tableC Two counters to store the number of instantiations, used to create unique labels:

21 \newcounter{FP@figureC}
22 \newcounter{FP@tableC}

\FP@floatCorpusBOX To store the actual figure or table we will use a box:

23 \newsavebox{\FP@floatCorpusBOX}

6 THE IMPLEMENTATION 6

\FP@guide \FP@guideStyle \FP@guideOneside \FP@guideTwoside \FP@guideAfter \FP@guideBefore \FP@guideFaceBefore \FP@guideFaceAfter To clarify the connection of caption to the float on other page it might be helpful

to give a hint with the macro \FP@guide. The macro \FP@guideStyle contains the appropriate style options. The \FP@guideAfter, \FP@guideFaceAfter, and \FP@guideFaceAfter contain the the default text strings:

24 \newcommand*{\FP@guide}{}%
25 \newcommand*{\FP@guideStyle}{\slshape}
26 \newcommand*{\FP@guideOneside}{following page}
27 \newcommand*{\FP@guideTwoside}{facing page}
28 \newcommand*{\FP@guideAfter}{following page}
29 \newcommand*{\FP@guideBefore}{preceding page}
30 \newcommand*{\FP@guideFaceBefore}{preceding page}
31 \newcommand*{\FP@guideFaceAfter}{following page}

\FP@separatorCaption To distinguish the caption on the separate page better from the text, we define a separator:

32 \newcommand*{\FP@separatorCaption}{\rule{\linewidth}{.4pt}}

\FP@positionLabel To get information about the page we need some unique labels

33 \newcommand{\FP@positionLabel}{FP\@captype-\number\value{FP@\@captype C}-pos}

\FP@helpNote For debugging the following messages are displayed helping to identify the position

of an FPfigure resp. FPtable.
34 \newcommand{\FP@helpNote}[2]{%
35 \typeout{FP#1 is inserted on page \pageref{#2}!}}%

\FP@float \FP@floatOneside \FP@floatTwoside The Internal Macro \FP@float is the central output macro to perform the sequence of caption and float. Here it is preliminary defined as a dummy:

36 \newcommand{\FP@floatOneside}{}
37 \newcommand{\FP@floatTwoside}{}
38 \newcommand{\FP@float}{}

6.4 Declaration of options

german In other languages the text strings pointing to the page of the float must be declared in other languages. So far only German is implemented. When option varioref is later used, we must pass this option to varioref:

39 \DeclareOption{german}{%
40 \renewcommand{\FP@guideAfter}{n\"achste Seite}
41 \renewcommand{\FP@guideBefore}{vorhergehende Seite}
42 \renewcommand{\FP@guideOneside}{\FP@guideAfter}
43 \renewcommand{\FP@guideFaceBefore}{gegen\"uberliegende Seite}
44 \renewcommand{\FP@guideFaceAfter}{gegen\"uberliegende Seite}
45 \renewcommand{\FP@guideTwoside}{\FP@guideFaceAfter}
46 \PassOptionsToPackage{german}{varioref}
47 }%

varioref Reference texts are already implemented for many languages in the standard package varioref, which implements slightly different expressions. To ensure the inclusion of the package we use \RequirePackage{}, which can only placed after \ProcessOptions below. Therefore the code is delayed by \AtBeginDocument{}.

48 \DeclareOption{varioref}{%
49 \AtBeginDocument{%
50  \RequirePackage{varioref}
51  \ifthenelse{\equal{\reftextbefore}{\@empty}}%
52  {}{\renewcommand{\FP@guideBefore}{\reftextbefore}}%
53  \ifthenelse{\equal{\reftextafter}{\@empty}}%
54  {}{\renewcommand{\FP@guideAfter}{\reftextafter}}%
55  \renewcommand{\FP@guideOneside}{\FP@guideAfter}
56  \ifthenelse{\equal{\reftextfacebefore}{\@empty}}%
57  {}{\renewcommand{\FP@guideFaceBefore}{\reftextfacebefore}}%
58  \ifthenelse{\equal{\reftextfaceafter}{\@empty}}%
59  {}{\renewcommand{\FP@guideFaceAfter}{\reftextfaceafter}}%
60  \renewcommand{\FP@guideTwoside}{\FP@guideFaceAfter}%
61 }%
62 }%

The Options are implemented via \FP@float, which will now have three arguments: The first is the label of the current page to determine if it is odd or even. The second contains the float itself, i.e. the figure ore table. The third contains all the commands, to initialize counters etc.. The fourth is the caption part.

closeFloats
63 \DeclareOption{closeFloats}{%
64 \renewcommand{\FP@floatOneside}[3]{#3#2#1}%
65 \renewcommand{\FP@floatTwoside}[4]{%
66  \ifthenelse{\isodd{\pageref{#1}}}{#2#3#4}{#4#3#2}}%
67 }%
leftFloats
68 \DeclareOption{leftFloats}{%
69 \renewcommand{\FP@floatOneside}[3]{#1#2#3}%
70 \renewcommand{\FP@floatTwoside}[4]{%
71  \ifthenelse{\isodd{\pageref{#1}}}{{#2#3#4}}{\afterpage{#2#3#4}}}%
72 \renewcommand{\FP@guideOneside}{\FP@guideBefore}%
73 \renewcommand{\FP@guideTwoside}{\FP@guideFaceBefore}%
74 }%
rightFloats
75 \DeclareOption{rightFloats}{%
76 \renewcommand{\FP@floatOneside}[3]{#3#2#1}%
77 \renewcommand{\FP@floatTwoside}[4]{%
78  \ifthenelse{\isodd{\pageref{#1}}}{\afterpage{#4#3#2}}{{#4#3#2}}}%
79 \renewcommand{\FP@guideOneside}{\FP@guideAfter}%
80 \renewcommand{\FP@guideTwoside}{\FP@guideFaceAfter}%
81 }%

CaptionAfterwards CaptionBefore Some synonymous options
82 \DeclareOption{CaptionAfterwards}{\ExecuteOptions{leftFloats}}
83 \DeclareOption{CaptionBefore}{\ExecuteOptions{rightFloats}}%

draft With the following options, we process options packages etc:

84 \DeclareOption{draft}{%
85 \renewcommand{\FP@helpNote}[2]{%
86  \marginpar{Insertion of FP#1}%
87  \typeout{FP#1 is inserted on page \pageref{#2}!}}%
88 }%
oneside
89 \DeclareOption{oneside}{%
90 \renewcommand{\FP@guide}{\FP@guideStyle(\FP@guideOneside)}%
91 \renewcommand{\FP@float}[4]{\FP@floatOneside{#2}{#3}{#4}}
92 }%
twoside
93 \DeclareOption{twoside}{%
94 \renewcommand{\FP@guide}{\FP@guideStyle(\FP@guideTwoside)}%
95 \renewcommand{\FP@float}[4]{\FP@floatTwoside{#1}{#2}{#3}{#4}}
96 }%

noSeparatorLine He we implement some options to disable some of the functionality of the fltpage package: First the implementation of a separator line in \FP@separatorCaption is destroyed:

97 \DeclareOption{noSeparatorLine}{%
98 \renewcommand{\FP@separatorCaption}{}

99 }

noHints Secondly any hint in the caption towards the float is disabled. We must delay this, because the option varioref will be executed later, too. We assume that the order of delayed code is the same as in the declaration.

100 \DeclareOption{noHints}{%
101 \AtBeginDocument{\renewcommand{\FP@guide}{}}

102 }%

Unknown options will result in a warning. Perhaps they mean anything to varioref:

103 \DeclareOption*{%
104 \PackageWarning{fltpage}{Unknown option `\CurrentOption'!}%
105 \PassOptionsToPackage{\currentOption}{varioref}

106 }%

6.5 Excecution of options

Set the default behaviour:

107 \ExecuteOptions{closeFloats}
108 \ExecuteOptions{oneside}

Don’t forget to process the Options in the order of declaration:

109 \ProcessOptions*
110 \relax

6.6 New environments

6.6.1 Internal environment doing the magic

\FP@floatBegin The opening statement \FP@float has one argument which contains the strings ‘figure’ or ‘table’.

111 \newcommand{\FP@floatBegin}[1]{%

First we save the type of float for further processing to \@captype:

112 \gdef\@captype{#1}%
The caption, label and fnum@figure resp. fnum@table commands must be

saved to be used later in the local group:

113 \global\let\FP@savedCaptionCommand\caption%
114 \global\let\FP@savedLabelCommand\label%
115 \ifthenelse{\equal{\@captype}{figure}}
116  {\global\let\old@Fnum\fnum@figure}%
117  {\global\let\old@Fnum\fnum@table}%

Initialize some text variables…

118 \let\FP@LabelText\@empty%
119 \let\FP@CaptionText\@empty%
120 \let\FP@optionalCaptionText\@empty%

Now we redefine the label and caption commands:

121 \renewcommand\label[1]{\gdef\FP@LabelText{##1}}%
122 \renewcommand\caption[2][]{\gdef\FP@optionalCaptionText{##1}\gdef\FP@CaptionText{##2}}%

Finally we must start to record/save the contents of the float, i.e. figure or table etc., in a box.

123 \begin{lrbox}{\FP@floatCorpusBOX}%

124 }%

\FP@floatEnd The closing statement \FP@floatEnd terminates the collection of the float and causes the output of it and the caption. Since we use \afterpage, the local Box

\FP@floatCorpusBOX must assigned to the global \FP@floatCorpusBOX.
125 \newcommand{\FP@floatEnd}{%
126 \end{lrbox}%
127 \global\setbox\FP@floatCorpusBOX=\box\FP@floatCorpusBOX

Creates a label for each figure or table for later determination if the page is odd or even. The counters FP@figureC or FP@tableC must be incremented before.

128 \stepcounter{FP@\@captype C}%
129 \FP@savedLabelCommand{\FP@positionLabel}%

Here we give some hints to the user about the state of the environment…

130 \FP@helpNote{\@captype}{\FP@positionLabel}%

Now call the wanted sequence of caption and float according to the options above with the \FP@float macro. The first argument is the location label, which will be used to determine the current page.

131 \FP@float{\FP@positionLabel}% location label test

The second argument contains the float itself: First we open a float environment of type \@captype with option [p]. The float itself, i.e. figure or table, will be used the contents of the box \FP@floatCorpusBOX. Before placing the label, in order to get the actual page of the figure/table referenced later, rather than the one with the caption, we must increment the the counter of type \@captype.

132  {\begin{\@captype}[p!]
133  \usebox{\FP@floatCorpusBOX}%
134  \refstepcounter{\@captype}%
135  \ifthenelse{\equal{\FP@LabelText}{\@empty}}
136  {}{\FP@savedLabelCommand{\expandafter\protect\FP@LabelText}}%
137  \end{\@captype}}

The third argument is used to reset something changed in the first object. So far it is only the counter of type \@captype.

138  {\addtocounter{\@captype}{-1}}

The fourth argument contains the caption: Again we open a float environment of type \@captype with option [p]. To distinguish the caption from the text, it is separated with a horizontal line. Space above and below are adjusted accordingly. Than we will adjust \fnum@figure, when wanted. Finally the caption is given with or without optional argument.

139  {\begin{\@captype}[b!]%
140  \ifthenelse{\equal{\FP@guide}{\@empty}}%
141  {}{\ifthenelse{\equal{\@captype}{figure}}%
142  {\renewcommand{\fnum@figure}{\old@Fnum\ {\FP@guide}}}%
143  {\renewcommand{\fnum@table}{\old@Fnum\ {\FP@guide}}}}%
144  \setlength{\abovecaptionskip}{2pt plus2pt minus 1pt} % length above caption
145  \setlength{\belowcaptionskip}{2pt plus2pt minus 1pt} % length above caption
146  \FP@separatorCaption%
147  \ifthenelse{\equal{\FP@optionalCaptionText}{\@empty}}%
148  {\FP@savedCaptionCommand{\expandafter\protect\FP@CaptionText}}%
149  {\FP@savedCaptionCommand[\expandafter\protect\FP@optionalCaptionText]{\expandafter\protect\FP@CaptionText}}%
150  \end{\@captype}}%

151 }%

6 THE IMPLEMENTATION 11 6.6.2 The user interface with the new two environments

FPfigure FPtable Finally we implement the new environments, the user wants to use. They redirect to FP@floatBegin with the string ‘figure’ or ‘table’ and to FP@floatEnd.

152 \newenvironment{FPfigure}{\FP@floatBegin{figure}}{\FP@floatEnd}
153 \newenvironment{FPtable}{\FP@floatBegin{table}}{\FP@floatEnd}

154 ⟨/package⟩