Debian Codegraph @

texmf-dist/source/latex/hep-float/hep-float-implementation.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2019-2023 by Jan Hajer
4 % -----------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3c
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3c or later is part of all distributions of LaTeX
14 % version 2005/12/01 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19
20 %<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
21 %<package>\ProvidesPackage{hep-float}[2025/09/01 v1.4 Float adjustments]
22 %<documentation>\ProvidesFile{hep-float-documentation.tex}[2025/09/01 v1.4 hep-float documentation]
23 %
24 %<*documentation>
25 \documentclass{ltxdoc}
26
27 \renewcommand*\theCodelineNo{\rmfamily\tstyle\footnotesize\arabic{CodelineNo}}
28 \AtBeginEnvironment{macrocode}{\renewcommand*{\ttdefault}{clmt}}
29 \renewcommand*{\MacroFont}{\codestyle}
30 \AtBeginDocument{\DeleteShortVerb{\|}}
31 \AtBeginDocument{\MakeShortVerb{\"}}
32 \EnableCrossrefs
33 \CodelineIndex
34 \RecordChanges
35
36 \usepackage{hologo}
37
38 \usepackage[parskip,oldstyle,font=10pt]{hep-paper}
39 \bibliography{bibliography}
40 %</documentation>
41
42 %<*driver>
43 \expandafter\newif\csname ifshort\endcsname
44 \shortfalse
45 \begin{document}
46 \DocInput{hep-float-implementation.dtx}
47 \end{document}
48 %</driver>
49 %
50 % \fi
51 %
52 % \CheckSum{364}
53 %
54 % \CharacterTable
55 % {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
56 % Lower-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
57 % Digits \0\1\2\3\4\5\6\7\8\9
58 % Exclamation \! Double quote \" Hash (number) \#
59 % Dollar \$ Percent \% Ampersand \&
60 % Acute accent \' Left paren \( Right paren \)
61 % Asterisk \* Plus \+ Comma \,
62 % Minus \- Point \. Solidus \/
63 % Colon \: Semicolon \; Less than \<
64 % Equals \= Greater than \> Question mark \?
65 % Commercial at \@ Left bracket \[ Backslash \\
66 % Right bracket \] Circumflex \^ Underscore \_
67 % Grave accent \` Left brace \{ Vertical bar \|
68 % Right brace \} Tilde \~}
69 %
70 % \changes{v1.0}{2021/09/01}{Initial version of the style file.}
71 % \changes{v1.1}{2022/11/01}{Bug fixes.}
72 % \changes{v1.2}{2023/07/01}{Bug fixes.}
73 % \changes{v1.3}{2024/11/01}{Bug fixes.}
74 % \changes{v1.4}{2025/09/01}{Bug fixes.}
75 %
76 % \ifshort
77 %<*documentation>
78 % \fi
79 %
80 \GetFileInfo{hep-float.sty}
81
82 \title{The \software{hep-float} package\thanks{This document corresponds to \software{hep-float}~\fileversion.}}
83 \subtitle{Convenience package for float placement}
84 \author{Jan Hajer \email{[email protected]}}
85 \date{\filedate}
86
87 % \ifshort
88 \begin{document}
89 % \fi
90
91 \newgeometry{vscale=.8, vmarginratio=3:4, includeheadfoot, left=11em, marginparwidth=4.6cm, marginparsep=3mm, right=7em}
92
93 \maketitle
94
95 \begin{abstract}
96 The \software{hep-float} package redefines some \hologo{LaTeX} float placement defaults and defines convenience wrappers for floats.
97 \end{abstract}
98
99 The \software{hep-float} package can be loaded with "\usepackage{hep-float}".
100
101 \DescribeEnv{figure}
102 \DescribeEnv{table}
103 Automatic float placement is adjusted to place a single float at the top of pages and to reduce the number of float pages, using the \hologo{LaTeX} macros.
104
105 "\setcounter{bottomnumber}{0}" \hfill no floats at the bottom of a page (default 1) \\
106 "\setcounter{topnumber}{1}" \hfill a single float at the top of a page (default 2) \\
107 "\setcounter{dbltopnumber}{1}" \hfill same for full widths floats in two-column mode \\
108 "\renewcommand{\textfraction}{.1}" \hfill large floats are allowed (default 0.2)\\
109 "\renewcommand{\topfraction}{.9}" \hfill (default 0.7) \\
110 "\renewcommand{\dbltopfraction}{.9}" \hfill (default 0.7) \\
111 "\renewcommand{\floatpagefraction}{.8}" \hfill float pages must be full (default 0.5)
112
113 The most useful float placement is usually archived by placing the float \emph{in front} of the paragraph it is referenced in first.
114 \DescribeMacro{local}
115 Additionally, manual float placement can be deactivated using the "local" package option.
116
117 \DescribeMacro{\raggedright}
118 The float environments have been adjusted to center their content.
119 The usual behaviour can be reactivated using "\raggedright".
120
121 \begin{table}
122 \begin{panels}{2}
123 \begin{verbatim}
124 \begin{panels}{2}
125 code
126 \panel
127 \begin{tabular}...\end{tabular}
128 \end{panels}
129 \end{verbatim}
130 \caption{Code for this panel environment.}
131 \label{tab:panels}
132 \panel
133 \begin{tabular}{cccc}
134 \toprule
135 \multicolumn{2}{c}{one}& \multicolumn{2}{c}{two} \\ \cmidrule(r){1-2} \cmidrule(l){3-4}
136 \multirow{2}{*}{a} & b & c & d \\
137 & b & c & d \\
138 \bottomrule
139 \end{tabular}
140 \caption{The \protecting{"booktabs"} and \protecting{"multirow"} features.}
141 \label{tab:booktabs}
142 \end{panels}
143 \caption{Example use of the \protecting{"panels"} environment in Panel \subref{tab:panels} and the features from the \software{booktabs} and \software{multirow} packages in Panel \subref{tab:booktabs}.
144 } \label{tab:table}
145 \end{table}
146
147 \DescribeEnv{panels}
148 \DescribeMacro{\panel}
149 The "panels" environment makes use of the \software{subcaption} package \cite{subcaption}.
150 It provides sub-floats and takes as mandatory argument either the number of sub-floats (default~2) or the width of the first sub-float as fraction of the "\linewidth".
151 Within the "\begin{panels}"\oarg{vertical alignment}\marg{width} environment the "\panel" macro initiates a new sub-float.
152 In the case that the width of the first sub-float has been given as an optional argument to the "panels" environment the "\panel"\marg{width} macro takes the width of the next sub-float as mandatory argument.
153 The example code is presented in \cref{tab:panels}.
154 \DescribeMacro{\panelhspace}
155 \DescribeMacro{\panelvspace}
156 The spacing between the panels can be adjusted by adjusting the "\panelvspace" in terms of a "\linewidth" fraction "\renewcommand*{\panelhspace}"{fraction} and the "\panelvspace" in terms of a length "\renewcommand*{\panelvspace}"\marg{length}.
157
158 \DescribeEnv{tabular}
159 The \software{booktabs} \cite{booktabs} and \software{multirow} \cite{multirow} packages are loaded enabling publication quality tabulars such as in \cref{tab:booktabs}.
160
161 \DescribeMacro{\graphic}
162 \DescribeMacro{\graphics}
163 The \software{graphicx} package \cite{graphicx} is loaded and the "\graphic"\oarg{width}\marg{figure} macro is defined, which is a wrapper for the "\includegraphics"\marg{figure} macro and takes the figure width as fraction of the "\linewidth" as optional argument (default~1).
164 If the graphics are located in a sub-folder its path can be indicated by "\graphics"\marg{subfolder}.
165
166 % \ifshort
167 \printbibliography
168
169 \end{document}
170 %
171 %</documentation>
172 % \fi
173 %
174 % \StopEventually{
175 % \printbibliography
176 % \PrintChanges
177 % }
178 %
179 % \appendix
180 % \section{Implementation}
181 %
182 %<*package>
183 %
184 % Load the \software{kvoptions} package \cite{kvoptions} and define a "hepfloat" namespace.
185 % \begin{macrocode}
186 \RequirePackage{kvoptions}
187 \SetupKeyvalOptions{
188 family=hepfloat,
189 prefix=hepfloat@
190 }
191 % \end{macrocode}
192 %
193 % \begin{macro}{local}
194 % Provide the "local" option for reactivating the manual placement of floats.
195 % \begin{macrocode}
196 \DeclareBoolOption[true]{local}
197 \DeclareComplementaryOption{global}{local}
198 % \end{macrocode}
199 % \end{macro}
200 %
201 % \begin{macrocode}
202 \ProcessKeyvalOptions*
203 % \end{macrocode}
204 %
205 % Adjust the \hologo{LaTeX} float placement defaults
206 % \begin{macrocode}
207 \setcounter{bottomnumber}{0} % 1
208 \setcounter{topnumber}{1} % 2
209 \setcounter{dbltopnumber}{1} % 2
210 \renewcommand*{\topfraction}{.9} % .7
211 \renewcommand*{\dbltopfraction}{.9} % .7
212 \renewcommand*{\textfraction}{.1} % .2
213 \renewcommand*{\floatpagefraction}{.8} % .5
214 % \end{macrocode}
215 %
216 % \begin{environment}{figure}
217 % \begin{environment}{table}
218 % Center the content of "figure" and "table" environments.
219 % Ignore the manual placement if the "local" option is set to false.
220 % \begin{macrocode}
221 \ifhepfloat@local%
222 \renewenvironment{figure}[1][tbp]{%
223 \@float{figure}[#1]\centering\small%
224 }{\end@float}
225 \renewenvironment{figure*}[1][tbp]{%
226 \@dblfloat{figure}[#1]\centering\small%
227 }{\end@dblfloat}
228 \renewenvironment{table}[1][tbp]{%
229 \@float{table}[#1]\centering\small%
230 }{\end@float}
231 \renewenvironment{table*}[1][tbp]{%
232 \@dblfloat{table}[#1]\centering\small%
233 }{\end@dblfloat}
234 \else%
235 \renewenvironment{figure}[1][]{%
236 \@float{figure}\centering\small%
237 }{\end@float}
238 \renewenvironment{figure*}[1][]{%
239 \@dblfloat{figure}\centering\small%
240 }{\end@dblfloat}
241 \renewenvironment{table}[1][]{%
242 \@float{table}\centering\small%
243 }{\end@float}
244 \renewenvironment{table*}[1][]{%
245 \@dblfloat{table}\centering\small%
246 }{\end@dblfloat}
247 \fi%
248 % \end{macrocode}
249 % \end{environment}
250 % \end{environment}
251 %
252 %
253 % \subsection{floats}
254 %
255 % \begin{environment}{figures}
256 % \begin{macro}{\figure}
257 % Define the "figures" environment that places figures next to each other.
258 % \begin{macrocode}
259 \newcommand*{\figurehspace}{0.0333}
260 \newcommand*{\figurevspace}{.5\baselineskip}
261 \newenvironment{figures}[2][b]{%
262 \begin{figure}
263 \let\oldcaption\caption
264 \renewcommand*{\caption}[1]{%
265 \renewcommand*{\caption}{\oldcaption}%
266 \captionof{figure}{##1}\vspace{\figurevspace}%
267 }
268 \ifdim#2pt>1pt%
269 \newcommand*{\hep@figure@space}{\figurehspace\linewidth/#2}%
270 \renewcommand*{\figure}[1][b]{%
271 \end{minipage}\hfill%
272 \begin{minipage}[##1]{\linewidth/#2-\hep@figure@space}%
273 }
274 \begin{minipage}[#1]{\linewidth/#2-\hep@figure@space}
275 \else%
276 \newcommand*{\hep@figure@space}[1]{##1\linewidth*\real{\figurehspace}}
277 \renewcommand*{\figure}[2][b]{%
278 \end{minipage}\hfill%
279 \begin{minipage}[##1]{##2\linewidth-\hep@figure@space{##2}}%
280 }
281 \begin{minipage}[#1]{#2\linewidth-\hep@figure@space{#2}}
282 \fi%
283 }{%
284 \end{minipage}\end{figure}%
285 }
286 % \end{macrocode}
287 % \end{macro}
288 % \end{environment}
289 % \begin{environment}{tables}
290 % \begin{macro}{\table}
291 % Define the "tables" environment that places tables next to each other.
292 % \begin{macrocode}
293 \newcommand*{\tablehspace}{0.0333}
294 \newcommand*{\tablevspace}{.5\baselineskip}
295 \newenvironment{tables}[2][b]{%
296 \begin{table}
297 \let\oldcaption\caption
298 \renewcommand*{\caption}[1]{%
299 \renewcommand*{\caption}{\oldcaption}%
300 \captionof{table}{##1}\vspace{\tablevspace}%
301 }
302 \ifdim#2pt>1pt%
303 \newcommand*{\hep@table@space}{\tablehspace\linewidth/#2}%
304 \renewcommand*{\table}[1][b]{%
305 \end{minipage}\hfill%
306 \begin{minipage}[##1]{\linewidth/#2-\hep@table@space}\centering%
307 }
308 \begin{minipage}[#1]{\linewidth/#2-\hep@table@space}\centering
309 \else%
310 \newcommand*{\hep@table@space}[1]{##1\linewidth*\real{\tablehspace}}
311 \renewcommand*{\table}[2][b]{%
312 \end{minipage}\hfill%
313 \begin{minipage}[##1]{##2\linewidth-\hep@table@space{##2}}%
314 \centering%
315 }
316 \begin{minipage}[#1]{#2\linewidth-\hep@table@space{#2}}%
317 \centering
318 \fi%
319 }{%
320 \end{minipage}\end{table}%
321 }
322 % \end{macrocode}
323 % \end{macro}
324 % \end{environment}
325 %
326 % \subsection{Sub-floats}
327 %
328 % Load the \software{subcaption} package \cite{subcaption}.
329 % \begin{macrocode}
330 \PassOptionsToPackage{subrefformat=parens}{subcaption}
331 \RequirePackage{subcaption}
332 \captionsetup{font=small}
333 \captionsetup[sub]{font=small}
334 % \end{macrocode}
335 % Provide the macros for older versions of the \software{subcaption} package using the \software{xparse} \cite{xparse} package.
336 % \begin{macrocode}
337 \RequirePackage{xparse}
338 \providecommand*\subcaption@minipage[2]{%
339 \minipage#1{#2}\setcaptionsubtype\relax%
340 }
341 \ProvideDocumentEnvironment{subcaptionblock}{O{b}m}{%
342 \caption@withoptargs\subcaption@minipage[#1]{#2}%
343 }{\endminipage}
344 % \end{macrocode}
345 % \begin{environment}{panels}
346 %
347 % \begin{macro}{\panel}
348 % \begin{macro}{\panelhspace}
349 % \begin{macro}{\panelvspace}
350 % Define the "panels" environment and the "\panel" macro using the \software{calc} \cite{calc} and \software{etoolbox} \cite{etoolbox} packages.
351 % \begin{macrocode}
352 \RequirePackage{calc}
353 \RequirePackage{etoolbox}
354 \newcommand*{\panelhspace}{0.0333}
355 \newcommand*{\panelvspace}{.5\baselineskip}
356 \newenvironment{panels}[2][b]{%
357 \addtolength{\belowcaptionskip}{\panelvspace}%
358 % \end{macrocode}
359 % Define an internal macro for global behaviour.
360 % \begin{macrocode}
361 \newcommand*{\begin@subcaption@minipage}[2][b]{%
362 % \caption@withoptargs\subcaption@minipage[##1]{##2}%
363 \subcaptionblock[##1]{##2}%
364 \centering\vskip 0pt%
365 % \renewcommand*{\hep@panel@vspace}{\panelvspace}%
366 }%
367 % \end{macrocode}
368 % Define the "\panel" macro for the case that the number of panels is given.
369 % \begin{macrocode}
370 \ifdim#2pt>1pt%
371 \newcommand*{\hep@panel@space}{\panelhspace\linewidth/#2}%
372 \newcommand*{\panel}[1][b]{%
373 \endminipage\hfill\begin@subcaption@minipage[#1]{%
374 \linewidth/#2-\hep@panel@space%
375 }%
376 }%
377 \begin@subcaption@minipage[#1]{\linewidth/#2-\hep@panel@space}%
378 % \end{macrocode}
379 % Define the "\panel" macro for the case that the width of the panel is given.
380 % \begin{macrocode}
381 \else%
382 \newcommand*{\hep@panel@space}[1]{##1\linewidth*\real{\panelhspace}}%
383 \newcommand*{\panel}[2][b]{%
384 \endminipage\hfill\begin@subcaption@minipage[#1]{%
385 ##2\linewidth-\hep@panel@space{##2}%
386 }%
387 }%
388 \begin@subcaption@minipage[#1]{%
389 #2\linewidth-\hep@panel@space{#2}%
390 }%
391 \fi%
392 }{%
393 \endsubcaptionblock%
394 \vspace{-\panelvspace}%
395 }
396 % \end{macrocode}
397 % \end{macro}
398 % \end{macro}
399 % \end{macro}
400 % \end{environment}
401 %
402 % \subsection{Tables}
403 %
404 % \begin{environment}{tabular}
405 % Enhance tabulars with the \software{booktabs} and \software{multirow} packages \cite{booktabs, multirow}.
406 % \begin{macrocode}
407 \RequirePackage{booktabs}
408 \RequirePackage{multirow}
409 \newcommand*\header[1]{\multicolumn{1}{c}{#1}}
410 % \end{macrocode}
411 % \end{environment}
412
413 % \subsection{Figures}
414 %
415 % \begin{macro}{\graphic}
416 % Provide the "\graphic" macro for the inclusion of figures using the \software{graphicx} package \cite{graphicx}.
417 % \begin{macrocode}
418 \RequirePackage{graphicx}
419 \providecommand*{\tikzsetnextfilename}[1]{}
420 \newcommand*{\graphic}[2][1]{\tikzsetnextfilename{#2}{%
421 \centering\includegraphics[width=#1\linewidth]{#2}\par%
422 }}
423 % \end{macrocode}
424 % \end{macro}
425 %
426 % \begin{macro}{\graphics}
427 % Provide the "\graphics" macro for the inclusion of figures located in a subfolder.
428 % \begin{macrocode}
429 \newcommand*{\graphics}[1]{\graphicspath{{./#1/}}}
430 % \end{macrocode}
431 % \end{macro}
432 %
433 %</package>
434 %
435 % \section{Test}
436 %
437 %<*test>
438 %
439 % \begin{macrocode}
440 \documentclass{article}
441
442 \usepackage[showframe]{geometry}
443 \usepackage{hep-float}
444
445 \begin{document}
446
447 \begin{figure}
448 \graphic[.5]{example-image-4x3}
449 \caption{test}
450 \end{figure}
451
452 \begin{figures}{.3}
453 \graphic{example-image-4x3}
454 \caption{one}
455 \figure{.4}
456 \graphic{example-image-16x9}
457 \caption{two}
458 \figure{.3}
459 \graphic{example-image-4x3}
460 \caption{three}
461 \figure{.3}
462 \graphic{example-image-4x3}
463 \caption{one}
464 \figure{.4}
465 \graphic{example-image-16x9}
466 \caption{two}
467 \figure{.3}
468 \graphic{example-image-4x3}
469 \caption{three}
470 \end{figures}
471
472 \begin{figures}{3}
473 \graphic{example-image-1x1}
474 \caption{one}
475 \figure
476 \graphic{example-image-1x1}
477 \caption{two}
478 \figure
479 \graphic{example-image-1x1}
480 \caption{three}
481 \figure
482 \graphic{example-image-1x1}
483 \caption{one}
484 \figure
485 \graphic{example-image-1x1}
486 \caption{two}
487 \figure
488 \graphic{example-image-1x1}
489 \caption{three}
490 \end{figures}
491
492
493 \begin{figure}
494 \begin{panels}{3}
495 \graphic{example-image-1x1}
496 \caption{a}
497 \panel
498 \graphic{example-image-1x1}
499 \caption{b}
500 \panel
501 \graphic{example-image-1x1}
502 \caption{c}
503 \panel
504 \graphic{example-image-1x1}
505 \caption{d}
506 \panel
507 \graphic{example-image-1x1}
508 \caption{e}
509 \panel
510 \graphic{example-image-1x1}
511 \caption{f}
512 \end{panels}
513 \caption{Panels}
514 \end{figure}
515
516 \begin{figure}
517 \begin{panels}{.3}
518 \graphic{example-image-4x3}
519 \caption{a}
520 \panel{.4}
521 \graphic{example-image-16x9}
522 \caption{b}
523 \panel{.3}
524 \graphic{example-image-4x3}
525 \caption{c}
526 \panel{.225}
527 \graphic{example-image-1x1}
528 \caption{d}
529 \panel{.4}
530 \graphic{example-image-16x9}
531 \caption{e}
532 \panel{.225}
533 \graphic[.8]{example-image-1x1}
534 \caption{f}
535 \end{panels}
536 \caption{Panels 2}
537 \end{figure}
538
539 \begin{tables}{2}
540 \begin{tabular}{cc}\toprule
541 a & b \\
542 \bottomrule\end{tabular}
543 \caption{a}
544 \table
545 \begin{tabular}{cc}\toprule
546 a & b \\
547 \bottomrule\end{tabular}
548 \caption{b}
549 \end{tables}
550
551 \end{document}
552 % \end{macrocode}
553 %
554 %</test>
555 %
556 % \section{Readme}
557 %
558 %<*readme>
559 %
560 % \begin{macrocode}
561 # The `hep-float` package
562
563 Convenience package for float placement
564
565 ## Introduction
566
567 The `hep-float` package redefines some `LaTeX` float placement defaults
568 and defines convenience wrappers for floats. The `hep-float` package can
569 be loaded with `\usepackage{hep-float}`.
570
571 ## Author
572
573 Jan Hajer
574
575 ## License
576
577 This file may be distributed and/or modified under the conditions of the
578 `LaTeX` Project Public License, either version 1.3c of this license or
579 (at your option) any later version. The latest version of this license is
580 in `http://www.latex-project.org/lppl.txt` and version 1.3c or later is
581 part of all distributions of LaTeX version 2005/12/01 or later.
582 % \end{macrocode}
583 %
584 %</readme>
585 %
586 % \Finale
587
588 \endinput
589
590 % \PrintIndex
591 % makeindex -s gglo.ist -o hep-float-implementation.gls hep-float-implementation.glo
592 % makeindex -s gglo.ist -o hep-float-implementation.ind hep-float-implementation.idx