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

\GetFileInfo{hep-acronym.sty}

\title{The \software{hep-acronym} package\thanks{This document corresponds to \software{hep-acronym}~\fileversion.}}
\subtitle{An acronym extension for glossaries}
\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-acronym} package provides sentence-aware acronym helpers based on \software{glossaries-extra}.
It defines declaration commands for regular, always-short, always-long, and alternative long-form acronyms, optional links back to the first use, reset and dummy-use helpers, and support for several acronym groups.
\end{abstract}

Acronyms are implemented using the \software{glossaries-extra} package \cite{glossaries-extra} which is an extension of the \software{glossaries} package \cite{glossaries} and must be loaded after the \software{hyperref} package \cite{hyperref}.
It can be loaded using "\usepackage{hep-acronym}".

\DescribeMacro{hyper}
The "hyper" option controls whether later acronym uses link back to their first appearance.
It is enabled by default and can be deactivated with "hyper=false".

\DescribeMacro{\acronym}
The "\acronym"\meta{*}\oarg{typeset abbreviation}\marg{abbreviation}\meta{*}\marg{definition}\oarg{plural definition} macro generates the singular "\"\meta{abbreviation} and plural "\"\meta{abbreviation}"s" macros.

The first star prevents the addition of an \enquote{s} to the abbreviation plural.
The second star restores the \hologo{TeX} default of swallowing subsequent white space.
The long form is only shown at the first appearance of these macros, later appearances generate the abbreviation with a hyperlink to the long form.
Capitalisation at the beginning of paragraphs and sentences is (mostly) ensured.
The long form is never used in math mode which can be exploited to enforce the short form.
In order to enforce the long form use "\"\meta{abbreviation}"long".
As there can be no fixed rule whether to use the long form or the short form in section headers the user is left to their own devices \eg "\glsdesc"\marg{abbreviation}, "\Glsdesc"\marg{abbreviation}.
\DescribeMacro{\sentence}
The "\sentence" macro ensures that the directly following abbreviation is capitalised.

\DescribeMacro{\shortacronym}
\DescribeMacro{\longacronym}
The "\shortacronym" and "\longacronym" macros are drop-in replacements of the "\acronym" macro showing only the short or long form of their acronym.

\DescribeMacro{\acronymalternative}
The "\acronymalternative"\marg{acronym}\marg{name}\meta{*}\marg{alternative long form} macro defines an additional acronym macro that shares the use counter and short form of \meta{acronym} but prints the supplied long form at first use.

\DescribeMacro{\resetacronym}
The first use form of the acronym can be enforced by resetting the acronym counter with "\resetacronym"\marg{key}.

\DescribeMacro{\dummyacronym}
If the acronym counter equals one at the end of the document the short form of the acronym is not introduced.
Placing a "\dummyacronym"\marg{key} at the end of the document ensures that the short form is introduced.

\DescribeMacro{\acronyms}
The "\acronyms"\oarg{key}\marg{title} macro creates a new acronym glossary and switches subsequent declarations to it.
Without the optional argument the mandatory argument is used both as glossary key and printed title.

\DescribeMacro{warning}
In order to reduce the number of potentially conflicting packages the \software{glossaries} package is loaded without any glossary style.
In the case that the glossary should be printed additional packages must be loaded via \eg "\usepackage{glossary-list}".

\printbibliography

\end{document}

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