%%
%% \iffalse filename: quickstart.dtx \fi
%%
%<*driver>
\input driver
\thisis{quickstart}{Quick Start}

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

You've done the research, your stack of cases and articles is overflowing, the
ideas are swimming in your head, and are ready to start writing. But as you open
your document, a troubling question creeps in.

\emph{Will you format citations as you
write?} That will interrupt your train of thought every few minutes as you pull
out the style guide. And as you edit and rearrange, your citations
will need to be redone many times over. All those \emph{supra} and \emph{id.\@}
citations will quickly become out of place and perhaps unintelligible as you
polish the text.

\emph{Or will you put off citation formatting
for later?} In that case your coauthors and draft reviewers will see a mess of
an unfinished paper. And you'll have to reserve hours or days before submitting
for publication, to
slog through an unrewarding round of citation formatting.

\hia* offers a better way. With it, you can type citations in your writing
concisely and efficiently, but with all the features of
a rich legal citation system. You can edit and reorganize with almost no
need to manually update existing citations in your document. And you can
produce correctly formatted citations at any stage of the writing process, so
that
when you and others are reviewing drafts, you aren't distracted by incomplete
formatting.

I have been developing \hia* since I started law school in 2004. In the years
since, I have used it to format tens of thousands of citations in hundreds of
legal briefs, administrative comments, and journal articles. It produces tables
of authorities without hesitation and handles lengthy law review pieces without
difficulty. I can confidently polish my pieces right up to the deadline, knowing
that my \emph{supra} and \emph{id.}\ citations will still be perfect after a
recompile.

Most
importantly, when the computer handles the appearance of my writing, I get to
focus on the substance. This has made the writing process far more rewarding and
enjoyable. Have you ever read through one of your own drafts and thought,
``Part II.A really belongs after II.B, but it'll be too much trouble to fix
the footnotes''? I don't. \hia* lets me strive toward my best work, rather
than settling for the easy but imperfect.

To me, \hia* is an indispensable tool for legal writing.
I hope it will also become your choice hereinafter.




\section{Quick Start Guide}


This introductory guide will show the basic concepts you'll need to use \hia* to
add citations to your document. As with other automated citation systems, you
will need to do two things:
\begin{enumerate}
\item Define your references (cases, books, articles,
and so on) by entering bibliographic information for them.
\item Cite references by entering citation commands into your document.
\end{enumerate}

Importantly, these two steps do not need to be done in order. In my personal
workflow, I will often first write, entering citation commands for references
that I've read but have not defined. I find that this order preserves my train
of thought best. \hia* displays a list of undefined references and other missing
items at the end of document compilation, conveniently letting you know what
needs to be fixed.


\subsection{Prerequisites}

At this stage, I assume that you have general knowledge both of legal citation
and of the \LaTeX\ typesetting system. \hia* operates purely within \LaTeX, and
is controlled by commands described below in this manual.

To begin, you should include the package in the preamble of your document:
\begin{demo}
|\usepackage|\oarg{options}|{hicite}|
\end{demo}
The \meta{options} are described in \sec{options}. The most important of these
are the options \opt{review} and \opt{memo}, which determine whether the package
will follow the rules for law review articles or for legal memoranda,
respectively.




\subsection{Defining References}

A \emph{reference} is a single work of authority that you want to cite. In order
to cite a reference in \hia*, you must ``define'' it by entering key information
about the reference.

To define a reference, you will need to (1) choose a nickname
for the reference, (2) determine the type of reference, and (3)
identify the relevant bibliographic information for the type.
Part~\ref{p:alltypes} lists the available reference types; common ones are
\rtype{book}, \rtype{case}, \rtype{website}, and \rtype{jrnart} (journal
articles). The bibliographic information is entered as parameter-value pairs.
For example:
\begin{demo}
|\defcase{wheaton}{| \\
|    p=Wheaton,| \\
|    d=Peters,| \\
|    vol=33,| \\
|    rep=U.S.,| \\
|    page=591,| \\
|    year=1834,| \\
|}|
\end{demo}
defines a reference named |wheaton| for the famous lawsuit between two Supreme
Court reporters.
For a more detailed overview of how to define references, see \sec{refs-syntax}
and the sections that follow.


\hia* permits for various shortcuts to simplify the definition of references.
The following are equivalent to the above definition:
\begin{demo}
|\defcase{wheaton}{| \\
|    parties=Wheaton v. Peters,| \\
|    cite=33 U.S. 591,| \\
|    year=1834,| \\
|}| \\
|\defcase{wheaton}{| \\
|    Wheaton v. Peters, 33 U.S. 591 (1834)| \\
|}|
\end{demo}
Shortcuts for reference definition are described in \sec{cparse}.

A wide range of types of references can be defined in \hia*. The full list, with
many example definitions, is given in Part~\ref{p:alltypes}. For example, here
is how one would define a reference for this manual:
\begin{demo}
|\defbook{hereinafter}{| \\
|    author=Charles Duan,| \\
|    title=Hereinafter: A Legal Citation Program,| \\
|    year=|\texttt{\the\year}|,| \\
|}|
\end{demo}

A key difficulty with legal citation is the wide range of possible parameters to
a reference definition---different types of authors, date formats, optional
parentheticals, and more. \hia* provides structure to that range of
possibilities, thereby offering as much flexibility as possible while retaining
consistency. Consider, for example, the problem of a work written by a person
employed by an institution. You may consider both the person and the institution
to be the ``author.'' \hia* allows for this:
\begin{demo}
|\defbook{ftc-pharma}{| \\
|    author=Markus H. Meier et al.,| \\
|    instauth=Federal Trade Commission,| \\
|    title=Overview of FTC Actions [...],| \\
|    date=june 2019,| \\
|}|
\end{demo}
All parameters are described in Part~\ref{p:allparams}. Authors and dates are
the most complex parameters; they are described in \sec{names} and \sec{dates},
respectively.





\subsection{Entering Citations}

To cite references in a document, the key commands are |\sentence| and
|\clause|, which produce sentence-style and clause-style citations. For law
review articles, these commands should be used in footnotes, and the |\note|
command creates a footnote with a sentence-style citation.

All of these commands receive a single argument of a citation string following a
syntax described in \sec{parse}. By design, the syntax looks like a simplified
legal citation. The following would generate a two-element string-cite to
\emph{Wheaton v.~Peters}, describing a (hypothetical) tension between two parts
of the decision:
\begin{demo}
\inputtext{\sentence{see, e.g., wheaton at 598 note 3 (Story, J.)
(describing holding); but see wheaton at 600-602 (noting alternative views)}.}
\Produces
\emph{See, e.g.}, \emph{Wheaton v.~Peters}, 33 U.S. 591, 598 n.3
(1834) (Story, J.) (describing holding); \emph{but see} \emph{id.}~at 600--02
(noting alternative views).
\end{demo}

This example shows a number of notable features of \hia*. First, references are
always cited by identifier; any short or \emph{id.}~form is selected
automatically without user intervention. This means that citations are portable:
They largely can be moved around the document unchanged, simplifying
reorganizations of one's writing.

Second, there is rich support for signals, pin cites, and parentheticals in
citations. In particular, pin cites can involve page numbers, section numbers,
footnotes, and more, as described in \sec{pages}. They are abbreviated
automatically, as shown above. Parentheticals and signals are
also ordered, arranged, and formatted appropriately.

Third and perhaps most importantly, nearly all the formatting work is hidden
from the writer. Abbreviations, fonts, and keywords are automatically chosen to
conform to a given citation system. Importantly, this makes it easy to conform
an already-written document to another citation system. If one journal prefers
small caps but another does not, it is simple to produce different documents for
each.

\paragraph{Inline Citations}
In addition to sentence and clause citations, \hia* supports citing references
as parts of the text: naming a case as the subject of a sentence, for example.
The relevant commands are |\inline|, |\Inline|, |\adjective|, and |\Adjective|
depending on whether the reference is being cited at the beginning of a sentence
and the part of speech the reference is taking on:
\begin{demo}
\inputtext{In \inline{wheaton}, the Court.... \sentence{wheaton at 603}.}
\Produces In \emph{Wheaton v.~Peters}, the Court\ldots. \emph{See} 33 U.S. 591,
603 (1834).
\end{demo}
Note how the |\sentence| citation automatically omits the case name because it
was displayed in with the previous |\inline| command.

For more on the parts and syntax of sentence, clause, and inline citations, see
Part~\ref{p:citations}.



\subsection{Cross-References}

\hia* also provides extensive support for cross-references. This requires not
only commands for inserting cross-reference citations, but also commands for
marking portions of the document to be referenced.

The |\hilabel| command marks a part of a document for cross-referencing.
Optionally, a range of a document can be marked using |\hiendlabel| as follows:
\begin{demo}
|\hilabel{keypart}| \\
|This is the key part!| \\
|\hiendlabel{keypart}|
\end{demo}
The command automatically chooses the best way to refer to the marked
section depending on where it is used:
\begin{itemize}
\item When called in a footnote, the cross-reference is to the footnote number.
\item When used in a figure, the cross-reference is to the figure number.
\item When used in main body text, \hia* chooses a cross-reference form
depending on the document type: page numbers for a \opt{memo}-style document,
and nearest footnotes for a \opt{review}-style document (``text accompanying
notes \emph{x}--\emph{y}'').
\end{itemize}

Additional commands give further options for cross-references.
The |\hisectlabel| command can label sections by number, and |\hitanlabel|
(terminated with |\hiendtanlabel|) produces a cross-reference citation to
both text and footnotes (written as ``notes \emph{x}--\emph{y} and accompanying
text'').

To insert a cross-reference, simply use a citation to the reference
\rtype{this} with the cross-reference label as the pincite:
\begin{demo}
|\sentence{see this at keypart}.|
\end{demo}
Again, the value of this cross-referencing system is that the cited numbers
automatically update as the document is edited, minimizing the amount of manual
updating.

The full cross-referencing system is
described in
\sec{xref}.


\subsection{Additional Features}

In addition to the above, \hia* provides additional features of
interest to many authors of legal documents:
\begin{itemize}
\item It can produce tables of authorities, as described in \sec{toa}.
\item It can switch footnotes into endnotes, as described in \sec{endnotes}.
\item It can manage abbreviations in text, as described in for reference type
\rtype{abbrev}, properly inserting the full version and an explanatory
parenthetical the first time the term is used.
\item It properly line-breaks URLs, as described in \sec{urls}, avoiding
unsightly gaps; it also provides several alternate means of presenting URLs in
documments.
\end{itemize}
These, of course, are in addition to the many features of \hia* that you
\emph{don't have to think about anymore}: abbreviations, short citations, font
selection, \emph{supra} note numbers, and more.



%</doc>