%%
%% \iffalse filename: prelims.dtx \fi
%%
%<*driver>
\input driver
\thisis{prelims}{Preliminaries}

This is a file used only for production of documentation.
%\endinput
%</driver>
%<*doc>


\section{Preliminary Matters}


\subsection{Structure of the Manual}

Besides simply describing how \hia* works, this manual is intended to explain my
conceptual framework for legal citation that is embedded in the system.
With that framework in mind, this manual on a
more practical level then teaches writers how to write citation input commands
that will produce formatted citations meeting their needs, and explains how
those inputs are formatted. As a result, it has three main objectives:
\begin{itemize}
\item Describing the data model behind \hia*'s legal citations
\item Specifying the input formats that writers must use
\item To a lesser extent, explaining the algorithms for producing formatted
citations
\end{itemize}

The manual is organized topically for different elements of legal citations,
with each section covering these three objectives of the data model, input
formats, and formatting algorithms (to the extent that each objective is
relevant). There are five parts:
\begin{enumerate}
\item How references are defined, including common parameters of references such
as authors and dates.
\item How citations are entered into documents.
\item General formatting algorithms used, such as keeping track of previous
citations for short forms.
\item All reference definition parameters.
\item All reference types.
\end{enumerate}

As currently written, this manual is primarily for writers of legal
documents who already have a baseline knowledge of legal citation, and
secondarily for software developers who wish to learn how the system works so
that they can modify it to produce different citation formats. It is not as
useful for learning how to format legal citations, as most citation manuals are.
First, it explains the formatting of citations in a manner that is useful to
programmers but probably confusing to human cite-checkers. \unskip\footnote{In
particular, a computer reads and formats citations sequentially, starting
from the beginning and never looking backwards, so at any given point it must
keep track of a great deal of information in memory about prior citations.
Computers do this easily, but a person would have to write copious and
error-prone notes to check the citations purely in forward order. A more
reasonable approach for a person would be to read the citations backwards to
find necessary information about previous citations.} Second, this manual does
not discuss the meanings of citation elements: It does not explain what citation
signals mean, when parentheticals are appropriate, or which edition of a book to
cite, for example.

It would not be difficult to revise this manual to address
these deficiencies and turn it into a guide on manual citation formatting, by
augmenting the data model sections to describe semantics and by rewriting the
formatting algorithm sections. Were that work to be done, the hope is that
presenting students with a data model and principles in tandem with formats
would offer them a clearer, enriched view of the seemingly arcane world of legal
citation.

\paragraph{Grammatical structures}
In many places, this manual describes expected inputs in terms of grammatical
structures. These are shown in blue boxes and use a version of Backus-Naur form.
\unskip\footnote{Spaces between items are not specified rigorously in these
grammars.}
For example:
\begin{grammar}
\meta{address} := \meta{number} \meta{street} [ \meta{apartment} ] \|
\littext{PO Box} \meta{number}
\end{grammar}
For those unfamiliar with this notation:
\begin{itemize}
\item The items between angle brackets represent text values, akin to entry
spaces in a form.
\item := means that the item on the left is defined to consist of the specified
items on the right.
\item \| means to choose either of the items to the left or right.
\item Square brackets [ ]  mean that the material inside is optional.
\item \underline{Underlined} text needs to be included literally.
\item ( \meta{item} )* means that whatever is inside the parentheses can be
repeated (or used once, or omitted entirely).
\end{itemize}

So to explain the above statement, an \meta{address} can take on two forms. It
can be a \meta{number} followed by a \meta{street} and optionally an
\meta{apartment} number, such as ``123 Elm Lane'' or ``15 Broadway \#5. Or it
can be a post office box like ``PO Box 123''. In general, grammatical
definitions will be followed by examples to help demonstrate what input is
expected.

In other cases, the manual will show expected inputs using a \LaTeX\ syntax:
\begin{grammar}
|\command|\oarg{option}\marg{required}
\end{grammar}
This means that the macro |\command| accepts an optional argument \meta{option},
surrounded by square brackets if present, and needs a mandatory argument
\meta{required}, surrounded by curly braces.

\paragraph{Documentation files}
This manual is one of two parts of documentation for \hia*. The package source
code is contained in multiple module files compiled into a unified main package,
and most chapters of this manual correspond to module files. The module files
are written as literate programming \LaTeX\ |.dtx| files, and contain further
documentation of the internal macros and implementation. For each chapter
having a corresponding module file, the filename is listed in the margin so that
the expanded documentation can be identified.

The manual alone should be sufficient for writers of legal documents to
understand how to use \hia*. The module file documentation is intended to help
package authors who wish to correct, modify, or extend the citation program
itself, perhaps to adapt it to other citation formatting regimes.




\subsection{Installation and Usage}


\hia* comprises a suite of files:
\begin{itemize}
\item The package file itself, \texttt{hicite.sty}.
\item Several auxiliary package files, described in \pt{support}.
\item Tables of abbreviations and other information.
\end{itemize}
All of these files need to be installed in a \TeX-accessible location.

To use the package, simply include it in a document:
\begin{demo}
|\usepackage|\oarg{options}|{hicite}|
\end{demo}
Then compile it using \LaTeX\ or an equivalent. No auxiliary programs are
needed, even for table indexing. However, multiple compilation runs may be
necessary in order to get cross-references and short citations to be correct.

If you have an existing Biblatex file, see \sec{hibib} for possible
compatibility options.



\subsection{Interaction with Other Packages}

\hia* is designed to be as self-contained as possible, minimizing its
dependencies on other packages. The packages that it requires are
\ListOfRequiredPackages, in addition to several auxiliary packages bundled with
\hia*.

The package also attempts to make minimal modifications to the \LaTeX\
environment, in order to limit potential conflicts with other packages. However,
some modifications are essential due to the fact that legal citations interact
closely with the underlying document structure. The following is a list of
general considerations with regard to package interactions and conflicts:
\begin{itemize}
\item The |\footnote| macro is modified to install some beginning and ending
hooks, so that the package can perform accounting of citations at each
footnote (see \sec{state-footnote}). Other packages that modify footnotes may
conflict with these modifications. In particular, most standard endnote packages
will not work with \hia* or legal citation generally, which is why the package
provides its own endnote feature (see \sec{endnotes}).

\item URL processing is handled internally by \hia* (see \sec{urls}). This
generally should not cause conflicts with other packages, although the package
will optionally define a standalone |\url| command for typesetting URLs.
Depending on the \TeX\ engine being used, it may also be necessary to select or
implement a driver for emitting hyperlink code (see \sec{urls-drivers}).

\item Cross-references in \hia* use different commands from standard \LaTeX\
references, but the package uses the same underlying data storage. The two
cannot be intermixed (e.g., the |\ref| and command cannot be used with \hia*
cross-references).

\item Some common macro names are defined and used in the package. Some of these
are the interface of user-level commands, which are listed in the index of this
manual. Internal macro names are generally prefixed with |\hi@| to avoid package
conflicts, and less-common user macros are generally prefixed with |\Hi| and
written in CamelCase. Where user macro names have been changed to conform to
these conventions, the older macro names are defined as specified in
\sec{legacy}, in a manner that avoids or warns about conflicts.

\item The command |\textellipsis| is redefined as specified in \sec{iface-misc},
to conform with typical legal citation standards.
\end{itemize}

The following are some notes on specific packages and their interaction with
\hia*.

\begin{itemize}
\item \textbf{hyperref}: This works, but the |hyperfootnotes| option should be
turned off. Additionally, both packages provide a |\url| command; see \sec{urls}
on selecting between them.

\item \textbf{sidenotes}: If included, \hia* will detect it and modify the
|\sidenote| macro analogously to what it does to |\footnote|. It is recommended
that documents using sidenotes use legal memorandum formatting (see option
\opt{memo}), because law review formatting depends heavily on having a single,
continuous series of footnotes.

\item \textbf{tex4ht}: This largely works but sometimes has difficulty with
converting URLs and footnotes. The author has some experimental configuration
files that can help with this, although they are not extensively tested.

\item \textbf{biblatex}: While this package is not compatible with other
citation systems, it does not override them, so other citation systems could
theoretically be used in tandem. (In particular, the |\cite| macro is
unchanged.) There is a partial implementation of a Biblatex converter, described
in \sec{hibib}.
\end{itemize}


\subsection{Intellectual Property Concerns}

Over the years, there have been multiple disputes over intellectual property in
legal citation systems and manuals. It is necessary to address both what
rights I claim as the author of \hia*, and what rights of others it implicates.

The source code of \hia* is released under the GNU General Public License (GPL)
version 3.0. That license applies to any executable code. The text of this
manual itself and all other documentation is released under a Creative Commons
license as described on the first page of the manual.
For purposes of clarity, the Creative Commons license applies to any text found
in this user manual and any text found in comments in the package source code;
the GPL license applies otherwise.

With respect to other legal citation manuals and systems, this software and
manual are not endorsed by, affiliated with, or authorized by any other legal
citation system, such as the Bluebook, the University of Chicago Manual of Legal
Citation (the ``Maroonbook''), the ALWD Guide to Legal Citation, or the Indigo
Book. It does not claim to be compatible with or identical to any of those
systems; indeed a design principle of \hia* is to be more flexible than any of
these existing systems. To the extent that material from existing citation
systems is used (primarily for tables of abbreviations), it has been taken from
the Indigo Book, which has been placed in the public domain.

%</doc>
