4. Citations

Citations in LaTeX are done with the \cite macro or variations of it. The argument of the macro is a citation key which identifies an article or book in either a BibTeX database file or in an explicit thebibliography environment in the document. RefTeX's support for citations helps to select the correct key quickly.

4.1 Creating Citations

In order to create a citation, press C-c [. RefTeX then prompts for a regular expression which will be used to search through the database and present the list of matches to choose from in a selection process similar to that for selecting labels (see section 3.2 Referencing Labels).

The regular expression uses an extended syntax: `&&' defines a logic and for regular expressions. For example `Einstein&&Bose' will match all articles which mention Bose-Einstein condensation, or which are co-authored by Bose and Einstein. When entering the regular expression, you can complete on known citation keys. RefTeX also offers a default when prompting for a regular expression. This default is the word before the cursor or the word before the current `\cite' command. Sometimes this may be a good search key.

RefTeX prefers to use BibTeX database files specified with a \bibliography macro to collect its information. Just like BibTeX, it will search for the specified files in the current directory and along the path given in the environment variable BIBINPUTS. If you do not use BibTeX, but the document contains an explicit thebibliography environment, RefTeX will collect its information from there. Note that in this case the information presented in the selection buffer will just be a copy of relevant \bibitem entries, not the structured listing available with BibTeX database files.

In the selection buffer, the following keys provide special commands. A summary of this information is always available from the selection process by pressing ?.

General

General

? Show a summary of available commands.

0-9,- Prefix argument.

Moving around

Moving around

n Go to next article.

p Go to previous article.

Access to full database entries

Access to full database entries

SPC Show the database entry corresponding to the article at point, in another window. See also the f key.

f Toggle follow mode. When follow mode is active, the other window will always display the full database entry of the current article. This is equivalent to pressing SPC after each cursor motion. With BibTeX entries, follow mode can be rather slow.

Selecting entries and creating the citation

Selecting entries and creating the citation

RET Insert a citation referencing the article at point into the buffer from which the selection process was started.

mouse-2 Clicking with mouse button 2 on a citation will accept it like RET would. See also variable reftex-highlight-selection, 8.11 Miscellaneous.

m Mark the current entry. When one or several entries are marked, pressing a or A accepts all marked entries. Also, RET behaves like the a key.

u Unmark a marked entry.

a Accept all (marked) entries in the selection buffer and create a single \cite macro referring to them.

A Accept all (marked) entries in the selection buffer and create a separate \cite macro for each of it.

TAB Enter a citation key with completion. This may also be a key which does not yet exist.

. Show insertion point in another window. This is the point from where you called reftex-citation.

Exiting

Exiting

q Exit the selection process without inserting a citation into the buffer.

Updating the buffer

Updating the buffer

g Start over with a new regular expression. The full database will be rescanned with the new expression (see also r).

r Refine the current selection with another regular expression. This will not rescan the entire database, but just the already selected entries.

In order to define additional commands for this selection process, the keymap reftex-select-bib-map may be used.

4.2 Citation Styles

The standard LaTeX macro \cite works well with numeric or simple key citations. To deal with the more complex task of author-year citations as used in many natural sciences, a variety of packages has been developed which define derived forms of the \cite macro. RefTeX can be configured to produce these citation macros as well by setting the variable reftex-cite-format. For the most commonly used packages (natbib, harvard, chicago) this may be done from the menu, under Ref->Citation Styles. Since there are usually several macros to create the citations, executing reftex-citation (C-c [) starts by prompting for the correct macro. For the Natbib style, this looks like this:

SELECT A CITATION FORMAT

[^M]   \cite{%l}
[t]    \citet{%l}
[T]    \citet*{%l}
[p]    \citep{%l}
[P]    \citep*{%l}
[e]    \citep[e.g.][]{%l}
[s]    \citep[see][]{%l}
[a]    \citeauthor{%l}
[A]    \citeauthor*{%l}
[y]    \citeyear{%l}

Following the most generic of these packages, natbib, the builtin citation packages always accept the t key for a textual citation (like: Jones et al. (1997) have shown...) as well as the p key for a parenthetical citation (like: As shown earlier (Jones et al, 1997)).

To make one of these styles the default, customize the variable reftex-cite-format or put into `.emacs':

(setq reftex-cite-format 'natbib)

You can also use AUCTeX style files to automatically set the citation style based on the usepackage commands in a given document. See section 6.8.2 Style Files, for information on how to set up the style files correctly.

4.3 Citation Info

When point is idle for more than reftex-idle-time seconds on the argument of a \cite macro, the echo area will display some information about the article cited there. Note that the information is only displayed if the echo area is not occupied by a different message.

RefTeX can also display the \bibitem or BibTeX database entry corresponding to a \cite macro, or all citation locations corresponding to a \bibitem or BibTeX database entry. See section 6. Viewing Cross--References.

4.4 Chapterbib and Bibunits

chapterbib and bibunits are two LaTeX packages which produce multiple bibliographies in a document. This is no problem for RefTeX as long as all bibliographies use the same BibTeX database files. If they do not, it is best to have each document part in a separate file (as it is required for chapterbib anyway). Then RefTeX will still scan the locally relevant databases correctly. If you have multiple bibliographies within a single file, this may or may not be the case.

4.5 Citations outside LaTeX

The command reftex-citation can also be executed outside a LaTeX buffer. This can be useful to reference articles in the mail buffer and other documents. You should not enter reftex-mode for this, just execute the command. The list of BibTeX files will in this case be taken from the variable reftex-default-bibliography. Setting the variable reftex-cite-format to the symbol locally does a decent job of putting all relevant information about a citation directly into the buffer. Here is the lisp code to add the C-c [ binding to the mail buffer. It also provides a local binding for reftex-cite-format.

(add-hook 'mail-setup-hook
          (lambda () (define-key mail-mode-map "\C-c["
                       (lambda () (interactive)
                         (require 'reftex)
                         (let ((reftex-cite-format 'locally))
                           (reftex-citation))))))

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.