File: bib-cite.el.html

This minor-mode is used in various TeX modes to display or edit references associated with \cite commands, or matching \ref and \label commands.

New versions of this package (if they exist) may be found at:
  https://people.debian.org/~psg/elisp/bib-cite.el
and in AUCTeX's Git archive at
  https://git.savannah.gnu.org/cgit/auctex.git

Operating Systems:
 Works in unix, DOS and OS/2. Developped under Linux.

AUCTeX users:
 AUCTeX is a super-charged LaTeX mode for emacs. Get it at:

   https://ftp.gnu.org/pub/gnu/auctex/

 WWW users may want to check out the AUCTeX page at
   https://www.gnu.org/software/auctex/

 bib-cite.el is included in the AUCTeX distribution. Therefore, if
 you use AUCTeX and didn't obtained bib-cite.el separately, make sure
 that you are actually using the more recent version.

RefTeX users:
 RefTeX is a package with similar functions to bib-cite.
   http://www.astro.uva.nl/~dominik/Tools/reftex/
 RefTeX is bundled and preinstalled with Emacs since version 20.2.
 It was also bundled with XEmacs 19.16--20.x.

 I suggest that you use RefTeX to help you type-in text as it's functions
 are better suited to this task than bib-cite, and use bib-cite's features
 when you proof-read the text.
 If you wish bib-cite to use RefTeX's reftex-view-crossref command to
 display and find \label's and \cite bibliography entries, set the variable
 bib-cite-use-reftex-view-crossref to t.

MS-DOS users:
 Multifile documents are supported by bib-cite by using etags (TAGS files)
 which contains a bug for MSDOS (at least for emacs 19.27 it does).
 Get the file
   https://people.debian.org/~psg/elisp/bib-cite.etags-bug-report
 to see what patches to make to etags.c to fix it.

Description:
~~~~~~~~~~~
This package is used in various TeX modes to display or edit references associated with \cite commands, or matching \eqref, \ref and \label
commands (so I actually overstep BiBTeX bounds here...).

These are the functions:

   bib-display bib-display-mouse
                          - Display citation, \ref or \label under point
   bib-find bib-find-mouse
                          - Edit citation, \ref or \label under point
   bib-find-next - Find next occurrence of a \ref or \eqref
   bib-make-bibliography - Make BiBTeX file containing only cite keys used.
   bib-apropos - Search BiBTeX source files for keywords.
   bib-etags - Refreshes (or builds) the TAGS files for
                            multi-file documents.
   bib-create-auto-file - Used in bibtex-mode to create cite key
                            completion .el file for AUCTeX.
   bib-highlight-mouse - Highlight \cite, \ref and \label commands in
                            green when the mouse is over them.

About Cite Commands and related functions:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Various flavors of \cite commands are allowed (as long as they contain
 the word cite) and they may optionally have bracketed [] options.
 Bibtex Cross-references are displayed, and @string abbreviations are
 substituted or included.

 The \cite text is found (by emacs) in the bibtex source files listed in the
 \bibliography command. The BiBTeX files can be located in a search path
 defined by an environment variable (typically BIBINPUTS, but you can change
 this).

 All citations used in a buffer can also be listed in a new bibtex buffer by
 using bib-make-bibliography. This is useful to make a bibtex file for a
 document from a large bibtex database. In this case, cross-references are
 included, as well as the @string commands used. The @string abbreviations
 are not substituted.

 The bibtex files can also be searched for entries matching a regular
 expression using bib-apropos.

Usage instructions:
~~~~~~~~~~~~~~~~~~
 bib-display Bound to Mouse-3 when specially highlighted.
               In Hyperbole, bound to the Assist key.
               Bound to \C-c b d

  bib-display will show the bibtex entry or the corresponding label or
  ref commands from anywhere within a document.
   With cursor on the \cite command itslef
       -> display all citations of the cite command from the BiBTeX source.
   With cursor on a particular cite key within the brackets
       -> display that citation's text from the BiBTeX source file(s).

      Example:

      \cite{Wadhams81,Bourke.et.al87,SchneiderBudeus94}
        ^Cursor -> Display-all-citations ^Cursor -> Display-this-citation

   With cursor on a \label command
       -> Display first matching \ref command in the document
   With cursor on a \ref command
       -> Display environment associated with the matching \label command.

  Finding a ref or label within a multi-file document requires a TAGS file,
  which is automatically generated for you. This enables you to then use
  any tags related emacs features.

 bib-find Bound to Mouse-2 when specially highlighted.
               In Hyperbole, bound to the Action key.
               Bound to \C-c b f

   bib-find will select the buffer and move point to the BiBTeX source file
   at the proper citation for a cite command, or move point to anywhere
   within a document for a label or ref command. The ref chosen is the
   first occurrance within a document (using a TAGS file). If point is
   moved within the same buffer, mark is set before the move and a message
   stating so is given. If point is moved to another file, this is done in
   a new window using tag functions.

   The next occurrence of a \ref or \eqref command may be found by invoking
   bib-find-next, usually bound to C-c b n.

   For multi-file documents, you must be using AUCTeX (so that bib-cite can
   find the master file) and all \input and \include commands must be first
   on a line (not preceeded by any non-white text).

 bib-make-bibliography: Bound to \C-c b m

  Extract citations used in the current document from the \bibliography{}
  file(s). Put them into a new suitably-named buffer. In a AUCTeX
  multi-file document, the .aux files are used to find the cite keys (for
  speed). You will be warned if these are out of date.

  This buffer is not saved to a file. It is your job to save it to whatever
  name you wish. Note that AUCTeX has a unique name space for LaTeX and
  BiBTeX files, so you should *not* name the bib file associated with
  example.tex as example.bib! Rather, name it something like
  example-bib.bib.

 bib-apropos: Bound to \C-c b a

  Searches the \bibliography{} file(s) for entries containing a keyword and
  display them in the *help* buffer. You can trim down your search by using
  bib-apropos in the *Help* buffer after the first invocation. the current
  buffer is also searched for keyword matches if it is in bibtex-mode.

  It doesn't display cross-references nor does it substitute or display
  @string commands used. It could easily be added, but it's faster this
  way. Drop me a line if this would be a useful addition.

  If you find yourself entering a cite command and have forgotten which key
  you want, but have entered a few initial characters as in \cite{Gal,
  then invoke bib-apropos. It will take that string (in this case Gal) as
  an initial response to the apropos prompt. You are free to edit it, or
  simply press carriage return.

 bib-etags: Bound to \C-c b e

  Creates a TAGS file for AUCTeX's multi-file document (or refreshes it).
  This is used by bib-find when editing multi-file documents. The TAGS file
  is created automatically, but it isn't refreshed automatically. So if
  bib-find can't find something, try running bib-etags again.

 bib-create-auto-file:

  Use this when editing a BiBTeX buffer to generate the AUCTeX .el file
  which tell emacs about all its cite keys. I've added this command to
  bibtex-mode pull-down menu.

 bib-highlight-mouse: Bound to \C-c b h

  Highlights \cite, \ref and \label commands in green when the mouse is over
  them. By default, a call to this function is added to LaTeX-mode-hook
  (via bib-cite-initialize) if you set bib-highlight-mouse-t to true. But
  you may want to run this command to refresh the highlighting for newly
  edited text.

Installation instructions:
~~~~~~~~~~~~~~~~~~~~~~~~~
 bib-cite is a minor-mode, so you could invoke it in a LaTeX-mode hook.
 e.g. If you are using AUCTeX (https://www.gnu.org/software/auctex/), you
 could use:

  (autoload 'turn-on-bib-cite "bib-cite")
  (add-hook 'LaTeX-mode-hook 'turn-on-bib-cite)

 If you are using Emacs' regular LaTeX-mode, use instead:

  (autoload 'turn-on-bib-cite "bib-cite")
  (add-hook 'latex-mode-hook 'turn-on-bib-cite)

 bib-cite can be used with AUCTeX, or stand-alone. If used with AUCTeX on a
 multi-file document (and AUCTeX's parsing is used), then all \bibliography
 commands in the document will be found and used.
 ---
 The following variable can be unset (like shown) to tell bib-cite to
 not give advice messages about which commands to use to find the next
 occurrence of a search:

   (setq bib-novice nil)
 ---
 If you wish bib-cite to use RefTeX's reftex-view-crossref command to
 display and find \label's and \cite bibliography entries, set the variable
 bib-cite-use-reftex-view-crossref to t:

   (setq bib-cite-use-reftex-view-crossref t)
 ---
 The following variable determines whether we will attempt to highlight
 citation, ref and label commands in green when they are under the
 mouse. When highlighted, the mouse keys work to call bib-display
 (bound to [mouse-3]) and bib-find (bound to [mouse-2]). If you use a
 mode other than LaTeX-mode, you'll want to call bib-highlight-mouse with
 a hook (See how we do this at the end of this file with the add-hook
 command).

   (setq bib-highlight-mouse-t nil)
 ---
 The variable bib-switch-to-buffer-function sets the function used to
 select buffers (if they differ from the original) in bib-cite commands
 bib-make-bibliography, bib-display, bib-find
 You may use switch-to-buffer switch-to-buffer-other-window or
 switch-to-buffer-other-frame.
 ---
 If you use DOS or OS/2, you may have to set the following variable:

   (setq bib-dos-or-os2-variable t)

   if bib-cite.el fails to determine that you are using DOS or OS/2.
 Try C-h v bib-dos-or-os2-variable to see if it needs to be set manually.
 ---
 bib-cite needs to call the etags program with its output file option
 and also with the append option (usually -a).
 I figured that DOS and OS/2 would use "etags /o=" instead of the unix
 variant "etags -o ", but users have reported differently. So while the
 unix notation is used here, you can reset it if you need to like so:

   (setq bib-etags-command "etags /r='/.*\\\\\\(eq\\|page\\|[fvF]\\)ref.*/' /o=")
   (setq bib-etags-append-command
                            "etags /r='/.*\\\\\\(eq\\|page\\|[fvF]\\)ref.*/' /a /o=")
 ---
 For multi-file documents, a TAGS file is generated by etags.
 By default, its name is TAGS. You can change this like so:

   (setq bib-etags-filename "TAGSLaTeX")
 ---
 If your environment variable to find BiBTeX files is not BIBINPUTS, then
 reset it with the following variable (here, assuming it's TEXBIB instead):

   (setq bib-bibtex-env-variable "TEXBIB")

 Note that any directory ending in a double slash will cause bib-cite to
 search recursively through subdirectories for your .bib files. This can
 be slow, so use this judiciously.
 e.g. setenv BIBINPUTS .:/home/psg/LaTeX/bibinputs//
       -> all directories below /home/psg/LaTeX/bibinputs/ will be
          searched.

 If your bibtex setup works but Emacs can't see the environment variable
 correctly (Check C-h v process-environment), then customize the
 variable bib-cite-inputs (e.g. M-x customize-variable bib-cite-imputs)

 ---
 If you do not wish bib-display to substitute @string abbreviations,
 then set the following variable like so:

   (setq bib-substitute-string-in-display nil)
 ---
 Warnings are given when @string abbreviations are not defined in your bib
 files. The exception is for months, usually defined in style files. If you
 use other definitions in styles file (e.g. journals), then you may add them
 to the bib-substitute-string-in-display list variable.

If you find circumstances in which this package fails, please let me know.

Things for me to do in later versions:
- treat @Strings correctly, not just in isolation.
- use kpsewhich -expand-path=$BIBINPUTS' instead of BIBINPUTS.
- jmv@di.uminho.pt (Jose Manuel Valenca) wants:
  - prompt for \cite as well as \label and \ref
    (and use AUCTeXs completion list)
  - implement string concatenation, with #[ \t\n]*STRING_NAME
  - Create new command to substitute @string text in any bibtex buffer.
----------------------------------------------------------------------------

Defined variables (23)

Defined functions (39)

Defined faces (0)