summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/amsrefs/amsrdoc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/amsrefs/amsrdoc.tex')
-rw-r--r--macros/latex/contrib/amsrefs/amsrdoc.tex1867
1 files changed, 1867 insertions, 0 deletions
diff --git a/macros/latex/contrib/amsrefs/amsrdoc.tex b/macros/latex/contrib/amsrefs/amsrdoc.tex
new file mode 100644
index 0000000000..ea3357a190
--- /dev/null
+++ b/macros/latex/contrib/amsrefs/amsrdoc.tex
@@ -0,0 +1,1867 @@
+%% filename: amsrdoc.tex
+%% version: 1.04
+%% date: 2013/01/16
+%%
+%% American Mathematical Society
+%% Technical Support
+%% Publications Technical Group
+%% 201 Charles Street
+%% Providence, RI 02904
+%% USA
+%% tel: (401) 455-4080
+%% (800) 321-4267 (USA and Canada only)
+%% fax: (401) 331-3842
+%% email: tech-support@ams.org
+%%
+%% Copyright 2004, 2006-2008, 2010, 2013 American Mathematical Society.
+%%
+%% This work may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either version 1.3c
+%% of this license or (at your option) any later version.
+%% The latest version of this license is in
+%% http://www.latex-project.org/lppl.txt
+%% and version 1.3c or later is part of all distributions of LaTeX
+%% version 2005/12/01 or later.
+%%
+%% This work has the LPPL maintenance status `maintained'.
+%%
+%% The Current Maintainer of this work is the American Mathematical
+%% Society.
+%%
+%% ====================================================================
+
+\documentclass[oneside]{amsdtx}
+
+\hyphenation{herme-neutics}
+
+\usepackage{amsrefs}
+\usepackage{amsthm}
+
+\renewcommand*\descriptionlabel[1]{\hspace\labelsep
+ \normalfont\bfseries #1:}
+
+\newcommand{\nshline}{\hline\omit\\}
+
+\makeatletter
+
+\newtheoremstyle{note}{3pt}{3pt}{}{}{\bfseries}{:}{.5em}{}
+
+\theoremstyle{note}
+\newtheorem*{note}{Note}
+
+\def\nitem[#1]{\item[#1\@gobble]}
+
+\DeclareRobustCommand{\fld}{\category@index{field}}
+\DeclareRobustCommand{\btype}{\category@index{entry type}}
+
+\DeclareRobustCommand{\attr}{\category@index{attribute}}
+
+\makeatother
+
+\newcommand{\rpack}[1]{\pkg{amsrefs} package}
+
+\providecommand{\cnbreak}{\penalty999\hskip0pt\relax}
+\providecommand{\cnm}[2]{\cn{#1}\cnbreak\embrace{#2}}
+\providecommand{\cnom}[1]{\cn{#1}\cnbreak\ommitude}
+\providecommand{\ommitude}[2][]{{\ntt[#1]}\cnbreak\embrace{#2}}
+\providecommand{\cnmsm}[4]{%
+ \cn{#1}\cnbreak\embrace{#2}\cnbreak *\embrace{#4}}
+
+\DeclareTextSymbol{\lbracechar}{OT1}{123}
+\DeclareTextSymbolDefault{\lbracechar}{OT1}
+\DeclareTextSymbol{\rbracechar}{OT1}{125}
+\DeclareTextSymbolDefault{\rbracechar}{OT1}
+
+\providecommand{\embrace}[1]{%
+ \begingroup \ntt\lbracechar#1\rbracechar\endgroup}
+
+\title{User's Guide to the \pkg{amsrefs} Package}
+\author{David M. Jones\\American Mathematical Society}
+\date{January 16, 2013}
+
+\begin{document}
+
+\maketitle
+
+\tableofcontents
+
+\section{Introduction}
+
+\pkg{amsrefs} is a \LaTeX\ package for preparing bibliography or
+reference lists. It attempts to provide many of the convenient
+features that \LaTeX\ and \BibTeX\ users have come to expect without
+imposing all of the overhead that \BibTeX\ entails. In particular, it
+has been carefully designed to encourage the preservation of
+structured markup of the bibliography throughout the entire lifetime
+of a document from rough draft to final archival version. As we shall
+see, it does this by replacing \LaTeX's unstructured \fn{.bbl} file
+format by a new, fully structured format. The package is compatible
+with the \pkg{showkeys}, \pkg{hyperref},\footnote{Note that unlike
+ most packages, which must be loaded \emph{before} \pkg{hyperref},
+ the \pkg{amsrefs} package must be loaded \emph{after} \pkg{hyperref}
+ in order to work properly.} and \pkg{backrefs} packages and
+implements the functionality of the popular \pkg{cite} package.
+Interoperability with \BibTeX\ is supported via a special bibliography
+style file, but \pkg{amsrefs} can be used without \BibTeX.
+
+\section{Using the \pkg{amsrefs} package}
+
+There are three ways of using the \rpack/:
+\begin{enumerate}
+
+\item
+Enter bibliography items directly in your \latex/ document using the
+\env{biblist} environment and the \cn{bib} command.
+
+\item
+Import items from an external \fn{.ltb} file.
+
+\item
+Import items from a \fn{.bib} file using \bibtex/ and the special
+bibliography styles distributed with the \pkg{amsrefs} package.
+
+\end{enumerate}
+
+\subsection{Direct entry of bibliography items}\label{direct-entry}
+
+The most basic way to use \pkg{amsrefs} is to enter the bibliography
+items directly in your \LaTeX\ document. For example, consider the
+following very short document:
+\begin{quote}
+ Alan Sokal~[2] recommends Bourbaki's text~[1]
+ for a gentle introduction to set theory.
+
+ \begin{bibsection}
+ \begin{biblist}
+
+ \bib{Bourbaki70}{book}{
+ title={Th\'eorie des ensembles},
+ author={Bourbaki, Nicolas},
+ date={1970},
+ publisher={Hermann},
+ address={Paris}
+ }
+
+ \bib{Sokal96}{article}{
+ title={Trangressing the boundaries},
+ subtitle={Toward a transformative hermeneutics of quantum gravity},
+ author={Sokal, Alan},
+ journal={Social Text},
+ volume={46/47},
+ date={1996},
+ pages={217--252}
+ }
+
+ \end{biblist}
+ \end{bibsection}
+\end{quote}
+Using \pkg{amsrefs}, this document would be coded as follows:
+\begin{verbatim}
+ \documentclass{article}
+
+ \usepackage{amsrefs}
+
+ \begin{document}
+
+ Alan Sokal~\cite{Sokal96} recommends Bourbaki's
+ text~\cite{Bourbaki70} for a gentle introduction to set theory.
+
+ \begin{bibdiv}
+ \begin{biblist}
+
+ \bib{Bourbaki70}{book}{
+ title={Th\'eorie des ensembles},
+ author={Bourbaki, Nicolas},
+ date={1970},
+ publisher={Hermann},
+ address={Paris}
+ }
+
+ \bib{Sokal96}{article}{
+ title={Trangressing the boundaries},
+ subtitle={Toward a transformative hermeneutics of quantum gravity},
+ author={Sokal, Alan},
+ journal={Social Text},
+ volume={46/47},
+ date={1996},
+ pages={217--252}
+ }
+
+ \end{biblist}
+ \end{bibdiv}
+
+ \end{document}
+\end{verbatim}
+Compared to the standard \LaTeX\ markup for bibliographies, there are
+two main differences:
+\begin{itemize}
+
+\item
+The functions of the \env{thebibliography} environment are split
+between two new environments: \env{bibdiv}, which produces the chapter
+or section heading for the bibliography, and \env{biblist}, which
+contains the reference list per se. These environments will be
+covered in more detail in sections \ref{biblist} and~\ref{bibdiv}.
+
+\item
+The \cn{bibitem} command is replaced by the \cn{bib} command, which is
+very similar to a \BibTeX\ database entry. However, as we shall see
+in section~\ref{bib-command}, there are some significant differences.
+
+\end{itemize}
+
+\subsection{Using an \fn{.ltb} database file}\label{ltb-files}
+
+The second way of using \pkg{amsrefs} is to keep your \cn{bib}
+commands in a separate database file and have \pkg{amsrefs} import the
+ones that are needed. For example, suppose you have a file
+\fn{nonsense.ltb} with the following contents:
+\begin{verbatim}
+ \documentclass{article}
+
+ \usepackage{amsrefs}
+
+ \begin{document}
+
+ \begin{bibdiv}
+
+ \begin{biblist}
+
+ \bib{Bourbaki70}{book}{
+ title={Th\'eorie des ensembles},
+ author={Bourbaki, Nicolas},
+ date={1970},
+ publisher={Hermann},
+ address={Paris}
+ }
+
+ \bib{Sokal96}{article}{
+ title={Trangressing the boundaries},
+ subtitle={Toward a transformative hermeneutics of quantum gravity},
+ author={Sokal, Alan},
+ journal={Social Text},
+ volume={46/47},
+ date={1996},
+ pages={217--252}
+ }
+
+ \bib{SokalB1998}{book}{
+ title={Fashionable Nonsense},
+ subtitle={Postmodern Intellectuals' Abuse of Science},
+ author={Sokal, Alan},
+ author={Bricmont, Jean},
+ publisher={Picador USA},
+ address={New York},
+ date={1998}
+ }
+
+ \end{biblist}
+
+ \end{bibdiv}
+
+ \end{document}
+\end{verbatim}
+Before seeing how this affects our sample document, take note of a
+couple of aspects of the format of \fn{nonsense.ltb}:
+\begin{enumerate}
+
+\item
+We have chosen to format \fn{nonsense.ltb} as a complete \LaTeX\
+document. This is so we can produce a formatted listing of our whole
+database by running \fn{nonsense.ltb} through \LaTeX. However, this
+is not necessary; when \pkg{amsrefs} treats \fn{nonsense.ltb} as a
+database file, it ignores everything except for the \cn{bib} commands.
+
+\item
+Each \cn{bib} command in the \fn{.ltb} file \emph{must} begin on a new
+line, and the first two arguments and the open brace of the third
+argument must be on that same line. Failure to follow this format may
+result in \pkg{amsrefs} getting terribly confused and aborting the
+processing of your document.
+
+\end{enumerate}
+
+With that out of the way, let's look at how this affects our main
+file, which we'll call \fn{sample.tex}:
+\begin{verbatim}
+ \documentclass{article}
+
+ \usepackage{amsrefs}
+
+ \begin{document}
+
+ Alan Sokal~\cite{Sokal96} recommends Bourbaki's
+ text~\cite{Bourbaki70} for a gentle introduction to set theory.
+
+ \begin{bibdiv}
+ \begin{biblist}
+
+ \bibselect{nonsense}
+
+ \end{biblist}
+ \end{bibdiv}
+
+ \end{document}
+\end{verbatim}
+When you run this document through \LaTeX, \pkg{amsrefs} will create a
+file \fn{sample.bbl} that contains all the relevant \cn{bib} entries
+from \fn{nonsense.ltb}. This is very similar to using \BibTeX, but
+with a few noteworthy differences:
+\begin{itemize}
+
+\item
+Because all processing is being handled by \latex/, the contents of
+the bibliography can be printed on the first pass; citation labels,
+consequently, are resolved on the second pass.
+
+\item
+Unlike \BibTeX, which adds the \env{thebibliography} environment
+automatically, \pkg{amsrefs} requires you to supply the \env{bibdiv}
+and \env{biblist} environments yourself. As we shall see later, this
+results in greater flexibility in the formatting of bibliographies.
+
+\item
+There is no need for a \cn{bibliographystyle} command.
+
+\item
+No sorting of the bibliography items is done. The entries will appear
+in your document in the same order that they appeared in the database
+files.
+
+\end{itemize}
+Like the \cn{bibliography} command, \cn{bibselect} can be given
+multiple files to process:
+\begin{verbatim}
+ \bibselect{bib1,bib2}
+\end{verbatim}
+and can be used multiple times in your document:
+\begin{verbatim}
+ \bibselect{bib1}
+ \bibselect{bib2}
+\end{verbatim}
+Normally each \cn{bibselect} command will only import entries that
+have been explicitly cited in your document. If you want to import
+all entries from a given file, you can use the $*$-variant:
+\begin{verbatim}
+ \bibselect*{sample}
+\end{verbatim}
+This is similar to the use of \label{nocite}\verb|\nocite{*}| but
+allows finer control. You can still use \verb|\nocite{*}|, but with
+one restriction: it only applies to \cn{bibselect} commands that occur
+after it in the document.
+
+The \cn{bibselect} command regenerates the \fn{.bbl} file each time
+the document is \LaTeX ed (unless, of course, the \cn{nofiles} switch
+is used). Once your bibliography is completed, you might wish to
+replace the \cn{bibselect} command by the contents of the \fn{.bbl}
+file to prevent any further modifications. This is particularly
+important if you need to edit the contents of the \fn{.bbl} file in
+any way (say, to re-order the items or adjust the capitalization of
+titles to match the style of the journal you are publishing in or to
+put in explicit line or page breaks). This will make your document
+more self-contained, which will make it easier to reuse and archive.
+
+\subsection{Using the \rpack/ with \bibtex/}
+
+Finally, you can use \pkg{amsrefs} in conjunction with \BibTeX:
+\begin{verbatim}
+ \documentclass{article}
+
+ \usepackage{amsrefs}
+
+ \begin{document}
+
+ Alan Sokal~\cite{Sokal96} recommends Bourbaki's
+ text~\cite{Bourbaki70} for a gentle introduction to set theory.
+
+ \bibliography{nonsense}
+
+ \end{document}
+\end{verbatim}
+Note two things:
+\begin{itemize}
+
+\item
+Unlike when you use \cn{bibselect} to import entries from a \fn{.ltb},
+in this case the \fn{.bbl} \emph{will} contain the \env{bibdiv} and
+\env{biblist} environments.
+
+\item
+There is no need for a \cn{bibliographystyle} command; \pkg{amsrefs}
+will automatically invoke the correct style. In fact, any
+\cn{bibliographystyle} command you put in your document will be
+ignored.
+
+\end{itemize}
+
+The main advantages of using \BibTeX\ are:
+\begin{itemize}
+
+\item
+you can take advantage of \BibTeX's ability to sort your items for
+you, and
+
+\item
+you can take advantage of the large number of \BibTeX\ database files
+already in existence.
+
+\end{itemize}
+
+As when using an \fn{.ltb} file, you may wish to replace the
+\cn{bibliography} command by the contents of the \fn{.bbl} file when
+you have finished compiling your bibliography.
+
+\section{The \protect\env{biblist} and \env{biblist*} environments}
+\label{biblist}
+
+As alluded to earlier, \env{thebibliography} performs two distinct
+functions: first, it produces the section heading for the bibliography
+and second, it provides the list environment for formatting the
+bibliography entries.
+
+In \pkg{amsrefs} these functions are performed by two distinct
+environments, \env{bibdiv} and \env{biblist}. As its name suggests,
+the \env{biblist} environment provides the second function. So, if
+you wanted a list of references with no heading at all, you could just
+leave out the \env{bibdiv} environment.
+
+The \env{biblist} environment has an optional argument to allow
+changing the list parameters. For example, suppose you know that your
+bibliography has between 100 and 999 entries and you want to ensure
+that there is enough space allocated for the labels on the first pass.
+You could write
+\begin{verbatim}
+ \begin{biblist}[\resetbiblist{999}]
+\end{verbatim}
+to tell \LaTeX\ to leave enough room for labels that are three digits
+long. Similarly, if you want your bibliography typeset in the normal
+font size instead of footnotesize, you could write
+\begin{verbatim}
+ \begin{biblist}[\normalsize]
+\end{verbatim}
+Want your bibliography numbered starting with~0 instead of~1? Just
+write
+\begin{verbatim}
+ \begin{biblist}[\setcounter{bib}{-1}]
+\end{verbatim}
+
+The \env{biblist} environment also takes a second optional argument
+that can be used to modify the current bibliography. This argument
+consists of an asterisk followed by a set of key-value pairs
+surrounded by braces:
+\begin{verbatim}
+ \begin{biblist}*{key={val},...}
+\end{verbatim}
+Two keys are supported at present:
+\begin{description}
+
+\item[labels]
+
+Set this to ``numeric,'' ``alphabetic,'' or ``shortalphabetic'' to
+override the default label style for the current bibliography.
+
+\item[prefix]
+
+The value of this key will be prepended to each of the labels in the
+current bibliography.
+
+\end{description}
+\begin{note}
+Neither of these can be used with the \opt{author-year} option.
+\end{note}
+For example, if you are using numeric labels, then
+\begin{verbatim}
+ \begin{biblist}*{prefix={A}}
+\end{verbatim}
+will cause the items to be labeled ``A1,'' ``A2,'' etc. Similarly,
+\begin{verbatim}
+ \begin{biblist}*{labels={alphabetic}}
+\end{verbatim}
+will cause the current list to be labeled alphabetically instead of
+numerically.
+
+\begin{note}
+Depending on your specific use of \cn{cite}s, use of non-numeric
+prefixes or of mixed numeric and non-numeric label styles can
+interfere with citation sorting and compression
+(section~\ref{sec:sorting}). You may need to pass the
+\opt{non-sorted-cites} and \opt{non-compressed-cites} options to
+amsrefs to get the correct behavior.
+\end{note}
+
+If you want to use both types of optional arguments, the key-value
+pairs come second:
+\begin{verbatim}
+ \begin{biblist}[\normalsize]*{...}
+\end{verbatim}
+
+Each \env{biblist} environment resets the \cnt{bib} counter so that
+its items are numbered starting from~1. If you want the numbering to
+start where the last \env{biblist} left off, use the \env{biblist*}
+environment instead.
+
+Finally, users familiar with the \env{thebibliography} environment may
+wonder why \env{biblist} doesn't have a mandatory argument to specify
+the longest label. The reason is that the \env{biblist} environment
+automatically calculates the width of the longest label and stores
+this information in the \fn{.aux} file. This means that the next time
+\LaTeX\ is run, the environment will know how much space to leave for
+the labels.
+
+\section[Section titles for bibliographies: \env{bibdiv} et
+ al.]{Section titles for bibliographies: \env{bibdiv},\\
+ \env{bibsection}, \env{bibchapter}}
+\label{bibdiv}
+
+As seen earlier, the \env{bibdiv} environment provides an appropriate
+section heading. Ordinarily that's all you need to know, since
+\env{bibdiv} will automatically switch between a \cn{chapter} and a
+\cn{section} heading depending on whether the document seems booklike
+or articlelike. Simililarly, it will use the current value of
+\cn{bibname} or \cn{refname} for the heading text. However, if that's
+not sufficient, there are three more ways of customizing its behavior:
+\begin{enumerate}
+
+\item
+Instead of \env{bibdiv}, you can use \env{bibchapter} or
+\env{bibsection} to generate the appropriate type of heading.
+
+\item
+All three environments take an optional argument to override the text
+of the heading:
+\begin{verbatim}
+ \begin{bibchapter}[Annotated Bibliography]
+\end{verbatim}
+
+\item
+For maximum flexibility, you can omit the \env{bibdiv} environment
+entirely and optionally add an arbitrary header:
+\begin{verbatim}
+ \subsection{Further reading}
+\end{verbatim}
+
+\end{enumerate}
+
+Finally, note that a further significant benefit of having separate
+\env{bibdiv} and \env{biblist} environments is that you can put
+arbitrary introductory text between the header and the list:
+\begin{verbatim}
+ \begin{bibdiv}
+
+ Abbreviations used:
+
+ ...
+
+ \begin{biblist}
+\end{verbatim}
+
+\section{More about the \cn{bib} command}\label{bib-command}
+
+As noted earlier, the syntax of the \cn{bib} command is very similar
+to that of a \BibTeX\ database record. For example, here's how the
+third bibliography item from section~\ref{ltb-files} might look in a
+\fn{.bib} file:
+\begin{verbatim}
+ @Book{SokalB1998,
+ title={Fashionable Nonsense: Postmodern Intellectuals' Abuse of
+ Science},
+ author={Alan Sokal and Jean Bricmont},
+ publisher={Picador USA},
+ address="New York",
+ year=1998
+ }
+\end{verbatim}
+However, there are a number of other significant differences between
+the two formats:
+
+\begin{description}
+
+\item[Order of type and key]
+
+In \BibTeX\ records, the entry type comes first and serves to mark the
+start of the field, and the cite key is separated from the data fields
+by a comma:
+\begin{verbatim}
+ @Book{SokalB1998,
+\end{verbatim}
+In \pkg{amsrefs}, every record begins with the \verb|\bib| command,
+followed first by the cite key and then by the entry type, and the
+data fields are preceded by an open brace, not a comma:
+\begin{verbatim}
+ \bib{SokalB1998}{book}{
+\end{verbatim}
+
+\item[Case sensitivity]
+
+In general, \BibTeX\ doesn't care how you capitalize field names. As
+far as it is concerned, ``title'', ``TITLE'' and ``tItLe'' are the
+same field name. Like \TeX\ in general, though, \pkg{amsrefs} is case
+sensitive. All of the standard field and bibliography entry-type
+names are spelled with all lowercase letters and must be typed exactly
+as shown in the documentation.
+
+\item[Mandatory braces]
+
+\BibTeX\ allows the braces around field values to be omitted in some
+contexts and allows double quotes to be substituted for braces. In
+\pkg{amsrefs}, every field value \emph{must} be surrounded by braces.
+
+\item[Repeated fields]
+
+\BibTeX\ does not allow fields to be repeated within a record;
+\pkg{amsrefs} allows certain fields (like \fld{author}) to be repeated
+as many times as needed.
+
+\item[Inverted names]
+
+\BibTeX\ allows names to be entered in a variety of formats, for
+example:
+\begin{verbatim}
+ author={John Doe}
+ author={Doe, John}
+ author={Doe, Jr., John}
+\end{verbatim}
+Although \BibTeX\ usually does a good job of parsing names into their
+components, sometimes it needs help, and experience shows that authors
+often have trouble telling when they need to provide such help. In
+order to avoid these problems, \pkg{amsrefs} takes the somewhat
+draconian step of requiring all names to be written in the form
+\emph{von Last, First, Jr.}, for example:
+\begin{verbatim}
+ author={Jones, John Paul}
+ author={van Beethoven, Ludwig}
+ author={Ford, Henry, Jr.}
+\end{verbatim}
+It is essential to follow this format for all names; otherwise
+\pkg{amsrefs} may produce profoundly incorrect results when it is
+asked to invert names (i.e., format the name as ``Doe, John'' instead
+of ``John Doe'', as some styles require), replace the first name by
+its initials (when the \opt{initials} option is used), or create a
+label based on the last name (the \opt{alphabetic} option).
+
+\end{description}
+
+In addition, there are differences in the rules that must be followed
+in marking the text inside fields:
+\begin{description}
+
+\item[Capitalization]
+
+Some \BibTeX\ styles will adjust the capitalization of titles to
+achieve a uniform style. This means that authors have to be careful
+to put extra braces around any characters that should not be upper- or
+lower-cased. For example, if you were to write
+\begin{verbatim}
+ title={An $O(n \log n)$ Sorting Network}
+\end{verbatim}
+many \BibTeX\ styles would change the title to
+\begin{quote}
+ An $o(n \log n)$ sorting network
+\end{quote}
+possibly resulting in great confusion on the part of the reader. To
+prevent this, you must surround the mathematical expression with an
+extra set of braces:
+\begin{verbatim}
+ title={An {$O(n \log n)$} Sorting Network}
+\end{verbatim}
+As with name formats, experience suggests that authors are often
+confused by \BibTeX's rules and fail to properly protect their titles.
+The good news is that \pkg{amsrefs} will not change the capitalization
+of any of your titles. The bad news is that this means you are solely
+responsible for editing the titles of your bibliography items to match
+the style your publisher requires.
+
+\item[Special characters]
+
+\BibTeX\ is also sometimes confused by text accents or other special
+characters such as \verb+\ae+ or \verb+\o+, which also have to be
+surrounded by braces for \BibTeX\ to process them correctly:
+\begin{verbatim}
+ author={Kurt G{\"o}del}
+ author={V. S{\o}rensen}
+\end{verbatim}
+\pkg{amsrefs} is more forgiving and will accept
+\begin{verbatim}
+ author={G\"odel, Kurt}
+ author={S\o rensen, V.}
+\end{verbatim}
+although it is probably still a good idea to surround \verb+\o+ with
+braces in the second example. We'll talk more about names in
+sections~\ref{names} and~\ref{attributes}.
+
+%% \item[ndash] Use of \cn{ndash} instead of \verb'--' for en-dashes is
+%% recommended (the \verb'--' notation, which is tied to
+%% idiosyncrasies of the Computer Modern \qq{\TeX{} text} font
+%% encoding, hinders document translation and the use of alternate
+%% fonts).
+
+\end{description}
+
+Finally, although \pkg{amsrefs} supports many of the same field and
+entry types that \BibTeX\ does, there are some differences, which we
+will explore in the next two sections.
+
+\subsection{Bibliography entry types}
+
+Compared to \BibTeX, \pkg{amsrefs} has a relatively small number of
+entry types. However, what it lacks in diversity it makes up for in
+versatility. Here are the supported entry types, along with some
+descriptive comments that are meant to suggest the variety of uses for
+which the type is appropriate.
+
+\begin{description}
+
+\item[article]
+
+A relatively short but self-contained item that is typically published
+as part of a larger collection, such as a journal, a conference
+proceedings, an edited collection published as a book, or even as part
+of a World Wide Web document.
+
+\item[book]
+
+A written work by one or more authors where the authors share credit
+for the work as a whole. For compatibility with \BibTeX, the
+following entry types are available as aliases for \btype{book}:
+\btype{collection}, \btype{proceedings}, \btype{manual},
+and \btype{unpublished}.
+
+\item[misc]
+
+Anything that doesn't fit into one of the other types.
+
+\item[report]
+
+A technical report, white paper, or the like. Similar to an
+\btype{article} but usually published and distributed by an
+organization such as a university or corporation whose primary
+business is usually not publishing. Also known as a
+\btype{techreport}.
+
+\item[thesis]
+
+Like \emph{report} but produced by the author for an educational
+institution to satisfy the requirements for a degree. Not (normally)
+produced by a commercial publisher for sale.
+
+\item[webpage]
+
+An online resource. It is limited to the following fields:
+\fld{accessdate},
+\fld{author},
+\fld{date},
+\fld{note},
+\fld{subtitle},
+\fld{title},
+\fld{url}.
+
+\end{description}
+
+\subsection{Field names for the \cn{bib} command}
+
+The \pkg{amsrefs} package distinguishes between three types of fields:
+\begin{enumerate}
+
+\item
+A \emph{simple} field can appear only once in each record. Some
+examples are \fld{title} and \fld{publisher}.
+
+\item
+A \emph{repeatable} field can appear as many times as necessary. As
+we saw above, \fld{author} is repeatable, as are \fld{editor} and
+\fld{translator}, but we'll see later that not all repeatable fields
+are names.
+
+\item
+Briefly, a \emph{compound} field is one that is made up of a
+collection of subfields, for example:\label{ex:translation}
+\begin{verbatim}
+ \bib{KostrikinS1965}{article}{
+ author={Kostrikin, A. I.},
+ author={\v{S}afarevi\v{c}, I. R.},
+ title={Cartan pseudogroups and Lie $p$-algebras},
+ journal={Dokl. Akad. Nauk SSSR},
+ volume={168},
+ date={1965},
+ pages={740--742},
+ translation={
+ journal={Soviet Math. Dokl.},
+ volume={6},
+ date={1965},
+ pages={715--718}
+ },
+ review={\MR{0199235}}
+ }
+\end{verbatim}
+Here the translation is specified with a compound field so it can have
+its own set of publication fields.
+
+\end{enumerate}
+
+\subsubsection{Simple fields}
+
+The meaning of many of these should be self-evident, so comments will
+be kept to a minimum.
+\begin{description}
+
+\item[accessdate]
+
+Used to specify the date on which a \btype{webpage} was viewed, as
+opposed to the date on which the resource was last modified, which
+would be put in the \fld{date} field.
+
+\item[address]
+
+Usually the address of the publisher or other issuing organization,
+but inside the \fld{conference} compound field (see
+page~\pageref{compound}) it refers to the address of the
+conference.
+
+\item[booktitle]
+
+Used in the \btype{article} type to specify the title of the book in
+which the article appeared. If anything other than a simple book
+title is required, the \fld{book} compound field should be used
+instead.
+
+\item[date]\label{date-format}
+
+Usually the date of publication, except inside the \fld{conference}
+field, where it is the date of the conference (see
+page~\pageref{compound}).
+
+This replaces \BibTeX's \fld{year} and \fld{month} fields. Its value
+should be written in ISO 8601 format, e.g., 1967-02-24. The day
+and/or month can be omitted, so all of the following are valid
+representations of February 24, 1967:
+\begin{verbatim}
+ date={1967-02-24}
+ date={1967-02}
+ date={1967}
+\end{verbatim}
+Using this format allows \pkg{amsrefs} maximum flexibility in
+formatting dates, for example, by allowing month names to be printed
+in full or abbreviated as necessary.
+
+For \qq{Winter}, \qq{Spring}, \qq{Summer}, \qq{Fall}, either use month
+numbers of 13, 14, 15, 16 (respectively) or just put in the text
+before the year:
+\begin{verbatim}
+ date={Summer 1987},
+\end{verbatim}
+For compatibility, \fld{year} is provided as an alias for \fld{date},
+but its use is discouraged.
+
+\item[edition]
+
+For books or reports. If the value of this field is a simple number,
+\cn{bib} will convert it to cardinal form and add \qq{ed.} (or
+alternative text if specified by the bibliography style). Otherwise
+it will be printed as~is.
+
+\item[eprint]
+
+Electronic preprint information such as for \url{www.arXiv.org}. See
+\url{http://xxx.lanl.gov/help/faq/references} for recommended form.
+
+\item[hyphenation]
+
+This corresponds to the Babel package notion of \qq{language}. The
+hyphenation language used for a given \cn{bib} entry is determined
+from various clues, which are checked in the following order:
+\begin{enumerate}
+
+\item
+The Babel language specified by the \fld{hyphenation} field.
+
+\item
+The Babel language specified by the \emph{first word} of the
+\fld{language} field (after lowercasing).
+
+\item
+The current Babel language that was in effect before the \cn{bib}
+command started.
+
+\item
+The current hyphenation patterns of the document, if there are no
+Babel language modules loaded.
+
+\end{enumerate}
+The \fld{hyphenation} field applies to an entire entry. To change the
+Babel language for a single field, see the discussion of the
+\fld{language} attribute on page~\pageref{attributes}.
+
+\nitem[journal]
+
+\item[label]
+
+When the \opt{alphabetic} or \opt{shortalphabetic} options are used,
+\pkg{amsrefs} will usually try to generate the label on its own. If
+necessary, you can override the automatically generated label by
+specifying a \fld{label} field.
+
+\item[language]
+
+Language of the work. The language name should be the printed form,
+not a Babel-style language name, since in principle this field could
+contain more complicated remarks such as \qq{Russian, with French
+abstract}. Cf.~\fld{hyphenation}.
+
+\item[note]
+
+Any additional information that does not fit into one of the other
+fields.
+
+\item[number]
+
+The issue number of the journal for an \btype{article} or the
+technical report number for a \btype{report}.
+
+\item[organization]
+
+The school, university, corporation, or other nonpublisher
+organization that issued the document.
+
+\nitem[pages]
+
+\nitem[part]
+
+\nitem[publisher]
+
+\nitem[series]
+
+%% Let's suppress this at least until we can think of a good
+%% example.
+%%
+%% \item[setup]
+%%
+%% This is a special field that can be used to give arbitrary commands to
+%% be executed at the beginning of the current \cn{bib} entry, after all
+%% the fields have been read. The idea is that one can alter the
+%% formatting of an individual entry through this field to handle
+%% special cases.
+
+\item[status]
+
+Typically used for notes such as \qq{to appear} or \qq{in preparation}
+or \qq{unpublished} with journal articles.
+
+\item[subtitle]
+
+Typically used with a multipart journal article to give a subtitle for
+each part, but it can also be used for books.
+
+\nitem[title]
+
+\item[type]
+
+The type of a thesis, e.g., ``Master's Thesis'' or ``Ph.D. Thesis''.
+
+\nitem[volume]
+
+\item[xref]
+
+This will be explained in section~\ref{xrefs}.
+
+\end{description}
+
+\subsubsection{Repeatable fields}
+
+\begin{description}
+
+\item[author, editor, translator]
+
+The authors, editors, and/or translators of the item. If there are
+other contributors that should be acknowledged, they should be listed
+in \fld{contribution} fields (see page~\pageref{contributors}).
+
+\item[isbn, issn]
+
+An International Standard Book or Serial Number. (These are not
+printed by the standard styles, but are reserved for future use.)
+
+\item[review]
+
+A review number or similar pointer to, for example, \emph{Mathematical
+Reviews} or \emph{Zentralblatt}. You must supply any special markup
+for the number; i.e., you should write
+\begin{verbatim}
+ review={\MR{2015463}}
+\end{verbatim}
+instead of
+\begin{verbatim}
+ review={2015463}
+\end{verbatim}
+
+\end{description}
+
+\subsubsection{Compound fields}\label{compound}
+
+These are the compound fields currently supported by \pkg{amsrefs}.
+
+\begin{description}
+
+\item[book]
+
+This is used for conference articles to make it easier to
+differentiate between an article and the book or proceedings that it
+appeared in. The \fld{book} field can contain any of the following
+subfields: \fld{title}, \fld{part}, \fld{subtitle}, \fld{edition},
+\fld{editor}, \fld{translator}, \fld{contribution}, \fld{series},
+\fld{volume}, \fld{publisher}, \fld{organization}, \fld{address},
+\fld{date}, \fld{note}.
+
+It is often used in conjunction with the \fld{conference} field.
+
+\item[conference]
+
+The \fld{conference} field can contain a \fld{title}, \fld{address},
+and \fld{date}.
+
+\begin{verbatim}
+ \bib{Burkholder1986a}{article}{
+ author={Burkholder, Donald L.},
+ title={Martingales and Fourier analysis in Banach spaces},
+ conference={
+ title={C.I.M.E. Lectures},
+ address={Varenna, Italy},
+ date={1985}
+ },
+ book={
+ series={Lecture Notes in Math.},
+ volume={1206},
+ publisher={Springer-Verlag},
+ address={Berlin and New York},
+ date={1986},
+ },
+ pages={61--108},
+ review={\MR{0864712}}
+ }
+\end{verbatim}
+
+\item[contribution]\label{contributors}
+
+This field can be repeated as many times as necessary to list any
+contributors other than authors, editors, or translators.
+\begin{verbatim}
+ contribution={
+ type={illustrations},
+ author={Gorey, Edward}
+ }
+\end{verbatim}
+which in the default style produces
+\begin{quote}
+ with illustrations by Edward Gorey
+\end{quote}
+Since contributions are potentially complicated, so is the
+\fld{contribution} field:
+\begin{itemize}
+
+\item
+Sometimes it is necessary to add additional material to the \fld{type}
+in order to produce intelligible text:
+\begin{verbatim}
+ contribution={
+ type={an appendix},
+ author={Doe, John}
+ }
+\end{verbatim}
+
+\item
+\pkg{amsrefs} tries very hard to format multiple contributions, each
+of which may have multiple authors, in an appropriate way. However,
+there might be cases where the default rules aren't flexible enough,
+in which case you can instead use the \fld{contribution} field as a
+simple field and format it exactly the way you want:
+\begin{verbatim}
+ contribution={some arbitrary text about contributions}
+\end{verbatim}
+This feature should only be used as a last resort, though.
+
+\end{itemize}
+
+\item[partial]
+
+This is used with the \btype{article} type for multipart articles.
+Like the \fld{contribution} field, it is repeatable. It can contain
+any of the following fields: \fld{part}, \fld{subtitle},
+\fld{contribution}, \fld{journal}, \fld{volume}, \fld{date},
+\fld{number}, \fld{pages}.
+\begin{verbatim}
+ \bib{Zho-fan1972}{article}{
+ author={Zho-fan, Z.},
+ title={Monomials},
+ partial={
+ part={I},
+ journal={Tot. Math.},
+ volume={19},
+ date={1972},
+ pages={335--350}
+ },
+ partial={
+ part={II},
+ journal={Tot. Math.},
+ volume={20},
+ date={1973},
+ pages={19--37}
+ }
+ }
+\end{verbatim}
+
+\item[reprint]
+
+This can be used inside an \btype{article} to indicate another place
+(usually a book) where the article can also be found. It can contain
+any field that the \btype{book} type can.
+\begin{verbatim}
+ \bib{Sokal96}{article}{
+ title={Trangressing the boundaries},
+ subtitle={Toward a transformative hermeneutics of quantum
+ gravity},
+ author={Sokal, Alan},
+ journal={Social Text},
+ volume={46/47},
+ date={1996},
+ pages={217--252},
+ reprint={
+ title={Fashionable Nonsense},
+ subtitle={Postmodern Intellectuals' Abuse of Science},
+ author={Sokal, Alan},
+ author={Bricmont, Jean},
+ publisher={Picador USA},
+ address={New York},
+ date={1998}
+ }
+ }
+\end{verbatim}
+
+\item[translation]
+
+This is the only compound field that can be used with any bibliography
+type. It can contain any field that its parent type can contain. We
+saw an example of this on page~\pageref{ex:translation}.
+
+\end{description}
+
+\subsection{What's in a name?}\label{names}
+
+We saw earlier that names must always be entered in the form ``von
+Last, First, Jr.''\ so that \pkg{amsrefs} can unambiguously determine
+which parts of the name correspond to the surname and which to the
+given name. In this section we will discuss some of the other
+subtleties that come into play with processing names.
+
+The good news is that the vast majority of the time you don't need to
+worry about this section. As long as your names contain only the
+following characters, you should be safe:
+\begin{itemize}
+
+\item
+the 26 ASCII letters, the apostrophe (') and \TeX's tie (\verb|~|) and
+grouping (\verb+{}+) characters,
+
+\item
+one of the following accent commands: \cn{\"} \cn{\'} \cn{\.}\ \cn{\=}
+\cn{\^} \cn{\`} \cn{\~} \cn{\b} \cn{\c} \cn{\d} \cn{\H} \cn{\k}
+\cn{\r} \cn{\t} \cn{\u} \cn{\v}, or
+
+\item
+one of the following special characters: \cn{AE} \cn{ae} \cn{DH}
+\cn{dh} \cn{DJ} \cn{dj} \cn{i} \cn{j} \cn{L} \cn{l} \cn{NG} \cn{ng}
+\cn{OE} \cn{oe} \cn{O} \cn{o} \cn{SS} \cn{ss} \cn{TH} \cn{th}.
+
+\end{itemize}
+If you are using the \pkg{mathscinet} package, any of the special
+characters and accents defined by it can also be used.\footnote{For
+pragmatic purposes, note that the difference between an ``accent'' and
+a ``special character'' is that all the macros identified as accents
+take a single argument, while the ones identified as special
+characters do not take an argument.}
+
+\subsubsection{Grouping multiple physical characters into a single
+ logical character}
+
+Sometimes it's necessary to tell \pkg{amsrefs} to treat two or more
+characters as a single ``logical'' character. For example, consider
+the following names:
+\begin{verbatim}
+ author={Gagarin, Yuri}
+ author={Katzenbach, Nicholas deBelleville}
+\end{verbatim}
+If the \opt{initials} option is in force, \pkg{amsrefs} will shorten
+those names to ``Y. Gagarin'' and ``N. d. Katzenbach''. These are
+both incorrect, the first because ``Yu'' represents the
+transliteration of a single Cyrillic character and the second because
+``deBelleville'' should be shortened to ``deB'', not just~``d''. The
+easiest way to force the correct interpretation is by adding braces,
+as follows:
+\begin{verbatim}
+ author={Gagarin, {Yu}ri}
+ author={Katzenbach, Nicholas {deB}elleville}
+\end{verbatim}
+which tells \pkg{amsrefs} that those characters should be kept
+together, producing the correct results.
+
+Incidentally, if you provide the names in already abbreviated form,
+i.e.,
+\begin{verbatim}
+ author={Gagarin, Yu.}
+ author={Katzenbach, N. deB.}
+\end{verbatim}
+it is not necessary to add the extra braces, since \pkg{amsrefs} will
+not further abbreviate any word that already ends in a period (but the
+extra braces also would do no harm).
+
+\subsubsection{Declaring new accents or special characters}
+
+In some cases it may also be necessary to add a special character or
+accent to the list given above. An accent command can be added to the
+list of acceptable name components by using the \cn{DeclareNameAccent}
+command. In fact, \pkg{amsrefs} contains a declaration like
+\begin{verbatim}
+ \DeclareNameAccent{\"}
+\end{verbatim}
+for each of the text accents listed above.
+
+Declaring a new text symbol is only slightly more complicated:
+\begin{verbatim}
+ \DeclareNameSymbol{\AE}{\ae}
+\end{verbatim}
+This says that \verb+\AE+ and \verb+\ae+ are both allowed as text
+symbols inside names and, furthermore, that \verb|\ae| is the
+lowercase version of~\verb|\AE|.
+
+\section{Package options}
+
+The \pkg{amsrefs} package has a plethora of options.
+
+\subsection{Citation labels}
+
+By default, the items in your bibliography are numbered, as in the
+\bst{plain} \BibTeX\ style. However, three other label styles are
+also supported via the following options:
+\begin{description}
+
+\item[alphabetic]
+
+This generates alphabetic labels similar to the \pkg{alpha} \BibTeX\
+style, consisting of the first letter(s) of each author name plus the
+year of publication.
+
+\item[shortalphabetic]
+
+This generates a shorter alphabetic label using only the first letter
+of each author name.
+
+\item[author-year]
+
+This switches to the popular author-year citation format, similar to
+that described in \emph{The Chicago Manual of Style}. See
+section~\ref{author-year} for more information on this option.
+
+\item[y2k]
+
+When using the \opt{alphabetic} option, normally only the last two
+digits of the year are used in the label. The \opt{y2k} instructs
+\pkg{amsrefs} to use the full year.
+
+\end{description}
+
+\begin{note}
+Since \pkg{amsrefs} leaves the order of the bibliography items up to
+the user, a common mistake when using non-numeric labels (especially
+\opt{shortalphabetic} labels) is to put the items in an order that is
+incompatible with the natural order of the labels. This can result in
+a sequence such as this:
+\begin{biblist}*{labels={shortalphabetic}}
+
+\bib{A}{article}{
+ title={\dots},
+ author={Doe, John},
+}
+
+\bib{C}{article}{
+ title={\dots},
+ author={Doe, John},
+ author={Smith, Jane},
+}
+
+\bib{B}{article}{
+ title={\dots},
+ author={Dunn, John},
+}
+\end{biblist}
+where \pkg{amsrefs} does not automatically replace the first and third
+labels by ``D1'' and ``D2'' as it would if they were consecutive.
+This is because the real error lies in attempting to force the labels
+into an unordered sequence. Readers are entitled to find reference
+``D2'' between references ``D1'' and~``DS'' in the bibliography just
+as they are entitled to find reference~[2] between references [1]
+and~[3].
+
+If \pkg{amsrefs} encounters a situation like this, it will issue a
+warning. There are three ways to resolve the problem:
+\begin{enumerate}
+
+\item
+Rearrange the items in an order that is compatible with the label
+style you have chosen.
+
+\item
+Choose a different label style that is compatible with the order you
+have chosen for the items.
+
+\item
+Use the \fld{label} field to override the automatically-generated
+label and leave your readers to their own devices.
+
+\end{enumerate}
+
+\end{note}
+
+\subsection{Citation sorting and compression}\label{sec:sorting}
+
+When numeric citation labels are being used and \pkg{amsrefs}
+encounters a list of multiple citations (for example,
+\verb|\cites{A,B}| or \verb|\citelist{\cite{A}\cite{B}}|), it will
+normally sort the citation labels and then compress ranges of three or
+more consecutive labels into a range of the form $n$--$m$. For
+example, the list [11, 9, 10, 1, 16, 12] would first be sorted into
+[1, 9, 10, 11, 12, 16] and then compressed into [1, 9--12, 16]. These
+options can be used to modify that behavior.
+
+\begin{description}
+
+\item[non-compressed-cites]
+
+Turn off range compression; citations will still be sorted. Range
+compression is also automatically turned off if \pkg{amsrefs} detects
+that the \pkg{hyperref} package has been loaded.\footnote{In order for
+ this to work correctly, the \pkg{hyperref} package must be loaded
+ \emph{after} the \pkg{amsrefs} package.}
+
+\item[non-sorted-cites]
+
+Turn off range sorting. This also turns off range compression as a
+side-effect.
+
+\end{description}
+
+\subsection{Abbreviations}
+
+These options emulate various aspects of the behavior of the \BibTeX\
+\bst{abbrv} style, but unlike \bst{abbrv}, they can be used with any
+of the citation label styles described above.
+
+\begin{description}
+
+\item[abbrev]
+
+This is equivalent to requesting all four of the following options.
+
+\item[initials]
+
+Replace the given names of all authors, editors, and translators with
+their initials. See section~\ref{names} for further discussion.
+
+\item[short-journals]
+
+Print short form instead of full form for journal names. This works
+only with abbreviations defined with the \cn{DefineJournal} command
+(see section~\ref{abbreviations}).
+
+\item[short-months]
+
+Print short version of month names (e.g., Jan.\ instead of January).
+This works only when you write all dates in ISO~8601 format (see
+page~\pageref{date-format}).
+
+\item[short-publishers]
+
+Print short form instead of full form for publisher names. This works
+only with abbreviations defined with the \cn{DefinePublisher} command
+(see section~\ref{abbreviations}).
+
+\end{description}
+
+\subsection{Miscellaneous options}
+
+\begin{description}
+
+\item[backrefs]
+
+This option causes ``back-references'' to be printed at the end of
+each bibliography entry to show what page it was cited on. This
+option will work only if the \pkg{hyperref} package is installed.
+
+\item[bibtex-style]
+
+By default, \pkg{amsrefs} formats references using the AMS house
+style. The \opt{bibtex-style} option instructs it to use a format that is
+very similar to the one implemented by the standard \BibTeX\ styles
+(\bst{plain}, \bst{alpha}, \bst{abbrv}, and \bst{unsrt}).
+
+\item[citation-order]
+
+This option applies only when using \pkg{amsrefs} in conjunction with
+\BibTeX. Consequently, changing this option will have no effect until
+after the next \bibtex/ run.
+
+The \opt{citation-order} option corresponds to the standard \BibTeX\
+style \bst{unsrt}, where items are printed in the reference list in
+the order in which they are cited in the document.
+
+\item[lite]
+
+Suppress the loading of the following packages, which \pkg{amsrefs}
+will normally automatically load:
+\begin{description}
+
+\item[\pkg{mathscinet}]
+
+Define a number of special characters and accents that are sometimes
+encountered when downloading data from MathSciNet.
+
+\item[\pkg{txtcmds}]
+
+Provide shorthand commands for a number of characters that are usually
+specified via ligatures (e.g., \verb|--| for an en-dash or \verb|?`|
+for ``?`''. Using these ligatures can cause problems if you're using
+fonts other than the Computer Modern Roman family or if you want to
+make it easy to convert your document to, say, HTML\@. \LaTeX\ does
+provide macros for these characters, but their names tend to be rather
+unwieldy (e.g., \cn{textendash} and \cn{textquestiondown}), so
+\pkg{txtcmds} provides shorter names (\cn{ndash} and \cn{qd} in this
+case).
+
+\end{description}
+
+\item[msc-links]
+
+Redefine the \cn{MR} command to create hypertext links to the
+MathSciNet database. This option will work only if the \pkg{hyperref}
+package is installed.
+
+\item[nobysame]
+
+If two or more consecutive bibliography items have the same authors,
+\pkg{amsrefs} will normally replace the author names in the second and
+succeeding entries by a horizontal rule (\hbox to3em{\hrulefill}).
+This option disables this feature, causing the full author names to
+always be printed.
+
+\end{description}
+
+\section{Citing entries: \cn{cite} and friends}
+
+\LaTeX's standard \cn{cite} command has two major shortcomings:
+\begin{enumerate}
+
+\item
+It takes an arbitrary number of arguments, so you can write, for
+example, \cnm{cite}{xx,yy} to get [13, 15]. But this feature does not
+interact well with the optional argument that's used to give a
+targeted citation: \cnom{cite}[Theorem 4.9]{xx} will give you [13,
+Theorem 4.9], but how do you request [13, Theorem 4.9; 15] or [13; 15,
+Theorem 4.9]?
+
+\item
+The optional argument uses the standard \LaTeX\ syntax, which has been
+shown to be errorprone. For example, a common user error is to write
+something like
+\begin{verbatim}
+ \begin{thm}[\cite[Theorem 4.9]{xyz}]
+\end{verbatim}
+(which results in a syntax error) instead of
+\begin{verbatim}
+ \begin{thm}[{\cite[Theorem 4.9]{xyz}}]
+\end{verbatim}
+
+\end{enumerate}
+
+The \pkg{amsrefs} package addresses both of these problems by
+providing separate commands for single and multiple citations and
+implementing a new syntax for optional arguments.
+
+\begin{description}
+
+\item[\cn{cite}]
+
+For backwards compatibility, the old syntax is still supported; so,
+for example, \cnm{cite}{a,b,c} and \verb|\cite[xxx]{...}| work the
+same way they always have. However, for consistency we recommend that
+you use \cn{cite} only for single cites and use \cn{citelist} (or
+\cn{cites}) for multiple citations.
+
+In addition, the square bracket notation \cnom{cite}[...]{...} is also
+deprecated, because a superior alternative is provided:
+\begin{verbatim}
+ \cite{xyz}*{Theorem 4.9}
+\end{verbatim}
+Note that this does not suffer from the syntax problems noted above,
+since
+\begin{verbatim}
+ \begin{thm}[\cite{xyz}*{Theorem 4.9}]
+\end{verbatim}
+does not have the same problems that
+\begin{verbatim}
+ \begin{thm}[\cite[Theorem 4.9]{xyz}]
+\end{verbatim}
+does.
+
+\item[\cn{citelist}]
+
+This is used to group a number of individual \cn{cite} commands into a
+single citation. Among other things, this makes it possible to add an
+optional argument to any of the \cn{cite} commands unambiguously:
+\begin{verbatim}
+ \citelist{\cite{xx} \cite{yy}*{Theorem 4.9} \cite{zz}}
+\end{verbatim}
+\textbf{Note that there is no punctuation or other text between the
+\cn{cite} commands}. Any necessary commas or other punctuation will
+be supplied automatically. Any attempts to supply it by hand will
+backfire.
+
+\item[\cn{cites}]
+
+This is a variant of \cn{citelist}, provided for convenience:
+\begin{verbatim}
+ \cites{aa,bb,cc}
+\end{verbatim}
+is equivalent to
+\begin{verbatim}
+ \citelist{\cite{aa}\cite{bb}\cite{cc}}
+\end{verbatim}
+Note that \cn{cites} does \emph{not} take an optional arguments.
+
+\item[\cn{nocite}]
+
+This continues to work the same way that it does in standard \LaTeX\
+when used with \BibTeX, but see page~\pageref{nocite} for limitations
+when it is used with \cn{bibselect} and \fn{.ltb} files.
+
+\end{description}
+
+When the \opt{author-year} option is used, there are some additional
+citation commands available, as we shall see in the next section.
+
+\subsection{Author-year citation schemes}\label{author-year}
+
+When an author-year citation scheme is used, some further
+complications arise, since different forms of citations are used
+depending on the grammatical context.
+
+The first form is used when the citation serves as a parenthetical
+annotation: i.e., it could be omitted without harming the grammatical
+structure of the sentence containing it. For example:
+\begin{quote}
+The question first arose in systems theory (Rupp and Young, 1977).
+\end{quote}
+
+The second form is like the first but is used when the author name is
+already present as a natural part of the sentence and only the year
+should be parenthesized:
+\begin{quote}
+Rupp and Young (1977) have investigated \dots
+\end{quote}
+Note that as in the first example, the material in parentheses can be
+deleted without changing the meaning of the sentence.
+
+A third form is preferred by some authors when the citation serves as
+a direct object or other nounlike role within its sentence. Consider
+the following example:
+\begin{quote}
+\dots\ for further details, see Rupp and Young (1977).
+\end{quote}
+Although this may appear at first glance identical with the second
+example, it is subtly different, since removing the parenthesized
+material results in
+\begin{quote}
+\dots\ for further details, see Rupp and Young.
+\end{quote}
+which does affect the meaning of the sentence.
+
+Another way of seeing the difference between the second and third
+examples is to consider how those sentences might read if numeric
+labels were being used:
+\begin{quote}
+Rupp and Young [14] have investigated \dots\par
+\dots\ for further details, see [14].
+\end{quote}
+Admittedly, ``see~[14]'' is poor style, but it does highlight the fact
+that in the third example ``Rupp and Young'' is part of the text we
+expect our cite command to generate, while in the second example it is
+not.
+
+%%** ``delegate''???
+
+We delegate \cn{cite} to produce the primary parenthetical form
+``(Author, Year)'' and provide \cn{ycite} (\qq{year cite}) and
+\cn{ocite} (\qq{object cite}) as the other forms. Our three examples
+would thus be coded as follows:
+\begin{verbatim}
+ The question first arose in systems theory \cite{...}.
+
+ Rupp and Young \ycite{...} have investigated
+
+ for further details, see \ocite{...}.
+\end{verbatim}
+For symmetry, a \cn{citeauthor} command, which produces the list of
+authors without the year, is also provided, and plural forms
+\cn{ycites} and \cn{ocites} are provided to mirror \cn{cites}. There
+is also a \cn{citeyear} command that is identical to \cn{ycite} except
+that it suppresses the surrounding parentheses.
+
+Finally, in some author-year styles, if there are three or more
+authors, \cn{cite} and \cn{ocite} will produce abbreviated author
+lists (``Larry et al.''\ instead of ``Larry, Moe, and Curly''). The
+``full'' variants \cn{fullcite} and \cn{fullocite} will always print
+the full list.
+
+\section{Advanced features}
+
+\subsection{Field attributes}\label{attributes}
+
+Sometimes it's necessary to associate some data with a field that is
+not actually part of the data of the field. For example, consider
+Chinese names, which are traditionally written with the family name
+first:
+\begin{quote}
+Li Lian Jie\qquad\emph{not} Li, Lian Jie \emph{or} Lian Jie Li
+\end{quote}
+Unfortunately, if you write
+\begin{verbatim}
+ author={Li, Lian Jie}
+\end{verbatim}
+you will get one of the incorrect forms above. On the other hand, if
+you try to force the correct order by writing
+\begin{verbatim}
+ author={Li Lian Jie}
+\end{verbatim}
+\pkg{amsrefs} will be unable to process the name correctly if, for
+example, the \opt{initials} or \opt{alphabetic} options are requested.
+
+To solve this problem, you can set the \attr{inverted} attribute for a
+given name as follows:
+\begin{verbatim}
+ author={Li, Lian Jie}*{inverted={yes}}
+\end{verbatim}
+As you can see, attributes are given as key-value pairs following the
+the field value and separated by an asterisk. The \attr{inverted}
+attribute can be set on any name.
+
+At present the only other attribute that is supported is
+\attr{language}, which can be set on any field. It's value should be
+a valid Babel language name and will apply only to that field. This
+can be especially useful if you need to change the hyphenation
+patterns or font encoding for a single field:
+\begin{verbatim}
+ \bib{Denecke1982}{article}{
+ author={Denecke, K.},
+ title={Pr\"aprimale Algebren, die arithmetische Variet\"aten
+ erzeugen}*{language={german}},
+ booktitle={Universal Algebra and Applications},
+ series={Banach Center Publ.},
+ volume={9},
+ publisher={PWN},
+ address={Warsaw},
+ date={1982},
+ pages={391--398}
+ }
+\end{verbatim}
+
+\subsection{Cross-references: \cn{bib*} and the \fld{xref} field}
+\label{xrefs}
+
+Distinct bibliography items often share a great deal of common data,
+especially when two or more papers from a single conference are being
+cited:
+\begin{verbatim}
+ \bib{StockmeyerM73}{article}{
+ title={Word Problems Requiring Exponential Time},
+ subtitle={Preliminary Report},
+ author={Stockmeyer, L. J.},
+ author={Meyer, A. R.},
+ pages={1--9},
+ booktitle={Conference Record of Fifth Annual ACM Symposium on
+ Theory of Computing},
+ date={1973},
+ address={Austin, Texas},
+ publisher={ACM}
+ }
+
+ \bib{Kung73}{article}{
+ title={The Computational Complexity of Algebraic Numbers},
+ author={Kung, H. T.},
+ pages={152--159},
+ booktitle={Conference Record of Fifth Annual ACM Symposium on
+ Theory of Computing},
+ date={1973},
+ address={Austin, Texas},
+ publisher={ACM}
+ }
+\end{verbatim}
+To cut down on the amount of text that has to be repeated, you can put
+the common information in a separate entry and then include it via the
+\fld{xref} field, as follows:
+\begin{verbatim}
+ \bib*{STOC5}{book}{
+ title={Conference Record of Fifth Annual ACM Symposium on
+ Theory of Computing},
+ date={1973},
+ address={Austin, Texas},
+ publisher={ACM}
+ }
+
+ \bib{StockmeyerM73}{article}{
+ title={Word Problems Requiring Exponential Time},
+ subtitle={Preliminary Report},
+ author={Stockmeyer, L. J.},
+ author={Meyer, A. R.},
+ pages={1--9},
+ xref={STOC5}
+ }
+
+ \bib{Kung73}{article}{
+ title={The Computational Complexity of Algebraic Numbers},
+ author={Kung, H. T.},
+ pages={152--159},
+ xref={STOC5}
+ }
+\end{verbatim}
+There are a number of things to take note of:
+\begin{enumerate}
+
+\item
+The \texttt{STOC5} entry uses the $*$-variant of the \cn{bib} command.
+The $*$ indicates that this entry is for use in cross-references. It
+cannot be \cn{cite}d independently and will never contribute an item
+to a \env{biblist}. If you do want the conference proceedings to
+appear as a separate item, the easiest way is to create a separate
+\cn{bib} item as follows:
+\begin{verbatim}
+ \bib{STOC5-citable}{book}{
+ xref={STOC5}
+ }
+\end{verbatim}
+
+\item
+All \cn{bib*} records must occur \emph{before} the entry that
+references them.
+
+\item
+Within a \cn{bib*} entry, \emph{all} fields should be treated as
+moving arguments (see section~C.1.3 of the \LaTeX\ manual), so any
+fragile commands should be preceded by \cn{protect}.
+
+\item
+Even though the \texttt{STOC5} record used the \fld{title} field, its
+title showed up as a \fld{booktitle} in the other records. This is
+the only case where a field is renamed when copied from the \cn{bib*}
+record.
+
+\end{enumerate}
+
+\subsection[Compound fields revisited]{Compound fields revisited:
+ compound fields\\ as cross-references}
+
+Earlier we saw how to use compound fields by embedding a set of
+key-value pairs. However, with the exception of the \fld{contribution}
+field, all compound fields can also function as cross-reference
+fields. For example, our example from page~\pageref{ex:translation}
+could equally well have been coded as
+\begin{verbatim}
+ \bib*{KostrikinS1965T}{article}{
+ journal={Soviet Math. Dokl.},
+ volume={6},
+ date={1965},
+ pages={715--718}
+ }
+
+ \bib{KostrikinS1965B}{article}{
+ author={Kostrikin, A. I.},
+ author={\v{S}afarevi\v{c}, I. R.},
+ title={Cartan pseudogroups and Lie $p$-algebras},
+ journal={Dokl. Akad. Nauk SSSR},
+ volume={168},
+ date={1965},
+ pages={740--742},
+ translation={KostrikinS1965T},
+ review={\MR{0199235}}
+ }
+\end{verbatim}
+Whether this is an improvement or not is left as an exercise for the
+reader.
+
+\subsection[Abbreviations: \cn{DefineName} et al.]{Abbreviations:
+ \cn{DefineName}, \cn{DefineJournal},\\ and \cn{DefinePublisher}}
+\label{abbreviations}
+
+The \fld{xref} mechanism is fine when there are several fields that
+you want to group together and refer to as a unit, but what if you
+want a handy abbreviation for a single field, such as an individual
+author name, journal, or publisher? These are also provided.
+After writing
+\begin{verbatim}
+ \DefineName{dmj}{Jones, David M.}
+
+ \DefinePublisher{ams}{AMS}{American Mathematical Society}{Providence}
+
+ \DefineJournal{jams}{0894-0347}
+ {J. Amer. Math. Soc.}
+ {Journal of the American Mathematical Society}
+\end{verbatim}
+you can use these abbrevations as follows:
+\begin{verbatim}
+ author={dmj} (or editor={dmj} or translator={dmj})
+
+ journal={jams}
+
+ publisher={ams}
+\end{verbatim}
+
+The second argument of \cn{DefinePublisher} is the abbreviated form of
+the publisher's name, the third argument is the full name, and the
+fourth will be used as the \fld{address}. If the
+\opt{short-publishers} option is requested, then the abbreviation will
+be used; otherwise the full name will be used.
+
+Similarly, the third argument of \cn{DefineJournal} will be used if
+the \opt{short-journals} option is requested; otherwise the fourth
+argument will be used. (The second argument is the ISSN of the
+journal, which is not currently used, but is included for future use.)
+
+\subsection{Line breaks in the bibliography}
+
+Suppose you need to recommend to \LaTeX\ that it break a line in a
+particular place. Suggesting a line break in the middle of a field
+presents no difficulties: just edit your final \fn{.bbl} file and
+insert a \cn{linebreak} command:
+\begin{verbatim}
+ subtitle={Toward a transformative hermeneutics\linebreak[3] of
+ quantum gravity},
+\end{verbatim}
+But what if you need to force a line break \emph{between} two fields?
+At first blush you might fear that
+\begin{verbatim}
+ subtitle={...hermeneutics of quantum gravity\linebreak[3]},
+\end{verbatim}
+will cause a line break before the comma that \pkg{amsrefs} normally
+inserts after the title:
+\begin{quote}
+\hfill\dots \emph{hermeneutics of quantum gravity}\linebreak[3], Social
+Text\dots
+\end{quote}
+Have no fear; \pkg{amsrefs} will detect this and automatically move
+the comma in front of the line break, as desired:
+\begin{quote}
+\hfill\dots \emph{hermeneutics of quantum gravity},\linebreak[3] Social
+Text\dots
+\end{quote}
+
+\subsection{Defining custom entry types or styles}
+
+See the documentation of \cn{BibSpec} and related commands in ``The
+\pkg{amsrefs} package'' (\fn{amsrefs.pdf}).
+
+\end{document}