Ebib: a BibTeX database manager for Emacs

Joost Kremers
`joostkremers@yahoo.com`

1 Overview
2 Installation
3 The Ebib buffers
4 Format of the .bib file
5 The initialisation file
6 Limitations

Ebib is a program with which you can manage BibTeX database files without having to edit the raw .bib files. It runs in GNU/Emacs, version 21.1 or higher (lower versions are not supported) and XEmacs (at least from version 21.4; lower version have not been tested, but may work.)

It should be noted that Ebib is not a minor or major mode for editing BibTeX files. It is a program in itself, which just happens to make use of Emacs as a working environment, in the same way that for example Gnus is.

The advantage of having a BibTeX database manager inside Emacs is that X is no longer required, as Emacs can run on the console, and also that some integration with Emacs' T_EX and L^AT_EX modes becomes possible. For example, one can insert a key from the database into the text one is editing using tab completion. Another advantage of Ebib is that it is completely controlled by key commands: no stressful mouse movements are required, as with most other (usually X-based) BibTeX database managers.

Note for the impatient: pressing `h' in Ebib will give you an overview of the commands you can use in the buffer you are in. You should be able to get by with just reading the Overview (section 1) and using this help function. Though reading the entire manual is still a good idea, of course.

1 Overview

A BibTeX database is somewhat of a free-form database. A BibTeX entry consists of a set of field-value pairs. Furthermore, each entry is known by a unique key. The way that Ebib navigates this database is by having two windows, one that contains a list of all the keys in the database, and one that contains the fields and values of the currently highlighted entry.

When Ebib is started, the current windows in Emacs are hidden and the screen is divided into two windows. The top one contains a buffer that is called the index buffer, while the lower window contains the entry buffer. When a database is loaded, the index buffer holds a list of all the keys in the database. You can navigate through these keys with the cursor keys or with `j' and `k'. In the entry buffer, the fields of the currently highlighted entry are shown, with their values.

Opening and closing .bib files

Ebib is started with the command M-x ebib. When Ebib is first started, both buffers are in principle empty. You can open a database with `o'. If you want to start a new database from scratch, use the `o' command and type the name for the new .bib file.

Closing a database can be done with the key `c'. Note that this only closes the currently active database, it does not close Ebib itself. If the database has been modified, you will be asked for confirmation.

It is possible to have Ebib load specific .bib files automatically when it is started. This is done by adding an ebib-preload command to Ebib's init file. See section 5 for details.

Field types

In the entry buffer, the entry type is given at the top, followed by (normally) three groups of fields. The first group are the so-called required fields, the fields that BibTeX requires to be filled. The second group are the optional fields, which do not have to be filled but which BibTeX will normally add to the bibliography if they do have a value. The third group are the so-called ignored fields. These fields are usually ignored by BibTeX (note that BibTeX will normally ignore all fields it does not know), although there are bibliography styles that treat some of these fields as optional rather than as ignored; (i.e., the harvard styles do typeset the url field, if present.)

As you will probably know, the obligatory and the optional fields can be different for each entry type. The ignored fields, however, are common to all the entry types. You can use these, for example, to add personal comments to the works in your database. (To see how you can define the entry types and the fields for them, see section 5.)

Basic editing

When a database is loaded, new entries can be added to it with `a', and entries can be deleted with `d'. For a full description of all the available key commands in the index buffer, see section 3. A special key is the key `e', which allows you to edit the field values of the current entry. When you hit `e' on a key, focus moves to the entry buffer, with the first field (the type field) highlighted. You can move up and down the fields with the cursor keys or with `j' and `k'. There are commands for cutting, copying and pasting the field contents, and of course one for editing the value of the current field. See section 3 for a full description.

Field values

The first field of each entry is special: this is the type field, and it holds the type of the entry (i.e., whether it is a book, article, phdthesis, etc.) (Note that in the BibTeX file, this is not really a field at all, but the keyword that follows the @-sign opening a new entry.) When you create a new entry, it is advisable to edit this field first and set it to the correct value, because the entry type determines the fields that are available.¹

All the other fields of an entry have simple text values. You can enter a value for a field, or change the existing value, by hitting `e'. BibTeX requires that a field value is surrounded by either braces or quotes, but you do not have to type these, as Ebib will add them automatically when it saves the database.² Note that if you want extra parenthesis in the field contents (e.g., to keep BibTeX from downcasing words in a titel, or to make sure it handles accented letters correctly) you can of course type them. Ebib puts braces around the values that you enter, but does not change them in any other way.

Note that the annote field is special: if you edit this field, Ebib will put you in a text buffer rather than in the minibuffer. The annote field is usually used for making annotated bibliographies, and for that, its value must be longer than a single line.

Multiline values

As just said, if you edit the annote field, Ebib automatically puts you in a text buffer, because annote field is supposed to hold texts of more than a single line. A value that consists of more than one line is called a multiline value in Ebib. For the annote field, a multiline value is standard, but in principle every field (except the type and crossref fields) can contain a multiline value.

You can give a field other than the annote field a multiline value by typing 'l'. This key puts you in the so-called multiline edit buffer (see section 3). Here you can enter or edit the value of the field. To leave the multiline edit buffer and store the text you have entered, hit C-x b. To leave the buffer without saving your changes, hit C-x k.

When a field holds a multiline value, only its first line will be displayed in the fields buffer. A plus sign `+' will appear in front of the field's value, however, to indicate that the value is longer than what is shown.

Raw values

As just mentioned, Ebib will put braces around the field values that you enter. This is not always desirable, however. When a field contains an abbreviation defined with an @string command, it must not be enclosed in braces, because then BibTeX would ignore the abbreviation and treat it as normal text. In order to tell Ebib that a field must not be surrounded by braces, you must mark the field as raw. This is done with the key `r'. An asterisk `*' will appear before the field's value in the fields buffer. When Ebib saves the database, raw fields will be saved as is, without additional braces.

Note that this also makes it possible to enter field values that are composed of concatenations of strings and abbreviations. The BibTeX documentation for example explains that if you have defined:

@string{WGA = "World Gnus Almanac"}

you can create a BibTeX field like this:

      title = 1966 # WGA

which will produce "1966 World Gnus Almanac". Or you can do:

      month = "1~" # jan

which will produce someting like "1 January", assuming your bibliography style has defined the abbreviation jan. All this is possible with Ebib, simply by entering the exact text including quotes or braces around the strings, and marking the relevant field as raw.

Note, by the way, that a field value can be both raw and multiline at the same time. Such a value will be marked with `*+' in the field buffer.

@String definitions

There would be no point in having raw fields if there were no way to create @string abbreviations. So obviously, Ebib provides one. When you hit `t' in the keys buffer, the entry buffer will disappear and be replaced by the strings buffer. This buffer shows all the @string definitions in the database. You can move through them in the same manner as you navigate the fields of an entry, and you can edit them, delete them and add new ones. BibTeX requires that string values be surrounded by braces or quotes, but just like with the field values, Ebib takes care of this: you do not have to type them yourself.

Note that the value for an @string definition cannot be raw, simply because it would not make any sense, and BibTeX would not accept it. An @string can be multiline, however. A multiline string is created with `l', just as a multiline field. There is one limitation, however: if you define a new string, you are always asked to enter a single-line value. You can only make it multiline after it has been defined.

@Preamble definition

Ebib allows you to add one @preamble definition to the database. In principle, BibTeX allows more than one such definition, but, as explained in the BibTeX documentation, one should suffice, because you can use the concatenation character # to include multiple T_EX or L^AT_EX commands. So, you can write this in your .bib file:

@preamble{ "\newcommand{\noopsort}[1]{} "
         # "\newcommand{\singleletter}[1]{#1} " }

With Ebib, of course, you only have to type the text between the braces. Ebib will take care of including the braces of the @preamble command, but otherwise it will save the text exactly as you enter it. So in order to get the preamble above, you'd have to type the following in Ebib:

"\newcommand{\noopsort}[1]{} "
# "\newcommand{\singleletter}[1]{#1} "

When Ebib loads a .bib file that contains more than one @preamble definition, it will concatenate all the strings in them in the manner just described and save them in one @preamble definition.

Multiple databases

Ebib allows you to have more than one .bib file open simultaneously. To open a second (or third, fourth, etc.) file, just hit `o' again and enter the filename. Ebib will number the databases, and the keys 1-9 provide a quick way of jumping from one database to another. The number of each database appears in the status line of the keys buffer, together with the .bib file's filename. Note that the numbering is dynamic: if you have three databases opened and then close the second, database 3 becomes database 2.

With the left and right cursor keys, you can move to the previous or next database. These keys wrap, so if you hit the left cursor key while the first database is active, you will move to the last database.

It is possible to copy an entry from one database to another, by using `x' prefixed with the database number (i.e., if you want to move an entry to database 3, type M-3 x).

Closing Ebib

There are two ways of leaving Ebib. The first is to use the key `z'. All this does is put Ebib in the background by hiding the Ebib buffers: the databases remain loaded, and you can go back to Ebib at any time with the command M-x ebib. The second way to leave Ebib is the key `q'. This quits Ebib completely, and unloads the databases. You can of course restart Ebib, but it will restart with an empty database (or with the database(s) that you've preloaded). Note, by the way, that `q' is only available in the keys buffer. In the fields buffer, `q' moves focus back to the keys buffer.

When Ebib is in the foreground, it requires that both its windows are present, and for proper operation it is also necessary that none of its buffers are closed explicitly by the user. For this reason, the key sequences C-x b and C-x k are redefined inside the Ebib buffers: they are equivalent to `z' and `q', respectively. This, by the way, will not stop you from killing an Ebib buffer explicitly with M-x kill-buffer. It will stop you from accidentally killing an Ebib buffer, though.

If you should kill Emacs with C-x C-c while one or more of the databases in Ebib was not saved yet, you will be asked if you want to save them. If you answer `y', Ebib will save the database(s) and Emacs will close. If you answer `n', you will be asked if you really want to kill Emacs and abandon the changes you made to the database.

L^AT_EX integration

Leaving Ebib with the command `z' has an additional advantage, apart from the fact that you do not have to reload your database(s) when you invoke Ebib again. When you are in a non-Ebib buffer, two commands are available that allow you to query Ebib's database. First, there is M-x ebib-insert-bibtex-key. When you invoke this command, Emacs will prompt you for a key from the database associated with the current buffer. (How this association works is explained below.)

At the prompt, you can use tab-completion, to complete a partial key, or to show you all the possible completions. After hitting ENTER, Emacs will put the selected key at the cursor position in the current buffer, surrounded by braces.

The second function that is available outside Ebib is ebib-entry-summary. This command reads the key under the cursor in the current buffer and displays the field values associated with that key in a *Help* buffer. This allows you to quickly check a reference in a text.

The easiest way to use these functions is of course to bind them to a key sequence. You can do this with global-set-key, but it makes more sense to define a key sequence in your L^AT_EX mode(s) only. For example, if you use AUCTeX, the following command in Emacs' init file will bind the key sequence C-c b to ebib-insert-bibtex-key in AUCTeX's LaTeX-mode:

(add-hook 'LaTeX-mode-hook #'(lambda ()
                  (local-set-key "\C-cb" 'ebib-insert-bibtex-key)))

You can do the same thing with ebib-entry-summary. Obviously, you can choose any other key or key sequence. Under a standard set-up, however, C-c b should still be available.³

In order to determine which database these two commands must consult, Ebib tries to associate a buffer with a particular .bib file. Ebib does this by checking if there is a \bibliography command in the current file. If there is, it reads the filename from that command and tries to find a corresponding database. If there is no database with that name, Ebib will give an error. If there is no \bibliography command in the current file, Ebib will consult the current database (i.e., the database that was active before you hit `z' to lower Ebib).

If you have split up your L^AT_EX document into more than one file, you may of course be editing a file that does not have a \bibliography commmand of its own. Ebib provides two ways of dealing with this. First, if you use AUCTeX, Ebib will check if the variable TeX-master happens to be set to a filename. If it is, Ebib will look for a \bibliography command in that file instead of in the current buffer. If you don't use AUCTeX, just make sure that the relevant database is active in Ebib: if Ebib does not find a \bibliography command in the current buffer, it will use the current database as a default.

2 Installation

To install Ebib, so that it will be loaded automatically when Emacs is started, simply copy the file ebib.el to somewhere in your load path and add the following line to Emacs' init file (~/.emacs for GNU/Emacs, ~/.xemacs/init.el for XEmacs):⁴

(autoload 'ebib "ebib" "Ebib, a BibTeX database manager." t)

When Ebib is loaded, you can run it with M-x ebib. This command is also used to return to Ebib when you have put the program in the background. You can, of course, bind this command to a key sequence by putting something like the following in Emacs' init file:

(global-set-key "\C-ce" 'ebib)

You can also byte-compile the source, either within Emacs with M-x byte-compile-file, or from your shell by going into the directory where you put ebib.el and typing:

emacs -batch -f batch-byte-compile ebib.el

(Substitute emacs with xemacs if you use XEmacs.) This will create a file ebib.elc, which Emacs will load instead of ebib.el. It will make Ebib run a bit faster. (Quite a lot faster, actually, in my experience.)

In order to run, Ebib needs the file ~/.ebibrc. This file contains essential definitions, and Ebib cannot and will not run without it. A sample ebibrc is provided, which you can copy to your home directory with the following command:

cp /path/to/ebibrc ~/.ebibrc

The sample ebibrc should be sufficient for most users, but if you want, you can customise it and define your own entry types. See section 5 for details.

3 The Ebib buffers

In the following sections, the various buffers that Ebib uses are discussed, and all the available key commands are listed. Note that in the index, entry and strings buffer, you can get a quick overview of the available commands by pressing `h'.

(Almost) all the key commands listed here can be customised through .ebibrc. How this is done is explained is section 5.

The index buffer

The keys buffer contains the keys of all the entries in the database. It is the buffer that is active when Ebib is invoked. Once a database is open, all of the following key commands are available:⁵

j, Down, C-n: - go to next entry.
k, Up, C-p: - go to previous entry.
g, Home: - go to first entry.
G, End: - go to last entry.
b, PgUp, M-p: - move ten entries up.
Space, PgDn, M-n: - move ten entries down.
q, C-x k: - quit Ebib. This sets all variables to nil, unloads the database(s) and quits Ebib. When Ebib is restarted with M-x ebib, it will start with an empty database, or with the preloaded ones. You will be prompted if you really want to quit, and see a warning if the database was modified. Note that in the index buffer, C-x k does not behave in the normal way: it quits Ebib, rather than just killing the current buffer.
s: - save the database. This saves the database to the file from which it was loaded. Ebib will make a backup of the .bib file (named <filename>.bib~) if it is being saved for the first time after opening it.
S: - save all databases. This amounts to going through all databases one by one and hitting `s' for each of them.
w: - write the database to a different file. This also saves the database, but to a different file than the one from which it was loaded. You are prompted for a filename. This filename will be the new file name, so if you use `s' after having used `w', the file will be written to the new file, not to the one from which it was originally loaded.
c: - close the database. This unloads the current database, but does not quit Ebib. You will be prompted if you really want to close it, and receive a warning if the database was modified.
o: - open a .bib file. This prompts you for a filename to load. As stated, you can have more than one .bib file open at the same time. There is no upper limit to the number of files Ebib will open, except for the amount of RAM in your computer.
m: - merge a .bib file. You can use this command to read BibTeX entries (and of course @string and @preamble definitions) from another file and add them to the database. If the file being merged contains entry keys or @string definitions that already occur in the database, they will be ignored and you will receive a warning message.
a: - add an entry. You are prompted for a new entry key. If you enter a key that already exists, the action is aborted with an appropriate error message. Otherwise, the new key is inserted in the index buffer and made active. Focus then moves to the entry buffer, where you can edit the fields. (See section `The entry buffer' below.)
/: - search the database. With this command, you can search through the current database. You are prompted to enter a search string (which can be a regular expression). Searching will start at the current entry, not at the first entry of the database. If the search string is found, the corresponding entry is displayed, and the search string is highlighted everywhere it is found in the entry. If the search string was found in a multiline value, the plus sign before the field value is highlighted. Keep an eye out for this, because if the search string is not found in the first line of the multiline value, it will not be shown on screen, and only the highlighted plus sign indicates where the search string is found.
n: - find next occurrence of the search string. Searching will be resumed from the entry following the current entry, and the next occurrence of the search string will be shown. Note that the search does not wrap: if the last entry of the database is reached, the search will not continue at the first entry. Hit `g' and then `n' to continue searching from the top.
f: - display the full filename of the current database in the minibuffer. This may be useful sometimes.
d: - delete the current entry. You are prompted for confirmation. Note that once an entry is deleted, it cannot be retrieved anymore.
x: - export the current entry. With this, you can write a single entry to another file, or copy it to another database. If you use `x' with a prefix argument (M-<number> x), the current entry will be copied to that database. If you use `x' without a prefix argument, you will be prompted for a filename, and the entry will be appended to that file. If the file does not exist, it will be created.
This command is intended for creating a new BibTeX file out of entries of an existing one, for example if you want to submit a paper with a .bib file containing only the relevant entries. The filename to which you save an entry is remembered, so the next time you use `x' it will default to the same file, although you can of course change it. Note: you may want to export the @preamble and @string definitions as well. See below (key `X') and section `The strings buffer' (keys `x' and `X').
Return: - make the entry under the cursor current. In the keys buffer, you can use the standard search functions (e.g., C-s) to search for an entry key. When one is found, the cursor is moved to it. After you exit the search function, you can hit RETURN to force Ebib to make that entry the current entry. (With C-s, this essentially comes down to having to hit RETURN twice when you found the desired key.)
z, C-x b: - lower Ebib. This puts Ebib in the background and restores the windows that were in the Emacs frame before you started Ebib. Ebib will stay active, and your databases will remain loaded. You can return to Ebib with M-x ebib. Note that in the index buffer, C-x b has been redefined: it does not switch from the current buffer in the normal way.
e: - edit the current entry. This puts you in edit mode, where you can edit the fields of the current entry. See section `The entry buffer' below.
E: - edit the key of the current entry. With this command, you can change the name you have given to an entry. One situation in which this can be useful is when you have an entry jones:1998 and you want to add another entry by Jones published in 1998. You can call the new entry jones:1998b and change jones:1998 into jones:1998a.
t: - list the @string definitions in the database. You will be put in the strings buffer, where you can edit or delete @string definitions, or add new ones. See section `The strings buffer'.
P: - show the @preamble definition in the database. You will be put in multiline edit mode (see section `The multiline edit buffer') where you can edit the text for the @preamble command in the database. Note that Ebib only allows you to define one @preamble definition, which will be put at the top of the database. This should not be a problem, because you can use BibTeX's concatenation character # to put multiple L^AT_EX commands in the preamble. The text that you enter is put in the @preamble command literally, so you have to type quotes around your strings.
J: - jump to another database. This accepts a numeric prefix argument, but will ask you for a database number if there is none. Note that the keys 1-9 will jump to the first nine databases, so `J' will only be needed when you load more than nine.
1-9: - jump to the corresponding database.
Left, Right: - move to the previous/next database. These keys wrap, so if you hit the left cursor key while the first database is active, Ebib will move to the last database.
X: - export the @preamble definition to a file or, when used with a prefix argument, to another database.
h: - show help for the keys buffer.

When no database is opened, only four commands are available: `o' to open a database, `h' to display the help text, `z' to lower Ebib, and `q' to quit Ebib.

The entry buffer

When you hit `e' or `a' in the index buffer, you will be placed in edit mode: focus moves to the entry buffer, and you can edit the fields of the current entry. The current field is highlighted. This section lists the commands available in the entry buffer. Of course, these keys are all customisable through .ebibrc.

j, Down, C-n: - go to the next field.
k, Up, C-p: - go to the previous field.
g, Home: - go to the first field.
G, End: - go to the last field.
b, PgUp, M-n: - go to the next set of fields. That is, when you are on one of the required fields, go to the first optional field, etc.
Space, PgUp, M-p: - go to the previous set of fields. That is, when you are on one of the the ignored fields, go to the last optional field, etc.
q, C-x k: - quit editing the current entry and return focus to the index buffer.
c: - copy the contents of the current field to the kill ring. You can copy the field contents and use C-y in a non-Ebib buffer to yank it, or use `p' to yank it to another (empty) field, possibly in another entry.
x: - cut the contents of the current field. Like `c', `x' puts the contents of the current field in the kill ring.
p: - paste the last element in the kill ring to the current field. It is not (yet) possible to move around the kill ring with this command. (You can of course use `e' and then C-y/M-y to do this.) Note that no text will be pasted if the field already has a value. Use `d' first to delete the fields value.
d: - delete the value of the current field. The deleted contents will not be put in the kill ring, and is therefore irretrievably lost.
e: - edit the current field. You are placed in the minibuffer where you can fill in a value for the current field, or edit the existing value. C-g cancels the edit action and retains the original value, if any. RETURN confirms the edit. If you edit the entry type, you must select a type from the ones defined in the init file. (See section 5.) You can use tab-completion in this case. If you edit the crossref field, you must select a key from the database. Here, too, tab-completion works. If you edit the annote field or any field that has a multiline value, you will be put in the multiline edit buffer (see section `The multiline edit buffer').
r: - toggle a field's "raw" status. The current field is marked as raw (an asterisk appears) or it becomes a "normal" field again when it was already marked as raw. If you hit `r' on a field that has no value yet, the field is marked as raw and you are prompted for a value. This is an important option if you use @string definitions.
l: - edit the current field as multiline. This puts you in Ebib's multiline edit buffer (see section `The multiline edit buffer'), which allows you to give the current field a multiline value (i.e., a value that contains newlines). If you want to edit a field that already has a multiline value, you can also use `e', but you must use `l' if you want to enter a multiline value for a field that doesn't have one yet. (An exception to this is the annote field, which is always edited in the multiline edit buffer.) Note that in the entry buffer, only the first line of the field's value is shown. A plus sign `+' is displayed in front of it to indicate that the value is actually longer.
s: - insert an abbreviation from the @string definitions in the database. This is another way to edit a field value, with the restriction that you can only select one of the abbreviations in the database. Tab completion works, and the field will automatically be marked raw. Of course you do not have to use this command; it is also possible to enter an abbreviation with `e' and `r'. But it is a good way of ensuring that you do not mistype an abbreviation, and that the field is marked raw. Note that `s' does not work if the field already has a value.
z, C-x b: - lower Ebib.
h: - show help for the entry buffer.

The strings buffer

When you hit `t' in the index buffer, you will be put in the strings buffer, where you can edit the @string definitions in your database. The keys available here are partly the same as the keys in the fields buffer:

j, Down, C-n: - go to the next string.
k, Up, C-p: - go to the previous string.
g, Home: - go to the first string.
G, End: - go to the last string.
b, PgUp, M-p: - go ten strings up.
Space, PgDn, M-n: - go ten strings down.
q, C-x k: - quit the strings buffer and return focus to the index buffer. The strings buffer will disappear from the bottom window and the fields buffer is displayed again.
c: - copy the text of the current string to the kill ring. You can copy the string value and use C-y in a non-Ebib buffer to yank it.
e: - edit the value of the current string. You are placed in the minibuffer where you can edit the value. C-g cancels the edit action and retains the original value. Return confirms the edit. It is pointless to have an empty value for a string, so Ebib will not accept an empty string. If you edit a string value that is multiline, you will be placed in the multiline edit buffer.
l: - edit the value of the current string as multiline. You are placed in the multiline edit buffer (see section `The multiline edit buffer').
a: - add a new @string definition. You will be prompted for a new abbreviation, which has to be unique, and for a string value.
d: - delete the current @string definition from the database. You will be asked for confirmation.
x: - export the current @string definition to a file or, when used with a prefix argument, to another database. Use this in conjunction with the commands to export fields and the preamble.
X: - export all the @string definitions to a file or, when used with a prefix argument, to another database. Useful if you do not want to hit `x' on every abbreviation separately.
h: - show help for the strings buffer.

The multiline edit buffer

Ebib has a special multiline edit buffer, which is used to edit field values that contain newlines (so-called multiline fields), and also to edit the contents of the @preamble command. Ebib enters multiline edit mode in one of three cases: when you press `P' in the keys buffer, to edit the @preamble definition, when you hit `l' in the fields or strings buffer, to edit the current field or string as multiline, or when you hit `e' on the annote field or on a field or string whose value already is multiline.

The multiline edit buffer uses a special major mode, ebib-multiline-edit-mode, which is derived from text-mode. The changes with respect to text-mode are minor (see below), which means that any customisations you may have made to text-mode will be available in the multiline edit buffer.

The settings that are specific for ebib-multiline-edit-mode are the functions assigned to the key sequences C-x b, C-x k and C-x C-s. These key sequences do not have their usual functions, but rather are redefined to fit Ebib. Both C-x b and C-x k can be used to leave the multiline edit buffer. C-x b will store the text as it is to the database, while C-x k will leave the multiline edit buffer without storing the text, i.e., the original value of the field, string or preamble that you were editing will be retained. If the text in the buffer was modified, C-x k will ask you if you really want to abandon your changes.

If you leave the mulitiline edit buffer with C-x b when the buffer is empty (i.e., you deleted all the text, including the final newline), and you were editing a field value or the @preamble definition, the field value or preamble will be deleted.⁶ If you do this while editing an @string definition, you will get an error message, because @string definitions cannot be empty.

The third command that is redefined in the multiline edit buffer is C-x C-s. This command can be used to save the database. Because Ebib does not do an autosave of the current database, it is advisable to save the database manually every now and then to prevent data-loss in case of crashes. It would be annoying to have to leave the multiline edit buffer every time you want to do this, so C-x C-s has been redefined to allow you to do this from within the buffer.⁷

4 Format of the `.bib` file

In principle, Ebib accepts everything in the .bib files it reads that BibTeX accepts. There are a few exceptions, however, that one may need to be aware of when one loads a self-created .bib file into Ebib. Like BibTeX, Ebib accepts both upper and lower case for the entry types and field names: they are not case-sensitive. Unlike BibTeX, however, the entry keys are case-sensitive. The reason for this is that they are so for L^AT_EX.

In entry types, field names, entry keys and @string abbreviations, Ebib will accept all printable ASCII characters except the following:⁸

   " # % ' ( ) , = { }

Ebib does not handle @comment commands. Ebib will ignore them when loading a file, and if you then modify the file and save it, the @comment commands will be gone.

Note also that when Ebib finds a field that has not been defined in the init file (see section 5), it will store it, and also save it to the .bib file, but it will not display it. No warning is given when this happens, so if you load your self-made .bib file into Ebib, make sure all the fields you use are properly defined.

When Ebib encounters an entry type that it does not know, it will issue a warning message, and continue searching for the next entry. Note that if there is more than one unknown entry in the .bib file, only the last warning message will be visible after the file has been loaded. To see all warning messages, you have to switch to the *Messages* buffer.

5 The initialisation file

Ebib makes use of an init file ~/.ebibrc. This file is loaded when Ebib is first loaded, and contains the definitions of the entry types and the field types, possibly a preload command, and the command key definitions. This information is essential to Ebib, because it cannot set up the database without it. Therefore, if Ebib cannot find this file, it will not run. For convenience, a default ebibrc file is provided. For most people, it will be sufficient to simply copy this file to their home directory.

For those that need or want to make certain customisations, this section explains how the init file is built up. It's basic Lisp syntax, so it shouldn't be too confusing. The init file starts with a set of entry type definitions that look like the following:


(defentry article                     ; name of entry type
  (author title journal year)         ; obligatory fields
  (volume number pages month note))   ; optional fields

This defines the entry type article with the obligatory fields author, title, journal and year, and with the optional fields volume, number, pages, month and note. Although Ebib indicates on the screen which fields are obligatory and which are optional, it does this purely for convenience: Ebib won't complain if you leave an obligatory field empty. It is BibTeX that will complain.

Note the format of the entry definition above: it starts with a parenthesis, then the keyword defentry, followed by the entry name. Then follows a list of obligatory fields, enclosed in parentheses. Next follows a list of optional fields, also enclosed in parenthesis. Finally, a closing parenthesis follows, which closes the first parenthesis before defentry. If you want to add any comments, you can use a semicolon. All the text after a semicolon up to the end of the line is ignored.

Note that it is legal to leave either the list of obligatory or optional fields empty. Such an entry type simply does not have fields of that particular type. When you do this, put an empty set of parenthesis:


(defentry misc
  ()
  (title author howpublished month year note))

Next to the obligatory and optional fields, it is also possible to define a set of ignored fields. These are fields that BibTeX will normally ignore, but they can be useful for storing additional information. These fields are identical for all entry types, and therefore they do not need to be defined for each entry type separately. Instead, they are defined with a line such as the following:

(ebib-ign-fields crossref url annote abstract keywords)

This defines crossref, url, annote, etc. as ignored fields. They will be made available for all entry types, but they do not have to be filled in. Note again that the entire definition must be enclosed within parentheses. If ~/.ebibrc contains more than one ebib-ign-fields definitions, only the last one is used.

The .ebibrc file also contains three lists of command key definitions. These too are essential, and must not be deleted. (If you delete them, the ebib functions will only be available through `M-x <command>', which is not a very practical way of using Ebib.)

A command key definition is built up as follows:

(ebib-key <buffer> <key> <command>)

<buffer> is either the index, the entry or the strings buffer. <key> is a standard Emacs key description, and <command> is the ebib command to be associated with the key. If you wish to customise the command keys, you will only need to change the <key> specification of the relevant command. Keys are specified as follows:

If you want to use a single letter as a command key, write it in double quotes: ä".
If you want to use a modifier (control, alt/meta or shift), put the entire key definition in square brackets and enclose the modifier(s) with the key in parentheses: [(control p)] means `C-p', [(meta shift p)] means `M-P'. `C-x n' would be written as [(control x) n], and `C-x C-n' would be [(control x) (control n)].
Keys such as Home, PgUp, etc. and the function keys are written in square brackets. Emacs has unusual names for some of them:
These keys can also be modified: [(control f1)] means `C-F1'.

Note that it is possible to bind more than one key to a single function: just add as many ebib-key commands as necessary. (In fact, the standard ebibrc file does this, too.)

Finally, it is possible to have Ebib automatically load a specific .bib file by adding a preload command to the .ebibrc file:

(ebib-preload "/home/user/bibtex/file.bib")

Note that the preload command must appear after the entry definitions: if it appears before the defentry commands, Ebib will not be able to recognise the entry types in the .bib file it is supposed to preload, and will therefore skip all entries, effectively loading nothing.

More than one file can be preloaded. Simply add all the files to the preload command. Note that all files must be enclosed in double quotes, separated by whitespace. They do not have to be on a single line. Make sure, however, that the entire preload command is surrounded by a pair of parentheses:

(ebib-preload "~/bibtex/file1.bib" "~/bibtex/file2.bib")

One thing to keep in mind if you edit the .ebibrc file is that all the keywords and entry and field names must be typed in lower case. Do not use upper case, because Ebib will ignore everything that is written in upper case.⁹

6 Limitations

Obviously, Ebib is not perfect. Some of its more serious limitations are listed here.

It is not possible to add @comment commands to the BibTeX file.
Backward searching is not possible.
Anything you can come up with that never occurred to me...

Footnotes:

¹Note, however, that it is really not a problem to change the type of an entry when some of its fields already have values. If the old entry type had fields that do not exist in the new entry type, their values will be retained and saved, although they are not shown. If you should later change the entry type back, those fields will become visible again.

²More precisely, Ebib stores the field values in memory with braces around them. It removes those braces if the field value is printed on the screen.

³Note that in Emacs key sequences of C-c <letter> are reserved for the user, so no package should have bound them to any function. For the same reason, Ebib does not set this key automatically.

⁴If you do not know what your load path is set to, go to the *scratch* buffer, type load-path on an empty line, put the cursor right after it and type C-j. The value of load-path will then appear in the buffer.

⁵Note that here and everywhere, command keys are case-sensitive; i.e., `g' and `G' run different commands.

⁶This is in fact the only way to delete the @preamble definition. Field values on the other hand, can also be deleted by hitting `x' or `d' on them in the entry buffer.

⁷Note that if you want Ebib to save the database automatically whenever Emacs does its autosave, you can add the function ebib-save-all-databases to Emacs' auto-save-hook.

⁸Actually, I found the BibTeX documentation somewhat lacking on this point. The characters listed here are not allowed in @string abbreviations, but I am not entirely sure if the same counts for the entry types, field names and key. The keys must probably adhere to L^AT_EX's rules for labels etc., but again I have found no documentation explaining what characters can appear in those. If you should know what exactly is and is not allowed, please let me know. If you do not, better err on the side of caution and use only letters, numbers, colon and dash in your keys, and only letters in the entry types and field names.

⁹To be more precise, when reading a .bib file, Ebib converts entry types and field names to lower case. The definitions in .ebibrc are not converted to lower case, however. As a result, entry types or field names defined as upper case will never match an entry type or field name read from a .bib file. Note, by the way, that writing defentry, ebib-ign-fields or ebib-preload in upper case will result in an error from Emacs.

File translated from T_EX by T_TH, version 3.70.
On 18 Aug 2006, 13:51.