summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/hep-acronym/hep-acronym-implementation.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/hep-acronym/hep-acronym-implementation.dtx')
-rw-r--r--macros/latex/contrib/hep-acronym/hep-acronym-implementation.dtx524
1 files changed, 524 insertions, 0 deletions
diff --git a/macros/latex/contrib/hep-acronym/hep-acronym-implementation.dtx b/macros/latex/contrib/hep-acronym/hep-acronym-implementation.dtx
new file mode 100644
index 0000000000..c5e9c60cfa
--- /dev/null
+++ b/macros/latex/contrib/hep-acronym/hep-acronym-implementation.dtx
@@ -0,0 +1,524 @@
+% \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-acronym}[2021/08/01 v1.0 Acronyms using glossaries]
+%<documentation>\ProvidesFile{hep-acronym-documentation.tex}[2021/08/01 v1.0 hep-acronym documentation]
+%
+%<*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}}
+%</documentation>
+
+%<*driver>
+\expandafter\newif\csname ifshort\endcsname
+\shortfalse
+\begin{document}
+\DocInput{hep-acronym-implementation.dtx}
+\end{document}
+%</driver>
+%
+% \fi
+%
+% \CheckSum{354}
+%
+% \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.}
+%
+% \ifshort
+%<*documentation>
+% \fi
+%
+\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@unibas.ch}}
+\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-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 "\glsdesc*"\marg{abbreviation}.
+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 devises \eg "\glsdesc"\marg{abbreviation}, "\Glsdesc"\marg{abbreviation}.
+
+\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}".
+
+% \ifshort
+\printbibliography
+
+\end{document}
+%
+%</documentation>
+% \fi
+%
+% \StopEventually{
+% \printbibliography
+% \PrintChanges
+% }
+%
+% \appendix
+%
+% \section{Implementation}
+%
+%<*package>
+%
+% Load the base package \cite{glossaries, glossaries-extra} and set the abbreviation style.
+% \begin{macrocode}
+\RequirePackage[nostyles]{glossaries-extra}
+\setabbreviationstyle{long-hyphen-short-hyphen}
+% \end{macrocode}
+% Use the entry count feature.
+% \begin{macrocode}
+\glsenableentrycount
+\glssetcategoryattribute{abbreviation}{entrycount}{1}
+% \end{macrocode}
+% Provide macros for older "glossaries-extra" installations.
+% \begin{macrocode}
+\AtBeginDocument{
+ \@ifpackageloaded{hyperref}{
+ \providecommand{\glsxtrusefield}[2]{\@gls@entry@field{#1}{#2}}
+ \providecommand{\glsxtrsetfieldifexists}[3]{\glsdoifexists{#1}{#3}}
+ \providecommand{\gGlsXtrSetField}[3]{%
+ \glsxtrsetfieldifexists{#1}{#2}{%
+ \csgdef{glo@\glsdetoklabel{#1}@#2}{#3}%
+ }%
+ }
+% \end{macrocode}
+% Set hyperlinks from the abbreviation to their definition in the text.
+% \begin{macrocode}
+ \glssetcategoryattribute{abbreviation}{nohyperfirst}{true}
+ \renewcommand*{\glsdonohyperlink}[2]{{%
+ \glsxtrprotectlinks\edef\fieldvalue{%
+ \glsxtrusefield{\glslabel}{hastarget}%
+ }%
+ \ifdefstring\fieldvalue{true}{#2}{%
+ \gGlsXtrSetField{\glslabel}{hastarget}{true}%
+ \glsdohypertarget{#1}{#2}%
+ }%
+ }}
+ }{\providecommand{\pdfstringdefDisableCommands}[1]{}}
+}
+% \end{macrocode}
+%
+% \begin{macro}{\begin@sentence}
+% Mark the beginning of a paragraph as if it would follow a full stop using the \software{everyhook} package \cite{everyhook}.
+% \begin{macrocode}
+\RequirePackage[excludeor]{everyhook}
+\newcommand{\begin@sentence}{1001}
+\PushPostHook{par}{{\spacefactor=\begin@sentence}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\frenchspacing}
+% Adjust the "\frenchspacing" macro to be compatibel with this idea.
+% \begin{macrocode}
+\def\frenchspacing{%
+ \sfcode`\.\begin@sentence \sfcode`\?\begin@sentence
+ \sfcode`\!\begin@sentence \sfcode`\:\begin@sentence
+ \sfcode`\;\@m \sfcode`\,\@m
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\if@begin@of@sentence}
+% Provide a macro checking for the beginning of a sentence by examining the length of the preceeding space.
+% \begin{macrocode}
+\newcommand{\if@begin@of@sentence}[2]{\leavevmode\protecting{%
+ \ifboolexpr{ test {\ifnumcomp{\spacefactor}{=}{3000}} or%
+ test {\ifnumcomp{\spacefactor}{=}{2000}} or%
+ test {\ifnumcomp{\spacefactor}{=}{\begin@sentence}}%
+ }{#1}{#2}%
+}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\mathdef}
+% Provide a macro that allows to extend a macro definition into math mode using the \software{xparse} package \cite{xparse}.
+% \begin{macrocode}
+\RequirePackage{xparse}
+\ProvideDocumentCommand{\mathdef}{mO{0}m}{%
+ \expandafter\let\csname hep@text\string#1\endcsname=#1
+ \expandafter\newcommand\csname hep@math\string#1\endcsname[#2]{#3}
+ \DeclareRobustCommand#1{%
+ \ifmmode
+ \expandafter\let\expandafter\next\csname%
+ hep@math\string#1\endcsname%
+ \else
+ \expandafter\let\expandafter\next\csname%
+ hep@text\string#1\endcsname%
+ \fi
+ \next
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\acronym}
+% Define the "\acronym"\meta{*}\oarg{typeset abbreviation}\marg{abbreviation}\meta{*}\marg{definition}\oarg{plural\linebreak[4] definition} macro using the \software{xspace} \cite{xspace} and \software{amstext} \cite{amstext} packages.
+% \begin{enumerate}[nosep, label=\#\arabic*]
+% \item star for omitting the \enquote{s} in the short plural
+% \item optional typeset abbreviation
+% \item mandatory abbreviation
+% \item star for restoring the \hologo{TeX} default for space after text macros
+% \item mandatory long form
+% \item optional plural long form
+% \end{enumerate}
+% \begin{macrocode}
+\RequirePackage{xspace}
+\RequirePackage{amstext}
+\NewDocumentCommand{\acronym}{somsmo}{
+ \newabbreviation[
+ type=\acronymtype,
+ sort=#3,
+ \glsshortpluralkey=\IfBooleanTF{#1}{#3}{\IfNoValueTF{#2}{#3s}{#2s}},
+ longplural=\IfNoValueTF{#6}{#5s}{#6}
+ ]{#3}{\IfNoValueTF{#2}{#3}{#2}}{#5}
+% \end{macrocode}
+% Provide the singular acronym macro.
+% \begin{macrocode}
+ \expandafter\newcommand\csname#3\endcsname[1][]{%
+ \if@begin@of@sentence{%
+ \ifglsused{#3}{\cgls{#3}[##1]}{\cGls{#3}[##1]}%
+ }{\cgls{#3}[##1]}%
+ \ifnum\glsentrycurrcount{#3}>1\relax
+ \IfBooleanTF{#4}{}{\@\xspace}%
+ \else\@\xspace\fi
+ }
+% \end{macrocode}
+% Expand the singular acronym macro in \PDF labels.
+% \begin{macrocode}
+ \pdfstringdefDisableCommands{\expandafter\def\csname#3\endcsname{%
+ \IfNoValueTF{#2}{#3}{#2} }%
+ }
+% \end{macrocode}
+% Provide the singular acronym macro in math mode.
+% \begin{macrocode}
+ \expandafter\mathdef\csname#3\endcsname{%
+ \text{\glsxtrshort{#3}}\@gls@increment@currcount{#3}%
+ }
+% \end{macrocode}
+% Provide the plural acronym macro.
+% \begin{macrocode}
+ \expandafter\newcommand\csname#3s\endcsname[1][]{%
+ \if@begin@of@sentence{\cGlspl{#3}[##1]}{\cglspl{#3}[##1]}%
+ \IfBooleanTF{#4}{}{\@\xspace}%
+ }
+% \end{macrocode}
+% Expand the plural acronym macro in \PDF labels.
+% \begin{macrocode}
+ \pdfstringdefDisableCommands{\expandafter\def\csname#3s\endcsname{%
+ \IfBooleanTF{#1}{#3}{\IfNoValueTF{#2}{#3s}{#2s}} }%
+ }
+% \end{macrocode}
+% Provide the plural acronym macro in math mode.
+% \begin{macrocode}
+ \expandafter\mathdef\csname#3s\endcsname{%
+ \text{\glsxtrshortpl{#3}}\@gls@increment@currcount{#3}%
+ }
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\shortacronym}
+% The "\shortacronym" never expands into the long form.
+% \begin{macrocode}
+\NewDocumentCommand{\shortacronym}{somsmo}{
+% \end{macrocode}
+% Provide the singular acronym macro.
+% \begin{macrocode}
+ \expandafter\newcommand\csname#3\endcsname[1][]{%
+ \IfNoValueTF{#2}{#3}{#2}\IfBooleanTF{#4}{}{\@\xspace}##1%
+ }
+% \end{macrocode}
+% Expand the singular acronym macro in \PDF labels.
+% \begin{macrocode}
+ \pdfstringdefDisableCommands{\expandafter\def\csname#3\endcsname{%
+ \IfNoValueTF{#2}{#3}{#2} }%
+ }
+% \end{macrocode}
+% Provide the singular acronym macro in math mode.
+% \begin{macrocode}
+ \expandafter\mathdef\csname#3\endcsname{%
+ \text{\IfNoValueTF{#2}{#3}{#2}}%
+ }
+% \end{macrocode}
+% Provide the plural acronym macro.
+% \begin{macrocode}
+ \expandafter\newcommand\csname#3s\endcsname[1][]{%
+ \IfBooleanTF{#1}{#3}{\IfNoValueTF{#2}{#3s}{#2s}}%
+ \IfBooleanTF{#4}{}{\@\xspace}##1%
+ }
+% \end{macrocode}
+% Expand the plural acronym macro in \PDF labels.
+% \begin{macrocode}
+ \pdfstringdefDisableCommands{\expandafter\def\csname#3s\endcsname{%
+ \IfBooleanTF{#1}{#3}{\IfNoValueTF{#2}{#3s}{#2s}} }%
+ }
+% \end{macrocode}
+% Provide the plural acronym macro in math mode.
+% \begin{macrocode}
+ \expandafter\mathdef\csname#3s\endcsname{%
+ \text{\IfBooleanTF{#1}{#3}{\IfNoValueTF{#2}{#3s}{#2s}}}%
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\longacronym}
+% The "\longacronym" never shows the abbreviated form.
+% \begin{macrocode}
+\NewDocumentCommand{\longacronym}{somsmo}{
+% \end{macrocode}
+% Provide the singular acronym macro.
+% \begin{macrocode}acronyms
+ \expandafter\newcommand\csname#3\endcsname[1][]{%
+ \if@begin@of@sentence{\MakeUppercase#5}{#5}%
+ \IfBooleanTF{#4}{}{\@\xspace}##1%
+ }
+% \end{macrocode}
+% Expand the singular acronym macro in \PDF labels.
+% \begin{macrocode}
+ \pdfstringdefDisableCommands{\expandafter\def\csname#3\endcsname{#5 }}
+% \end{macrocode}
+% Provide the plural acronym macro.
+% \begin{macrocode}
+ \expandafter\newcommand\csname#3s\endcsname[1][]{%
+ \if@begin@of@sentence{%
+ \IfNoValueTF{#6}{\MakeUppercase#5s}{\MakeUppercase#6}%
+ }{%
+ \IfNoValueTF{#6}{#5s}{#6}}\IfBooleanTF{#4}{}{\@\xspace}##1%
+ }
+% \end{macrocode}
+% Expand the plural acronym macro in \PDF labels.
+% \begin{macrocode}
+ \pdfstringdefDisableCommands{\expandafter\def\csname#3s\endcsname{%
+ \IfNoValueTF{#6}{#5s}{#6} }%
+ }
+}
+% \end{macrocode}
+% \end{macro}
+% Silence warning if no acronyms are defined.
+% \begin{macrocode}
+\renewcommand*{\@gls@write@entrycounts}{%
+ \immediate\write\@auxout{%
+ \string\providecommand*{\string\@gls@entry@count}[2]{}
+ }%
+ \count@=0\relax
+ \forallglsentries{\@glsentry}{%
+ \glshasattribute{\@glsentry}{entrycount}{%
+ \ifglsused{\@glsentry}{%
+ \immediate\write\@auxout{%
+ \string\@gls@entry@count{\@glsentry}{%
+ \glsentrycurrcount{\@glsentry}%
+ }
+ }%
+ }{}\advance\count@ by \@ne
+ }{}%
+ }%
+}
+% \end{macrocode}
+% \begin{macro}{\resetacronym}
+% \begin{macro}{\dummyacronym}
+% Add two macros for acronym management.
+% \begin{macrocode}
+\newcommand{\resetacronym}[1]{\protect\glsreset{#1}}
+\newcommand{\dummyacronym}[1]{\protect\glsunset{#1}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{abstract}
+% Adjust the "abstract" environment to reset all acronym counters.
+% \begin{macrocode}
+\@ifundefined{endabstract}{}{%
+ \let\end@hep@abstract\endabstract%
+ \renewcommand\endabstract{\glsresetall\end@hep@abstract}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\tableofcontents}
+% \begin{macro}{\listoffigures}
+% \begin{macro}{\listoftables}
+% Adjust the "\tableofcontents" macro to never show the long form of acronyms.
+% \begin{macrocode}
+\let\hep@table@of@contents\tableofcontents
+\renewcommand\tableofcontents{%
+ \glsunsetall\hep@table@of@contents\glsresetall%
+}
+\let\hep@list@of@figures\listoffigures
+\renewcommand\listoffigures{%
+ \glsunsetall\hep@list@of@figures\glsresetall%
+}
+\let\hep@list@of@tables\listoftables
+\renewcommand\listoftables{%
+ \glsunsetall\hep@list@of@tables\glsresetall%
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\acronyms}
+% Add a possibility to have different groups of acronyms.
+% \begin{macrocode}
+\NewDocumentCommand{\acronyms}{om}{%
+ \IfNoValueTF{#1}{
+ \newglossary{#2}{#2.in}{#2.out}{#2}%
+ \renewcommand{\acronymtype}{#2}%
+ }{
+ \newglossary{#1}{#1.in}{#1.out}{#2}%
+ \renewcommand{\acronymtype}{#1}%
+ }
+}
+% \end{macrocode}
+% \end{macro}
+%
+%</package>
+%
+% \section{Test}
+%
+%<*test>
+% \begin{macrocode}
+\documentclass{article}
+
+% \usepackage{hep-paper}
+\usepackage{hyperref}
+\usepackage{hep-acronym}
+
+\acronym{PDF}{portable document format}
+\acronym{URL}{uniform resource locator}
+\acronym{CM}{computer modern}
+\acronym{LM}{latin modern}
+
+\begin{document}
+
+\PDF \emph{(Capitalised at beginning of paragraph)}
+\PDF \emph{(Second appearance is shortened)}.
+\URLs \emph{(Capitalised plural form at beginning of sentence)}
+$\URL$ \emph{(Second appearance is forced to be always short)}
+\LM \emph{(Not capitalised in middle of sentence)}
+\LM \emph{(Second appearance is shorted)}.
+$\CM$ \emph{(Enforce short form)}
+\CM \emph{(then extend second appearance)}
+\glsdesc*{CM} \emph{(enforce long form)}
+
+\end{document}
+% \end{macrocode}
+%
+%</test>
+%
+% \section{Readme}
+%
+%<*readme>
+%
+% \begin{macrocode}
+# The `hep-acronym` package
+
+An acronym extension for glossaries
+
+## Introduction
+
+The `hep-acronym` package provides an acronym macro based on the `glossaries` package.
+It can be loaded using `\usepackage{hep-acronym}`.
+
+## 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-acronym-implementation.gls hep-acronym-implementation.glo
+% makeindex -s gglo.ist -o hep-acronym-implementation.ind hep-acronym-implementation.idx