% \iffalse meta-comment
%
% Copyright (C) 2019 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.
%
% \fi
%
% \iffalse

%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<package>\ProvidesPackage{hep-float}[2022/11/01 v1.1 Float adjustments ]
%<documentation>\ProvidesFile{hep-float-documentation.tex}[2022/11/01 v1.1 hep-float documentation]
%
%<*documentation>

\RequirePackage[l2tabu, orthodox]{nag}

\documentclass{ltxdoc}
\AtBeginDocument{\DeleteShortVerb{\|}}
\AtBeginDocument{\MakeShortVerb{\"}}

\EnableCrossrefs
\CodelineIndex
\RecordChanges

\usepackage[parskip, oldstyle]{hep-paper}

\bibliography{bibliography}

\usepackage{hologo}

\MacroIndent=1.5em
\AtBeginEnvironment{macrocode}{\renewcommand{\ttdefault}{clmt}}
%</documentation>

%<*driver>
\expandafter\newif\csname ifshort\endcsname
\shortfalse
\begin{document}
\DocInput{hep-float-implementation.dtx}
\end{document}
%</driver>
%
% \fi
%
% \CheckSum{0}
%
% \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
%   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
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \changes{v1.0}{2021/09/01}{Initial version of the style file.}
% \changes{v1.1}{2022/11/01}{Bug fixes.}
%
% \ifshort
%<*documentation>
% \fi
%
\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}

% \ifshort
\begin{document}
% \fi

\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{manualplacement}
Additionally, manual float placement can be deactivated using the "manualplacement" 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}.

% \ifshort
\printbibliography

\end{document}
%
%</documentation>
% \fi
%
% \StopEventually{
% \printbibliography
% \PrintChanges
% }
%
% \appendix
% \section{Implementation}
%
%<*package>
%
% Load the \software{kvoptions} package \cite{kvoptions} and define a "hepfloat" namespace.
%    \begin{macrocode}
\RequirePackage{kvoptions}
\SetupKeyvalOptions{
  family=hepfloat,
  prefix=hepfloat@
}
%    \end{macrocode}
%
% \begin{macro}{manualplacement}
% Provide the "manualplacement" option for reactivating the manual placement of floats.
%    \begin{macrocode}
\DeclareBoolOption[true]{manualplacement}
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\ProcessKeyvalOptions*
%    \end{macrocode}
%
% Adjust the \hologo{LaTeX} float placement defaults
%    \begin{macrocode}
\setcounter{bottomnumber}{0} % 1
\setcounter{topnumber}{1} % 2
\setcounter{dbltopnumber}{1} % 2
\renewcommand{\topfraction}{.9} % .7
\renewcommand{\dbltopfraction}{.9} % .7
\renewcommand{\textfraction}{.1} % .2
\renewcommand{\floatpagefraction}{.8} % .5
%    \end{macrocode}
%
% \begin{environment}{figure}
% \begin{environment}{table}
% Center the content of "figure" and "table" environments.
% Ignore the manual placement if the "manualplacement" option is set to false.
%    \begin{macrocode}
\let\hep@figure\figure%
\let\end@hep@figure\endfigure%
\let\hep@table\table%
\let\end@hep@table\endtable%
\ifhepfloat@manualplacement%
  \renewenvironment{figure}[1][tbp]{%
    \hep@figure[#1]\centering%
    }{\end@hep@figure}%
  \renewenvironment{table}[1][tbp]{%
    \hep@table[#1]\centering%
  }{\end@hep@table}%
\else%
  \renewenvironment{figure}[1][]{%
    \hep@figure\centering%
  }{\end@hep@figure}%
  \renewenvironment{table}[1][]{%
    \hep@table\centering%
  }{\end@hep@table}
\fi%
%    \end{macrocode}
% \end{environment}
% \end{environment}
%
%
% \subsection{Sub-floats}
%
% Load the \software{subcaption} package \cite{subcaption}.
%    \begin{macrocode}
\PassOptionsToPackage{subrefformat=parens}{subcaption}
\RequirePackage{subcaption}
\captionsetup{font=small}
\captionsetup[sub]{font=small}
%    \end{macrocode}
% Provide the macros for older versions of the \software{subcaption} package using the \software{xparse} \cite{xparse} package.
%    \begin{macrocode}
\RequirePackage{xparse}
\providecommand*\subcaption@minipage[2]{%
  \minipage#1{#2}\setcaptionsubtype\relax%
}
\ProvideDocumentEnvironment{subcaptionblock}{O{b}m}{%
  \caption@withoptargs\subcaption@minipage[#1]{#2}%
}{\endminipage}
%    \end{macrocode}
% \begin{environment}{panels}
%
% \begin{macro}{\panel}
% \begin{macro}{\panelhspace}
% \begin{macro}{\panelvspace}
% Define the "panels" environment and the "\panel" macro using the \software{calc} \cite{calc} and \software{etoolbox} \cite{etoolbox} packages.
%    \begin{macrocode}
\RequirePackage{calc}
\RequirePackage{etoolbox}
\newcommand{\panelhspace}{0.0333}
\newcommand{\panelvspace}{.5\baselineskip}
\newenvironment{panels}[2][b]{%
  \addtolength{\belowcaptionskip}{\panelvspace}%
%    \end{macrocode}
% Define an internal macro for global behaviour.
%    \begin{macrocode}
  \newcommand{\begin@subcaption@minipage}[2][b]{%
%     \caption@withoptargs\subcaption@minipage[##1]{##2}%
    \subcaptionblock[##1]{##2}%
    \centering\vskip 0pt%
%     \renewcommand{\hep@panel@vspace}{\panelvspace}%
  }%
%    \end{macrocode}
% Define the "\panel" macro for the case that the number of panels is given.
%    \begin{macrocode}
  \ifdim#2pt>1pt%
    \newcommand{\hep@panel@space}{\panelhspace\linewidth/#2}%
    \newcommand{\panel}[1][b]{%
      \endminipage\hfill\begin@subcaption@minipage[#1]{%
        \linewidth/#2-\hep@panel@space%
      }%
    }%
    \begin@subcaption@minipage[#1]{\linewidth/#2-\hep@panel@space}%
%    \end{macrocode}
% Define the "\panel" macro for the case that the width of the panel is given.
%    \begin{macrocode}
  \else%
    \newcommand{\panel}[2][b]{%
      \endminipage\hfill\begin@subcaption@minipage[#1]{%
        ##2\linewidth-##2\linewidth*\real{\panelhspace}%
      }%
    }%
    \begin@subcaption@minipage[#1]{%
      #2\linewidth-#2\linewidth*\real{\panelhspace}%
    }%
  \fi%
}{
\endsubcaptionblock
\vspace{-\panelvspace}
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{environment}
%
% \subsection{Tables}
%
% \begin{environment}{tabular}
% Enhance tabulars with the \software{booktabs} and \software{multirow} packages \cite{booktabs, multirow}.
%    \begin{macrocode}
\RequirePackage{booktabs}
\RequirePackage{multirow}
%    \end{macrocode}
% \end{environment}

% \subsection{Figures}
%
% \begin{macro}{\graphic}
% Provide the "\graphic" macro for the inclusion of figures using the \software{graphicx} package \cite{graphicx}.
%    \begin{macrocode}
\RequirePackage{graphicx}
\providecommand{\tikzsetnextfilename}[1]{}
\newcommand{\graphic}[2][1]{\tikzsetnextfilename{#2}{%
  \centering\includegraphics[width=#1\linewidth]{#2}\par%
}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\graphics}
% Provide the "\graphics" macro for the inclusion of figures located in a subfolder.
%    \begin{macrocode}
\newcommand{\graphics}[1]{\graphicspath{{./#1/}}}
%    \end{macrocode}
% \end{macro}
%
%</package>
%
% \section{Readme}
%
%<*readme>
%
%    \begin{macrocode}
# The `hep-float` package

Convenience package for float placement

## Introduction

The `hep-float` package redefines some `LaTeX` float placement defaults and defines convenience wrappers for floats.

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

## Author

Jan Hajer

## License

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.
%    \end{macrocode}
%
%</readme>
%
% \Finale

\endinput

% \PrintIndex
% makeindex -s gglo.ist -o hep-float-implementation.gls hep-float-implementation.glo
% makeindex -s gglo.ist -o hep-float-implementation.ind hep-float-implementation.idx