TEX
v2.07 — 2022/01/10
© 2016–2022Brian Dunn [email protected]
Provides a key/value interface for generating floats.
Abstract
Thekeyfloatpackage provides a key/value user interface for quickly creating figures with a single image each, figures with arbitrary contents, tables, subfloats, rows of floats, floats located [H]ere, floats in the [M]argin, and floats with text [W]rapped around them.
Key/value combinations may specify a caption and label, a width proportional to\linewidth, a fixed width and/or height, rotation, scaling, a tight or loose frame, an\arraystretch, a continued float, additional supplemental text, and an artist/author’s name with automatic index entry. When used with thetocdata package, the name also appears in the List of Figures.
Floats may be moved into or rearranged inside a multi-row environment or subfloats, and are typeset to fit within the given number of columns, continuing to additional rows as necessary. Nested sub-rows may be used to generate layouts such as two small figures placed vertically next to one larger figure.
As an example, a typical command to include a figure with a framed image of half\linewidthcould be:
\keyfig*[hbp]{f,lw=.5,c={A caption},l={fig:label}}{image}
keyfloatuses thecaption,subcaption,newfloatorfloat, andwrapfigpack- ages, and cannot be used with thesubfig,subfigure,subfloat,floatrow, orfloatflt
! incompatible packages
packages.
See theGeneral Indexfor an index of topics and troubleshooting.
! Need help?
For the latest updates, seeUpdates.
What’s new?
License:
This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3 of this license or (at your option) any later version. The latest version of this license is in http://www.latex-project.org/lppl.txt and version 1.3 or later is part of all distributions of LaTeX version 2005/12/01 or later.
1 Introduction 6
1.1 A problem with floats . . . 6
1.2 Thekeyfloatpackage . . . 6
1.3 Features. . . 7
1.4 Updates . . . 8
1.5 Other float-related packages . . . 9
2 Using thekeyfloatpackage 10 2.1 Loadingkeyfloatand related packages . . . 10
2.2 Macros and environments. . . 11
2.3 Keys and values. . . 13
2.4 Other settings. . . 17
2.5 Examples . . . 18
2.5.1 Single floats. . . 18
2.5.2 Groups of floats, shared keys, keep aspect ratio . . . 29
2.5.3 Subfloats . . . 31
2.5.4 Continued floats . . . 33
2.5.5 Continued subfloats . . . 34
2.5.6 Margin floats . . . 35
2.5.7 Wrapped floats . . . 37
2.5.8 Custom frames . . . 42
2.5.9 Artist’s name . . . 44
2.6 Customization . . . 46
2.6.1 Custom frames . . . 46
2.6.2 Distance between floats and rows . . . 46
2.6.3 Formatting the captions . . . 47
3 Code 48 3.1 Older packages . . . 48
3.2 Prohibited packages . . . 48
3.3 Required packages . . . 49
3.4 In-line figures and tables . . . 50
3.5 Row counting and control . . . 51
3.6 Float key handling . . . 51
3.7 Nesting control . . . 59
3.8 Subfloat key handling . . . 59
2
3.11 A graphics image from a file . . . 66
3.12 Printing the caption . . . 69
3.13 Defaults for a new float . . . 73
3.14 Row start/end processing . . . 74
3.15 Key environment helper macros . . . 75
3.16 The\KFLT@keyfltmacro . . . 86
3.17 The\keyfltmacro . . . 86
3.18 Thekeyfloatenvironment . . . 87
3.19 Thekeyfigureenvironment . . . 89
3.20 The\keyfigmacro . . . 89
3.21 The\keyfigboxmacro . . . 90
3.22 The\keyparboxmacro . . . 91
3.23 The\keytabmacro . . . 92
3.24 Thekeytableenvironment . . . 92
3.25 A row of floats. . . 93
3.26 Subfloats . . . 99
3.27 Margin floats . . . 105
3.28 Wrapped floats . . . 107
4 keyfloatpackage maintenance 109
Change History 110 Index of Objects 112 General Index 117 Index of Indexes 119 List of Examples
1 Figure with an image from a file. . . 182 Figure with arbitrary contents. . . 18
3
5 Table environment with arbitrary contents . . . 20
6 Figure with many options selected . . . 21
7 Using\linewidth . . . 22
8 Using frames . . . 23
9 Using rotation with boxes . . . 24
10 Located [H]ere . . . 25
11 Unnumbered float . . . 26
12 Unnumbered float with a LOF entry. . . 26
13 An unnumbered in-text image . . . 27
14 A box without a caption. . . 28
15 Groups of figures —keyfloatsenvironment . . . 29
16 Subfigures —keysubfigsenvironment . . . 31
17 Subtables [H] —keysubtabsenvironment. . . 32
18 Continued figure . . . 33
19 Continued subfloats . . . 34
20 Themarginfigureenvironment . . . 35
21 Themargintableenvironment . . . 35
22 Using\keyfig[M] . . . 36
23 Usingkeytable[M]and an offset . . . 36
24 Using\keyfig[W]and\keytab[W] . . . 37
25 Using\keyfigbox[W]and\keyparbox[W] . . . 38
26 Using\keyfigure[W]and\keytable[W] . . . 39
27 Usingkeywrapwith a\keyfig . . . 40
28 Using wrap widthwwandwlw . . . 41
29 Custom frames withmdframed. . . 42
30 Custom shadows withfancybox . . . 43
31 Artist’s name — image . . . 44
32 Artist’s name — arbitrary contents . . . 44
33 Subfloats with an artist . . . 45
List of Figures
1 A\keyfigwith an image . . . 182 A\keyfigbox . . . 18
3 Akeyfigureenvironment . . . 19
4 A figure with options . . . 21
5 Half of\linewidth. . . 22
6 Loosely-framed figure . . . 23
7 Tightly-framed figure . . . 23
8 A keyfig [H] . . . 25
Starred short caption. . . 26
9 Next to a\keyparbox . . . 28
10 First in a group . . . 30
4
11 Third in a group . . . 30
12 Fourth in a group, with a longer caption . . . 30
13 Fifth in a group . . . 30
14 Sixth in a group. . . 30
15 Subfigures . . . 31
16 Figure to be continued. . . 33
16 . . . continued . . . 33
17 A set of figures . . . 34
17 . . . continued . . . 34
18 Amarginfigure . . . 35
19 A\keyfig[M] . . . 36
20 A\keyfig[W] . . . 37
21 A\keyfigbox[W] . . . 38
22 A\keyfigure[W] . . . 39
23 Keywrap with\keyfig . . . 40
24 A\keyfig[W] with wlw . . . 41
25 A\keyfig[W] with ww . . . 41
26 Custom-framed image . . . 42
27 Custom loosely-framed box . . . 42
28 Custom shadow . . . 43
29 Custom loosely-framed shadow. . . 43
30 Artist’s name — image . . . First Last 44 31 Artist’s name — arbitrary contents . . . Last 44 32 Artist’s collection . . . First Last 45
List of Tables
1 Keys and values — part I. . . 141 Keys and values — part II . . . 15
2 Caption-related key combinations . . . 16
3 Keywp: Wrapped float placement options . . . 16
4 A\keytabtable. . . 19
5 Akeytableenvironment . . . 20
6 Loosely-framed table . . . 23
7 Tightly-framed table . . . 23
8 Table, rotated . . . 24
9 A table [H] . . . 25
10 Seventh in a group . . . 30
11 Subtables [H] . . . 32
12 Amargintable . . . 35
13 Akeytable[M] . . . 36
14 A\keytab[W] . . . 37
15 Akeytable[W] . . . 39
1 Introduction
Thekeyfloatpackage simplifies the creation of LATEX floats, while still allowing a large number of useful features.
1.1 A problem with floats
When including a figure with a graphics image into a document, the user typically enters something such as:
\begin{figure}
\centering
\includegraphics[width=3in]{filename}
\caption{A Figure}
\label{fig:somelabel}
\end{figure}
When doing that often enough, it makes sense to factor the common code:
\onefigure[3in]{filename}{A Figure}{fig:somelabel}
Expanding the capability of\onefigureviaxparsecan lead to the general case of:
\onefigure*[loc](width){filename}(add'l text)[shortcap]{caption}*[label]
Attempting to add additional features such as frames and continued floats hits the limit of nine parameters for a TEX macro, requiring that new features use some kind of change-state macros instead. Attempting to support rows of floats or subfloats only makes things more complicated still.
A key/value system solves the problem of adding more features, does not require much additional typing, is a more self-documenting syntax, and allows a shared syntax with subfloats and groups of floats as well. Thus, thekeyfloatpackage.
1.2 The keyfloat package
Usingkeyfloat, the previous example becomes:
\keyfig{w=3in,c=A figure,l=fig:somelabel}{filename}
The\onefiguregeneral case becomes:
\keyfig*[loc]{w=width,t={add'l text},sc=shortcap,cstar=caption, l=label}{filename}
1.3 Features
The macros and environments provided bykeyfloatinclude:
\keyfig: A figure with an image.
\keytab: A table.
\keyflt: An arbitrary float type macro.
\keyfigbox: A figure with arbitrary contents.
\keyparbox: A “figure” without a caption, useful to place uncaptioned text inside a group,
keyfigure: A figure environment.
keytable: A table environment.
keyfloat: An arbitrary float type environment.
keyfloats: A group of rows and columns of floats.
keysubfigs: A figure containing a group of rows and columns of subfigures.
keysubtabs: A table containing a group of rows and columns of subtables.
keysubfloats: A float of arbitrary type containing a group of rows and columns of subfloats.
keywrap: Wraps a keyfloat around an environment of text. Usable inside a list.
marginfigure: A figure environment placed into the margin.1 margintable: A table environment placed in the margin.
Additional features include:
• Rows and columns of floats may be generated by placing them inside a keyfloatsenvironment.
• Subfloats may be generated by placing them inside akeysubfigsorkeysubtabs environment.
• Dynamic layout: The number of columns is specified. Extra floats are placed onto additional rows as needed, with the final row adjusted to compensate for leftovers.
1marginfigureandmargintable: The environments provided by thetufte-bookclass are used if loaded, otherwisekeyfloatprovides its own versions.
• Floats may be placed[H]ere.
• Floats may be placed in the[M]argin.
• Floats may be placed with text[W]rapped around them.
• Floats may be starred to span two columns.
• Continued floats may be used to repeat the previous float number.
• A figure may contain an image, with additional sizing, rotation, and a frame.
• Tables may be stretched. (\arraystretch)
• Boxes of arbitrary contents may be assigned a width and framed.
• Floats may be moved into and out of the grouping environments as needed.
• An artist/author’s name may be added to a figure and the index.
• If thetocdatapackage is loaded (use v0.12+), the name is also added to the LOF.
• Additional descriptive text may be added as well.
• Frames may be customized.
A large number of examples are provided, each showing LATEX source and the resulting examples
float.
A customized index is included at the back of the documentation, including trou- index
bleshooting issues.
Blue margin tags are used to help quickly find information, and often indicate the margin tags
destination of index entries.
Several warnings are noted in the text. Watch out for these special cases.
! warnings
1.4 Updates
Recent changes include the following:
v2.06: Added shared keys for groups of floats or subfloats. Added thekarkey to keep the aspect ratio of an image. Removed:for an empty caption. Warns if an image is too wide to fit.
v2.02, v2.04: Added keys for wrapped floats.
1.5 Other float-related packages
Several other LATEX packages related to floats include:
captionandsubcaption: Improved control over captions.
floatrow: A macro-based package for creating floats; including captions, footnotes, and rows of floats.
hvfloat: A key / value system allowing the easy rotation of captions and floats.
nccfloats: Macros for minipage floats and side-by-side floats.
newfloat: Macros for the creationg of float environments.
rotfloat: Environments for rotated floats.
subfig: Macros to add subfloats inside a float.
2 Using the keyfloat package
2.1 Loading keyfloat and related packages
keyfloatis loaded with the usual command:
\usepackage{keyfloat}
If you wish to have artists’ names appear in the list of figures, as provided by the
Pkg tocdata
Pkg tocloft
Pkg titletoc
tocdatapackage, loadtocdata, optionally followed by eithertocloftortitletoc, then keyfloat:
\usepackage{tocdata}
\usepackage{titletoc}% or titletoc, or neither
\usepackage{keyfloat}
To use custom float types with thefloatpackage:
Pkg float
\usepackage{float}
\newfloat{diagram}{htb}{lod}
To use custom float types with thenewfloatpackage:
Pkg newfloat
\usepackage{newfloat}
\DeclareFloatingEnvironment[
fileext={lod},
listname={List of Diagrams}, name={Diagram},
]{diagram}
For thecaptionpackage, to have table captions appear above the tables, and to use
Pkg caption
custom float types:
\usepackage[tableposition=top]{caption}
\captionsetup[diagram]{
style=default, justification=centering, margin=0pt, parskip=0pt, skip=1ex, labelfont={small,bf},textfont={small,bf}
}
To use custom float and subfloat types withcleveref:
Pkg cleveref
\usepackage{cleveref}
\crefname{diagram}{diagram}{diagrams}
\crefname{subdiagram}{subdiagram}{subdiagrams}
2.2 Macros and environments
*[⟨loc⟩] {⟨keys/values⟩} {⟨image filename⟩}
\keyfig
A macro to generate a figure with an image from a file.
*[⟨loc⟩] {⟨keys/values⟩} {⟨tabular contents⟩}
\keytab
A macro to generate a table with tabular contents. Usually use thekeytableenviron- ment instead.
*[⟨loc⟩] {⟨float type⟩} {⟨keys/values⟩} {⟨contents⟩}
\keyflt
A macro to generate an arbitrary float type with its contents.
*[⟨loc⟩] {⟨keys/values⟩} {⟨box contents⟩}
\keyfigbox
A macro to generate a figure with arbitrary paragraph contents. See example2.
*[⟨loc⟩] {⟨keys/values⟩} {⟨box contents⟩}
\keyparbox
A macro to generate a figure with arbitrary paragraph contents, but no number or cap- tion. This is equal to a\keyfigboxwithcstar={}. Mostly useful to add supplemental information inside a row of floats or subfloats. See example14.
*[⟨loc⟩] {⟨keys/values⟩}
Env keyfigure
An environment to generate a figure with arbitrary contents. Useful for multi- paragraph contents. See example3.
*[⟨loc⟩] {⟨keys/values⟩}
Env keytable
An environment to generate a table with arbitrary contents. Useful for larger tables.
See example5.
*[⟨loc⟩] {⟨float type⟩} {⟨keys/values⟩}
Env keyfloat
An environment to generate an arbitrary float type with its contents. Useful for multi- paragraph contents.
The above macros and environments may be used by themselves, or inside the followingkeyfloats,keysubfigs, orkeysubtabsenviron- ments.
*[⟨loc⟩] {⟨num columns⟩} [⟨shared keys/values⟩]
Env keyfloats
A group of figures or tables typeset in rows. May be nested, [H], [W], or [M]. The optional shared keys / values are passed to each object within. See example15.
*[⟨loc⟩] {⟨numcols⟩} {⟨keys⟩} [⟨shared keys/values⟩]
Env keysubfigs
A group of subfigures typeset in rows. Maynotbe nested. May be [H], [W], or [M]. The optional shared keys / values are passed to each object within. See example16.
*[⟨loc⟩] {⟨numcols⟩} {⟨keys⟩} [⟨shared keys/values⟩]
Env keysubtabs
A group of subtables typeset in rows. Maynotbe nested. May be [H], [W], or [M]. The optional shared keys / values are passed to each object within. See example17.
*[⟨loc⟩] {⟨float type⟩} {⟨numcols⟩} {⟨keys⟩} [⟨shared keys/values⟩]
Env keysubfloats
A group of subfloats typeset in rows. Maynotbe nested. May be [H], [W], or [M]. The optional shared keys / values are passed to each object within.
{⟨width of keyfloat⟩} {⟨keyfloat⟩}
Env keywrap
Displays a keyfloat next to an environment of text. Two minipages are used side- by-side, which allows its use inside a list item where [W] will not work, but extra empty vertical space will appear if the keyfloat and the text are of unequal vertical size.
! empty space
⟨keyfloat⟩may be any of\keyfig,keyfigure,keyfloats,keysubfigs, etc., each with its proper arguments. See example27.
[⟨offset⟩]
Env marginfigure
A figure placed into the margin, with an optional vertical offset.\keyfloatuses the version provided by thetufte-bookclass if available, or provides its own version otherwise. See example20.
[⟨offset⟩]
Env margintable
A table placed into the margin, with an optional vertical offset.\keyfloatuses the version provided by thetufte-bookclass if available, or provides its own version otherwise. See example21.
The star option create floats which span both columns in a two-column document.
Arg *
The[H]location forces a figure to be “Here”, in the form of a minipage instead of a
Arg [H]
float. A caption, label, etc. may still be assigned.
The[M]location places the float into the margin. When thetufte-bookclass is used,
Arg [M]
itsmarginfigureandmargintableenvironments are used, otherwisekeyfloatpro- vides and uses its own versions of the same environments. See examples22and23.
The[W]location wraps text around the float. Use this just before the start of a para-
Arg [W]
Pkg wrapfig graph with contents large enough to wrap around the float. Do not use this inside a list environment. Select placement with thewpkey; see thewrapfigpackage documenta- tion for more information. Useworlwto set the width of the item / image contained inside the wrap area. By default the caption will also be contained in this width. To use a larger width for the overall container and caption, setworlwfor the size of the image, and also usewworwlwfor a larger size for the caption. Watch the log for warnings from wrapfig.
! wrapfigwarnings
The star and [loc] options are ignored for floats inside akeyfloats,keysubfigs, or
Arg [loc]
keysubtabsenvironment. Note that these container environments may have their own star and [loc] options.
2.3 Keys and values
Table1shows the key/value combinations which are allowed. In most cases these may be used in any order and any combination, except for the following:
The keys labeled "Sub"may be used for thekeysubfigsandkeysubtabsenvironments, subfloat keys
which group a number of subfloats together under one master float. The master float has its own caption, label, and text, and each subfloat inside the group likewise has its own set of keys.
keyfloatsdoes not accept any keys at all.
keyfloats keys
The “artist” keysap,af,al, andasare only used by figures.
Thestretchkey increases space between tabular elements.
The rest of the macros and environments accept all of the keys, as they each create an individual float or subfloat, and each may have its own assigned dimensions and frame.
Table2shows the combinations of the caption-related keysc,cstar, andsc, and how short/long
caption combinations they control the caption numbering and entries in the LOF/LOT.
Table3shows the wrapped-float placement options for thewpkey for floats placed wrapped float placement
[W].
Table 1: Keys and values — part I
Key Suba Description Example
c
•
An unstarred caption. If empty, creates a figure with a number but no caption.c={A caption}
cstar
•
A starred caption. Creates a float without a number. If empty, creates a figure with no number or caption.cstar={No Num}
sc
•
The short caption for the LOF/LOT, even if cstar. sc={Short cap}cont
•
Continued float? contl
•
The label. Enclose in braces if a comma is included. Ignored in unnumbered floats.l=fig:alabel
ap, aup
•
Artist/author’s prefix, such as “Mr.”b ap=Mr.af, auf
•
Artist/author’s first name.b af=First al, aul•
Artist/author’s last name.b al=Last as, aus•
Artist/author’s suffix, such as~III.b al=~IIIt
•
Additional text. May include paragraphs.Enclose in braces if a comma is included. May need\protectbefore macro calls.
Fully-justified alignment.
t={Paragraphs}
tc
•
Additional text, aligned to the center. tc={Paragraphs}tl
•
Additional text, aligned to the left. tl={Paragraphs}tr
•
Additional text, aligned to the right. tr={Paragraphs}a:All the keys in Part I may be used with the main keys of thekeysubfigs,keysubtabs, and keysubfloatsenvironments.
b:Artist /author keys:alis an artist’s last name,aulis an author’s last name, etc. Artists names are printed centered, authors are flush right. A fixed-width non-breakable space is placed between parts of names, except that the optional suffix is connected directly to the last name, allowing “as={, Title}”, for example.
. . . continued
Table 1: Keys and values — part II
Key Subc Description Example
lw — Set the width to a fraction of\linewidth.
Cancelsw. If a non-image float, sets the width of the text box. For wrapped objects, may be used withwlwfor a smaller item with a larger caption.
lw=.5
w — Set the actual width. Cancelslw. If a non-image float, sets the width of the text box. For wrapped objects, may be used withwwfor a smaller item with a larger caption.
w=2in
h — Set the actual height. Images only. w=2in
kar — Keep aspect ratio: Use withworlw, along withh, to fit an image into a given area. Images only.
kar
s — Set the image scale. Images only. s=3
r — Set the rotation angle; counter-clockwise degrees.
r=90 f — Selects a loose frame with the current\fboxsep.
Only rotated with\keyfig. f
ft — Selects a tight frame with no\fboxsep. Useful for photographs, or diagrams which already have some margin built in.
ft
stretch — Sets\arraystretchinside the float. stretch=1.5
mo — Sets the vertical offset for a margin float. mo=-1.2ex
wn — Sets the number of lines for a wrapped float. wn=2
wp — Sets the wrap placement for a wrapped float.
The default isO, which places the wrapped float at the outside edge of the text. See table3.
wp=I
wo — Sets the wrap overhang for a wrapped float. wo=8em
wlw — Sets the total width of the wrapped item to a fraction of\linewidth. May be more than thew orlwwidth.
wlw=.6
ww — Sets the total width of the wrapped item. May be more than theworlwwidth.
ww=2in va — Sets the vertical alignment of the outermost
minipage container for the keyfloat. Defaults to
’c’. Ignored bysubfigure,subtable.
va=t
c:None of the keys in Part II are used in the main keys of thekeysubfigs,keysubtabs, or keysubfloatsenvironments, but may be used in the optional shared keys to be passed to each object within.
Table 2: Caption-related key combinations
Keys in Use Type of
c cstar sc Captiona LOF / LOTb
•
— — Numbered Caption•
—•
Numbered Short Caption—
•
— Unnumbered None—
• •
Unnumbered Short Caption— cstar={} Ignored None None
a:Caption: Shows whether the float will be numbered, unnum- bered, or have no caption.
b:LOF / LOT: Shows whether the regular or short caption will appear in the List of Figures or List of Tables, or if there will be no listing.
Table 3: Keywp: Wrapped float placement options
Key Location
r R to the right of the text body l L to the left of the text body i I to the inside margin o O to the outside margin
The un-capitalized key attempts to place the float “here”, and the capitalized key allows LATEX to try to find the best location. The default isO.
2.4 Other settings
{⟨contents⟩}Frames the contents without separation.
\KFLTtightframe
{⟨contents⟩}Frames the contents with separation.
\KFLTlooseframe
These may be used to re-define how contents are framed. The default is a simple
\fbox.
Combined width of the frame and separation for each of tight and loose frames. These
Len \KFLTtightframewidth
settings should be adjusted when changing the frame width and/or separation. The value should be equivalent to\fboxwidthplus\fboxsep.
Len \KFLTlooseframewidth
The computed width of the image. Useful to enclose an mdframed environment to
Len \KFLTimageboxwidth
restrict its width. See example29.
An image.
Figure 1: A\keyfigwith an image
Some text. More text.
Another paragraph.
Figure 2: A\keyfigbox
2.5 Examples
2.5.1 Single floats
Example 1: Figure with an image from a file
Code:
\keyfig{c=A \cs{keyfig} with an image,l=fig:simple}{image}
Result:
Figure1
This float (fig.1) is shown at its natural size because no width or height modifiers were natural size
specified. When used alone like this, a regular float is created.
Example 2: Figure with arbitrary contents
Code:
\keyfigbox{f,c={A \cs{keyfigbox}},l=fig:figbox}
{Some text. More text. \par Another paragraph.}
Result:
Figure2
The\keyfigboxcreates a figure with a box of arbitrary contents, instead of an image from a file. Its default width is the full\linewidth,unlessworlwkeys are used.
default width
Arbitrary contents may go here.
Including multiple paragraphs.
Figure 3: Akeyfigureenvironment
Table 4: A\keytabtable
A B
C D
Example 3: Figure environment with arbitrary contents
Code:
\begin{keyfigure}{f,c={A \env{keyfigure} environment}, l=fig:environment}
Arbitrary contents may go here.
Including multiple paragraphs.
\end{keyfigure}
Result:
Figure3
Thekeyfigureenvironment is preferred over the\keyfigboxmacro when multiple lines of contents are to be included.
Example 4: Table macro
Code:
\keytab{c=A \cs{keytab} table,l=tab:simpletable}{\testtable}
Result:
Table4
Do not try to use tables which overflow the page.
For anything other than a simple table, use thekeytableenvironment. See example5.
For large tables, use thelongtableorsupertabularpackages.
large tables
Table 5: Akeytableenvironment
Arbitrary contents may go here.a
A B
C D
aA footnote.
Example 5: Table environment with arbitrary contents
Code:
\begin{keytable}{f,c={A \env{keytable} environment}, l=tab:environment}
Arbitrary contents may go here.\footnote{A footnote.}
\testtable
\end{keytable}
Result:
Table5
Thekeytableenvironment is preferred over the\keytabmacro since most tables are multi-line creations.
\keytabcenters the table, butkeytabledoes not. Add\centeringif desired.
An image .
Additional text. Multiple paragraphs may be used. The entire text is enclosed in braces because a comma is included. Alignment may be set by using tagstc,tl, ortrinstead oft
Figure 4: A figure with many options
Example 6: Figure with many options selected
Code:
\keyfig{
w=2in,ft,r=15,
c=A figure with many options, sc=A figure with options,
t={Additional text. Multiple paragraphs may be used.
The entire text is enclosed in braces because a comma is included. Alignment may be set by using
tags \optn{tc}, \optn{tl}, or \optn{tr}
instead of \optn{t}}, l=fig:options
}{image}
Result:
Figure4
Width is fixed at 2 in, a tight frame is specified (\fboxsepof 0 pt), a short caption appears in the List of Figures, and the additional text is using the default fully-justified alignment.
Since fig.4is a float, it may appear on the following page.
An image.
Figure 5: Half of\linewidth
Example 7: Using\linewidth
Code:
\keyfig{lw=.5,c=Half of \cs{linewidth},l=fig:linewidth}{image}
Result:
Figure5
Figure5is half of\linewidthin size. When thelwkey is used inside akeyfloats
\linewidth
orkeysubfigsenvironment, the\linewidthwill be proportional to the sub-box for each element. When used alone, such as here, the\linewidthis the full width of the text on this page.
lwandware not used at the same time. If bothlwandware specified, the last one cancels any previous ones.
Example 8: Using frames
Code:
\begin{keyfloats}[hbp]{4}
\keyfig{f,c=Loosely-framed figure,l=fig:looseframe}{image}
\keyfig{ft,c=Tightly-framed figure,l=fig:tightframe}{image}
\keytab{f,c=Loosely-framed table,l=tab:looseframe}{\testtable}
\keytab{ft,c=Tightly-framed table,l=tab:tightframe}{\testtable}
\end{keyfloats}
Result:
Figures6and7and tables6and7 An image.
Figure 6:
Loosely-framed figure
An image.
Figure 7:
Tightly-framed figure
Table 6:
Loosely-framed table
A B
C D
Table 7:
Tightly-framed table
A B
C D
Thefkey adds a loose frame with the current\fboxsep. This is desirable in most cases.
Thetfkey adds a tight frame with no separation. This is useful for framing a photo- graph, or a diagram which already has a margin.
Framing tables is seldom recommended. In the case of the tight frame, table7, note that the external frame almost overwrites the table’s natural horizontal rules.
Also see section2.6.1for customizing frames.
custom frames
Table 8: Table, rotated
A B
C
D E
F
(Framed to show box width.)
Example 9: Using rotation with boxes
Code:
\keytab{f,w=.8in,c={Table, rotated}, r=70,l=tab:rotated,
tc=(Framed to show box width.)}
{\testwidetable}
Result:
Table8
Unless a width is given, a box is the full\linewidth. When rotated, this extra horizontal rotated whitespace
space is rotated into extra vertical space. To avoid this extra space, set aworlwto be wide enough for the table or other contents, but not much wider. When this box is
! box width
rotated, it will not take much more vertical space than necessary.
Unlike an image, the frame of a box does not rotate with its contents.
frame rotation
Example 10: Located [H]ere
Code:
\keytab[H]{c={A table [H]},l=tab:here}{\testtable}
\keyfig[H]{f,w=1in,c={A keyfig [H]},l=fig:here}{image}
Result:
Table9, Figure8
Table 9: A table [H]
A B
C D
An image.
Figure 8: A keyfig [H]
Table9and Figure8are to be placed “[H]ere”, and therefore may appear out-of-
! Out of sequence
sequence with surrounding figures. Place a\clearpagebefore or after to re-sync, if necessary.
An image.
Starred caption with a short caption.
Example 11: Unnumbered float
Code:
\keyfig[H]{f,cstar={A starred caption}}{image}
Result:
See fig: “A starred caption”.
An image.
A starred caption
A starred caption creates a float without a number, and without an entry in the List of Figures unless there is a non-empty short caption. (See the next example.)
Labels cannot be used when there is no number for a float.
! No label
Example 12: Unnumbered float with a LOF entry
Code:
\keyfig{
f,cstar={Starred caption with a short caption.}, sc={Starred short caption}
}{image}
Result:
See fig: “Starred caption with a short caption”.
A starred caption with a non-empty short caption creates an unnumbered entry in the List of Figures.
Example 13: An unnumbered in-text image
Code:
\keyfig[H]{f,cstar={},
tc={Optional text which is not a caption.}
}{image2}
Result:
See fig: “Optional text which is not a caption.”
Another image
Optional text which is not a caption.
By using [H] andcstar={}, the image is placed inline without a number or LOF entry.
Also see example14.
Some contents.
A\keyparboxwith no number or label.
An image.
Figure 9: Next to a\keyparbox
Example 14: A box without a caption.
Code:
\begin{keyfloats}{2}
\keyparbox{
f,lw=.5,
tc={A \cs{keyparbox} with no number or label.}
}{Some contents.}
\keyfig{c=Next to a \cs{keyparbox},l=fig:nexttoparbox}{image}
\end{keyfloats}
\keyparbox[H]{f,lw=.5}{A \cs{keyparbox} [H], outside the keyfloats.}
Result:
Figure9, and the box to its left.
A\keyparbox[H], outside the keyfloats.
A\keyparboxis a\keyfigboxwithcstar={}, and is mostly useful as an information box inside a row or a set of subfloats.
2.5.2 Groups of floats, shared keys, keep aspect ratio
Example 15: Groups of figures —keyfloatsenvironment
Code:
\begin{keyfloats}{2}
\keyfig{lw=1,c={First in a group},
l=fig:firstinrow,tl={\cs{raggedright} text}
}{image}
\keyparbox{}{\centering A \cs{keyparbox} describing something.
\par With several paragraphs.}
\begin{keyfloats}{2}[f,lw=1,h=3em,kar,va=t]
\keyfig{lw=1,c={Third in a group}, l=fig:thirdinarow}{image}
\keyfig{lw=1,c={Fourth in a group, with a longer caption}}{image2}
\keyfig{lw=1,c={Fifth in a group}}{image}
\keyfig{lw=1,c={Sixth in a group}, l=fig:sixthinarow}{image2}
\end{keyfloats}
\keytab{c={Seventh in a group},l=tab:seventhinrow}{\testwidetable}
\end{keyfloats}
Result:
Figure10to Table10
Thekeyfloatsenvironment takes an argument for the number of columns. Additional floats are automatically placed on following rows. Changing the number of columns automatic layout
will cause the floats to automatically readjust as necessary. Leftovers will be centered on the last row. An optional argument may contain keys and values which are passed shared keys
to each object inside the group.
Figure10to table10are in akeyfloatsenvironment. Furthermore, Figures11to14 nested groups
are in an additional nestedkeyfloatsenvironment, forming a small box of floats inside the larger group. In this subgroup, shared keys are set so that each image is framed and keeps its aspect ratio while being resized to fit a fixed width and height.
Note that\linewidthis adjusted for each row and nested row, so thelwkey may need
! \linewidth
to be changed if a float is moved to a different nesting level.
Fixed-width or fixed-height floats may be too large to fit if they are moved into a
! image too large
group. A warning is issued if so. It is the user’s responsibility to adjustw,h, orlwas necessary. To allow images to automatically adjust, uselw=1or less, which adjusts to the\linewidth.
Keyfloats may be located [H], [M], or located [W] set with half the line width:
location
An image.
\raggedrighttext
Figure 10: First in a group
A\keyparboxdescribing something.
With several paragraphs.
An image.
Figure 11: Third in a group
Another image
Figure 12: Fourth in a group, with a longer caption
An image.
Figure 13: Fifth in a group
Another image
Figure 14: Sixth in a group
Table 10: Seventh in a group
A B C
D E F
\begin{keyfloats}[H]{2}. . .
Keyfloats may be starred to span both columns in a two-column format:
two columns
\begin{keyfloats}*{2}. . .
As shown in the sub group above, to display a group of images of varying shape inside grid of images
a grid, use the shared option to select a maximum size, keep aspect ratio, and align at the top so that captions of varying length may wrap below each image:
\begin{keyfloats}{2}[lw=1,h=3em,kar,va=t]
...\end{keyfloats}
An image.
Some text
a: First subfigure
Ano ther imag e
Lots of lots of lots of lots of text.
b: Second subfigure
An image.
c: Third subfigure
A B
C D
d: Fourth subfigure
An image.
e: Fifth subfigure Figure 15: Subfigures
2.5.3 Subfloats
Example 16: Subfigures —keysubfigsenvironment
Code:
\begin{keysubfigs}{3}{c=Subfigures,l=fig:subfigs}
\keyfig{lw=1,f,c={First subfigure}, l=fig:firstsubfig,t=Some text}{image}
\keyfig{lw=1,f,r=90,c={Second subfigure}, l=fig:secondsubfig,
t=Lots of lots of lots of lots of text.}
{image2}
\begin{keyfloats}{1}
\keyfig{lw=1,f,c={Third subfigure},l=fig:thirdsubfig}{image}
\keytab{c={Fourth subfigure},l=fig:fourthsubfig}{\testtable}
\keyfig{lw=.5,f,c={Fifth subfigure},l=fig:fifthsubfig}{image}
\end{keyfloats}
\end{keysubfigs}
Result:
Figure15
Figures15ato15eare in the fig.15keysubfigsenvironment. Thekeysubtabsen- vironment is similar. Mixed types have the type of their container, as shown with fig.15d.
Subfloats are associated floats (a, b, . . . ) collected together into one common float (the enclosingkeysubfigsorkeysubtabsenvironment). The enclosing float can have its own caption (call “Sub-Figures” in the example), which appears in the LOF/LOT, and also a label. Each subfloat can have its own caption and label as well, but the subcaption does not appear in the LOF/LOT.
All subfloats are forced to have the same type as its containing float.A table inside
! mixed subfloats
a figure will be labeled as a figure, for example. This avoids miss-labeling as each subfloat must clearly be identified as a child of its containing float.
keysubfigsandkeysubtabsmay not be used insidethekeyfloatsenvironment, and
! nested subfloats
cannot be nested inside each other. (No subfloat12aa,12ab,12ba, etc.)
Thekeyfloatsenvironment may be used insidekeysubfigsorkeysubtabsto gather nested keyfloats
subfloats together, such as the three right-most figures in fig.15.
Subfloats may be located [H], [M], or located [W] set with half the line width:
location
\begin{keysubfigs}[H]{3}{key/vals . . .}
Subfloats may be starred to span both columns in a two-column format:
two columns
\begin{keysubfigs}*{2}{key/vals . . .}
A group of subfloats may have an optional argument for shared keys and values, which shared keys
are then passed to each subfloat within.
The vertical alignment optionvadoes not work with subfloats.
! va
Example 17: Subtables [H] —keysubtabsenvironment
Code:
\begin{keysubtabs}[H]{2}{c=Subtables [H],l=tab:subtabs}
\keytab{c={First subtable},l=fig:firstsubtab}{\testtable}
\keytab{c={Second subtable},l=fig:secondsubtab}{\testwidetable}
\end{keysubtabs}
Result:
Table11
Table 11: Subtables [H]
a: First subtable
A B
C D
b: Second subtable
A B C
D E F
An image.
Figure 16: Figure to be continued
Another image
Figure 16: ...continued
2.5.4 Continued floats
Thecontkey may be used to generate a “continued” float. The continued float receives the same number as the previous float, and it is assumed that they are the same float, except that they are separated for some reason such as size on the page.
The label may be placed in a continued float, and will still receive the same float number as the prior non-continued float.
Example 18: Continued figure
Code:
\begin{keyfloats}{2}
\keyfig{,c=Figure to be continued}{image}
\keyfig{c={\dots continued},cont,l=fig:firstcontinued}{image2}
\end{keyfloats}
Result:
Figure16
An image.
a: First of a set
An image.
b: Second of a set Figure 17: A set of figures
Another image c: Third of a set
Another image
d: Fourth of a set Figure 17: ...continued
2.5.5 Continued subfloats
Thekeysubfigsandkeysubtabsenvironments may also be given thecontkey. The containing environment’s float receives the same number as the previous float (pre- sumably another subfloat container).
Example 19: Continued subfloats
Code:
\begin{keysubfigs}{2}{c={A set of figures},l=fig:continuedfigures}
\keyfig{c={First of a set},l=fig:contfirst}{image}
\keyfig{c={Second of a set},l=fig:contsecond}{image}
\end{keysubfigs}
\begin{keysubfigs}{2}{c={\dots continued},cont}
\keyfig{c={Third of a set},l=fig:contthird}{image2}
\keyfig{c={Fourth of a set},l=fig:contfourth}{image2}
\end{keysubfigs}
Result:
Figure17
2.5.6 Margin floats
When a keyfloat is located [M], it will be placed in the margin.
When thetufte-bookclass is used, itsmarginfigureormargintableenvironments
Cls tufte-book
will be used, otherwisekeyfloatprovides environments of the same name and uses those instead.
Example 20: Themarginfigureenvironment
Code:
\begin{marginfigure}
\centering
\includegraphics[width=.75\linewidth]{image}
Some text added by hand.
\caption{A \env{marginfigure}}
\label{fig:marginfigure}
\end{marginfigure}
Result:
Figure18
An image.
Some text added by hand.
Figure 18: Amarginfigure
Example 21: Themargintableenvironment
Code:
\begin{margintable}
\centering
\testwidetable
\caption{A \env{margintable}}
\label{fig:margintable}
\end{margintable}
Result:
Table12
A B C
D E F
Table 12: Amargintable
Example 22: Using\keyfig[M]
Code:
\keyfig[M]{c={A \cs{keyfig}\optn{[M]}},l=fig:keyfigm,ft, t=Additional text.
Text text text text text text.
More paragraphs.
}{image2}
Result:
Figure19 Another
image
Additional text. Text text text text text text.
More paragraphs.
Figure 19: A\keyfig[M]
Example 23: Usingkeytable[M]and an offset
Code:
\begin{keytable}[M]{c={A \env{keytable}\optn{[M]}}, l=tab:keytablem,mo=-.9in}
\centering
\testwidetable
\end{keytable}
Result:
Table13 Table 13: Akeytable[M]
A B C
D E F
A negative offset was used to shift the table upwards to the top of the example.
margin float offset
To set the minimum-allowed distance between\marginpars and margin floats:
distance between floats
\setlength{\marginparpush}{3ex}
2.5.7 Wrapped floats
Example 24: Using\keyfig[W]and\keytab[W]
Code:
\keyfig[W]{c={A \cs{keyfig}\optn{[W]}},
l=fig:keyfigw,ft,lw=.4,wp=I, wo=8em, wn=12, t={.4\cs{linewidth} wide, placed \optn{I}.}
}{image2}
\blindtext
\keytab[W]{c={A \cs{keytab}\optn{[W]}},l=tab:keytabw,w=.75in, }{\testtable}
\blindtext
Result:
Figure20and table14
Another image
.4\linewidthwide, placedI.
Figure 20: A\keyfig[W]
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Etiam lobortis facilisis sem. Nullam nec mi et neque pharetra sollicitudin.
Praesent imperdiet mi nec ante. Donec ullamcorper, felis non so- dales commodo, lectus velit ultrices augue, a dignissim nibh lectus placerat pede. Vivamus nunc nunc, molestie ut, ultricies vel, sem- per in, velit. Ut porttitor. Praesent in sapien. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Duis fringilla tristique neque.
Sed interdum libero ut metus. Pellentesque placerat. Nam rutrum augue a leo. Morbi sed elit sit amet ante lobortis sollicitudin. Prae- sent blandit blandit mauris. Praesent lectus tellus, aliquet aliquam, luctus a, egestas a, turpis. Mauris lacinia lorem sit amet ipsum.
Nunc quis urna dictum turpis accumsan semper.
Table 14: A
\keytab[W]
A B
C D
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Etiam lobortis facilisis sem. Nullam nec mi et neque pharetra sollicitudin.
Praesent imperdiet mi nec ante. Donec ullamcorper, felis non so- dales commodo, lectus velit ultrices augue, a dignissim nibh lectus placerat pede. Vivamus nunc nunc, molestie ut, ultricies vel, semper in, velit. Ut porttitor. Praesent in sapien. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Duis fringilla tristique neque. Sed inter-
dum libero ut metus. Pellentesque placerat. Nam rutrum augue a leo. Morbi sed elit sit amet ante lobortis sollicitudin. Praesent blandit blandit mauris. Praesent lectus tellus, aliquet aliquam, luctus a, egestas a, turpis. Mauris lacinia lorem sit amet ipsum.
Nunc quis urna dictum turpis accumsan semper.
Example 25: Using\keyfigbox[W]and\keyparbox[W]
Code:
\keyfigbox[W]{c={A \cs{keyfigbox}\optn{[W]}}, l=fig:keyfigboxw,f,lw=.25,wp=I, wn=7,
t=Text text text text text text text text text }{The contents.}
\blindtext
\keyparbox[W]{w=1in}{A \cs{keyparbox}[W] and some more text.}
\blindtext
Result:
Figure21and the\keyparbox.
The contents.
Text text text text text text text text text
Figure 21: A
\keyfigbox[W]
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Etiam lobortis facilisis sem. Nullam nec mi et neque pharetra sollicitudin. Praesent imperdiet mi nec ante. Donec ullam- corper, felis non sodales commodo, lectus velit ultrices augue, a dignissim nibh lectus placerat pede. Vivamus nunc nunc, molestie ut, ultricies vel, semper in, velit. Ut porttitor. Prae- sent in sapien. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Duis fringilla tristique neque. Sed interdum libero ut metus. Pel- lentesque placerat. Nam rutrum augue a leo. Morbi sed elit sit amet ante lobortis sollicitudin. Praesent blandit blandit mauris. Praesent lectus tellus, aliquet aliquam, luctus a, egestas a, turpis. Mauris lacinia lorem sit amet ipsum. Nunc quis urna dictum turpis accumsan semper.
\keyparbox[W]A and some more text.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Etiam lobortis facilisis sem. Nullam nec mi et neque pharetra sollic- itudin. Praesent imperdiet mi nec ante. Donec ullamcorper, felis non sodales commodo, lectus velit ultrices augue, a dignis- sim nibh lectus placerat pede. Vivamus nunc nunc, molestie ut, ultricies vel, semper in, velit. Ut porttitor. Praesent in sapien.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Duis fringilla tristique neque.
Sed interdum libero ut metus. Pellentesque placerat. Nam rutrum augue a leo. Morbi sed elit sit amet ante lobortis sollicitudin. Praesent blandit blandit mauris. Praesent lectus tellus, aliquet aliquam, luctus a, egestas a, turpis. Mauris lacinia lorem sit amet ipsum. Nunc quis urna dictum turpis accumsan semper.
Example 26: Using\keyfigure[W]and\keytable[W]
Code:
\begin{keyfigure}[W]{c={A \cs{keyfigure}\optn{[W]}}, l=fig:keyfigurew,f,w=1.5in, wo=4em,wn=5}
This is a keyfigure.
\end{keyfigure}
\blindtext
\begin{keytable}[W]{c={A \env{keytable}\optn{[W]}}, l=tab:keytablew,w=2in,wp=L,
tc=Placed \optn{L} and 2in wide.}
\centering
\testwidetable
\end{keytable}
\blindtext
Result:
Figure22and table15
This is a keyfigure.
Figure 22: A\keyfigure[W]
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Etiam lobortis facilisis sem. Nullam nec mi et neque pharetra sollici- tudin. Praesent imperdiet mi nec ante. Donec ullamcorper, felis non sodales commodo, lectus velit ultrices augue, a dignissim nibh lectus placerat pede. Vivamus nunc nunc, molestie ut, ul-
tricies vel, semper in, velit. Ut porttitor. Praesent in sapien. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Duis fringilla tristique neque. Sed interdum libero ut metus. Pellentesque placerat. Nam rutrum augue a leo. Morbi sed elit sit amet ante lobortis sollicitudin. Praesent blandit blandit mauris. Praesent lectus tellus, aliquet aliquam, luctus a, egestas a, turpis. Mauris lacinia lorem sit amet ipsum. Nunc quis urna dictum turpis accumsan semper.
Table 15: Akeytable[W]
A B C
D E F
PlacedLand 2in wide.
Lorem ipsum dolor sit amet, consectetuer adip- iscing elit. Etiam lobortis facilisis sem. Nullam nec mi et neque pharetra sollicitudin. Praesent imperdiet mi nec ante. Donec ullamcorper, fe- lis non sodales commodo, lectus velit ultrices augue, a dignissim nibh lectus placerat pede.
Vivamus nunc nunc, molestie ut, ultricies vel, semper in, velit. Ut porttitor. Praesent in sapien. Lorem ipsum dolor sit amet, con- sectetuer adipiscing elit. Duis fringilla tristique neque. Sed interdum libero ut metus.
Pellentesque placerat. Nam rutrum augue a leo. Morbi sed elit sit amet ante lobortis sollicitudin. Praesent blandit blandit mauris. Praesent lectus tellus, aliquet aliquam, luctus a, egestas a, turpis. Mauris lacinia lorem sit amet ipsum. Nunc quis urna dictum turpis accumsan semper.
Example 27: Usingkeywrapwith a\keyfig
Code:
\begin{itemize}
\item First item.
Several lines of text text text text text text text text text text text text text.
\item \begin{keywrap}{.3\linewidth}{\keyfig{%
lw=1,c={Keywrap with \cs{keyfig}},l=fig:keywrapfig%
}{image}}
Second item.
These paragraphs are inside the \texttt{keywrap}.
A vertical gap appears below if the text is not enough to fill the space next to the \cs{keyfig}.
\end{keywrap}
Now outside the \env{keywrap},\margintag{notes}\
but still in the second item.
There is no elegant way to place only part of a paragraph inside a \env{keywrap}.
\item Third item.
\end{itemize}
Result:
Figure23
• First item. Several lines of text text text text text text text text text text text text text.
• Second item.
These paragraphs are inside thekeywrap. A vertical gap appears below if the text is not enough to fill the space next to the\keyfig.
An image.
Figure 23: Keywrap with
\keyfig
Now outside thekeywrap, but still in the second item. There is no elegant way notes
to place only part of a paragraph inside akeywrap.
• Third item.
Example 28: Using wrap widthwwandwlw
Code:
\keyfig[W]{c={A \cs{keyfig}\optn{[W] with \optn{wlw}}}, l=fig:keyfigwlw,ft,lw=.15,wlw=.4,wp=I,
t={.15\cs{linewidth} wide, in a .4\cs{linewidth} box.}
}{image2}
\blindtext[1]
\keyfig[W]{c={A \cs{keyfig}\optn{[W] with \optn{ww}}}, l=fig:keyfigww,ft,w=1cm,ww=3cm,wp=I,
t={1cm wide, in a 3cm box.}
}{image2}
\blindtext[1]
Result:
Figures24and25
Another image
.15\linewidthwide, in a .4\linewidthbox.
Figure 24: A\keyfig[W] with wlw
Lorem ipsum dolor sit amet, consectetuer adip- iscing elit. Etiam lobortis facilisis sem. Nullam nec mi et neque pharetra sollicitudin. Praesent imperdiet mi nec ante. Donec ullamcorper, fe- lis non sodales commodo, lectus velit ultrices augue, a dignissim nibh lectus placerat pede.
Vivamus nunc nunc, molestie ut, ultricies vel, semper in, velit. Ut porttitor. Praesent in sapien.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Duis fringilla tristique neque.
Sed interdum libero ut metus. Pellentesque placerat. Nam rutrum augue a leo. Morbi sed elit sit amet ante lobortis sollicitudin. Praesent blandit blandit mauris. Praesent lectus tellus, aliquet aliquam, luctus a, egestas a, turpis. Mauris lacinia lorem sit amet ipsum. Nunc quis urna dictum turpis accumsan semper.
Another image
1cm wide, in a 3cm box.
Figure 25: A
\keyfig[W] with ww
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Etiam lobortis facilisis sem. Nullam nec mi et neque pharetra sollicitudin. Praesent imperdiet mi nec ante. Donec ullam- corper, felis non sodales commodo, lectus velit ultrices augue, a dignissim nibh lectus placerat pede. Vivamus nunc nunc, molestie ut, ultricies vel, semper in, velit. Ut porttitor. Prae- sent in sapien. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Duis fringilla tristique neque. Sed interdum libero ut metus. Pellentesque placerat. Nam rutrum augue a leo. Morbi sed elit sit amet ante lobortis sollicitudin. Praesent blandit blandit mauris. Praesent lectus tellus, aliquet aliquam, luctus a, egestas a, turpis. Mauris lacinia lorem sit amet ipsum. Nunc quis urna dictum turpis accumsan semper.
An image.
Figure 26: Custom-framed image
A loosely-framed box.
Figure 27: Custom loosely-framed box
2.5.8 Custom frames
Example 29: Custom frames withmdframed
Code:
\renewcommand{\KFLTtightframe}[1]{%
\begin{minipage}{\KFLTimageboxwidth}
\begin{mdtightframe}%
#1\end{mdtightframe}%
\end{minipage}
}\setlength{\KFLTtightframewidth}{1pt}
\renewcommand{\KFLTlooseframe}[1]{%
\begin{mdlooseframe}[leftmargin=.5in,rightmargin=.5in]%
#1\end{mdlooseframe}%
}\setlength{\KFLTlooseframewidth}{4pt}
\keyfig{ft,c=Custom-framed image,l=fig:customframe,r=90}{image}
\keyfigbox{f,c=Custom loosely-framed box,
l=fig:customlooseframe}{A loosely-framed box.}
Result:
Figures26and27
Example29shows custom frames created with themdframedpackage along with
Pkg mdframed
tikz. Note thatmdframeduses the full\linewidtheven if the left/right margins are
! mdframedwidth
explicitly set, which causes extra vertical space when rotated. Because of this, the framed object is enclosed inside a minipage whose width is precomputed based on the object itself, then set in\KFLTimageboxwidth. Any shadow may fall outside this
An image.
Figure 28: Custom shadow
A loosely-framed shadow box.
Figure 29: Custom loosely-framed shadow
box.
See section2.6.1for more details.
Example 30: Custom shadows withfancybox
Code:
\renewcommand{\KFLTtightframe}[1]{%
\setlength{\fboxrule}{.4pt}
\setlength{\fboxsep}{0pt}
\setlength{\shadowsize}{2pt}
\shadowbox{#1}%
}\setlength{\KFLTtightframewidth}{0.4pt}
\renewcommand{\KFLTlooseframe}[1]{%
\setlength{\fboxrule}{.4pt}
\setlength{\fboxsep}{3pt}
\setlength{\shadowsize}{2pt}
\shadowbox{#1}%
}\setlength{\KFLTlooseframewidth}{3.4pt}
\keyfig{ft,c=Custom shadow,l=fig:customshadow}{image}
\keyfigbox{f,c=Custom loosely-framed shadow,lw=.5,
l=fig:customlooseshadow}{A loosely-framed shadow box.}
Result:
Figures28and29
Example30shows custom shadow frames created with thefancyboxpackage. This
Pkg fancybox
combination respectslwandw.
See section2.6.1for more details.
An image.
MR. FIRST LAST III About the illustration.
Figure 30: Artist’s name — image
Some text, a quotation, a TikZ diagram — anything not an image file.
MR. LAST Figure 31: Artist’s name — arbitrary contents
2.5.9 Artist’s name
Example 31: Artist’s name — image
Code:
\keyfig{ft,ap=Mr.,af=First,al=Last,as={~III}, tc={\textit{About the illustration.}},
c=Artist's name --- image,l=fig:artist}{image}
Result:
Figure30
Example 32: Artist’s name — arbitrary contents
Code:
\tdartistright
\begin{keyfigure}{f,ap=Mr.,al=Last,
c=Artist's name --- arbitrary contents,l=fig:artistpar}
\centering Some text, a quotation, a TikZ\ diagram --- anything not an image file.
\end{keyfigure}
\tdartistcenter
Result:
Figure31
The artist’s name and optional prefix/suffix are printed below the figure, and an index entry is made for the name in (Last, First) format, or (Last) if there is no first name. If thetocdatapackage is loaded, the artist’s name is also added to the List of Figures, and thetocdata\tdname. . . macros may be used to align the name.
An image.
a: Artist’s First Work
Another image
Commentary about the work.
b: Artist’s Second Work
PREFIX FIRST LAST, SUFFIX
Some fully-justified text just for illustrative purposes, in case you have use for long explanations. This text may be the full\linewidthin size.
Multiple paragraphs of text are allowed.
Figure 32: Artist’s collection
Example 33: Subfloats with an artist
Code:
\begin{keysubfigs}{2}{
c=Artist's collection, l=fig:artistcollection,
t={Some fully-justified text just for illustrative purposes, in case you have use for long explanations.
This text may be the full \cs{linewidth} in size. \par Multiple paragraphs of text are allowed.},
ap=Prefix,af=First,al=Last,as={, Suffix}
} \keyfig{c=Artist's First Work}{image}
\keyfig{c=Artist's Second Work,
tc={Commentary about the work.}}{image2}
\end{keysubfigs}
Result:
Figure32
A group of figures may be placed into a subfloat container, which may have its own artist keys and additional text. Furthermore, each subfloat inside the collection may also have its own artist tags and additional text.
2.6 Customization
2.6.1 Custom frames
There are two user-redefinable framing macros:
\KFLTtightframeand\KFLTlooseframe
A float’s contents are placed into a box, which is passed to either of these two macros depending on the keyfortf.
Each macro takes one argument and frames it.
Each macro has a associated LATEX lengths:
\KFLTtightframewidthand\KFLTlooseframewidth
These lengths must be redefined to the expected total frame width, equal to the frame thickness plus separation.
The default definitions are:
\newcommand{\KFLTtightframe}[1]{%
\setlength{\fboxsep}{0pt}%
\setlength{\fboxrule}{.4pt}%
\fbox{#1}%
}\setlength{\KFLTtightframewidth}{.4pt}
\newcommand{\KFLTlooseframe}[1]{%
\setlength{\fboxsep}{3pt}%
\setlength{\fboxrule}{.4pt}%
\fbox{#1}%
}\setlength{\KFLTlooseframewidth}{3.4pt}
See example29for an example created with themdframedpackage, and example30 for an example created with thefancyboxpackage.
2.6.2 Distance between floats and rows
To spread out the distance between floats and/or rows of floats on a busy page, the rows too close/far
following settings may be changed. The settings used in this documentation are:
\setlength{\floatsep}{5ex plus 1ex minus 1ex}
\setlength{\dblfloatsep}{5ex plus 1ex minus 1ex}
2.6.3 Formatting the captions
To modify the typesetting of the captions, see thecaptionpackage. The settings used in this documentation are:
% default applied to margin floats:
\captionsetup{labelfont={small,bf},textfont={small,bf}}
\captionsetup[figure]{
style=default, justification=centering, margin=0pt, parskip=0pt, skip=2ex, labelfont={small,bf},textfont={small,bf}
}
\captionsetup[table]{
style=default, justification=centering, margin=0pt, parskip=0pt, skip=1ex, labelfont={small,bf},textfont={small,bf}
}
\captionsetup[subfigure]{
style=default, justification=centering, margin=0pt, parskip=0pt, skip=2ex, labelfont={small},textfont={small}
}
\captionsetup[subtable]{
style=default, justification=centering, margin=0pt, parskip=0pt, skip=1ex, labelfont={small},textfont={small}
}
3 Code
3.1 Older packages
Ensure thattocdata, if loaded, is new enough:
1\@ifpackageloaded{tocdata}{
2 \@ifpackagelater{tocdata}{2019/03/21}{}{
3 \PackageError{keyfloat}
4 {%
5 The tocdata package is out of date.\MessageBreak
6 Update to tocdata v2.02 2019/03/21 or later\MessageBreak
7 to use use this version of keyfloat%
8 }
9 {%
10 Please update the tocdata package. It’s worth it!%
11 }
12 }
13}{}
3.2 Prohibited packages
Prohibits the use of a certain other packages.
\KFLT@@prohibitpackage {⟨packagename⟩}
14\newcommand*{\KFLT@@prohibitpackage}[2]{%
15\@ifpackageloaded{#1}
16{
17 \PackageError{keyfloat}
18 {%
19 The keyfloat package conflicts with the #1\MessageBreak
20 package. Remove #1 to use keyfloat.\MessageBreak
21 Alternative(s):\MessageBreak
22 \space\space#2%
23 }
24 {%
25 Keyfloat uses the caption, subcaption, newfloat, and wrapfig packages.%
26 }
27}{}
28}
\KFLT@prohibitpackage {⟨packagename⟩}
Prohibits the use of another package, both now and also\AtBeginDocument.
29\newcommand*{\KFLT@prohibitpackage}[2]{
30 \KFLT@@prohibitpackage{#1}{#2}
31 \AtBeginDocument{\KFLT@@prohibitpackage{#1}{#2}}
32}
The list of prohibited packages:
33\KFLT@prohibitpackage{floatrow}{caption and subcaption}
34\KFLT@prohibitpackage{subfig}{subcaption}
35\KFLT@prohibitpackage{subfigure}{subcaption}
36\KFLT@prohibitpackage{subfloat}{subcaption}
37\KFLT@prohibitpackage{floatflt}{wrapfig}
3.3 Required packages
v2.6 or later for\BeforeBeginEnvironment,\AfterEndEnvironment
Pkg etoolbox
38\RequirePackage{etoolbox}[2011/01/03]%
Argument processing:
Pkg xparse
39\RequirePackage{xparse}
Key processing:
Pkg keyval
40\RequirePackage{xkeyval}
For\includegraphicsandrotating:
Pkg graphicx
41\RequirePackage{graphicx}
Handles all caption-related functions:
Pkg caption
42\RequirePackage{caption}[2010/10/31]% v3.2 to support \phantomcaption Derived fromcaption, used to handle subfloats:
Pkg subcaption
43\RequirePackage{subcaption}
Used to compute box width minus frame sep and width.
Pkg calc
44\RequirePackage{calc}
Provides rotation via theturnenvironment:
Pkg rotating
45\RequirePackage{rotating}
Provides
Pkg placeins
to process existing floats before adding new ones.
46\RequirePackage{placeins}
Provides figure wrapping code.
Pkg wrapfig
47\RequirePackage{wrapfig}
Used byhyperrefandnameref.
Pkg gettitlestring
Expand names used in titles:
48\PassOptionsToPackage{expand}{gettitlestring}
Rows of floats are created by a simpleminipageenvironment, instead of relying on a preexisting package. This proved to be advantageous when support was added for multiple rows in one environment.
3.4 In-line figures and tables
These macros are commonly used by others.
Env tablehere Place a table exactly [H].
tablehere minipage
Contents
49\ProvideDocumentEnvironment{tablehere}{}
50{%
51 \vskip\intextsep\noindent%
52 \minipage{\linewidth}%
53 \def\@captype{table}%
54 \normalcolor\reset@font\normalsize%
55}%
56{\endminipage\vskip\intextsep}%
Env figurehere Place a figure exactly [H].
