summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/amsrefs/README
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/amsrefs/README')
-rw-r--r--macros/latex/contrib/amsrefs/README347
1 files changed, 347 insertions, 0 deletions
diff --git a/macros/latex/contrib/amsrefs/README b/macros/latex/contrib/amsrefs/README
new file mode 100644
index 0000000000..920bd35056
--- /dev/null
+++ b/macros/latex/contrib/amsrefs/README
@@ -0,0 +1,347 @@
+README for amsrefs 2.14 [2013/03/07]
+
+Copyright 2001-2004, 2007, 2008, 2010-2013 American Mathematical Society.
+
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.3c
+of this license or (at your option) any later version.
+The latest version of this license is in
+ http://www.latex-project.org/lppl.txt
+and version 1.3c or later is part of all distributions of LaTeX
+version 2005/12/01 or later.
+
+This work has the LPPL maintenance status `maintained'.
+
+The Current Maintainer of this work is the American Mathematical
+Society.
+
+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
+
+========================================================================
+ CONTENTS
+I. OVERVIEW
+II. FEATURES
+III. INSTALLATION AND GETTING STARTED
+IV. REMARKS ON THIS RELEASE
+V. CHANGE LOG
+
+========================================================================
+I. OVERVIEW
+
+The amsrefs package supports bibliographies and citations in LaTeX
+documents. The basic citation command remains more or less the same
+as in standard LaTeX (\cite), but a number of additional variations
+address certain known pitfalls or gaps in the standard LaTeX set of
+citation features.
+
+The command for bibliography items is different -- \bib instead of
+\bibitem -- for reasons that will be evident upon further reading in
+the documentation.
+
+A set of BibTeX style files are provided to allow people to extract
+data from .bib files and produce .bbl files in amsrefs format instead
+of conventional \bibitem format.
+
+User documentation is in amsrdoc.pdf and amsrefs.faq.
+
+Technical documentation (including documentation for package writers)
+is in amsrefs.pdf.
+
+========================================================================
+II. FEATURES
+
+-- Preservation of structure.
+
+With BibTeX alone, the structure of a bibitem in a .bib file is lost
+when items are imported into a .bbl file for direct processing by
+LaTeX. With amsrefs, there is no such conversion; LaTeX typesets the
+bibliography directly from the structured data. The greatest
+potential advantage of this is seen when archiving documents in LaTeX
+form or transmitting them to another user (such as a publisher).
+
+-- Deferred formatting.
+
+Since bibliography entries are stored in structured format in the
+LaTeX file and the formatting is under the control of a LaTeX package
+instead of a separate program, the style of the bibliography can be
+changed on demand without re-importing everything from the original
+database(s).
+
+-- More natural data format for titles.
+
+Proper nouns do not need to have braces added to prevent
+capitalization problems.
+
+-- Less ambiguous format for author names.
+
+When author names are given in inverted order (last name first) it is
+possible for LaTeX to unambiguously identify the last name without any
+further markup, even in cases like Saunders Mac Lane (Mac Lane,
+Saunders) versus Stephen H. Lane (Lane, Stephen H.), or Cam Van Tran
+(Tran, Cam Van) versus Bert Van Keulen (Van Keulen, Bert). In BibTeX
+some of these would need to have extra braces added to ensure that the
+surname is accurately distinguished.
+
+-- Author-year citations.
+
+There is integrated support for citations in author-year form.
+
+-- Back-reference support.
+
+Works in conjunction with the hyperref package.
+
+-- Setup requires only LaTeX knowledge.
+
+All bibliography setup can be done in LaTeX; learning another
+programming language (such as, the one used in BibTeX bst files) is
+unnecessary.
+
+-- Self-printable database files.
+
+A LaTeX document that contains only a bibliography in amsrefs forms can
+be used as a database for exporting entries to other documents. And
+because it is a LaTeX document, the database can be printed directly at
+any time simply by running it through LaTeX in the usual way.
+
+-- Self-contained.
+
+In many cases it seems possible to do without BibTeX entirely. For
+example, if the entries are extracted from a single database file that
+is maintained in sorted order, the bibliography can be printed directly
+by LaTeX on the first pass and the citations resolved on the second
+pass.
+
+========================================================================
+III. INSTALLATION AND GETTING STARTED
+
+1. Install the package, referring to install.txt as needed.
+
+2. There are four example files provided:
+
+ cite-xa : Demonstrates an author-year citation scheme. The
+ bibliography is embedded in the .tex file instead of
+ residing in a separate .bbl file.
+
+ cite-xb : Demonstrates usage with more-or-less standard BibTeX
+ methods.
+
+ cite-xs : Shows how the bbl file can be created by LaTeX itself from a
+ suitably presorted ltb file.
+
+ cite-xh : A working hyperref/backrefs example.
+
+3. Run LaTeX on cite-xa.tex. Take a look at the messages that have to
+ do with citations and the bibliography section. Run LaTeX again to
+ resolve the citations and check the output.
+
+4. Run LaTeX on cite-xb.tex. Run BibTeX. Look at the bbl file.
+ Interesting, huh? Run LaTeX twice more to resolve the citations.
+
+5. Run LaTeX on cite-xs.tex and look at the output.
+
+6. Run pdflatex on cite-xh.tex (it is set up to use BibTeX also, like
+ cite-xb).
+
+========================================================================
+IV. REMARKS ON THIS RELEASE
+
+Version 2.12 of amsrefs implements two new features for the biblist
+environment, one new entry type, one new warning, and one bug fix.
+
+New features: The biblist environment now takes an optional argument
+ consisting of an asterisk followed by a brace-delimited set of
+ key-value pairs. The currently supported keys are "labels," which
+ changes the label style of the current biblist, and "prefix,"
+ which adds a prefix to each label. For example, if you are using
+ numeric labels, then
+
+ \begin{biblist}*{prefix={A}}
+
+ will result in items labeled A1, A2, etc., instead of 1, 2, etc.
+
+ Similarly,
+
+ \begin{biblist}*{labels={alphabetic}}
+
+ will switch to alphabetic labels for the current bibliography.
+ Other allowable values are "numeric" and "shortalphabetic."
+
+ The biblist environment already takes a []-delimited optional
+ argument, so if you want to use both, the *-argument comes last:
+
+ \begin{biblist}[\normalsize]*{...}
+
+ NOTE: Use of non-numeric prefixes or of mixed numeric and
+ non-numeric label styles can interfere with the citation sorting
+ and compression features, depending on exactly how you arrange
+ your \cite's. You may need to pass the non-sorted-cites and
+ non-compressed-cites options to amsrefs to get the correct
+ behavior.
+
+New entry type: There is now a webpage entry designed for references
+ to online resources. It takes the following fields: accessdate,
+ author, date, note, subtitle, title, url.
+
+New warning: A common mistake when using non-numeric labels is to
+ place the bibliography items in an order that is incompatible with
+ the labels assigned by amsrefs. This can result in a sequence
+ such as this
+
+ [D] John Doe. ...
+ [DS] John Doe and Jane Smith. ...
+ [D] John Dunn. ...
+
+ where amsrefs does not automatically replace the first and third
+ labels by "D1" and "D2" as it would if they were consecutive.
+ This is because the real error lies in attempting to force the
+ labels into an unordered sequence. Readers are entitled to expect
+ that reference "D2" lies between references "D1" and "DS" in the
+ bibliography just as they are entitled to expect that reference
+ [2] lies between references [1] and [3].
+
+ If amsrefs encounters a situation like this, it will now issue a
+ warning. There are three ways to resolve the problem:
+
+ 1. Rearrange the items in an order that is compatible with the
+ label style you have chosen.
+
+ 2. Choose a different label style that is compatible with the
+ order you have chosen for the items.
+
+ 3. Use the label field to override the automatically-generated
+ label and leave your readers to their own devices.
+
+Bug fix: Spaces are now ignored inside the first argument (the
+ citekey) to \bib. Previously, something like
+
+ \bib{Doe 1998}{...}{...}
+
+ along with
+
+ \cite{Doe 1998}
+
+ would result in a warning that the citation 'Doe1998' was
+ undefined since the space was stripped from the argument to \cite,
+ but not from the first argument to \bib.
+
+========================================================================
+V. CHANGE LOG (REVERSE CHRONOLOGICAL ORDER)
+
+2012-03-07 amsrefs.dtx v2.14
+ -- More thorough patch to \calc@alpha@suffix.
+
+2012-03-06 amsrefs.dtx v2.13
+ -- Patched \calc@alpha@suffix to fix a problem with use of
+ \etalchar in alphabetic labels.
+
+2012-01-15 amsrefs.dtx v2.12
+ -- Added *-optional argument to biblist to allow setting of new
+ per-biblist prefix and labels options.
+ -- Added new webpage entry type.
+ -- Patched \bib to ignore spaces inside the citekey for
+ compatibility with \cite.
+ -- Add a warning if an out-of-order duplicate biblabel stem is
+ detected.
+
+2012-07-26 amsrefs.dtx v2.11
+ -- Minimal support for mixing \bibitem with \bib. This is *not*
+ recommended practice and will not be mentioned in the user
+ documentation, but it is necessary for certain internal AMS
+ applications.
+
+ -- Eliminated the "(to appear in print)" note that \PrintDOI used
+ to add if there was was no volume field.
+
+ -- Added \citeyear to aid in emulating natbib.
+
+ * textcmds.dtx 2.00:
+ -- Replaced most \newcommand's by \providecommand to minimize
+ chances of conflicts with other packages or user definitions.
+
+2012-05-08 amsrefs.dtx 2.10
+ -- patched amsbst.sty to remove unwanted close paren from \PrintEditorsA
+ -- patched \@endbiblist to reset \previous@primary between biblists
+
+2010-08-17 amsrefs.dtx 2.09
+
+ -- Restored support for \citeform that was inadvertently lost
+ somewhere along the way.
+ -- .bst files now unpack into bibtex/bst/amsrefs instead of
+ bibtex/bst/ams
+ -- .bib files now unpack into bibtex/bib/amsrefs instead of
+ bibtex/bib/ams
+
+2010-08-13 amsrefs.dtx 2.08
+
+ -- Updated license to LPPL.
+ -- Patched author-year \BibLabel to support hyperref.
+ -- Added \biblistfont to support easier customization of
+ bibliography font.
+
+2008-07-25 amsrefs.dtx 2.07: AMS-internal modifications.
+
+2008-07-25 amsrefs.dtx 2.06
+
+ -- Modified \BibLabel to typeset numeric labels flush-right
+ instead of flush-left, per AMS house style.
+
+amrefs.dtx 2.03, 2.04, 2.05: AMS-internal modifications only.
+
+2007-10-22 amsrefs.dtx 2.03
+
+ -- .sty files now unpack into tex/latex/amsrefs instead of
+ tex/latex/amscls.
+
+ * amsrefs.dtx 2.03:
+ -- Added the msc-links option.
+ -- \nocite no longer produces a back reference with the backrefs
+ option.
+ -- The backrefs option no longer automatically loads hyperref.
+ -- Fixed support for showkeys (not showlabels, as incorrectly
+ stated in the release notes for 2.02) and the showkeys
+ notcite option.
+ -- Modified the bibdiv, bibchapter and bibsection environments
+ to set the page headings correctly for non-AMS document
+ classes.
+ -- For journals with issue numbers but no volumes, the issue
+ number is now treated as a volume number, per AMS house
+ style.
+ -- \cite and related commands can now be used within the fields
+ of a \bib item, for example, note={See also \cite{SokalB1998}}
+
+ * textcmds.dtx 1.06:
+ -- Added \q for symmetry with \qq.
+
+2006-10-25 amsrefs.dtx 2.02
+
+ -- Updated copyright and license fields.
+ -- Numerous bug fixes.
+
+ * amsrefs.dtx 2.02:
+ -- Fixed bug in copying cross-referenced entries from .ltb files
+ to the .bbl file.
+ -- Fixed disappearing table of contents when used with AMS
+ document classes.
+ -- Enabled xrefs in more fields.
+ -- Fixed spacing problems with \MR. Also be more forgiving if
+ the argument to \MR begins with "MR" or "MR ".
+ -- Added support for showlabels.sty.
+ -- Fixed some bugs in the interaction with hyperref.
+ -- Removed support for the obsolete beta and jpa package options.
+
+ * amsxport.dtx 2.01:
+ -- Fixed bug in sort order of references.
+
+2004-06-30 amsrefs.dtx 2.0
+
+ * Major rewrite of internals. See changes.pdf for information on
+ the user-visible changes.