Debian Codegraph @

texmf-dist/source/latex/amsrefs/amsrdoc.tex

raw
1 %% filename: amsrdoc.tex
2 %% version: 1.04
3 %% date: 2013/01/16
4 %%
5 %% American Mathematical Society
6 %% Technical Support
7 %% Publications Technical Group
8 %% 201 Charles Street
9 %% Providence, RI 02904
10 %% USA
11 %% tel: (401) 455-4080
12 %% (800) 321-4267 (USA and Canada only)
13 %% fax: (401) 331-3842
14 %% email: [email protected]
15 %%
16 %% Copyright 2004, 2006-2008, 2010, 2013 American Mathematical Society.
17 %%
18 %% This work may be distributed and/or modified under the
19 %% conditions of the LaTeX Project Public License, either version 1.3c
20 %% of this license or (at your option) any later version.
21 %% The latest version of this license is in
22 %% http://www.latex-project.org/lppl.txt
23 %% and version 1.3c or later is part of all distributions of LaTeX
24 %% version 2005/12/01 or later.
25 %%
26 %% This work has the LPPL maintenance status `maintained'.
27 %%
28 %% The Current Maintainer of this work is the American Mathematical
29 %% Society.
30 %%
31 %% ====================================================================
32
33 \documentclass[oneside]{amsdtx}
34
35 \hyphenation{herme-neutics}
36
37 \usepackage{amsrefs}
38 \usepackage{amsthm}
39
40 \renewcommand*\descriptionlabel[1]{\hspace\labelsep
41 \normalfont\bfseries #1:}
42
43 \newcommand{\nshline}{\hline\omit\\}
44
45 \makeatletter
46
47 \newtheoremstyle{note}{3pt}{3pt}{}{}{\bfseries}{:}{.5em}{}
48
49 \theoremstyle{note}
50 \newtheorem*{note}{Note}
51
52 \def\nitem[#1]{\item[#1\@gobble]}
53
54 \DeclareRobustCommand{\fld}{\category@index{field}}
55 \DeclareRobustCommand{\btype}{\category@index{entry type}}
56
57 \DeclareRobustCommand{\attr}{\category@index{attribute}}
58
59 \makeatother
60
61 \newcommand{\rpack}[1]{\pkg{amsrefs} package}
62
63 \providecommand{\cnbreak}{\penalty999\hskip0pt\relax}
64 \providecommand{\cnm}[2]{\cn{#1}\cnbreak\embrace{#2}}
65 \providecommand{\cnom}[1]{\cn{#1}\cnbreak\ommitude}
66 \providecommand{\ommitude}[2][]{{\ntt[#1]}\cnbreak\embrace{#2}}
67 \providecommand{\cnmsm}[4]{%
68 \cn{#1}\cnbreak\embrace{#2}\cnbreak *\embrace{#4}}
69
70 \DeclareTextSymbol{\lbracechar}{OT1}{123}
71 \DeclareTextSymbolDefault{\lbracechar}{OT1}
72 \DeclareTextSymbol{\rbracechar}{OT1}{125}
73 \DeclareTextSymbolDefault{\rbracechar}{OT1}
74
75 \providecommand{\embrace}[1]{%
76 \begingroup \ntt\lbracechar#1\rbracechar\endgroup}
77
78 \title{User's Guide to the \pkg{amsrefs} Package}
79 \author{David M. Jones\\American Mathematical Society}
80 \date{January 16, 2013}
81
82 \begin{document}
83
84 \maketitle
85
86 \tableofcontents
87
88 \section{Introduction}
89
90 \pkg{amsrefs} is a \LaTeX\ package for preparing bibliography or
91 reference lists. It attempts to provide many of the convenient
92 features that \LaTeX\ and \BibTeX\ users have come to expect without
93 imposing all of the overhead that \BibTeX\ entails. In particular, it
94 has been carefully designed to encourage the preservation of
95 structured markup of the bibliography throughout the entire lifetime
96 of a document from rough draft to final archival version. As we shall
97 see, it does this by replacing \LaTeX's unstructured \fn{.bbl} file
98 format by a new, fully structured format. The package is compatible
99 with the \pkg{showkeys}, \pkg{hyperref},\footnote{Note that unlike
100 most packages, which must be loaded \emph{before} \pkg{hyperref},
101 the \pkg{amsrefs} package must be loaded \emph{after} \pkg{hyperref}
102 in order to work properly.} and \pkg{backrefs} packages and
103 implements the functionality of the popular \pkg{cite} package.
104 Interoperability with \BibTeX\ is supported via a special bibliography
105 style file, but \pkg{amsrefs} can be used without \BibTeX.
106
107 \section{Using the \pkg{amsrefs} package}
108
109 There are three ways of using the \rpack/:
110 \begin{enumerate}
111
112 \item
113 Enter bibliography items directly in your \latex/ document using the
114 \env{biblist} environment and the \cn{bib} command.
115
116 \item
117 Import items from an external \fn{.ltb} file.
118
119 \item
120 Import items from a \fn{.bib} file using \bibtex/ and the special
121 bibliography styles distributed with the \pkg{amsrefs} package.
122
123 \end{enumerate}
124
125 \subsection{Direct entry of bibliography items}\label{direct-entry}
126
127 The most basic way to use \pkg{amsrefs} is to enter the bibliography
128 items directly in your \LaTeX\ document. For example, consider the
129 following very short document:
130 \begin{quote}
131 Alan Sokal~[2] recommends Bourbaki's text~[1]
132 for a gentle introduction to set theory.
133
134 \begin{bibsection}
135 \begin{biblist}
136
137 \bib{Bourbaki70}{book}{
138 title={Th\'eorie des ensembles},
139 author={Bourbaki, Nicolas},
140 date={1970},
141 publisher={Hermann},
142 address={Paris}
143 }
144
145 \bib{Sokal96}{article}{
146 title={Trangressing the boundaries},
147 subtitle={Toward a transformative hermeneutics of quantum gravity},
148 author={Sokal, Alan},
149 journal={Social Text},
150 volume={46/47},
151 date={1996},
152 pages={217--252}
153 }
154
155 \end{biblist}
156 \end{bibsection}
157 \end{quote}
158 Using \pkg{amsrefs}, this document would be coded as follows:
159 \begin{verbatim}
160 \documentclass{article}
161
162 \usepackage{amsrefs}
163
164 \begin{document}
165
166 Alan Sokal~\cite{Sokal96} recommends Bourbaki's
167 text~\cite{Bourbaki70} for a gentle introduction to set theory.
168
169 \begin{bibdiv}
170 \begin{biblist}
171
172 \bib{Bourbaki70}{book}{
173 title={Th\'eorie des ensembles},
174 author={Bourbaki, Nicolas},
175 date={1970},
176 publisher={Hermann},
177 address={Paris}
178 }
179
180 \bib{Sokal96}{article}{
181 title={Trangressing the boundaries},
182 subtitle={Toward a transformative hermeneutics of quantum gravity},
183 author={Sokal, Alan},
184 journal={Social Text},
185 volume={46/47},
186 date={1996},
187 pages={217--252}
188 }
189
190 \end{biblist}
191 \end{bibdiv}
192
193 \end{document}
194 \end{verbatim}
195 Compared to the standard \LaTeX\ markup for bibliographies, there are
196 two main differences:
197 \begin{itemize}
198
199 \item
200 The functions of the \env{thebibliography} environment are split
201 between two new environments: \env{bibdiv}, which produces the chapter
202 or section heading for the bibliography, and \env{biblist}, which
203 contains the reference list per se. These environments will be
204 covered in more detail in sections \ref{biblist} and~\ref{bibdiv}.
205
206 \item
207 The \cn{bibitem} command is replaced by the \cn{bib} command, which is
208 very similar to a \BibTeX\ database entry. However, as we shall see
209 in section~\ref{bib-command}, there are some significant differences.
210
211 \end{itemize}
212
213 \subsection{Using an \fn{.ltb} database file}\label{ltb-files}
214
215 The second way of using \pkg{amsrefs} is to keep your \cn{bib}
216 commands in a separate database file and have \pkg{amsrefs} import the
217 ones that are needed. For example, suppose you have a file
218 \fn{nonsense.ltb} with the following contents:
219 \begin{verbatim}
220 \documentclass{article}
221
222 \usepackage{amsrefs}
223
224 \begin{document}
225
226 \begin{bibdiv}
227
228 \begin{biblist}
229
230 \bib{Bourbaki70}{book}{
231 title={Th\'eorie des ensembles},
232 author={Bourbaki, Nicolas},
233 date={1970},
234 publisher={Hermann},
235 address={Paris}
236 }
237
238 \bib{Sokal96}{article}{
239 title={Trangressing the boundaries},
240 subtitle={Toward a transformative hermeneutics of quantum gravity},
241 author={Sokal, Alan},
242 journal={Social Text},
243 volume={46/47},
244 date={1996},
245 pages={217--252}
246 }
247
248 \bib{SokalB1998}{book}{
249 title={Fashionable Nonsense},
250 subtitle={Postmodern Intellectuals' Abuse of Science},
251 author={Sokal, Alan},
252 author={Bricmont, Jean},
253 publisher={Picador USA},
254 address={New York},
255 date={1998}
256 }
257
258 \end{biblist}
259
260 \end{bibdiv}
261
262 \end{document}
263 \end{verbatim}
264 Before seeing how this affects our sample document, take note of a
265 couple of aspects of the format of \fn{nonsense.ltb}:
266 \begin{enumerate}
267
268 \item
269 We have chosen to format \fn{nonsense.ltb} as a complete \LaTeX\
270 document. This is so we can produce a formatted listing of our whole
271 database by running \fn{nonsense.ltb} through \LaTeX. However, this
272 is not necessary; when \pkg{amsrefs} treats \fn{nonsense.ltb} as a
273 database file, it ignores everything except for the \cn{bib} commands.
274
275 \item
276 Each \cn{bib} command in the \fn{.ltb} file \emph{must} begin on a new
277 line, and the first two arguments and the open brace of the third
278 argument must be on that same line. Failure to follow this format may
279 result in \pkg{amsrefs} getting terribly confused and aborting the
280 processing of your document.
281
282 \end{enumerate}
283
284 With that out of the way, let's look at how this affects our main
285 file, which we'll call \fn{sample.tex}:
286 \begin{verbatim}
287 \documentclass{article}
288
289 \usepackage{amsrefs}
290
291 \begin{document}
292
293 Alan Sokal~\cite{Sokal96} recommends Bourbaki's
294 text~\cite{Bourbaki70} for a gentle introduction to set theory.
295
296 \begin{bibdiv}
297 \begin{biblist}
298
299 \bibselect{nonsense}
300
301 \end{biblist}
302 \end{bibdiv}
303
304 \end{document}
305 \end{verbatim}
306 When you run this document through \LaTeX, \pkg{amsrefs} will create a
307 file \fn{sample.bbl} that contains all the relevant \cn{bib} entries
308 from \fn{nonsense.ltb}. This is very similar to using \BibTeX, but
309 with a few noteworthy differences:
310 \begin{itemize}
311
312 \item
313 Because all processing is being handled by \latex/, the contents of
314 the bibliography can be printed on the first pass; citation labels,
315 consequently, are resolved on the second pass.
316
317 \item
318 Unlike \BibTeX, which adds the \env{thebibliography} environment
319 automatically, \pkg{amsrefs} requires you to supply the \env{bibdiv}
320 and \env{biblist} environments yourself. As we shall see later, this
321 results in greater flexibility in the formatting of bibliographies.
322
323 \item
324 There is no need for a \cn{bibliographystyle} command.
325
326 \item
327 No sorting of the bibliography items is done. The entries will appear
328 in your document in the same order that they appeared in the database
329 files.
330
331 \end{itemize}
332 Like the \cn{bibliography} command, \cn{bibselect} can be given
333 multiple files to process:
334 \begin{verbatim}
335 \bibselect{bib1,bib2}
336 \end{verbatim}
337 and can be used multiple times in your document:
338 \begin{verbatim}
339 \bibselect{bib1}
340 \bibselect{bib2}
341 \end{verbatim}
342 Normally each \cn{bibselect} command will only import entries that
343 have been explicitly cited in your document. If you want to import
344 all entries from a given file, you can use the $*$-variant:
345 \begin{verbatim}
346 \bibselect*{sample}
347 \end{verbatim}
348 This is similar to the use of \label{nocite}\verb|\nocite{*}| but
349 allows finer control. You can still use \verb|\nocite{*}|, but with
350 one restriction: it only applies to \cn{bibselect} commands that occur
351 after it in the document.
352
353 The \cn{bibselect} command regenerates the \fn{.bbl} file each time
354 the document is \LaTeX ed (unless, of course, the \cn{nofiles} switch
355 is used). Once your bibliography is completed, you might wish to
356 replace the \cn{bibselect} command by the contents of the \fn{.bbl}
357 file to prevent any further modifications. This is particularly
358 important if you need to edit the contents of the \fn{.bbl} file in
359 any way (say, to re-order the items or adjust the capitalization of
360 titles to match the style of the journal you are publishing in or to
361 put in explicit line or page breaks). This will make your document
362 more self-contained, which will make it easier to reuse and archive.
363
364 \subsection{Using the \rpack/ with \bibtex/}
365
366 Finally, you can use \pkg{amsrefs} in conjunction with \BibTeX:
367 \begin{verbatim}
368 \documentclass{article}
369
370 \usepackage{amsrefs}
371
372 \begin{document}
373
374 Alan Sokal~\cite{Sokal96} recommends Bourbaki's
375 text~\cite{Bourbaki70} for a gentle introduction to set theory.
376
377 \bibliography{nonsense}
378
379 \end{document}
380 \end{verbatim}
381 Note two things:
382 \begin{itemize}
383
384 \item
385 Unlike when you use \cn{bibselect} to import entries from a \fn{.ltb},
386 in this case the \fn{.bbl} \emph{will} contain the \env{bibdiv} and
387 \env{biblist} environments.
388
389 \item
390 There is no need for a \cn{bibliographystyle} command; \pkg{amsrefs}
391 will automatically invoke the correct style. In fact, any
392 \cn{bibliographystyle} command you put in your document will be
393 ignored.
394
395 \end{itemize}
396
397 The main advantages of using \BibTeX\ are:
398 \begin{itemize}
399
400 \item
401 you can take advantage of \BibTeX's ability to sort your items for
402 you, and
403
404 \item
405 you can take advantage of the large number of \BibTeX\ database files
406 already in existence.
407
408 \end{itemize}
409
410 As when using an \fn{.ltb} file, you may wish to replace the
411 \cn{bibliography} command by the contents of the \fn{.bbl} file when
412 you have finished compiling your bibliography.
413
414 \section{The \protect\env{biblist} and \env{biblist*} environments}
415 \label{biblist}
416
417 As alluded to earlier, \env{thebibliography} performs two distinct
418 functions: first, it produces the section heading for the bibliography
419 and second, it provides the list environment for formatting the
420 bibliography entries.
421
422 In \pkg{amsrefs} these functions are performed by two distinct
423 environments, \env{bibdiv} and \env{biblist}. As its name suggests,
424 the \env{biblist} environment provides the second function. So, if
425 you wanted a list of references with no heading at all, you could just
426 leave out the \env{bibdiv} environment.
427
428 The \env{biblist} environment has an optional argument to allow
429 changing the list parameters. For example, suppose you know that your
430 bibliography has between 100 and 999 entries and you want to ensure
431 that there is enough space allocated for the labels on the first pass.
432 You could write
433 \begin{verbatim}
434 \begin{biblist}[\resetbiblist{999}]
435 \end{verbatim}
436 to tell \LaTeX\ to leave enough room for labels that are three digits
437 long. Similarly, if you want your bibliography typeset in the normal
438 font size instead of footnotesize, you could write
439 \begin{verbatim}
440 \begin{biblist}[\normalsize]
441 \end{verbatim}
442 Want your bibliography numbered starting with~0 instead of~1? Just
443 write
444 \begin{verbatim}
445 \begin{biblist}[\setcounter{bib}{-1}]
446 \end{verbatim}
447
448 The \env{biblist} environment also takes a second optional argument
449 that can be used to modify the current bibliography. This argument
450 consists of an asterisk followed by a set of key-value pairs
451 surrounded by braces:
452 \begin{verbatim}
453 \begin{biblist}*{key={val},...}
454 \end{verbatim}
455 Two keys are supported at present:
456 \begin{description}
457
458 \item[labels]
459
460 Set this to ``numeric,'' ``alphabetic,'' or ``shortalphabetic'' to
461 override the default label style for the current bibliography.
462
463 \item[prefix]
464
465 The value of this key will be prepended to each of the labels in the
466 current bibliography.
467
468 \end{description}
469 \begin{note}
470 Neither of these can be used with the \opt{author-year} option.
471 \end{note}
472 For example, if you are using numeric labels, then
473 \begin{verbatim}
474 \begin{biblist}*{prefix={A}}
475 \end{verbatim}
476 will cause the items to be labeled ``A1,'' ``A2,'' etc. Similarly,
477 \begin{verbatim}
478 \begin{biblist}*{labels={alphabetic}}
479 \end{verbatim}
480 will cause the current list to be labeled alphabetically instead of
481 numerically.
482
483 \begin{note}
484 Depending on your specific use of \cn{cite}s, use of non-numeric
485 prefixes or of mixed numeric and non-numeric label styles can
486 interfere with citation sorting and compression
487 (section~\ref{sec:sorting}). You may need to pass the
488 \opt{non-sorted-cites} and \opt{non-compressed-cites} options to
489 amsrefs to get the correct behavior.
490 \end{note}
491
492 If you want to use both types of optional arguments, the key-value
493 pairs come second:
494 \begin{verbatim}
495 \begin{biblist}[\normalsize]*{...}
496 \end{verbatim}
497
498 Each \env{biblist} environment resets the \cnt{bib} counter so that
499 its items are numbered starting from~1. If you want the numbering to
500 start where the last \env{biblist} left off, use the \env{biblist*}
501 environment instead.
502
503 Finally, users familiar with the \env{thebibliography} environment may
504 wonder why \env{biblist} doesn't have a mandatory argument to specify
505 the longest label. The reason is that the \env{biblist} environment
506 automatically calculates the width of the longest label and stores
507 this information in the \fn{.aux} file. This means that the next time
508 \LaTeX\ is run, the environment will know how much space to leave for
509 the labels.
510
511 \section[Section titles for bibliographies: \env{bibdiv} et
512 al.]{Section titles for bibliographies: \env{bibdiv},\\
513 \env{bibsection}, \env{bibchapter}}
514 \label{bibdiv}
515
516 As seen earlier, the \env{bibdiv} environment provides an appropriate
517 section heading. Ordinarily that's all you need to know, since
518 \env{bibdiv} will automatically switch between a \cn{chapter} and a
519 \cn{section} heading depending on whether the document seems booklike
520 or articlelike. Simililarly, it will use the current value of
521 \cn{bibname} or \cn{refname} for the heading text. However, if that's
522 not sufficient, there are three more ways of customizing its behavior:
523 \begin{enumerate}
524
525 \item
526 Instead of \env{bibdiv}, you can use \env{bibchapter} or
527 \env{bibsection} to generate the appropriate type of heading.
528
529 \item
530 All three environments take an optional argument to override the text
531 of the heading:
532 \begin{verbatim}
533 \begin{bibchapter}[Annotated Bibliography]
534 \end{verbatim}
535
536 \item
537 For maximum flexibility, you can omit the \env{bibdiv} environment
538 entirely and optionally add an arbitrary header:
539 \begin{verbatim}
540 \subsection{Further reading}
541 \end{verbatim}
542
543 \end{enumerate}
544
545 Finally, note that a further significant benefit of having separate
546 \env{bibdiv} and \env{biblist} environments is that you can put
547 arbitrary introductory text between the header and the list:
548 \begin{verbatim}
549 \begin{bibdiv}
550
551 Abbreviations used:
552
553 ...
554
555 \begin{biblist}
556 \end{verbatim}
557
558 \section{More about the \cn{bib} command}\label{bib-command}
559
560 As noted earlier, the syntax of the \cn{bib} command is very similar
561 to that of a \BibTeX\ database record. For example, here's how the
562 third bibliography item from section~\ref{ltb-files} might look in a
563 \fn{.bib} file:
564 \begin{verbatim}
565 @Book{SokalB1998,
566 title={Fashionable Nonsense: Postmodern Intellectuals' Abuse of
567 Science},
568 author={Alan Sokal and Jean Bricmont},
569 publisher={Picador USA},
570 address="New York",
571 year=1998
572 }
573 \end{verbatim}
574 However, there are a number of other significant differences between
575 the two formats:
576
577 \begin{description}
578
579 \item[Order of type and key]
580
581 In \BibTeX\ records, the entry type comes first and serves to mark the
582 start of the field, and the cite key is separated from the data fields
583 by a comma:
584 \begin{verbatim}
585 @Book{SokalB1998,
586 \end{verbatim}
587 In \pkg{amsrefs}, every record begins with the \verb|\bib| command,
588 followed first by the cite key and then by the entry type, and the
589 data fields are preceded by an open brace, not a comma:
590 \begin{verbatim}
591 \bib{SokalB1998}{book}{
592 \end{verbatim}
593
594 \item[Case sensitivity]
595
596 In general, \BibTeX\ doesn't care how you capitalize field names. As
597 far as it is concerned, ``title'', ``TITLE'' and ``tItLe'' are the
598 same field name. Like \TeX\ in general, though, \pkg{amsrefs} is case
599 sensitive. All of the standard field and bibliography entry-type
600 names are spelled with all lowercase letters and must be typed exactly
601 as shown in the documentation.
602
603 \item[Mandatory braces]
604
605 \BibTeX\ allows the braces around field values to be omitted in some
606 contexts and allows double quotes to be substituted for braces. In
607 \pkg{amsrefs}, every field value \emph{must} be surrounded by braces.
608
609 \item[Repeated fields]
610
611 \BibTeX\ does not allow fields to be repeated within a record;
612 \pkg{amsrefs} allows certain fields (like \fld{author}) to be repeated
613 as many times as needed.
614
615 \item[Inverted names]
616
617 \BibTeX\ allows names to be entered in a variety of formats, for
618 example:
619 \begin{verbatim}
620 author={John Doe}
621 author={Doe, John}
622 author={Doe, Jr., John}
623 \end{verbatim}
624 Although \BibTeX\ usually does a good job of parsing names into their
625 components, sometimes it needs help, and experience shows that authors
626 often have trouble telling when they need to provide such help. In
627 order to avoid these problems, \pkg{amsrefs} takes the somewhat
628 draconian step of requiring all names to be written in the form
629 \emph{von Last, First, Jr.}, for example:
630 \begin{verbatim}
631 author={Jones, John Paul}
632 author={van Beethoven, Ludwig}
633 author={Ford, Henry, Jr.}
634 \end{verbatim}
635 It is essential to follow this format for all names; otherwise
636 \pkg{amsrefs} may produce profoundly incorrect results when it is
637 asked to invert names (i.e., format the name as ``Doe, John'' instead
638 of ``John Doe'', as some styles require), replace the first name by
639 its initials (when the \opt{initials} option is used), or create a
640 label based on the last name (the \opt{alphabetic} option).
641
642 \end{description}
643
644 In addition, there are differences in the rules that must be followed
645 in marking the text inside fields:
646 \begin{description}
647
648 \item[Capitalization]
649
650 Some \BibTeX\ styles will adjust the capitalization of titles to
651 achieve a uniform style. This means that authors have to be careful
652 to put extra braces around any characters that should not be upper- or
653 lower-cased. For example, if you were to write
654 \begin{verbatim}
655 title={An $O(n \log n)$ Sorting Network}
656 \end{verbatim}
657 many \BibTeX\ styles would change the title to
658 \begin{quote}
659 An $o(n \log n)$ sorting network
660 \end{quote}
661 possibly resulting in great confusion on the part of the reader. To
662 prevent this, you must surround the mathematical expression with an
663 extra set of braces:
664 \begin{verbatim}
665 title={An {$O(n \log n)$} Sorting Network}
666 \end{verbatim}
667 As with name formats, experience suggests that authors are often
668 confused by \BibTeX's rules and fail to properly protect their titles.
669 The good news is that \pkg{amsrefs} will not change the capitalization
670 of any of your titles. The bad news is that this means you are solely
671 responsible for editing the titles of your bibliography items to match
672 the style your publisher requires.
673
674 \item[Special characters]
675
676 \BibTeX\ is also sometimes confused by text accents or other special
677 characters such as \verb+\ae+ or \verb+\o+, which also have to be
678 surrounded by braces for \BibTeX\ to process them correctly:
679 \begin{verbatim}
680 author={Kurt G{\"o}del}
681 author={V. S{\o}rensen}
682 \end{verbatim}
683 \pkg{amsrefs} is more forgiving and will accept
684 \begin{verbatim}
685 author={G\"odel, Kurt}
686 author={S\o rensen, V.}
687 \end{verbatim}
688 although it is probably still a good idea to surround \verb+\o+ with
689 braces in the second example. We'll talk more about names in
690 sections~\ref{names} and~\ref{attributes}.
691
692 %% \item[ndash] Use of \cn{ndash} instead of \verb'--' for en-dashes is
693 %% recommended (the \verb'--' notation, which is tied to
694 %% idiosyncrasies of the Computer Modern \qq{\TeX{} text} font
695 %% encoding, hinders document translation and the use of alternate
696 %% fonts).
697
698 \end{description}
699
700 Finally, although \pkg{amsrefs} supports many of the same field and
701 entry types that \BibTeX\ does, there are some differences, which we
702 will explore in the next two sections.
703
704 \subsection{Bibliography entry types}
705
706 Compared to \BibTeX, \pkg{amsrefs} has a relatively small number of
707 entry types. However, what it lacks in diversity it makes up for in
708 versatility. Here are the supported entry types, along with some
709 descriptive comments that are meant to suggest the variety of uses for
710 which the type is appropriate.
711
712 \begin{description}
713
714 \item[article]
715
716 A relatively short but self-contained item that is typically published
717 as part of a larger collection, such as a journal, a conference
718 proceedings, an edited collection published as a book, or even as part
719 of a World Wide Web document.
720
721 \item[book]
722
723 A written work by one or more authors where the authors share credit
724 for the work as a whole. For compatibility with \BibTeX, the
725 following entry types are available as aliases for \btype{book}:
726 \btype{collection}, \btype{proceedings}, \btype{manual},
727 and \btype{unpublished}.
728
729 \item[misc]
730
731 Anything that doesn't fit into one of the other types.
732
733 \item[report]
734
735 A technical report, white paper, or the like. Similar to an
736 \btype{article} but usually published and distributed by an
737 organization such as a university or corporation whose primary
738 business is usually not publishing. Also known as a
739 \btype{techreport}.
740
741 \item[thesis]
742
743 Like \emph{report} but produced by the author for an educational
744 institution to satisfy the requirements for a degree. Not (normally)
745 produced by a commercial publisher for sale.
746
747 \item[webpage]
748
749 An online resource. It is limited to the following fields:
750 \fld{accessdate},
751 \fld{author},
752 \fld{date},
753 \fld{note},
754 \fld{subtitle},
755 \fld{title},
756 \fld{url}.
757
758 \end{description}
759
760 \subsection{Field names for the \cn{bib} command}
761
762 The \pkg{amsrefs} package distinguishes between three types of fields:
763 \begin{enumerate}
764
765 \item
766 A \emph{simple} field can appear only once in each record. Some
767 examples are \fld{title} and \fld{publisher}.
768
769 \item
770 A \emph{repeatable} field can appear as many times as necessary. As
771 we saw above, \fld{author} is repeatable, as are \fld{editor} and
772 \fld{translator}, but we'll see later that not all repeatable fields
773 are names.
774
775 \item
776 Briefly, a \emph{compound} field is one that is made up of a
777 collection of subfields, for example:\label{ex:translation}
778 \begin{verbatim}
779 \bib{KostrikinS1965}{article}{
780 author={Kostrikin, A. I.},
781 author={\v{S}afarevi\v{c}, I. R.},
782 title={Cartan pseudogroups and Lie $p$-algebras},
783 journal={Dokl. Akad. Nauk SSSR},
784 volume={168},
785 date={1965},
786 pages={740--742},
787 translation={
788 journal={Soviet Math. Dokl.},
789 volume={6},
790 date={1965},
791 pages={715--718}
792 },
793 review={\MR{0199235}}
794 }
795 \end{verbatim}
796 Here the translation is specified with a compound field so it can have
797 its own set of publication fields.
798
799 \end{enumerate}
800
801 \subsubsection{Simple fields}
802
803 The meaning of many of these should be self-evident, so comments will
804 be kept to a minimum.
805 \begin{description}
806
807 \item[accessdate]
808
809 Used to specify the date on which a \btype{webpage} was viewed, as
810 opposed to the date on which the resource was last modified, which
811 would be put in the \fld{date} field.
812
813 \item[address]
814
815 Usually the address of the publisher or other issuing organization,
816 but inside the \fld{conference} compound field (see
817 page~\pageref{compound}) it refers to the address of the
818 conference.
819
820 \item[booktitle]
821
822 Used in the \btype{article} type to specify the title of the book in
823 which the article appeared. If anything other than a simple book
824 title is required, the \fld{book} compound field should be used
825 instead.
826
827 \item[date]\label{date-format}
828
829 Usually the date of publication, except inside the \fld{conference}
830 field, where it is the date of the conference (see
831 page~\pageref{compound}).
832
833 This replaces \BibTeX's \fld{year} and \fld{month} fields. Its value
834 should be written in ISO 8601 format, e.g., 1967-02-24. The day
835 and/or month can be omitted, so all of the following are valid
836 representations of February 24, 1967:
837 \begin{verbatim}
838 date={1967-02-24}
839 date={1967-02}
840 date={1967}
841 \end{verbatim}
842 Using this format allows \pkg{amsrefs} maximum flexibility in
843 formatting dates, for example, by allowing month names to be printed
844 in full or abbreviated as necessary.
845
846 For \qq{Winter}, \qq{Spring}, \qq{Summer}, \qq{Fall}, either use month
847 numbers of 13, 14, 15, 16 (respectively) or just put in the text
848 before the year:
849 \begin{verbatim}
850 date={Summer 1987},
851 \end{verbatim}
852 For compatibility, \fld{year} is provided as an alias for \fld{date},
853 but its use is discouraged.
854
855 \item[edition]
856
857 For books or reports. If the value of this field is a simple number,
858 \cn{bib} will convert it to cardinal form and add \qq{ed.} (or
859 alternative text if specified by the bibliography style). Otherwise
860 it will be printed as~is.
861
862 \item[eprint]
863
864 Electronic preprint information such as for \url{www.arXiv.org}. See
865 \url{http://xxx.lanl.gov/help/faq/references} for recommended form.
866
867 \item[hyphenation]
868
869 This corresponds to the Babel package notion of \qq{language}. The
870 hyphenation language used for a given \cn{bib} entry is determined
871 from various clues, which are checked in the following order:
872 \begin{enumerate}
873
874 \item
875 The Babel language specified by the \fld{hyphenation} field.
876
877 \item
878 The Babel language specified by the \emph{first word} of the
879 \fld{language} field (after lowercasing).
880
881 \item
882 The current Babel language that was in effect before the \cn{bib}
883 command started.
884
885 \item
886 The current hyphenation patterns of the document, if there are no
887 Babel language modules loaded.
888
889 \end{enumerate}
890 The \fld{hyphenation} field applies to an entire entry. To change the
891 Babel language for a single field, see the discussion of the
892 \fld{language} attribute on page~\pageref{attributes}.
893
894 \nitem[journal]
895
896 \item[label]
897
898 When the \opt{alphabetic} or \opt{shortalphabetic} options are used,
899 \pkg{amsrefs} will usually try to generate the label on its own. If
900 necessary, you can override the automatically generated label by
901 specifying a \fld{label} field.
902
903 \item[language]
904
905 Language of the work. The language name should be the printed form,
906 not a Babel-style language name, since in principle this field could
907 contain more complicated remarks such as \qq{Russian, with French
908 abstract}. Cf.~\fld{hyphenation}.
909
910 \item[note]
911
912 Any additional information that does not fit into one of the other
913 fields.
914
915 \item[number]
916
917 The issue number of the journal for an \btype{article} or the
918 technical report number for a \btype{report}.
919
920 \item[organization]
921
922 The school, university, corporation, or other nonpublisher
923 organization that issued the document.
924
925 \nitem[pages]
926
927 \nitem[part]
928
929 \nitem[publisher]
930
931 \nitem[series]
932
933 %% Let's suppress this at least until we can think of a good
934 %% example.
935 %%
936 %% \item[setup]
937 %%
938 %% This is a special field that can be used to give arbitrary commands to
939 %% be executed at the beginning of the current \cn{bib} entry, after all
940 %% the fields have been read. The idea is that one can alter the
941 %% formatting of an individual entry through this field to handle
942 %% special cases.
943
944 \item[status]
945
946 Typically used for notes such as \qq{to appear} or \qq{in preparation}
947 or \qq{unpublished} with journal articles.
948
949 \item[subtitle]
950
951 Typically used with a multipart journal article to give a subtitle for
952 each part, but it can also be used for books.
953
954 \nitem[title]
955
956 \item[type]
957
958 The type of a thesis, e.g., ``Master's Thesis'' or ``Ph.D. Thesis''.
959
960 \nitem[volume]
961
962 \item[xref]
963
964 This will be explained in section~\ref{xrefs}.
965
966 \end{description}
967
968 \subsubsection{Repeatable fields}
969
970 \begin{description}
971
972 \item[author, editor, translator]
973
974 The authors, editors, and/or translators of the item. If there are
975 other contributors that should be acknowledged, they should be listed
976 in \fld{contribution} fields (see page~\pageref{contributors}).
977
978 \item[isbn, issn]
979
980 An International Standard Book or Serial Number. (These are not
981 printed by the standard styles, but are reserved for future use.)
982
983 \item[review]
984
985 A review number or similar pointer to, for example, \emph{Mathematical
986 Reviews} or \emph{Zentralblatt}. You must supply any special markup
987 for the number; i.e., you should write
988 \begin{verbatim}
989 review={\MR{2015463}}
990 \end{verbatim}
991 instead of
992 \begin{verbatim}
993 review={2015463}
994 \end{verbatim}
995
996 \end{description}
997
998 \subsubsection{Compound fields}\label{compound}
999
1000 These are the compound fields currently supported by \pkg{amsrefs}.
1001
1002 \begin{description}
1003
1004 \item[book]
1005
1006 This is used for conference articles to make it easier to
1007 differentiate between an article and the book or proceedings that it
1008 appeared in. The \fld{book} field can contain any of the following
1009 subfields: \fld{title}, \fld{part}, \fld{subtitle}, \fld{edition},
1010 \fld{editor}, \fld{translator}, \fld{contribution}, \fld{series},
1011 \fld{volume}, \fld{publisher}, \fld{organization}, \fld{address},
1012 \fld{date}, \fld{note}.
1013
1014 It is often used in conjunction with the \fld{conference} field.
1015
1016 \item[conference]
1017
1018 The \fld{conference} field can contain a \fld{title}, \fld{address},
1019 and \fld{date}.
1020
1021 \begin{verbatim}
1022 \bib{Burkholder1986a}{article}{
1023 author={Burkholder, Donald L.},
1024 title={Martingales and Fourier analysis in Banach spaces},
1025 conference={
1026 title={C.I.M.E. Lectures},
1027 address={Varenna, Italy},
1028 date={1985}
1029 },
1030 book={
1031 series={Lecture Notes in Math.},
1032 volume={1206},
1033 publisher={Springer-Verlag},
1034 address={Berlin and New York},
1035 date={1986},
1036 },
1037 pages={61--108},
1038 review={\MR{0864712}}
1039 }
1040 \end{verbatim}
1041
1042 \item[contribution]\label{contributors}
1043
1044 This field can be repeated as many times as necessary to list any
1045 contributors other than authors, editors, or translators.
1046 \begin{verbatim}
1047 contribution={
1048 type={illustrations},
1049 author={Gorey, Edward}
1050 }
1051 \end{verbatim}
1052 which in the default style produces
1053 \begin{quote}
1054 with illustrations by Edward Gorey
1055 \end{quote}
1056 Since contributions are potentially complicated, so is the
1057 \fld{contribution} field:
1058 \begin{itemize}
1059
1060 \item
1061 Sometimes it is necessary to add additional material to the \fld{type}
1062 in order to produce intelligible text:
1063 \begin{verbatim}
1064 contribution={
1065 type={an appendix},
1066 author={Doe, John}
1067 }
1068 \end{verbatim}
1069
1070 \item
1071 \pkg{amsrefs} tries very hard to format multiple contributions, each
1072 of which may have multiple authors, in an appropriate way. However,
1073 there might be cases where the default rules aren't flexible enough,
1074 in which case you can instead use the \fld{contribution} field as a
1075 simple field and format it exactly the way you want:
1076 \begin{verbatim}
1077 contribution={some arbitrary text about contributions}
1078 \end{verbatim}
1079 This feature should only be used as a last resort, though.
1080
1081 \end{itemize}
1082
1083 \item[partial]
1084
1085 This is used with the \btype{article} type for multipart articles.
1086 Like the \fld{contribution} field, it is repeatable. It can contain
1087 any of the following fields: \fld{part}, \fld{subtitle},
1088 \fld{contribution}, \fld{journal}, \fld{volume}, \fld{date},
1089 \fld{number}, \fld{pages}.
1090 \begin{verbatim}
1091 \bib{Zho-fan1972}{article}{
1092 author={Zho-fan, Z.},
1093 title={Monomials},
1094 partial={
1095 part={I},
1096 journal={Tot. Math.},
1097 volume={19},
1098 date={1972},
1099 pages={335--350}
1100 },
1101 partial={
1102 part={II},
1103 journal={Tot. Math.},
1104 volume={20},
1105 date={1973},
1106 pages={19--37}
1107 }
1108 }
1109 \end{verbatim}
1110
1111 \item[reprint]
1112
1113 This can be used inside an \btype{article} to indicate another place
1114 (usually a book) where the article can also be found. It can contain
1115 any field that the \btype{book} type can.
1116 \begin{verbatim}
1117 \bib{Sokal96}{article}{
1118 title={Trangressing the boundaries},
1119 subtitle={Toward a transformative hermeneutics of quantum
1120 gravity},
1121 author={Sokal, Alan},
1122 journal={Social Text},
1123 volume={46/47},
1124 date={1996},
1125 pages={217--252},
1126 reprint={
1127 title={Fashionable Nonsense},
1128 subtitle={Postmodern Intellectuals' Abuse of Science},
1129 author={Sokal, Alan},
1130 author={Bricmont, Jean},
1131 publisher={Picador USA},
1132 address={New York},
1133 date={1998}
1134 }
1135 }
1136 \end{verbatim}
1137
1138 \item[translation]
1139
1140 This is the only compound field that can be used with any bibliography
1141 type. It can contain any field that its parent type can contain. We
1142 saw an example of this on page~\pageref{ex:translation}.
1143
1144 \end{description}
1145
1146 \subsection{What's in a name?}\label{names}
1147
1148 We saw earlier that names must always be entered in the form ``von
1149 Last, First, Jr.''\ so that \pkg{amsrefs} can unambiguously determine
1150 which parts of the name correspond to the surname and which to the
1151 given name. In this section we will discuss some of the other
1152 subtleties that come into play with processing names.
1153
1154 The good news is that the vast majority of the time you don't need to
1155 worry about this section. As long as your names contain only the
1156 following characters, you should be safe:
1157 \begin{itemize}
1158
1159 \item
1160 the 26 ASCII letters, the apostrophe (') and \TeX's tie (\verb|~|) and
1161 grouping (\verb+{}+) characters,
1162
1163 \item
1164 one of the following accent commands: \cn{\"} \cn{\'} \cn{\.}\ \cn{\=}
1165 \cn{\^} \cn{\`} \cn{\~} \cn{\b} \cn{\c} \cn{\d} \cn{\H} \cn{\k}
1166 \cn{\r} \cn{\t} \cn{\u} \cn{\v}, or
1167
1168 \item
1169 one of the following special characters: \cn{AE} \cn{ae} \cn{DH}
1170 \cn{dh} \cn{DJ} \cn{dj} \cn{i} \cn{j} \cn{L} \cn{l} \cn{NG} \cn{ng}
1171 \cn{OE} \cn{oe} \cn{O} \cn{o} \cn{SS} \cn{ss} \cn{TH} \cn{th}.
1172
1173 \end{itemize}
1174 If you are using the \pkg{mathscinet} package, any of the special
1175 characters and accents defined by it can also be used.\footnote{For
1176 pragmatic purposes, note that the difference between an ``accent'' and
1177 a ``special character'' is that all the macros identified as accents
1178 take a single argument, while the ones identified as special
1179 characters do not take an argument.}
1180
1181 \subsubsection{Grouping multiple physical characters into a single
1182 logical character}
1183
1184 Sometimes it's necessary to tell \pkg{amsrefs} to treat two or more
1185 characters as a single ``logical'' character. For example, consider
1186 the following names:
1187 \begin{verbatim}
1188 author={Gagarin, Yuri}
1189 author={Katzenbach, Nicholas deBelleville}
1190 \end{verbatim}
1191 If the \opt{initials} option is in force, \pkg{amsrefs} will shorten
1192 those names to ``Y. Gagarin'' and ``N. d. Katzenbach''. These are
1193 both incorrect, the first because ``Yu'' represents the
1194 transliteration of a single Cyrillic character and the second because
1195 ``deBelleville'' should be shortened to ``deB'', not just~``d''. The
1196 easiest way to force the correct interpretation is by adding braces,
1197 as follows:
1198 \begin{verbatim}
1199 author={Gagarin, {Yu}ri}
1200 author={Katzenbach, Nicholas {deB}elleville}
1201 \end{verbatim}
1202 which tells \pkg{amsrefs} that those characters should be kept
1203 together, producing the correct results.
1204
1205 Incidentally, if you provide the names in already abbreviated form,
1206 i.e.,
1207 \begin{verbatim}
1208 author={Gagarin, Yu.}
1209 author={Katzenbach, N. deB.}
1210 \end{verbatim}
1211 it is not necessary to add the extra braces, since \pkg{amsrefs} will
1212 not further abbreviate any word that already ends in a period (but the
1213 extra braces also would do no harm).
1214
1215 \subsubsection{Declaring new accents or special characters}
1216
1217 In some cases it may also be necessary to add a special character or
1218 accent to the list given above. An accent command can be added to the
1219 list of acceptable name components by using the \cn{DeclareNameAccent}
1220 command. In fact, \pkg{amsrefs} contains a declaration like
1221 \begin{verbatim}
1222 \DeclareNameAccent{\"}
1223 \end{verbatim}
1224 for each of the text accents listed above.
1225
1226 Declaring a new text symbol is only slightly more complicated:
1227 \begin{verbatim}
1228 \DeclareNameSymbol{\AE}{\ae}
1229 \end{verbatim}
1230 This says that \verb+\AE+ and \verb+\ae+ are both allowed as text
1231 symbols inside names and, furthermore, that \verb|\ae| is the
1232 lowercase version of~\verb|\AE|.
1233
1234 \section{Package options}
1235
1236 The \pkg{amsrefs} package has a plethora of options.
1237
1238 \subsection{Citation labels}
1239
1240 By default, the items in your bibliography are numbered, as in the
1241 \bst{plain} \BibTeX\ style. However, three other label styles are
1242 also supported via the following options:
1243 \begin{description}
1244
1245 \item[alphabetic]
1246
1247 This generates alphabetic labels similar to the \pkg{alpha} \BibTeX\
1248 style, consisting of the first letter(s) of each author name plus the
1249 year of publication.
1250
1251 \item[shortalphabetic]
1252
1253 This generates a shorter alphabetic label using only the first letter
1254 of each author name.
1255
1256 \item[author-year]
1257
1258 This switches to the popular author-year citation format, similar to
1259 that described in \emph{The Chicago Manual of Style}. See
1260 section~\ref{author-year} for more information on this option.
1261
1262 \item[y2k]
1263
1264 When using the \opt{alphabetic} option, normally only the last two
1265 digits of the year are used in the label. The \opt{y2k} instructs
1266 \pkg{amsrefs} to use the full year.
1267
1268 \end{description}
1269
1270 \begin{note}
1271 Since \pkg{amsrefs} leaves the order of the bibliography items up to
1272 the user, a common mistake when using non-numeric labels (especially
1273 \opt{shortalphabetic} labels) is to put the items in an order that is
1274 incompatible with the natural order of the labels. This can result in
1275 a sequence such as this:
1276 \begin{biblist}*{labels={shortalphabetic}}
1277
1278 \bib{A}{article}{
1279 title={\dots},
1280 author={Doe, John},
1281 }
1282
1283 \bib{C}{article}{
1284 title={\dots},
1285 author={Doe, John},
1286 author={Smith, Jane},
1287 }
1288
1289 \bib{B}{article}{
1290 title={\dots},
1291 author={Dunn, John},
1292 }
1293 \end{biblist}
1294 where \pkg{amsrefs} does not automatically replace the first and third
1295 labels by ``D1'' and ``D2'' as it would if they were consecutive.
1296 This is because the real error lies in attempting to force the labels
1297 into an unordered sequence. Readers are entitled to find reference
1298 ``D2'' between references ``D1'' and~``DS'' in the bibliography just
1299 as they are entitled to find reference~[2] between references [1]
1300 and~[3].
1301
1302 If \pkg{amsrefs} encounters a situation like this, it will issue a
1303 warning. There are three ways to resolve the problem:
1304 \begin{enumerate}
1305
1306 \item
1307 Rearrange the items in an order that is compatible with the label
1308 style you have chosen.
1309
1310 \item
1311 Choose a different label style that is compatible with the order you
1312 have chosen for the items.
1313
1314 \item
1315 Use the \fld{label} field to override the automatically-generated
1316 label and leave your readers to their own devices.
1317
1318 \end{enumerate}
1319
1320 \end{note}
1321
1322 \subsection{Citation sorting and compression}\label{sec:sorting}
1323
1324 When numeric citation labels are being used and \pkg{amsrefs}
1325 encounters a list of multiple citations (for example,
1326 \verb|\cites{A,B}| or \verb|\citelist{\cite{A}\cite{B}}|), it will
1327 normally sort the citation labels and then compress ranges of three or
1328 more consecutive labels into a range of the form $n$--$m$. For
1329 example, the list [11, 9, 10, 1, 16, 12] would first be sorted into
1330 [1, 9, 10, 11, 12, 16] and then compressed into [1, 9--12, 16]. These
1331 options can be used to modify that behavior.
1332
1333 \begin{description}
1334
1335 \item[non-compressed-cites]
1336
1337 Turn off range compression; citations will still be sorted. Range
1338 compression is also automatically turned off if \pkg{amsrefs} detects
1339 that the \pkg{hyperref} package has been loaded.\footnote{In order for
1340 this to work correctly, the \pkg{hyperref} package must be loaded
1341 \emph{after} the \pkg{amsrefs} package.}
1342
1343 \item[non-sorted-cites]
1344
1345 Turn off range sorting. This also turns off range compression as a
1346 side-effect.
1347
1348 \end{description}
1349
1350 \subsection{Abbreviations}
1351
1352 These options emulate various aspects of the behavior of the \BibTeX\
1353 \bst{abbrv} style, but unlike \bst{abbrv}, they can be used with any
1354 of the citation label styles described above.
1355
1356 \begin{description}
1357
1358 \item[abbrev]
1359
1360 This is equivalent to requesting all four of the following options.
1361
1362 \item[initials]
1363
1364 Replace the given names of all authors, editors, and translators with
1365 their initials. See section~\ref{names} for further discussion.
1366
1367 \item[short-journals]
1368
1369 Print short form instead of full form for journal names. This works
1370 only with abbreviations defined with the \cn{DefineJournal} command
1371 (see section~\ref{abbreviations}).
1372
1373 \item[short-months]
1374
1375 Print short version of month names (e.g., Jan.\ instead of January).
1376 This works only when you write all dates in ISO~8601 format (see
1377 page~\pageref{date-format}).
1378
1379 \item[short-publishers]
1380
1381 Print short form instead of full form for publisher names. This works
1382 only with abbreviations defined with the \cn{DefinePublisher} command
1383 (see section~\ref{abbreviations}).
1384
1385 \end{description}
1386
1387 \subsection{Miscellaneous options}
1388
1389 \begin{description}
1390
1391 \item[backrefs]
1392
1393 This option causes ``back-references'' to be printed at the end of
1394 each bibliography entry to show what page it was cited on. This
1395 option will work only if the \pkg{hyperref} package is installed.
1396
1397 \item[bibtex-style]
1398
1399 By default, \pkg{amsrefs} formats references using the AMS house
1400 style. The \opt{bibtex-style} option instructs it to use a format that is
1401 very similar to the one implemented by the standard \BibTeX\ styles
1402 (\bst{plain}, \bst{alpha}, \bst{abbrv}, and \bst{unsrt}).
1403
1404 \item[citation-order]
1405
1406 This option applies only when using \pkg{amsrefs} in conjunction with
1407 \BibTeX. Consequently, changing this option will have no effect until
1408 after the next \bibtex/ run.
1409
1410 The \opt{citation-order} option corresponds to the standard \BibTeX\
1411 style \bst{unsrt}, where items are printed in the reference list in
1412 the order in which they are cited in the document.
1413
1414 \item[lite]
1415
1416 Suppress the loading of the following packages, which \pkg{amsrefs}
1417 will normally automatically load:
1418 \begin{description}
1419
1420 \item[\pkg{mathscinet}]
1421
1422 Define a number of special characters and accents that are sometimes
1423 encountered when downloading data from MathSciNet.
1424
1425 \item[\pkg{txtcmds}]
1426
1427 Provide shorthand commands for a number of characters that are usually
1428 specified via ligatures (e.g., \verb|--| for an en-dash or \verb|?`|
1429 for ``?`''. Using these ligatures can cause problems if you're using
1430 fonts other than the Computer Modern Roman family or if you want to
1431 make it easy to convert your document to, say, HTML\@. \LaTeX\ does
1432 provide macros for these characters, but their names tend to be rather
1433 unwieldy (e.g., \cn{textendash} and \cn{textquestiondown}), so
1434 \pkg{txtcmds} provides shorter names (\cn{ndash} and \cn{qd} in this
1435 case).
1436
1437 \end{description}
1438
1439 \item[msc-links]
1440
1441 Redefine the \cn{MR} command to create hypertext links to the
1442 MathSciNet database. This option will work only if the \pkg{hyperref}
1443 package is installed.
1444
1445 \item[nobysame]
1446
1447 If two or more consecutive bibliography items have the same authors,
1448 \pkg{amsrefs} will normally replace the author names in the second and
1449 succeeding entries by a horizontal rule (\hbox to3em{\hrulefill}).
1450 This option disables this feature, causing the full author names to
1451 always be printed.
1452
1453 \end{description}
1454
1455 \section{Citing entries: \cn{cite} and friends}
1456
1457 \LaTeX's standard \cn{cite} command has two major shortcomings:
1458 \begin{enumerate}
1459
1460 \item
1461 It takes an arbitrary number of arguments, so you can write, for
1462 example, \cnm{cite}{xx,yy} to get [13, 15]. But this feature does not
1463 interact well with the optional argument that's used to give a
1464 targeted citation: \cnom{cite}[Theorem 4.9]{xx} will give you [13,
1465 Theorem 4.9], but how do you request [13, Theorem 4.9; 15] or [13; 15,
1466 Theorem 4.9]?
1467
1468 \item
1469 The optional argument uses the standard \LaTeX\ syntax, which has been
1470 shown to be errorprone. For example, a common user error is to write
1471 something like
1472 \begin{verbatim}
1473 \begin{thm}[\cite[Theorem 4.9]{xyz}]
1474 \end{verbatim}
1475 (which results in a syntax error) instead of
1476 \begin{verbatim}
1477 \begin{thm}[{\cite[Theorem 4.9]{xyz}}]
1478 \end{verbatim}
1479
1480 \end{enumerate}
1481
1482 The \pkg{amsrefs} package addresses both of these problems by
1483 providing separate commands for single and multiple citations and
1484 implementing a new syntax for optional arguments.
1485
1486 \begin{description}
1487
1488 \item[\cn{cite}]
1489
1490 For backwards compatibility, the old syntax is still supported; so,
1491 for example, \cnm{cite}{a,b,c} and \verb|\cite[xxx]{...}| work the
1492 same way they always have. However, for consistency we recommend that
1493 you use \cn{cite} only for single cites and use \cn{citelist} (or
1494 \cn{cites}) for multiple citations.
1495
1496 In addition, the square bracket notation \cnom{cite}[...]{...} is also
1497 deprecated, because a superior alternative is provided:
1498 \begin{verbatim}
1499 \cite{xyz}*{Theorem 4.9}
1500 \end{verbatim}
1501 Note that this does not suffer from the syntax problems noted above,
1502 since
1503 \begin{verbatim}
1504 \begin{thm}[\cite{xyz}*{Theorem 4.9}]
1505 \end{verbatim}
1506 does not have the same problems that
1507 \begin{verbatim}
1508 \begin{thm}[\cite[Theorem 4.9]{xyz}]
1509 \end{verbatim}
1510 does.
1511
1512 \item[\cn{citelist}]
1513
1514 This is used to group a number of individual \cn{cite} commands into a
1515 single citation. Among other things, this makes it possible to add an
1516 optional argument to any of the \cn{cite} commands unambiguously:
1517 \begin{verbatim}
1518 \citelist{\cite{xx} \cite{yy}*{Theorem 4.9} \cite{zz}}
1519 \end{verbatim}
1520 \textbf{Note that there is no punctuation or other text between the
1521 \cn{cite} commands}. Any necessary commas or other punctuation will
1522 be supplied automatically. Any attempts to supply it by hand will
1523 backfire.
1524
1525 \item[\cn{cites}]
1526
1527 This is a variant of \cn{citelist}, provided for convenience:
1528 \begin{verbatim}
1529 \cites{aa,bb,cc}
1530 \end{verbatim}
1531 is equivalent to
1532 \begin{verbatim}
1533 \citelist{\cite{aa}\cite{bb}\cite{cc}}
1534 \end{verbatim}
1535 Note that \cn{cites} does \emph{not} take an optional arguments.
1536
1537 \item[\cn{nocite}]
1538
1539 This continues to work the same way that it does in standard \LaTeX\
1540 when used with \BibTeX, but see page~\pageref{nocite} for limitations
1541 when it is used with \cn{bibselect} and \fn{.ltb} files.
1542
1543 \end{description}
1544
1545 When the \opt{author-year} option is used, there are some additional
1546 citation commands available, as we shall see in the next section.
1547
1548 \subsection{Author-year citation schemes}\label{author-year}
1549
1550 When an author-year citation scheme is used, some further
1551 complications arise, since different forms of citations are used
1552 depending on the grammatical context.
1553
1554 The first form is used when the citation serves as a parenthetical
1555 annotation: i.e., it could be omitted without harming the grammatical
1556 structure of the sentence containing it. For example:
1557 \begin{quote}
1558 The question first arose in systems theory (Rupp and Young, 1977).
1559 \end{quote}
1560
1561 The second form is like the first but is used when the author name is
1562 already present as a natural part of the sentence and only the year
1563 should be parenthesized:
1564 \begin{quote}
1565 Rupp and Young (1977) have investigated \dots
1566 \end{quote}
1567 Note that as in the first example, the material in parentheses can be
1568 deleted without changing the meaning of the sentence.
1569
1570 A third form is preferred by some authors when the citation serves as
1571 a direct object or other nounlike role within its sentence. Consider
1572 the following example:
1573 \begin{quote}
1574 \dots\ for further details, see Rupp and Young (1977).
1575 \end{quote}
1576 Although this may appear at first glance identical with the second
1577 example, it is subtly different, since removing the parenthesized
1578 material results in
1579 \begin{quote}
1580 \dots\ for further details, see Rupp and Young.
1581 \end{quote}
1582 which does affect the meaning of the sentence.
1583
1584 Another way of seeing the difference between the second and third
1585 examples is to consider how those sentences might read if numeric
1586 labels were being used:
1587 \begin{quote}
1588 Rupp and Young [14] have investigated \dots\par
1589 \dots\ for further details, see [14].
1590 \end{quote}
1591 Admittedly, ``see~[14]'' is poor style, but it does highlight the fact
1592 that in the third example ``Rupp and Young'' is part of the text we
1593 expect our cite command to generate, while in the second example it is
1594 not.
1595
1596 %%** ``delegate''???
1597
1598 We delegate \cn{cite} to produce the primary parenthetical form
1599 ``(Author, Year)'' and provide \cn{ycite} (\qq{year cite}) and
1600 \cn{ocite} (\qq{object cite}) as the other forms. Our three examples
1601 would thus be coded as follows:
1602 \begin{verbatim}
1603 The question first arose in systems theory \cite{...}.
1604
1605 Rupp and Young \ycite{...} have investigated
1606
1607 for further details, see \ocite{...}.
1608 \end{verbatim}
1609 For symmetry, a \cn{citeauthor} command, which produces the list of
1610 authors without the year, is also provided, and plural forms
1611 \cn{ycites} and \cn{ocites} are provided to mirror \cn{cites}. There
1612 is also a \cn{citeyear} command that is identical to \cn{ycite} except
1613 that it suppresses the surrounding parentheses.
1614
1615 Finally, in some author-year styles, if there are three or more
1616 authors, \cn{cite} and \cn{ocite} will produce abbreviated author
1617 lists (``Larry et al.''\ instead of ``Larry, Moe, and Curly''). The
1618 ``full'' variants \cn{fullcite} and \cn{fullocite} will always print
1619 the full list.
1620
1621 \section{Advanced features}
1622
1623 \subsection{Field attributes}\label{attributes}
1624
1625 Sometimes it's necessary to associate some data with a field that is
1626 not actually part of the data of the field. For example, consider
1627 Chinese names, which are traditionally written with the family name
1628 first:
1629 \begin{quote}
1630 Li Lian Jie\qquad\emph{not} Li, Lian Jie \emph{or} Lian Jie Li
1631 \end{quote}
1632 Unfortunately, if you write
1633 \begin{verbatim}
1634 author={Li, Lian Jie}
1635 \end{verbatim}
1636 you will get one of the incorrect forms above. On the other hand, if
1637 you try to force the correct order by writing
1638 \begin{verbatim}
1639 author={Li Lian Jie}
1640 \end{verbatim}
1641 \pkg{amsrefs} will be unable to process the name correctly if, for
1642 example, the \opt{initials} or \opt{alphabetic} options are requested.
1643
1644 To solve this problem, you can set the \attr{inverted} attribute for a
1645 given name as follows:
1646 \begin{verbatim}
1647 author={Li, Lian Jie}*{inverted={yes}}
1648 \end{verbatim}
1649 As you can see, attributes are given as key-value pairs following the
1650 the field value and separated by an asterisk. The \attr{inverted}
1651 attribute can be set on any name.
1652
1653 At present the only other attribute that is supported is
1654 \attr{language}, which can be set on any field. It's value should be
1655 a valid Babel language name and will apply only to that field. This
1656 can be especially useful if you need to change the hyphenation
1657 patterns or font encoding for a single field:
1658 \begin{verbatim}
1659 \bib{Denecke1982}{article}{
1660 author={Denecke, K.},
1661 title={Pr\"aprimale Algebren, die arithmetische Variet\"aten
1662 erzeugen}*{language={german}},
1663 booktitle={Universal Algebra and Applications},
1664 series={Banach Center Publ.},
1665 volume={9},
1666 publisher={PWN},
1667 address={Warsaw},
1668 date={1982},
1669 pages={391--398}
1670 }
1671 \end{verbatim}
1672
1673 \subsection{Cross-references: \cn{bib*} and the \fld{xref} field}
1674 \label{xrefs}
1675
1676 Distinct bibliography items often share a great deal of common data,
1677 especially when two or more papers from a single conference are being
1678 cited:
1679 \begin{verbatim}
1680 \bib{StockmeyerM73}{article}{
1681 title={Word Problems Requiring Exponential Time},
1682 subtitle={Preliminary Report},
1683 author={Stockmeyer, L. J.},
1684 author={Meyer, A. R.},
1685 pages={1--9},
1686 booktitle={Conference Record of Fifth Annual ACM Symposium on
1687 Theory of Computing},
1688 date={1973},
1689 address={Austin, Texas},
1690 publisher={ACM}
1691 }
1692
1693 \bib{Kung73}{article}{
1694 title={The Computational Complexity of Algebraic Numbers},
1695 author={Kung, H. T.},
1696 pages={152--159},
1697 booktitle={Conference Record of Fifth Annual ACM Symposium on
1698 Theory of Computing},
1699 date={1973},
1700 address={Austin, Texas},
1701 publisher={ACM}
1702 }
1703 \end{verbatim}
1704 To cut down on the amount of text that has to be repeated, you can put
1705 the common information in a separate entry and then include it via the
1706 \fld{xref} field, as follows:
1707 \begin{verbatim}
1708 \bib*{STOC5}{book}{
1709 title={Conference Record of Fifth Annual ACM Symposium on
1710 Theory of Computing},
1711 date={1973},
1712 address={Austin, Texas},
1713 publisher={ACM}
1714 }
1715
1716 \bib{StockmeyerM73}{article}{
1717 title={Word Problems Requiring Exponential Time},
1718 subtitle={Preliminary Report},
1719 author={Stockmeyer, L. J.},
1720 author={Meyer, A. R.},
1721 pages={1--9},
1722 xref={STOC5}
1723 }
1724
1725 \bib{Kung73}{article}{
1726 title={The Computational Complexity of Algebraic Numbers},
1727 author={Kung, H. T.},
1728 pages={152--159},
1729 xref={STOC5}
1730 }
1731 \end{verbatim}
1732 There are a number of things to take note of:
1733 \begin{enumerate}
1734
1735 \item
1736 The \texttt{STOC5} entry uses the $*$-variant of the \cn{bib} command.
1737 The $*$ indicates that this entry is for use in cross-references. It
1738 cannot be \cn{cite}d independently and will never contribute an item
1739 to a \env{biblist}. If you do want the conference proceedings to
1740 appear as a separate item, the easiest way is to create a separate
1741 \cn{bib} item as follows:
1742 \begin{verbatim}
1743 \bib{STOC5-citable}{book}{
1744 xref={STOC5}
1745 }
1746 \end{verbatim}
1747
1748 \item
1749 All \cn{bib*} records must occur \emph{before} the entry that
1750 references them.
1751
1752 \item
1753 Within a \cn{bib*} entry, \emph{all} fields should be treated as
1754 moving arguments (see section~C.1.3 of the \LaTeX\ manual), so any
1755 fragile commands should be preceded by \cn{protect}.
1756
1757 \item
1758 Even though the \texttt{STOC5} record used the \fld{title} field, its
1759 title showed up as a \fld{booktitle} in the other records. This is
1760 the only case where a field is renamed when copied from the \cn{bib*}
1761 record.
1762
1763 \end{enumerate}
1764
1765 \subsection[Compound fields revisited]{Compound fields revisited:
1766 compound fields\\ as cross-references}
1767
1768 Earlier we saw how to use compound fields by embedding a set of
1769 key-value pairs. However, with the exception of the \fld{contribution}
1770 field, all compound fields can also function as cross-reference
1771 fields. For example, our example from page~\pageref{ex:translation}
1772 could equally well have been coded as
1773 \begin{verbatim}
1774 \bib*{KostrikinS1965T}{article}{
1775 journal={Soviet Math. Dokl.},
1776 volume={6},
1777 date={1965},
1778 pages={715--718}
1779 }
1780
1781 \bib{KostrikinS1965B}{article}{
1782 author={Kostrikin, A. I.},
1783 author={\v{S}afarevi\v{c}, I. R.},
1784 title={Cartan pseudogroups and Lie $p$-algebras},
1785 journal={Dokl. Akad. Nauk SSSR},
1786 volume={168},
1787 date={1965},
1788 pages={740--742},
1789 translation={KostrikinS1965T},
1790 review={\MR{0199235}}
1791 }
1792 \end{verbatim}
1793 Whether this is an improvement or not is left as an exercise for the
1794 reader.
1795
1796 \subsection[Abbreviations: \cn{DefineName} et al.]{Abbreviations:
1797 \cn{DefineName}, \cn{DefineJournal},\\ and \cn{DefinePublisher}}
1798 \label{abbreviations}
1799
1800 The \fld{xref} mechanism is fine when there are several fields that
1801 you want to group together and refer to as a unit, but what if you
1802 want a handy abbreviation for a single field, such as an individual
1803 author name, journal, or publisher? These are also provided.
1804 After writing
1805 \begin{verbatim}
1806 \DefineName{dmj}{Jones, David M.}
1807
1808 \DefinePublisher{ams}{AMS}{American Mathematical Society}{Providence}
1809
1810 \DefineJournal{jams}{0894-0347}
1811 {J. Amer. Math. Soc.}
1812 {Journal of the American Mathematical Society}
1813 \end{verbatim}
1814 you can use these abbrevations as follows:
1815 \begin{verbatim}
1816 author={dmj} (or editor={dmj} or translator={dmj})
1817
1818 journal={jams}
1819
1820 publisher={ams}
1821 \end{verbatim}
1822
1823 The second argument of \cn{DefinePublisher} is the abbreviated form of
1824 the publisher's name, the third argument is the full name, and the
1825 fourth will be used as the \fld{address}. If the
1826 \opt{short-publishers} option is requested, then the abbreviation will
1827 be used; otherwise the full name will be used.
1828
1829 Similarly, the third argument of \cn{DefineJournal} will be used if
1830 the \opt{short-journals} option is requested; otherwise the fourth
1831 argument will be used. (The second argument is the ISSN of the
1832 journal, which is not currently used, but is included for future use.)
1833
1834 \subsection{Line breaks in the bibliography}
1835
1836 Suppose you need to recommend to \LaTeX\ that it break a line in a
1837 particular place. Suggesting a line break in the middle of a field
1838 presents no difficulties: just edit your final \fn{.bbl} file and
1839 insert a \cn{linebreak} command:
1840 \begin{verbatim}
1841 subtitle={Toward a transformative hermeneutics\linebreak[3] of
1842 quantum gravity},
1843 \end{verbatim}
1844 But what if you need to force a line break \emph{between} two fields?
1845 At first blush you might fear that
1846 \begin{verbatim}
1847 subtitle={...hermeneutics of quantum gravity\linebreak[3]},
1848 \end{verbatim}
1849 will cause a line break before the comma that \pkg{amsrefs} normally
1850 inserts after the title:
1851 \begin{quote}
1852 \hfill\dots \emph{hermeneutics of quantum gravity}\linebreak[3], Social
1853 Text\dots
1854 \end{quote}
1855 Have no fear; \pkg{amsrefs} will detect this and automatically move
1856 the comma in front of the line break, as desired:
1857 \begin{quote}
1858 \hfill\dots \emph{hermeneutics of quantum gravity},\linebreak[3] Social
1859 Text\dots
1860 \end{quote}
1861
1862 \subsection{Defining custom entry types or styles}
1863
1864 See the documentation of \cn{BibSpec} and related commands in ``The
1865 \pkg{amsrefs} package'' (\fn{amsrefs.pdf}).
1866
1867 \end{document}