texlive[59759] Master/texmf-dist: keyfloat (29jun21)
commits+karl at tug.org
commits+karl at tug.org
Tue Jun 29 21:55:06 CEST 2021
Revision: 59759
http://tug.org/svn/texlive?view=revision&revision=59759
Author: karl
Date: 2021-06-29 21:55:06 +0200 (Tue, 29 Jun 2021)
Log Message:
-----------
keyfloat (29jun21)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/latex/keyfloat/README.txt
trunk/Master/texmf-dist/doc/latex/keyfloat/keyfloat.pdf
trunk/Master/texmf-dist/source/latex/keyfloat/keyfloat.dtx
trunk/Master/texmf-dist/tex/latex/keyfloat/keyfloat.sty
Modified: trunk/Master/texmf-dist/doc/latex/keyfloat/README.txt
===================================================================
--- trunk/Master/texmf-dist/doc/latex/keyfloat/README.txt 2021-06-29 19:54:30 UTC (rev 59758)
+++ trunk/Master/texmf-dist/doc/latex/keyfloat/README.txt 2021-06-29 19:55:06 UTC (rev 59759)
@@ -1,7 +1,7 @@
The LaTeX keyfloat package
Provides a key/value interface for generating floats.
-v2.05
+v2.06
Copyright 2016-2021 Brian Dunn — www.BDTechConcepts.com
LaTeX Project Public License, version 1.3
Modified: trunk/Master/texmf-dist/doc/latex/keyfloat/keyfloat.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/source/latex/keyfloat/keyfloat.dtx
===================================================================
--- trunk/Master/texmf-dist/source/latex/keyfloat/keyfloat.dtx 2021-06-29 19:54:30 UTC (rev 59758)
+++ trunk/Master/texmf-dist/source/latex/keyfloat/keyfloat.dtx 2021-06-29 19:55:06 UTC (rev 59759)
@@ -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 @@
+\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 @@
\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 @@
+\setlength{\marginparsep}{1em}
+\setlength{\marginparpush}{.7ex}
+\setlength{\IndexMin}{40ex}
+
\setcounter{IndexColumns}{2}
\DisableCrossrefs
@@ -317,7 +349,7 @@
%<*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 @@
% \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 @@
% 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 @@
% \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,12 +630,39 @@
% 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
%
% \section{Using the \pkg{keyfloat} package}
@@ -710,25 +772,29 @@
% \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 @@
%
% \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 @@
% \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 @@
% \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 @@
% 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 @@
% 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,7 +973,7 @@
% 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
@@ -911,7 +980,7 @@
% 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 @@
%
%
% \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 @@
% 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 @@
% \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 @@
%
% 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 @@
% 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 @@
% }{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 @@
%
% \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 @@
% 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 @@
% 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 @@
% \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,15 +1267,17 @@
% \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''.]
% {Unnumbered float with a \acro{LOF} entry}
@@ -1224,6 +1301,8 @@
% }{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 @@
% }{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,22 +1333,22 @@
%
% \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}
@@ -1274,42 +1355,75 @@
% \end{dtxexample}
%
%
+% The \env{keyfloats} environment takes an argument for the number of columns.
+% 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, \Crefrange{fig:thirdinarow}{fig:sixthinarow} are in an
+% 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.
%
-% The \env{keyfloats} environment takes an argument for the number of columns.
-% Additional floats 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.
-%
% 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 @@
% 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,7 +1453,7 @@
% 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
@@ -1346,22 +1460,37 @@
% 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}
% \keytab{c={First subtable},l=fig:firstsubtab}{\testtable}
@@ -1375,6 +1504,9 @@
%
% \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 @@
%
% \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 @@
% \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 @@
%
% 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 @@
% \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 @@
% 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 @@
% 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 @@
% 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 @@
% \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 @@
% \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 @@
%
%
% \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 @@
%
% \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,10 +1966,117 @@
% \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 at index
+% code line of the
+% \fi
+% definition.
+% ^^A ; numbers in roman refer to the
+% ^^A \ifcodeline at 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}
% ^^A *source
%
@@ -2234,6 +2488,7 @@
\providecommand{\tdauthorright}{}
% \end{macrocode}
%
+%
% \DescribeKey[main]{t} Additional text, justified alignment.
% \begin{macrocode}
\define at key{KFLT at keys}{t}{%
@@ -2242,6 +2497,7 @@
}
% \end{macrocode}
%
+%
% \DescribeKey[main]{tc} Additional text, centered alignment.
% \begin{macrocode}
\define at key{KFLT at keys}{tc}{%
@@ -2250,6 +2506,7 @@
}
% \end{macrocode}
%
+%
% \DescribeKey[main]{tr} Additional text, aligned to the right.
% \begin{macrocode}
\define at key{KFLT at keys}{tr}{%
@@ -2258,6 +2515,7 @@
}
% \end{macrocode}
%
+%
% \DescribeKey[main]{tl} Additional text, aligned to the left.
% \begin{macrocode}
\define at key{KFLT at keys}{tl}{%
@@ -2267,7 +2525,6 @@
% \end{macrocode}
%
%
-%
% \DescribeKey[main]{lw} Fraction of \cs{linewidth}
% \begin{macrocode}
\define at key{KFLT at keys}{lw}{%
@@ -2282,6 +2539,7 @@
% \end{macrocode}
% \end{macro}
%
+%
% \DescribeKey[main]{w} Fixed width
% \begin{macrocode}
\define at key{KFLT at keys}{w}{%
@@ -2296,6 +2554,7 @@
% \end{macrocode}
% \end{macro}
%
+%
% \DescribeKey[main]{h} Fixed height
% \begin{macrocode}
\define at key{KFLT at keys}{h}{\setlength{\KFLT at h}{#1}}
@@ -2307,6 +2566,23 @@
% \end{macrocode}
% \end{macro}
%
+%
+% \DescribeKey[main]{kar} Keep aspect ratio
+% \changes{v2.06}{2021/06/25}{Added \optn{kar}.}
+% \begin{macrocode}
+\define at key{KFLT at keys}{kar}[false]{%
+ \renewcommand{\KFLT at keepaspectratio}{keepaspectratio}%
+}
+% \end{macrocode}
+%
+% \begin{macro}{\KFLT at keepaspectratio} Stores ``\optn{keepaspectratio}'' if set.
+% \changes{v2.06}{2021/06/25}{Added \optn{kar}.}
+% \begin{macrocode}
+\newcommand{\KFLT at keepaspectratio}{}
+% \end{macrocode}
+% \end{macro}
+%
+%
% \DescribeKey[main]{s} Scale
% \begin{macrocode}
\define at key{KFLT at keys}{s}{\renewcommand{\KFLT at s}{#1}}
@@ -2318,6 +2594,7 @@
% \end{macrocode}
% \end{macro}
%
+%
% \DescribeKey[main]{r} Angle. 90 is counter-clockwise 90 degrees.
% \begin{macrocode}
\define at key{KFLT at keys}{r}{\renewcommand{\KFLT at r}{#1}}
@@ -2329,6 +2606,7 @@
% \end{macrocode}
% \end{macro}
%
+%
% \DescribeKey[main]{f} Frame the image with \cs{KFLTlooseframe}.
% \begin{macrocode}
\define at key{KFLT at keys}{f}[true]{\setboolean{KFLT at f}{#1}}
@@ -2338,7 +2616,8 @@
% \begin{macrocode}
\newboolean{KFLT at 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 @@
% \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 @@
%
% 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 @@
%
% 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 @@
%
% \subsection{A graphics image from a file}
%
+% \DescribeLength{\KFLT at testwidth} Used to find the width of a graphics image.
+% \begin{macrocode}
+\newlength{\KFLT at testwidth}
+% \end{macrocode}
+%
+%
+% \begin{macro}{\KFLT at includegraphics} \oarg{keys} \marg{file name}
+%
+% Issue a warning if the image will be too wide, then display the image.
+% \begin{macrocode}
+\newcommand*{\KFLT at includegraphics}[2][]{%
+% \end{macrocode}
+%
+% Find the width of the image:
+% \begin{macrocode}
+ \settowidth{\KFLT at 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 at testwidth}{\linewidth-.01pt}} and
+ test {\ifdimless{\KFLT at testwidth}{\linewidth+1pt}}
+ }%
+ {\setlength{\KFLT at 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 at 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 at onefigureimage} \marg{filename}
%
% Create an image with size, frame, and turn.
%
% \changes{v2.00}{2019/03/12}{Filename in arg instead of \cs{KFLT at i}.}
+% \changes{v2.06}{2021/06/25}{Added \optn{kar}.}
% \begin{macrocode}
\NewDocumentCommand{\KFLT at onefigureimage}{m}%
{%
@@ -2906,16 +3240,22 @@
% Width and height are both given:
% \begin{macrocode}
{% w and h
- \includegraphics%
- [scale=\KFLT at s,%
- width=\KFLT at imagewidth,height=\KFLT at h]{#1}%
+ \KFLT at includegraphics[%
+ scale=\KFLT at s,%
+ width=\KFLT at imagewidth,%
+ height=\KFLT at h,%
+ \KFLT at keepaspectratio,%
+ ]{#1}%
}% w and h
% \end{macrocode}
% Only width:
% \begin{macrocode}
{% only w
- \includegraphics%
- [scale=\KFLT at s,width=\KFLT at imagewidth]{#1}%
+ \KFLT at includegraphics[%
+ scale=\KFLT at s,%
+ width=\KFLT at imagewidth,%
+ \KFLT at keepaspectratio,%
+ ]{#1}%
}% only w
}% width is given
% \end{macrocode}
@@ -2926,15 +3266,44 @@
% \end{macrocode}
% |h| was given:
% \begin{macrocode}
- {\includegraphics[scale=\KFLT at s,height=\KFLT at h]{#1}}%
+ {%
+ \KFLT at includegraphics[%
+ scale=\KFLT at s,%
+ height=\KFLT at h,%
+ \KFLT at keepaspectratio,%
+ ]{#1}%
+ }%
% \end{macrocode}
% If none were given, use the image's natural size:
% \begin{macrocode}
- {\includegraphics[scale=\KFLT at s]{#1}}%
+ {%
+ \KFLT at includegraphics[%
+ scale=\KFLT at s,%
+ \KFLT at keepaspectratio,%
+ ]{#1}%
+ }%
}% width is not given
}% not linewidth
{% linewidth given
- \includegraphics[scale=\KFLT at s,width=\KFLT at imagewidth]{#1}%
+% \end{macrocode}
+% \changes{v2.06}{2021/06/25}{Fix: \optn{lw} with \optn{h}.}
+% \begin{macrocode}
+ \ifdimgreater{\KFLT at h}{0pt}%
+ {% lw and h given
+ \KFLT at includegraphics[%
+ scale=\KFLT at s,%
+ width=\KFLT at imagewidth,%
+ height=\KFLT at h,%
+ \KFLT at keepaspectratio,%
+ ]{#1}%
+ }%
+ {% lw w/o h
+ \KFLT at includegraphics[%
+ scale=\KFLT at s,%
+ width=\KFLT at imagewidth,%
+ \KFLT at keepaspectratio,%
+ ]{#1}%
+ }%
}%
\end{lrbox}%
\unskip%
@@ -3164,22 +3533,34 @@
{\csuse{KFLT@#1type}}{\KFLT at 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 at docaption*{\csuse{KFLT@#1c}}{#1}%
+ \ifcsempty{KFLT@#1c}%
+ {\KFLT at docaption*{}{#1}}%
+ {\KFLT at 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 at docaption{\csuse{KFLT@#1c}}{#1}%
+ \ifcsempty{KFLT@#1c}%
+ {\KFLT at docaption{}{#1}}%
+ {\KFLT at docaption{\csuse{KFLT@#1c}}{#1}}%
}% no short cap
{% short cap
- \KFLT at docaption[\csuse{KFLT@#1sc}]%
- {\csuse{KFLT@#1c}}{#1}%
+ \ifcsempty{KFLT@#1c}%
+ {\KFLT at docaption[\csuse{KFLT@#1sc}]{}{#1}}%
+ {\KFLT at docaption[\csuse{KFLT@#1sc}]{\csuse{KFLT@#1c}}{#1}}%
}% short cap
% \end{macrocode}
% Optional label:
@@ -3196,6 +3577,7 @@
% \subsection{Defaults for a new float}
% \begin{macro}{\KFLT at defaults} Defaults all settings before reading the keys.
+% \changes{v2.06}{2021/06/25}{Added \optn{kar}.}
% \begin{macrocode}
\newcommand*{\KFLT at defaults}{%
\setboolean{KFLT at cont}{false}%
@@ -3218,6 +3600,7 @@
\renewcommand{\KFLT at lw}{}%
\setlength{\KFLT at w}{0pt}%
\setlength{\KFLT at h}{0pt}%
+ \renewcommand{\KFLT at keepaspectratio}{}%
\renewcommand{\KFLT at s}{1}%
\renewcommand{\KFLT at r}{0}%
\setboolean{KFLT at f}{false}%
@@ -3535,14 +3918,38 @@
% \end{environment}
+% \begin{macro}{\KFLT at 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 at sharedkeys}{}
+% \end{macrocode}
+% \end{macro}
+
% \begin{macro}{\KFLT at 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 at boxkeys}{+m m}
{%
+% \end{macrocode}
+% Set the key defaults:
+% \begin{macrocode}
\KFLT at defaults%
+% \end{macrocode}
+% Remember the float type:
+% \begin{macrocode}
\renewcommand{\KFLT at type}{#2}%
+% \end{macrocode}
+% Set the shared keys. Expansion seems to be required for \pkg{xkeyval}.
+% \begin{macrocode}
+ \edef\next{\noexpand\setkeys{KFLT at keys}{\KFLT at sharedkeys}}%
+ \next%
+% \end{macrocode}
+% Set the float-specific keys, which might overright the group's keys:
+% \begin{macrocode}
\setkeys{KFLT at keys}{#1}%
}
% \end{macrocode}
@@ -3728,7 +4135,9 @@
% 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 at iftop{\booltrue{KFLT at captionistop}}{\boolfalse{KFLT at captionistop}}%
+ \caption at iftop%
+ {\booltrue{KFLT at captionistop}}%
+ {\boolfalse{KFLT at captionistop}}%
\ifbool{KFLT at captionistop}{\KFLT at caption{}}{}%
% \end{macrocode}
% Typeset the contents:
@@ -4182,9 +4591,11 @@
(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 @@
% \end{macro}
-% \begin{environment}{KFLT at LWR@hook at keyfloatsminipage} Modified by \pkg{lwarp}.
+% \begin{environment}{KFLT at LWR@hook at keyfloatsminipage} \marg{contents}
+%
+% Modified by \pkg{lwarp}.
+% \changes{v2.06}{2021/06/25}{Added vertical alignment.}
% \begin{macrocode}
\newenvironment*{KFLT at LWR@hook at keyfloatsminipage}[1]
- {\noindent\minipage{#1}}
- {\endminipage}%
+ {\noindent\minipage[\KFLT at 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 @@
% \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 at envignorespaces%
% \end{macrocode}
@@ -4242,6 +4656,12 @@
% \begin{macrocode}
\addtocounter{KFLT at keyfloatdepth}{1}%
% \end{macrocode}
+% Nest the group's keys.
+% \changes{v2.06}{2021/06/25}{Added shared keys.}
+% \begin{macrocode}
+ \edef\KFLT at outersharedkeys{\KFLT at sharedkeys}%
+ \edef\KFLT at sharedkeys{\KFLT at sharedkeys,#4}%
+% \end{macrocode}
% If [H], nested, subfloats, or keywrap, use a minipage instead of a float:
% \begin{macrocode}
\ifboolexpr{%
@@ -4263,6 +4683,16 @@
bool {KFLT at 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 at keys}{\KFLT at outersharedkeys}}%
+ \next%
+% \end{macrocode}
+% Create the containing minipage:
+% \begin{macrocode}
\KFLT at LWR@hook at keyfloatsminipage{\KFLT at rowboxwidth}%
}%
{%
@@ -4569,7 +4999,9 @@
% 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 at iftop{\booltrue{KFLT at subcaptionistop}}{\boolfalse{KFLT at subcaptionistop}}%
+ \caption at iftop%
+ {\booltrue{KFLT at subcaptionistop}}%
+ {\boolfalse{KFLT at subcaptionistop}}%
\ifbool{KFLT at subcaptionistop}{\KFLT at caption{subgrp}}{}%
% \end{macrocode}
% Not yet started a row of subfloats.
@@ -4661,12 +5093,14 @@
% \end{macrocode}
% \end{macro}
-% \begin{environment}{KFLT at keysubfloats} \marg{star?} \marg{loc} \marg{float type} \marg{numcols} \marg{\keyvalsarg}
+% \begin{environment}{KFLT at 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 at keysubfloats}{m m m m +m}
+\NewDocumentEnvironment{KFLT at keysubfloats}{m m m m +m m}
{%
% \end{macrocode}
% Error if trying to nest environments:
@@ -4681,6 +5115,11 @@
% \begin{macrocode}
\KFLT at subgrpdefaults%
% \end{macrocode}
+% Nest the group's keys:
+% \changes{v2.06}{2021/06/25}{Added shared keys.}
+% \begin{macrocode}
+ \edef\KFLT at sharedkeys{\KFLT at sharedkeys,#6}%
+% \end{macrocode}
% Default to figure float type:
% \begin{macrocode}
\renewcommand{\KFLT at subgrptype}{#3}%
@@ -4699,46 +5138,43 @@
% \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 at keysubfloats{#1}{#2}{#3}{#4}{#5}%
-}{%
- \endKFLT at keysubfloats%
-}
+\NewDocumentEnvironment{keysubfloats}{s O{tbp} m m +m O{}}
+ {\KFLT at keysubfloats{#1}{#2}{#3}{#4}{#5}{#6}}
+ {\endKFLT at 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 at keysubfloats{#1}{#2}{figure}{#3}{#4}%
-}{%
- \endKFLT at keysubfloats%
-}
+\NewDocumentEnvironment{keysubfigs}{s O{tbp} m +m O{}}
+ {\KFLT at keysubfloats{#1}{#2}{figure}{#3}{#4}{#5}}
+ {\endKFLT at 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 at keysubfloats{#1}{#2}{table}{#3}{#4}%
-}{%
- \endKFLT at keysubfloats%
-}
+\NewDocumentEnvironment{keysubtabs}{s O{tbp} m +m O{}}
+ {\KFLT at keysubfloats{#1}{#2}{table}{#3}{#4}{#5}}
+ {\endKFLT at keysubfloats}
% \end{macrocode}
% \end{environment}
%
@@ -4745,8 +5181,6 @@
%
%
%
-%
-%
% \subsection{Margin floats}
%
% \begin{environment}{KFLT at marginfloat} \oarg{offset} \marg{type}
@@ -4876,8 +5310,23 @@
% \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
%</package>
% \fi
@@ -4890,7 +5339,7 @@
%
% \renewcommand{\partname}{}
% \renewcommand{\thepart}{}
-% \part{Change History and Index}
+% ^^A \part{Change History and Index}
%
%
% \Finale
Modified: trunk/Master/texmf-dist/tex/latex/keyfloat/keyfloat.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/keyfloat/keyfloat.sty 2021-06-29 19:54:30 UTC (rev 59758)
+++ trunk/Master/texmf-dist/tex/latex/keyfloat/keyfloat.sty 2021-06-29 19:55:06 UTC (rev 59759)
@@ -18,7 +18,7 @@
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{keyfloat}
- [2021/06/11 v2.05 Key/value interface for floats and subfloats.]
+ [2021/06/29 v2.06 Key/value interface for floats and subfloats.]
@@ -26,6 +26,7 @@
+
\@ifpackageloaded{tocdata}{
\@ifpackagelater{tocdata}{2019/03/21}{}{
\PackageError{keyfloat}
@@ -187,6 +188,10 @@
\newlength{\KFLT at w}
\define at key{KFLT at keys}{h}{\setlength{\KFLT at h}{#1}}
\newlength{\KFLT at h}
+\define at key{KFLT at keys}{kar}[false]{%
+ \renewcommand{\KFLT at keepaspectratio}{keepaspectratio}%
+}
+\newcommand{\KFLT at keepaspectratio}{}
\define at key{KFLT at keys}{s}{\renewcommand{\KFLT at s}{#1}}
\newcommand*{\KFLT at s}{1}
\define at key{KFLT at keys}{r}{\renewcommand{\KFLT at r}{#1}}
@@ -193,7 +198,6 @@
\newcommand*{\KFLT at r}{0}
\define at key{KFLT at keys}{f}[true]{\setboolean{KFLT at f}{#1}}
\newboolean{KFLT at f}
-
\define at key{KFLT at keys}{ft}[true]{\setboolean{KFLT at ft}{#1}}
\newboolean{KFLT at ft}
@@ -364,6 +368,20 @@
{}% no frame
}% not looseframe
}
+\newlength{\KFLT at testwidth}
+\newcommand*{\KFLT at includegraphics}[2][]{%
+ \settowidth{\KFLT at testwidth}{\includegraphics[#1]{#2}}%
+ \ifboolexpr{%
+ test {\ifdimgreater{\KFLT at testwidth}{\linewidth-.01pt}} and
+ test {\ifdimless{\KFLT at testwidth}{\linewidth+1pt}}
+ }%
+ {\setlength{\KFLT at testwidth}{\linewidth-.01pt}}%
+ {}%
+ \ifdimgreater{\KFLT at testwidth}{\linewidth}{%
+ \PackageWarning{keyfloat}{The image is wider than the line width}%
+ }{}%
+ \includegraphics[#1]{#2}%
+}
\NewDocumentCommand{\KFLT at onefigureimage}{m}%
{%
\begin{lrbox}{\KFLT at envbox}%
@@ -373,23 +391,55 @@
{% width is given
\ifdimgreater{\KFLT at h}{0pt}%
{% w and h
- \includegraphics%
- [scale=\KFLT at s,%
- width=\KFLT at imagewidth,height=\KFLT at h]{#1}%
+ \KFLT at includegraphics[%
+ scale=\KFLT at s,%
+ width=\KFLT at imagewidth,%
+ height=\KFLT at h,%
+ \KFLT at keepaspectratio,%
+ ]{#1}%
}% w and h
{% only w
- \includegraphics%
- [scale=\KFLT at s,width=\KFLT at imagewidth]{#1}%
+ \KFLT at includegraphics[%
+ scale=\KFLT at s,%
+ width=\KFLT at imagewidth,%
+ \KFLT at keepaspectratio,%
+ ]{#1}%
}% only w
}% width is given
{% width is not given
\ifdimgreater{\KFLT at h}{0pt}%
- {\includegraphics[scale=\KFLT at s,height=\KFLT at h]{#1}}%
- {\includegraphics[scale=\KFLT at s]{#1}}%
+ {%
+ \KFLT at includegraphics[%
+ scale=\KFLT at s,%
+ height=\KFLT at h,%
+ \KFLT at keepaspectratio,%
+ ]{#1}%
+ }%
+ {%
+ \KFLT at includegraphics[%
+ scale=\KFLT at s,%
+ \KFLT at keepaspectratio,%
+ ]{#1}%
+ }%
}% width is not given
}% not linewidth
{% linewidth given
- \includegraphics[scale=\KFLT at s,width=\KFLT at imagewidth]{#1}%
+ \ifdimgreater{\KFLT at h}{0pt}%
+ {% lw and h given
+ \KFLT at includegraphics[%
+ scale=\KFLT at s,%
+ width=\KFLT at imagewidth,%
+ height=\KFLT at h,%
+ \KFLT at keepaspectratio,%
+ ]{#1}%
+ }%
+ {% lw w/o h
+ \KFLT at includegraphics[%
+ scale=\KFLT at s,%
+ width=\KFLT at imagewidth,%
+ \KFLT at keepaspectratio,%
+ ]{#1}%
+ }%
}%
\end{lrbox}%
\unskip%
@@ -503,17 +553,22 @@
\addcontentsline{\csuse{ext@\KFLT at listtype}}%
{\csuse{KFLT@#1type}}{\KFLT at sc}%
}% non-empty cstar and sc
- \KFLT at docaption*{\csuse{KFLT@#1c}}{#1}%
+ \ifcsempty{KFLT@#1c}%
+ {\KFLT at docaption*{}{#1}}%
+ {\KFLT at docaption*{\csuse{KFLT@#1c}}{#1}}%
}%
}% starred caption
{% unstarred caption
\ifcsempty{KFLT@#1sc}%
{% no short cap
- \KFLT at docaption{\csuse{KFLT@#1c}}{#1}%
+ \ifcsempty{KFLT@#1c}%
+ {\KFLT at docaption{}{#1}}%
+ {\KFLT at docaption{\csuse{KFLT@#1c}}{#1}}%
}% no short cap
{% short cap
- \KFLT at docaption[\csuse{KFLT@#1sc}]%
- {\csuse{KFLT@#1c}}{#1}%
+ \ifcsempty{KFLT@#1c}%
+ {\KFLT at docaption[\csuse{KFLT@#1sc}]{}{#1}}%
+ {\KFLT at docaption[\csuse{KFLT@#1sc}]{\csuse{KFLT@#1c}}{#1}}%
}% short cap
\ifcsempty{KFLT@#1l}%
{}%
@@ -543,6 +598,7 @@
\renewcommand{\KFLT at lw}{}%
\setlength{\KFLT at w}{0pt}%
\setlength{\KFLT at h}{0pt}%
+ \renewcommand{\KFLT at keepaspectratio}{}%
\renewcommand{\KFLT at s}{1}%
\renewcommand{\KFLT at r}{0}%
\setboolean{KFLT at f}{false}%
@@ -681,10 +737,14 @@
\par%
}% endkeyboxinner
+\newcommand*{\KFLT at sharedkeys}{}
+
\NewDocumentCommand{\KFLT at boxkeys}{+m m}
{%
\KFLT at defaults%
\renewcommand{\KFLT at type}{#2}%
+ \edef\next{\noexpand\setkeys{KFLT at keys}{\KFLT at sharedkeys}}%
+ \next%
\setkeys{KFLT at keys}{#1}%
}
@@ -756,7 +816,9 @@
}% not subfloat
\ifbool{KFLT at cont}{\ContinuedFloat}{}%
\KFLT at findwidths%
- \caption at iftop{\booltrue{KFLT at captionistop}}{\boolfalse{KFLT at captionistop}}%
+ \caption at iftop%
+ {\booltrue{KFLT at captionistop}}%
+ {\boolfalse{KFLT at captionistop}}%
\ifbool{KFLT at captionistop}{\KFLT at caption{}}{}%
\center\unskip%
}% boxouter
@@ -987,9 +1049,11 @@
(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.%
}%
}%
@@ -999,14 +1063,16 @@
\newcommand*{\KFLT at LWR@hook at keyfloats}{}%
\newenvironment*{KFLT at LWR@hook at keyfloatsminipage}[1]
- {\noindent\minipage{#1}}
- {\endminipage}%
+ {\noindent\minipage[\KFLT at va]{#1}}
+ {\endminipage}
-\NewDocumentEnvironment{keyfloats}{s O{tbp} m}
+\NewDocumentEnvironment{keyfloats}{s O{tbp} m O{}}
{%
\KFLT at envignorespaces%
\KFLT at LWR@hook at keyfloats%
\addtocounter{KFLT at keyfloatdepth}{1}%
+ \edef\KFLT at outersharedkeys{\KFLT at sharedkeys}%
+ \edef\KFLT at sharedkeys{\KFLT at sharedkeys,#4}%
\ifboolexpr{%
test {\ifstrequal{#2}{H}} or
test {\ifnumgreater{\value{KFLT at keyfloatdepth}}{1}} or
@@ -1019,6 +1085,8 @@
bool {KFLT at inkeysubfloats}
}%
{%
+ \edef\next{\noexpand\setkeys{KFLT at keys}{\KFLT at outersharedkeys}}%
+ \next%
\KFLT at LWR@hook at keyfloatsminipage{\KFLT at rowboxwidth}%
}%
{%
@@ -1168,7 +1236,9 @@
{\ContinuedFloat}%
{}%
\center\unskip%
- \caption at iftop{\booltrue{KFLT at subcaptionistop}}{\boolfalse{KFLT at subcaptionistop}}%
+ \caption at iftop%
+ {\booltrue{KFLT at subcaptionistop}}%
+ {\boolfalse{KFLT at subcaptionistop}}%
\ifbool{KFLT at subcaptionistop}{\KFLT at caption{subgrp}}{}%
\defcounter{KFLT at numcols}{#3}%
\defcounter{KFLT at thiscol}{0}%
@@ -1211,11 +1281,12 @@
\newcommand*{\KFLT at LWR@hook at keysubfloats}{}
-\NewDocumentEnvironment{KFLT at keysubfloats}{m m m m +m}
+\NewDocumentEnvironment{KFLT at keysubfloats}{m m m m +m m}
{%
\KFLT at nonest%
\KFLT at LWR@hook at keysubfloats%
\KFLT at subgrpdefaults%
+ \edef\KFLT at sharedkeys{\KFLT at sharedkeys,#6}%
\renewcommand{\KFLT at subgrptype}{#3}%
\KFLT at subfloats{#1}{#2}{#4}{#5}%
}% the start of the environment
@@ -1223,26 +1294,17 @@
\KFLT at endsubfloats{#1}{#2}%
}
-\NewDocumentEnvironment{keysubfloats}{s O{tbp} m m +m}
-{%
- \KFLT at keysubfloats{#1}{#2}{#3}{#4}{#5}%
-}{%
- \endKFLT at keysubfloats%
-}
+\NewDocumentEnvironment{keysubfloats}{s O{tbp} m m +m O{}}
+ {\KFLT at keysubfloats{#1}{#2}{#3}{#4}{#5}{#6}}
+ {\endKFLT at keysubfloats}
-\NewDocumentEnvironment{keysubfigs}{s O{tbp} m +m}
-{%
- \KFLT at keysubfloats{#1}{#2}{figure}{#3}{#4}%
-}{%
- \endKFLT at keysubfloats%
-}
+\NewDocumentEnvironment{keysubfigs}{s O{tbp} m +m O{}}
+ {\KFLT at keysubfloats{#1}{#2}{figure}{#3}{#4}{#5}}
+ {\endKFLT at keysubfloats}
-\NewDocumentEnvironment{keysubtabs}{s O{tbp} m +m}
-{%
- \KFLT at keysubfloats{#1}{#2}{table}{#3}{#4}%
-}{%
- \endKFLT at keysubfloats%
-}
+\NewDocumentEnvironment{keysubtabs}{s O{tbp} m +m O{}}
+ {\KFLT at keysubfloats{#1}{#2}{table}{#3}{#4}{#5}}
+ {\endKFLT at keysubfloats}
\newsavebox{\KFLT at marginfloatbox}
\NewDocumentEnvironment{KFLT at marginfloat}{O{-1.2ex} m}
More information about the tex-live-commits
mailing list.