ebib-find-entry-key definition moved.

[ebib.git] / manual / ebib-manual.muse

#author Joost Kremers
#title Ebib Manual
#disable-tables t

<div id="menu">

<contents>

</div>

<div id="main">

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):

<example>
(autoload 'ebib "ebib" "Ebib, a BibTeX database manager." t)
</example>

On a default installation, the load path probably only contains system
directories. If you want to put =ebib.el= somewhere in your home directory, you
can create a directory and add it to your load path:

<example>
(setq load-path (cons "~/.emacs.d" load-path))
</example>

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:

<example>
(global-set-key "\C-ce" 'ebib)
</example>

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:

<example>
emacs -batch -f batch-byte-compile ebib.el
</example>

(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.

Ebib has a menu through which most functions can be accessed. Especially some of
the lesser used functions can only be accessed through the menu (unless you
assign key shortcuts to them, of course.)


** 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 define them. This can be done by
selecting "Options | Modify Entry Types" from the Ebib menu. (See also the
chapter on customising Ebib, esp. [[#entry-types][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][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][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-database][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=. (In fact, in the entry buffer, =ENTER=
is equivalent to =e=.) For most fields, Ebib simply asks you for a string value in
the minibuffer. (Here, =ENTER= 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-c | q=.

If you want to leave the multiline edit buffer without saving the text you have
just typed, type =C-c | c=. This command cancels the edit and leaves the multiline
edit buffer. The text that is stored in the field you were editing is not
altered.

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
[[#multiline-edit-buffer][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 storing the text in the kill ring. (It asks for confirmation, though,
just to make sure.)

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
#saving-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 save
all databases at once through the menu.

The menu also provides a way to save the database to another name. 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
#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][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 =ENTER=, 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 command =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.

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][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=:

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

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
#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][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][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.


** 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][Marked Face]].)

Of the commands discussed so far, two can be used on marked entries: =d= 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, =; p= pushes all
marked entries to a LaTeX buffer. 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.

When using =; p= to push all marked entries to a LaTeX buffer, they are put in a
single citation command, separated by commas. Ebib does not create a citation
command for each entry separately.


** Printing the Database
#printing-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 print options are available in the Ebib menu when the index buffer is
active. You can print the entries as index cards or as a bibliography.

If you print your entries as a bibliography, Ebib creates a simple LaTeX
document that essentially contains a <verb>\nocite{*}</verb> command followed by
a <verb>\bibliography</verb> 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.

If you choose to print as index cards, Ebib also creates a LaTeX file. However,
instead of simply providing a <verb>\nocite{*}</verb> command, this file
contains a =tabular= environment for each entry in the database listing all the
fields of that entry and their values.

The entries are separated by a =\bigskip=, but if you set the option =Print Newpage=
in the customisation buffer (or in the Print menu), the entries are separated by
a =\newpage=, so that every entry is on a separate page. The latter option is
useful when printing actual index cards (though you'd probably have to change
the page size with the =geometry= package as well).

By default, the index cards only show 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 the Options menu
or in Ebib's customisation buffer. (See [[#customisation-buffer][The Customisation Buffer]].) With this
option set, Ebib includes all multiline values in the LaTeX file that it
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 "print" the database, Ebib really just 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.

Note that both print options operate on all entries of the database. If there
are marked entries in the database, however, only those are printed.

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. <verb>\usepackage{a4}</verb> or
<verb>\usepackage{times})</verb>. This is especially useful for printing a
bibliography, 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
[[#customisation-buffer][The Customisation Buffer]].



** 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 <verb>\url{...}</verb> command as
a URL. This behaviour is controlled by a regular expression that can be
customised. (See [[#url-regexp][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][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][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][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][File Regexp]].

The option [[#file-search-dirs][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][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
#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][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. uppercase =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][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 (and dropped from the file when you save it).

=@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:

<example>
@preamble{ "\newcommand{\noopsort}[1]{} " }
@preamble{ "\newcommand{\singleletter}[1]{#1} " }
</example>

<literal style="texinfo">@noindent</literal>you can write this in your =.bib=
file:

<example>
@preamble{ "\newcommand{\noopsort}[1]{} "
         # "\newcommand{\singleletter}[1]{#1} " }
</example>

Creating or editing a =@preamble= definition in Ebib is done by hitting =P=
(uppercase =P=) 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-c | q= stores the =@preamble= text and returns focus to the index buffer,
while =C-c | c= returns focus to the index buffer while abandoning any changes you
may have made. (For details on using the multiline edit buffer, see
[[#multiline-edit-buffer][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:

<example>
"\newcommand{\noopsort}[1]{} "
# "\newcommand{\singleletter}[1]{#1} "
</example>

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 =S= (that's a uppercase =S=) 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:

<example>
@string{WGA = "World Gnus Almanac"}
</example>

<literal style="texinfo">@noindent</literal>you can create a BibTeX field like
this:

<example>
title = 1966 # WGA
</example>

<literal style="texinfo">@noindent</literal>which will produce "1966 World Gnus
Almanac". Or you can do:

<example>
month = "1~" # jan
</example>

<literal style="texinfo">@noindent</literal>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
#sorting-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][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.

In the index buffer, the Ebib menu has an option to merge a second .bib file
into the current database. Ebib 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
#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 checking the option "Show Hidden Fields" in the Options
menu.)

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
#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][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:

<example>
@book{jones1998,
    author = {Jones, Joan},
    year = {1998},
    ...
    keywords = {sleep},
    keywords = {winter},
    keywords = {hybernation}
}
</example>

If you load this entry into Ebib with the option =Allow Identical Fields= set, you
will get the following:

<example>
@book{jones1998,
    author = {Jones, Joan},
    year = {1998},
    ...
    keywords = {sleep; winter; hybernation}
}
</example>


** Virtual Databases
#virtual-databases

In the previous chapter, Ebib's basic search functionality was discussed. (See
[[#searching][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 menu option
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 print bibliography command 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 print index cards frm a virtual database.


** The Multiline Edit Buffer
#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 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 mode that is used in the multiline edit buffer is user-configurable. The
default value is =text-mode=, but if you prefer to use some other mode, you can
specify this through the customization options. (Personally, I use =markdown-mode=
in the multiline edit buffer, so that I can use [[http://daringfireball.net/projects/markdown/][markdown]] to write annotations,
which provides an easy way to create headers, use bold and italic, etc., in
plain text.)

Three commands are relevant for interacting with Ebib when you're in the
multiline edit buffer. These are =ebib-quit-multiline-edit=,
=ebib-save-from-multiline-edit= and =ebib-cancel-multiline-edit=. These commands are
bound to key sequences through the minor mode ebib-multiline-edit-mode, which is
activated automatically in the multiline edit buffer.

=ebib-quit-multiline-edit=, bound to =C-c | q=, leaves the multiline edit buffer and
stores the text in the database. If you invoke this command when you've deleted
all contents of the buffer (including the final newline!) and you were editing a
field value or the =@preamble=, the field value or preamble is 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.)
If you were editing a =@string= value, Ebib will just complain, because string
definitions cannot be empty.

=ebib-cancel-multiline-edit=, bound to =C-c | c=, also leaves the multiline edit
buffer, but it does so without storing the text. The original value of the
field, string or preamble will be retained. If the text was modified, Ebib will
ask for a confirmation before leaving the buffer.

=ebib-save-from-multiline-edit=, bound to =C-c | s=, can be used in the multiline
edit buffer to save the database. This command first stores the text in the
database and then saves it. 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 this command has been
provided to allow you to do this from within the buffer.

It is possible to change the second key of these commands, if you find =|=
inconvenient. See [[#modifying-key-bindings][Modifying Key Bindings]] for
details.


** The Options Menu
In the index buffer, Ebib's menu has an Options submenu. This menu gives you
quick access to Ebib's customisation buffer, and it also provides checkboxes for
several settings that can be toggled on and off. All of these settings have
defaults that can be defined in the customisation buffer. Setting or unsetting
them in the Options menu only changes them for the duration of your Emacs
session, it doesn't affect the default setting.

The same is true for the printing options that are in the Print menu. When set
or unset in the menu, the default values specified in the customisation buffer
do not change.


* The Ebib Buffers
#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][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 =and= on the current
virtual database. With negative prefix argument: apply a logical =not= to the
selectional criterion. =(ebib-virtual-db-and)=

  =|= :: Create a virtual database, or perform a logical =or= on the current
virtual database. With negative prefix argument: apply a logical =not= to the
selectional criterion. =(ebib-virtual-db-or)=

  =~= :: Perform a logical =not= on 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)=
  
  =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 =file= field and send it to an appropriate
viewer. With numeric prefix argument, extract the *n*-th filename.

  =F= :: follow =crossref= field. =(ebib-follow-crossref)=

  =g= :: equivalent to =Home=.

  =G= :: equivalent to =End=.

  =h= :: show the info node on the index buffer. (=ebib-index-help=)

  =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=)

  =m= :: mark (or unmark) the current entry. =(ebib-mark-entry)=

  =; m= :: unmark all marked entries.

  =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 =.bib= file. =(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= :: show and edit the =@preamble= definition 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= :: show and edit the =@string= definitions in the database.
=(ebib-edit-strings)=

  =u= :: extract a URL from the =url= field 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)=

  =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 =@preamble= definition 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)=

Functions not bound to any key: =ebib-print-filename=, =ebib-customize=,
=ebib-merge-bibtex-file=, =ebib-write-database=, =ebib-save-all-databases=,
=ebib-print-entries=, =ebib-latex-entries=, =ebib-toggle-hidden=,
=ebib-toggle-timestamp=, =ebib-toggle-identical-fields=,
=ebib-toggle-print-multiline=, =ebib-toggle-layout=.


** 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=.

  =h= :: show the info node on the entry buffer. (=ebib-entry-help=)

  =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 =@string= definitions 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=, =x= puts 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 =y= functions like =C-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 =@string= definition. =(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 =@string= definition 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=.

  =h= :: show the info node on the strings buffer. (=ebib-strings-help=)

  =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 =@string= definition to a file or, when used with a
prefix argument, to another database. =(ebib-export-string)=
  
  =X= :: export all the =@string= definitions to a file or, when used with a prefix
argument, to another database. =(ebib-export-all-strings)=


* Customisation
#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
#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 going to the Options menu and
selecting "Customize Ebib". 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
#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
#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
#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 =custom=, in which case
you can specify the width of the Ebib windows yourself. In this case, Ebib takes
up the right part of the frame, leaving the left part free. See [[#screen-layout][Screen Layout]]
for details.


*** Width

The width of the Ebib windows when =ebib-layout= is set to =custom=. Default value
is 80.


*** 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
#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
#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 should 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.


*** Multiline Major Mode

This specifies the major mode used in the multiline edit buffer. The default
value is =text-mode=. Note that the value *must* be a command for a major mode.


*** Sort Order

The use of this option is explained above, see [[#sorting-bib-file][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
#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
#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
#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][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
#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
#url-regexp

This is the regular expression that Ebib uses to search for URLs in a field. The
default value is:

<example>
\\url{\(.*\)}\|https?://[^ '<>\"\n\t\f]+
</example>

With this regular expression, Ebib considers everything that is in a LaTeX
<verb>\url{...}</verb> 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
#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
#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
#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
#file-regexp

In order to find files in a field, Ebib uses a regular expression. The default
value is:

<example>
  [^?|\:*<>\" \n\t\f]+
</example>

This essentially means that every string of characters not containing any of the
characters

<example>? | \ : * < > "</example>

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
#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 as index cards. By default, the preamble is
empty. You can set your own <verb>\usepackage</verb> commands, or anything else
you may need.


*** Print Newline

With this option set, Ebib puts every entry on a separate page when printing
index cards. When this option is unset (the default), the entries are separated
by a small amount of whitespace only.


*** Print Multiline

When this options is set, Ebib includes multiline field values when you print
index cards . 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. By default, the line
<verb>\bibliographystyle{plain}</verb> 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
#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][Multiple Identical Fields]].


*** Entry Types
#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
#modifying-key-bindings

If you are unhappy about Ebib's standard key bindings and would like to change
them, or if you would like to bind a command that is only available through the
menu to a key, you can do so by creating a file =~/.ebibrc= and writing your
preferred key bindings in it. A key binding definition is built up as follows:

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

=<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
[[#ebib-buffers][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 =/=:

<example>
(ebib-key index "\C-s" ebib-search)
</example>

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=:

<example>
(ebib-key index "D" ebib-delete-entry)
(ebib-key index "d")
</example>

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=.

Note that if you bind the print commands to a key (=ebib-print-entries= and
=ebib-latex-entries=) they are automatically set up to accept the prefix key as
well.

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:

<example>
(ebib-key mark-prefix ":")
</example>

This sets up =:= as the new prefix key. Doing this automatically unbinds the
existing prefix key.

As a final option, =ebib-key= allows you to redefine the second key in the key
bindings of the multiline edit buffer:

<example>
(ebib-key multiline "&")
</example>

This piece of code changes the commands =C-c | q=, =C-c | c= and =C-c | s= to =C-c & q=,
=C-c & c= and =C-c & s=, respectively.

</div>