This section describes how to use the software. First make sure you have the necessary files in the right place, or have environment variables set appropriately (see section Installation).
Now we describe how to set up your BibTeX bib files.
If you are familiar with BibTeX already you can probably skip
this section.
Using BibTeX, your references are stored in a bib file,
for example myrefs.bib (the .bib suffix is important).
These need not (indeed, should not) be limited to the articles you
are citing in the document you are preparing; BibTeX picks out the
ones you actually cite and only includes those in your bibliography.
A typical entry in a bib file looks like this:
@Book{Peebles:94,
author = {P.~J.~E.~Peebles},
title = "Physical Cosmology",
publisher = "Princeton University Press",
year = 1994,
address = "Princeton, NJ"
}
or like this:
@Article{1997ApJ...485....1M,
author = {Myers, S.~T. and Jonathan E.~Baker and Readhead, A.~C.~S. and
Erik M.~Leitch and Herbig, T.},
title = "Measurements of the Sunyaev-Zeldovich Effect...",
journal = apj,
year = 1997,
month = aug,
volume = 485,
pages = "1--8",
}
Other types include
@Booklet,
@InBook, @InCollection, @InProceedings,
@Manual, @MastersThesis, @PhDThesis,
@Proceedings, @TechReport, and @Unpublished.
The @Misc type is a catch-all which allows you to do the
formatting yourself if necessary. Most of these types should give
correct results for the journals using the bst files included
here for AAS and MNRAS.
The first thing after the { is the cite key, which you use to cite
the reference in your document. Note that author names can have
either first or last name first, and they are separated with and.
Very long lists can be truncated with and others. Natbib's
automatic lettering will get confused if the author last names are
not punctuated consistently (e.g., if some of them have extra braces
as in ADS style and others don't).
Emacs (see section Useful Emacs modes) has a very nice set of commands for automatically
generating a bibliographic entry in a bib file.
BibTeX will complain if it does not know the definition of a string
which is not enclosed in quotes, such as the strings apj and
aug in the example above. References downloaded from ADS will
have "\apj" instead of apj; this tells BibTeX to write
\apj in the bibliographic entry. This is fine for AASTeX macros,
where the \apj command is defined in the style file. But if
you are using a style file which does not define this command, you
will get errors from LaTeX unless you define it yourself.
One way to handle this is to use the journal abbreviation bib
files such as the ones included here, apj-jour.bib or
mn-jour.bib. These contain commands such as
@STRING{apj = "\apj"}
in apj-jour.bib and
@STRING{apj = "ApJ"}
in mn-jour.bib which define the strings if you use a command like
\bibliography{apj-jour,myrefs} or
\bibliography{mn-jour,myrefs} in your document
(see section Preparing the LaTeX Document) to include the bib files. This way
you don't have to change your bib database for different
journals, and you don't have to define a lot of new journal
commands in your LaTeX document. Look at the files to see all
the defined abbreviations. The very short abbreviations such as
"ApJ" for frequently cited journals are included, along with many
others following the IAU convention.
The three-letter month abbreviation strings
and strings for a few mathematics journals are defined in the
bibliography style (bst) files.
First include the natbib style file. For LaTeX 2e,
\documentclass{ ... }
\usepackage{ ... ,natbib}
or for LaTeX 2.09 (required by the journals),
\documentstyle[ ... ,natbib209]{ ... }
Place the natbib package last in your list of packages to make
sure it doesn't get over-written. It works with the AASTeX styles
as well as the emulateapj style, and with the mn
style (mostly, but see section MNRAS style).
Second, somewhere in the preamble (before \begin{document}),
use the command
\citestyle{aa}
This simply insures that natbib gives you citations which look
like (Bester 1998) and not like (Bester, 1998). The aa
stands for Astronomy & Astrophysics, but this citation style
is appropriate for all the journals. (Actually, the code
nat2jour.pl, which prepares files for electronic
submission, produces citations like this regardless of the
\citestyle command, so this does not matter for the
final output.)
Next, at the point where you want the bibliography to appear, use
\bibliographystyle{STYLE}
\bibliography{REFS}
where STYLE is the name of the bibliography style you want to
use (e.g., \bibliographystyle{apj} to use apj.bst --
leave off the .bst suffix). REFS is a list of
bibliography files to use (leave off the .bib). So if you
wanted to use the ApJ journal abbreviations (see section Using String Abbreviations for Journals (optional))
and a database called myrefs.bib,
\bibliography{apj-jour,myrefs}
This loads the journal definitions from apj-jour.bib, so you can
use things like journal = apj in myrefs.bib.
The natbib package defines a number of very useful citation commands
which replace the usual \cite. These are really necessary
in any author-year citation system, where you don't always cite a
reference using the same format for the citation. These commands
and their output are illustrated below. The most frequently used
are \citet (textual cite) and \citep (parenthetical cite).
\cite is equivalent to \citet, but this shouldn't be
used because it is often defined by other style files.
\citet{KEY}
\citep{KEY}
Multiple citations work within a single cite, for example
\citep{KEY1, KEY2, KEY3, KEY4, ...}
The lettering of the citations and references is done automatically.
You can use optional arguments to get text before and after the citation(s):
\citep[hereafter B98]{KEY}
\citep[e.g.,][]{KEY}
\citep[see][p. 68]{KEY}
Any of these can have a * affixed to make a full author list
when "et al." would normally be used, e.g.,
\citet*{KEY}
Note that the nat2jour.pl script takes care of the bizarre
practice of listing three names on the first citation and using
"et al." thereafter, so you don't need to worry about that,
although the intermediate file will come out "wrong".
\citeauthor{KEY}
\citeyear{KEY}
\citeyearpar{KEY}
\citealp and \citealt are the sames as \citep
and \citet, respectively, except that they do not produce
any parentheses at all:
\citealt{KEY}
Finally, \citetext can be used to place arbitrary text
around a citation. Look at the comments in the natbib style
files for more information.
When you process a document for the first time, or when you add citations
to new references, you have to go through four steps. For a file called
foo.tex with a bibliography refs.bib:
latex foo
aux file
bibtex foo
.bbl) file
latex foo
bbl information
latex foo
The .bbl file is a normal-looking LaTeX file containing
the \thebibliography environment; it is inserted into the
document at the point where the \bibliography command is
issued.
If you are producing an article for electronic submission, you can
stop after step #2, run nat2jour.pl (see section Generating a Copy for Electronic Submission) and
then run LaTeX (twice) on the output.
It's not too difficult to automate this process (see section Makefiles) and speed things up.
Your article looks great now, but in the shape it's in as of the
last section, you'll have to use a decidedly low-tech method
of submitting it to the journal: print it out and snail-mail it in!
This is because you cannot include complex style files like
natbib.sty with your submission, and the journals don't
provide bibliographic style files.
(As of AASTeX version 5.0, this is no longer true! You can stop here
and simply submit your tex and bbl files. But the
`minor tweaks' mentioned below won't be performed, so you'll have to
do them by hand. For instance, use the \cite* commands rather
than \cite commands the first time you cite a reference with
three authors, to get all the names.)
Fortunately, there is a Perl script, nat2jour.pl, which
comes to the rescue. It takes the tex and bbl files
you have made (see section Processing LaTeX/BibTeX files) and makes new ones which you
can actually submit. This is accomplished by
\bibitem's with the right format
A few other minor tweaks are also performed; you may notice some
small style errors in the document before processing it.
For input files foo.tex and foo.bbl, invoke
it by typing
nat2jour.pl foo
(make sure it is executable
and in your PATH). By default it will make new output files
foo-aas.tex and foo-aas.bbl, but you can name
them something different by specifying a second argument.
The new files can be processed completely independently of
the natbib sty files, the bst files, and your
bib files. The bibliography is simply pasted in from
the bbl file, so all you need are the tex and
bbl, with the usual one or two passes with latex
to process them.
The code has two options:
-inline
.tex file. The default leaves the bibliography in a separate
.bbl file.
-maxauth
et al. is used;
default is 8. Set to zero for no limit.
-references
thebibliography environment
with \bibitem's, generate a references environment. This
also leaves off the \markcite or \nocite commands. I
found it was necessary for preparing a PASP conference proceeding.
The nat2jour.pl code looks for a \documentstyle
containing "mn". If it finds it, it adds \nocite commands next
to the inlined references; otherwise it adds the AASTeX \markcite
command (unless the -references flag is set).
The code also ensures that three-author papers are cited as Bester, Winters, & Alexander (1998) on the first citation and as Bester et al. (1998) thereafter. This will not be the case in the input files because natbib does not do this. In addition, it truncates long author lists at the right point (8 authors, natbib doesn't do this).
Finally, the code may alter the appearance of the typeset
bibliography, because natbib may redefine the \thebibliography
environment in the input files. The output files will conform to the
other style files (such as AASTeX) you are using.
Note that the script should work on bbl files produced
with any bst bibliography style, as long as it
produces \bibitem commands which exactly follow this format:
\bibitem[{ SHORT-AUTHOR-LIST (YEAR) LONG-AUTHOR-LIST }]{KEY}BIBLIOGRAPHIC-ENTRY-TEXT
The LONG-AUTHOR-LIST may be omitted when it is the same as the
SHORT-AUTHOR-LIST (usually, <3 authors). This is the
"extended natbib" format used by natbib versions 5.3 and later.
The script will become confused in the unlikely event that there are
square brackets in the author lists. The \bibitem entries must
be separated by blank lines.
Go to the first, previous, next, last section, table of contents.