summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/keyfloat/keyfloat.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/keyfloat/keyfloat.dtx')
-rw-r--r--macros/latex/contrib/keyfloat/keyfloat.dtx745
1 files changed, 597 insertions, 148 deletions
diff --git a/macros/latex/contrib/keyfloat/keyfloat.dtx b/macros/latex/contrib/keyfloat/keyfloat.dtx
index 5baa10608e..a729c86a4b 100644
--- a/macros/latex/contrib/keyfloat/keyfloat.dtx
+++ b/macros/latex/contrib/keyfloat/keyfloat.dtx
@@ -1,7 +1,7 @@
%
% \iffalse meta-comment
%
-% Copyright 2016 Brian Dunn
+% Copyright 2016--2021 Brian Dunn
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
@@ -17,7 +17,7 @@
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{keyfloat}
-%<package> [2021/06/11 v2.05 Key/value interface for floats and subfloats.]
+%<package> [2021/06/29 v2.06 Key/value interface for floats and subfloats.]
%
%<*driver>
\documentclass{ltxdoc}
@@ -71,6 +71,8 @@
\newunicodechar{‡}{\ddag}
\newunicodechar{⚠}{\textwarning}
+
+
\usepackage{metalogo}
\makeatletter
\@ifpackageloaded{erewhon}{
@@ -90,6 +92,8 @@
\usepackage[log-declarations=false]{xparse}
+
+
\usepackage[svgnames]{xcolor}
\definecolor{myurlcolor}{rgb}{0,0,.7}
\definecolor{mylinkcolor}{rgb}{.7,0,0}
@@ -235,6 +239,30 @@ frametitlerulewidth=1pt,frametitleaboveskip=5pt,%
+\usepackage{splitidx}
+
+\newindex[Index of Objects]{idx}
+\newindex[General Index]{gen}
+% \newindex[Troubleshooting Index]{trb}
+\newindex[Index of Indexes]{meta}
+
+\makeindex
+
+\newcommand*{\gindex}[1]{\sindex[gen]{#1}\ignorespaces}
+
+% \trouble[watchout phrase]{index entry}
+\newcommand*{\trouble}[2][]{%
+\ifblank{#1}{}{%
+ \watchout[#1]%
+}%
+% \sindex[trb]{#2}%
+\gindex{#2}%
+\ignorespaces%
+}
+
+
+
+
\newcommand{\testtable}{%
\begin{tabular}{cc}%
\hline\rule{0pt}{2.7ex}%
@@ -255,7 +283,7 @@ D & E & F \\
\newcommand{\mainsubarg}{empty or ``\texttt{subgrp}''}
-\newcommand{\keyvalsarg}{keys/values}
+\newcommand{\keyvalsarg}{keys \Slash values}
\setlength{\floatsep}{5ex plus 1ex minus 1ex}
\setlength{\dblfloatsep}{5ex plus 1ex minus 1ex}
@@ -300,6 +328,10 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
+\setlength{\marginparsep}{1em}
+\setlength{\marginparpush}{.7ex}
+\setlength{\IndexMin}{40ex}
+
\setcounter{IndexColumns}{2}
\DisableCrossrefs
@@ -317,7 +349,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%<*package>
% \fi
%
-% \CheckSum{1320}
+% \CheckSum{1392}
%
% \CharacterTable
% {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
@@ -357,6 +389,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \changes{v2.03}{2021/05/28}{2021/05/28}
% \changes{v2.04}{2021/06/08}{2021/06/08}
% \changes{v2.05}{2021/06/11}{2021/06/11}
+% \changes{v2.06}{2021/06/29}{2021/06/29}
@@ -424,22 +457,23 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% two small figures placed vertically next to
% one larger figure.
%
-% \vfill
-%
-% \noindent
% As an example, a typical command to include a figure with a framed image of half \cs{linewidth}
% could be: \\
% \hspace*{1em}\verb|\keyfig*[hbp]{f,lw=.5,c={A caption},l={fig:label}}{image}|
%
-% \vfill
-%
-% \noindent \pkg{keyfloat} uses the \pkg{caption}, \pkg{subcaption},
+% \pkg{keyfloat} uses the \pkg{caption}, \pkg{subcaption},
% \pkg{newfloat} or \pkg{float}, and \pkg{wrapfig} packages,
-% \watchout
+% \watchout[incompatible packages]
% and cannot be used with the
% \pkg{subfig}, \pkg{subfigure}, \pkg{subfloat}, \pkg{floatrow},
% or \pkg{floatflt} packages.
%
+% See the \nameref{sec:indexgen} for an index of topics and troubleshooting.
+% \watchout[Need help?]
+%
+% For the latest updates, see \nameref{sec:updates}.
+% \margintag{What's new?}
+%
% \vfill
%
% \footnotesize
@@ -585,8 +619,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \margintag{examples}
% the resulting float.
%
-% A customized index is included at the back of the documentation.
+% A customized index is included at the back of the documentation,
% \margintag{index}
+% including troubleshooting issues.
%
% Blue margin tags are used to help quickly find information, and often
% \margintag{margin tags}
@@ -595,10 +630,37 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% Several warnings are noted in the text. Watch out for these special cases.
% \watchout[warnings]
%
-% See the ``troubleshooting'' section of the index for help
-% \margintag{problems}
-% with specific problems which may occur.
+% ^^A % See the ``troubleshooting'' section of the index for help
+% ^^A % \margintag{problems}
+% ^^A % with specific problems which may occur.
%
+% \subsection{Updates}
+%
+% \label{sec:updates}
+%
+% Recent changes include the following:
+% \begin{description}
+% \item[v2.06:] Added shared keys for groups of floats or subfloats.
+% Added the \optn{kar} key to keep the aspect ratio of an image.
+% Removed \texttt{:} for an empty caption.
+% Warns if an image is too wide to fit.
+% \item[v2.02, v2.04:] Added keys for wrapped floats.
+% \end{description}
+%
+% \subsection{Other float-related packages}
+%
+% Several other \LaTeX\ packages related to floats include:
+% \begin{description}
+% \item[\pkg{caption} and \pkg{subcaption}:] Improved control over captions.
+% \item[\pkg{floatrow}:] A macro-based package for creating floats; including captions,
+% footnotes, and rows of floats.
+% \item[\pkg{hvfloat}:] A key \Slash value system allowing the easy rotation of
+% captions and floats.
+% \item[\pkg{nccfloats}:] Macros for minipage floats and side-by-side floats.
+% \item[\pkg{newfloat}:] Macros for the creationg of float environments.
+% \item[\pkg{rotfloat}:] Environments for rotated floats.
+% \item[\pkg{subfig}:] Macros to add subfloats inside a float.
+% \end{description}
%
%
% \clearpage
@@ -710,25 +772,29 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{docsidebar}
%
%
-% \DescribeEnv{keyfloats} * \oarg{loc} \marg{num columns} \\
+% \DescribeEnv{keyfloats} * \oarg{loc} \marg{num columns} \oarg{shared \keyvalsarg} \\
% A group of figures or tables typeset in rows. May be nested, [H], [W], or [M].
+% The optional shared \keyvalsarg\ are passed to each object within.
% See \cref{ex:keyfloats}.
%
-% \DescribeEnv{keysubfigs} * \oarg{loc} \marg{numcols} \marg{keys} \\
+% \DescribeEnv{keysubfigs} * \oarg{loc} \marg{numcols} \marg{keys} \oarg{shared \keyvalsarg} \\
% A group of subfigures typeset in rows.
% May \emph{not} be nested. May be [H], [W], or [M].
+% The optional shared \keyvalsarg\ are passed to each object within.
% See \cref{ex:keysubfigs}.
%
% \needspace{2\baselineskip}
-% \DescribeEnv{keysubtabs} * \oarg{loc} \marg{numcols} \marg{keys} \\
+% \DescribeEnv{keysubtabs} * \oarg{loc} \marg{numcols} \marg{keys} \oarg{shared \keyvalsarg} \\
% A group of subtables typeset in rows.
% May \emph{not} be nested. May be [H], [W], or [M].
+% The optional shared \keyvalsarg\ are passed to each object within.
% See \cref{ex:keysubtabs}.
%
% \needspace{2\baselineskip}
-% \DescribeEnv{keysubfloats} * \oarg{loc} \marg{float type} \marg{numcols} \marg{keys} \\
+% \DescribeEnv{keysubfloats} * \oarg{loc} \marg{float type} \marg{numcols} \marg{keys} \oarg{shared \keyvalsarg} \\
% A group of subfloats typeset in rows.
% May \emph{not} be nested. May be [H], [W], or [M].
+% The optional shared \keyvalsarg\ are passed to each object within.
%
% \DescribeEnv{keywrap} \marg{width of keyfloat} \marg{keyfloat} \\
% Displays a keyfloat next to an environment of text.
@@ -800,7 +866,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% \begin{keytable}[bp]{c={Keys and values — part I},l={tab:keyvals},stretch=1.5}
% \centering
-% \index{keys>and values}
+% \gindex{keys>and values}
% \begin{threeparttable}
% \small
% \begin{tabular}{>{\ttfamily}cc>{\raggedright}p{2.5in}>{\centering\arraybackslash}>{\ttfamily\arraybackslash}p{1in}}
@@ -830,7 +896,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \bottomrule
% \end{tabular}
% \begin{tablenotes}
-% \item[a:] All the keys in Part I may be used with the
+% \item[a:] All the keys in Part I may be used with the main keys of the
% \env{keysubfigs}, \env{keysubtabs}, and \env{keysubfloats} environments.
% \item[b:] Artist \Slash author keys:
% |al| is an artist's last name, |aul| is an author's last name, etc.
@@ -851,7 +917,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \begin{keytable}{
% c={Keys and values — part II},cont,stretch=1.5}
% \centering
-% \index{keys>and values}
+% \gindex{keys>and values}
% \begin{threeparttable}
% \small
% \begin{tabular}{>{\ttfamily}cc>{\raggedright}p{2.5in}>{\centering\arraybackslash}>{\ttfamily\arraybackslash}p{1in}}
@@ -868,8 +934,10 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% For wrapped objects, may be used with \optn{ww} for a smaller item
% with a larger caption.
% & w=2in \\
-% h & --- & Set the actual height, images only. & w=2in \\
-% s & --- & Set the image scale, images only. & s=3 \\
+% h & --- & Set the actual height. Images only. & w=2in \\
+% kar & --- & Keep aspect ratio: Use with \optn{w} or \optn{lw}, along with \optn{h},
+% 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 \cs{fboxsep}.
% Only rotated with \cs{keyfig}. & f \\
@@ -888,13 +956,14 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% ww & --- & Sets the total width of the wrapped item.
% May be more than the \optn{w} or \optn{lw} width. & ww=2in \\
% va & --- & Sets the vertical alignment of the outermost minipage container for the keyfloat.
-% Defaults to 'c'.
+% Defaults to 'c'. Ignored by \env{subfigure}, \env{subtable}.
% & va=t \\
% \bottomrule
% \end{tabular}
% \begin{tablenotes}
-% \item[c:] None of the keys in Part II are used in the
-% \env{keysubfigs}, \env{keysubtabs}, and \env{keysubfloats} environments.
+% \item[c:] None of the keys in Part II are used in the main keys of the
+% \env{keysubfigs}, \env{keysubtabs}, or \env{keysubfloats} environments,
+% but may be used in the optional shared keys to be passed to each object within.
% \end{tablenotes}
% \end{threeparttable}
% \end{keytable}
@@ -904,14 +973,14 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% except for the following:
%
% The keys labeled "Sub"\margintag{subfloat keys}
-% \index{subfloat>keys}\index{keys>subfloats}
+% \gindex{subfloat>keys}\gindex{keys>subfloats}
% may be used for the \env{keysubfigs} and
% \env{keysubtabs} environments, 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.
%
% \env{keyfloats} does not accept any keys at all.\margintag{keyfloats keys}
-% \index{keyfloats>keys}\index{keys>keyfloats}
+% \gindex{keyfloats>keys}\gindex{keys>keyfloats}
%
% The ``artist'' keys |ap|, |af|, |al|, and |as| are only used by figures.
%
@@ -928,7 +997,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
%
% \begin{keytable}{c={Caption-related key combinations},l=tab:captions,stretch=1.5}
-% \index{caption>options}
+% \gindex{caption>options}
% \centering
% \begin{threeparttable}
% \small
@@ -963,7 +1032,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% for floats placed |[W]|.
%
% \begin{keytable}{c={Key \optn{wp}: Wrapped float placement options},l=tab:wrapplacement}
-% \index{float>wrapped placement}\index{wrapped float placement}
+% \gindex{float>wrapped placement}\gindex{wrapped float placement}
% \centering
% \begin{tabular}{ccl}
% \toprule
@@ -1023,7 +1092,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \margintag{natural size}
% because no width or height modifiers were specified. When used alone like this,
% a regular float is created.
-% \index{image>natural size}
+% \gindex{image>natural size}
%
%
% \begin{dtxexample}[\Cref{fig:figbox}]{Figure with arbitrary contents\label{ex:keyfigbox}}
@@ -1033,7 +1102,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% The \cs{keyfigbox} creates a figure with a box of arbitrary contents, instead of
% an image from a file. Its default width is the full \cs{linewidth},\margintag{default width}
-% \index{float>default width}
+% \gindex{float>default width}
% unless |w| or |lw| keys are used.
%
%
@@ -1060,8 +1129,8 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% See \cref{ex:keytable}.
%
% For large tables, use the \pkg{longtable} or \pkg{supertabular} packages.
-% \margintag{large tables}\index{tables>large}
-% \index{troubleshooting>large tables}
+% \margintag{large tables}
+% \trouble{table>large}
%
%
% \begin{dtxexample}[\Cref{tab:environment}]
@@ -1096,6 +1165,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% }{image}
% \end{dtxexample}
%
+% \gindex{text>added}
+% \gindex{float>text added}
+%
% Width is fixed at 2\,in, a tight frame is specified (\cs{fboxsep} of 0\,pt),
% a short caption appears in the List of Figures, and the additional text
% is using the default fully-justified alignment.
@@ -1111,8 +1183,8 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% \Cref{fig:linewidth} is half of \cs{linewidth} in size.
% \margintag{\cs{linewidth}}
-% \index{image>\cs{linewidth}}\index{\cs{linewidth}}
-% \index{subfloat>\cs{linewidth}}\index{keyfloats>\cs{linewidth}}
+% \gindex{image>\cs{linewidth}}\gindex{\cs{linewidth}}
+% \gindex{subfloat>\cs{linewidth}}\gindex{keyfloats>\cs{linewidth}}
% When the |lw| key is used inside a \env{keyfloats} or \env{keysubfigs} environment,
% the \cs{linewidth} will be proportional to the sub-box for each element.
% When used alone, such as here, the \cs{linewidth} is the full width of the text on
@@ -1160,8 +1232,8 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% Unless a width is given, a box is the full \cs{linewidth}.
% \margintag{rotated whitespace}
% When rotated, this extra horizontal space is rotated into extra vertical space.
-% \index{rotate>box width and vertical space}\index{\cs{linewidth}>with rotation}
-% \index{troubleshooting>rotating>extra space}
+% \gindex{rotate>box width and vertical space}\gindex{\cs{linewidth}>with rotation}
+% \trouble{rotate>extra space}
% To avoid this extra space, set a |w| or |lw| to be wide enough
% \watchout[box width]
% for the table or other contents,
@@ -1169,8 +1241,8 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% vertical space than necessary.
%
% Unlike an image, the frame of a box does not rotate with its contents.
-% \margintag{frame rotation}\index{frame>rotation}
-% \index{troubleshooting>rotating>frame}
+% \margintag{frame rotation}\gindex{frame>rotation}
+% \trouble{rotate>frame}
%
% \clearpage
%
@@ -1179,10 +1251,13 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \keyfig[H]{f,w=1in,c={A keyfig [H]},l=fig:here}{image}
% \end{dtxexample}
%
+% \gindex{h=[H]ere placement}
+% \gindex{float>h=[H]ere placement}
+% \gindex{float>inline}
% \Cref{tab:here} and \Cref{fig:here} are to be placed ``[H]ere'', and therefore may appear
% \watchout[Out of sequence]
% out-of-sequence with surrounding figures.
-% \index{troubleshooting>float out of sequence}
+% \trouble{float>out of sequence}
% Place a \cs{clearpage} before or after to re-sync, if necessary.
%
%
@@ -1192,14 +1267,16 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \keyfig[H]{f,cstar={A starred caption}}{image}
% \end{dtxexample}
%
+% \gindex{float>unnumbered}
+%
% 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.
-% \watchout[No label]
-% \index{troubleshooting>missing label}
-%
+% \trouble[No label]{label>missing}
+% \trouble{label>unnumbered float}
+% \trouble{float>unnumbered>no label}
%
% \begin{dtxexample}
% [See fig: ``Starred caption with a short caption''.]
@@ -1224,6 +1301,8 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% }{image2}
% \end{dtxexample}
%
+% \gindex{float>inline without caption}
+%
% By using [H] and |cstar={}|, the image is placed inline
% without a number or \acro{LOF} entry.
%
@@ -1241,9 +1320,11 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% }{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 row.}
+% \keyparbox[H]{f,lw=.5}{A \cs{keyparbox} [H], outside the keyfloats.}
% \end{dtxexample}
%
+% \gindex{float>without caption}
+%
% A \cs{keyparbox} is a \cs{keyfigbox} with |cstar={}|,
% and is mostly useful as an information box inside a row or a set of subfloats.
%
@@ -1252,64 +1333,97 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% \clearpage
%
-% \subsubsection{Groups of floats}
+% \subsubsection{Groups of floats, shared keys, keep aspect ratio}
%
% \begin{dtxexample}[\Cref{fig:firstinrow} to \Cref{tab:seventhinrow}]{Groups of figures — \env{keyfloats} environment\label{ex:keyfloats}}
% \begin{keyfloats}{2}
-% \keyfig{lw=1,f,c={First in a group},
+% \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}
-% \keyfig{lw=1,c={Third in a group},
-% l=fig:thirdinarow}{image}
-% \keyfig{lw=1,c={Fourth in a group}}{image2}
-% \keyfig{lw=1,c={Fifth in a group}}{image}
-% \keyfig{lw=1,c={Sixth in a group},
-% l=fig:sixthinarow}{image2}
+% \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}
% \end{dtxexample}
%
%
-% \Cref{fig:firstinrow} to \cref{tab:seventhinrow} are in a \env{keyfloats} environment.
-% Furthermore, \Crefrange{fig:thirdinarow}{fig:sixthinarow} are in an
-% additional nested \env{keyfloats} environment, forming a small box of floats inside
-% the larger group.
-%
% The \env{keyfloats} environment takes an argument for the number of columns.
-% Additional floats are automatically placed on following rows.
+% Additional floats
+% \margintag{automatic layout}
+% are automatically placed on following rows.
% Changing the number of columns will cause the floats to automatically readjust as
% necessary. Leftovers will be centered on the last row.
+% An optional argument
+% \margintag{shared keys}
+% \gindex{group>shared keys}
+% \gindex{float>shared keys}
+% \gindex{keys>shared in a group}
+% may contain keys and values which are passed to each object
+% inside the group.
+%
+% \Cref{fig:firstinrow} to \cref{tab:seventhinrow} are in a \env{keyfloats} environment.
+% Furthermore,
+% \margintag{nested groups}
+% \Crefrange{fig:thirdinarow}{fig:sixthinarow} are in an
+% additional nested \env{keyfloats} environment, 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 \cs{linewidth} is adjusted for each row and nested row,
% \watchout[\cs{linewidth}]
-% so the |lw| key will need to be changed if a float is moved to a different nesting level.
-% \index{troubleshooting>\cs{linewidth}}\index{\cs{linewidth}>subfloats}
-% \index{subfloat>\cs{linewidth}}
+% so the |lw| key may need to be changed if a float is moved to a different nesting level.
+% \trouble{\cs{linewidth}}\gindex{\cs{linewidth}>subfloats}
+% \gindex{subfloat>\cs{linewidth}}
%
% Fixed-width or fixed-height floats may be too large to fit
% \watchout[image too large]
-% if they are moved into a group.
+% if they are moved into a group. A warning is issued if so.
% It is the user's responsibility to adjust |w|, |h|, or |lw| as necessary.
-% \index{troubleshooting>image too large}
+% \trouble{image>too large}
+% To allow images to automatically adjust, use |lw=1| or less, which adjusts
+% to the \cs{linewidth}.
%
-% Keyfloats may be located [H], [M], or located [W] set with half the line width:\\
+% Keyfloats may be located
+% \margintag{location}
+% [H], [M], or located [W] set with half the line width:\\
% \hspace*{2em}|\begin{keyfloats}[H]{2}| \dots
%
-% Keyfloats may be starred to span both columns in a two-column format: \\
+% Keyfloats may be starred
+% \margintag{two columns}
+% to span both columns in a two-column format: \\
% \hspace*{2em}|\begin{keyfloats}*{2}| \dots
%
+% As shown in the sub group above,
+% \margintag{grid of images}
+% \gindex{group>nested}
+% \gindex{float>nested group}
+% \gindex{image>grid of}
+% \gindex{image>keep aspect ratio}
+% \gindex{aspect ratio}
+% \gindex{keep aspect ratio}
+% to display a group of images of varying shape inside 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{sourceverb}
+% \begin{keyfloats}{2}[lw=1,h=3em,kar,va=t]
+% ...
+% \end{keyfloats}
+% \end{sourceverb}
+%
%
% \clearpage
%
% \subsubsection{Subfloats}
%
-%
-%
-%
% \begin{dtxexample}[\Cref{fig:subfigs}]{Subfigures — \env{keysubfigs} environment\label{ex:keysubfigs}}
% \begin{keysubfigs}{3}{c=Subfigures,l=fig:subfigs}
% \keyfig{lw=1,f,c={First subfigure},
@@ -1319,9 +1433,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% 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}
+% \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}
% \end{dtxexample}
@@ -1339,28 +1453,43 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% subcaption does not appear in the \acro{LOF}/\acro{LOT}.
%
% All subfloats are forced to have the same type as
-% its containing float.\index{troubleshooting>mixed subfloats}
+% its containing float.\trouble{mixed subfloats}
% \watchout[mixed subfloats]
% A table inside 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.
%
% \env{keysubfigs} and \env{keysubtabs} may not be used inside\watchout[nested subfloats]
-% \index{troubleshooting>nested subfloats}\index{subfloat>nested}
+% \trouble{nested subfloats}\gindex{subfloat>nested}
% the \env{keyfloats} environment,
% and cannot be nested inside each other. (No subfloat |12aa|, |12ab|, |12ba|, etc.)
%
% The \env{keyfloats} environment may be used inside \env{keysubfigs} or
-% \margintag{nested keyfloats}\index{keyfloats>nested}
+% \margintag{nested keyfloats}\gindex{keyfloats>nested}
% \env{keysubtabs} to gather subfloats together, such as the
% three right-most figures in \cref{fig:subfigs}.
%
-% Subfloats may be located [H], [M], or located [W] set with half the line width: \\
+% Subfloats may be located
+% \margintag{location}
+% [H], [M], or located [W] set with half the line width: \\
% \hspace*{2em}|\begin{keysubfigs}[H]{3}{|key/vals \dots|}|
%
-% Subfloats may be starred to span both columns in a two-column format: \\
+% Subfloats may be starred
+% \margintag{two columns}
+% to span both columns in a two-column format: \\
% \hspace*{2em}|\begin{keysubfigs}*{2}{|key/vals \dots|}|
%
+% A group of subfloats
+% \margintag{shared keys}
+% \gindex{group>shared keys}
+% \gindex{subfloat>shared keys}
+% \gindex{keys>shared in a group}
+% may have an optional argument for shared keys and values,
+% which are then passed to each subfloat within.
+%
+% The vertical alignment
+% \watchout[va]
+% option |va| does not work with subfloats.
%
% \begin{dtxexample}[\Cref{tab:subtabs}]{Subtables [H] — \env{keysubtabs} environment\label{ex:keysubtabs}}
% \begin{keysubtabs}[H]{2}{c=Subtables [H],l=tab:subtabs}
@@ -1375,6 +1504,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% \subsubsection{Continued floats}
%
+% \gindex{float>continued}
+% \gindex{continued float}
+%
% The |cont| key 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
@@ -1393,7 +1525,11 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% \clearpage
% \subsubsection{Continued subfloats}
-%
+%
+% \gindex{float>subfloat continued}
+% \gindex{subfloat>continued}
+% \gindex{continued subfloat}
+%
% The \env{keysubfigs} and \env{keysubtabs} environments may also
% be given the |cont| key.
% The containing environment's float receives the same number as the previous float
@@ -1415,6 +1551,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \subsubsection{Margin floats}
% \changes{v0.12}{2016/12/02}{Docs: Margin float examples.}
%
+% \gindex{float>margin placement}
+% \gindex{margin placement}
+%
% When a keyfloat is located [M], it will be placed in the margin.
%
% \DescribeClass{tufte-book}
@@ -1469,7 +1608,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% To set the minimum-allowed distance between \cs{marginpar}s and margin floats:
% \margintag{distance between floats}
-% \index{distance between floats}\index{float>distance between}
+% \gindex{distance between floats}\gindex{float>distance between}
% \begin{sourceverb}
% \setlength{\marginparpush}{3ex}
% \end{sourceverb}
@@ -1574,7 +1713,6 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \clearpage
% \subsubsection{Custom frames}
%
-%
% \begin{dtxexample}[\Cref{fig:customframe,fig:customlooseframe}]
% {Custom frames with \pkg{mdframed}\label{ex:customframe}}
% \renewcommand{\KFLTtightframe}[1]{%
@@ -1598,6 +1736,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% l=fig:customlooseframe}{A loosely-framed box.}
% \end{dtxexample}
%
+% \gindex{frame>mdframed}
+% \gindex{mdframed}
+%
% \DescribePackage{mdframed}
% \Cref{ex:customframe} shows custom frames
% created with the \pkg{mdframed} package along with \pkg{tikz}.
@@ -1609,8 +1750,8 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% whose width is precomputed based on the object itself, then
% set in \cs{KFLTimageboxwidth}. Any shadow may fall outside this
% box.
-% \index{troubleshooting>rotating>extra space}
-% \index{troubleshooting>mdframed}
+% \trouble{rotate>extra space}
+% \trouble{mdframed}
%
% See \cref{sec:customframes} for more details.
%
@@ -1637,6 +1778,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% l=fig:customlooseshadow}{A loosely-framed shadow box.}
% \end{dtxexample}
%
+% \gindex{fancybox}
+% \gindex{frame>fancybox}
+%
% \DescribePackage{fancybox}
% \Cref{ex:customshadow} shows custom shadow frames
% created with the \pkg{fancybox} package.
@@ -1669,6 +1813,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \clearpage
% \subsubsection{Artist's name}
%
+% \gindex{author's or artist's name}
+% \gindex{name>author or artist}
+%
% \begin{dtxexample}[\Cref{fig:artist}]{Artist's name — image}
% \keyfig{ft,ap=Mr.,af=First,al=Last,as={~III},
% tc={\textit{About the illustration.}},
@@ -1723,7 +1870,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \subsubsection{Custom frames}
% \label{sec:customframes}
%
-% \index{frame>custom}
+% \gindex{frame>custom}
%
% There are two user-redefinable framing macros: \\
% \hspace*{2em}\cs{KFLTtightframe} and \cs{KFLTlooseframe}
@@ -1766,10 +1913,10 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
%
% \subsubsection{Distance between floats and rows}
-% \index{distance between floats}
-% \index{subfloat>distance between}
-% \index{float>distance between}
-% \index{troubleshooting>rows too close or far}
+% \gindex{distance between floats}
+% \gindex{subfloat>distance between}
+% \gindex{float>distance between}
+% \trouble{table>rows too close or far}
% To spread out the distance between floats and/or rows of floats
% \margintag{rows too close/far}
% on a busy page, the following settings may be changed.
@@ -1782,9 +1929,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% \subsubsection{Formatting the captions}
%
-% \index{troubleshooting>caption format}
+% ^^A \trouble{caption format}
% To modify the typesetting of the captions, see the \pkg{caption} package.
-% \index{caption>formatting}
+% \gindex{caption>formatting}
% The settings used in this documentation are:
% \begin{sourceverb}
% % default applied to margin floats:
@@ -1819,8 +1966,115 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \clearpage
%
-% \StopEventually{\PrintChanges\PrintIndex}
-%
+% ^^A \StopEventually{\PrintChanges\PrintIndex}
+%
+% \makeatletter
+%
+% \StopEventually{
+% ^^A \part{Change History and Index}
+% ^^A \part{Change History}
+%
+%
+% \pagestyle{plain}
+%
+% ^^A Each index has a prologue which creates its own \part, label,
+% ^^A and meta index entry.
+% \GlossaryPrologue{
+% \part{Change History}
+% ^^A \section{Chg Hist}
+% \label{sec:changehistory}
+% \sindex[meta]{Change History}
+% \markboth{{Change History}}{{Change History}}
+%
+% For the most recent changes, see page \pageref{sec:changesend}.
+%
+% }
+% \PrintChanges
+% \phantomsection
+% \label{sec:changesend}
+%
+%
+% ^^A The instructions for the Index of Objects:
+% \IndexPrologue{
+% \clearpage
+% \expandafter\part\expandafter{\indexname}
+% \label{sec:index\indexshortcut}
+% \sindex[meta]{\indexname}
+% \markboth{Index of Objects}{Index of Objects}%
+%
+% This is an index of macros, environments, booleans, counters, lengths,
+% packages, classes, options, keys, files, and various other programming objects.
+% Each is listed by itself, and also by category.
+% In some cases, they are further subdivided by [class].
+%
+% Numbers written in italic refer to the page
+% where the corresponding entry is described;
+% numbers underlined refer to the
+% \ifcodeline@index
+% code line of the
+% \fi
+% definition.
+% ^^A ; numbers in roman refer to the
+% ^^A \ifcodeline@index
+% ^^A code lines
+% ^^A \else
+% ^^A pages
+% ^^A \fi
+% ^^A where the entry is used.
+% }
+%
+% \printindex[idx][Index of Objects]
+%
+%
+% ^^A The instructions for the General Index:
+% \IndexPrologue{
+% \clearpage
+% \expandafter\part\expandafter{\indexname}
+% \label{sec:index\indexshortcut}
+% \sindex[meta]{\indexname}
+%
+% ^^A This is an index of instructions and concepts.
+% ^^A Look here when wondering how to do something, and
+% ^^A check the Troubleshooting Index when something goes wrong.
+% This is a general index, including how-to and troubleshooting.
+% }
+%
+% \printindex[gen][General Index]
+%
+%
+% ^^A% The instructions for the Troubleshooting Index:
+% ^^A% \IndexPrologue{
+% ^^A% \clearpage
+% ^^A% \expandafter\part\expandafter{\indexname}
+% ^^A% \label{sec:index\indexshortcut}
+% ^^A% \sindex[meta]{\indexname}
+% ^^A%
+% ^^A% This index is a sorted reference of problems and solutions.
+% ^^A% In order to make it easier to locate a solution,
+% ^^A% the same issue may be addressed by more than one entry.
+% ^^A%
+% ^^A% Entries with higher page numbers are often duplicates of entries with
+% ^^A% lower page numbers, as the same warning may occur within the user manual
+% ^^A% and again within the source code for a given package.
+% ^^A% }
+% ^^A%
+% ^^A% \printindex[trb][Troubleshooting Index]
+%
+%
+% ^^A The meta index does not get a meta index entry pointing to itself:
+% \IndexPrologue{
+
+% \clearpage
+% \expandafter\part\expandafter{\indexname}
+% \label{sec:index\indexshortcut}
+% }
+%
+% \printindex[meta][Index of Indexes]
+% }
+%
+% \makeatother
+%
+%
%
%
% \section{Code}
@@ -2234,6 +2488,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
\providecommand{\tdauthorright}{}
% \end{macrocode}
%
+%
% \DescribeKey[main]{t} Additional text, justified alignment.
% \begin{macrocode}
\define@key{KFLT@keys}{t}{%
@@ -2242,6 +2497,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
}
% \end{macrocode}
%
+%
% \DescribeKey[main]{tc} Additional text, centered alignment.
% \begin{macrocode}
\define@key{KFLT@keys}{tc}{%
@@ -2250,6 +2506,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
}
% \end{macrocode}
%
+%
% \DescribeKey[main]{tr} Additional text, aligned to the right.
% \begin{macrocode}
\define@key{KFLT@keys}{tr}{%
@@ -2258,6 +2515,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
}
% \end{macrocode}
%
+%
% \DescribeKey[main]{tl} Additional text, aligned to the left.
% \begin{macrocode}
\define@key{KFLT@keys}{tl}{%
@@ -2267,7 +2525,6 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{macrocode}
%
%
-%
% \DescribeKey[main]{lw} Fraction of \cs{linewidth}
% \begin{macrocode}
\define@key{KFLT@keys}{lw}{%
@@ -2282,6 +2539,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{macrocode}
% \end{macro}
%
+%
% \DescribeKey[main]{w} Fixed width
% \begin{macrocode}
\define@key{KFLT@keys}{w}{%
@@ -2296,6 +2554,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{macrocode}
% \end{macro}
%
+%
% \DescribeKey[main]{h} Fixed height
% \begin{macrocode}
\define@key{KFLT@keys}{h}{\setlength{\KFLT@h}{#1}}
@@ -2307,6 +2566,23 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{macrocode}
% \end{macro}
%
+%
+% \DescribeKey[main]{kar} Keep aspect ratio
+% \changes{v2.06}{2021/06/25}{Added \optn{kar}.}
+% \begin{macrocode}
+\define@key{KFLT@keys}{kar}[false]{%
+ \renewcommand{\KFLT@keepaspectratio}{keepaspectratio}%
+}
+% \end{macrocode}
+%
+% \begin{macro}{\KFLT@keepaspectratio} Stores ``\optn{keepaspectratio}'' if set.
+% \changes{v2.06}{2021/06/25}{Added \optn{kar}.}
+% \begin{macrocode}
+\newcommand{\KFLT@keepaspectratio}{}
+% \end{macrocode}
+% \end{macro}
+%
+%
% \DescribeKey[main]{s} Scale
% \begin{macrocode}
\define@key{KFLT@keys}{s}{\renewcommand{\KFLT@s}{#1}}
@@ -2318,6 +2594,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{macrocode}
% \end{macro}
%
+%
% \DescribeKey[main]{r} Angle. 90 is counter-clockwise 90 degrees.
% \begin{macrocode}
\define@key{KFLT@keys}{r}{\renewcommand{\KFLT@r}{#1}}
@@ -2329,6 +2606,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{macrocode}
% \end{macro}
%
+%
% \DescribeKey[main]{f} Frame the image with \cs{KFLTlooseframe}.
% \begin{macrocode}
\define@key{KFLT@keys}{f}[true]{\setboolean{KFLT@f}{#1}}
@@ -2338,7 +2616,8 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \begin{macrocode}
\newboolean{KFLT@f}
% \end{macrocode}
-
+%
+%
% \DescribeKey[main]{ft} Tightly frame the image using \cs{KFLTtightframe}.
% This is useful for photographs, or diagrams which
% already have built-in margins.
@@ -2436,6 +2715,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{macrocode}
% \end{macro}
%
+%
% \DescribeKey[main]{ww} Wrapped figure, fixed width
% \changes{v2.02}{2021/05/27}{Added \optn{ww} and \optn{wlw}.}
% \begin{macrocode}
@@ -2790,9 +3070,11 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% A user-redefinable macro and length to tightly frame the contents.
%
-% \cs{KFLTtightframe} may be redefined to a macro which frames its contents.
-% \cs{KFLTtightframewidth} should be redefined to the total width of the new
-% frame and its separation.
+% \begin{description}
+% \item [\cs{KFLTtightframe}:] Redefine to a macro which frames its contents.
+% \item [\cs{KFLTtightframewidth}:] Redefine to the total width of the new.
+% frame and its separation.
+% \end{description}
%
% \begin{macro}{\KFLTtightframe} \marg{contents}
% \begin{macrocode}
@@ -2817,9 +3099,11 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% A user-redefinable macro and length to loosely frame the contents.
%
-% \cs{KFLTlooseframe} may be redefined to a macro which frames its contents.
-% \cs{KFLTlooseframewidth} should be redefine to the total width of the new
-% frame and its separation.
+% \begin{description}
+% \item[\cs{KFLTlooseframe}:] Redefine to a macro which frames its contents.
+% \item[\cs{KFLTlooseframewidth}:] Redefine to the total width of the new
+% frame and its separation.
+% \end{description}
%
% \begin{macrocode}
\newcommand{\KFLTlooseframe}[1]{%
@@ -2877,11 +3161,61 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% \subsection{A graphics image from a file}
%
+% \DescribeLength{\KFLT@testwidth} Used to find the width of a graphics image.
+% \begin{macrocode}
+\newlength{\KFLT@testwidth}
+% \end{macrocode}
+%
+%
+% \begin{macro}{\KFLT@includegraphics} \oarg{keys} \marg{file name}
+%
+% Issue a warning if the image will be too wide, then display the image.
+% \begin{macrocode}
+\newcommand*{\KFLT@includegraphics}[2][]{%
+% \end{macrocode}
+%
+% Find the width of the image:
+% \begin{macrocode}
+ \settowidth{\KFLT@testwidth}{\includegraphics[#1]{#2}}%
+% \end{macrocode}
+%
+% Avoid rounding errors when using the \optn{lw} option,
+% and also avoid the exact line width in case images are side-by-side.
+%
+% If close to \cs{linewidth}, use slightly less than the \cs{linewidth}:
+% \changes{v2.06}{2021/06/25}{Clip if close to \cs{linewidth}.}
+% \begin{macrocode}
+ \ifboolexpr{%
+ test {\ifdimgreater{\KFLT@testwidth}{\linewidth-.01pt}} and
+ test {\ifdimless{\KFLT@testwidth}{\linewidth+1pt}}
+ }%
+ {\setlength{\KFLT@testwidth}{\linewidth-.01pt}}%
+ {}%
+% \end{macrocode}
+%
+%
+% Issue a warning if wider than the \cs{linewidth}:
+% \changes{v2.06}{2021/06/25}{Warn if image too wide.}
+% \begin{macrocode}
+ \ifdimgreater{\KFLT@testwidth}{\linewidth}{%
+ \PackageWarning{keyfloat}{The image is wider than the line width}%
+ }{}%
+% \end{macrocode}
+%
+% Display the image:
+% \begin{macrocode}
+ \includegraphics[#1]{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
% \begin{macro}{\KFLT@onefigureimage} \marg{filename}
%
% Create an image with size, frame, and turn.
%
% \changes{v2.00}{2019/03/12}{Filename in arg instead of \cs{KFLT@i}.}
+% \changes{v2.06}{2021/06/25}{Added \optn{kar}.}
% \begin{macrocode}
\NewDocumentCommand{\KFLT@onefigureimage}{m}%
{%
@@ -2906,16 +3240,22 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% Width and height are both given:
% \begin{macrocode}
{% w and h
- \includegraphics%
- [scale=\KFLT@s,%
- width=\KFLT@imagewidth,height=\KFLT@h]{#1}%
+ \KFLT@includegraphics[%
+ scale=\KFLT@s,%
+ width=\KFLT@imagewidth,%
+ height=\KFLT@h,%
+ \KFLT@keepaspectratio,%
+ ]{#1}%
}% w and h
% \end{macrocode}
% Only width:
% \begin{macrocode}
{% only w
- \includegraphics%
- [scale=\KFLT@s,width=\KFLT@imagewidth]{#1}%
+ \KFLT@includegraphics[%
+ scale=\KFLT@s,%
+ width=\KFLT@imagewidth,%
+ \KFLT@keepaspectratio,%
+ ]{#1}%
}% only w
}% width is given
% \end{macrocode}
@@ -2926,15 +3266,44 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{macrocode}
% |h| was given:
% \begin{macrocode}
- {\includegraphics[scale=\KFLT@s,height=\KFLT@h]{#1}}%
+ {%
+ \KFLT@includegraphics[%
+ scale=\KFLT@s,%
+ height=\KFLT@h,%
+ \KFLT@keepaspectratio,%
+ ]{#1}%
+ }%
% \end{macrocode}
% If none were given, use the image's natural size:
% \begin{macrocode}
- {\includegraphics[scale=\KFLT@s]{#1}}%
+ {%
+ \KFLT@includegraphics[%
+ scale=\KFLT@s,%
+ \KFLT@keepaspectratio,%
+ ]{#1}%
+ }%
}% width is not given
}% not linewidth
{% linewidth given
- \includegraphics[scale=\KFLT@s,width=\KFLT@imagewidth]{#1}%
+% \end{macrocode}
+% \changes{v2.06}{2021/06/25}{Fix: \optn{lw} with \optn{h}.}
+% \begin{macrocode}
+ \ifdimgreater{\KFLT@h}{0pt}%
+ {% lw and h given
+ \KFLT@includegraphics[%
+ scale=\KFLT@s,%
+ width=\KFLT@imagewidth,%
+ height=\KFLT@h,%
+ \KFLT@keepaspectratio,%
+ ]{#1}%
+ }%
+ {% lw w/o h
+ \KFLT@includegraphics[%
+ scale=\KFLT@s,%
+ width=\KFLT@imagewidth,%
+ \KFLT@keepaspectratio,%
+ ]{#1}%
+ }%
}%
\end{lrbox}%
\unskip%
@@ -3164,22 +3533,34 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
{\csuse{KFLT@#1type}}{\KFLT@sc}%
}% non-empty cstar and sc
% \end{macrocode}
+%
+% In the following,
+% the test for an empty caption is because the \pkg{caption} package does not
+% detect an empty caption if it is given as a macro.
+%
% |cstar| was given, so create an unnumbered caption:
+% \changes{v2.06}{2019/06/29}{Fix for empty caption.}
% \begin{macrocode}
- \KFLT@docaption*{\csuse{KFLT@#1c}}{#1}%
+ \ifcsempty{KFLT@#1c}%
+ {\KFLT@docaption*{}{#1}}%
+ {\KFLT@docaption*{\csuse{KFLT@#1c}}{#1}}%
}%
}% starred caption
% \end{macrocode}
% Unstarred caption |c| was given, so number this float:
+% \changes{v2.06}{2019/06/29}{Fix for empty caption.}
% \begin{macrocode}
{% unstarred caption
\ifcsempty{KFLT@#1sc}%
{% no short cap
- \KFLT@docaption{\csuse{KFLT@#1c}}{#1}%
+ \ifcsempty{KFLT@#1c}%
+ {\KFLT@docaption{}{#1}}%
+ {\KFLT@docaption{\csuse{KFLT@#1c}}{#1}}%
}% no short cap
{% short cap
- \KFLT@docaption[\csuse{KFLT@#1sc}]%
- {\csuse{KFLT@#1c}}{#1}%
+ \ifcsempty{KFLT@#1c}%
+ {\KFLT@docaption[\csuse{KFLT@#1sc}]{}{#1}}%
+ {\KFLT@docaption[\csuse{KFLT@#1sc}]{\csuse{KFLT@#1c}}{#1}}%
}% short cap
% \end{macrocode}
% Optional label:
@@ -3196,6 +3577,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \subsection{Defaults for a new float}
% \begin{macro}{\KFLT@defaults} Defaults all settings before reading the keys.
+% \changes{v2.06}{2021/06/25}{Added \optn{kar}.}
% \begin{macrocode}
\newcommand*{\KFLT@defaults}{%
\setboolean{KFLT@cont}{false}%
@@ -3218,6 +3600,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
\renewcommand{\KFLT@lw}{}%
\setlength{\KFLT@w}{0pt}%
\setlength{\KFLT@h}{0pt}%
+ \renewcommand{\KFLT@keepaspectratio}{}%
\renewcommand{\KFLT@s}{1}%
\renewcommand{\KFLT@r}{0}%
\setboolean{KFLT@f}{false}%
@@ -3535,14 +3918,38 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{environment}
+% \begin{macro}{\KFLT@sharedkeys}
+% Key/values to apply to each object in this group,
+% such as a \env{keyfloats} or \env{keysubfigs}.
+% \changes{v2.06}{2021/06/25}{Added shared keys.}
+% \begin{macrocode}
+\newcommand*{\KFLT@sharedkeys}{}
+% \end{macrocode}
+% \end{macro}
+
% \begin{macro}{\KFLT@boxkeys} \marg{keys} \marg{float type}
%
% Default the options, adjust for a table, then parse the keys:
+% \changes{v2.06}{2021/06/25}{Added shared keys.}
% \begin{macrocode}
\NewDocumentCommand{\KFLT@boxkeys}{+m m}
{%
+% \end{macrocode}
+% Set the key defaults:
+% \begin{macrocode}
\KFLT@defaults%
+% \end{macrocode}
+% Remember the float type:
+% \begin{macrocode}
\renewcommand{\KFLT@type}{#2}%
+% \end{macrocode}
+% Set the shared keys. Expansion seems to be required for \pkg{xkeyval}.
+% \begin{macrocode}
+ \edef\next{\noexpand\setkeys{KFLT@keys}{\KFLT@sharedkeys}}%
+ \next%
+% \end{macrocode}
+% Set the float-specific keys, which might overright the group's keys:
+% \begin{macrocode}
\setkeys{KFLT@keys}{#1}%
}
% \end{macrocode}
@@ -3728,7 +4135,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% Place the caption above the contents depending on \pkg{caption} \optn{position} option:
% \changes{v2.01}{2019/09/11}{Fix: Positions with \brand{Komascript}.}
% \begin{macrocode}
- \caption@iftop{\booltrue{KFLT@captionistop}}{\boolfalse{KFLT@captionistop}}%
+ \caption@iftop%
+ {\booltrue{KFLT@captionistop}}%
+ {\boolfalse{KFLT@captionistop}}%
\ifbool{KFLT@captionistop}{\KFLT@caption{}}{}%
% \end{macrocode}
% Typeset the contents:
@@ -4182,9 +4591,11 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
(Not in outer par mode.)%
}%
{%
- The subcaption package do not support nested environments,\MessageBreak
+ The subcaption package do not support nested environments,%
+ \MessageBreak
so the keyfloat package cannot place a\MessageBreak
- keysubfigs or keysubtabs environment inside another,\MessageBreak
+ keysubfigs or keysubtabs environment inside another,%
+ \MessageBreak
or inside a keyfloats.%
}%
}%
@@ -4201,16 +4612,19 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{macro}
-% \begin{environment}{KFLT@LWR@hook@keyfloatsminipage} Modified by \pkg{lwarp}.
+% \begin{environment}{KFLT@LWR@hook@keyfloatsminipage} \marg{contents}
+%
+% Modified by \pkg{lwarp}.
+% \changes{v2.06}{2021/06/25}{Added vertical alignment.}
% \begin{macrocode}
\newenvironment*{KFLT@LWR@hook@keyfloatsminipage}[1]
- {\noindent\minipage{#1}}
- {\endminipage}%
+ {\noindent\minipage[\KFLT@va]{#1}}
+ {\endminipage}
% \end{macrocode}
% \end{environment}
-% \begin{environment}{keyfloats} * \oarg{loc} \marg{num columns}
+% \begin{environment}{keyfloats} * \oarg{loc} \marg{num columns} \oarg{shared keys/values}
%
% User-level macro to create rows of figures/tables.
% Wrapping occurs after the number of specified columns.
@@ -4230,7 +4644,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \changes{v0.15}{2017/05/12}{Adjustments for \protect\env{keywrap}.}
%
% \begin{macrocode}
-\NewDocumentEnvironment{keyfloats}{s O{tbp} m}
+\NewDocumentEnvironment{keyfloats}{s O{tbp} m O{}}
{%
\KFLT@envignorespaces%
% \end{macrocode}
@@ -4242,6 +4656,12 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \begin{macrocode}
\addtocounter{KFLT@keyfloatdepth}{1}%
% \end{macrocode}
+% Nest the group's keys.
+% \changes{v2.06}{2021/06/25}{Added shared keys.}
+% \begin{macrocode}
+ \edef\KFLT@outersharedkeys{\KFLT@sharedkeys}%
+ \edef\KFLT@sharedkeys{\KFLT@sharedkeys,#4}%
+% \end{macrocode}
% If [H], nested, subfloats, or keywrap, use a minipage instead of a float:
% \begin{macrocode}
\ifboolexpr{%
@@ -4263,6 +4683,16 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
bool {KFLT@inkeysubfloats}
}%
{%
+% \end{macrocode}
+% Use the keys from the outer container.
+% Expansion required for \pkg{xkeyval}.
+% \changes{v2.06}{2021/06/25}{Added shared keys.}
+% \begin{macrocode}
+ \edef\next{\noexpand\setkeys{KFLT@keys}{\KFLT@outersharedkeys}}%
+ \next%
+% \end{macrocode}
+% Create the containing minipage:
+% \begin{macrocode}
\KFLT@LWR@hook@keyfloatsminipage{\KFLT@rowboxwidth}%
}%
{%
@@ -4569,7 +4999,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% Place the caption above the contents depending on \pkg{caption} \optn{position} option:
% \changes{v2.01}{2019/09/11}{Fix: Positions with \brand{Komascript}.}
% \begin{macrocode}
- \caption@iftop{\booltrue{KFLT@subcaptionistop}}{\boolfalse{KFLT@subcaptionistop}}%
+ \caption@iftop%
+ {\booltrue{KFLT@subcaptionistop}}%
+ {\boolfalse{KFLT@subcaptionistop}}%
\ifbool{KFLT@subcaptionistop}{\KFLT@caption{subgrp}}{}%
% \end{macrocode}
% Not yet started a row of subfloats.
@@ -4661,12 +5093,14 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{macrocode}
% \end{macro}
-% \begin{environment}{KFLT@keysubfloats} \marg{star?} \marg{loc} \marg{float type} \marg{numcols} \marg{\keyvalsarg}
+% \begin{environment}{KFLT@keysubfloats} \marg{1: star?}
+% \marg{2: loc} \marg{3: float type} \marg{4: numcols}
+% \marg{5: \keyvalsarg} \marg{6: shared keys/values}
%
% A group of subfigures typeset in rows.
%
% \begin{macrocode}
-\NewDocumentEnvironment{KFLT@keysubfloats}{m m m m +m}
+\NewDocumentEnvironment{KFLT@keysubfloats}{m m m m +m m}
{%
% \end{macrocode}
% Error if trying to nest environments:
@@ -4681,6 +5115,11 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \begin{macrocode}
\KFLT@subgrpdefaults%
% \end{macrocode}
+% Nest the group's keys:
+% \changes{v2.06}{2021/06/25}{Added shared keys.}
+% \begin{macrocode}
+ \edef\KFLT@sharedkeys{\KFLT@sharedkeys,#6}%
+% \end{macrocode}
% Default to figure float type:
% \begin{macrocode}
\renewcommand{\KFLT@subgrptype}{#3}%
@@ -4699,54 +5138,49 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{environment}
-% \begin{environment}{keysubfloats} * \oarg{loc} \marg{float type} \marg{numcols} \marg{\keyvalsarg}
+% \begin{environment}{keysubfloats} * \oarg{2: loc} \marg{3: float type}
+% \marg{4: numcols} \marg{5: \keyvalsarg} \oarg{6: shared \keyvalsarg}
%
% A group of subfloats typeset in rows.
%
+% \changes{v2.06}{2021/06/25}{Added shared keys.}
% \begin{macrocode}
-\NewDocumentEnvironment{keysubfloats}{s O{tbp} m m +m}
-{%
- \KFLT@keysubfloats{#1}{#2}{#3}{#4}{#5}%
-}{%
- \endKFLT@keysubfloats%
-}
+\NewDocumentEnvironment{keysubfloats}{s O{tbp} m m +m O{}}
+ {\KFLT@keysubfloats{#1}{#2}{#3}{#4}{#5}{#6}}
+ {\endKFLT@keysubfloats}
% \end{macrocode}
% \end{environment}
-% \begin{environment}{keysubfigs} * \oarg{loc} \marg{numcols} \marg{\keyvalsarg}
+% \begin{environment}{keysubfigs} * \oarg{2: loc} \marg{3: numcols}
+% \marg{4: \keyvalsarg} \oarg{5: shared \keyvalsarg}
%
% A group of subfigures typeset in rows.
%
+% \changes{v2.06}{2021/06/25}{Added shared keys.}
% \begin{macrocode}
-\NewDocumentEnvironment{keysubfigs}{s O{tbp} m +m}
-{%
- \KFLT@keysubfloats{#1}{#2}{figure}{#3}{#4}%
-}{%
- \endKFLT@keysubfloats%
-}
+\NewDocumentEnvironment{keysubfigs}{s O{tbp} m +m O{}}
+ {\KFLT@keysubfloats{#1}{#2}{figure}{#3}{#4}{#5}}
+ {\endKFLT@keysubfloats}
% \end{macrocode}
% \end{environment}
-% \begin{environment}{keysubtabs} * \oarg{loc} \marg{numcols} \marg{\keyvalsarg}
+% \begin{environment}{keysubtabs} * \oarg{2: loc} \marg{3: numcols}
+% \marg{4: \keyvalsarg} \oarg{5: shared \keyvalsarg}
%
% A group of subtables typeset in rows.
+% \changes{v2.06}{2021/06/25}{Added shared keys.}
% \begin{macrocode}
-\NewDocumentEnvironment{keysubtabs}{s O{tbp} m +m}
-{%
- \KFLT@keysubfloats{#1}{#2}{table}{#3}{#4}%
-}{%
- \endKFLT@keysubfloats%
-}
+\NewDocumentEnvironment{keysubtabs}{s O{tbp} m +m O{}}
+ {\KFLT@keysubfloats{#1}{#2}{table}{#3}{#4}{#5}}
+ {\endKFLT@keysubfloats}
% \end{macrocode}
% \end{environment}
%
%
%
%
-%
-%
% \subsection{Margin floats}
%
% \begin{environment}{KFLT@marginfloat} \oarg{offset} \marg{type}
@@ -4876,6 +5310,21 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{environment}
%
%
+% \section{\pkg{keyfloat} package maintenance}
+%
+% To compile the \pkg{keyfloat} documentation from \filenm{keyfloat.dtx} and
+% \filenm{keyfloat.ins}:
+%
+% \begin{sourceverb}
+% pdflatex keyfloat.ins
+% pdflatex keyfloat.dtx
+% pdflatex keyfloat.dtx
+% pdflatex keyfloat.dtx
+% makeindex -s gglo.ist -o keyfloat.gls keyfloat.glo
+% splitindex keyfloat.idx -- -s gind.ist
+% pdflatex keyfloat.dtx
+% pdflatex keyfloat.dtx
+% \end{sourceverb}
%
%
% \iffalse
@@ -4890,7 +5339,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% \renewcommand{\partname}{}
% \renewcommand{\thepart}{}
-% \part{Change History and Index}
+% ^^A \part{Change History and Index}
%
%
% \Finale