This is /home/joost/programs/ebib/manual/texi/ebib-manual.info,
produced by makeinfo version 4.12 from
/home/joost/programs/ebib/manual/texi/ebib-manual.texi.

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Ebib: (ebib).           A BibTeX database manager that runs in Emacs and XEmacs
END-INFO-DIR-ENTRY


File: ebib-manual.info,  Node: Top,  Next: Installation,  Prev: (dir),  Up: (dir)

Overview
********

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.

* Menu:

* Installation::
* Basic Usage::
* Advanced Features::
* The Ebib Buffers::
* Customisation::


File: ebib-manual.info,  Node: Installation,  Next: Basic Usage,  Prev: Top,  Up: Top

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


File: ebib-manual.info,  Node: Basic Usage,  Next: Advanced Features,  Prev: Installation,  Up: Top

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

* Menu:

* Getting Started::
* Editing the Database::
* Saving a Database::
* Searching::
* LaTeX Integration::
* Cross-referencing::
* Printing the Database::
* Marking Entries::
* Calling a Browser::
* Viewing Files::


File: ebib-manual.info,  Node: Getting Started,  Next: Editing the Database,  Prev: Basic Usage,  Up: Basic Usage

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

* Menu:

* Opening a `.bib' file::
* Navigating a `.bib' file::
* Starting a New `.bib' File::


File: ebib-manual.info,  Node: Opening a `.bib' file,  Next: Navigating a `.bib' file,  Prev: Getting Started,  Up: Getting Started

2.1.1 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 *note 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.


File: ebib-manual.info,  Node: Navigating a `.bib' file,  Next: Starting a New `.bib' File,  Prev: Opening a `.bib' file,  Up: Getting Started

2.1.2 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 *note 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 *note 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.


File: ebib-manual.info,  Node: Starting a New `.bib' File,  Prev: Navigating a `.bib' file,  Up: Getting Started

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


File: ebib-manual.info,  Node: Editing the Database,  Next: Saving a Database,  Prev: Getting Started,  Up: Basic Usage

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

* Menu:

* Adding and Deleting Entries::
* Editing Fields Values::
* Editing Multiline Values::
* Copy::


File: ebib-manual.info,  Node: Adding and Deleting Entries,  Next: Editing Fields Values,  Prev: Editing the Database,  Up: Editing the Database

2.2.1 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 *note Saving a
Database: saving-database.)


File: ebib-manual.info,  Node: Editing Fields Values,  Next: Editing Multiline Values,  Prev: Adding and Deleting Entries,  Up: Editing the Database

2.2.2 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.)


File: ebib-manual.info,  Node: Editing Multiline Values,  Next: Copy,  Prev: Editing Fields Values,  Up: Editing the Database

2.2.3 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
*note The Multiline Edit Buffer: multiline-edit-buffer.


File: ebib-manual.info,  Node: Copy,  Prev: Editing Multiline Values,  Up: Editing the Database

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


File: ebib-manual.info,  Node: Saving a Database,  Next: Searching,  Prev: Editing the Database,  Up: Basic Usage

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


File: ebib-manual.info,  Node: Searching,  Next: LaTeX Integration,  Prev: Saving a Database,  Up: Basic Usage

2.4 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 *note Virtual
Databases: virtual-databases.)


File: ebib-manual.info,  Node: LaTeX Integration,  Next: Cross-referencing,  Prev: Searching,  Up: Basic Usage

2.5 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 *note 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':


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

* Menu:

* Consulting databases from within a LaTeX file::


File: ebib-manual.info,  Node: Consulting databases from within a LaTeX file,  Prev: LaTeX Integration,  Up: LaTeX Integration

2.5.1 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'.


File: ebib-manual.info,  Node: Cross-referencing,  Next: Printing the Database,  Prev: LaTeX Integration,  Up: Basic Usage

2.6 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 *note 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 *note 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.


File: ebib-manual.info,  Node: Printing the Database,  Next: Marking Entries,  Prev: Cross-referencing,  Up: Basic Usage

2.7 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 *note The Customisation
Buffer: 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 *note The Customisation Buffer: customisation-buffer.


File: ebib-manual.info,  Node: Marking Entries,  Next: Calling a Browser,  Prev: Printing the Database,  Up: Basic Usage

2.8 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 *note
Marked Face: 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.


File: ebib-manual.info,  Node: Calling a Browser,  Next: Viewing Files,  Prev: Marking Entries,  Up: Basic Usage

2.9 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 *note 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 *note 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 *note 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.)


File: ebib-manual.info,  Node: Viewing Files,  Prev: Calling a Browser,  Up: Basic Usage

2.10 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 *note 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 *note File Regexp: file-regexp.

   The option *note 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 *note 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.


File: ebib-manual.info,  Node: Advanced Features,  Next: The Ebib Buffers,  Prev: Basic Usage,  Up: Top

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

* Menu:

* Screen Layout::
* Preloading `.bib' Files::
* `@Preamble' Definition::
* `@String' Definitions::
* Sorting the `.bib' file::
* Merging and Importing::
* Exporting Entries::
* Timestamps::
* Multiple Identical Fields::
* Virtual Databases::
* The Multiline Edit Buffer::


File: ebib-manual.info,  Node: Screen Layout,  Next: Preloading `.bib' Files,  Prev: Advanced Features,  Up: Advanced Features

3.1 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 *note 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.
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.


File: ebib-manual.info,  Node: Preloading `.bib' Files,  Next: `@Preamble' Definition,  Prev: Screen Layout,  Up: Advanced Features

3.2 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 *note Preload Bib Files:
preload-bib-files.


File: ebib-manual.info,  Node: `@Preamble' Definition,  Next: `@String' Definitions,  Prev: Preloading `.bib' Files,  Up: Advanced Features

3.3 `@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 *note The Multiline Edit Buffer:
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.


File: ebib-manual.info,  Node: `@String' Definitions,  Next: Sorting the `.bib' file,  Prev: `@Preamble' Definition,  Up: Advanced Features

3.4 `@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.


File: ebib-manual.info,  Node: Sorting the `.bib' file,  Next: Merging and Importing,  Prev: `@String' Definitions,  Up: Advanced Features

3.5 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 *note
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.


File: ebib-manual.info,  Node: Merging and Importing,  Next: Exporting Entries,  Prev: Sorting the `.bib' file,  Up: Advanced Features

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


File: ebib-manual.info,  Node: Exporting Entries,  Next: Timestamps,  Prev: Merging and Importing,  Up: Advanced Features

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


File: ebib-manual.info,  Node: Timestamps,  Next: Multiple Identical Fields,  Prev: Exporting Entries,  Up: Advanced Features

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


File: ebib-manual.info,  Node: Multiple Identical Fields,  Next: Virtual Databases,  Prev: Timestamps,  Up: Advanced Features

3.9 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 *note 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:


     @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}
     }


File: ebib-manual.info,  Node: Virtual Databases,  Next: The Multiline Edit Buffer,  Prev: Multiple Identical Fields,  Up: Advanced Features

3.10 Virtual Databases
======================

In the previous chapter, Ebib's basic search functionality was
discussed. (See *note 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'.

* Menu:

* Simple Selection::
* Complex Filters::
* Properties of Virtual Databases::


File: ebib-manual.info,  Node: Simple Selection,  Next: Complex Filters,  Prev: Virtual Databases,  Up: Virtual Databases

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


File: ebib-manual.info,  Node: Complex Filters,  Next: Properties of Virtual Databases,  Prev: Simple Selection,  Up: Virtual Databases

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


File: ebib-manual.info,  Node: Properties of Virtual Databases,  Prev: Complex Filters,  Up: Virtual Databases

3.10.3 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 *note Printing the Database:
printing-database, for details on these two commands.


File: ebib-manual.info,  Node: The Multiline Edit Buffer,  Prev: Virtual Databases,  Up: Advanced Features

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


File: ebib-manual.info,  Node: The Ebib Buffers,  Next: Customisation,  Prev: Advanced Features,  Up: Top

4 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
*note Modifying Key Bindings: modifying-key-bindings.)

* Menu:

* The Index Buffer::
* The Entry Buffer::
* The Strings Buffer::


File: ebib-manual.info,  Node: The Index Buffer,  Next: The Entry Buffer,  Prev: The Ebib Buffers,  Up: The Ebib Buffers

4.1 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)'

*`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 `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/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 `.bib' file. `(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 `.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'*
     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 `@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'*
     save all modified databases. `(ebib-save-all-databases)'

*`t'*
     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)'

*`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 `@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)'

   One function is not bound to any key: `ebib-print-filename'.


File: ebib-manual.info,  Node: The Entry Buffer,  Next: The Strings Buffer,  Prev: The Index Buffer,  Up: The Ebib Buffers

4.2 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 `@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)'


File: ebib-manual.info,  Node: The Strings Buffer,  Prev: The Entry Buffer,  Up: The Ebib Buffers

4.3 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'.

*`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)'


File: ebib-manual.info,  Node: Customisation,  Prev: The Ebib Buffers,  Up: Top

5 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'.

* Menu:

* The Customisation Buffer::
* Modifying Key Bindings::


File: ebib-manual.info,  Node: The Customisation Buffer,  Next: Modifying Key Bindings,  Prev: Customisation,  Up: Customisation

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

* Menu:

* Default Type::
* Preload Bib Files::
* Additional Fields::
* Layout::
* Index Window Size::
* Index Display Fields::
* Insertion Commands::
* Sort Order::
* Save Xrefs First::
* Crossref Face::
* Marked Face::
* Use Timestamp::
* Timestamp Format::
* Standard Url Field::
* Url Regexp::
* Browser Command::
* Standard File Field::
* File Associations::
* File Regexp::
* File Search Dirs::
* Print Preamble::
* Print Multiline::
* Latex Preamble::
* Print Tempfile::
* Allow Identical Fields::
* Entry Types::


File: ebib-manual.info,  Node: Default Type,  Next: Preload Bib Files,  Prev: The Customisation Buffer,  Up: The Customisation Buffer

5.1.1 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'.


File: ebib-manual.info,  Node: Preload Bib Files,  Next: Additional Fields,  Prev: Default Type,  Up: The Customisation Buffer

5.1.2 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'.


File: ebib-manual.info,  Node: Additional Fields,  Next: Layout,  Prev: Preload Bib Files,  Up: The Customisation Buffer

5.1.3 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'.


File: ebib-manual.info,  Node: Layout,  Next: Index Window Size,  Prev: Additional Fields,  Up: The Customisation Buffer

5.1.4 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 *note
Screen Layout: screen-layout. for details.


File: ebib-manual.info,  Node: Index Window Size,  Next: Index Display Fields,  Prev: Layout,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Index Display Fields,  Next: Insertion Commands,  Prev: Index Window Size,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Insertion Commands,  Next: Sort Order,  Prev: Index Display Fields,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Sort Order,  Next: Save Xrefs First,  Prev: Insertion Commands,  Up: The Customisation Buffer

5.1.8 Sort Order
----------------

The use of this option is explained above, see *note Sorting the .bib
file: sorting-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.


File: ebib-manual.info,  Node: Save Xrefs First,  Next: Crossref Face,  Prev: Sort Order,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Crossref Face,  Next: Marked Face,  Prev: Save Xrefs First,  Up: The Customisation Buffer

5.1.10 Crossref Face
--------------------

Field values inherited from a cross-referenced entry are marked with
this face. By default, the face has red as foreground colour.


File: ebib-manual.info,  Node: Marked Face,  Next: Use Timestamp,  Prev: Crossref Face,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Use Timestamp,  Next: Timestamp Format,  Prev: Marked Face,  Up: The Customisation Buffer

5.1.12 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
*note Timestamps: timestamps.


File: ebib-manual.info,  Node: Timestamp Format,  Next: Standard Url Field,  Prev: Use Timestamp,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Standard Url Field,  Next: Url Regexp,  Prev: Timestamp Format,  Up: The Customisation Buffer

5.1.14 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'.


File: ebib-manual.info,  Node: Url Regexp,  Next: Browser Command,  Prev: Standard Url Field,  Up: The Customisation Buffer

5.1.15 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 `>'.


File: ebib-manual.info,  Node: Browser Command,  Next: Standard File Field,  Prev: Url Regexp,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Standard File Field,  Next: File Associations,  Prev: Browser Command,  Up: The Customisation Buffer

5.1.17 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: ebib-manual.info,  Node: File Associations,  Next: File Regexp,  Prev: Standard File Field,  Up: The Customisation Buffer

5.1.18 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: ebib-manual.info,  Node: File Regexp,  Next: File Search Dirs,  Prev: File Associations,  Up: The Customisation Buffer

5.1.19 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: ebib-manual.info,  Node: File Search Dirs,  Next: Print Preamble,  Prev: File Regexp,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Print Preamble,  Next: Print Multiline,  Prev: File Search Dirs,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Print Multiline,  Next: Latex Preamble,  Prev: Print Preamble,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Latex Preamble,  Next: Print Tempfile,  Prev: Print Multiline,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Print Tempfile,  Next: Allow Identical Fields,  Prev: Latex Preamble,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Allow Identical Fields,  Next: Entry Types,  Prev: Print Tempfile,  Up: The Customisation Buffer

5.1.25 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 *note Multiple Identical
Fields: multiple-identical-fields.


File: ebib-manual.info,  Node: Entry Types,  Prev: Allow Identical Fields,  Up: The Customisation Buffer

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


File: ebib-manual.info,  Node: Modifying Key Bindings,  Prev: The Customisation Buffer,  Up: Customisation

5.2 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 *note The Ebib Buffers:
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.



Tag Table:
Node: Top306
Node: Installation1617
Node: Basic Usage3491
Node: Getting Started4888
Node: Opening a `.bib' file5998
Node: Navigating a `.bib' file7877
Node: Starting a New `.bib' File11112
Node: Editing the Database11577
Node: Adding and Deleting Entries12036
Node: Editing Fields Values13302
Node: Editing Multiline Values15775
Node: Copy18126
Node: Saving a Database19243
Ref: saving-database19405
Node: Searching20522
Ref: searching20665
Node: LaTeX Integration22865
Node: Consulting databases from within a LaTeX file25311
Node: Cross-referencing27912
Ref: cross-referencing28083
Node: Printing the Database30419
Ref: printing-database30596
Node: Marking Entries34409
Node: Calling a Browser35969
Node: Viewing Files38119
Node: Advanced Features40505
Node: Screen Layout41118
Ref: screen-layout41285
Node: Preloading `.bib' Files42823
Node: `@Preamble' Definition43382
Node: `@String' Definitions45672
Node: Sorting the `.bib' file49149
Ref: sorting-bib-file49348
Node: Merging and Importing52352
Node: Exporting Entries53738
Node: Timestamps55949
Ref: timestamps56109
Node: Multiple Identical Fields57700
Ref: multiple-identical-fields57890
Node: Virtual Databases59817
Ref: virtual-databases60008
Node: Simple Selection61101
Node: Complex Filters62241
Node: Properties of Virtual Databases66271
Node: The Multiline Edit Buffer67611
Ref: multiline-edit-buffer67784
Node: The Ebib Buffers70188
Ref: ebib-buffers70336
Node: The Index Buffer70675
Node: The Entry Buffer75718
Node: The Strings Buffer78064
Node: Customisation79808
Ref: customisation79924
Node: The Customisation Buffer80208
Ref: customisation-buffer80399
Node: Default Type81184
Node: Preload Bib Files81667
Ref: preload-bib-files81846
Node: Additional Fields82049
Ref: additional-fields82222
Node: Layout82629
Ref: layout82780
Node: Index Window Size83102
Node: Index Display Fields83393
Ref: index-display-fields83587
Node: Insertion Commands83872
Ref: insertion-commands84055
Node: Sort Order85161
Node: Save Xrefs First85654
Ref: save-xrefs-first85824
Node: Crossref Face86284
Ref: crossref-face86451
Node: Marked Face86583
Ref: marked-face86743
Node: Use Timestamp87050
Node: Timestamp Format87387
Node: Standard Url Field87933
Ref: standard-url-field88114
Node: Url Regexp88227
Ref: url-regexp88391
Node: Browser Command88799
Ref: browser-command88974
Node: Standard File Field89315
Ref: standard-file-field89505
Node: File Associations89624
Ref: file-associations89806
Node: File Regexp90475
Ref: file-regexp90642
Node: File Search Dirs91104
Ref: file-search-dirs91278
Node: Print Preamble91446
Node: Print Multiline91869
Node: Latex Preamble92266
Node: Print Tempfile92720
Node: Allow Identical Fields93176
Ref: allow-identical-fields93368
Node: Entry Types93685
Ref: entry-types93832
Node: Modifying Key Bindings94371
Ref: modifying-key-bindings94536

End Tag Table


Local Variables:
coding: iso-8859-1
End: