summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/amsrefs/amsrdoc.tex
blob: 9c29af18082e450314574fe930782163dd4805d0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
%% filename: amsrdoc.tex
%% version: 1.03
%% date: 2008/10/27
%%
%% 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 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}

\renewcommand*\descriptionlabel[1]{\hspace\labelsep
                                \normalfont\bfseries #1:}

\newcommand{\nshline}{\hline\omit\\}

\makeatletter

\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{October 27, 2008}

\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}

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.

\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[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}

\subsection{Citation sorting and compression}

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}.

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}

\end{document}