%%
%% \iffalse filename: toa.dtx \fi
%%
%<*doc>
\input driver
\thisis{toa}{Table of Authorities}

Legal briefs and other documents often include a Table of Authorities, listing
all of the references cited and the pages where those citations occur. One of
the motivations for creating this package was the automatic generation of
complete, correct, and properly formatted Tables of Authorities.

The table is generated using \LaTeX's auxiliary file feature. Citations generate
index lines that are written to a |\jobname.toa| file, and those lines are read,
sorted, and formatted to produce the table. Indexing can be disabled with
\DescribeMacro\HiEnableTOA
\DescribeMacro\HiDisableTOA
|\HiDisableTOA| and enabled with |\HiEnableTOA|.

A Table of Authorities is a complex structure, because it is typically sorted
into sections based on reference types. This section describes how references
are sorted into lists, how those lists get their headings, how page numbers in
the tables are displayed, and finally how the table is formatted.

%</doc>
%<*package>
%    \begin{macrocode}
\newif\if@hi@in@toa
\newif\if@hi@toa@disabled
\def\HiDisableTOA{\@hi@toa@disabledtrue}
\def\HiEnableTOA{\@hi@toa@disabledfalse}
%    \end{macrocode}
%</package>
%<*doc>

\subsection{Table of Authorities Categories}

\label{s:toa-categories}

Each reference type is associated with a category, used to organize the
Table of Authorities.
The category can be altered using the reference
definition parameter \param{toacat} or by the |\HiSetTOACat| macro.
The categories are used to assemble the headings for the table.

Specifically, every category has three properties:
\begin{enumerate}
\item A name for internal use.

\item A ``supercategory'' that associates the category with others that this
category should be joined with in the Table of Authorities. For example, the
categories for statutes and regulations should have the same supercategory, so
that they are placed in a single section with the Table of Authorities.
Supercategories are presented in alphabetical order.

\item A textual description of the category, for use in constructing the Table
of Authorities heading. Because both the singular and plural forms are needed,
the textual description consists of two to three parts, separated by slashes:
\begin{enumerate}
\item The base text common to both forms.
\item \relax[\emph{Optional}] Text to append to the singular form only.
\item Text to append to the plural form only.
\end{enumerate}
\end{enumerate}

\MacroSpec\HiNewTOACat\marg{name}\marg{supercat}\meta{text}\meta{include?}\\
Defines a new TOA category. The macro takes
four parameters, the first three corresponding to the three properties of
categories above, and the last (being ``Y'' or ``N'') indicating whether to
include the supercategory in the default table of authorities.

%</doc>
%<*package>
%
% TODO: The underlying implementation here could be improved to rely less on
% marker symbols. Also, categories should have a precedence number indicating
% the order in which they should appear in the TOA heading.
%
%    \begin{macrocode}
\def\HiNewTOACat#1#2#3#4{%
    \@namedef{hi@cats@#1}{#2:#3}%
    \ifx#4Y%
        \AddToList{hi@toacat@supercats}{#2}%
    \fi
}
%    \end{macrocode}
%
%
%</package>
%<*doc>

\subsubsection{Setting and Getting Categories}

\label{s:toa-set}

\MacroSpec\HiDefaultTOACat
Each reference type may have a default category, set with the
|\HiDefaultTOACat| macro. The parameters are \#1 the reference type, and
\#2 the category name. If the category name is blank, then there will be no
default category. This default category will be used unless another category
is specified for a particular reference, overriding the default category.

%</doc>
%<*package>
%    \begin{macrocode}
\def\HiDefaultTOACat#1#2{%
    \ifstrempty{#2}{%
        \cslet{hi@catd@#1}\relax
    }{%
        \@ifundefined{hi@cats@#2}{%
            \PackageError\hi@pkgname{%
                TOA category #2 does not exist, in setting the\MessageBreak
                default for reference type #1%
            }{Define TOA category #2 first with \string\HiNewTOACat}%
        }{%
            \@namedef{hi@catd@#1}{#2}%
        }%
    }%
}
%    \end{macrocode}
%</package>
%<*doc>

\MacroSpec\HiSetTOACat
\marg{reference}\marg{category} \\
Sets the TOA
category for \meta{reference}. This macro should be called within the
reference definer macros to set the category, or it is invoked by the
\param{toacat} parameter. If it is called multiple times, then the last
category will prevail. If it is not called, then the reference will not appear
in the table. If \meta{category} is empty, then any previously set category
will be removed.

%</doc>
%<*package>
%
%    \begin{macrocode}
\def\HiSetTOACat#1#2{%
    \ifstrempty{#2}{%
        \global\cslet{hi@cat@#1}\relax
    }{%
        \@ifundefined{hi@cats@#2}{%
            \PackageError\hi@pkgname{%
                Invalid Table of Authorities category #1,\MessageBreak
                given for reference #2%
            }{%
                Please enter a valid Table of Authorities category.
            }%
        }{%
            \global\csletcs{hi@cat@#1}{hi@cats@#2}%
        }%
    }
}
%    \end{macrocode}
%
% Retrieves the TOA category for a reference |#1|, and executes a callback |#2|
% with the category text as an argument. If the reference has no category, then
% the callback will not be executed.
%
%    \begin{macrocode}
\def\hi@toacat@get#1#2{%
    \@ifundefined{hi@cat@#1}{}{%
        \@expand{#2}{\csname hi@cat@#1\endcsname}{ii}%
    }%
}
%    \end{macrocode}
%
% Transfers a reference's category to another reference. \#1 is the reference
% with the already-defined category; \#2 is the reference to receive the
% category. The category for \#1 is deleted.
%
%    \begin{macrocode}
\def\hi@toacat@transfer#1#2{%
    \global\csletcs{hi@cat@#2}{hi@cat@#1}%
    \global\cslet{hi@cat@#1}\relax
}
%    \end{macrocode}
%
% Sets a reference's TOA category to the reference type's default category. \#1
% is the reference name, and \#2 the reference type. The category will not be
% changed if it is already set, or if the reference type has no default
% category.
%
%    \begin{macrocode}
\def\hi@toacat@setdefault#1#2{%
    \@ifundefined{hi@cat@#1}{%
        \@ifundefined{hi@catd@#2}{}{%
            \HiSetTOACat{#1}{\csname hi@catd@#2\endcsname}%
        }%
    }{}%
}
%    \end{macrocode}
%
%
% \subsubsection{Supercategories}
%
% Supercategories are stored in a sorted list (see \sec{hisort}), which is
% sorted alphabetically.
%
%    \begin{macrocode}
\NewSortedList{hi@toacat@supercats}{\SortEasyAlpha}{\StripForAlpha{#1}{\def#2}}
\ListElementsMustBeUnique{hi@toacat@supercats}
%    \end{macrocode}
%
%
%
%
% \subsubsection{Predefined Categories}
%
% Definitions of the categories follow in the source code, but they are used to
% produce a table in the documentation, so please consult the package file for
% the code.
%
%</package>
%<*doc>

The following are the TOA categories, with their supercategories and display
texts as described above. Note the choice of supercategory names, which
coincidentally sort alphabetically in the correct order. Because the actual
supercategory names are never displayed, any new supercategories can be named to
fit into the existing ordering.

\begin{demo}
\def\HiNewTOACat#1#2#3#4{#1&#2&#3&#4\\}
\begin{tabular}{llll}
\textbf{Category} & \textbf{Supercat.} & \textbf{Text} & \textbf{In TOA?} \\
\hline
%</doc>
%<*doc|package>
\HiNewTOACat{other}{other}{Other Source/s}{Y}
\HiNewTOACat{const}{const}{Constitutional Provision/s}{Y}
\HiNewTOACat{found}{const}{Foundational Document/s}{Y}
\HiNewTOACat{statute}{edict}{Statute/s}{Y}
\HiNewTOACat{regulation}{edict}{Regulation/s}{Y}
\HiNewTOACat{rule}{edict}{Rule/s}{Y}
\HiNewTOACat{case}{case}{Case/s}{Y}
\HiNewTOACat{admin}{case}{Administrative Decision/s}{Y}
\HiNewTOACat{treaty}{edict}{Treat/y/ies}{Y}
\HiNewTOACat{abbrev}{abbrev}{Abbreviation/s}{N}
%</doc|package>
%<*doc>
\end{tabular}
\end{demo}


%</doc>
%<*package>
%
% \DescribeMacro\hi@toacat@each
% This macro will perform a function for each of the Table of Authorities
% groups, in the proper order. The function should be given as a macro
% definition in \#1, the macro definition accepting one argument which will be
% the supercategory name.
%
%    \begin{macrocode}
\long\def\hi@toacat@each#1{%
    %
    % Unfortunately, this macro is used to iterate over items in the TOA, which
    % also stores items in SortedLists. So we can't just use \ShowList directly
    % since \ShowList can't be used in a nested fashion. So instead, we iterate
    % over the supercategory list to construct a series of macro expansions of
    % the given parameter, and then execute that series.
    %
    \begingroup % Will be ended when \reserved@a runs
    \def\hi@toacat@temp{\endgroup}%
    \def\hi@toacat@do##1{#1}%
    \ShowList{hi@toacat@supercats}{%
        \@expand{\appto\hi@toacat@temp}{\hi@toacat@do{##1}}{i}%
    }%
    \hi@toacat@temp
}
%    \end{macrocode}
%
%</package>
%<*doc>

\subsection{Altering Categories in a Document}

It may be useful to alter the TOA categories in a document, to create new
categories or recategorize certain references or reference types. The macros
described above allow for that. The following is a how-to guide on achieving a
few such effects.

\textbf{Place one reference in a different part of the TOA}: use the
\param{toacat} parameter when defining that reference.

\textbf{Remove a reference from the TOA}: use the \param{notoa}
parameter, or set the \param{toacat} parameter to blank.

\textbf{Place all references of a given type in a different part of the
TOA} (e.g., treat \rtype{modelcode} references like statutes): Use
\begin{grammar}
|\HiDefaultTOACat|\marg{type}\marg{category}
\Example
|\HiDefaultTOACat{modelcode}{statute}|
\end{grammar}
where \meta{category} is chosen from the table above.

\textbf{Add a new TOA section} (e.g., put \rtype{film} references in their
own section): Use 
\begin{grammar}
|\HiNewTOACat|\marg{category}\marg{super}\marg{text}|{Y}|
|\HiDefaultTOACat|\marg{type}\marg{category}
\Example
|\HiNewTOACat{m}{movies}{Motion Picture/s}{Y}| \\
|\HiDefaultTOACat{film}{m}|
\end{grammar}
where \meta{category} and \meta{super} are new names (not in the above table), and \meta{text} is the text of the heading.

\textbf{Add a new type to an existing TOA section} (e.g., add ``Model
Code'' to Statutes and Regulations): Use
\begin{grammar}
|\HiNewTOACat|\marg{category}\marg{super}\marg{text}|{Y}| \\
|\HiDefaultTOACat|\marg{type}\marg{category}
\Example |\HiNewTOACat{mc}{edict}{Model Code/s}{Y}| \\
|\HiDefaultTOACat{modelcode}{mc}|
\end{grammar}
where \meta{category} is a new name (not in the above table), \marg{super} is
the supercategory name corresponding to the existing TOA section,
and \meta{text} is the text of the heading.

\subsection{Indexing References}

\label{s:toa-index}

References are indexed for the Table of Authorities upon every citation, by
having entries added to the |\jobname.toa| file automatically for each citation
command. The command |\AddToTOA| described below can also add an entry
manually.

An interesting challenge for indexing is that, especially for briefs, references
may be cited in parts of a document that use different pagination systems. As a
result, it is necessary to store detailed information about where a reference is
cited in a document in order to produce a correct listing of pages in the table.

Five pieces of information are written out to the file for each use of a
reference:
\begin{enumerate}
\item The reference name, and possibly the page for references where the page
number is included in table of authorities entries.
\item The page number as formatted.
\item The page number as an arabic number.
\item The prevailing definition of |\thepage|, so that different page counting
schemes can be identified.
\item A comma-separated list of ``tags'' under which the index entry should be
categorized. Typically this will be up to two tags, one based on the reference's
category and one based on the reference's location. A tag is a colon-separated
structure comprising a supercategory name and a textual heading name
(corresponding to the TOA Categories elements described in
\sec{toa-categories}).
\end{enumerate}


\MacroSpec\HiAddToTOA\marg{ref} \\
Adds \meta{ref} to the table of authorities without producing any citation text.

%</doc>
%<*package>
%    \begin{macrocode}
\def\HiAddToToa#1#2{\@bsphack\hi@addtotoa{#1}{#2}\@esphack}
%    \end{macrocode}
%
%
% Proposes adding a reference for indexing in the table of authorities. \#1 is
% the reference, and \#2 is the page number if any. Even if a reference is
% proposed for adding, the following conditions must be true:
% \begin{itemize}
% \item The TOA is not disabled
% \item The citation containing the reference to be added to the TOA is not
% itself in the TOA
% \item The reference has an associated category (see \sec{toa-categories}).
% \end{itemize}
%
%    \begin{macrocode}
\def\hi@addtotoa#1#2{%
    \hi@toacat@get{#1}{\hi@addtotoa@{#1}{#2}}%
}
%
% Called only if the reference had a category. |#1| is the reference name, |#2|
% the page number, |#3| the category text.
\def\hi@addtotoa@#1#2#3{%
    \if@hi@in@toa\else \if@hi@toa@disabled\else
        \addtocontents{toa}{%
            \protect\contentsline{hi@toa}{%
                #1\@ifundefined{tcpg@#1}{}{\ifstrempty{#2}{}{ at #2}}%
            }{%
                {%
                    \thepage
                }{%
                    \noexpand\the\noexpand\c@page
                }{%
                    % We want this to run at the time the |\write| is
                    % executed.
                    \noexpand\expandonce\thepage
                }{%
                    #3%
                    \ifx\hi@toa@locationtag\relax\else
                        ,\hi@toa@locationtag
                    \fi
                }%
            }{}%
        }%
    \fi\fi
}
%    \end{macrocode}
%
% \DescribeMacro\hi@include@page@in@toa
% Declares that the page number is relevant and should be included for a
% citation. This command should be issued by reference macro definers where the
% reference type ought to include a page number in the TOA.
%
%    \begin{macrocode}
\def\hi@include@page@in@toa#1{%
    \global\@namedef{tcpg@#1}{}%
}
%    \end{macrocode}
%
%</package>
%<*doc>

\subsection{Reading the Index}

Prior to generating a table of authorities, the index file is read and its
entries are sorted to produce three sets of data structures:
\begin{itemize}
\item For each supercategory, a list of references falling within that
supercategory.
\item For each supercategory, a list of textual headings for that supercategory.
\item For each reference, a macro identifying the page numbers associated with
that reference.
\end{itemize}

%</doc>
%<*package>
%
% Sets up the Table of Authorities. This reads the |toa| file, performs all the
% reference use counting, and opens the |toa| file for writing. It then
% undefines itself so it cannot be called again. It should be run before
% displaying any TOA entries.
%
%    \begin{macrocode}
\def\hi@setuptoa{%
    \@hi@in@toatrue
    \hi@noid
    \global\let\@last@toatitle\relax
    \hi@toa@counter\z@
    \@input{\jobname.toa}%
    \@hi@in@toafalse
    \if@filesw
        \newwrite\tf@toa
        \immediate\openout\tf@toa \jobname.toa\relax
    \fi
    \global\let\hi@setuptoa\relax
}
%    \end{macrocode}
%
% This is run for each entry in the |toa| file, as produced above. The arguments
% (after expansion of the groups in the second argument) match the five elements
% given above with respect to |\hi@addtotoa@|.
%
% The macro invokes |\hi@toa@addpg| to update the page number listing for the
% reference, and invokes |\hi@toa@addtolist| to add the reference's information
% to the supercategory lists.
%
%    \begin{macrocode}
\def\l@hi@toa#1#2{\l@hi@toa@{#1}#2}
\def\l@hi@toa@#1#2#3#4#5{%
    \expandafter\hi@toa@addpg
        \csname hi@pg@\detokenize{#1}\endcsname
        {#2}{#3}{#4}%
    \@for\hi@toa@tmp:=\@empty#5\do{%
        \@expand{\find@in{:}}\hi@toa@tmp{i}{\hi@toa@addtolist{#1}}{%
            \hi@toa@addtolist{#1}\hi@toa@tmp\hi@toa@tmp
        }%
    }%
}
\make@find@in{:}
%    \end{macrocode}
%
% A counter for TOA items, just for informational purposes.
%
%    \begin{macrocode}
\newcount\hi@toa@counter
%    \end{macrocode}
%
%
% \paragraph{Adding to Lists}
%
% Adds a given reference to a supercategory list, called
% |hi@toa@|\meta{supercat}. If the list does not already exist, then create it.
% The list is alphabetically sorted and its items are unique.
%
% Also updates the heading lists for the supercategory by invoking
% |\hi@toa@headlist@add|.
%
% The message counters are updated and displayed here because we want to track
% unique additions of references to TOA lists.
%
% \#1 is the reference, \#2 the supercategory, \#3 the textual description.
%
%    \begin{macrocode}
\def\hi@toa@addtolist#1#2#3{%
    \IfKnownList{hi@toa@#2}{}{%
        \NewSortedList{hi@toa@#2}\SortEasyAlpha{%
            \hi@toa@makesortable{##1}{\def##2}%
        }%
        \ListElementsMustBeUnique{hi@toa@#1}%
    }%
    \IfListContains{hi@toa@#2}{#1}{}{%
        \AddToList{hi@toa@#2}{#1}%
        \hi@toa@headlist@add{#2}{#3}%
        \advance\hi@toa@counter\@ne
        \message{(\the\hi@toa@counter)}%
    }%
}
%    \end{macrocode}
%
% Given \#1 a reference name and \#2 a callback, turns the TOA citation form of
% \#1 into sortable text and runs \#2 on it.
%
%    \begin{macrocode}
\def\hi@toa@makesortable#1#2{%
    \find@in{ at }{#1}{\hi@toa@makesortable@}{\hi@toa@makesortable@{#1}{}}{#2}%
}
%    \end{macrocode}
%
% \#1 is the reference name, \#2 the page number, \#3 the callback.
%
%    \begin{macrocode}
\def\hi@toa@makesortable@#1#2#3{%
    \@expand\hi@toa@makesortable@@{%
        \csname\@ifundefined{lc@#1}{fc@#1}{lc@#1}\endcsname
    }{ii}{#2}{#3}%
}
%    \end{macrocode}
%
% \#1 is the defined text of the reference macro, \#2 the page number, \#3 the
% callback.
%    \begin{macrocode}
\def\hi@toa@makesortable@@#1#2#3{%
    \uppercase{\StripForAlpha{#1#2}}{#3}%
}
\make@find@in{ at }
%    \end{macrocode}
%
%</package>
%<*doc>

\subsubsection{Heading Lists}

For each supercategory, the textual description heading may comprise one or
more types of references. For example, the ``edict'' supercategory may have
statutes and/or regulations, and the heading should reflect the particular
items to be listed. So if one regulation and several statutes have been cited,
then the heading should read ``Statutes and Regulation,'' for example.

To implement this, for every supercategory there is a ``heading list''
associated with the supercategory. The heading list contains every textual
description associated with the supercategory, plus a flag for each textual
description for whether it should be singular or plural. The first time a
textual description is encountered for a heading list, the singular form is
used. If the same description is encountered again, then it is updated to be
marked as plural.

%</doc>
%<*package>
%
% |\hi@headlist@|\meta{supercat} is the macro for the heading list. That macro
% contains a list of paired items, one for each textual description encountered:
% \begin{itemize}
% \item A macro |\hi@toa@headlist@singular| or |\hi@toa@headlist@plural|
% \item The given textual description
% \end{itemize}
%
% Determines if the heading list exists for the given supercategory. If not,
% creates it. Otherwise, searches for the textual description in the list and
% updates it. \#1 is the supercategory name, \#2 is the textual description.
%
%    \begin{macrocode}
\def\hi@toa@headlist@add#1#2{%
    \expandafter\hi@toa@headlist@add@\csname hi@headlist@#1\endcsname{#2}%
}
%    \end{macrocode}
%
% \#1 is the |\hi@headlist@|\meta{supercat} macro, \#2 is the textual
% description. |\reserved@a| will be the textual description to search for.
%
%    \begin{macrocode}
\def\hi@toa@headlist@add@#1#2{%
    \ifx#1\relax
        \def#1{\hi@toa@headlist@singular{#2}}%
    \else
        \def\reserved@a{#2}
        \expandafter\hi@toa@headlist@update#1\@stop{}#1%
    \fi
}
%    \end{macrocode}
%
% Iterates through the heading list, searching for textual description saved in
% |\reserved@a|. \#1 is the singular/plural marker, \#2 the textual description
% in the list being considered, \#3 is the remaining list, \#4 the part of the
% list already searched, \#5 the heading list macro.
%
%    \begin{macrocode}
\def\hi@toa@headlist@update#1#2#3\@stop#4#5{%
    \def\reserved@b{#2}%
    \@test \ifx\reserved@a\reserved@b\fi {%
        \def#5{#4\hi@toa@headlist@plural{#2}#3}%
    }{%
        \ifblank{#3}{%
            \edef#5{%
                \unexpanded{#4#1{#2}\hi@toa@headlist@singular}%
                {\expandonce\reserved@a}%
            }%
        }{%
            \hi@toa@headlist@update#3\@stop{#4#1{#2}}{#5}%
        }%
    }
}
%    \end{macrocode}
%
%
% As noted above in \sec{toa-categories}, textual descriptions use a convention
% of slashes to differentiate between the singular and plural forms. The
% |\hi@toa@headlist@singular| and |\hi@toa@headlist@plural| macros parse the
% slashes to construct the desired form, and also insert the relevant
% punctuation for the subsequent element in the heading list.
%
%    \begin{macrocode}
\def\hi@toa@headlist@singular#1{%
    \find@in{/}{#1}{\hi@toa@headlist@choose\@firstoftwo}{#1}%
    \hi@toa@headlist@lookahead
}
\def\hi@toa@headlist@plural#1{%
    \find@in{/}{#1}{\hi@toa@headlist@choose\@secondoftwo}{#1}%
    \hi@toa@headlist@lookahead
}
\make@find@in{/}
\def\hi@toa@headlist@lookahead#1{%
    \ifx#1\@empty\else
        \expandafter\hi@toa@headlist@lookahead@\expandafter#1%
    \fi
}
\def\hi@toa@headlist@lookahead@#1#2#3{%
    \@test \ifx#3\@empty \fi{%
        \space and\space #1{#2}#3%
    }{%
        ,\space#1{#2}#3%
    }%
}
\def\hi@toa@headlist@choose#1#2#3{%
    #2\find@in{/}{#3}{#1}{#1{}{#3}}%
}
%    \end{macrocode}
%
% Shows a heading list, for example in a heading.
%
%    \begin{macrocode}
\DeclareRobustCommand\hi@toa@headlist@show[1]{%
    \csname hi@headlist@#1\endcsname\@empty
}
%    \end{macrocode}
%
%</package>
%<*doc>

\paragraph{Location-Based Lists}
\label{s:toa-tag}

It may be desirable to prepare a chapter-by-chapter bibliography, such that
references are tagged not by type but by location in the document.

\MacroSpec\HiTOATag \marg{tag} \\
Indicate that all subsequent references cited should be tagged with \meta{tag},
which can then be used as a list of the Table of Authorities.

%</doc>
%<*package>
%
% The current location tag is stored in |\hi@toa@locationtag|.
%
%    \begin{macrocode}
\def\HiTOATag#1{%
    \def\hi@toa@locationtag{#1}%
}
\let\hi@toa@locationtag\relax
%    \end{macrocode}
%
%</package>
%<*doc>

\subsection{Composing Page Number Lists}

If a reference is cited on pages 3, 4, 5, 7, 8, and 10, it is desirable to group
these numbers into compact range forms for presentation in the Table of
Authorities: ``3--5, 7--8, 10.'' The package does so by reading the page numbers
in order, keeping a running compilation of the properly formatted aggregate
number listing and revising the last element of that listing as necessary.


%</doc>
%<*package>
%
% The |\hi@pg@|\meta{ref} macros take on the following form:
% \begin{grammar}
%   \marg{last-display-page} \marg{last-numeric-page} \marg{last-\cmd\thepage}
%   \marg{built-page-list}
% \end{grammar}
% where appending \meta{last-display-page} to \meta{built-page-list} will give
% the complete page list so far. Also, \meta{built-page-list} is prepended with
% a list of |*|s to indicate the number of citations to a particular
% reference, for counting purposes.
%
% \#1 is the |\hi@pg@|\meta{ref} macro. \#2-\#4 are the elements from the |toa|
% file listing: the display-form page number, the numeric page number, and the
% definition of |\thepage|.
%
%    \begin{macrocode}
\def\hi@toa@addpg#1#2#3#4{%
    \@test \ifx#1\relax\fi {%
        \def#1{{}{#3}{#4}{*:#2}}%
    }{%
        \expandafter\hi@toa@addpg@#1#1{#2}{#3}{#4}%
    }%
}
%    \end{macrocode}
% Updates the running list of pages, when given a new page number.
%
% \#1-\#4 are the four hi@pg@\meta{ref} parameters, which are described above,
% \#5 is |\hi@pg@|\meta{ref},
% \#6-\#8 are \#2-\#4 of |\l@hi@toa|.
%
%    \begin{macrocode}
\def\hi@toa@addpg@#1#2#3#4#5#6#7#8{%
    \def\reserved@a{#3}\def\reserved@b{#8}%
    \ifx\reserved@a\reserved@b
%    \end{macrocode}
%
% For the same |\thepage|: Compare the last-added page number to the page
% number to be added. If they are the same, then just increment the count. If
% the new page number is one greater, then see if we're already working with a
% range (\#1, \meta{last-display-page} is not blank). If so, then just increment
% the count. Otherwise, increment the count and add a dash. In any event, set
% \meta{last-display-page} to the new display page number.
%
%    \begin{macrocode}
        \@tempcnta=#2\relax
        \ifnum#7=\@tempcnta
            \def#5{{#1}{#2}{#3}{*#4}}%
        \else
            \advance\@tempcnta\@ne
            \ifnum#7=\@tempcnta
                \ifblank{#1}{%
                    \def#5{{#6}{#7}{#8}{*#4--}}%
                }{%
                    \def#5{{#6}{#7}{#8}{*#4}}%
                }%
            \else
%    \end{macrocode}
%
% If the numeric increase is greater than one, then compose the full aggregate
% list (\#4\#1), and tack on a comma and the new display number.
%
%    \begin{macrocode}
                \def#5{{}{#7}{#8}{*#4#1, #6}}%
            \fi
        \fi
    \else
%    \end{macrocode}
%
% If |\thepage| has changed, then compose the full list and tack on a comma and
% the new number.
%
%    \begin{macrocode}
        \def#5{{}{#7}{#8}{*#4#1, #6}}%
    \fi
}
%    \end{macrocode}
%
%
%
% \paragraph{Using Page Number Lists}
%
% Composes the page number list and runs the callback on it. \#1 is the
% reference name, \#2 is a callback.
%
%    \begin{macrocode}
\def\hi@toa@usepg#1#2{%
    \@expand{\@unbrace\hi@toa@usepg@}{%
        \csname hi@pg@\detokenize{#1}\endcsname
    }{ii}{#2}%
}
% \#1-\#4 are the elements of the |\hi@pg@|\meta{ref} structure, \#5 is the
% callback.
\def\hi@toa@usepg@#1#2#3#4#5{%
    \find@in{:}{#4#1}{%
        \@tworun\@gobble\hi@toa@usepg@passim
    }{%
        \PackageError\hi@pkgname{%
            Page data structure `#4#1' contains \MessageBreak
            no colon, but it should. This indicates \MessageBreak
            a bug in the hicite program%
        }{Check the hicite program.}%
        \@gobble
    }{#5}%
}
\make@find@in{:}
% \#1 is the page list, \#2 is the callback.
\def\hi@toa@usepg@passim#1#2{%
    \@test \ifnum\HiTOAPassimNum>\z@ \fi{%
        \hi@toa@usepg@passim@{1}#1, \@stop{#1}{#2}%
    }{#2{#1}}%
}
\def\hi@toa@usepg@passim@#1#2, #3\@stop#4#5{%
    \@test \ifnum#1<\HiTOAPassimNum \fi{%
        \ifstrempty{#3}{#5{#4}}{%
            \@expandarg\hi@toa@usepg@passim@{%
                \number\numexpr#1+1\relax
            }#3\@stop{#4}{#5}%
        }%
    }{#5{\HiTOAPassim}}%
}
%    \end{macrocode}
%
% Counts the number of times a reference was used, based on the
% |\hi@pg@|\meta{ref} data. \#1 is \meta{ref}, \#2 a callback. It is entirely
% expandable.
%
%    \begin{macrocode}
\def\hi@toa@refcount#1#2{%
    \@expand{\@unbrace\hi@toa@refcount@}{\csname hi@pg@#1\endcsname}{ii}{#2}%
}
\def\hi@toa@refcount@#1#2#3#4#5{%
    \find@in{:}{#4}{\hi@toa@refcount@@}{%
        \PackageError\hi@pkgname{%
            Reference count data `#4' should have contained a \MessageBreak
            colon, but it does not. This probably indicates \MessageBreak
            a programming error.
        }{Check the hicite program.}%
        \@gobble
    }{#5}%
}
\def\hi@toa@refcount@@#1#2#3{\hi@toa@refcount@@@{1}#1\@stop{#3}}%
\def\hi@toa@refcount@@@#1#2#3\@stop#4{%
    \ifstrempty{#3}{#4{#1}}{%
        \@expandarg\hi@toa@refcount@@@{\number\numexpr#1+1\relax}#3\@stop{#4}%
    }%
}
%    \end{macrocode}
%
% 
%</package>
%<*doc>

\paragraph{Starred References}\label{s:toa-star}
Some courts ask litigants to insert asterisks in the Table of Authorities before
references that they rely most heavily on. This can be done automatically by
counting the number of times each reference has been used.

\MacroSpec\HiStarCount \marg{num} \\
Sets the minimum number of uses of a reference
before that reference receives a star. The package option \opt{toastar} sets the
value to 4. By default it is zero, in which case no stars are displayed.

\DescribeMacro\HiStarText
This macro may be redefined with text to place at the beginning of the
Table of Authorities explaining the stars.

\DescribeMacro\HiStarMark
The macro |\HiStarMark| may be redefined to specify the content of the star
(by default an asterisk). It will be added before the relevant TOA entries via
|\everypar|, so it probably should be an |\llap| box so as not to affect the
alignment.

%</doc>
%<*package>
%
% Adds a star before the reference if its usage count exceeds the minimum count.
% \#1 is the reference name. The star is added by an |\everypar| because TOA
% entries are initially in vertical mode.
%
%    \begin{macrocode}
\newcount\hi@toa@starcount
\def\hi@toa@star#1{%
    \ifnum\hi@toa@starcount>\z@
        \ifnum\hi@toa@refcount{#1}\@iden<\hi@toa@starcount\else
            \everypar{\HiStarMark\everypar{}}%
        \fi
    \fi
}
\def\HiStarCount#1{\hi@toa@starcount=#1\relax}
\def\HiStarText{%
    Authorities upon which this brief primarily relies are indicated with
    asterisks in the margin.\par
}
\def\HiStarMark{\llap{* }}
%    \end{macrocode}
%</package>
%<*doc>

\subsection{Showing the Table}
\label{s:toa-show}

\DescribeMacro\tableofauthorities
The Table of Authorities is produced by calling |\tableofauthorities|. This will
create one section for each reference category as described in \sec{refs}.

\MacroSpec\HiTOAHeading\marg{text}
This macro may be redefined to specify how to format a heading within the table
of authorities.

%</doc>
%<*package>
%
%    \begin{macrocode}
\def\tableofauthorities{%
    \ifnum\hi@toa@starcount>\z@
        \HiStarText
    \fi
    \begingroup
        \hi@toacat@each{%
            \HiTOATable[%
                \HiTOAHeading{\hi@toa@headlist@show{##1}}\par
                \ifdim\lastskip<\HiTOASkip
                    \vskip-\lastskip
                \else
                    \vskip-\HiTOASkip
                \fi
                \parindent\z@
                \parskip=\HiTOASkip
            ]{##1}%
        }%
    \endgroup
}
\def\HiTOAHeading{\section*}
%    \end{macrocode}
%</package>
%<*doc>

\MacroSpec\HiTOATable\oarg{heading-text}\marg{list-name}
Typesets a single Table of Authorities section based on the authorities in
\meta{list-name}, with a heading \meta{heading-text}. This macro can be used as
an alternative to |\tableofauthorities| to provide more fine-grained control
over which tables are emitted.

%</doc>
%<*package>
%    \begin{macrocode}
\newcommand\HiTOATable[2][]{%
    \hi@setuptoa
    \IfKnownList{hi@toa@#2}{\IfEmptyList{hi@toa@#2}{}{%
        #1%
        \ShowList{hi@toa@#2}{%
            \global\let\@this@toatitle\relax
            \hi@toa@usepg{##1}{\hi@toaline{\hi@toa@star{##1}\HiTOACite{##1}}}%
            \global\let\@last@toatitle\@this@toatitle
        }%
    }}{}%
}
%    \end{macrocode}
%
%
% Displays one reference's line in the Table of Authorities. \#1 is the text of
% the reference citation, \#2 the page number aggregate.
%
%    \begin{macrocode}
\def\hi@toaline#1#2{%
    {\hi@toa@par@settings
    #1\nobreak
    \HiTOALeader
    \nobreak
    {\normalfont \normalcolor \hi@toa@brkpg{#2}}%
    \par}%
}
%    \end{macrocode}
%
% Sets up the paragraph margin settings for TOA entries.
%
%    \begin{macrocode}
\def\hi@toa@par@settings{%
    \leftskip\z@\rightskip \@tocrmarg
    % Make the right margin ragged. This is necessary because the ditto spacing
    % gets messed up on occasion due to space stretching.
    \rightskip=1\rightskip plus .1\hsize
    \parfillskip -\rightskip
    \hangindent\HiTOAIndent\relax
    \parindent \z@\@afterindenttrue
    \interlinepenalty\@M
}
%    \end{macrocode}
%
%</package>
%<*doc>

\MacroSpec\HiTOALeader
Produces the dots for TOA entries, between the reference text and the page
numbers. This macro may be redefined to change the appearance of the dots.

%</doc>
%<*package>
%    \begin{macrocode}
\def\HiTOALeader{%
    \leaders\hbox{%
        $\m@th \mkern \@dotsep mu\hbox{.}\mkern \@dotsep mu$%
    }\hskip 2em \@plus 1fill \@minus 0.5em
}
%    \end{macrocode}
%
%</package>
%<*doc>

\MacroSpec\HiTOACite\marg{cite-string}
Displays a single entry in the Table of Authorities. This is essentially
another citation command like |\sentence| except it invokes less overhead
because there is no punctuation at the end of the entry to check. It may be
useful in section headings within documents as well.

%</doc>
%<*package>
%    \begin{macrocode}
\DeclareRobustCommand\HiTOACite[1]{%
    \begingroup
    \@hi@in@toatrue
    \hi@noid
    \let\clause\hi@clause
    \let\sentence\hi@sentence
    \hi@pse@parse{#1}{\hi@draw@citation{\@hi@captrue\@hi@senttrue}{}}%
    \endgroup
}
%    \end{macrocode}
%
%
% On occasion, the best presentation of the TOA entry involves breaking the page
% number listing across a line. This macro computes the best place for doing so.
%
% The basic idea is that, for each page number item, three glue entries are
% inserted: $-|\rightskip|$, $G_a$ and $G_b$. $G_b$ has natural dimension
% |\hsize| but is shrinkable to zero, and $G_a = -G_b + |\rightskip|$. $G_a$ is
% inserted with a penalty that favors breaking after the last possible comma,
% but $G_b$ cannot be broken beforehand.
%
% If no break occurs between two page numbers, then the total glue is
% $-|\rightskip| + G_a + G_b = 0$. If a break is permitted, though, then $G_a$
% is discarded. As a result, the preceding page number gets glue
% $-|\rightskip|$, pulling it all the way to the right margin, and the next page
% number starts a new line and gets glue $G_b$, pushing it as far to the right
% margin as possible and (because of the shrinkage) causing the line-breaking
% algorithm to favor putting as few items on this new line as possible.
%
% Below, |\@tempskipa| is $G_a$, |\@tempskipb| is $G_b$, and |\@tempcnta| is a
% descending penalty placed before $G_a$.
%
%    \begin{macrocode}
\def\hi@toa@brkpg#1{%
    \@tempcnta=9999\relax
    \@tempskipb=\hsize\@minus\hsize\relax
    \@tempskipa=\glueexpr \@tempskipb * -1 + 1\rightskip\relax
    \find@in{, }{#1}\hi@toa@brkpg@{\hbox{#1}}%
}
\make@find@in{, }
\def\hi@toa@brkpg@#1#2{%
    \hbox{#1,}%
    % Pull the page number to the right margin
    \nobreak\hskip-\rightskip
    % Now permit a line break. If the break is not accepted, nix the
    % right-margin glue above, insert a -1fil glue to counteract the |\hfil| to
    % come, and insert a space to separate the commas.
    \penalty\@tempcnta\hskip \@tempskipa\relax
    % Insert an |\hbox| and then an |\hfil|. If the line is broken, then the
    % |\hfil| will show up, pushing this page number to the right side of the
    % page. If the line is not broken here, then the -1fil glue from above will
    % counteract this glue, and nothing will result.
    \hbox{ }\nobreak\hskip\@tempskipb\relax
    % Reduce the penalty, to encourage later line breaks rather than earlier
    % ones
    \advance\@tempcnta\m@ne
    \find@in{, }{#2}\hi@toa@brkpg@{\hbox{#2}}%
}
%    \end{macrocode}
%
%
% Citation macros should use this when displaying an author name as the first
% item in a reference. It stores the author name in |\@this@toatitle|, for
% identifying duplicates. It then displays the author name, replacing it with
% |\HiTOADitto| if it is a duplicate. \#1 is the font for the author; \#2 is the
% author name (sortable).
%
%    \begin{macrocode}
\DeclareRobustCommand\hi@toa@dupauthor[2]{%
    \if@hi@in@toa
        \global\def\@this@toatitle{#2}%
        \hi@nocap
        \ifx\@this@toatitle\@last@toatitle
            \HiTOADitto, % space
        \else
            #1{#2}, % space
        \fi
    \else
        #1{#2}, % space
    \fi
}
%    \end{macrocode}
%
% If there is no author, then just reset the author tracking state.
%
%    \begin{macrocode}
\DeclareRobustCommand\hi@toa@dupnone{\global\let\@this@toatitle\relax}%
%    \end{macrocode}
%
% For statutes, an even more complex format for Table of Authorities listings is
% desirable involving ditto marks: the ditto-omitted title should be indented so
% that it lines up with the non-omitted title.
%
% \#1 is a statute title; \#2 is a statute citation; \#3 is the page
% number text if no ditto is used; \#4 is the text if a ditto is used.
%
% The form of the resulting TOA entry is:
% \begin{itemize}
% \item If no ditto: \#1\#2\#3
% \item If \#1 is empty: [ditto]\#4
% \item If \#1 is present: [extra indent][ditto]\#4
% \end{itemize}
%
%    \begin{macrocode}
\def\hi@toa@duptitle#1#2#3#4{%
    \global\def\@this@toatitle{#1#2}%
    \ifx\@this@toatitle\@last@toatitle
        \ifhmode \immediate\write16{BAD!!!!}\fi
        \penalty\z@
        \@tempdima=\pagegoal \advance\@tempdima-\pagetotal
        \advance\@tempdima-\pageshrink
        \ifdim\@tempdima<\baselineskip
            \ifvmode \break \fi
            \hi@citeguts{#1#2#3}%
        \else
            \setbox\@tempboxa=\hbox{#2}%
            \@tempdima=\wd\@tempboxa
            \ifstrempty{#1}{}{\advance\@tempdima\HiTOAIndent\relax}%
            \ifdim 6em<\@tempdima \@tempdima=6em\relax\fi
            \setbox\@tempboxa=\hbox{\HiTOADitto}%
            \ifdim\@tempdima<\wd\@tempboxa \@tempdima=\wd\@tempboxa \fi
            \hi@citeguts{%
                \leavevmode\hb@xt@\@tempdima{\hss \box\@tempboxa}%
                \hi@nocap
                #4%
            }%
        \fi
    \else
        \hi@citeguts{#1#2#3}%
    \fi
}
%    \end{macrocode}
%</package>
%<*doc>

The following affect the appearance of the Table of Authorities.

\MacroSpec\HiTOASkip A glue specification for how much
space to put between entries.

%</doc>
%<*package>
%    \begin{macrocode}
\newskip\HiTOASkip
\HiTOASkip=1\baselineskip \@plus .1\baselineskip \@minus .1\baselineskip
%    \end{macrocode}
%</package>
%<*doc>

\MacroSpec\HiTOAPassimNum A number (defined by |\chardef|), representing many
items an aggregate page listing must have before it is replaced with
\emph{passim}. When zero (the default), \emph{passim} is never used.

%</doc>
%<*package>
%    \begin{macrocode}
\let\HiTOAPassimNum\z@
%    \end{macrocode}
%</package>
%<*doc>

\MacroSpec\HiTOAPassim is the text to be used if
|\HiTOAPassimNum| is met or exceeded.

%</doc>
%<*package>
%    \begin{macrocode}
\def\HiTOAPassim{\hi@fn@latin{passim}}
%    \end{macrocode}
%</package>
%<*doc>

\MacroSpec\HiTOADitto The text that
replaces repeated authors, statutory titles, and other information that can be
omitted from the table listings.

%</doc>
%<*package>
%    \begin{macrocode}
\def\HiTOADitto{---\kern-.1em---\kern-.1em---}
%    \end{macrocode}
%</package>
%<*doc>

\MacroSpec\HiTOAIndent The length for the hanging indent. (It is specified in
|em| units so it is defined as macro text.)

%</doc>
%<*package>
%    \begin{macrocode}
\def\HiTOAIndent{1.5em}
%    \end{macrocode}
%</package>
%<*doc>

\subsection{Table of Abbreviations}

A table of abbreviations is like a simplified table of authorities, and because
of \hia*'s support for abbreviations as the reference type \rtype{abbrev},
such tables can be made automatically. The macro |\tableofabbreviations| takes
as an argument a two-element callback, which it executes for every abbreviation
definition and full text. Entries are sorted by abbreviations, ignoring any
``The''.

%</doc>
%<*package>
%
%    \begin{macrocode}
\def\tableofabbreviations#1{%
    \hi@setuptoa
    \@hi@in@toatrue
    \hi@noid
    \IfKnownList{hi@toa@abbrev}{\IfEmptyList{hi@toa@abbrev}{}{%
        \ShowList{hi@toa@abbrev}{%
            \@expand{\@unbrace#1}{\csname lc@##1\endcsname}{iii}%
        }%
    }}{}%
    \@hi@in@toafalse
}
%    \end{macrocode}
%</package>
%<*test>




\section{toa.dtx}

\subsection{Aux File Writing}

\let\WrittenText\@empty
\let\OrigProtectedWrite\protected@write
\def\protected@write#1#2#3{%
    \begingroup
        \let\thepage\relax
        #2%
        \let\protect\@unexpandable@protect
        \xdef\WrittenText{#3}%
    \endgroup
    \begingroup
        \let\protect\noexpand
        \xdef\WrittenText{\WrittenText}%
    \endgroup
}

\begingroup


    \HiSetTOACat{ref}{other}
    \let\tcpg@ref\relax
    \@hi@in@toafalse
    \@hi@toa@disabledfalse
    \def\thepage{\csname @roman\endcsname \c@page}

    \begingroup
        \let\WrittenText\@empty
        \AssertBox{%
            \c@page=5
            \hi@addtotoa{ref}{15}%
        }{}
        \AssertMacro[\AssertExpandedEqual]{\WrittenText}{%
            \string\@writefile{toa}{%
                \noexpand\contentsline {hi@toa}{ref}{%
                    {\detokenize{v}}%
                    {5}%
                    {%
                        \noexpand\csname @roman\noexpand\endcsname
                        \noexpand\c@page
                    }%
                    {other:Other Source/s}%
                }{}%
            }%
        }%
    \endgroup

    \begingroup
        \let\WrittenText\@empty
        \let\tcpg@ref\@empty
        \AssertBox{%
            \c@page=5
            \hi@addtotoa{ref}{15}%
        }{}
        \AssertMacro[\AssertExpandedEqual]{\WrittenText}{%
            \string\@writefile{toa}{%
                \noexpand\contentsline {hi@toa}{ref at 15}{%
                    {\detokenize{v}}%
                    {5}%
                    {%
                        \noexpand\csname @roman\noexpand\endcsname
                        \noexpand\c@page
                    }%
                    {other:Other Source/s}%
                }{}%
            }%
        }%
    \endgroup

    \begingroup
        \let\WrittenText\@empty
        \@hi@in@toatrue
        \AssertBox{%
            \hi@addtotoa{ref}{15}%
        }{}
        \AssertMacro[\AssertEqual]{\WrittenText}{}
    \endgroup

    \begingroup
        \let\WrittenText\@empty
        \@hi@toa@disabledtrue
        \AssertBox{%
            \hi@addtotoa{ref}{15}%
        }{}
        \AssertMacro[\AssertEqual]{\WrittenText}{}
    \endgroup

\endgroup

\let\protected@write\OrigProtectedWrite


\subsection{Aux File Reading}

\begingroup
    \def\hi@toa@addtolist#1#2#3{%
        \edef\ListTestResult{{\unexpanded{#1}}{#2}{#3}}%
    }
    \def\hi@toa@addpg#1#2#3#4{%
        \def\PageTestResult{{#1}{#2}{#3}{#4}}%
    }

    \let\ListTestResult\relax
    \let\PageTestResult\relax

    \contentsline {hi@toa}{ref}{%
        {v}%
        {5}%
        {\csname @roman\endcsname \c@page}%
        {other:Other Source/s}%
    }{}%
    \AssertMacro\PageTestResult{%
        {\hi@pg@ref}{v}{5}{\csname @roman\endcsname\c@page}%
    }
    \AssertMacro\ListTestResult{{ref}{other}{Other Source/s}}

\endgroup

\subsection{Canonicalization}

\begingroup

    \def\fc@ref{\emph{a b} Cde 12 Fg. ({hij})}

    \AssertCallback[\AssertCharEqual]{\hi@toa@makesortable{ref}}{%
        ABCDE...12FGHIJ%
    }

    \AssertCallback[\AssertCharEqual]{\hi@toa@makesortable{ref at 15/a2b}}{%
        ABCDE...12FGHIJ...15A....2B%
    }

    \def\lc@ref{\emph{k l} Mno 25 Pq. ({rst})}

    \AssertCallback[\AssertCharEqual]{\hi@toa@makesortable{ref}}{%
        KLMNO...25PQRST%
    }

\endgroup


\subsection{Heading Lists}

\begingroup

    \hi@toa@headlist@add{stat}{Regulation/s}
    \AssertBox{\hi@toa@headlist@show{stat}}{Regulation}

    \hi@toa@headlist@add{stat}{Regulation/s}
    \AssertBox{\hi@toa@headlist@show{stat}}{Regulations}

    \hi@toa@headlist@add{stat}{Treat/y/ies}
    \AssertBox{\hi@toa@headlist@show{stat}}{Regulations and Treaty}

    \hi@toa@headlist@add{stat}{Statute/s}
    \AssertBox{\hi@toa@headlist@show{stat}}{Regulations, Treaty and Statute}

    \hi@toa@headlist@add{stat}{Treat/y/ies}
    \AssertBox{\hi@toa@headlist@show{stat}}{Regulations, Treaties and Statute}

\endgroup


\subsection{List Addition}


\begingroup

    \def\fc@refA{A}
    \def\fc@refI{I}
    \def\fc@refM{M}
    \AssertFalse{\IfKnownList{hi@toa@list}}

    \hi@toa@addtolist{refM}{list}{item/s}
    \AssertTrue{\IfKnownList{hi@toa@list}}

    \AssertBox{\ShowList{hi@toa@list}{#1, }}{refM, }
    \AssertBox{\hi@toa@headlist@show{list}}{item}

    \AssertTrue{\IfListContains{hi@toa@list}{refM}}

    \hi@toa@addtolist{refM}{list}{item/s}
    \AssertBox{\ShowList{hi@toa@list}{#1, }}{refM, }
    \AssertBox{\hi@toa@headlist@show{list}}{item}

    \hi@toa@addtolist{refA}{list}{item/s}
    \AssertBox{\ShowList{hi@toa@list}{#1, }}{refA, refM, }
    \AssertBox{\hi@toa@headlist@show{list}}{items}

    \hi@toa@addtolist{refI}{list}{element/s}
    \AssertBox{\ShowList{hi@toa@list}{#1, }}{refA, refI, refM, }
    \AssertBox{\hi@toa@headlist@show{list}}{items and element}

    \hi@toa@addtolist{refA}{list}{item/s}
    \AssertBox{\ShowList{hi@toa@list}{#1, }}{refA, refI, refM, }
    \AssertBox{\hi@toa@headlist@show{list}}{items and element}

\endgroup


\subsection{Page Numbers and Star Counting}

\begingroup
    \HiStarCount{4}
    \everypar{}
    \let\hi@pg@ref\relax
    \hi@toa@addpg\hi@pg@ref{ii}{2}{roman}
    \AssertCallback{\hi@toa@usepg{ref}}{ii}
    \AssertCallback{\hi@toa@refcount{ref}}{1}

    \hi@toa@star{ref}
    \AssertExpand{\the\everypar}{}

    \hi@toa@addpg\hi@pg@ref{iii}{3}{roman}
    \AssertCallback{\hi@toa@usepg{ref}}{ii--iii}
    \AssertCallback{\hi@toa@refcount{ref}}{2}

    \hi@toa@star{ref}
    \AssertExpand{\the\everypar}{}

    \hi@toa@addpg\hi@pg@ref{iii}{3}{roman}
    \AssertCallback{\hi@toa@usepg{ref}}{ii--iii}
    \AssertCallback{\hi@toa@refcount{ref}}{3}

    \hi@toa@star{ref}
    \AssertExpand{\the\everypar}{}


    \hi@toa@addpg\hi@pg@ref{iv}{4}{roman}
    \AssertCallback{\hi@toa@usepg{ref}}{ii--iv}
    \AssertCallback{\hi@toa@refcount{ref}}{4}

    Stars should now show up at the start of every first test paragraph.

    \hi@toa@star{ref}
    \AssertExpand{\the\everypar}{\noexpand\HiStarMark\noexpand\everypar{}}

    \hi@toa@addpg\hi@pg@ref{4}{4}{arabic}
    \AssertCallback{\hi@toa@usepg{ref}}{ii--iv, 4}
    \AssertCallback{\hi@toa@refcount{ref}}{5}

    \hi@toa@star{ref}
    \AssertExpand{\the\everypar}{\noexpand\HiStarMark\noexpand\everypar{}}

    \hi@toa@addpg\hi@pg@ref{5}{5}{arabic}
    \AssertCallback{\hi@toa@usepg{ref}}{ii--iv, 4--5}
    \AssertCallback{\hi@toa@refcount{ref}}{6}

    \hi@toa@star{ref}
    \AssertExpand{\the\everypar}{\noexpand\HiStarMark\noexpand\everypar{}}

    \hi@toa@addpg\hi@pg@ref{7}{7}{arabic}
    \AssertCallback{\hi@toa@usepg{ref}}{ii--iv, 4--5, 7}
    \AssertCallback{\hi@toa@refcount{ref}}{7}

    \hi@toa@star{ref}
    \AssertExpand{\the\everypar}{\noexpand\HiStarMark\noexpand\everypar{}}

    \let\HiTOAPassimNum\tw@
    \AssertCallback{\hi@toa@usepg{ref}}{\HiTOAPassim}

    \let\HiTOAPassimNum\thr@@
    \AssertCallback{\hi@toa@usepg{ref}}{\HiTOAPassim}

    \chardef\HiTOAPassimNum=4
    \AssertCallback{\hi@toa@usepg{ref}}{ii--iv, 4--5, 7}
\endgroup

\subsection{Formatting}

\AssertBox{\hbox{\hi@toa@brkpg{1--2, 3--4, 5}}}{\hbox{1--2, 3--4, 5}}

The following can only be tested visually. Make sure that these look acceptable.
\def\testbox#1#2{\vrule\vtop{%
    \hsize=1.25in\relax \hi@toa@par@settings
    #1\nobreak\HiTOALeader\nobreak\hi@toa@brkpg{#2}\par
}\vrule\allowbreak\space}

\leavevmode
\testbox{A}{1--2, 3, 4, 5}
\testbox{AB}{1--2, 3, 4, 5}
\testbox{ABC}{1--2, 3, 4, 5}
\testbox{ABCD}{1--2, 3, 4, 5}
\testbox{ABCDE}{1--2, 3, 4, 5}
\testbox{A B C D E F}{1--2, 3, 4, 5}
\testbox{A B C D E F G}{1--2, 3, 4, 5}
\testbox{A B C D E F G H}{1--2, 3, 4, 5}

\subsection{TOA Categories}

\defcase{garcia}{
parties={Garcia v. Google, Inc.},
cite=786 F.3d 733,
court=9th Cir.,
year=2015,
enbanc,
}

\AssertCallback{\hi@toacat@get{garcia}}{case:Case/s}

\defcase{dc-comics}{
parties=DC Comics v. Towle,
cite=802 F.3d 1012,
court=9th Cir.,
year=2015,
toacat=other,
}

\AssertCallback{\hi@toacat@get{dc-comics}}{other:Other Source/s}

\HiNewTOACat{movie}{m}{Motion Picture/s}{Y}
\HiDefaultTOACat{film}{movie}

\deffilm{faceoff}{
name=Face/Off,
year=1997,
publisher=Paramount Pictures,
}
\AssertCallback{\hi@toacat@get{faceoff}}{m:Motion Picture/s}

\begingroup

    \def\catlist{}
    \hi@toacat@each{%
        \ifx\catlist\@empty\else \addto@macro\catlist{, }\fi
        \addto@macro\catlist{#1}%
    }%
    \AssertMacro\catlist{case, const, edict, m, other}

\endgroup

%</test>