%%
%% This is file `hep-reference-documentation.tex',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% hep-reference-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-reference-documentation.tex}[2026/08/01 v1.5 HEP-reference 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}
\shortacronym{PDF}{portable document format}

\GetFileInfo{hep-reference.sty}

\title{The \software{hep-reference} package\thanks{This document corresponds to \software{hep-reference}~\fileversion.}}
\subtitle{Adjustments of standard references, footnotes, and citations}
\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-reference} package collects small reference-related adjustments for high-energy physics documents.
It loads and configures \software{hyperref}, \software{cleveref}, and \software{footnotebackref}, suppresses unwanted line breaks before references and citations, adds backlinking footnotes, sets useful \PDF metadata from the document title data, and provides helper macros for text labels, subobject references, and named equation-like references.
\end{abstract}

\section{Introduction}

Load the package with "\usepackage{hep-reference}".

The \software{hyperref} package \cite{hyperref} is loaded with hidden, breakable links and Unicode-aware \PDF strings.
The package also clears the \PDF creator and producer fields and disables fragile formatting commands in bookmarks.
Before "\maketitle" is executed, the \PDF title is filled from "\title" and, if present, the subtitle defined by \software{hep-title}; keywords from \software{hep-title} are passed to the \PDF metadata as well.
If \software{hep-title} is loaded, label-only references to affiliations are formatted as superscript lists and ranges on the title page.

\DescribeMacro{\cref}
\DescribeMacro{\labelcrefrange}
References are extended with the \software{cleveref} package \cite{cleveref}, loaded with the "noabbrev" and "nameinlink" options.
This allows "\cref"\marg{key} to write context-sensitive references such as \enquote{figure 1}, and "\cref"\marg{key1,key2} to combine multiple references.
The final conjunction is set to a comma followed by a non-breaking \enquote{and}, enumerated items from "enumerate" and "inlinelist" are named \enquote{point} and \enquote{points}, and "\labelcrefrange"\marg{key1}\marg{key2} provides the corresponding range command for label-only references.

\DescribeMacro{\eqcrefname}
The "\eqcrefname"\marg{counter}\marg{singular}\oarg{plural} macro declares a \software{cleveref} name for an equation-like counter and formats label-only references to that counter in parentheses.
If the optional plural is omitted, the plural form is built by appending \enquote{s} to the singular name.

\DescribeMacro{\ref}
\DescribeMacro{\eqref}
\DescribeMacro{\subref}
\DescribeMacro{\cite}
The "\ref", "\eqref", "\subref", and "\cite" commands are adjusted so that a preceding inter-word space is converted to a non-breaking space.
This avoids line starts such as \enquote{[1]} or \enquote{(2)} without requiring repeated manual uses of "~\cite"\marg{key}.
When \software{amsmath} is loaded, "\eqref" is routed through "\labelcref".
When \software{subcaption} is loaded, "\subref" keeps the same no-break behaviour.

\DescribeMacro{\subcref}
If \software{subcaption} is loaded, the package additionally defines "\subcref"\marg{key}, which applies "\cref" to the underlying subobject label.

\DescribeMacro{\footnote}
Footnotes are adjusted to swallow white space before the footnote mark and at the beginning of the footnote text.
They also receive backlinks to the text location from which they were called.

\DescribeMacro{\textlabel}
The "\textlabel"\oarg{reference format}\marg{key}\oarg{text format}\marg{text} macro creates a hyperlink target and a label for a piece of text while also printing the text.
The first optional argument formats the text stored in the label and the second optional argument formats the printed text.

\DescribeMacro{\usecommand}
The "\usecommand"\oarg{number of arguments}\marg{definition} helper defines a temporary command with the requested number of arguments and immediately applies it to the following arguments.

\printbibliography

\end{document}

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