%%
%% This is file `hep-float-documentation.tex',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% hep-float-implementation.dtx  (with options: `documentation')
%% This is a generated file.
%% Copyright (C) 2019-2025 by Jan Hajer
%% This file may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either
%% version 1.3c 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.3c or later is part of all distributions of
%% LaTeX version 2005/12/01 or later.

\ProvidesFile{hep-float-documentation.tex}[2025/09/01 v1.4 hep-float documentation]
\documentclass{ltxdoc}

\renewcommand*\theCodelineNo{\rmfamily\tstyle\footnotesize\arabic{CodelineNo}}
\AtBeginEnvironment{macrocode}{\renewcommand*{\ttdefault}{clmt}}
\renewcommand*{\MacroFont}{\codestyle}
\AtBeginDocument{\DeleteShortVerb{\|}}
\AtBeginDocument{\MakeShortVerb{\"}}
\EnableCrossrefs
\CodelineIndex
\RecordChanges

\usepackage{hologo}

\usepackage[parskip,oldstyle,font=10pt]{hep-paper}
\bibliography{bibliography}

\GetFileInfo{hep-float.sty}

\title{The \software{hep-float} package\thanks{This document corresponds to \software{hep-float}~\fileversion.}}
\subtitle{Convenience package for float placement}
\author{Jan Hajer \email{jan.hajer@tecnico.ulisboa.pt}}
\date{\filedate}

\begin{document}

\newgeometry{vscale=.8, vmarginratio=3:4, includeheadfoot, left=11em, marginparwidth=4.6cm, marginparsep=3mm, right=7em}

\maketitle

\begin{abstract}
The \software{hep-float} package redefines some \hologo{LaTeX} float placement defaults and defines convenience wrappers for floats.
\end{abstract}

The \software{hep-float} package can be loaded with "\usepackage{hep-float}".

\DescribeEnv{figure}
\DescribeEnv{table}
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.

"\setcounter{bottomnumber}{0}" \hfill no floats at the bottom of a page (default 1) \\
"\setcounter{topnumber}{1}" \hfill a single float at the top of a page (default 2) \\
"\setcounter{dbltopnumber}{1}" \hfill same for full widths floats in two-column mode \\
"\renewcommand{\textfraction}{.1}" \hfill large floats are allowed (default 0.2)\\
"\renewcommand{\topfraction}{.9}" \hfill (default 0.7) \\
"\renewcommand{\dbltopfraction}{.9}" \hfill (default 0.7) \\
"\renewcommand{\floatpagefraction}{.8}" \hfill float pages must be full (default 0.5)

The most useful float placement is usually archived by placing the float \emph{in front} of the paragraph it is referenced in first.
\DescribeMacro{local}
Additionally, manual float placement can be deactivated using the "local" package option.

\DescribeMacro{\raggedright}
The float environments have been adjusted to center their content.
The usual behaviour can be reactivated using "\raggedright".

\begin{table}
\begin{panels}{2}
\begin{verbatim}
\begin{panels}{2}
  code
\panel
  \begin{tabular}...\end{tabular}
\end{panels}
\end{verbatim}
\caption{Code for this panel environment.}
\label{tab:panels}
\panel
\begin{tabular}{cccc}
\toprule
\multicolumn{2}{c}{one}& \multicolumn{2}{c}{two} \\ \cmidrule(r){1-2} \cmidrule(l){3-4}
\multirow{2}{*}{a} & b & c & d \\
 & b & c & d \\
\bottomrule
\end{tabular}
\caption{The \protecting{"booktabs"} and \protecting{"multirow"} features.}
\label{tab:booktabs}
\end{panels}
\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}.
} \label{tab:table}
\end{table}

\DescribeEnv{panels}
\DescribeMacro{\panel}
The "panels" environment makes use of the \software{subcaption} package \cite{subcaption}.
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".
Within the "\begin{panels}"\oarg{vertical alignment}\marg{width} environment the "\panel" macro initiates a new sub-float.
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.
The example code is presented in \cref{tab:panels}.
\DescribeMacro{\panelhspace}
\DescribeMacro{\panelvspace}
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}.

\DescribeEnv{tabular}
The \software{booktabs} \cite{booktabs} and \software{multirow} \cite{multirow} packages are loaded enabling publication quality tabulars such as in \cref{tab:booktabs}.

\DescribeMacro{\graphic}
\DescribeMacro{\graphics}
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).
If the graphics are located in a sub-folder its path can be indicated by "\graphics"\marg{subfolder}.

\printbibliography

\end{document}

\endinput
%%
%% End of file `hep-float-documentation.tex'.
