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' TeX and LaTeX modes becomes possible. For example, you can push a BibTeX key from Ebib to a LaTeX buffer, or, vice versa, when you're in a LaTeX buffer, you can consult your BibTeX database and insert a key from it into the document. 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.
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)
Note: 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.
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 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 of course choose any key combination you like. (In Emacs, key
combinations of C-c <letter> are reserved for the user, so that no package
may set them.)
It is recommended to byte-compile the source, Ebib runs quite a lot faster
when it is byte-compiled. You can do this 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. Byte-compiling Ebib may
produce a warning about functions that are ``not known to be
defined''. This can be safely ignored. GNU Emacs and XEmacs have some small
differences, and the functions reported in this warning are those used by
the other version. Ebib makes sure that the correct functions are called.
Basic Usage
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 entry 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 Emacs frame 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 move through these keys with the cursor keys. In the entry buffer, the fields of the currently highlighted entry are shown, with their values.
In this chapter, all basic functions of Ebib are described, so that you can get startet with it. At times, reference will be made to later chapters, where more specific functions are described.
Getting Started
Ebib is started with the command M-x ebib. Entering this command hides all
the windows in the current Emacs frame and replaces them with two windows:
the top one contains the index buffer, the bottom one, taking up the larger
part of the screen, contains the entry buffer. The index buffer is named
none, to indicate that no database has been loaded. If you open a database,
or start a new one, the index buffer will carry its name.
You can quit Ebib by typing q. You will be asked for confirmation, and you
will receive a warning if you happen to have an unsaved database. The
command z can also be used to leave Ebib. However, unlike q, which
completely quits Ebib, z only lowers it, so that it remains active in the
background. The .bib files that you have opened remain loaded, and you can
return to them by typing M-x ebib again.
Opening a .bib file
Loading a .bib file into Ebib is done with the command o. Ebib reads the
file that you specify, and reports how many entries it found, how many
@string definitions it found, and whether a @preamble was found. Note that
when Ebib reads a .bib file, it only reads entry types (e.g. book, article,
phdthesis etc.) that it knows about. Fields (e.g. author, title, year etc.)
that Ebib does not know about, are loaded (and saved) but not displayed, so
they cannot be edited. Therefore, you should make sure that all the entry
types and fields that your databases use are defined. A sensible set has
been predefined, so that anyone who's using standard BibTeX entry types
should have no problem loading an existing .bib file into Ebib. If,
however, you have custom entry types, or custom fields in your .bib files,
you should read the chapter on customising Ebib to learn how to define
them, so that Ebib knows about them. (See Entry types.)
Every time Ebib reads a .bib file, it produces a few log messages. These
are written into a special buffer *Ebib-log*. If Ebib encounters entry
types in the .bib file that it doesn't know, it will log a warning. If Ebib
finds something that it believes to be incorrect, an error will be
logged. If any warnings or errors occur while loading the .bib file, Ebib
tells you so after loading the file. To view the log file, press l in the
index buffer.
Note that even if it detects warnings or errors, Ebib will try to continue
parsing the rest of the .bib file. That means that normally, only the entry
in which an error occurs is not read. Entries occurring after the
problematic one are read.
Navigating a .bib file
Once you've opened a .bib file, the keys of all the entries in the file are
shown in alphabetical order in the index buffer in the top Ebib window. (In
fact, it is possible to show more than just the entry key in this
buffer. See Index Display Fields on how to accomplish this.) The first
entry is highlighted, meaning it is the current entry. The fields it holds
and their values are shown in the entry buffer in the bottom Ebib
window. The first field is the type field, which tells you what kind of
entry you're dealing with (i.e. book, article, etc.).
Below the type field, Ebib displays (up to) three sets of fields. The first
set are the so-called obligatory 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 additional fields. These
fields are usually ignored by BibTeX (note that BibTeX normally ignores
all fields it does not know), although there are bibliography styles that
treat some of these fields as optional rather than as additional; (i.e.,
the harvard styles do typeset the url field, if present.)
The first two groups of fields are different for each entry type, while the
third group are common to all entry types. You can use the additional
fields, for example, to add personal comments to the works in your
database. Ebib by default defines the following additional fields:
crossref, url, annote, abstract, keywords, file and timestamp. If these are
not sufficient for you, you need to customise Ebib and add your own
fields. (See Additional Fields, if you need to find out how to do that.)
To move around in the index buffer, you can use the up and down cursor
keys, C-p and C-n, or for those more used to mutt's key bindings, k and
j. Furthermore, Space and PgDn move a screenful of entries down, while b
and PgUp move in the other direction. Lastly, g and Home move to the first
entry, while G and End move to the last one.
Ebib is not restricted to opening just one .bib file at a time. You can
open more files by just typing o again and entering the filename. Ebib
numbers the databases: the number of each database is shown in the mode
line of the index buffer, directly before the database name. The keys 1—9
provide a quick way of jumping from one database to another. 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 move to the last database. If you are done
with a database and want to close it, type c. This closes the current
database. It does not leave Ebib, and all other databases you have open
will remain so.
Starting a New .bib File
If you want to start a new .bib file from scratch, you cannot just go and
enter entries. You first have to give the database a name. So, to start a
new database, type o first, and give the new file a name. Once you have
done this, you can start adding entries to the database.
Editing the Database
Of course, being able to open and view .bib files is only half the fun. One
needs to be able to edit the files as well. Ebib's essential editing
facilities are discussed here.
Adding and Deleting Entries
To add an entry to a database, you type a. When you do this, Ebib first
asks you for an entry key, as every entry must be identified by a unique
key. Just type a name for the new entry (say jones1998). Since the entry
key must be unique, Ebib will complain if you enter a key that already
exists.
Note that if you should later decide that you want to change the key of an
entry, you can do so with the command E. So if you have an entry with the
key jones1998 and you want to add another entry by Jones from 1998, you can
call the new one jones1998b and rename the existing one to jones1998a.
Deleting an entry is done with d. Be careful with this: you will be asked
for confirmation, but once you've confirmed, the entry is gone, and it is
not possible to bring it back. There is no undo in Ebib. (If you haven't
saved the database yet, it is still possible to retrieve the deleted entry
from the .bib file, and otherwise it may still be in the backup file that
Ebib creates. See Saving a Database.)
Editing Fields Values
Editing the field values for an entry is done in the lower of the two Ebib
buffers, the so-called entry buffer. You can move focus to the entry buffer
by typing the command e in the index buffer.
You can move between fields with the same keys that you use to move between
entries in the index buffer: the cursor keys up and down, C-p and C-n, or j
and k. Space and PgDn move to the next set of fields, while PgUp and b move
to the previous set of fields. g and G, and Home and End also work as
expected.
Editing a field value can be done with e. For most fields, Ebib simply asks
you for a string value in the minibuffer. (Here, RET confirms the edit,
while C-g cancels it.) Although BibTeX requires that field values be
surrounded by braces {} (or double quotes "", but Ebib does not use those,
even though it can of course handle them when they are used in an existing
.bib file) you do not need to type these. Ebib adds them when it saves the
.bib file.
Some fields, however, are handled in a special way. The first of these is
the type field: if you edit this field, you must enter one of the
predefined entry types. Ebib won't allow you to enter anything else. You
can use tab-completion in this case. Similarly, if you edit the crossref
field, Ebib requires that you fill in a key from the database. Here, too,
you can use tab-completion.
Note that if you're adding a new entry, Ebib automatically puts you in the
entry buffer after you've typed the entry key: you don't have to type e to
move to the entry buffer. When creating a new entry, it is best to set the
type field first, because the type field determines which other fields are
available for an entry.
Note also that after editing a field, Ebib (usually) puts you on the next field. This is convenient if you're creating a new entry and need to fill out several fields in a row.
If you're done editing the fields of the entry, type q to move focus back
to the index buffer. (Note: keys may have different functions in the index
buffer and the entry buffer. q is a typical example: in the entry buffer,
it quits editing the entry and moves focus back to the index buffer. In the
index buffer, however, q quits Ebib.)
Editing Multiline Values
Apart from the type and crossref field, there is another field that Ebib
handles in a special way when you edit its value. This is the annote
field. Most field values normally consist of a single line of
text. However, because the annote field is meant for creating annotated
bibliographies, it would not be very useful if you could only write one
line of text in this field. Therefore, when you edit the annote field, Ebib
puts you in the so-called multiline edit buffer. This is essentially a text
mode buffer that allows you to enter as much text as you like. To store the
text and leave the multiline edit buffer, type C-x b. (This is of course
the standard Emacs command to switch buffers. It is redefined in Ebib's
multiline edit buffer.)
If you want to leave the multiline edit buffer without saving the text you
have just typed, you can use the command C-x k. This too is redefined in
the multiline edit buffer: it leaves the multiline edit buffer (and hides
it), but it does not actually kill the buffer.
Multiline values are not restricted to the annote field. Any field can in
fact hold a multiline value. (Except of course the type and crossref
fields.) To give a field a multiline value, use l instead of e. You will
again be put in the multiline edit buffer, where you can edit the
value. Note that you can use l even if a field already has a single line
value. Ebib will just make that the first line in the multiline edit
buffer.
When a field has a multiline value, only the first line is shown in the
entry buffer, for space reasons. To indicate that the value is multiline, a
plus sign + is placed in front of the value.
By the way, the e key is smart about the way an entry must be edited. If
you press e on a field that already has a multiline value, regardless of
the fact whether it is the annote field or not, Ebib puts you in the
multiline edit buffer. Therefore, you need l only if you want to give a
field a multiline value when it doesn't have one yet.
For more details on working with the multiline edit buffer, see The Multiline Edit Buffer.
Copy, cut, paste (yank), and delete
A few more commands are available when you're in the entry buffer editing
field values. The commands c, x and y implement a copy and paste system: c
copies the contents of the current field to the kill ring, x kills the
contents of the current field to the kill ring, and y yanks (pastes) the
most recently killed text in the kill ring. You can type y repeatedly to
get the same effect you get in Emacs when you type M-y after an initial
C-y: every additional use of y moves back in the kill ring.
Lastly, there is the command d, which deletes the contents of the current
field, without asking questions and without storing the text in the kill
ring.
Note that y only works when the current field does not have a value
yet. This is to prevent you from accidentally overwriting a field value. If
you do want to yank text into a field that already has a value, simply hit
d first to delete the text.
Saving a Database
When you have undertaken any kind of editing action on a database, it is
marked as modified, which is indicated in the mode line for the index
buffer. A modified database can be saved by typing s. This saves the
database to the file it was loaded from without asking for
confirmation. (It is similar to C-x C-s in Emacs.) If you're saving a file
for the first time after loading it, Ebib creates a backup file under the
same name appended with a tilde: <filename>.bib~.
If you have multiple databases open, have made changes in more than one of
them, and want to save all of them without going through each yourself, you
can use S. (That's a capital S.) This command saves all modified databases.
Another way to save a database is to use the command w. Use this if you
want to write the database to another file than the one it was loaded
from. Ebib will ask you for a filename to save to, and will of course warn
you if that file happens to exist already. Note that this command is
similar to C-x C-w in Emacs, so that after using it, the new .bib file
becomes associated with the database.
Searching
Ebib provides several search methods. First, if you are in the index
buffer, the normal Emacs incremental searches, C-s and C-r, function as
expected. You can use them to search entry keys. Note that once you've
found the key you're searching, you must hit ENTER to make it active. Ebib
does not update the entry buffer during incremental search, as this would
be rather pointless: you're only interested in the entry you're searching
for, not in the entries you pass along the way.
Of course, it is also possible to search the database itself. If you type
/, Ebib asks you for a search term. This can be a regular expression, to
allow for flexibility in searching. After hitting ENTER, Ebib will start
searching the database (starting from the current entry, not from the first
entry!) and will display the entry with the first occurrence of the search
string that it finds. All the occurrences of the search string in that
entry are highlighted.
Ebib searches all the fields of each entry. It is not possible with / to
specify the fields to search. Note that if the search term is found in a
field with a multiline value, Ebib will highlight the + sign that it
displays in front of the field value. Keep an eye out for this when doing a
search, because Ebib only shows the first line of multiline values, and if
the search term appears in another line, the highlighted + is the only
indication that the search term was found. (Well, that and the fact that
Ebib does not say Search string not found, of course...)
A search term may of course appear more than once in the database. To
search for the next occurrence, type n. This will continue searching for
the search string in the rest of the database. Again, the first entry found
to contain the search string is displayed. Note that n does not wrap: if
the end of the database is reached, Ebib stops searching. To continue
searching from the top, hit g and then n.
The functions described here form Ebib's basic search functionality. Ebib also has a much more powerful search mechanism in the form of virtual databases. These are described later. (See Virtual Databases.)
LaTeX Integration
Having a BibTeX database manager running inside Emacs has an additional advantage: it makes it trivially easy to insert BibTeX keys in your LaTeX documents.
Ebib provides two functions for this. First, if you're in a LaTeX buffer, you
can call the function ebib-insert-bibtex-key. When you invoke this command,
Emacs prompts you for a key from the database(s) associated with the current
buffer, a citation command (that has to be typed without the backslash) and any
optional argument(s) the command allows. You can type the key using
TAB-completion, and after hitting RET, Emacs puts a BibTeX citation at the
cursor position in the current buffer with the key you selected.
You can also do it the other way around: if you're in the index buffer in Ebib,
you can push an entry to a LaTeX buffer. To do this, use the key p. Ebib will
ask you for a buffer to push the entry to, a citation command and also any
optional arguments, and then insert a citation at the current cursor position in
the buffer you've supplied.
For the citation command that ebib-insert-bibtex-key and the command key p ask
for can be any command that you need. But it is also possible to predefine a
list of citation commands which you can then enter at this prompt using tab
completion. For details on setting this up, see Insertion Commands.
There is another function that is available outside Ebib:
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.
Probably the easiest way to use both ebib-insert-bibtex-key and
ebib-entry-summary is to bind them to a key sequence. For example, you
could put the following in your ~/.emacs:
(add-hook 'LaTeX-mode-hook #'(lambda ()
(local-set-key "\C-cb" 'ebib-insert-bibtex-key)))
This binds C-c b to the command ebib-insert-bibtex-key in AUCTeX's LaTeX
mode. (Note that commands of the form C-c <letter> are reserved for the
user, and should therefore not be set by any package. For this reasons,
Ebib does not set this command automatically.)
Consulting databases from within a LaTeX file
The commands ebib-insert-bibtex-key and ebib-entry-summary must consult the
database or databases loaded in Ebib, and Ebib tries to be smart about
which database(s) to consult. Usually, a LaTeX file has a \bibliography
command somewhere toward the end, which names the .bib file or files that
contain the bibliography entries. If you consult a BibTeX database from
within a LaTeX file, Ebib first looks for a \bibliography command, reads
the .bib files from it, and then sees if those files happen to be open. If
they are, Ebib uses them to let you pick an entry key (in the case of
ebib-insert-entry-key) or to search for the entry (in the case of
ebib-entry-summary).
Of course, it may be the case that the LaTeX file is actually part of a
bigger project, and that only the master file contains a \bibliography
command. To accommodate for this, Ebib checks whether the (buffer-local)
variable TeX-master is set to a filename. If it is, it reads that file and
tries to find the \bibliography command there. (Note: TeX-master is an
AUCTeX variable, which is used to keep track of multi-file projects. If you
don't use AUCTeX, this functionality doesn't work, and Ebib will only check
the current file for a \bibliography command.)
Note that if one of the .bib files in the \bibliography command isn't
loaded, Ebib issues a warning message about this, and continues to check
for the next .bib file. These warning messages appear in the minibuffer,
but are probably directly overwritten again by further messages or prompts
Ebib produces, so check the *Messages* buffer if Ebib doesn't seem to be
able to find an entry that you're sure is in one of your databases.
Another thing to keep in mind is that Ebib only looks for a \bibliography
command once: the first time either ebib-insert-bibtex-entry or
ebib-entry-summary is called. It stores the result of this search and uses
it the next time either of these commands is used. Therefore, if you make a
change to the \bibliography command, you must reload the file (use M-x
revert-buffer) to make sure Ebib rereads the \bibliography command.
If no \bibliography command is found at all, either in the LaTeX file
itself, or in the master file, Ebib simply consults the current database,
i.e. the database that was active when Ebib was lowered with z.
Cross-referencing
BibTeX has a cross-referencing facility. Suppose you have an entry jones1998,
which appeared in a book that is also in your database, say under miller1998.
You can tell BibTeX that jones1998 is contained in miller1998 by putting
miller1998 in the crossref field. When BibTeX finds such a cross-reference, all
the fields of jones1998 that don't have a value inherit their values from
miller1998. At the very least, this saves you some typing, but more importantly,
if two or more entries cross-reference the same entry, BibTeX automatically
includes the cross-referenced entry in the bibliography (and puts a reduced
reference in the cross-referencing entries).
When you fill in the crossref field in Ebib, Ebib displays the values of the
cross-referenced entry in the entry buffer. To indicate that they are just
inherited values, they are marked with ebib-crossref-face, which by default is
red. (You can customise it, of course. See the customisation option
Crossref Face.) These values are just displayed for convenience: otherwise, Ebib
treats these fields as if they are empty. That is, they cannot be edited (to
edit them, you need to edit the cross-referenced entry), and it's not possible
to copy these values to the kill ring.
If you're viewing an entry that has a cross-reference and you want to go to the
cross-referenced entry you can type F. This command reads the value of the
crossref field and then displays that entry. If you want to do the reverse,
i.e., see if the current entry is cross-referenced by any other entries, you can
use the key N. What this command actually does is to make the key of the current
entry the current search string and to search for its first occurrence after the
current entry. Like the normal search command /, N does not wrap and only
searches forward. So if you want to search for the next cross-referencing entry
you need to press n (i.e., lowercase n), and to continue searching from the
first entry, press g followed by n.
Note that if you want to use BibTeX's cross-referencing options, you need to set
the option Save Xrefs first. This tells Ebib to save all entries with a crossref
field first in the .bib file. Without this, BibTeX's cross-referencing will not
work reliably.
Printing the Database
Sometimes it may be useful to have a .pdf file or print-out of your
database. Although Ebib does not actually do the printing itself, it can
create a LaTeX file for you that you can compile and print. In fact, there
are two ways of doing this.
The first is the command L. This command creates a simple LaTeX document
that essentially contains a \nocite{*} command followed by a
\bibliography command referring to the .bib file belonging to
the current database. You can then run the usual sequence of LaTeX, BibTeX,
LaTeX, LaTeX on this file, creating a document containing a list of all the
references in your database.
The second command for printing a database is P. This command also creates
a LaTeX file. However, instead of simply providing a
\nocite{*} command, P creates a tabular environment for each
entry in the database listing all the fields of that entry and their
values.
The difference between L and P should be obvious: with L, you get a list of
references created by BibTeX. This means that the references look the way
they will when actually used in a document, but it also means that the list
only contains the information that BibTeX deems relevant.
With P you get an overview of your database with all the field values of
each entry, including the ones that BibTeX does not use. The entries are
not formatted as literature references, but in a way similar to how they
are shown in Ebib.
By default, P only shows single-line field values. That is, multiline
values are normally excluded. If you want to include multiline values in
the print-out, you have to set the option Print Multiline in Ebib's
customisation buffer. (See The Customisation Buffer.) With this option set,
Ebib will include all multiline values in the LaTeX file that P
creates. Note however that Ebib does not change anything about the
formatting of the text in a multiline value. So if you plan to make (heavy)
use of this option, make sure that the way you type your text conforms to
LaTeX's conventions (e.g. empty lines to mark paragraphs, etc.) and doesn't
contain any characters such as & that are illegal in LaTeX. (Or,
alternatively, use LaTeX code in your multiline fields.)
As mentioned, when you use either L or P, Ebib creates a LaTeX file. More
precisely, it creates a temporary buffer and writes the LaTeX code into it,
and then saves the contents of that buffer to a file. After it has done
that, Ebib lowers itself and instruct Emacs to open the file in a buffer,
which will then be properly set up as a LaTeX buffer. From there you can
run LaTeX and view the result.
Before doing all this, Ebib asks you which file to write to. Be careful with this: since this is supposed to be a temporary file, Ebib simply assumes that if you provide a filename of an existing file, it can overwrite that file without warning!
A better way to tell Ebib which file to use is to set the option Print
Tempfile in Ebib's customisation buffer to some temporary file. When this
option is set, Ebib will always use this file to write to, and will not ask
you for a filename anymore when you type L or P.
There are two more customisation options for printing the database. These
are Print Preamble and LaTeX Preamble. With these options, you can specify
what Ebib should put in the preamble of the LaTeX files it creates. Use
this if you want to use specific packages
(e.g. \usepackage{a4} or
\usepackage{times}). This is especially useful for L, since by
default, Ebib uses BibTeX's standard bibliography style. With the option
LaTeX Preamble you can set your preferred bibliography style. Details are
discussed in the chapter on customisation, see The Customisation Buffer.
Marking Entries
Commands in the index buffer generally operate on one single entry, or on
all entries. For some, however, it may sometimes be useful to perform them
on more than one entry, but not necessarily all of them. This can be
achieved by marking entries. You can mark the entries you want to perform a
command on with the key m. This marks (or unmarks) the current
entry. Marked entries are displayed in inverse video (in GNU Emacs) or
white on red (in XEmacs; note that the face properties of marked entries
can be customised through the customisation option Marked Face.)
Of the commands discussed so far, four can be used on marked entries: d, p,
L and P. Note, however, that it is not enough to mark the entries you want
and then type any of these commands. If you do so, they will behave as if
no entries were marked. To get these commands to work on the marked
entries, you have to type a semicolon before them. That is, ; d deletes all
marked entries, and ; L and ; P create a LaTeX file of only the marked
entries. The command m itself can also be used with the ; prefix. If there
are any marked entries, ; m unmarks them all. Otherwise, ; m marks all
entries.
; p pushes all marked entries to a LaTeX buffer. It does so by putting them
all in a single \cite command, separated by commas, not by putting them in
separate \cite commands.
Calling a Browser
With more and more scientific literature becoming available on-line, it becomes common to store URLs in a BibTeX database. Sometimes you may want to load such a URL in your browser. Ebib provides a convenient way for doing so.
If you type u in the index buffer, Ebib takes the first URL stored in the
url field of the current entry and passes it to your browser. Furthermore,
in the entry buffer, you can use u on any field. If you happen to have more
than one URL stored in the relevant field, and you want to pass the second
(or third, etc.) to the browser, you can use a prefix argument. So typing
M-2 u sends the second URL to your browser, M-3 u the third, and so on.
It is not even necessary that the relevant field contains only URLs. It may
contain other text mixed with the URLs: Ebib simply searches the URLs in
the field and ignores the rest of the text. Ebib considers every string of
characters that starts with http:// or https:// and that does not contain
whitespace or any of the characters " ' < or > as a URL. Furthermore, Ebib
regards everything that is enclosed in a LaTeX \url{...}
command as a URL. This behaviour is controlled by a regular expression that
can be customised. (See Url Regexp.)
There exists an Emacs function browse-url, which provides a nifty interface
to calling an external browser. In principle, Ebib uses this
function. However, if this function is not present on your installation,
you can set the option Browser Command to call the browser.
As just explained, if you press u in the index buffer, Ebib searches the
url field of the current entry for URLs. If you have the habit of putting
your URLs in another field, however, you may change the customisation
option Standard Url Field and tell Ebib to use another field for searching
the URLs. (Keep in mind, though, that in the entry buffer, you can load a
URL from any field.)
Viewing Files
If you have electronic versions of the papers in your database stored on
your computer, you can use Ebib to call external viewers for these
files. The interface for this is similar to that for calling a browser: if
you press f in the index buffer, Ebib searches the file field for a
filename and when it finds one, calls an appropriate viewer.
Just as with u, you can use f in the entry buffer as well, in which case it
can be used on any field, not just the file field. It is also possible to
have more than one filename in a field: you can select the one you want to
view with the prefix argument.
Just as in the case of URLs, you can customise several things about the
file view functionality. The option Standard File Field allows you to
customise the field that f extracts filenames from when pressed in the
index buffer. Extracting filenames is done with a regular expression, which
can be customised through the option File Regexp.
The option File Search Dirs allows you to tell Ebib which directories it
needs to search for files. The default value is ~, which means Ebib just
looks in your home dir. Since this is probably not where you keep your
files, you may want to customise this. Note that you can specify more than
one directory.
Note that Ebib does not search directories recursively. It is possible,
however, to put subdirectories in the filenames. That is, if you put
something like a/abney1987.pdf in the file field, Ebib searches for the
relevant file in a subdirectory a/ of the directories listed in the option
File Search Dirs. (Note that if you want to do this under Windows, you may
want to remove the backslash from the file regexp.)
Ebib can call different external programs depending on the file type of the
relevant file, but you have to specify which programs to call. The option
File Associations allows you to do this. By default, .pdf and .ps files are
handled, by xpdf and gv, respectively. You can specify further file types by
their extensions (do not include the dot). The program is searched for in
PATH, but you can of course specify the full path to the program.
Advanced Features
The features discussed in the previous chapter should be sufficient to get started using Ebib. However, Ebib has several more advanced features, which are described in this chapter.
Screen Layout
By default, Ebib takes over the entire Emacs frame it is started in. If you have a wide enough screen, however, it may be more convenient to have Ebib take up only part of the frame, so that you can have the LaTeX text you're working on and Ebib visible at the same time. The option Layout allows you to do this, by giving you the ability to choose between a full-frame or a split-frame layout.
In the split-frame layout, the Ebib windows are displayed on the right of the current frame, with the left part free for your document. In this layout, some aspects of Ebib behave somewhat differently. Most importantly, the multiline edit buffer is not displayed in the lower Ebib window, but in the non-Ebib window on the left. (Obviously, after leaving the multiline edit buffer, the original buffer is restored to that window.)
Furthermore, pressing z in the index buffer leaves Ebib, but keeps the
buffers visible. You can get back to Ebib with the command M-x ebib (or any
key bound to it, of course), or simply by manually switching to the index
buffer. If you want to remove the Ebib buffers from the frame but keep Ebib
in the background, you can use Z (i.e. capital Z) in the index
buffer. (Note that Z is also available in the full-frame layout, but there
it is identical to z.)
Lastly, the command ebib-entry-summary checks whether the Ebib buffers are
visible in the frame. If they are, it does not output the entry info in a
*Help* buffer, but rather displays the entry in Ebib itself.
Preloading .bib Files
Chances are that you will be doing most of your work with one or a few .bib
files, and you may find yourself opening the same file or files every time
you start Ebib. If so, you can tell Ebib to always load specific .bib files
on startup. To do this, specify the files in Ebib's customisation buffer,
under the option Preload Bib Files.
@Preamble Definition
Apart from database entries, BibTeX allows three more types of elements to
appear in a .bib file. These are @comment, @preamble and @string
definitions. Ebib provides facilities to handle the latter two. @comment
definitions cannot be added to a .bib file through Ebib, and if Ebib finds
one in a .bib file, it is simply ignored.
@preamble and @string definitions can be handled, however. Ebib allows you
to add one @preamble definition to the database. In principle, BibTeX
allows more than one such definition, but really one suffices, because you
can use the concatenation character # to include multiple TeX or LaTeX
commands. So, rather than having two @preamble definitions such as:
@preamble{ "\newcommand{\noopsort}[1]{} " }
@preamble{ "\newcommand{\singleletter}[1]{#1} " }
you can write this in your .bib
file:
@preamble{ "\newcommand{\noopsort}[1]{} "
# "\newcommand{\singleletter}[1]{#1} " }
Creating or editing a @preamble definition in Ebib is done by hitting r in
the index buffer. Ebib uses the multiline edit buffer for editing the text
of the @preamble definition, which means that as discussed above, C-x b
stores the @preamble text and returns focus to the index buffer, while C-x
k returns focus to the index buffer while abandoning any changes you may
have made. (For details on using the multiline edit buffer, see
The Multiline Edit Buffer.)
In order to create a @preamble as shown above in Ebib, you only have to
type the text between the braces. Ebib takes care of including the braces
of the @preamble command, but otherwise it saves 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} "
Note that when Ebib loads a .bib file that contains more than one @preamble
definition, it concatenates all the strings in them in the manner just
described and saves them in one @preamble definition.
@String Definitions
If you press t in the index buffer, Ebib hides the entry buffer in the
lower window and replaces it with the strings buffer. In this buffer, you
can add, delete and edit @string definitions.
Adding a @string definition is done with the command a. This will first ask
you for an abbreviation and then for the value to be associated with that
abbreviation. Once you've entered these, Ebib will sort the new
abbreviation into the buffer.
Moving between the @string definitions can be done in the usual way: the
cursor keys up and down, C-p and C-n and k and j move up and down. Space
and PgDn move ten strings down, while b and PgUp move in the other
direction. The keys g, G, Home and End also function as expected.
To delete a @string definition, use d. To edit the value of a definition,
use e. There is also a command c, which copies the value of the current
@string definition to the kill ring. Unlike in the entry buffer, there are
no corresponing commands y and x. (In fact, x does exist, but has another
function.) Yanking from the kill ring can be done with C-y/M-y in the
minibuffer when you edit a @string's value. Cutting a @string's value
is pointless, because a @string definition must have a value.
Having defined @string definitions, there must of course be a way to use
them. Just giving a field a string abbreviation as value will not do,
because Ebib puts braces around the value that you enter when it writes the
.bib file, so that BibTeX will not recognise the abbreviation, and will not
expand it. BibTeX will only recognise an abbreviation if it appears in the
.bib file outside of any braces.
To accomplish this, you must mark a field's value as raw. A raw field is a
field whose value is not surrounded by braces when the database is saved,
so that BibTeX recognises it as an abbreviation. To mark a field raw, press
r. An asterisk will appear before the field, indicating that it is
raw. Pressing r again will change the field back to normal. If you press r
on a field that does not have a value yet, Ebib will ask you for one.
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.
An easy way to enter a @string abbreviation as a field value is to use the
key s instead of e. If you type s, Ebib asks you for a @string abbreviation
to put in the current field, and automatically marks the field as raw. With
this command, Ebib only accepts @string definitions that are in the
database, so that by using s you can make sure you don't make any
typos. Note that you can use tab completion to complete a partial string.
Sorting the .bib file
By default, the entries in the database are saved to the .bib file in
alphabetical order according to entry key. If you only deal with the .bib
file through Ebib, you may not care in which order the entries are
saved. However, it may sometimes be desirable to be able to specify the
sort order of entries in more detail. (Apparently, this can be useful with
ConTeXt, for example.)
You can specify a sort order in Ebib's customisation buffer. To sort the
entries, you must set at least one sort level (that is, a field to sort the
entries on). You can also specify more than one sort level: if two entries
have identical values for the first sort level, they will be sorted on the
second sort level. E.g., if the first sort level is author and the second
is year, then the entries are sorted by author, and those entries that have
identical values for the author field are sorted by year.
A sort level is not restricted to a single field. You can specify more
fields for a single sort level. Within a single sort level, a second sort
field is used if the first sort field does not have a value. For example,
books that have an editor instead of an author will have an empty author
field. If you sort the database on the author field, such entries will all
appear at the beginning of the .bib file, which is most likely not what you
want.
To remedy this, you can specify both the author and the editor fields for
the first sort level. Ebib will then sort an entry on its author field if
it has a value, and will otherwise use the value of the editor field.
The difference between two sort fields within one sort level and two sort levels is that a second sort field is an alternative for the first field when it has no value, while a second sort level is an additional sort criterion when two or more entries cannot be sorted on the first level, because they have identical values.
By default, the option Sort Order has no value, which means that the
entries in the .bib file are sorted according to entry key. Those that wish
to customise the sort order will usually want to set the first sort level
to author editor, and the second to year. In that way, the entries in the
.bib file are sorted according to author/editor, and entries with the same
author/editor are sorted by year.
Entries that cannot be sorted on some sort level, because the sort fields are empty, are sorted on entry key. (Keep in mind that if the first sort level yields no value for a specific entry, Ebib does not use the second sort level to sort that entry. It uses the entry key. The second sort level is only used if the first yields identical values for two or more entries.)
Note that if you have set the option Save Xrefs First (see
Cross-referencing), it is pointless to set a sort order. Saving
cross-referencing entries first messes up any sort order, so Ebib simply
ignores the sort order if Save Xrefs First is set.
Merging and Importing
As described in the previous chapter, adding entries to a database can be
done manually with the key a. There are other ways of adding entries to a
database, however.
With the command M you can merge a second .bib file into your current
database. When you hit M, you are asked for a filename. Ebib then reads the
entries in this file and adds them to the database. Duplicate entries (that
is, entries with an entry key that already exists in the database) will not
be loaded. Ebib logs a warning about each duplicate entry to its log
buffer, and displays a warning after loading the .bib file when this
happens.
Another way to add entries to a database is to import them from an Emacs
buffer. If, for example, you find ready-formatted BibTeX entries in a text
file or e.g. on the internet, you can copy & paste them to any Emacs buffer
(e.g. the *scratch* buffer), and then execute the command M-x
ebib-import. Ebib then goes through the buffer and loads all BibTeX entries
it finds into the current database (i.e. the database that was active when
you lowered Ebib). If you call ebib-import while the region is active, Ebib
only reads the BibTeX entries in the region.
Exporting Entries
Sometimes it can be useful to copy entries from one database to another, or
to create a new .bib file with several entries from an existing
database. For this purpose, Ebib provides exporting facilities. To export
an entry to a .bib file, use the command x. Ebib will ask you for a
filename to export the entry to. (If you have already exported an entry
before, Ebib will present the filename you used as default, but you can of
course change it.)
For obvious reasons, Ebib appends the entry to the file that you enter if it already exists, it does not overwrite the file. If this is not what you want, delete the file first, as Ebib provides no way to do this.
If you have more than one database open in Ebib, it is also possible to
copy entries from one database to another. To do this, use the x command
with a numeric prefix argument. E.g., if the database you want to export an
entry to is the second database, type M-2 x to export the current entry to
it. The number of the database is given in the modeline of the index
buffer.
If the database you're copying an entry to already contains an entry with the same entry key, Ebib won't copy the entry, and issues an appropriate warning message.
Note that the command x can operate on marked entries. So to export several
entries in one go mark them and type ; x. You can use a prefix argument in
the normal way: M-2 ; x exports the marked entries to database 2.
Apart from entries, it is also possible to export the @preamble and @string
definitions. The @preamble definition is exported with the command X in the
index buffer. @string definitions can be exported in the strings buffer: x
in this buffer exports the current string, while X exports all @string
definitions in one go. All these commands function in the same way: when
used without a prefix argument, they ask for a filename, and then append
the relevent data to that file. With a numeric prefix argument, they copy
the relevant data to the corresponding open database.
Timestamps
Ebib provides the possibility to add a timestamp to every new entry,
recording the time it was added to the database. The timestamp is recorded
in the (additional) field timestamp. (By default, this field is not shown,
but you can make it visible by pressing H in the index buffer.)
You can tell Ebib to create timestamps by setting the option Use Timestamp
in Ebib's customisation buffer. With this option set, a timestamp is
included in entries added to the database with a. Ebib will also add a
timestamp to entries imported from a buffer or merged from a file, and to
entries exported to another database or to a file. When importing or
exporting entries, existing timestamps will be overwritten. The logic
behind this is that the timestamp records the date and time when the entry
was added to the database, not when it was first created.
Note that if this option is unset, the timestamp of an entry is retained when it's imported or exported. Therefore, if you record timestamps and want to im-/export entries without changing their timestamps, temporarily unset this option.
Ebib uses the function format-time-string to create the timestamp. The
format string that Ebib uses can be customised in Ebib's customisation
buffer. The default string is "%a %b %e %T %Y", which produces a timestamp
of the form "Mon Mar 12 01:03:26 2007". Obviously, this string is not
suited for sorting, so if you want to be able to sort on timestamps, you'll
need to customise the format string. See the documentation for
format-time-string on the options that are available.
Multiple Identical Fields
Under normal circumstances, a BibTeX entry only contains one occurrence of each field. If BibTeX notices that an entry contains more than one occurrence of an obligatory or optional field, it issues a warning. Ebib is somewhat less gracious, it simply takes the value of the last occurrence without giving any warning. (Note, by the way, that BibTeX will use the value of the first occurrence, not the last.) When additional fields appear more than once in an entry, BibTeX does not warn you, since it ignores those fields anyway. Here, too, Ebib's standard behaviour is to ignore all but the last value.
However, some online reference management services ``use'' this feature of
BibTeX in that they put multiple keywords fields in the BibTeX entries that
they produce. If you were to import such an entry into Ebib, you would lose
all your keywords except the last one. To remedy this, you can tell Ebib
that it should allow multiple occurrences of a single field in a BibTeX
entry. You can do this by setting the customisation option
Allow Identical Fields.
With this option set, Ebib collapses the multiple occurrences into a single
occurrence. All the values of the different occurrences are collected and
stored in the single occurrence, separated by semicolons. That is, Ebib
does not retain the multiple occurrences, but it does retain the values. So
suppose you have an entry that contains the following keywords fields:
@book{jones1998,
author = {Jones, Joan},
year = {1998},
...
keywords = {sleep},
keywords = {winter},
keywords = {hybernation}
}
If you load this entry into Ebib with the option Allow Identical Fields
set, you will get the following:
@book{jones1998,
author = {Jones, Joan},
year = {1998},
...
keywords = {sleep; winter; hybernation}
}
Virtual Databases
In the previous chapter, Ebib's basic search functionality was discussed. (See Searching.) Ebib also provides a much more sophisticated search and filtering mechanism in the form of virtual databases.
A virtual database is a database that is not associated with any .bib
file. Rather, it is created from another database by selecting entries from
it based on a specific search pattern, called a filter. This allows you,
for example, to select all entries from a database that contain the string
``Jones'' in their author field. A filter can be as complex as you want:
you can select all entries that do not contain ``Jones'' in the author
field, or all entries that contain ``Jones'' in either the author or the
editor field, or all entries that contain ``Jones'' in the author field,
and ``symbiotic hybernation'' in the keyword field, etc. Basically, the
filter can consist of an arbitray number of search criteria combined with
the logical operators and, or and not.
Simple Selection
Creating a virtual database is simple: press &, and Ebib will ask you for a
field to select on, and for a regular expression to select with. So if you
want to select all entries that contain ``Jones'' in the author field, you
press & and type author as the field and Jones as the regexp to filter on.
Ebib will then create a virtual database containing the entries matching
your selection criterion. A virtual database has the same name as the
database it is based on, prepended with V:. It also has a number like any
other database, and you can move back and forth to other databases with the
number or cursor keys.
If you don't want to filter on one specific field but rather want to select
all entries that match a certain regexp in any field, you can type any as
the field to filter on. So specifying any as the field and Jones as the
regexp, the virtual database will select all entries that have a field that
contains ``Jones'' in them.
Complex Filters
Once you have a virtual database, it remains associated with the database
it was created from. This means that you can refine or extend the selection
(i.e. the filter) that the virtual database is based on. If, in the current
example, you want to include all the entries that have ``Jones'' in the
editor field, you have to perform a logical or operation: you want to
select an entry if it contains ``Jones'' in the author field (which you
already did) or if it contains ``Jones'' in the editor field.
A short sidenote: the first impulse in a case like this might be to use and
instead of or: after all, you want to select all entries that contain
``Jones'' in the author field and all entries that contain ``Jones'' in the
editor field. However, the filter that you build up is used to test each
entry individually whether it meets the selection criterion. An entry meets
the criterion if it contains ``Jones'' in the author field or if it
contains ``Jones'' in the editor field. Therefore, or is the required
operator in this case. If you would use and, you would only get those
entries that contain ``Jones'' in both the author and editor fields.
To perform a logical or operation, press the key |. As before, you will be
asked which field you want to filter on, and which regexp you want to
filter with. Ebib will then update the virtual database with all entries in
the original database that match the additional criterion.
It is also possible to perform a logical and on the virtual database. Use
this if you want to select those entries that contain ``Jones'' in the
author field and e.g. ``symbiotic hybernation'' in the keyword field. A
logical and operation is done with the key &. (Note: this is the same key
that is used to create a virtual database. In fact, you can also create a
virtual database with |: when used in a normal database, & and | are
equivalent. They are only different in virtual databases.)
Both the & and | commands can be used with the negative prefix argument M--
(or C-u -, which is identical). In this case, the search criterion is
negated. That is, the negative prefix argument performs a logical not
operation on the search criterion.
That is, if you want to select all entries from a database that do not
contain ``Jones'' in the author field, you can do this by typing M-- & and
then filling out the relevant field and regexp. This prefix argument is
available both in real and in virtual databases.
There is another way of performing a logical not operation, which is only
available in virtual databases: by pressing the key ~, you invert the
current filter. That is, if you have a virtual database with all the
entries containing ``Jones'' in the author or in the editor field, and you
press ~, the selection is inverted, and now contains all entries that do
not have ``Jones'' in the author or editor field.
Although ~ and the negative prefix argument to & or | both perform logical
not operations, they are not equivalent: ~ negates the entire filter built
up so far, while the negative prefix argument only negates the single
selection criterion you enter with it.
If you want to know what the filter for the current virtual database is
exactly, you can type V. This command displays the current filter in the
minibuffer. The filter is specified as a Lisp expression, meaning that the
operators appear before their operands, not in between them. That is, x and
y is written as (and x y).
With a prefix argument (any prefix argument will do), the command V not
only displays the current filter, but also reapplies it. This can be useful
when you've made changes to the source database: Ebib does not
automatically update a virtual database when its source database is
modified.
Properties of Virtual Databases
Virtual databases differ from normal databases in several ways. First, they cannot be modified: you cannot add or delete entries, and you cannot modify the contents of fields. It is also not possible to import entries to them or merge another file with them. Furthermore, it is not possible to export entries to them or from them.
A virtual database cannot be saved in the normal way with s, and the
command S to save all databases ignores virtual databases. If you want to
save a virtual database, you can use the command w. This command not only
saves the virtual database, it also changes it into a normal database, and
detaches it from its original source database, so that you can modify it
without affecting the source database.
The command L also doesn't work with virtual databases. The reason for this
is that the virtual database is not associated with an actual .bib file, so
there is no file to create a list of references from. However, it is
possible to use the command P with a virtual database to create a list of
entries. See Printing the Database, for details on these two commands.
The Multiline Edit Buffer
As mentioned several times before, 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. This section discusses the details of this buffer.
Ebib enters multiline edit mode in one of three cases: when you press P in
the index buffer, to edit the @preamble definition, when you hit l in the
entry buffer to edit the current field as multiline, or when you hit e on
the annote field, or on a field 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
leaves the multiline edit buffer without storing the text, i.e., the
original value of the field or preamble that you were editing is
retained. If the text in the buffer was modified, C-x k asks you if you
really want to abandon your changes.
If you leave the multitiline 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 preambleis deleted. (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.)
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.
The Ebib Buffers
This chapter lists all the key commands that exist in Ebib, with a short description and the actual command that they call. The latter information is needed if you want to customise Ebib's key bindings. (See Modifying Key Bindings.)
The Index Buffer
Up- go to previous entry.
(ebib-prev-entry) Down- go to next entry.
(ebib-next-entry) Right- move to the next database.
(ebib-next-database) Left- move to the previous database.
(ebib-prev-database) PgUp- scroll the index buffer down.
(ebib-index-scroll-down) PgDn- scroll the index buffer up.
(ebib-index-scroll-up) Home- go to first entry.
(ebib-goto-first-entry) End- go to last entry.
(ebib-goto-last-entry) Return- make the entry under the cursor current. Use after e.g.
C-s.(ebib-select-entry) Space- equivalent to
PgDn. 1-9- jump to the corresponding database.
/- search the database.
(ebib-search) &- Create a virtual database, or perform a logical
andon the current virtual database. With negative prefix argument: apply a logicalnotto the selectional criterion.(ebib-virtual-db-and) |- Create a virtual database, or perform a logical
oron the current virtual database. With negative prefix argument: apply a logicalnotto the selectional criterion.(ebib-virtual-db-or) ~- Perform a logical
noton the current virtual database.(ebib-virtual-db-not) a- add an entry.
(ebib-add-entry) b- equivalent to
Pgup. c- close the database.
(ebib-close-database) C- customise Ebib.
(ebib-customize) d- delete the current entry.
(ebib-delete-entry) ; d- delete all marked entries.
e- edit the current entry.
(ebib-edit-entry) E- edit the key of the current entry.
(ebib-edit-keyname) f- extract a filename from the
filefield and send it to an appropriate viewer. With numeric prefix argument, extract the n-th filename. F- follow
crossreffield.(ebib-follow-crossref) g- equivalent to
Home. G- equivalent to
End. H- show/hide hidden fields.
(ebib-toggle-hidden) j- equivalent to
Down. J- jump to another database. This accepts a numeric prefix argument,
but will ask you for a database number if there is
none.
(ebib-switch-to-database) k- equivalent to
Up. l- show the log buffer. (
ebib-show-log) L- create a LaTeX file from the current database that produces a list
of references formatted by BibTeX.
(ebib-latex-database) ; L- create a LaTeX file with the marked entries only.
m- mark (or unmark) the current entry.
(ebib-mark-entry) ; m- unmark all marked entries.
M- merge a
.bibfile.(ebib-merge-bibtex-file) n- find next occurrence of the search string.
(ebib-search-next) N- search for entries cross-referencing the current one.
(ebib-search-crossref) C-n- equivalent to
Down. M-n- equivalent to
PgDn. o- open a
.bibfile.(ebib-load-bibtex-file) p- push an entry to a LaTeX buffer
(ebib-push-bibtex-key) ; p- push the marked entries to a LaTeX buffer.
C-p- equivalent to
Up. M-p- equivalent to
PgUp. P- create a LaTeX file for printing the database, listing the entire
contents of each entry.
(ebib-print-database) ; P- create a LaTeX file with the marked entries.
r- show and edit the
@preambledefinition in the database.(ebib-edit-preamble) q- quit Ebib. This sets all variables to nil, unloads the database(s)
and quits Ebib.
(ebib-quit) s- save the database.
(ebib-save-current-database) S- save all modified databases.
(ebib-save-all-databases) t- show and edit the
@stringdefinitions in the database.(ebib-edit-strings) u- extract a URL from the
urlfield and send it to a browser. With numeric prefix argument, extract the n-th url. V- Display the filter of the current virtual database in the
minibuffer. With prefix argument: reapply the filter.
(ebib-print-filter) w- write the database to a different file.
(ebib-write-database) x- export the current entry to a file, or, when used with numeric
prefix argument, to another database.
(ebib-export-entry) ; x- export the marked entries to a file, or, when used with a numeric prefix argument, to another database.
C-x b- equivalent to
z. C-x k- equivalent to
q. X- export the
@preambledefinition to a file or, when used with a numeric prefix argument, to another database.(ebib-export-preamble) z- move focus away from the Ebib windows.
(ebib-leave-ebib-windows) Z- put Ebib in the background.
(ebib-lower)
One function is not bound to any key: ebib-print-filename.
The Entry Buffer
Up- go to the previous field.
(ebib-prev-field) Down- go to the next field.
(ebib-next-field) PgUp- go to the previous set of fields.
(ebib-goto-prev-set) PgDn- go to the next set of fields.
(ebib-goto-next-set) Home- go to the first field.
(ebib-goto-first-field) End- go to the last field.
(ebib-goto-last-field) Space- equivalent to
PgDn. b- equivalent to
PgUp. c- copy the contents of the current field to the kill
ring.
(ebib-copy-field-contents) d- delete the value of the current field. The deleted contents will not
be put in the kill ring, and is therefore irretrievably
lost.
(ebib-delete-field-contents) e- edit the current field.
(ebib-edit-fields) f- extract a filename from the current field and send it to an appropriate viewer. With numeric prefix argument, extract the n-th filename.
g- equivalent to
Home. G- equivalent to
End. j- go to the next field.
(ebib-next-field) k- go to the previous field.
(ebib-prev-field) l- edit the current field as multiline.
(ebib-edit-multiline-field) C-n- equivalent to
Down. M-n- equivalent to
PgDn. C-p- equivalent to
Up. M-p- equivalent to
PgUp. q- quit editing the current entry and return focus to the index
buffer.
(ebib-quit-entry-buffer) r- toggle a field's ``raw'' status.
(ebib-toggle-raw) s- insert an abbreviation from the
@stringdefinitions in the database.(ebib-insert-abbreviation) u- extract a URL from the current field and send it to a browser. With numeric prefix argument, extract the n-th url.
x- cut the contents of the current field. Like
c,xputs the contents of the current field in the kill ring.(ebib-cut-field-contents) y- yank the last element in the kill ring to the current
field. Repeated use of
yfunctions likeC-y/M-y. Note that no text will be yanked if the field already has a value.(ebib-yank-field-contents)
The Strings Buffer
Up- go to the previous string.
(ebib-prev-string) Down- go to the next string.
(ebib-next-string) PgUp- go ten strings up.
(ebib-strings-page-up) PgDn- go ten strings down.
(ebib-strings-page-down) Home- go to the first string.
(ebib-goto-first-string) End- go to the last string.
(ebib-goto-last-string) Space- equivalent to
PgDn. a- add a new
@stringdefinition.(ebib-add-string) b- equivalent to
PgUp. c- copy the text of the current string to the kill
ring.
(ebib-copy-string-contents) d- delete the current
@stringdefinition from the database. You will be asked for confirmation.(ebib-delete-string) e- edit the value of the current string.
(ebib-edit-string) g- equivalent to
Home. G- equivalent to
End. j- equivalent to
Down. k- equivalent to
Up. l- edit the value of the current string as
multiline.
(ebib-edit-multiline-string) C-n- equivalent to
Down. M-n- equivalent to
PgDn. C-p- equivalent to
Up. M-p- equivalent to
PgUp. q- quit the strings buffer and return focus to the index
buffer.
(ebib-quit-strings-buffer) x- export the current
@stringdefinition to a file or, when used with a prefix argument, to another database.(ebib-export-string) X- export all the
@stringdefinitions to a file or, when used with a prefix argument, to another database.(ebib-export-all-strings)
Customisation
Ebib can be customised through Emacs' standard customisation interface. The
only thing that cannot be customised in this way are the key bindings. If
you wish to customise those, you have to use the file ~/.ebibrc.
The Customisation Buffer
Ebib's customisation group is a subgroup of the Tex group. It can be
invoked by typing M-x customize-group RET ebib RET, or by pressing C in
the index buffer. This chapter gives a short description of all the options
available in the customisation buffer.
Default Type
The default type is the default entry type given to a new entry. Every
entry in the Ebib database must have a type, because the type defines which
fields are available. When a new entry is created, Ebib gives it a default
type, which can be customised through this option. The standard value is
article.
Preload Bib Files
This option allows you to specify which file(s) Ebib is to load when it
starts up. Specify one file per line, press the INS button to add more
files. You can complete a partial filename with M-TAB.
Additional Fields
The additional fields are those fields that are available for all entry
types, and which BibTeX generally ignores. This option allows you to
specify which additional fields you wish to use in your database. Specify
one field per line, press the INS button to add more fields.
By default, the following additional fields are defined: crossref, url,
annote, abstract, keywords, file and timestamp.
Layout
The default value of this option is full, which means that Ebib takes over
the entire frame when it runs. Alternatively, you can select to specify a
width (in characters) yourself, in which case Ebib takes up the right part
of the frame, leaving the left part free. See Screen Layout for details.
Index Window Size
This option lets you specify the size of the index window at the top of the Ebib screen. The default value is 10.
Index Display Fields
This option allows you to specify fields that should be displayed next to the entry key in the index buffer. By default, the index buffer only shows the key of each entry, but if this is too little information, you can use this option to display e.g. the title of each entry as well.
Insertion Commands
With the command ebib-insert-bibtex-key or with the command key p in the index
buffer, you can insert a BibTeX key into a LaTeX buffer. This option allows you
to define the commands that are available through tab completion when these
functions ask for a citation command.
The citation commands must be given without the leading backslash, as Ebib adds one. Furthermore, you need to specify how many optional arguments each command can have. When Ebib prompts you for a citation key, it will ask for as many optional arguments as you specify here. (If you don't want to be asked for those optional arguments, just fill in 0.)
When Ebib prompts you for a citation command, the commands specified in this option can be obtained through tab completion. However, it is not necessary to fill in a command from this list here. You can also enter another command (in which case Ebib asks for exactly one optional argument) or even no command at all. In the latter case, Ebib does not ask for any optional arguments and simply puts the key in the buffer without adding a backslash or curly braces.
Sort Order
The use of this option is explained above, see Sorting the .bib file. To
create a sort order, click the INS button to create a sort level, and then
click the INS button under that sort level to enter a sort field. If you
want to add more than one sort field to the sort level, simply hit INS
again.
Save Xrefs First
For cross-referencing to work, the cross-referencing entries must appear in
the .bib file before the cross-referenced entries. In order to tell Ebib to
save all entries with a crossref field first, you must set the option Save
Xrefs First in Ebib's customisation buffer. With this option set, BibTeX's
crossreferencing options work as intended.
By default, this option is unset, because it (marginally) slows down saving
the .bib file somewhat.
Crossref Face
Field values inherited from a cross-referenced entry are marked with this face. By default, the face has red as foreground colour.
Marked Face
When entries are marked (with m), they are highlighted in this face. By
default, GNU Emacs uses the text property highlight. XEmacs only allows
this on terminals, therefore it displays marked entries with a red
background and a white foreground colour. This option allows you to change
these defaults.
Use Timestamp
If this option is set, Ebib will add a timestamp field to every new entry,
recording the date and time it was added to the database. See Timestamps.
Timestamp Format
This option specifies the format string that is used to create the
timestamp. The format string is used by format-time-string to create a time
representation. The default value is "%a %b %e %T %Y", which produces a
timestamp of the form "Mon Mar 12 01:03:26 2007". See the documentation for
format-time-string for the forms that the format string can take.
Standard Url Field
This is the field that Ebib searches for URLs if you press u in the index
buffer. Its default value is url.
Url Regexp
This is the regular expression that Ebib uses to search for URLs in a field. The default value is:
\\url{\(.*\)}\|https?://[^ '<>\"\n\t\f]+
With this regular expression, Ebib considers everything that is in a LaTeX
\url{...} command as a URL, and furthermore every string of
text that starts with http:// or https:// and does not contain whitespace
or one of the characters ' " < or >.
Browser Command
If this option is unset (which is the default), Ebib uses the Emacs
function browse-url to start a browser. If this function does not exist,
you can set this option. For example, if you use the Firefox browser, set
this option to firefox.
For this to work, the browser that you use must be able to handle a URL on the command line.
Standard File Field
This is the field that Ebib searches for filenames if you press f in the
index buffer. Its default value is file.
File Associations
The programs used to view files. By default, programs for .pdf and .ps
files are specified, which should be available on most linux systems. If
you prefer other programs or are running on Windows, you'll can specify
them here. Note that Ebib searches the PATH for the programs, but you can
also specify full path names. Of course, it is also possible to add new
associations.
Note that GNU/Emacs 23 (as yet unreleased) comes with doc-view-mode, which
provides a way to view .pdf and .ps files inside Emacs. (The files are
converted to .png format first.) If you prefer to use this mode, simply
leave the program field blank for the relevant file type.
File Regexp
In order to find files in a field, Ebib uses a regular expression. The default value is:
[^?|\:*<>\" \n\t\f]+
This essentially means that every string of characters not containing any of the characters
? | \ : * < > "
or space, newline, tab of formfeed. URLs can easily by recognised by the
prefix http:, but recognising files is not so straightforward. It is
therefore not advisable to put anything but filenames in the file field.
File Search Dirs
This is the list of directories that Ebib searches for files. Note that searching is not recursive: only the files listed here are searched, not their subdirectories.
Print Preamble
This option specifies the preamble that is to be added to the LaTeX file
Ebib creates for printing the database (i.e., the P command). By default,
the preamble is empty. You can set your own \usepackage
commands, or anything else you may need.
Print Multiline
When this options is set, Ebib includes multiline field values when it
creates a LaTeX file with P (ebib-print-database). When unset, multiline
values are excluded, which saves space. By default, this option is unset.
Latex Preamble
This option specifies the preamble to be added to the LaTeX file for
creating a list of references from the database (i.e., the L command). By
default, the line \bibliographystyle{plain} is put in the
preamble, but you may want to specify your own BibTeX packages and options.
Print Tempfile
This option specifies the name and location of the temporary file Ebib
creates with the commands ebib-print-database and
ebib-latex-database. By default, this option has no value,
which means that Ebib will ask for a filename each time either of these
commands is called.
Allow Identical Fields
If this option is set, Ebib stores the values of multiple occurrences of a
single field within an entry in a single occurrence of that field,
separated by semicolons. By default, this option is unset, because it slows
down the loading of .bib files. See Multiple Identical Fields.
Entry Types
This option allows you to customise the entry types that Ebib uses. Each entry type has a name, a set of obligatory fields and a set of optional fields. You can add, alter or delete single fields in an entry type, or whole entry types.
If you want to add an entry type, hit the INS key on the top level and give
the new entry a name, then add obligatory and/or optional fields. It is not
necessary that an entry type has both obligatory and optional fields, you
can define an entry that has only obligatory or only optional fields.
Modifying Key Bindings
If you are unhappy about Ebib's standard key bindings, you can change them
to anything you like. To do this, you have to create a file ~/.ebibrc and
write your preferred key bindings in it. A key binding definition is built
up as follows:
(ebib-key <buffer> <key> <command>)
<buffer> is either index, entry or strings, for the corresponding
buffer. <key> is a standard Emacs key description, and <command> is the
Ebib command to be associated with the key. The commands that can be used
here are listed in The Ebib Buffers. Note that it is possible to bind more
than one key to a single function: just add as many ebib-key statements as
necessary.
As an example, the following binds C-s to ebib-search in the index buffer,
so that the database can be searched with C-s as well as with /:
(ebib-key index "\C-s" ebib-search)
If you want to unbind a key, you can simply leave out <command>. So if you
want to bind the command ebib-delete-entry to D rather than d, you need to
put the following in .ebibrc:
(ebib-key index "D" ebib-delete-entry) (ebib-key index "d")
The first line binds D to the command ebib-delete-entry. The second line
unbinds d.
If a command can be called with a prefix key (as for example
ebib-delete-entry can), ebib-key will automatically rebind the prefixed
version as well. So in the example above, the first line not only binds D,
it also binds ; D. Similarly, the second line not only unbinds d, but also
; d.
It is also possible to redefine the prefix key itself. To do this, you must
specify mark-prefix for <buffer>. The value of <command> is irrelevant
here, so it can be left out:
(ebib-key mark-prefix ":")
This sets up : as the new prefix key. Doing this automatically unbinds the
existing prefix key.