Debian Codegraph @

texmf-dist/source/latex/amsrefs/README

raw
1 README for amsrefs 2.14 [2013/03/07]
2
3 Copyright 2001-2004, 2007, 2008, 2010-2013 American Mathematical Society.
4
5 This work may be distributed and/or modified under the
6 conditions of the LaTeX Project Public License, either version 1.3c
7 of this license or (at your option) any later version.
8 The latest version of this license is in
9 http://www.latex-project.org/lppl.txt
10 and version 1.3c or later is part of all distributions of LaTeX
11 version 2005/12/01 or later.
12
13 This work has the LPPL maintenance status `maintained'.
14
15 The Current Maintainer of this work is the American Mathematical
16 Society.
17
18 American Mathematical Society
19 Technical Support
20 Publications Technical Group
21 201 Charles Street
22 Providence, RI 02904
23 USA
24 tel: (401) 455-4080
25 (800) 321-4267 (USA and Canada only)
26 fax: (401) 331-3842
27 email: [email protected]
28
29 ========================================================================
30 CONTENTS
31 I. OVERVIEW
32 II. FEATURES
33 III. INSTALLATION AND GETTING STARTED
34 IV. REMARKS ON THIS RELEASE
35 V. CHANGE LOG
36
37 ========================================================================
38 I. OVERVIEW
39
40 The amsrefs package supports bibliographies and citations in LaTeX
41 documents. The basic citation command remains more or less the same
42 as in standard LaTeX (\cite), but a number of additional variations
43 address certain known pitfalls or gaps in the standard LaTeX set of
44 citation features.
45
46 The command for bibliography items is different -- \bib instead of
47 \bibitem -- for reasons that will be evident upon further reading in
48 the documentation.
49
50 A set of BibTeX style files are provided to allow people to extract
51 data from .bib files and produce .bbl files in amsrefs format instead
52 of conventional \bibitem format.
53
54 User documentation is in amsrdoc.pdf and amsrefs.faq.
55
56 Technical documentation (including documentation for package writers)
57 is in amsrefs.pdf.
58
59 ========================================================================
60 II. FEATURES
61
62 -- Preservation of structure.
63
64 With BibTeX alone, the structure of a bibitem in a .bib file is lost
65 when items are imported into a .bbl file for direct processing by
66 LaTeX. With amsrefs, there is no such conversion; LaTeX typesets the
67 bibliography directly from the structured data. The greatest
68 potential advantage of this is seen when archiving documents in LaTeX
69 form or transmitting them to another user (such as a publisher).
70
71 -- Deferred formatting.
72
73 Since bibliography entries are stored in structured format in the
74 LaTeX file and the formatting is under the control of a LaTeX package
75 instead of a separate program, the style of the bibliography can be
76 changed on demand without re-importing everything from the original
77 database(s).
78
79 -- More natural data format for titles.
80
81 Proper nouns do not need to have braces added to prevent
82 capitalization problems.
83
84 -- Less ambiguous format for author names.
85
86 When author names are given in inverted order (last name first) it is
87 possible for LaTeX to unambiguously identify the last name without any
88 further markup, even in cases like Saunders Mac Lane (Mac Lane,
89 Saunders) versus Stephen H. Lane (Lane, Stephen H.), or Cam Van Tran
90 (Tran, Cam Van) versus Bert Van Keulen (Van Keulen, Bert). In BibTeX
91 some of these would need to have extra braces added to ensure that the
92 surname is accurately distinguished.
93
94 -- Author-year citations.
95
96 There is integrated support for citations in author-year form.
97
98 -- Back-reference support.
99
100 Works in conjunction with the hyperref package.
101
102 -- Setup requires only LaTeX knowledge.
103
104 All bibliography setup can be done in LaTeX; learning another
105 programming language (such as, the one used in BibTeX bst files) is
106 unnecessary.
107
108 -- Self-printable database files.
109
110 A LaTeX document that contains only a bibliography in amsrefs forms can
111 be used as a database for exporting entries to other documents. And
112 because it is a LaTeX document, the database can be printed directly at
113 any time simply by running it through LaTeX in the usual way.
114
115 -- Self-contained.
116
117 In many cases it seems possible to do without BibTeX entirely. For
118 example, if the entries are extracted from a single database file that
119 is maintained in sorted order, the bibliography can be printed directly
120 by LaTeX on the first pass and the citations resolved on the second
121 pass.
122
123 ========================================================================
124 III. INSTALLATION AND GETTING STARTED
125
126 1. Install the package, referring to install.txt as needed.
127
128 2. There are four example files provided:
129
130 cite-xa : Demonstrates an author-year citation scheme. The
131 bibliography is embedded in the .tex file instead of
132 residing in a separate .bbl file.
133
134 cite-xb : Demonstrates usage with more-or-less standard BibTeX
135 methods.
136
137 cite-xs : Shows how the bbl file can be created by LaTeX itself from a
138 suitably presorted ltb file.
139
140 cite-xh : A working hyperref/backrefs example.
141
142 3. Run LaTeX on cite-xa.tex. Take a look at the messages that have to
143 do with citations and the bibliography section. Run LaTeX again to
144 resolve the citations and check the output.
145
146 4. Run LaTeX on cite-xb.tex. Run BibTeX. Look at the bbl file.
147 Interesting, huh? Run LaTeX twice more to resolve the citations.
148
149 5. Run LaTeX on cite-xs.tex and look at the output.
150
151 6. Run pdflatex on cite-xh.tex (it is set up to use BibTeX also, like
152 cite-xb).
153
154 ========================================================================
155 IV. REMARKS ON THIS RELEASE
156
157 Version 2.12 of amsrefs implements two new features for the biblist
158 environment, one new entry type, one new warning, and one bug fix.
159
160 New features: The biblist environment now takes an optional argument
161 consisting of an asterisk followed by a brace-delimited set of
162 key-value pairs. The currently supported keys are "labels," which
163 changes the label style of the current biblist, and "prefix,"
164 which adds a prefix to each label. For example, if you are using
165 numeric labels, then
166
167 \begin{biblist}*{prefix={A}}
168
169 will result in items labeled A1, A2, etc., instead of 1, 2, etc.
170
171 Similarly,
172
173 \begin{biblist}*{labels={alphabetic}}
174
175 will switch to alphabetic labels for the current bibliography.
176 Other allowable values are "numeric" and "shortalphabetic."
177
178 The biblist environment already takes a []-delimited optional
179 argument, so if you want to use both, the *-argument comes last:
180
181 \begin{biblist}[\normalsize]*{...}
182
183 NOTE: Use of non-numeric prefixes or of mixed numeric and
184 non-numeric label styles can interfere with the citation sorting
185 and compression features, depending on exactly how you arrange
186 your \cite's. You may need to pass the non-sorted-cites and
187 non-compressed-cites options to amsrefs to get the correct
188 behavior.
189
190 New entry type: There is now a webpage entry designed for references
191 to online resources. It takes the following fields: accessdate,
192 author, date, note, subtitle, title, url.
193
194 New warning: A common mistake when using non-numeric labels is to
195 place the bibliography items in an order that is incompatible with
196 the labels assigned by amsrefs. This can result in a sequence
197 such as this
198
199 [D] John Doe. ...
200 [DS] John Doe and Jane Smith. ...
201 [D] John Dunn. ...
202
203 where amsrefs does not automatically replace the first and third
204 labels by "D1" and "D2" as it would if they were consecutive.
205 This is because the real error lies in attempting to force the
206 labels into an unordered sequence. Readers are entitled to expect
207 that reference "D2" lies between references "D1" and "DS" in the
208 bibliography just as they are entitled to expect that reference
209 [2] lies between references [1] and [3].
210
211 If amsrefs encounters a situation like this, it will now issue a
212 warning. There are three ways to resolve the problem:
213
214 1. Rearrange the items in an order that is compatible with the
215 label style you have chosen.
216
217 2. Choose a different label style that is compatible with the
218 order you have chosen for the items.
219
220 3. Use the label field to override the automatically-generated
221 label and leave your readers to their own devices.
222
223 Bug fix: Spaces are now ignored inside the first argument (the
224 citekey) to \bib. Previously, something like
225
226 \bib{Doe 1998}{...}{...}
227
228 along with
229
230 \cite{Doe 1998}
231
232 would result in a warning that the citation 'Doe1998' was
233 undefined since the space was stripped from the argument to \cite,
234 but not from the first argument to \bib.
235
236 ========================================================================
237 V. CHANGE LOG (REVERSE CHRONOLOGICAL ORDER)
238
239 2012-03-07 amsrefs.dtx v2.14
240 -- More thorough patch to \calc@alpha@suffix.
241
242 2012-03-06 amsrefs.dtx v2.13
243 -- Patched \calc@alpha@suffix to fix a problem with use of
244 \etalchar in alphabetic labels.
245
246 2012-01-15 amsrefs.dtx v2.12
247 -- Added *-optional argument to biblist to allow setting of new
248 per-biblist prefix and labels options.
249 -- Added new webpage entry type.
250 -- Patched \bib to ignore spaces inside the citekey for
251 compatibility with \cite.
252 -- Add a warning if an out-of-order duplicate biblabel stem is
253 detected.
254
255 2012-07-26 amsrefs.dtx v2.11
256 -- Minimal support for mixing \bibitem with \bib. This is *not*
257 recommended practice and will not be mentioned in the user
258 documentation, but it is necessary for certain internal AMS
259 applications.
260
261 -- Eliminated the "(to appear in print)" note that \PrintDOI used
262 to add if there was was no volume field.
263
264 -- Added \citeyear to aid in emulating natbib.
265
266 * textcmds.dtx 2.00:
267 -- Replaced most \newcommand's by \providecommand to minimize
268 chances of conflicts with other packages or user definitions.
269
270 2012-05-08 amsrefs.dtx 2.10
271 -- patched amsbst.sty to remove unwanted close paren from \PrintEditorsA
272 -- patched \@endbiblist to reset \previous@primary between biblists
273
274 2010-08-17 amsrefs.dtx 2.09
275
276 -- Restored support for \citeform that was inadvertently lost
277 somewhere along the way.
278 -- .bst files now unpack into bibtex/bst/amsrefs instead of
279 bibtex/bst/ams
280 -- .bib files now unpack into bibtex/bib/amsrefs instead of
281 bibtex/bib/ams
282
283 2010-08-13 amsrefs.dtx 2.08
284
285 -- Updated license to LPPL.
286 -- Patched author-year \BibLabel to support hyperref.
287 -- Added \biblistfont to support easier customization of
288 bibliography font.
289
290 2008-07-25 amsrefs.dtx 2.07: AMS-internal modifications.
291
292 2008-07-25 amsrefs.dtx 2.06
293
294 -- Modified \BibLabel to typeset numeric labels flush-right
295 instead of flush-left, per AMS house style.
296
297 amrefs.dtx 2.03, 2.04, 2.05: AMS-internal modifications only.
298
299 2007-10-22 amsrefs.dtx 2.03
300
301 -- .sty files now unpack into tex/latex/amsrefs instead of
302 tex/latex/amscls.
303
304 * amsrefs.dtx 2.03:
305 -- Added the msc-links option.
306 -- \nocite no longer produces a back reference with the backrefs
307 option.
308 -- The backrefs option no longer automatically loads hyperref.
309 -- Fixed support for showkeys (not showlabels, as incorrectly
310 stated in the release notes for 2.02) and the showkeys
311 notcite option.
312 -- Modified the bibdiv, bibchapter and bibsection environments
313 to set the page headings correctly for non-AMS document
314 classes.
315 -- For journals with issue numbers but no volumes, the issue
316 number is now treated as a volume number, per AMS house
317 style.
318 -- \cite and related commands can now be used within the fields
319 of a \bib item, for example, note={See also \cite{SokalB1998}}
320
321 * textcmds.dtx 1.06:
322 -- Added \q for symmetry with \qq.
323
324 2006-10-25 amsrefs.dtx 2.02
325
326 -- Updated copyright and license fields.
327 -- Numerous bug fixes.
328
329 * amsrefs.dtx 2.02:
330 -- Fixed bug in copying cross-referenced entries from .ltb files
331 to the .bbl file.
332 -- Fixed disappearing table of contents when used with AMS
333 document classes.
334 -- Enabled xrefs in more fields.
335 -- Fixed spacing problems with \MR. Also be more forgiving if
336 the argument to \MR begins with "MR" or "MR ".
337 -- Added support for showlabels.sty.
338 -- Fixed some bugs in the interaction with hyperref.
339 -- Removed support for the obsolete beta and jpa package options.
340
341 * amsxport.dtx 2.01:
342 -- Fixed bug in sort order of references.
343
344 2004-06-30 amsrefs.dtx 2.0
345
346 * Major rewrite of internals. See changes.pdf for information on
347 the user-visible changes.