00readme.txt for amsrefs 1.23 [2002-02-28]

See also install.txt and manifest.txt. There is a history of changes at
the end of this file.

The amsrefs package deals with 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 self-evident upon further reading in
the documentation.

A BibTeX style file "amsxport" is provided to allow people to extract
data from .bib files and produce .bbl files in amsrefs format instead of
conventional \bibitem format.

Documentation is in amsrefs.dvi, but please note:

WARNING! If you simply print amsrefs.dvi without restricting the number
of pages, you will get the full documentation, including a printout of
the source code and a lot of technical commentary. To get just the
documentation about using amsrefs, you should print only the first ten
pages or so (try previewing first to decide how far you want to go).

========================================================================
I. FEATURES

---Preservation of structure.

The internal structural information of the bibliography entries is not
lost when they are imported from the database file into the LaTeX
document. This takes on its greatest significance when archiving
documents in LaTeX form or transmitting them to another user (such as a
publisher).

---Deferred formatting.

This means that the style of the bibliography can be changed on demand
without reimporting 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.

========================================================================
II. 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).

========================================================================
III. REMARKS ON THIS RELEASE

A number of functions used by the amsrefs package are implemented as
subordinate packages: inicap, rkeyval, ifoption, textcmds, pcatcode.
The pcatcode package was not part of the beta release in April 2000.

Documents written for the beta release of amsrefs should continue to work
if the `beta' option was used:

  \usepackage[beta,...]{amsrefs}

This is implemented internally simply by switching to amsrbeta.sty and
rkvbeta.sty because the differences under the hood are rather
substantial.

Although the document-level syntax remained mostly the same, a couple of
things should be pointed out:

--- \bib used to accept an optional argument: \bib[...]{key}{type}{...}.
Now the purpose of the optional argument is addressed by a "label" field
instead.

--- \bib* means ``this item is the source for an xref but it should not
itself be printed when processing the bibliography''.

--- \aulist was renamed to \AuthorList for more consistency.

--- Instead of \PrintSeries, author and editor names now use \PrintNames
with some suitable \BibSpec's (firstauthor, middleauthor, etc).

========================================================================
IV. SETTING UP A CUSTOM BIBLIOGRAPHY STYLE

More documentation is needed here, but for now, try running a test
document with and without \usepackage{jeb-bibl}, then compare the
\BibSpec statements in amsrefs.sty with the ones in jeb-bibl.sty to see
how the differences in style are produced. Then send me mail with all
the unanswered questions that remain.
[Michael Downes, tech-support@ams.org]

========================================================================
V. CHANGE LOG

*amsrefs.dtx 1.23 2002-02-28 09:53:52-05

Added a fallback definition for \languagename, otherwise it shows up as
undefined when not using Babel. Changed \cite*, \ocite* to \fullcite,
\fullocite. Added some warnings for \ycites, \ocites, \fullcite,
\fullocite to say that they are not yet implemented.
----------------------------------------
*amsrefs.dtx 1.22 2002-02-27 16:12:11-05

Fixed up the language support; added 'hyphenation' field; some
substantial improvements in the documentation; added \macrotext, \vdef;
implemented the "?" option; changed the *sorted, *citation-order
options; added ISO 8601 parsing of the date field in various entry types
that didnt have it.
----------------------------------------
*amsrefs.dtx 1.19 2002-02-26 14:27:45-05

Patch 1.18 for \extract@initials wasn't good enough: led to spurious
spaces with author-year option. Added support for \bibselect*; added
\othercites cmd as synonym for \nocite.
-----------------------------------------
*pcatcode.dtx 1.03 2002-02-21 10:32:32-05

Changed \@@space to \dl@@space to avoid conflict with
tex/context/base/supp-mis.tex (loaded by \usepackage[pdftex]{graphicx}).

[In principle maybe supp-mis.tex should be changed, since it defines
\@@space in a way that is conceptually different from the conventional
uses of \@@xxx in LaTeX. But practically speaking it is not possible to
go out and retroactively patch all the existing copies already in users'
hands.]

----------------------------------------
*amsrefs.dtx 1.18 2002-02-18 16:54:54-05

Throw in an extra token to keep extract@initials from failing when the
"given name" part consists of only a single letter without even a period.

-----------------------------------------
*amsrefs.dtx 1.17 2002-02-18 10:57:08-05

Added missing \citeauthor, \citeauthory commands. Added some top-level
grouping to properly handle variations in \citesel.

-----------------------------------------
*amsrefs.dtx 1.16 2002-02-18 08:30:30-05

ISBN wasn't working properly because I had left the changes to make it a
repeatable field only half done. Added a definition of \ISBNList and
changed the bib specs to use it.

-----------------------------------------
*amsrefs.dtx 1.15 2002-01-24 17:16:55-05

Fixed up printing of undefined cites in the author-year scenario.
And CiteNames processing. (\ocite wasn't working.)
