%%
%% 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 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}[2022/11/01 v1.1 hep-acronym documentation]

\RequirePackage[l2tabu, orthodox]{nag}
\documentclass{ltxdoc}
\AtBeginDocument{\DeleteShortVerb{\|}}
\AtBeginDocument{\MakeShortVerb{\"}}

\EnableCrossrefs
\CodelineIndex
\RecordChanges

\usepackage{hologo}
\usepackage[parskip]{hep-paper}

\bibliography{bibliography}

\acronym{PDF}{portable document format}

\MacroIndent=1.5em
\AtBeginEnvironment{macrocode}{\renewcommand{\ttdefault}{clmt}}

\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 an acronym macro based on the \software{glossaries} package.
\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{\acronym}
The "\acronym"\meta{*}\oarg{typeset abbreviation}\marg{abbreviation}\meta{*}\marg{definition}\oarg{plural\linebreak[4]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{\resetacronym}
\DescribeMacro{\dummyacronym}
The first use form of the acronym can be enforced by resetting the acronym counter with "\resetacronym"\marg{key}.

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.

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'.
