I am not the author of this file and am only putting it online
because, to my knowledge, it is not available anywhere else
anymore and I find it a very valuable reference. I
wish to acknowledge here the work of its author Stefan Schoef. I
haven't been able to find out who the current maintainer of the
BibTex-Mode for GNU emacs is, but am willing to withdraw this text
or add any copyright notice that would be deemed relevant.
Please note: You should be sure, that you know how to correctly
report bugs, before preparing a bug report (see section 'Bugs' in
Emacs Manual). You also should have browsed the list of frequently
asked questions for an useful answer to your problem (see section
Frequently Asked Questions).
To report bugs, use the M-x bibtex-submit-bug-report command.
This sets up a mail buffer with version information already included.
Please make sure that the buggy behavior doesn't stem from other lisp
libraries you loaded prior to 'bibtex.el'.
Make sure to include a short, but expressive example of a
BibTeX buffer indicating the arising problem. Please describe exactly
what triggered the bug, i.e.
what the buffer looks like,
what you type,
where the cursor is at that time,
what you expect to happen,
and what in fact does happen.
If you want to send patches, you're welcome, but please get first
the latest beta release of 'bibtex.el' (see section
Getting New Beta Releases)
and (after having assured that the bug is not already fixed) send
patches against this newest beta version.
From 'http://www.ida.ing.tu-bs.de/people/dirk/bibtex/index.html'
you can always get the newest beta test release of BibTeX mode. Besides the
code, here is always contained a list of user-visible changes compared to
the next prior beta release and compared to the version of BibTeX mode
shipped with the newest GNU Emacs release.
If you want to be announced on new beta releases automatically, please
mail to 'Dirk Herrmann <D.Herrmann@tu-bs.de>'.
If you want to use the version of BibTeX mode that comes with GNU
Emacs, you are on the lucky side: It is already installed and it will be
used if you load a file with the extension '.bib'.
Since for some reasons, all libraries contained in the GNU Emacs
standard distribution shouldn't contain any version information, it is
not easy to tell if the version of BibTeX mode you use then is the
same version (or even newer) as the version of BibTeX mode described
in this manual. For a relationship between GNU Emacs versions and
BibTeX mode features, please refer to section
History of Changes to BibTeX Mode.
If you are brave, you can get the newest beta release of BibTeX mode
(see section Getting New Beta Releases)
and install it.
In this case, you have to byte-compile (see section 'Byte Compilation' in Emacs Lisp Manual) the obtained beta version of 'bibtex.el'
and put the file 'bibtex.elc' somewhere in your load path, so that
it is loaded prior to the standard version of 'bibtex.el' shipped
with GNU Emacs. For details see section 'Lisp Libraries' in
Emacs Manual.
In this chapter the basic concepts for editing a BibTeX buffer with
Emacs BibTeX mode are described. If you enter a file with the extension
'.bib' BibTeX mode is automatically loaded. This mode
provides you with several useful functions to ease your work on the
BibTeX database. Of course, you can edit the buffer manually as in
normal text mode, but usually you will want the more specific functions
of BibTeX mode to support you. Entry to BibTeX mode calls the functions
in bibtex-mode-hook.
While editing a BibTeX buffer, you either have to insert new
reference entries, to delete existing entries, or to modify an existing
entry. Inserting a new entry is done by using an entry template
appropriate for the type of the entry, manipulating existing entries is
done by moving around in the entry, by deleting and inserting fields,
and by changing field contents.
The most often used editing operation on your BibTeX buffers will
normally be to insert new reference entries for a paper or book not
already in the BibTeX database. BibTeX mode assists you by
providing for each reference entry type defined by the BibTeX
program an appropriate template, which contains all required and
optional fields for this entry type. You can control the appearance of
this template by using many variables, all described in section
Controlling Template Layout.
To insert a new template, you move the cursor with the normal cursor
movement functions of Emacs (see section 'Moving Point' in Emacs Manual)
to the position where you want the entry to appear and call one
of the entry insertion functions. If you call an entry insertion
function with the point inside another reference entry, the new entry
template is inserted after that entry. After the new reference entry
template has been inserted the functions in bibtex-add-entry-hook
are called.
There are three possibilities to insert new reference templates. You can
use the entries of the pull-down or pop-up menu 'Entry-Types',
where for each reference type known to BibTeX an appropriate entry
resides. Alternatively, you can use the command bibtex-entry,
which is normally bound to C-c C-b. After having typed this
command you can enter with completion (see section 'Completion' in
Emacs Manual) in the minibuffer the type of the required reference
entry. A third possibility is to use a direct command to insert the new
reference entry. For each possible entry type an appropriate command is
available. All these commands are bound to a key with the prefix
C-c C-e. The third key depends on the reference type you want to
insert and is mnemonically related to the reference type. The general
rule for these keys is that often used reference types are on control
keys (such that you can enter the whole command without releasing the
control key at all), moderately used types are entered using lowercase
letters, seldom used reference types are on uppercase letters, and very
rarely used types are on meta keys. The exact key sequences and command
names are given in the table below.
C-c C-e C-a
bibtex-Article
C-c C-e C-b
bibtex-InBook
(an alternative for this is C-c C-e I)
C-c C-e b
bibtex-Book
C-c C-e B
bibtex-Booklet
C-c C-e C-c
bibtex-InCollection
(an alternative for this is C-c C-e i)
C-c C-e C-m
bibtex-Manual
C-c C-e m
bibtex-MastersThesis
C-c C-e M
bibtex-Misc
C-c C-e C-p
bibtex-InProceedings
(an alternative for this is C-c C-e C-i)
Of course you can use the normal Emacs movement commands (see section
'Moving Point' in Emacs Manual) to move around in BibTeX reference
entries. Another possibility is however to use some special functions
provided by BibTeX mode to jump to the beginning and the end of the
reference entry and to move to the text part of the entry fields.
To jump to the start of the BibTeX entry use the command
bibtex-beginning-of-entry, which is normally bound
to M-C-a. To jump to the entry's end, please use
bibtex-end-of-entry, which is normally bound to M-C-e.
To position point at the right end of the current field's text part you can
use bibtex-find-text, normally bound to TAB. If you give
a prefix argument to this command, point goes to the left instead. The
command bibtex-next-field (normally bound to linefeed (LFD)
which you may have to enter as C-j) is used to jump to the
following field's right end. Again, you can give a prefix argument to
jump to the left end instead. Thus, you can enter the contents of the
whole reference entry by entering a field's contents, thereafter typing
LFD, entering the next field's contents, and so on.
If you enter the command bibtex-reposition-window (normally bound
to M-C-l) with point inside a BibTeX entry, the window gets
scrolled such that all of the entry is visible (if it doesn't contain
more lines than the screen height, of course).
As you may already have noticed, all optional fields in the reference
entry template are prefixed by 'OPT' and some field names are
prefixed by 'ALT'. How to get rid of these prefixes and what to do
with fields you don't need (and other things) are covered in this section.
Normally, all fields in the generated reference entry template are
delimited by double-quotes or braces. Sometimes, BibTeX requires that
a field text isn't delimited, for instance if it is a string (say an
abbreviation for a month or journal name). Sometimes you may want to
have the delimiters explicitly removed, e.g. for numbers (as the
contents of the 'year' field).
To get rid of the delimiters of the current field, you can enter the
command bibtex-remove-delimiters, which is normally bound to
C-c ", C-c {, and C-c }.
BibTeX mode prefixes all optional fields with 'OPT' and all
alternative fields with 'ALT' (you need at least one of the fields
marked with 'ALT', but the others are optional). The BibTeX
program will not recognize a prefixed field and treat it as a comment,
thus if you want an optional or alternative field inside your reference
you have to remove the prefix. You can use the command
bibtex-remove-OPT-or-ALT for this, which normally is bound to
C-c C-o.
Instead of removing 'OPT' and 'ALT' prefixes and unnecessary
delimiters one by one, you can use the command bibtex-clean-entry
(normally bound to C-c C-c) to let BibTeX mode do the work for
you. When you enter this command, all prefixes are deleted from all
field names with non-empty contents and delimiters around pure numerical
fields are removed. The exact action bibtex-clean-entry performs
depends on the contents of the variable bibtex-entry-format (see
section Advanced Entry Cleaning for
details). After cleaning the functions inside bibtex-clean-entry-hook
are called with point inside the cleaned entry.
If you have typed something completely wrong as a field's text, you can
clear the field completely by using the command bibtex-empty-field,
which is normally bound to C-c C-d.
If you want to have an additional field in the current entry (e.g. you
want a 'comment' field for just the current entry or you want to
reinsert a previously removed optional field) you can use the function
bibtex-make-field (normally bound to C-c C-f) to insert an
empty field after the current field. The field name may be entered with
completion using the minibuffer. Object to completion are all fields
defined for the current entry. If you want to add a specific field to
every reference entry, you should consider using the appropriate
variables instead (see section Controlling
Template Layout).
If you don't need a field anymore (say you had a field as 'remark =
{attention: pages missing}' in your reference entry and you have just
completed it), you can kill the entire field by the command
bibtex-kill-field (normally bound to C-c C-k).
You can reinsert the same field and its contents in another place (even
in another BibTeX buffer) by using the command bibtex-yank,
which is normally bound to C-c C-y.
You can get earlier killed fields by entering the command
bibtex-yank-pop (normally bound to C-c M-y). Both,
bibtex-yank and bibtex-yank-pop can get a numerical
argument n to determine the n-th recent kill.
Finally, you can use the function bibtex-copy-field-as-kill to
copy the current field to the kill ring without actually deleting it.
This function is normally bound to C-c M-k.
The variable bibtex-field-kill-ring-max bounds the size of the
kill ring used for fields. It defaults to 20.
If you want to get rid of a complete entry, you can use the command
bibtex-kill-entry, normally bound to C-c C-w. Note that any
comments outside of entries are treated as part of the preceding entry,
thus they are killed together with the entry. You can paste killed
entries back at another place (even in another file) by using the
command bibtex-yank (normally bound to C-c C-y). The entry
is normally yanked before the current entry (except when point is at end
of buffer).
You can get earlier killed entries by entering the command
bibtex-yank-pop (normally bound to C-c M-y). Both,
bibtex-yank and bibtex-yank-pop can get a numerical
argument n to determine the n-th recent kill.
You may have noticed that the yank commands are the same as for yanking
fields. This is intended to provide you with a unique interface for
yanking. Yanking always acts on the kill ring which was affected by the
last kill command.
Finally, you can use the function bibtex-copy-entry-as-kill to
copy the current entire reference entry to the kill ring without actually
deleting it. This function is normally bound to C-c M-w.
The variable bibtex-entry-kill-ring-max bounds the size of the
kill ring used for fields. It defaults to 20.
You can use these functions also to cut, copy, and paste entries between
different BibTeX buffers.
If you enter the command bibtex-mark-entry (normally bound to
M-C-h) with point inside a BibTeX entry, the whole entry gets
marked (i.e., mark is placed at beginning of entry, point at its end).
Normally, you won't need this function and use directly something as
bibtex-kill-entry (see section
Killing and Yanking Reference Entries.), bibtex-copy-entry-as-kill
(see section Killing and Yanking Reference
Entries.), or bibtex-narrow-to-entry (see section
Changing the Visible Portion of the Buffer).
You can get information on the current field's purpose (which may depend
on the containing entry's type as well) by entering the command
bibtex-print-help-message, which is normally bound to C-c ?.
If the variable bibtex-help-message is non-nil (which is the
default), you get this information as well, whenever you call the
command bibtex-find-text or bibtex-next-field.
If for some reason the fields in the current entry aren't aligned
nicely, you can use the command bibtex-fill-entry (normally bound
to C-c C-q) to align the entry's contents nicely.
This function changes the entry's layout, such that each field starts on
a separate line. Field names appear in column bibtex-field-indentation,
field texts start in column bibtex-text-indentation. Continuation
lines start in column bibtex-contline-indentation. If
bibtex-align-at-equal-sign is non-nil, equal signs are
aligned as well. The variable bibtex-entry-offset is added
to all column numbers.
If you type one of the commands to get a new reference entry template
(see section Inserting Entry Templates),
you get a bunch of required, alternative, and optional fields, depending
on the chosen reference type. There are various variables to control the
name and kind of fields, to control the initial field contents, to control
field alignment, and to control other style options.
By various variables you can determine which fields appear in your
reference entry templates (and in which order). These variables are
described in this section.
The standard fields contained in each reference entry template as well as
the purpose comments (see section Getting
Information about a Field's Purpose) and the initial field contents
are defined by the variable bibtex-entry-field-alist. Normally,
you don't have to cope with this variable, since almost everything you
will change in template appearance is controlled by the other variables
in this section. However, if you want to do something really strange,
you may have to cope with this variable, hence it is described here.
This variable is an alist (see section 'Association List Type' in
Emacs Lisp Manual) with an entry for each possible reference type.
Each item of the alist is a list of the form (ENTRY-NAME (REQUIRED
OPTIONAL) (CROSSREF-REQUIRED CROSSREF-OPTIONAL)). ENTRY-NAME
is the name of the reference entry (say "Article"). In case of absence of a
'crossref' field, REQUIRED contains the required fields,
OPTIONAL the optional fields. If a 'crossref' field is
present, CROSSREF-REQUIRED and CROSSREF-OPTIONAL contain
the required and optional fields, respectively. If the
(CROSSREF-REQUIRED CROSSREF-OPTIONAL) pair is missing the
(REQUIRED OPTIONAL) pair is used for all entries of type
ENTRY-NAME.
Each of the REQUIRED, OPTIONAL, CROSSREF-REQUIRED,
and CROSSREF-OPTIONAL fields has the same structure. It is a
list, where each item has the form (FIELD-NAME COMMENT-STRING
INIT ALTERNATIVE-FLAG), where everything but FIELD-NAME
may be omitted. FIELD-NAME is the field's name,
COMMENT-STRING is the comment to appear in the echo
area when the command bibtex-print-help-message (see section
Getting Information about a Field's Purpose)
is invoked, INIT is either the initial content of the field or a
function, which is called to determine the initial content of the field,
and ALTERNATIVE-FLAG (either nil or t) marks if the
field is an alternative. ALTERNATIVE-FLAG may be t only in
the REQUIRED or CROSSREF-REQUIRED lists.
If you want to change this variable, the best idea might be to get the
source code of BibTeX mode from file 'bibtex.el', copy this
variable's definition to your '.emacs' file, change it to a
setq statement (see section 'Setting Variables' in Emacs
Lisp Manual), and modify the variable's contents.
You can determine if a reference entry shall have a 'crossref'
field by using the variable bibtex-include-OPTcrossref. This
variable is a list of strings, where each string must correspond to the
type of a reference entry as contained in the first element of the lists
in bibtex-entry-field-alist (see section
Definition of Entry Contents for each
Reference Type). Each listed reference type will have a 'crossref'
field and the other fields are chosen according to the (CROSSREF-REQUIRED
CROSSREF-OPTIONAL) part in bibtex-entry-field-alist.
If you want to include a 'key' field in all of your reference entry
templates, you can set the variable bibtex-include-OPTkey to
t. If you want a specific string as the initial field contents,
you can use a different value: either the string itself or the name of a
function, which is called to produce the initial string.
If you want additional fields in all reference entry templates, as e.g.
an 'annote' or 'abstract' field, you can use the variable
bibtex-user-optional-fields for this purpose. This variable is a
list of lists with the same format as the OPTIONAL and
CROSSREF-OPTIONAL fields in bibtex-entry-field-alist
(see section Definition of Entry Contents
for each Reference Type), thus each item has the form
(FIELD-NAME COMMENT-STRING INIT). Again, FIELD-NAME is the
name of the field, COMMENT-STRING the comment to appear in the
echo area on entering the field, and INIT is a string used as the
field's initial contents or the name of a function, which shall be
called to produce the initial string. For instance you can set INIT
to current-time-string to get the current date and time or
user-full-name to get the name of the entry's creator.
To resemble the behavior of older versions of BibTeX mode, this
variable defaults to include an empty 'annote' field in all
reference entry templates.
To control how the fields are aligned in the generated reference entry
templates, BibTeX mode provides three variables. With the two numerical
variables bibtex-field-indentation, bibtex-text-indentation,
and bibtex-contline-indentation you can determine the starting
column for field names, field texts, and continuation lines for fields,
respectively. The default value for bibtex-field-indentation is 2.
The default values for bibtex-text-indentation and
bibtex-contline-indentation are 17 and 18, respectively,
such that the longest standard field (organization) fits
nicely into the reference entry template. With the variable
bibtex-entry-offset you can give an additional
amount of columns the whole entry is indented.
With the boolean user option bibtex-align-at-equal-sign you
control if the equal signs of all fields are placed in the same column.
It defaults to nil, resembling the behavior of older BibTeX
mode versions.
There are three additional variables to control the layout of the
reference entry templates. The variable bibtex-field-delimiters
should be set to 'braces or 'double-quotes, depending on
what kind of delimiters you want to have for the generated fields. The
default is 'braces, since in many languages the double-quote sign
has a special meaning to LaTeX and may thus be used inside the fields
itself. This variable is buffer local (see section 'Locals' in
Emacs Manual).
The variable bibtex-entry-delimiters should be set to
'braces or 'parentheses, depending what kind of
delimiters you want to have for the generated entries. The default is
'braces. This variable is buffer local (see section 'Locals'
in Emacs Manual). If you set it to 'parentheses, BibTeX
mode might be able to do more useful parsing. For instance, an entry as
@Article{key,
author = {John Doe},
title = {My Life},
year = {1969},
journal = {Transactions on Unknown Problems}},
pages = {815-4711}
}
will cause both, Emacs BibTeX mode and the BibTeX program as well to think
the entry ends with the second closing brace after 'Problems' and
treat the 'pages' line as comment residing outside of all entries.
If you use parentheses, an error is signalled on validating this entry.
The boolean user option bibtex-comma-after-last-field determines,
if after the last field of the reference entry template a comma is generated
or not. It defaults to nil, resembling the behavior of older BibTeX
mode versions.
In this chapter, the more sophisticated editing features of BibTeX
Mode are described. All topics described in this chapter are related to
input of new reference entries and modification of existing ones. Other
commands, which are related to operating on bunches of reference
entries, are described in the following chapter (see section Operating on Entry Groups).
If you are already comfortable with the basic methods to edit
reference entries as described in the last chapter (see section
Basic Editing Concepts), you can
learn now new comfortable ways to perform your tasks.
If you want to maintain your BibTeX database in sorted order,
BibTeX mode can assist you. You can set the variable
bibtex-maintain-sorted-entries to t (it defaults to
nil) and BibTeX mode will try to keep all entries in sorted
order. This variable is buffer local (see section 'Locals' in
Emacs Manual).
By this, not only the buffer is kept in nice order, allowing you to
quickly find some entries, but there are additional benefits. If you
have bibtex-maintain-sorted-entries set to t, BibTeX
mode can easily detect, if you want to enter an entry with a duplicate
key into your database. You can enter the key of the new reference entry
using the minibuffer with completion (see section 'Completion' in
Emacs Manual). The key completion feature for 'crossref'
fields (see section Completing Prefixes
of Keys) and the inheritance of 'booktitle' fields from
crossreferenced entries (see section Inherit
'booktitle' from a Crossreferenced Entry) will only work for
sorted buffers.
If you want to set bibtex-maintain-sorted-entries to t,
it is required that all entries of the buffer are parsable by BibTeX mode
(function bibtex-validate (see section
Checking if Entries are Parsable)
should signal no errors). Further, the buffer must be already in
sorted order (use bibtex-sort-buffer, see section
Sort a Parsable Buffer).
In addition to the variable bibtex-maintain-sorted-entries, there
is the boolean user option bibtex-sort-ignore-string-entries, which
can be used to tell BibTeX mode not to try to keep '@String' entries
sorted. This variable is buffer local (see section 'Locals' in
Emacs Manual). It is recommended to put all '@String' entries
at the start of the buffer (in order to get the best results for the function
bibtex-complete-string, see section
Completing Prefixes of Strings), hence the default value for
bibtex-sort-ignore-string-entries is t. Further, if you
set this variable to nil, string labels are object to key completion
(see section Completing Prefixes of Keys), too, what is normally not what you want (use string completion (see section
Completing Prefixes of Strings),
if you want to complete strings).
Now, whenever you call one of the functions to insert entry templates
(see section Inserting Entry Templates),
you are asked to enter the key of the new entry in the minibuffer. Here,
you can use completion commands (see section 'Completion' in
Emacs Manual). Object to completion are all keys defined by
reference entry headers and 'crossref' fields in the current
buffer. After having read the reference entry key, BibTeX mode inserts
the new entry in the appropriate place and signals an error if a duplicate
key was used. You can now enter the reference entry as you normally would,
but if you change the key manually after BibTeX mode has inserted it in the
BibTeX database, you must use bibtex-clean-entry (see section
Cleaning Entries) to register
the new key.
In order for BibTeX mode to do its work, it must know the reference
keys defined in the current buffer. For this, from time to time it
parses all BibTeX buffers automatically. The first call to the parse
function is done at entry to BibTeX mode and subsequent calls are
done every bibtex-parse-keys-timeout seconds, for BibTeX
buffers changed after the last parsing. The automatic calls are
immediately abborted, if you type a key, so you will not be hindered in
doing your normal work. Parsing of the whole buffer is only necessary if
you modify keys manually or if you delete 'crossref' fields or
complete reference entries. If you enter all new reference entries in an
appropriate way and register them with bibtex-clean-entry,
BibTeX mode should have a very good idea what keys are defined in the
buffer, even if you abort the parse function very frequently. However,
if BibTeX mode never had the chance to complete the parsing and you
call a function which needs to know the keys (as a function to insert a
new entry template or as the command bibtex-complete-key), it
forces a non-abortable parsing of the buffer. Only one non-abortable
parsing will at most take place in every buffer.
You always learned about the basic benefits of the command
bibtex-clean-entry in section
Cleaning Entries. This command can remove 'OPT' and 'ALT'
prefixes from used fields and it removes delimiters from pure numerical
fields. In addition, it does various other useful formatting actions,
most depending on the contents of the variable bibtex-entry-format.
This variable is a list of symbols, the value nil, which means to
do no formatting at all, or the value t, which has the meaning to
do all possible formatting. The defined symbols and the corresponding
actions are described in the menu below.
What bibtex-clean-entry always does, is to check if at least one
of the alternative fields is non-empty (if there are alternative fields
at all) and if all required fields are non-empty. The number and kind of
required fields may depend on whether the 'crossref' field is empty
or not. It may be that you asked BibTeX mode to provide a reference
entry template with a `crossref' field (see section
Inclusion of 'crossref' fields),
but that you leave it empty for a particular entry. This situation is
handled correctly by BibTeX mode, i.e. the missing required fields
are detected even though they are prefixed with 'OPT'. If you
really want to leave for some reasons one of the mandatory fields empty,
you have to kill it explicitly, then bibtex-clean-entry won't
signal an error (but the BibTeX program probably will).
In addition, if you call bibtex-clean-entry on a reference entry
with an empty reference key or if you call bibtex-clean-entry
with an argument (usually by C-u C-c C-c), BibTeX mode
automatically calculates a reference entry key (see section
Automatic Reference Key Generation).
After cleaning the functions inside bibtex-clean-entry-hook are
called with point inside the cleaned entry.
If bibtex-entry-format contains the value opts-or-alts
or is t, bibtex-clean-entry removes 'OPT' and
'ALT' prefixes from all used (i.e. nonempty) optional and alternative
fields and it removes unused (i.e. empty) optional and alternative fields at
all.
Since the constant opts-or-alts is contained in the default value
of bibtex-entry-format, this is one of the default actions of
bibtex-clean-entry. If you remove this constant, you have to
remove prefixes and unused fields manually (see section
Removing 'OPT' or 'ALT'
Prefixes and see section Killing and
Yanking Fields).
If bibtex-entry-format contains the value numerical-fields
or is t, bibtex-clean-entry removes delimiters (braces and
double-quotes) around fields with pure numerical contents (as normally
the 'year' field).
Since the constant numerical-fields is contained in the default
value of bibtex-entry-format, this is one of the default actions
of bibtex-clean-entry. If you remove this constant, you must
remove delimiters around fields with pure numerical contents manually,
if you want to (see section Delete Delimiters
around Numerical Fields).
If bibtex-entry-format contains the value page-dashes
or is t, bibtex-clean-entry change double dashes in
'page' fields to single page dashes. It is remarked in
btxdoc.tex that the standard styles convert a single dash in
'page' fields to a double dash as used in TeX in order to make
it easier to maintain Scribe-compatible databases. Thus, if you
want to maintain Scribe-compatible databases, you can include
page-dashes into bibtex-entry-format and
bibtex-clean-entry will convert any mistakenly typed double
dashes for you.
The constant page-dashes isn't contained in the default
value of bibtex-entry-format, thus by default
bibtex-clean-entry leaves dashes as they are.
If bibtex-entry-format contains the value inherit-booktitle
or is t, bibtex-clean-entry tries to get the contents for
an empty 'booktitle' field from the 'title' field of the
crossreferenced entry, if the 'crossref' field of the cleaned entry
contains the key of a valid reference entry.
Since this feature will work only for sorted buffers (and if the variable
bibtex-maintain-sorted-entries is t), the default value
of bibtex-entry-format doesn't contain inherit-booktitle.
However, if you work on sorted buffers, you can spare some typing by this
feature, hence in this case I suggest to put the value
inherit-booktitle into bibtex-entry-format.
If bibtex-entry-format contains the value realign or is
t, bibtex-clean-entry realigns the whole reference entry
as if you had entered the command bibtex-fill-entry manually
(see section Nicely Aligning Reference
Entries).
Normally, if the reference entry template is generated by BibTeX
mode, the entry should be already aligned nicely, hence on default
bibtex-entry-format doesn't contain realign. However, if
you often get entries from other sources, just paste them into your
BibTeX buffer, and modify them with BibTeX mode, you should consider
putting the value realign into bibtex-entry-format.
If bibtex-entry-format contains the value last-comma
or is t, bibtex-clean-entry adds or deletes a comma
after the last field in the entry, depending on the value of
bibtex-comma-after-last-field (see section
Controlling Other Style Options).
Normally, if the reference entry template is generated by BibTeX
mode, the entry should already have or have not a comma after the
last field, just as you required by the value of
bibtex-comma-after-last-field. Hence, on default
bibtex-entry-format doesn't contain last-comma.
However, if you often get entries from other sources, just paste
them into your BibTeX buffer, and modify them with BibTeX mode,
you should consider putting the value last-comma into
bibtex-entry-format.
If bibtex-entry-format contains the value delimiters
or is t, bibtex-clean-entry changes field delimiters
according to the value of bibtex-field-delimiters (see section
Controlling Other Style Options).
Normally, if the reference entry template is generated by BibTeX
mode, the fields should already be delimited by the kind of delimiters
you required by the value of bibtex-field-delimiters. Hence, on
default bibtex-entry-format doesn't contain delimiters.
However, if you often get entries from other sources, just paste them
into your BibTeX buffer, and modify them with BibTeX mode, you should
consider putting the value delimiters into
bibtex-entry-format.
If bibtex-entry-format contains the value unify-case
or is t, bibtex-clean-entry changes the case of the
entry type name and field names according to the case used in
bibtex-entry-field-alist (see section
Definition of Entry Contents for each Reference Type).
Normally, if the reference entry template is generated by BibTeX
mode, the fields should already have the case as in
bibtex-entry-field-alist. Hence, on default
bibtex-entry-format doesn't contain unify-case.
However, if you often get entries from other sources, just paste
them into your BibTeX buffer, and modify them with BibTeX mode,
you should consider putting the value unify-case into
bibtex-entry-format.
If bibtex-clean-entry is called with a prefix argument or on a
reference entry with an empty key (see section
Advanced Entry Cleaning), BibTeX mode automatically calculates a reference
entry key for this entry and inserts it in the appropriate place. If you have
set bibtex-autokey-before-presentation-hook to a non-nil value, it
must have been set to a function taking one argument. This function is
called with the automatically generated key as its argument and must
return the key (as a string) which is actually to be used. Further, if
you have set bibtex-autokey-edit-before-use to a non-nil value
(the default), the achieved key is prior to insertion offered in the
minibuffer for editing by the user.
The reference key is calculated from the contents of various fields in
the reference entry. It may contain a constant prefix, a name part,
derived from the 'author' or 'editor' field, a year part,
derived from the 'year' field, and a title part, derived from the
'title' field.
It is possible to convert special TeX commands as e.g. for language
specific characters to standard ASCII strings or even to replace
complete character strings with abbreviations. The exact behavior of the
generation algorithm can be controlled by various user options, which
are described in the following sections.
You can give a unique prefix for all generated keys in the variable
bibtex-autokey-prefix-string. The contents of this variable are
copied verbatim to the beginning of the key string.
There are several user options which control, how the name part of the
key string is built. Base for the name part are the contents of the
'author' field or, if this is missing, of the 'editor'
field. The used field is referenced to in the following as the name field.
You can use the variable bibtex-autokey-name-change-strings
to replace specific strings (e.g. TeX commands) by other strings.
This variable is an alist (see section 'Association List Type' in
Emacs Lisp Manual) of pairs of the form (OLD-REGEXP NEW-STRING).
You can use any kind of regular expressions defined by Emacs (see section
'Regexps' in Emacs Manual) for OLD-REGEXP, but you should
pay attention to the fact that case in OLD-REGEXP is significant.
You should further regard that all pairs are tried in the order in which
they appear in bibtex-autokey-name-change-strings, hence you must
avoid infinite loops. This variable defaults to the value of
bibtex-autokey-transcriptions, which causes BibTeX mode
to replace TeX commands for foreign language special characters and
accented characters to their corresponding ASCII transcription. However,
this variable operates on the whole name field. Thus you can use it, to
change e.g. every occurence of 'John Smith' to 'Jsmith'
and 'Carl Smith' to 'Csmith', such that the finally
generated keys will distinguish these persons.
You can control how many persons from the name field should be used by
the variable bibtex-autokey-names. It may be set to a number,
giving the maximum number of names to use from the name field, or it may
be set to anything else (say nil), which tells BibTeX mode to
use all names. If the numer of names doesn't exceed
bibtex-autokey-names + bibtex-autokey-names-stretch
then all names are used. Only the 'Last' name part
(see btxdoc.tex) of each person is used.
The variable bibtex-autokey-name-length can be set to the maximum
number of characters, which shall be used from each name. However, a
word is aborted only after a consonant or at its end. You can set
bibtex-autokey-name-length to anything but a number (e.g.
nil) to use an unlimited number of characters.
Unless the variable bibtex-autokey-preserve-case is non-nil, the
name parts for all persons are converted to lowercase letters. Now these
parts are concatenated using the value of bibtex-autokey-name-separator
(a string) between any two names. If not all names could be used in the name
part, the contents of bibtex-autokey-additional-names are appended.
By these rules, the name part of the whole key has been built.
The year part of the key is built by taking the
bibtex-autokey-year-length rightmost characters
from the contents of the 'year' field. Useful values
are 2 and 4.
If there is no 'year' field in the current entry, but it has a
valid 'crossref' field with the crossreferenced entry residing in
the current buffer, the 'year' field of the crossreferenced entry
is used, if the variable bibtex-autokey-year-use-crossref-entry
is non-nil. Please note: this feature is available only, if user
option bibtex-maintain-sorted-entries (see section
Maintaining Alphabetic Order of Entries)
is non-nil.
To build the title part of the key, first the whole title string is changed
according to the variable bibtex-autokey-titleword-change-strings.
You can use it to replace specific strings (e.g. TeX commands) by other
strings. This variable is an alist (see section 'Association List Type' in
Emacs Lisp Manual) of pairs of the form (OLD-REGEXP NEW-STRING).
You can use any kind of regular expressions defined by Emacs (see section
'Regexps' in Emacs Manual) for OLD-REGEXP, but you should
pay attention to the fact that case in OLD-REGEXP is significant.
You should further regard that all pairs are tried in the order in which they
appear in bibtex-autokey-titleword-change-strings, hence you have to
avoid infinite loops. This variable defaults to the value of
bibtex-autokey-transcriptions, which causes BibTeX mode
to replace TeX commands for foreign language special characters and
accented characters to their corresponding ASCII transcription. However,
since this variable operates on the whole title string and not on single
words, you can use it to change specific word combinations to abbreviations
as well (e.g.\ 'Petri Net' to 'petnet').
Thereafter, the transformed title string is abbreviated to the string up
to (but not including) the first occurrence of a regular expression
matched by the items of bibtex-autokey-title-terminators. This is
simply a list of regular expressions which are used to terminate the
part of the title string significant for key generation. It is by default
set to a list of punctuation characters, which are normally used to end a
sentence or a self-contained sentence part.
If the first word of the abbreviated title string appears in
bibtex-autokey-titleword-first-ignore, it is deleted from the
title string. This variable is a list of regular expressions, the case
of which is ignored. The purpose of this variable is to exclude expletives
like articles, which may appear in uppercase letters at the start of the
title, from the key.
The first bibtex-autokey-titlewords capitalized words from the
resulting title string are used for the title part of the key. If the
number of capitalized words in the title string is less than or equal to
bibtex-autokey-titlewords + bibtex-autokey-titlewords-stretch
all words of the title string are used instead. Unless the variable
bibtex-autokey-preserve-case is non-nil, all used title words are
now converted to lowercase letters.
For each of the used title words it is tested if it matches an item of
bibtex-autokey-titleword-abbrevs. This variable is an alist
(see section 'Association List Type' in Emacs Lisp Manual) of pairs
of the form (OLD-REGEXP NEW-STRING). Case of OLD-REGEXP
doesn't matter. If there is a match, the title word is replaced by the
NEW-STRING corresponding to the first matching OLD-REGEXP.
For a title word with no match in bibtex-autokey-titleword-abbrevs,
the first bibtex-autokey-titleword-length characters are used.
However, a word is aborted only after a consonant or at its end. You can set
bibtex-autokey-titleword-length to anything but a number (e.g.
nil) to use an unlimited number of characters.
Now all generated title words are concatenated using the value of
bibtex-autokey-titleword-separator (a string) between any two
title words. By these rules, the title part of the whole key has been
built.
Finally, to get the whole key, BibTeX mode concatenates
bibtex-autokey-prefix-string, the name part, the year part and
the title part with bibtex-autokey-name-year-separator between
the name and the year if both are non-empty and
bibtex-autokey-year-title-separator between the year and the
title if both are non-empty. If only the year part is empty,
bibtex-autokey-year-title-separator is used between the name and
the title part.
The complete algorithm which is used for automatic key generation is
summarized here.
Use the value of bibtex-autokey-prefix-string as a prefix.
If there is a non-empty 'author' field use it as the name part of
the key. If not use the 'editor' field (either 'author' or
`editor' is required in all entry types).
Change any substring of the name field matching a regular expression in
bibtex-autokey-name-change-strings to the corresponding new one.
For every of the first bibtex-autokey-names names in the name
field, determine the last name. If there are not more than
bibtex-autokey-names + bibtex-autokey-names-stretch names,
use all names instead.
From every last name, take at least bibtex-autokey-name-length
characters (abort only after a consonant or at a word end). If
bibtex-autokey-name-length is not a number take all characters.
Unless bibtex-autokey-preserve-case is non-nil, convert all last
names to lowercase letters.
Build the name part of the key by concatenating all abbreviated last
names with the string bibtex-autokey-name-separator between any
two. If not all names could be used, append the contents of
bibtex-autokey-additional-names.
Build the year part of the key by truncating the contents of the
'year' field to the rightmost bibtex-autokey-year-length
digits. If the 'year' field is absent, but the entry has a valid
'crossref' field and the variable
bibtex-autokey-year-use-crossref-entry is non-nil, use the
'year' field of the crossreferenced entry instead.
To build the title part of the key change any substring of the name
field matching a regular expression in
bibtex-autokey-titleword-change-strings to the corresponding new
one.
Abbreviate the result to the string up to (but not including) the first
occurrence of a string matched by a regular expression in
bibtex-autokey-title-terminators and delete the first word if it
appears in bibtex-autokey-titleword-first-ignore.
Build the title part of the key by using at least the first
bibtex-autokey-titlewords capitalized words from this abbreviated
title. If the abbreviated title contains maximal
bibtex-autokey-titlewords + bibtex-autokey-titlewords-stretch
capitalized words, all capitalized words from the abbreviated title are used.
Unless bibtex-autokey-preserve-case is non-nil, convert all used
titlewords to lowercase letters.
For every used title word that matches a regular expression from
bibtex-autokey-titleword-abbrevs use the corresponding
abbreviation.
From every title word not generated by an abbreviation, take at least
bibtex-autokey-titleword-length characters (abort only after a
consonant or at a word end). If bibtex-autokey-titleword-length
is not a number take all characters.
Build the title part of the key by concatenating all abbreviated title
words with the string bibtex-autokey-titleword-separator between
any two.
At least, to get the key, concatenate bibtex-autokey-prefix-string,
the name part, the year part and the title part with
bibtex-autokey-name-year-separator between the name part and the year
part if both are non-empty and bibtex-autokey-year-title-separator
between the year part and the title part if both are non-empty.
If the year part is empty, but not the other two parts,
bibtex-autokey-year-title-separator is used, too.
If the value of bibtex-autokey-before-presentation-hook is
non-nil, it must be a function taking one argument. This function is
then called with the generated key as the argument. The return value of
this function (which must be a string) is used as the key.
If the value of bibtex-autokey-edit-before-use is non-nil, the
key is then presented in the minibuffer to the user, where it can be
edited. The key given by the user is then used.
If you want to enter a string (and in this context this means a string
defined by the BibTeX '@String' reference type or defined in
the standard BibTeX style files by the MACRO command), you
don't have to type it in manually, but you can use BibTeX mode's
feature of string completion. This means, that you can give an arbitrary
prefix of the string and execute the command bibtex-complete-string,
which is usually bound to M-TAB.
This command works very similar to other completion commands in emacs
(see section 'Completion' in Emacs Manual), i.e. if you enter it at
the end of a valid string prefix this string is expanded to the longest
matching common prefix of all known strings. However, if further
completion is not possible, since the prefix before point is already a
longest common prefix, a window pops up which lists all possible
alternatives. If there is no matching completion for the prefix before
point, an error is signalled by BibTeX mode.
bibtex-complete-string acts special in the following way: if it
has just expanded a complete string it removes the enclosing delimiters.
This is because the BibTeX program requires strings not to be delimited.
You can of course use bibtex-complete-string also on an
undelimited string prefix.
Object to string completion is a set of strings defined by various
variables. At first, all strings defined in the current buffer
before current point position by a '@String' reference
belong to this set. Thus, you should normally define all '@String'
references before any other references in the BibTeX database and you
should avoid sorting '@String' entries by setting
bibtex-sort-ignore-string-entries to t (see section
Maintaining Alphabetic Order of Entries).
Secondly, you can define additional strings by the variable
bibtex-predefined-strings. You should put any strings here which
are defined by MACRO commands in the BibTeX style files you
normally use. This variable defaults to the strings defined by
MACRO commands in the standard BibTeX style files, i.e. to
abbreviations for english month names plus abbreviations for some
standard computer science journals.
Further, you might have one or more BibTeX databases containing all
the '@String' definitions you normally use. In your LaTeX file,
you will then give them as additional parameters to the
\bibliography command as e.g. in
\bibliography{stringdefs1,stringdefs2,bibtexdb}. You can make
these strings object to string completion, too, by using the variable
bibtex-string-files. These variable may contain a list of file
names with additional '@String' definitions. This variable is only
evaluated on entry to BibTeX mode. The files defined by
bibtex-string-files are searched in the paths defined by the
variable bibtex-string-file-path. This variable contains as a
single string a colon separated list of paths and defaults to the value
of the environment variable '$BIBINPUTS'.
Similar to bibtex-complete-string (see section
Completing Prefixes of Strings)
there is a command bibtex-complete-key (usually bound to
C-TAB) to complete the string before point to a key defined in
the buffer. Object to completion are all keys defined by reference entry
headers and 'crossref' fields in the current buffer.
Please note: this feature is available only, if user option
bibtex-maintain-sorted-entries (see section
Maintaining Alphabetic Order of Entries)
is non-nil.
Delimiters are not removed by this command. It is most useful in the
'crossref' field of an entry.
If you edit a new BibTeX entry it might occur that some fields shall
have similar or equal contents as the same fields in adjacent reference
entries. You can use the commands bibtex-pop-previous and
bibtex-pop-next (normally bound to C-c C-p and C-c
C-n, respectively) to snatch the contents of adjacent reference
entries. If you use these commands several times in a row you traverse
the buffer in backward and forward direction. You may give a numerical
argument to these commands as well.
There are several other commands to operate on single entries or whole
entry groups (all entries in region if mark is active (see section 'Mark'
in Emacs Manual) and all entries in buffer if not).
There are commands to check single entries or entry groups for
correctness. Other commands convert entry groups according to particular
requirements. Commands from a third group modify the appearance, but not
the contents of the buffer (or in other words they change the visible
parts). A fourth command group gives information on entry groups.
There are three commands for checking entries. One checks entries in the
visible portion of the buffer for syntactical correctness and two check
entries for misspellings.
To check if the whole buffer (or if mark is active the current region)
is parsable by BibTeX mode (and thus all features can work correctly)
the command bibtex-validate can be used. It only checks reference
entries with known type, hence you can put comments anywhere outside of
entries. If bibtex-maintain-sorted-entries is t
(see section Maintaining Alphabetic Order
of Entries) the correct sort order of the buffer is also checked.
All errors are shown in a 'compilation mode' buffer (see section
'Compilation' in Emacs Manual). You can traverse the errors by the
normal 'compilation mode' commands, e.g. next-error,
usually bound to C-x `.
If you give a prefix argument to bibtex-validate it is also
checked if required fields are missing in some entries and it is checked
if entries contain questionable 'month' fields. A 'month'
field is defined to be questionable if its text part is a string from
bibtex-predefined-month-strings delimited by braces or
double-quotes (normally you wouldn't want the delimiters here). The
variable bibtex-predefined-month-strings contains by default the
abbreviations for english month names as defined in the standard BibTeX
style files. The value for the variable bibtex-predefined-strings
(see section Completing Prefixes of Strings)
is by default derived from bibtex-predefined-month-strings, too,
so be cautious if you change it.
With the command bibtex-ispell-abstract (usually bound to
C-c $) the abstract of the current reference entry is spell
checked by 'ispell' (see section 'Overview' in Ispell Manual).
You might prefer this command to bibtex-ispell-entry, because
the complete entry will contain name of organizations, persons, institutes,
and countries, all probably unknown to 'ispell'. The contents of
the 'abstract' field (if available) holds normally a longer english
text, which may be worth to spell-check.
In this section three commands for buffer conversion are presented. One
is used to sort the buffer, one is used to reformat all entries in
buffer or region, and one is used to convert a syntactical correct
BibTeX database of arbitrary format to a format parsable by BibTeX
mode.
You can sort a buffer with the command bibtex-sort-buffer. The
buffer is sorted alphabetically according to reference entry keys. Text
outside of BibTeX entries is not affected. If
bibtex-sort-ignore-string-entries is non-nil, '@String'
entries will be ignored.
To use this function, the buffer must be parsable by BibTeX mode
(use function bibtex-validate (see section
Checking if Entries are Parsable)).
You can refill all reference entries in the current region (if mark is
active) or in the whole buffer by calling bibtex-reformat. If you
give a prefix argument to this function, additional options for
reformatting are read interactively from the minibuffer. These options
correspond to the possible options which may be given in the variable
bibtex-entry-format (see section
Advanced Entry Cleaning). In addition it is asked if new reference
labels shall be generated automatically (and non-interactively). If you
call bibtex-reformat with a double prefix argument, the previous
options are used (if any).
If you get a BibTeX database from an alien source it might not be
parsable by BibTeX mode, since BibTeX mode can parse only a subset
of the input language defined by the BibTeX program. For instance,
for quick access BibTeX mode requires the starting '@' of each
reference entry to be the first non-whitespace character in the line,
while the BibTeX program doesn't.
If a buffer isn't parsable by BibTeX mode some of the high-level
functions won't work. You can convert an arbitrary syntactical correct
BibTeX buffer to a format parsable by BibTeX mode by using the
function bibtex-convert-alien. If you give a prefix argument
to this command, additional options for reformatting are read from the
minibuffer.
Please note: If you load an alien buffer not conforming to the
required structure and you have bibtex-maintain-sorted-entries
set to t, BibTeX mode will try to parse it, which will
normally fail. You should abort this (by typing an arbitrary key)
and call immediately bibtex-convert-alien.
There are two BibTeX specific functions which change how the buffer
is presented to you, but do not change any buffer contents.
With bibtex-narrow-to-entry you can narrow the buffer to just the
current reference entry (see section 'Narrowing' in Emacs Manual for
details). With the normal Emacs command widen you will see whole
the buffer again. The command bibtex-narrow-to-entry usually is
bound to C-c C-r n while widen is for convenience bound to
C-c C-r w (in addition to its normal binding C-x n w).
With the function bibtex-hide-entry-bodies (usually bound to
C-c C-t) all entry bodies in the visible portion of the buffer are
hidden, such that only the first line of each entry remains visible. If
you put the reference key on the same line as the reference type (and
nothing else), you will have by this a quick glance at all defined
references. If you give bibtex-hide-entry-bodies a prefix
argument all entry bodies are visible again.
With the function bibtex-count-entries you can determine the
number of all entries (except '@String' entries) in the current
region (if mark is active) or in the whole buffer. If you give this command
a prefix argument it counts '@String' entries as well.
BibTeX mode supports other packages and features. These are summarized here.
To find all locations in a TeX document where the database entry at
point is cited, the RefTeX package provides the function
reftex-view-crossref-from-bibtex. From BibTeX, this function
can be accessed via C-c &. On first use, RefTeX will prompt
for a buffer which belongs to the document you want to search.
Subsequent calls will use the same document, unless you break this link
with a prefix argument to C-c &.
You can use the Font Lock minor mode (see section 'Font Lock' in
Emacs Manual) with BibTeX buffers, since BibTeX mode supports font
locking by defining various variables. One easy way to use Font Lock
mode in newer versions of GNU Emacs is to execute
(global-font-lock-mode) in your 'emacs'. If you want
other Font Lock patterns in BibTeX mode as the defaults inspect the
variable bibtex-font-lock-keywords.
You can use 'imenu' together with BibTeX mode. This package
isn't documented in the Emacs manual yet, so you have to look into the
source code 'imenu.el' in the Emacs 'lisp' directory.
Calling the command 'imenu' will provide you with a menu of
interesting places in the buffer. Interesting places are defined by
BibTeX mode to be the single reference entries and the indices appearing
in the minibuffer are the reference entry keys. You can also put an
'Imenu' entry in the menubar by putting in your '.emacs'
a command as
You can use auto fill mode (see section 'Auto Fill' in Emacs Manual)
with BibTeX mode as well. BibTeX mode provides a special function for
autofilling that assures that continuation lines of fields begin in
column bibtex-contline-indentation (see section
Nicely Aligning Reference Entries).
In this chapter, some of the frequently occuring questions are answered.
If you think something else should be here, e.g. a question, for which
to answer you needed to dive really deep into the code of BibTeX mode,
please contact 'Dirk Herrmann <D.Herrmann@tu-bs.de>'.
The questions are summarized first and thereafter they are answered.
If you want to know the answer to a specific question, search for the
question number.
I always get a "Can't find enclosing BibTex field" error
when I try to insert an entry. Shall I report a bug?
In previous versions of BibTeX mode keys for new entries where
read using the minibuffer and they were inserted in the right place.
Why is this feature missing now?
I don't like how BibTeX mode generates reference keys. How can
I change it to my needs?
How can I call the function bibtex-generate-autokey?
You have forgotten to make it interactive.
I like my entries to be indented a little bit. How can I do this?
I do not like the order of standard fields in reference entry
templates. I also do not like how reference entry types and field names
are capitalized. I think other fields should be there on default. How
can I change this?
I want to have the field 'xyz' in all of my entries.
And I want it to be initialized with a nice text. Is this possible?
I have some enhancements or major patches to 'bibtex.el'
or this 'info' file. Shall I send them?
Why is there no version information in 'bibtex.el'?
Answers to Questions
I always get a "Can't find enclosing BibTex field" error when
I try to insert an entry. Shall I report a bug?
The answer is usually no. Please investigate at first the contents of
the variable emacs-version (see section 'Examining and Setting
Variables' in Emacs Manual). If this is '19.30' you should
know that in version 19.30 a serious bug was introduced in BibTeX mode.
For more details read section Only Available
in GNU Emacs 19.30 or Newer..
If you get this error message really for all entry insertions (even in
completely empty BibTeX buffers) and emacs-version is not
'19.30' it is probable that an old version of 'bibtex.el'
is in your load path. Please try the following:
Start Emacs with emacs --no-init-file --no-site-file.
Type C-x C-f and load the standard 'bibtex.el' file
from the emacs distribution. This resides in something like
'/usr/local/share/emacs/19.35/lisp/bibtex.el' (the version
number '19.35' and the prefix '/usr/local' may differ).
Type M-x eval-buffer.
Find a new file with the extension '.bib' and type
C-c C-e C-a. If you get now a reference entry template for
an article, the error is probably caused by a wrong version of the
'bibtex.el' in your load path. Start Emacs again without
special options, use M-x locate-library to locate which file
is loaded for the library 'bibtex.el' and remove this wrong
version.
You should be able to fix the problem by this. If not please consider
reproting a bug (see section Submitting Bug
Reports).
In previous versions of BibTeX mode keys for new entries where
read using the minibuffer and they were inserted in the right place.
Why is this feature missing now?
Please make sure your buffer is parsable by BibTeX mode (see section
Checking if Entries are Parsable),
sort it (see section Sort a Parsable
Buffer), and set the variable bibtex-maintain-sorted-entries
to t in your '.emacs' (see section
Maintaining Alphabetic Order of Entries).
If you now start Emacs again, you should get what you want.
I don't like how BibTeX mode generates reference keys. How can I change
it to my needs?
Please refer to section Automatic Reference
Key Generation. If you really are unhappy and find that the used algorithm
cannot be forced to do what you want (even by twiddling around with all
variables beginning with 'bibtex-autokey-') you should consider
to overload the function bibtex-generate-autokey (see section
'Hooks for Loading' in Emacs Lisp Manual). Perhaps you don't need
to alter whole the functionality, but just a few of the internal functions
called by bibtex-generate-autokey (all beginning with
bibtex-autokey-). Please note: there may be always cases
where you are not satisfied with the keys generated automatically. It may
be a good idea to have bibtex-autokey-edit-before-use set to
t and fine-tune keys manually.
How can I call the function bibtex-generate-autokey?
You have forgotten to make it interactive.
No. It is intended to be called automatically whenever you call
bibtex-clean-entry with a prefix argument or on a reference entry
without a key (see section Automatic Reference
Key Generation). It is not intended to be called interactively.
I like my entries to be indented a little bit. How can I do this?
You can control the amount of indentation for field names and texts and
even for whole entries by appropriate variables (see section
Controlling the Alignment of Fields
and Entries).
I do not like the order of standard fields in reference entry templates.
I also do not like how reference entry types and field names are capitalized.
I think other fields should be there on default. How can I change this?
You have to change the variable bibtex-entry-field-alist for this
(see section Definition of Entry Contents for
each Reference Type). This variable contains for all entries all fields
which according to 'btxdoc.tex' are supported by standard BibTeX
style files. Be sure you know what you are doing if you modify this variable.
Setting it to something inappropriate will virtually break everything
in BibTeX mode.
I want to have the field 'xyz' in all of my entries. And I
want it to be initialized with a nice text. Is this possible?
Please refer for both issues to section
Additional Fields Required by the User.
I have some enhancements or major patches to 'bibtex.el' or
this 'info' file. Shall I send them?
Normally yes. If you have patches you should at first get the newest
beta release (see section Getting New Beta
Releases) and see if the bug has been fixed already. If not, please
send me the patch. However, since I often have versions of BibTeX mode
in alpha stage (I only make versions available as beta code, which I
have tested myself), it might be that the bug fix has been already made.
So to make sure not to do unnecessary work (trying fo fix a bug which has
been fixed already) it might be best to first contact me ('Dirk Herrmann
<D.Herrmann@tu-bs.de>') and indicate that you are willing to
submit a patch.
If you want to have new features in BibTeX mode and plan to program
and provide code, it is a good idea to contact me, too. Some features
may be useful in a special environment only and even irritating to other
users. Some features may break existing code. Some features should
perhaps reside somewhere else (not in BibTeX mode). Some features
might even already be incorporated in current alpha or beta versions of
BibTeX mode.
Why is there no version information in 'bibtex.el'?
In official releases of BibTeX mode there is no version information,
since the version number of Emacs itself (contained in
emacs-version) suffices for identification. Beta releases of
BibTeX mode (see section Getting New Beta
Releases) have version information included in the variable
bibtex-version. Please refer to the contents of one of these
variables (whichever is appropriate) if you send me a mail concerning
BibTeX mode (e.g. suggestions, questions). For bug reports, please use
the dedicated function (see section
Submitting Bug Reports).
History of Changes to BibTeX Mode
Here is a list of new features of BibTeX mode introduced with the
single GNU Emacs distributions. If you know the version of GNU Emacs you
have installed (e.g. type C-h v emacs-version), you can look here
to see what you may miss.
Even if there are no new features in particular versions, there may be
bug fixes.
In GNU Emacs 19.35, the following features were introduced to BibTeX
mode:
Fields and complete entries can be killed and yanked back by using
appropriate functions.
New variable bibtex-entry-delimiters to determine how entries
shall be delimited.
Allow preinitialization of field texts. See documentation of
bibtex-user-optional-fields, bibtex-entry-field-alist,
and bibtex-include-OPTkey for details.
'Book' and 'InBook' entries require either an
'author' or an 'editor' field. This is now supported by
BibTeX mode. Alternative fields are prefixed with 'ALT'.
New variable bibtex-entry-format, which replaces variable
bibtex-clean-entry-zap-empty-opts and allows specification of
many formatting options performed on calling bibtex-clean-entry.
Some new variables (bibtex-autokey-prefix-string,
bibtex-autokey-names-stretch,
bibtex-autokey-additional-names,
bibtex-autokey-preserve-case,
bibtex-autokey-year-use-crossref-entry, and
bibtex-autokey-before-presentation-hook) are used by
bibtex-generate-autokey. Transcriptions for foreign languages
other than German are now handled, too.
New boolean user option bibtex-comma-after-last-field to decide
if comma should be inserted at end of last field.
New boolean user option bibtex-align-at-equal-sign to determine
if alignment should be made at left side of field contents or at equal
signs. New user options bibtex-entry-offset,
bibtex-field-indentation, bibtex-text-indentation, and
bibtex-contline-indentation.
New function bibtex-fill-entry to realign entries.
New function bibtex-reformat to reformat region or buffer.
New function bibtex-convert-alien to convert a BibTeX database
from alien sources.
Reference key completion with C-TAB key. Mainly useful in
'crossref' entries.
New function bibtex-count-entries to count entries in buffer or
region.
Added support for 'imenu'.
The function bibtex-validate now checks current region instead of
buffer if mark is active. With optional prefix argument it also checks
if required fields are missing or if entries contain questionable month
fields. Now it shows all errors of buffer in a compilation mode
buffer. You can use the normal commands (e.g. next-error) for
compilation modes to jump to errors.
Made bibtex-parse-keys, bibtex-reformat, and
bibtex-validate more verbose. They show progress by indicating
percentage of done work.
In GNU Emacs 19.32, the following features were introduced to BibTeX
mode:
For all entries allow spaces and tabs between opening brace or
parenthesis and key.
Support for non-escaped double-quoted characters in field texts
(as in 'Sch"of').
Unfortunately, an internal variable in the source code of GNU Emacs
19.32 was changed. This resulted in BibTeX mode not working anymore
if used on buffers with entries containing long fields. If you have GNU
Emacs 19.32, please consider upgrading your GNU Emacs version
(see section 'Distribution' in Emacs Manual).
If you are for some reasons unable to do this, you can get a special
version of 'bibtex.el' which will work with GNU Emacs 19.32 from
the same place where you can get new beta releases of 'bibtex.el'
(see section Getting New Beta Releases).
On how to install this special version, please refer to section
Installing BibTeX mode.
Please note: if you install this special version for GNU Emacs
19.32, you will miss the features of the newer versions.
In GNU Emacs 19.30, no new features were introduced, but unfortunately
a serious bug, which prevents adding new entries to the BibTeX buffer.
If you have GNU Emacs 19.30, please consider upgrading your GNU
Emacs version (see section 'Distribution' in Emacs Manual).
If you are for some reasons unable to do this, you can get a special
version of 'bibtex.el' which will work with GNU Emacs 19.30 from
the same place where you can get new beta releases of 'bibtex.el'
(see section Getting New Beta Releases).
On how to install this special version, please refer to section
Installing BibTeX mode.
Please note: if you install this special version for GNU
Emacs 19.30, you will miss the features of the newer versions.
Since I took over maintenance of BibTeX mode on the basis of the
version shipped with GNU Emacs 19.28, I have no knowledge of earlier
version history. Though BibTeX mode shipped with GNU Emacs 19.28 does
a pretty good job in aiding edition of BibTeX files, it lacks ---
compared to the current version -- the following features:
Automatic reference key generation.
Helpful comments in the echo area on purpose of current BibTeX field.
Possibility to reformat region or buffer.
Possibility to realign entries.
Enhanced functionality of bibtex-validate, e.g. possibility to
have it check if required fields are missing or if entries contain
questionable month fields. Compilation-mode like error listings.
Killing and yanking of fields and complete entries.
Enhanced cleaning of BibTeX entries, e.g. checking for missing
fields.
TAB completion on entering reference keys in the minibuffer.
String completion with the M-TAB key.
Reference key completion with C-TAB key.
Possiblity to generate 'crossref' fields not for all
reference types, but for only a few of them.
Possibility to kill and yank fields and whole entries.
Support for alternative fields as in 'Book' and
'InBook' entries.
Support for braces as field delimiters and parentheses as entry
delimiters.
Support for entries with quotes inside quote-delimited fields.
Support for non-escaped double-quoted characters in field texts
(as in 'Sch"of') as may be useful in foreign language BibTeX
databases.
Support for entries with spaces or tabs between opening brace or
parenthesis and key.
Boolean user option bibtex-comma-after-last-field to decide
if comma should be inserted at end of last field.
Boolean user option bibtex-align-at-equal-sign to determine if
alignment should be made at left side of field contents or at equal
signs. New user options bibtex-entry-offset,
bibtex-field-indentation, bibtex-text-indentation, and
bibtex-contline-indentation.
Preinitialization of field texts from functions.
Smarter indentation scheme for continuation lines of fields.
Support of 'Font Lock mode'.
Support for 'imenu'.
Support for 'auto fill mode'.
Function bibtex-count-entries to count entries in buffer or
region.
The author wishes to thank a few people for contributing to the current
state of GNU Emacs BibTeX mode. These are:
Bengt Martensson, Mark Shapiro, Mike Newton, and Aaron Larson for
working on BibTeX mode up to the version shipped with GNU Emacs
19.28.
Karl Eichwalder and Martin Maechler for their numerous comments, bug
reports, and suggestions.
Oren Patashnik for many discussions and hints regarding the syntax of
BibTeX and -- last, but not least -- for developing and providing
the BibTeX program, without which a GNU Emacs BibTeX mode would be
pretty useless.
Simon Marshall for discussions and suggestions about Font Lock patterns
for BibTeX mode.
Many other people for bug reports, comments, and suggestions.