%
% \iffalse meta-comment
%
% Copyright 2013-2022 Charles Duan. This program is free software: you can
% redistribute it and/or modify it under the terms of the GNU General Public
% License as published by the Free Software Foundation, either version 3 of the
% License, or (at your option) any later version.
%
% This program is distributed in the hope that it will be useful, but WITHOUT
% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
% FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License along with
% this program.  If not, see <http://www.gnu.org/licenses/>.
%
% \fi
%
%<*driver>
\input driver
\thisis{parts}{Parts}

This is a file used only for production of documentation.
%\endinput
%</driver>
%
%<references>\part{References}
%<references>\label{p:references}
%
%<*intro>
\clearpage
\part{Introduction}
\label{p:intro}
%</intro>
%<*citations>
\clearpage
\part{Citations}
\label{p:citations}

A citation to a reference in a document consists of a \emph{citation command}
followed by a \emph{citation string} as the argument to the command. Citation
commands are described in \sec{iface}, and citation strings are explained
generally in \sec{parse}. The remainder of this Part then describes individual
components of citation strings in more detail.

%</citations>
%
%<features>\part{Additional Features}
%<features>\label{p:features}
%
%<*formatting>
\part{Formatting Algorithms}
\label{p:formatting}

This chapter is generally not essential reading for \hia* users, as it describes
algorithms and processes that are automatically applied when formatting
citations. For advanced readers interested in changing some of the default
formatting behaviors, however, this Part provides some commands and features for
doing so.

%</formatting>
%
%<*allparams>
\clearpage
\part{Reference Parameters}
\label{p:allparams}

These are all of the parameters that may be given when defining a reference.
Parameters in \emph{italics} are aliases for others.

The long history of development of this package has meant that some parameter
names do not conform with the naming conventions otherwise followed in this
package. In particular, \param{inline} and related parameters relate not to
inline citations but to short reference names (see \sec{short}), and date
parameters typically end in |year| even though full date specifications are
permitted (see \sec{dates}). Generally, aliases to properly conforming names are
provided.

%</allparams>
%
%<*alltypes>

\clearpage
\part{Reference Types}
\label{p:alltypes}

This Part is a comprehensive list of every reference type that \hia* supports.
Reference types are organized topically into chapters which contain both
introductory material describing overall characteristics of reference types and
then specific definitions. The chapters contain three types of subheadings
indicating the material contained:
\begin{itemize}
\item Numbered headings in serif type are general descriptions of reference type
features.
\item Unnumbered headings in \textbf{\textsf{sans serif type}} describe specific
reference types, which may be invoked using |\def|\meta{reference type} commands
as described in \sec{refs-syntax}.
\item Headings in \textbf{\textit{\textsf{italic sans serif type}}} describe
reference types that are aliases for other types.
\end{itemize}


\section{What If the Type I Need Isn't Listed?}

The available
reference types reflect the package author's own
citation needs over the years. Having used this package many times to write a
diverse range of works involving technical, historical, judicial, political, and
media references, he has covered nearly every type of conventionally cited work.
Nevertheless, in the event that a writer needs to cite a reference type not
specifically defined here, the package makes several affordances.

First, several reference types are designed to be catch-all types. For
government documents, \rtype{govdoc} provides a generic format for references
cited in the \emph{Federal Register} and other reporters, and for miscellaneous
agency promulgations that are essentially unpublished. For non-governmental
works published in some periodical format, \rtype{website} works as a generic
format, especially since it accepts any publication parameters that can be
attached to a book (\param{editor}, \param{publisher}, etc.; see
\sec{bookrefs-pubparen}). Works that are part of a published book or volume can
generally be defined using the highly flexible \rtype{citecontainer} type.



If truly nothing works, then the reference type \rtype{custom} can be used to
define a custom citation form. Alternatively, the singleton named reference
\rtype{verbatim} can be used to
inject arbitrary text into a citation. Even when these are used, the writer
still enjoys most of the structural capabilities of this package: signals
management, string citations, and so on.

Finally, writers faced with a class of unexpected reference types are encouraged
to develop new citation macros. The syntax and programming conventions for
reference type definer macros are not simple, so it may be easiest to make small
tweaks to the existing reference definitions. In doing so, the package author
recommends using more specific, uncommon reference types as a starting point,
such as those in \sec{specrefs}. The widely used reference types such as
\rtype{case} and \rtype{book} require a great deal of code to deal with many
different inputs and the idiosyncractic historical rules of legal citation for
those types, and would be difficult for would-be package improvers to understand
at first. Reference types such as \rtype{procart}, designed to cover a narrower
class of references and that include fewer features, would be easier to revise
to one's tastes.

%</alltypes>
%<*support>
\clearpage
\part{Supporting Packages}
\label{p:support}

\hia* includes several supporting packages, primarily consisting of lower-level
tools for macro writing. They are distributed in standalone form in case they
are useful for other package authors.

%</support>
%<*appendix>
\clearpage
\appendix
\part{Appendix}
\label{p:appendix}
%</appendix>
