summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/hereapplies/hereapplies.sty
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/hereapplies/hereapplies.sty')
-rw-r--r--macros/latex/contrib/hereapplies/hereapplies.sty585
1 files changed, 346 insertions, 239 deletions
diff --git a/macros/latex/contrib/hereapplies/hereapplies.sty b/macros/latex/contrib/hereapplies/hereapplies.sty
index 61ee402956..ba13cdb9a7 100644
--- a/macros/latex/contrib/hereapplies/hereapplies.sty
+++ b/macros/latex/contrib/hereapplies/hereapplies.sty
@@ -1,4 +1,4 @@
-% -*- Mode: latex; indent-tabs-mode: t; c-basic-offset: 4; tab-width: 4 -*-
+% -*- Mode: latex; indent-tabs-mode: nil; c-basic-offset: 4; tab-width: 4 -*-
%
%
% hereapplies.sty
@@ -8,7 +8,7 @@
%
% https://github.com/madmurphy/hereapplies.sty
%
-% Version 0.6.0
+% Version 0.7.0
%
% Copyright (C) 2022 madmurphy <madmurphy333@gmail.com>
%
@@ -47,26 +47,26 @@
% This is concept two. To find this concept applied, please
% see \whereapplies{conceptTwo}.\newpage
%
-% \hereapplies{conceptOne}This is page \thepage. As you can see, ``concept
-% one'' applies here.\newpage
+% \hereapplies{conceptOne} This is page \thepage. As you can see,
+% ``concept one'' applies here.\newpage
%
-% \hereapplies{conceptTwo}This is page \thepage. As you can see, ``concept
-% two'' applies here.\newpage
+% \hereapplies{conceptTwo} This is page \thepage. As you can see,
+% ``concept two'' applies here.\newpage
%
-% \hereapplies{conceptOne,conceptTwo}This is page \thepage. As you
+% \hereapplies{conceptOne, conceptTwo} This is page \thepage. As you
% can see, both ``concept one'' and ``concept two'' apply here.\newpage
%
-% \hereapplies{conceptTwo}This is page \thepage. As you can see, ``concept
-% two'' applies here.\newpage
+% \hereapplies{conceptTwo} This is page \thepage. As you can see,
+% ``concept two'' applies here.\newpage
%
-% \hereapplies[myref]{conceptOne}This is page \thepage. As you can
+% \hereapplies[myref]{conceptOne} This is page \thepage. As you can
% see, ``concept one'' applies here. This point in the document is
% labeled \texttt{myref}.
%
% \end{document}
%
%
-\ProvidesPackage{hereapplies}[2022/08/23 Here Applies]
+\ProvidesPackage{hereapplies}[2022/08/29 Here Applies]
\RequirePackage{hyperref}
\RequirePackage{refcount}
%
@@ -77,118 +77,207 @@
%
%
% The abbreviation of one single page
-\providecommand{\hapage}{p.\ }
+\providecommand*{\hapage}{p.\ }
% The abbreviation of two or more pages
-\providecommand{\hapages}{pp.\ }
+\providecommand*{\hapages}{pp.\ }
% The delimiter between page numbers
-\providecommand{\hadelimiter}{,\ }
+\providecommand*{\hadelimiter}{,\ }
% The delimiter before the last page number
-\providecommand{\halastdelimiter}{\ and\ }
+\providecommand*{\halastdelimiter}{\ and\ }
+%
+%
+%
+% ABSTRACT UTILITIES
+% ==================
+%
+% These macros are not strictly related to this package, but are required.
+%
+%
+% Macro: `\@ha@ifcomma text to check,\@then{if yes}{if no}`
+% *****************************************************************************
+%
+% Check if a string contains a comma
+%
+% This macro is mainly for internal purposes (but nothing forbids invoking it
+% directly). When invoked it checks whether a comma is present in `text to
+% check`, then expands to `if yes` or `if no` accordingly.
+
+% Please do not put curly brackets around the text to check. The comma at the
+% end of the text is mandatory.
+%
+\long\gdef\@ha@ifcomma#1,#2\@then#3#4{%
+ \if\relax\detokenize{#2}\relax#4\else#3\fi%
+}
+%
+%
+% Macro: `\ha@trim{text}`
+% *****************************************************************************
+%
+% Trim leading and trailing spaces from a string
+%
+% This macro is mainly for internal purposes (but nothing forbids invoking it
+% directly).
+%
+\begingroup
+% Temporarily change the categories of `<` and `>`, for trimming safely
+\catcode`\<=4\catcode`\>=3
+% Helper macro
+\long\gdef\@ha@trm< #1 >< #2 >< #3 >< #4 >< #5 >< #6 >< #7 >< #8 >< #9 >/{%
+ \ifcase\numexpr2#3#8\relax\or#2\or#7\or#5\or#1\fi%
+}
+% Usable macro
+\long\gdef\ha@trim#1{%
+ \@ha@trm< #1 >< #1>< - >< + >< ? ><#1 ><#1>< 0 >< 2 >< 1 >< 3 >< 2 >< ! >/%
+}
+\endgroup
%
%
%
% PRIVATE ENVIRONMENT
% ===================
%
+% These macros regulate the internal functioning of the package and should not
+% be invoked directly.
+%
%
-% Assign a unique number to each identifier
-\newcounter{@ha@identifier@counter}
-% Assign a unique number to each unnamed occurrence of an identifier
+% Assign a unique number to each unlabeled occurrence of an identifier
\newcounter{@ha@unlabeled@counter}
%
%
-% Macro `\@ha@makeoccurrencelist{hypermacro}{labels}`
+% Macro `\@ha@makepagelist{hypermacro}{labels}`
% *****************************************************************************
%
% Generate the list of page numbers (with page range support)
%
-% This macro is for internal purposes. When invoked, it scans the
+% This macro is for internal purposes only. When invoked, it scans the
% comma-separated list of labels provided (`labels`), checks which labels refer
% to duplicate page numbers and which page numbers can be grouped together, and
% finally prints a list.
%
-% The `hypermacro` argument is the macro from the `hyperref` package that will
-% process the label name. This should be either `T@pageref` -- equivalent to
-% `\pageref` -- or `@pagerefstar` -- equivalent to `\pageref*`.
-%
-% The `labels` must be a comma-separated list of labels.
-%
-\newcommand{\@ha@makeoccurrencelist}[2]{%
- % Reset the current page number
- \def\@ha@tmp@@currp{-1}%
- % Reset the current range offset
- \def\@ha@tmp@@prangeoffs{-1}%
- % Ensure no comma before the first page number
- \def\@ha@tmp@@psep{}%
- % Ensure no text before the last page number if it is also the first one
- \def\@ha@tmp@@lastpsep{}%
- % Iterate through the `labels` argument
- \@for\@ha@tmp@@thislabel:=#2\do{%
- % Store the page number associated with this label
- \edef\@ha@tmp@@nextp{\getpagerefnumber{\@ha@tmp@@thislabel}}%
- % Check that we are not on the same page as in the last iteration
- \unless\ifnum\@ha@tmp@@currp=\@ha@tmp@@nextp%
- % This is not the same page as in the last iteration
- % Is this the first page in which this identifier appears?
- \unless\ifnum\@ha@tmp@@currp=-1%
- % This is not the first page in which this identifier appears
- % Does this page follow immediately the previous label's page?
- \ifnum\numexpr\@ha@tmp@@currp+1=\@ha@tmp@@nextp%
- % This page follows immediately the previous label's page
- % Are these the first contiguous pages that we encounter?
- \ifnum\@ha@tmp@@prangeoffs=-1%
- % These are the first contiguous pages we encounter
- % Store the first page number of the pair
- \edef\@ha@tmp@@prangeoffs{\@ha@tmp@@currp}%
- % Store the first label of the pair
- \edef\@ha@tmp@@currrangelbl{\@ha@tmp@@currlbl}%
- \fi%
- \else%
- % This page is far from the previous label's page
- % Was the previous page part of a contiguous range?
- \ifnum\@ha@tmp@@prangeoffs=-1%
- % The previous page was a standalone page
- % Print "[, ]<p>"
- {\@ha@tmp@@psep\csname
- #1\endcsname{\@ha@tmp@@currlbl}}%
- \else%
- % The previous page was part of a contiguous range
- % Print "[, ]<p--q>"
- {\@ha@tmp@@psep\csname
- #1\endcsname{\@ha@tmp@@currrangelbl}--\csname
- #1\endcsname{\@ha@tmp@@currlbl}}%
- % Reset the current range offset
- \def\@ha@tmp@@prangeoffs{-1}%
- \fi%
- % Ensure a comma before the next page number
- \let\@ha@tmp@@psep\hadelimiter%
- % Ensure " and " before the last page number
- \let\@ha@tmp@@lastpsep\halastdelimiter%
- \fi%
- \fi%
- % Prepare the next page number
- \edef\@ha@tmp@@currp{\@ha@tmp@@nextp}%
- % Prepare the next label
- \edef\@ha@tmp@@currlbl{\@ha@tmp@@thislabel}%
- \fi%
- }%
- % Print the last page number
- % Is there at least one page to print?
- \unless\ifnum\@ha@tmp@@currp=-1%
- % There is at least one page to print
- % Was the previous page part of a contiguous range?
- \ifnum\@ha@tmp@@prangeoffs=-1%
- % The previous page was a standalone page
- % Print "[ and ]<p>"
- {\@ha@tmp@@lastpsep\csname #1\endcsname{\@ha@tmp@@currlbl}}%
- \else%
- % The previous page was part of a contiguous range
- % Print "[ and ]<p--q>"
- {\@ha@tmp@@lastpsep\csname
- #1\endcsname{\@ha@tmp@@currrangelbl}--\csname
- #1\endcsname{\@ha@tmp@@currlbl}}%
- \fi%
- \fi%
+% The `hypermacro` argument is the macro (usually from the `hyperref` package)
+% that will process the label name.
+%
+% The `labels` argument must be a comma-separated list of labels.
+%
+\gdef\@ha@makepagelist#1#2{%
+ \begingroup%
+ % Reset the current page number
+ \def\@ha@tmp@@currp{-1}%
+ % Reset the current range offset
+ \def\@ha@tmp@@prangeoffs{-1}%
+ % Ensure no comma before the first page number
+ \def\@ha@tmp@@psep{}%
+ % Ensure no text before the last number if it is also the first one
+ \def\@ha@tmp@@lastpsep{}%
+ % Iterate through the `labels` argument
+ \@for\@ha@tmp@@thislabel:=#2\do{%
+ % Store the page number associated with this label
+ \edef\@ha@tmp@@nextp{\getpagerefnumber{\@ha@tmp@@thislabel}}%
+ % Check that we are not on the same page as in the last iteration
+ \ifnum\@ha@tmp@@currp=\@ha@tmp@@nextp\else%
+ % This is not the same page as in the last iteration
+ % Is this the first page in which this identifier appears?
+ \ifnum\@ha@tmp@@currp>-1%
+ % We have already met pages in which this identifiers appears
+ % Does this page follow immediately the previous page?
+ \ifnum\numexpr\@ha@tmp@@currp+1=\@ha@tmp@@nextp%
+ % This page follows immediately the previous page
+ % Are these the first two contiguous pages of the range?
+ \ifnum\@ha@tmp@@prangeoffs=-1%
+ % These are the first two contiguous pages of the range
+ % Store the first page number of the pair
+ \let\@ha@tmp@@prangeoffs\@ha@tmp@@currp%
+ % Store the first label of the pair
+ \let\@ha@tmp@@currrangelbl\@ha@tmp@@currlbl%
+ \fi%
+ \else%
+ % This page is far from the previous label's page
+ % Was the previous page part of a contiguous range?
+ \ifnum\@ha@tmp@@prangeoffs=-1%
+ % The previous page was a standalone page
+ % Print "[, ]<p>"
+ {\@ha@tmp@@psep\csname
+ #1\expandafter\endcsname%
+ \expandafter{\@ha@tmp@@currlbl}}%
+ \else%
+ % The previous page was part of a contiguous range
+ % Print "[, ]<p--q>"
+ {\@ha@tmp@@psep\csname
+ #1\expandafter\endcsname%
+ \expandafter{\@ha@tmp@@currrangelbl}--\csname
+ #1\expandafter\endcsname%
+ \expandafter{\@ha@tmp@@currlbl}}%
+ % Reset the current range offset
+ \def\@ha@tmp@@prangeoffs{-1}%
+ \fi%
+ % Ensure a comma before the next page number
+ \let\@ha@tmp@@psep\hadelimiter%
+ % Ensure " and " before the last page number
+ \let\@ha@tmp@@lastpsep\halastdelimiter%
+ \fi%
+ \fi%
+ % Prepare the next page number
+ \let\@ha@tmp@@currp\@ha@tmp@@nextp%
+ % Prepare the next label
+ \let\@ha@tmp@@currlbl\@ha@tmp@@thislabel%
+ \fi%
+ }%
+ % Print the last page number
+ % Is there at least one page to print?
+ \ifnum\@ha@tmp@@currp>-1%
+ % There is at least one page to print
+ % Was the previous page part of a contiguous range?
+ \ifnum\@ha@tmp@@prangeoffs=-1%
+ % The previous page was a standalone page
+ % Print "[ and ]<p>"
+ {\@ha@tmp@@lastpsep\csname
+ #1\expandafter\endcsname%
+ \expandafter{\@ha@tmp@@currlbl}}%
+ \else%
+ % The previous page was part of a contiguous range
+ % Print "[ and ]<p--q>"
+ {\@ha@tmp@@lastpsep\csname
+ #1\expandafter\endcsname%
+ \expandafter{\@ha@tmp@@currrangelbl}--\csname
+ #1\expandafter\endcsname%
+ \expandafter{\@ha@tmp@@currlbl}}%
+ \fi%
+ \fi%
+ \endgroup%
+}
+%
+%
+% Macro `\@ha@makeoutputstrings{identifier}{preamble}{labels}`
+% *****************************************************************************
+%
+% Generate the output strings of `\whereapplies` and `\whereapplies*`
+%
+% This macro is for internal purposes only. When invoked, it updates the two
+% macros `@ha@prop@@soutput@...` and `@ha@prop@@doutput@...`.
+%
+% The `identifier` argument remains confined within the internal scope of the
+% package and does not create conflicts with possible macros or labels of the
+% same name. Leading and trailing spaces around this string will **not** be
+% ignored.
+%
+% The `preamble` argument is the text that will be expanded before the page
+% list (usually "p." or "pp.").
+%
+% The `labels` argument must be a comma-separated list of labels.
+%
+\gdef\@ha@makeoutputstrings#1#2#3{%
+ % Write "p./pp. \pageref..." to the output
+ \expandafter\gdef\csname @ha@prop@@doutput@#1\endcsname{%
+ % `\T@pageref` is a synonym of `\pageref`
+ #2\@ha@makepagelist{T@pageref}{#3}%
+ }%
+ % Write "p./pp. \pageref*..." to the starred output
+ \expandafter\gdef\csname @ha@prop@@soutput@#1\endcsname{%
+ % `\@pagerefstar` is a synonym of `\pageref*`
+ #2\@ha@makepagelist{@pagerefstar}{#3}%
+ }%
+ % Make the list of labels available to the API (via `\get@hainfo`)
+ \expandafter\gdef\csname @ha@prop@@labels@#1\endcsname{#3}%
}
%
%
@@ -202,151 +291,168 @@
% identifier. If the identifier was already initialized the macro will be no
% op.
%
-% The `identifier` argument may contain only Latin letters and the "at" sign
-% (`/^[A-Za-z@]+$/`). This string remains confined within the internal scope of
-% the package and does not create conflicts with possible macros or labels of
-% the same name.
-%
-\newcommand{\@ha@newidentifier}[1]{%
- % Was this identifier already initialized?
- \unless\ifcsname @ha@prop@@count@#1\endcsname%
- % The identifier was never initialized
- % Set the output to "??" - it will be updated by the .haN file
- \expandafter\gdef\csname @ha@prop@@uoutput@#1\endcsname{\textbf{??}}%
- % Set the starred output to "??" - it will be updated by the .haN file
- \expandafter\gdef\csname @ha@prop@@soutput@#1\endcsname{\textbf{??}}%
- % Use "p." for the preamble when there is only one occurrence
- \global\expandafter\let\csname @ha@prop@@preamble@#1\endcsname\hapage%
- % Increase the counter of identifiers
- \stepcounter{@ha@identifier@counter}%
- % Store the current value of the counter of identifiers
- \expandafter\xdef\csname
- @ha@prop@@count@#1\endcsname{\the@ha@identifier@counter}%
- % Initialize the .haN file
- % Previous versions had this line, which created unwanted whitespaces:
- %\@starttoc{ha\csname @ha@prop@@count@#1\endcsname}%
- % I am thankful to David Carlisle for the following replacement:
- {\endlinechar=\m@ne\@starttoc{ha\csname @ha@prop@@count@#1\endcsname}}%
- % Store all the occurrences when the document reaches the end
- \AtEndDocument{%
- % Make sure that there are occurrences
- \ifcsname @ha@prop@@labels@#1\endcsname%
- % There are occurrences
- % Set the .haN file as output
- \addtocontents{ha\csname @ha@prop@@count@#1\endcsname}{%
- % Write "p./pp. \pageref..." to the output
- \gdef\expandafter\protect\csname @ha@prop@@uoutput@#1\endcsname{%
- % Preamble (either "p." or "pp.")
- \csname @ha@prop@@preamble@#1\endcsname%
- % `\T@pageref` is a synonym of `\pageref`
- \expandafter\protect\csname
- @ha@makeoccurrencelist\endcsname{T@pageref}{\csname
- @ha@prop@@labels@#1\endcsname}%
- }%
- % Write "p./pp. \pageref*..." to the starred output
- \gdef\expandafter\protect\csname @ha@prop@@soutput@#1\endcsname{%
- % Preamble (either "p." or "pp.")
- \csname @ha@prop@@preamble@#1\endcsname%
- % `\@pagerefstar` is a synonym of `\pageref*`
- \expandafter\protect\csname
- @ha@makeoccurrencelist\endcsname{@pagerefstar}{\csname
- @ha@prop@@labels@#1\endcsname}%
- }%
- }%
- \fi%
- }%
- \fi%
+% The `identifier` argument remains confined within the internal scope of the
+% package and does not create conflicts with possible macros or labels of the
+% same name. Leading and trailing spaces around this string will **not** be
+% ignored.
+%
+\gdef\@ha@newidentifier#1{%
+ % Was this identifier already initialized?
+ \ifcsname @ha@iter@@preamble@#1\endcsname\else%
+ % The identifier was never initialized
+ % Was the .hax input already initialized during this run?
+ \ifdefined\@ha@commons@@haxcontent\else%
+ % The .hax input was never initialized
+ % Previous versions created unwanted whitespaces; I am thankful to
+ % David Carlisle for suggesting `\endlinechar=\m@ne`
+ {\endlinechar=\m@ne\@starttoc{hax}}%
+ % Initialize the content to export to the .hax file
+ \gdef\@ha@commons@@haxcontent{}%
+ % Export the content when the document reaches the end
+ \AtEndDocument{%
+ \addtocontents{hax}{\@ha@commons@@haxcontent}%
+ }%
+ \fi%
+ % Was a .hax file already exported during a previous run?
+ \ifcsname @ha@prop@@labels@#1\endcsname\else%
+ % This is the first run
+ % Set the output to "??" - to be updated by the .hax file
+ \expandafter\gdef\csname
+ @ha@prop@@doutput@#1\endcsname{\textbf{??}}%
+ % Set the starred output to "??" - to be updated by the .hax file
+ \expandafter\gdef\csname
+ @ha@prop@@soutput@#1\endcsname{\textbf{??}}%
+ % Set the list of labels to an empty value
+ \expandafter\gdef\csname @ha@prop@@labels@#1\endcsname{}%
+ \fi%
+ % Use "p." for the preamble when there is only one occurrence
+ \global\expandafter\let\csname @ha@iter@@preamble@#1\endcsname\hapage%
+ % Generate the output strings
+ \g@addto@macro\@ha@commons@@haxcontent{%
+ % Make sure that there are occurrences
+ \ifcsname @ha@iter@@labels@#1\endcsname%
+ % There are occurrences
+ % Generate the output strings
+ \protect\@ha@makeoutputstrings{#1}{\csname
+ @ha@iter@@preamble@#1\endcsname}{\csname
+ @ha@iter@@labels@#1\endcsname}%
+ \fi%
+ }%
+ \fi%
}
%
%
-% Macro: `\@ha@getpropat{field}{identifier}`
-% *****************************************************************************
%
-% Get the value of an identifier's property
+% LIBRARY ENVIRONMENT
+% ===================
%
-% This macro is for internal purposes (but nothing forbids invoking it
-% directly). If the identifier was never initialized the macro will initialize
-% it.
+% These macros are not directly available to the user, but are callable by
+% other packages, if needed.
+%
+%
+% Macro: `\starred@labeled@hereapplies{label}{identifiers}`
+% *****************************************************************************
%
-% Possible values for the `field` argument are: `count`, `labels`, `preamble`,
-% `soutput`, `uoutput`.
+% Identical to `\hereapplies*`, but the two arguments are both mandatory
%
-% The `identifier` argument may contain only Latin letters and the "at" sign
-% (`/^[A-Za-z@]+$/`). This string remains confined within the internal scope of
-% the package and does not create conflicts with possible macros or labels of
-% the same name.
+% This macro is mainly for internal purposes (but nothing forbids invoking it
+% directly). See the documentation of `\hereapplies` for more information.
%
-\newcommand{\@ha@getpropat}[2]{%
- % Make sure that the identifier is initialized
- \@ha@newidentifier{#2}%
- % Print the identifier's property
- \csname @ha@prop@@#1@#2\endcsname%
+\newcommand*{\starred@labeled@hereapplies}[2]{%
+ \begingroup%
+ % Assign a label to this occurrence
+ \label{#1}%
+ % Iterate through the comma-separated list `identifiers`
+ \@for\@ha@tmp@@litem:=#2\do{%
+ % Remove trailing and leading spaces
+ \edef\@ha@tmp@@id{\expandafter\ha@trim\expandafter{\@ha@tmp@@litem}}%
+ % Make sure that the identifier is initialized
+ \expandafter\@ha@newidentifier\expandafter{\@ha@tmp@@id}%
+ % Is this the first time this identifier is mentioned?
+ \ifcsname @ha@iter@@labels@\@ha@tmp@@id\endcsname%
+ % This is *not* the first time this identifier is mentioned
+ % Add this label to the list
+ \expandafter\g@addto@macro\csname
+ @ha@iter@@labels@\@ha@tmp@@id\endcsname{,#1}%
+ % Use "pp." for the preamble when there are multiple occurrences
+ \global\expandafter\let\csname
+ @ha@iter@@preamble@\@ha@tmp@@id\endcsname\hapages%
+ \else%
+ % This is the first time this identifier is mentioned
+ % Set up the list with this label as value
+ \expandafter\gdef\csname
+ @ha@iter@@labels@\@ha@tmp@@id\endcsname{#1}%
+ \fi%
+ }%
+ \endgroup%
}
%
%
-% Macro: `\starred@labeled@hereapplies{label}{identifiers}`
+% Macro: `\starred@hereapplies[label]{identifiers}`
% *****************************************************************************
%
-% Equivalent to `\hereapplies*`, but the two arguments are both mandatory
+% Identical to `\hereapplies*`
%
-% This macro is for internal purposes (but nothing forbids invoking it
+% This macro is mainly for internal purposes (but nothing forbids invoking it
% directly). See the documentation of `\hereapplies` for more information.
%
-\newcommand{\starred@labeled@hereapplies}[2]{%
- % Assign a label to this occurrence
- \label{#1}%
- % Iterate through the comma-separated list `identifiers`
- \@for\@ha@tmp@@id:=#2\do{%
- % Make sure that the identifier is initialized
- {\edef\tmp{\noexpand\@ha@newidentifier{\@ha@tmp@@id}}\tmp}%
- % Is this the first time this identifier is mentioned?
- \ifcsname @ha@prop@@labels@\@ha@tmp@@id\endcsname%
- % This is *not* the first time this identifier is mentioned
- % Add this label to the list
- \expandafter\g@addto@macro\csname
- @ha@prop@@labels@\@ha@tmp@@id\endcsname{,#1}%
- % Use "pp." for the preamble when there are multiple occurrences
- \global\expandafter\let\csname
- @ha@prop@@preamble@\@ha@tmp@@id\endcsname\hapages%
- \else%
- % This is the first time this identifier is mentioned
- % Set up the list with this label as value
- \expandafter\gdef\csname
- @ha@prop@@labels@\@ha@tmp@@id\endcsname{#1}%
- \fi%
- }%
+\newcommand*{\starred@hereapplies}[2][]{%
+ % Check whether the macro has been called with one or two arguments
+ \if\relax\detokenize{#1}\relax%
+ % The macro has been called with only one argument
+ % Assign a unique number to the unnamed occurrence
+ \stepcounter{@ha@unlabeled@counter}%
+ % Call `\starred@hereapplies` with an opaque label
+ {\edef\@ha@tmp@@mcall{\noexpand\starred@labeled@hereapplies{%
+ hereapplies:unnamed\the@ha@unlabeled@counter}{#2}%
+ }\@ha@tmp@@mcall}%
+ \else%
+ % The macro has been called with two arguments
+ % Call `\starred@labeled@hereapplies` with the same arguments
+ \starred@labeled@hereapplies{#1}{#2}%
+ \fi%
}
%
%
-% Macro: `\starred@hereapplies[label]{identifiers}`
+% Macro: `\get@hainfo[property]{identifier}`
% *****************************************************************************
%
-% Equivalent to `\hereapplies*`
+% Get the value of an identifier's property
%
-% This macro is for internal purposes (but nothing forbids invoking it
-% directly). See the documentation of `\hereapplies` for more information.
+% This macro is mainly for internal purposes (but nothing forbids invoking it
+% directly). If the identifier was never initialized the macro will initialize
+% it.
%
-\newcommand{\starred@hereapplies}[2][]{%
- % Check whether the macro has been called with one or two arguments
- \if\relax\detokenize{#1}\relax%
- % The macro has been called with only one argument
- % Assign a unique number to the unnamed occurrence
- \stepcounter{@ha@unlabeled@counter}%
- % Call `\starred@hereapplies` with an opaque label
- {\edef\tmp{\noexpand\starred@labeled@hereapplies{%
- hereapplies:unnamed\the@ha@unlabeled@counter}{#2}%
- }\tmp}%
- \else%
- % The macro has been called with two arguments
- % Call `\starred@labeled@hereapplies` with the same arguments
- \starred@labeled@hereapplies{#1}{#2}%
- \fi%
+% Possible values for the `property` argument are: `doutput`, `labels` and
+% `soutput`. When omitted it defaults to `labels`.
+%
+% The `identifier` argument remains confined within the internal scope of the
+% package and does not create conflicts with possible macros or labels of the
+% same name. Leading and trailing spaces around this string will be ignored.
+%
+\newcommand*{\get@hainfo}[2][labels]{%
+ \begingroup%
+ % Trim leading and trailing spaces from the identifier
+ \edef\@ha@tmp@@id{\ha@trim{#2}}%
+ % Make sure that there are no commas
+ \expandafter\@ha@ifcomma\@ha@tmp@@id,\@then{%
+ \PackageError{hereapplies}{Comma detected in "#2"}{%
+ It is possible to query only one single identifier at a time.%
+ }%
+ }{}%
+ % Make sure that the identifier is initialized
+ \expandafter\@ha@newidentifier\expandafter{\@ha@tmp@@id}%
+ % Print the identifier's property
+ \csname @ha@prop@@#1@\@ha@tmp@@id\endcsname%
+ \endgroup%
}
%
%
%
-% PUBLIC ENVIRONMENT
-% ===================
+% USER ENVIRONMENT
+% ================
+%
+% These macros are directly available to the user.
%
%
% Macro: `\hereapplies[label]{identifiers}`
@@ -356,20 +462,21 @@
% and add a label to it
%
% If the optional argument is passed the label created will be named
-% accordingly, otherwise an opaque name will be assigned to it. This argument
-% may contain only what is legal for `\pageref`.
+% accordingly, otherwise an opaque name will be chosen. This argument may
+% contain only what is legal for `\pageref`.
%
-% The `identifiers` argument must be a comma-separated list of identifiers.
-% Each of these may contain only Latin letters and the "at" sign (`@`). These
-% strings will remain confined within the internal scope of the package and
-% will not create conflicts with possible macros or labels of the same names.
+% The `identifiers` argument must be a comma-separated list of identifiers
+% (leading and trailing spaces around each member will be ignored). Each of
+% these strings will remain confined within the internal scope of the package
+% and will not create conflicts with possible macros or labels of the same
+% names.
%
-% The starred version of this macro (`\hereapplies*`) does not invoke the
+% The starred version of this command (`\hereapplies*`) will not invoke the
% `\phantomsection` directive.
%
-\newcommand{\hereapplies}{%
- % Check if a star is present in the invocation of the command
- \@ifstar{\starred@hereapplies}{\phantomsection\relax\starred@hereapplies}%
+\newcommand*{\hereapplies}{%
+ % Check if a star is present in the invocation of the command
+ \@ifstar{\starred@hereapplies}{\phantomsection\starred@hereapplies}%
}
%
%
@@ -377,21 +484,21 @@
% *****************************************************************************
%
% Print all the occurrences of an identifier in the form "p. ..." or "pp. ..."
-% with page range support
+% (with page range support)
%
-% The `identifier` argument may contain only Latin letters and the "at"
-% sign (`@`). This string will remain confined within the internal scope of the
-% package and will not create conflicts with possible macros or labels of the
-% same name.
+% The `identifier` argument remains confined within the internal scope of the
+% package and does not create conflicts with possible macros or labels of the
+% same name. Leading and trailing spaces around this string will be ignored.
%
% If the same `identifier` is not passed to `\hereapplies` at least once
% throughout the document, `\whereapplies` will print "??".
%
-% The starred version of this macro (`\whereapplies*`) will use `\pageref*`
+% The starred version of this command (`\whereapplies*`) will use `\pageref*`
% instead of `\pageref` for generating the page list.
%
-\newcommand{\whereapplies}{%
- % Check if a star is present in the invocation of the command
- \@ifstar{\@ha@getpropat{soutput}}{\@ha@getpropat{uoutput}}%
+\newcommand*{\whereapplies}{%
+ % Check if a star is present in the invocation of the command
+ \@ifstar{\get@hainfo[soutput]}{\get@hainfo[doutput]}%
}%
+% EOF