summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/keyfloat
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-05-12 22:00:38 +0000
committerKarl Berry <karl@freefriends.org>2017-05-12 22:00:38 +0000
commit0f3f6bc2e482d3999fec92653eb1305308170254 (patch)
treefbe6f7fbe70c9c90d01c05ed481a1500c22d96e5 /Master/texmf-dist/source/latex/keyfloat
parent778ba561199969808c132ea6968f1202ec315e4c (diff)
keyfloat (12may17)
git-svn-id: svn://tug.org/texlive/trunk@44306 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/keyfloat')
-rw-r--r--Master/texmf-dist/source/latex/keyfloat/keyfloat.dtx241
1 files changed, 207 insertions, 34 deletions
diff --git a/Master/texmf-dist/source/latex/keyfloat/keyfloat.dtx b/Master/texmf-dist/source/latex/keyfloat/keyfloat.dtx
index 0379749ae14..d6e3b217db5 100644
--- a/Master/texmf-dist/source/latex/keyfloat/keyfloat.dtx
+++ b/Master/texmf-dist/source/latex/keyfloat/keyfloat.dtx
@@ -1,4 +1,4 @@
-
+%
% \iffalse meta-comment
%
% Copyright 2016 Brian Dunn
@@ -17,7 +17,7 @@
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{keyfloat}
-%<package> [2017/02/09 v0.14 Key/value interface for floats and the subcaption package.]
+%<package> [2017/05/12 v0.15 Key/value interface for floats and the subcaption package.]
%
%<*driver>
\documentclass{ltxdoc}
@@ -316,7 +316,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%<*package>
% \fi
%
-% \CheckSum{1022}
+% \CheckSum{1102}
%
% \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
@@ -342,7 +342,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \changes{v0.13}{2017/01/18}{\ 2017/01/18}
% \changes{v0.13}{2017/01/12}{Docs: Other Settings.}
% \changes{v0.14}{2017/02/09}{\ 2017/02/09}
-
+% \changes{v0.15}{2017/05/12}{\ 2017/05/12}
@@ -405,9 +405,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% When used with the \pkg{tocdata} package, the name also appears in the
% List of Figures.
%
-% Floats may be placed into a row environment, and are
+% Floats may be placed into a multi-row environment, and are
% typeset to fit within the given number of columns,
-% continuing to the next row if necessary.
+% continuing to the next rows as necessary.
% Nested sub-rows may be used to generate layouts such as
% two small figures placed vertically next to
% one larger figure.
@@ -421,6 +421,21 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% 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}|
+% \bigskip
+%
+% \footnotesize
+% \begin{description}
+% \item[License:] \
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+% \end{description}
+%
% \end{abstract}
%
% \vspace*{\fill}
@@ -475,22 +490,22 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% Attempting to add additional features such as frames and continued floats
% hits the limit of nine parameters for a \TeX\ macro,
% requiring that new features use some kind of change-state macros instead.
-% Attempting to support rows of floats or subfloats only made things more complicated still.
+% Attempting to support rows of floats or subfloats only makes things more complicated still.
%
% A key/value system solves the problem of adding more features,
% does not require much additional typing, is a more self-documenting
-% syntax, and allows the sharing of keys with subfloats as well.
+% syntax, and allows a shared syntax with subfloats and groups of floats as well.
% Thus, the \pkg{keyfloat} package.
%
% \subsection{The \pkg{keyfloat} Package}
%
-% Using \pkg{keyfloat}, the first example above becomes:
+% Using \pkg{keyfloat}, the previous example becomes:
% \begin{verbatim}
% \keyfig{w=3in,c=A Figure,l=fig:somelabel}{filename}
% \end{verbatim}
% \unskip
%
-% The \cs{onefigure} example above becomes:
+% The \cs{onefigure} general case becomes:
% \begin{verbatim}
% \keyfig*[loc]{w=width,t={add'l text},sc=shortcap,cstar=caption,
% l=label}{filename}
@@ -510,11 +525,12 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \item[keyfloats:] A group of rows and columns of floats.
% \item[keysubfigs:] A figure containing a group of rows and columns of subfigures.
% \item[keysubtabs:] A table containing a group of rows and columns of subtables.
+% \item[keywrap:] Wraps a keyfloat around an environment of text. Usable inside a list.
% \item[marginfigure:] A figure environment placed into
% the margin.\footnote{\env{marginfigure} and \env{margintable}: The environments
% provided by the |tufte-book| class are used if loaded,
% otherwise \pkg{keyfloat} provides its own versions.}
-% \item[margintable:] A table environment placed into the margin.
+% \item[margintable:] A table environment placed in the margin.
% \end{description}
%
% Additional features include:
@@ -634,6 +650,12 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% May not be nested.
% See \cref{ex:keysubtabs}.
%
+% \DescribeEnv{keywrap} \marg{width of keyfloat} \marg{keyfloat} \\
+% Displays a keyfloat next to an environment of text. Usable inside a list item,
+% where [W] will not work. \meta{keyfloat} may be any of \cs{keyfig}, \env{keyfigure},
+% \env{keyfloats}, \env{keysubfigs}, etc., each with its proper arguments.
+% See \cref{ex:keywrapkeyfig}.
+%
% \DescribeEnv{marginfigure} \oarg{offset} \\
% A figure placed into the margin, with an optional vertical offset.
% \cs{keyfloat} uses the version provided by the |tufte-book| class if available,
@@ -756,6 +778,9 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% is |O|, which places the wrapped float at the outside edge of the text.
% See \cref{tab:wrapplacement}.
% & wp=I \\
+% va & Sets the vertical alignment of the outermost minipage container for the keyfloat.
+% Defaults to 'c'.
+% & va=t \\
% \bottomrule
% \end{tabular}
% \begin{tablenotes}
@@ -1173,8 +1198,8 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
%
% \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},
-% l=fig:firstsubfig,t=Some Text}{image}
+% \keyfig{lw=1,f,c={First subfigure},
+% l=fig:firstsubfig,t=Some text}{image}
% \keyfig{lw=1,f,r=90,c={Second subfigure},
% l=fig:secondsubfig,
% t=Lots of lots of lots of lots of text.}
@@ -1380,6 +1405,35 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \end{dtxexample}
%
%
+% \clearpage
+%
+% \begin{dtxexample}[\Cref{fig:keywrapfig}]
+% {Using \cs{keywrap} with a \cs{keyfig}\label{ex:keywrapkeyfig}}
+% \begin{itemize}
+% \item First item.
+% Several lines of text text text text text
+% text text text text text text text text.
+% \item \begin{keywrap}{.3\linewidth}{\keyfig{%
+% lw=1,c={Keywrap with \cs{keyfig}},l=fig:keywrapfig%
+% }{image}}
+% Second item.
+% Several lines of text text text text text
+% text text text text text text text text text
+% text text text text text text text.
+%
+% These paragraphs are inside the \texttt{keywrap}.
+% A vertical gap appears below if the text is not enough to
+% fill the space next to the \cs{keyfig}.
+% \end{keywrap}
+% Outside the \env{wrapfig},\margintag{notes}\
+% but still in the second item.
+% There is no elegant way to place only part of a paragraph
+% inside a \env{keywrap}, and attempting to do so requires
+% manually removing the vertical paragraph skip.
+% \item Third item.
+% \end{itemize}
+% \end{dtxexample}
+%
%
%
% \clearpage
@@ -1510,7 +1564,7 @@ Keywords={LaTeX, floats, key/val, subcaption, rows}%
% \begin{keysubfigs}{2}{
% c=Artist's collection, l=fig:artistcollection,
% t={Some fully-justified text just for illustrative purposes,
-% in case you have use for large explanations.
+% in case you have use for long explanations.
% This text may be the full \cs{linewidth} in size. \par
% Multiple paragraphs of text are allowed.},
% ap=Prefix,af=First,al=Last,as={, Suffix}
@@ -1773,7 +1827,7 @@ provide similar functionality to floatrow.}
% \DescribeBoolean{KFLT@cont} Continued float?
% \begin{macrocode}
-\newboolean{KFLT@cont}{}
+\newboolean{KFLT@cont}
% \end{macrocode}
%
% \DescribeKey[main]{cont} Continued float?
@@ -2096,13 +2150,27 @@ provide similar functionality to floatrow.}
\define@key{KFLT@keys}{wp}{\renewcommand{\KFLT@wp}{#1}}
% \end{macrocode}
%
-% \begin{macro}{\KFLT@wp} Storage for the vertical margin offset.
+% \begin{macro}{\KFLT@wp} Storage for the wrap placement.
% \begin{macrocode}
\newcommand{\KFLT@wp}{O}
% \end{macrocode}
% \end{macro}
+% \DescribeKey[main]{va} Set vertical alignment of the outermost minipage container.
+%
+% \changes{v0.15}{2017/05/09}{Added vertical alignment key \texttt{va}.}
+% \begin{macrocode}
+\define@key{KFLT@keys}{va}{\renewcommand{\KFLT@va}{#1}}
+% \end{macrocode}
+%
+% \begin{macro}{\KFLT@va} Storage for the vertical alignment.
+% \begin{macrocode}
+\newcommand{\KFLT@va}{c}
+% \end{macrocode}
+% \end{macro}
+
+
@@ -2784,6 +2852,7 @@ width=\KFLT@imagewidth,height=\KFLT@h]{\KFLT@i}%
\renewcommand{\KFLT@stretch}{1}%
\setlength{\KFLT@mo}{-1.2ex}%
\renewcommand{\KFLT@wp}{O}%
+\renewcommand{\KFLT@va}{c}%
}
% \end{macrocode}
% \end{macro}
@@ -3092,14 +3161,16 @@ width=\KFLT@imagewidth,height=\KFLT@h]{\KFLT@i}%
% Not used by subfigures.
%
% \changes{v0.12}{2016/12/03}{[M] and [W] floats.}
+% \changes{v0.15}{2017/05/09}{Handle vertical alignment key \protect\texttt{va}.}
+% \changes{v0.15}{2017/05/12}{Adjustments for \protect\env{keywrap}.}
% \begin{macrocode}
\NewDocumentEnvironment{KFLT@boxouter}{m m}
{% boxouter
% \end{macrocode}
-% The \env{keytable} environment handles the contents in either of
+% The \env{keyfigure} and \env{keytable} environments handle the contents in one of
% three possible ways, depending on whether it is
% called alone, inside a \env{keyfloats} environment, or
-% inside a \env{keysubtabs} environment.
+% inside a \env{keysubfigs} or \env{keysubtabs} environment.
%
% Start the new subfigure or subtable, of the given width:
% \begin{macrocode}
@@ -3111,7 +3182,9 @@ width=\KFLT@imagewidth,height=\KFLT@h]{\KFLT@i}%
{% not subfloat:
\ifthenelse{\cnttest{\value{KFLT@keyfloatdepth}}>{0}}%
{% keyfloats
-\minipage{\KFLT@rowboxwidth}%
+\ifbool{KFLT@keywrap}
+{\minipage[t]{\KFLT@rowboxwidth}}%
+{\minipage[\KFLT@va]{\KFLT@rowboxwidth}}%
\captionsetup*{type=\KFLT@type}%
}% keyfloats
{% not keyfloats
@@ -3119,7 +3192,20 @@ width=\KFLT@imagewidth,height=\KFLT@h]{\KFLT@i}%
%
% Not a subfloat or \env{keyfloats}, so create a single float.
%
+% See if inside a \env{keywrap}.
+% If so, force [H] and vertical align top.
+% \begin{macrocode}
+\ifbool{KFLT@keywrap}%
+{%
+\par\addvspace{\baselineskip}%
+\noindent\minipage[t]{\linewidth}%
+\captionsetup{type=\KFLT@type}%
+}%
+{% not a keywrap
+% \end{macrocode}
+%
% See if the float should [W]rap:
+%
% \begin{macrocode}
\ifthenelse{\equal{#2}{W}}%
% \end{macrocode}
@@ -3162,7 +3248,7 @@ width=\KFLT@imagewidth,height=\KFLT@h]{\KFLT@i}%
% \begin{macrocode}
{% [H]
\par\addvspace{\baselineskip}%
-\noindent\minipage{\linewidth}%
+\noindent\minipage[\KFLT@va]{\linewidth}%
\captionsetup{type=\KFLT@type}%
}% [H]
% \end{macrocode}
@@ -3175,6 +3261,7 @@ width=\KFLT@imagewidth,height=\KFLT@h]{\KFLT@i}%
}% not [H]
}% not [M]
}% not [W]
+}% not keywrap
}% not keyfloats
}% not subfloat
% \end{macrocode}
@@ -3226,6 +3313,15 @@ width=\KFLT@imagewidth,height=\KFLT@h]{\KFLT@i}%
%
% Close the minipage or float:
%
+% See if in a \env{keywrap}:
+% \begin{macrocode}
+\ifbool{KFLT@keywrap}{%
+\endminipage%
+\par\addvspace{\baselineskip}%
+}
+{% not keywrap
+% \end{macrocode}
+%
% See if the float should [W]rap:
% \begin{macrocode}
\ifthenelse{\equal{#2}{W}}%
@@ -3258,6 +3354,7 @@ width=\KFLT@imagewidth,height=\KFLT@h]{\KFLT@i}%
}% not [H]
}% not [M]
}% not [W]
+}% not keywrap
}% not keyfloats
}% not subfloat
}% endkeyboxouter
@@ -3482,6 +3579,8 @@ environment inside another, or inside a keyfloats.}%
% Likewise, manually-selected |w| width and |h| tags may need to be
% adjusted to prevent overflow.
%
+% \changes{v0.15}{2017/05/12}{Adjustments for \protect\env{keywrap}.}
+%
% \begin{macrocode}
\NewDocumentEnvironment{keyfloats}{s O{tbp} m}
{%
@@ -3490,12 +3589,13 @@ environment inside another, or inside a keyfloats.}%
% \begin{macrocode}
\addtocounter{KFLT@keyfloatdepth}{1}%
% \end{macrocode}
-% If [H] or nested, use a minipage instead of a float:
+% If [H], nested, subfloats, or keywrap, use a minipage instead of a float:
% \begin{macrocode}
\ifthenelse{%
\equal{#2}{H}%
\OR\cnttest{\value{KFLT@keyfloatdepth}}>{1}%
\OR\boolean{KFLT@inkeysubfloats}%
+\OR\boolean{KFLT@keywrap}%
}%
% \end{macrocode}
% Create an inline minipage:
@@ -3509,7 +3609,8 @@ environment inside another, or inside a keyfloats.}%
\OR\boolean{KFLT@inkeysubfloats}%
}%
{\noindent%
-\begin{minipage}{\KFLT@rowboxwidth}}%
+\begin{minipage}{\KFLT@rowboxwidth}%
+}%
{\bigbreak%
\noindent\begin{minipage}{\linewidth}}%
% \end{macrocode}
@@ -3562,12 +3663,16 @@ environment inside another, or inside a keyfloats.}%
\equal{#2}{H}%
\OR\cnttest{\value{KFLT@keyfloatdepth}}>{1}%
\OR\boolean{KFLT@inkeysubfloats}%
+\OR\boolean{KFLT@keywrap}%
}%
{\end{minipage}%
% \end{macrocode}
% Spacing if nested:
% \begin{macrocode}
-\ifthenelse{\cnttest{\value{KFLT@keyfloatdepth}}>{0}}%
+\ifthenelse{%
+\cnttest{\value{KFLT@keyfloatdepth}}>{0}%
+\OR\boolean{KFLT@keywrap}%
+}%
{}{\bigbreak}%
}% was [H]
% \end{macrocode}
@@ -3642,6 +3747,7 @@ environment inside another, or inside a keyfloats.}%
% \begin{macro}{\KFLT@subfloats} \marg{starred?} \marg{loc} \marg{cols} \marg{\keyvalsarg}
%
% \changes{v0.13}{2017/01/16}{Fix: Subfloat type selection.}
+% \changes{v0.15}{2017/05/12}{Adjustments for \protect\env{keywrap}.}
%
% Start a subfloat environment
% \begin{macrocode}
@@ -3664,9 +3770,12 @@ environment inside another, or inside a keyfloats.}%
{\setlength{\KFLT@rowboxwidth}{.9\textwidth/\real{#3}}}%
{\setlength{\KFLT@rowboxwidth}{.9\linewidth/\real{#3}}}%
% \end{macrocode}
-% If [H], create an inline minipage:
+% If [H], or in a \env{keywrap}, create an inline minipage:
% \begin{macrocode}
-\ifthenelse{\equal{#2}{H}}%
+\ifthenelse{%
+\equal{#2}{H}%
+\OR\boolean{KFLT@keywrap}%
+}%
{%
\bigbreak\noindent\begin{minipage}{\linewidth}%
}%
@@ -3735,7 +3844,10 @@ environment inside another, or inside a keyfloats.}%
% \end{macrocode}
% End the float or minipage:
% \begin{macrocode}
-\ifthenelse{\equal{#2}{H}}%
+\ifthenelse{%
+\equal{#2}{H}%
+\OR\boolean{KFLT@keywrap}%
+}%
{\end{minipage}\bigbreak}% was [H]
{% not [H]:
\IfBooleanTF{#1}% starred?
@@ -3858,20 +3970,81 @@ environment inside another, or inside a keyfloats.}%
{\end{KFLT@marginfloat}}
% \end{macrocode}
% \end{environment}
+%
+%
+%
+%
+%
+%
+% \DescribeBoolean{KFL@keywrap} Tells the next keyfloat to wrap around some text.
+% \begin{macrocode}
+\newboolean{KFLT@keywrap}
+\boolfalse{KFLT@keywrap}
+% \end{macrocode}
+%
+%
+% \DescribeLength{\KFLT@keywrapwidth} The width of the object to be wrapped beside the text.
+% \begin{macrocode}
+\newlength{\KFLT@keywrapwidth}
+% \end{macrocode}
+%
+% \DescribeLength{\KFLT@keywrapparskip} The \cs{parskip} outside of the keywrap.
+% \begin{macrocode}
+\newlength{\KFLT@keywrapparskip}
+% \end{macrocode}
+%
+% \DescribeLength{\KFLT@keywrapparindent} The \cs{parindent} outside of the keywrap.
+% \begin{macrocode}
+\newlength{\KFLT@keywrapparindent}
+% \end{macrocode}
+%
+%
+% \begin{environment}{keywrap} \marg{width} \marg{keyfloat}
+% \changes{v0.15}{2017/05/11}{Added.}
+% \begin{macrocode}
+\DeclareDocumentEnvironment{keywrap}{m +m}
+{%
+\par%
+\setlength{\KFLT@keywrapwidth}{\linewidth}%
+\addtolength{\KFLT@keywrapwidth}{-#1}%
+\addtolength{\KFLT@keywrapwidth}{-2em}%
+\minipage[t]{\KFLT@keywrapwidth}%
+%
+\setlength{\parskip}{\KFLT@keywrapparskip}%
+\setlength{\parindent}{\KFLT@keywrapparindent}%
+\booltrue{KFLT@keywrap}%
+}
+{%
+\par
+\endminipage%
+\hfill%
+\begin{minipage}[t]{#1}%
+\booltrue{KFLT@keywrap}%
+#2%
+\par
+\unskip\vspace{\smallskipamount}
+\end{minipage}%
+\par
+}
-
-
-
-
+\BeforeBeginEnvironment{keywrap}{
+\setlength{\KFLT@keywrapparskip}{\parskip}
+\setlength{\KFLT@keywrapparindent}{\parindent}
+}
+% \end{macrocode}
+%
+% \end{environment}
+%
+%
%
%
% \iffalse
%</package>
% \fi
-
-
-
-
+%
+%
+%
+%
% \clearpage
% \pagestyle{plain}
%