ebib.info

This is ebib.info, produced by makeinfo version 7.1.1 from ebib.texi.

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Ebib: (ebib).           A BibTeX database manager.
END-INFO-DIR-ENTRY


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

Ebib Manual
***********

Ebib is a program with which you can manage ‘biblatex’ and BibTeX
database files without having to edit the raw ‘.bib’ files.  It runs in
GNU/Emacs, version 26.1 or higher.

It should be noted that Ebib is _not_ a minor or major mode for editing
‘.bib’ 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.

* Menu:

* Installation::
* Getting Started::
* Editing the Database::
* Main and Dependent Databases::
* Inserting Citations into a Text Buffer::
* Searching::
* Filters::
* Importing BibTeX entries::
* Linking to external resources::
* Notes files::
* Managing a reading list::
* Managing Keywords::
* Window Management::
* Copying Entries to the Kill Ring::
* Printing the Database::
* Customisation::


File: ebib.info,  Node: Installation,  Next: Getting Started,  Prev: Top,  Up: Top

1 Installation
**************

* Menu:

* Package manager::
* Manual installation::
* News::
* Starting Ebib::


File: ebib.info,  Node: Package manager,  Next: Manual installation,  Up: Installation

1.1 Package manager
===================

The easiest way to install Ebib is to get it from the Melpa package
archive (http://melpa.org/).  This also installs the Info file so you
can access the Ebib manual within Emacs.


File: ebib.info,  Node: Manual installation,  Next: News,  Prev: Package manager,  Up: Installation

1.2 Manual installation
=======================

It's also possible to install Ebib manually.  If you prefer this method,
then you probably know what you're doing, so detailed instructions are
omitted here.  Just be sure to also install the parsebib
(https://github.com/joostkremers/parsebib) package, which Ebib depends
on.


File: ebib.info,  Node: News,  Next: Starting Ebib,  Prev: Manual installation,  Up: Installation

1.3 News
========

New features and (possibly breaking) changes to existing features are
announced in the NEWS (NEWS.html) file.


File: ebib.info,  Node: Starting Ebib,  Prev: News,  Up: Installation

1.4 Starting Ebib
=================

Once installed, Ebib can be started with ‘M-x ebib’.  This command is
also used to return to Ebib when you have put the program in the
background.  To bind this command globally to e.g., ‘C-c e’, put
something like the following in Emacs' init file:

(global-set-key (kbd "C-c e") 'ebib)

Ebib can also be called from an Eshell command line.  When used in this
way, you can provide a filename to load.  So, provided a file
‘references.bib’ exists in ‘~/Work/Papers/’, the following command:

~/Work/Papers $ ebib references.bib

starts Ebib and loads the file ‘references.bib’.


File: ebib.info,  Node: Getting Started,  Next: Editing the Database,  Prev: Installation,  Up: Top

2 Getting Started
*****************

A BibTeX database is somewhat of a free-form database.  A BibTeX entry
consists of a set of field-value pairs and 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 entries in the database,
and one that contains the fields and values of the currently highlighted
entry.

When Ebib is started (with ‘M-x ebib’), 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 shows the _entry buffer_.  When a database is loaded, the index
buffer holds a list of all the keys in the database plus some additional
information for each entry: the author or editor, its year of
publication, and the title.

Ebib has a menu through which all of its functionality can be accessed.
Most functions are also bound to keys, but especially some of the lesser
used ones can (by default) only be accessed through the menu.

To quit Ebib and unload all ‘.bib’ files, type ‘q’.  Alternatively, type
‘z’ to put Ebib in the background but keep it active.  This way, 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::
* Preloading bib Files::
* Starting a New bib File::
* Closing a database::
* The Database View::
* Navigating the Database::
* Displaying and Sorting the Entries List::
* Biblatex vs BibTeX::


File: ebib.info,  Node: Opening a bib File,  Next: Preloading bib Files,  Up: Getting Started

2.1 Opening a ‘.bib’ File
=========================

To open a ‘.bib’ file, type ‘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.  If Ebib encounters entry
types in the ‘.bib’ file that it does not know, a warning will be logged
to a special buffer ‘*Ebib-log*’.  If Ebib finds something that it
cannot parse, it will log an error.  Ebib attempts to be as liberal as
possible, so everything that looks like a BibTeX entry will be read, but
if you open a ‘.bib’ file that wasn't written by Ebib, it is always a
good idea to check the log buffer to see if everything is in order.

In order to parse ‘.bib’ files, Ebib uses the entry type definitions of
‘bibtex.el’, which is fairly complete, but if you use non-standard entry
types, you may need to customise ‘bibtex-biblatex-entry-alist’ or
‘bibtex-bibtex-entry-alist’, depending on which of the two you use.  If
Ebib finds entry types in a ‘.bib’ file that are not defined, those
entries will still be loaded, but their entry type is displayed using
Emacs' ‘error’ face.  The most likely case in which this may happen is
when you load a BibTeX file without letting Ebib know the file is
‘biblatex’-specific.  By default, Ebib assumes that a ‘.bib’ file it
loads is a BibTeX file.  If you intend to use ‘biblatex’ files, make
sure to read the section *note ‘Biblatex’ vs. Bibtex:
#biblatex-vs-bibtex.

When you open a ‘.bib’ file, the directory in which you started Ebib is
the start directory for file name completion.  If you always want Ebib
to assume a specific default directory, regardless of the directory in
which Ebib is actually started, you can customise the option
‘ebib-default-directory’.


File: ebib.info,  Node: Preloading bib Files,  Next: Starting a New bib File,  Prev: Opening a bib File,  Up: Getting Started

2.2 Preloading ‘.bib’ Files
===========================

Chances are that you will be doing most of your work with one or a few
‘.bib’ files.  In order to open these files automatically when Ebib is
started, set the option "Preload Bib Files" (‘ebib-preload-bib-files’).
You may specify the files to preload with their full path or with a
relative path.  In the latter case, the files are searched for in the
directories listed in the option ‘ebib-bib-search-dirs’.

It is also possible to set this variable as a file-local or
directory-local variable (i.e., in a ~.dir-locals.el‘file). You can use
this method to only load the’.bib' file or files associated with a
specific project.


File: ebib.info,  Node: Starting a New bib File,  Next: Closing a database,  Prev: Preloading bib Files,  Up: Getting Started

2.3 Starting a New ‘.bib’ File
==============================

To start a new ‘.bib’ file from scratch, you first need 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.info,  Node: Closing a database,  Next: The Database View,  Prev: Starting a New bib File,  Up: Getting Started

2.4 Closing a database
======================

If you are done with a database, type ‘c’ to close it.  This unloads the
current database (you are asked for confirmation if you have unsaved
changes), but it does not leave Ebib, and the other databases you have
open will remain so.


File: ebib.info,  Node: The Database View,  Next: Navigating the Database,  Prev: Closing a database,  Up: Getting Started

2.5 The Database View
=====================

Once you've opened a ‘.bib’ file, all the entries in the file are shown
in alphabetical order (sorted by entry key, though this is customisable)
in the index buffer in the top Ebib window.  The fields of the first
entry and their values are shown in the entry buffer in the bottom Ebib
window.  The first field is the type field (i.e. ‘Book’, ‘Article’,
etc.)

Below the type field, Ebib displays (up to) four sets of fields.  The
first set are the so-called required fields, the fields that ‘biblatex’
/ BibTeX requires to be filled.  The second group are the optional
fields, which do not have to be filled but which are normally added to
the bibliography if they do have a value.  These two groups are specific
to the entry type; they are defined in Emacs and can be customised in
the customisation group ‘bibtex’.

The third group comprises the so-called extra fields.  These fields are
usually ignored by ‘biblatex’ / BibTeX (note that ‘biblatex’ and BibTeX
normally ignore _all_ fields they do not know about), although there are
bibliography styles that treat some of these fields as optional rather
than as extra.  Extra fields are not specific to the entry type.  They
are defined globally.  By default, Ebib defines the following extra
fields:

   • ‘abstract’
   • ‘annote’ (‘annotation’ in ‘biblatex’)
   • ‘crossref’
   • ‘doi’ (BibTeX only)
   • ‘file’
   • ‘keywords’
   • ‘timestamp’
   • ‘url’ (BibTeX only)

The fields ‘url’ and ‘doi’ are defined only for BibTeX because
‘biblatex’ defines them as optional fields for most entry types.  If
these fields are not sufficient for your use, you can customise the
option ‘ebib-extra-fields’.

Below the extra fields is one more set of fields.  These are fields that
exist in the entry but are not defined as part of the entry type nor as
extra fields.  See the section *note Undefined Fields:
#undefined-fields. for some more information.


File: ebib.info,  Node: Navigating the Database,  Next: Displaying and Sorting the Entries List,  Prev: The Database View,  Up: Getting Started

2.6 Navigating the Database
===========================

The basic motion keys in the index buffer are the following:

Key                Action
---------------------------------------------
‘up’ ‘p’ ‘C-p’     move one entry up
‘down’ ‘n’ ‘C-n’   move one entry down
‘Space’ ‘PgDn’     move one page up
‘b’ ‘PgUp’         move one page down
‘g’ ‘Home’         move to the first entry
‘G’ ‘End’          move to the last entry

If you have more than one database opened, you can use the keys ‘1’-‘9’
to jump between databases.  The number of each database is shown in the
mode line of the index buffer before the database name.  (Note that the
numbering is dynamic: if you have three databases opened and then close
the second, database 3 becomes database 2.)  You can also use the ‘left’
and ‘right’ cursor keys to move to the previous or next database (these
keys wrap).

You can quickly jump to any entry in a database with the key ‘j’.  This
asks you for an entry key (using completion) and then jumps to the
corresponding entry.  This actually works across databases: the keys
that are offered for completion are the keys from all open databases.
After selecting a key, Ebib changes to the corresponding database and
shows the entry corresponding to the key.  Note, though, that you can
restrict the jump candidates to the current database by using a prefix
argument, i.e., by typing ‘C-u j’.

If you use selectrum (https://github.com/raxod502/selectrum), ivy
(https://github.com/abo-abo/swiper) or helm
(https://github.com/emacs-helm/helm) or the built-in package ido, using
‘j’ becomes even more convenient: instead of completing the entry key,
you can type any part of the author/editor names, of the title and the
year of the entry you want to jump to.  You can also see the
bibliography file to which the entry belongs.  This is a good way to
search for a particular entry if you're not sure of the entry key.

Ebib keeps a history of the entries that you've visited.  You can move
through this history with ‘C-b’ and ‘C-f’.  Furthermore, using the Emacs
command ‘point-to-register’, you can store an entry in a register and
jump back to it at a later point with ‘jump-to-register’.


File: ebib.info,  Node: Displaying and Sorting the Entries List,  Next: Biblatex vs BibTeX,  Prev: Navigating the Database,  Up: Getting Started

2.7 Displaying and Sorting the Entries List
===========================================

By default, the index buffer displays the list of entries in the
database in a table format using the entry key, and the author, year and
title fields of each entry.  The entries are sorted in ascending order
on the first column, which by default is the entry key.  You can sort
the entries on one of the other columns using the keys ‘<’ and ‘>’.  The
former performs an ascending sort (smallest to largest, hence the
smaller-than sign), the latter a descending sort.  They both ask you for
the column to sort on.  Restoring the default sort can be done with ‘=’.

The fields that are displayed in the index buffer can be customised with
the user option ‘ebib-index-columns’.  Each element in this option
describes a column and consists of the field to display (which is also
the column label), the width of the column and a flag indicating whether
the column can be sorted.  You can add or remove fields, or reorder the
existing ones.  Note that the width of the last column is ignored: the
last column always takes up all the space that is left.

You can use any ‘biblatex’ or BibTeX field to define a column in the
index buffer.  There are a few column labels that do not correspond
directly to a field name, however.  For example, the column label
‘"Entry Key"’, which displays the entry key, is not a field.  Similarly,
there is a column label ‘"Author/Editor"’, which displays the contents
of the author field if it is not empty, and the contents of the editor
field otherwise.  Furthermore, the column label ‘"Year"’ does not simply
display the contents of the year field.  Rather, it first checks the
contents of the date field, which is ‘biblatex’'s replacement of the
year field, and extracts the first year in it.  Only if the date field
is empty does it display the year field.

Three other column labels have special behaviour: ‘"Title"’, ‘"Doi"’,
and ‘"Url"’.  These do display information from the fields they
correspond with, but in a special way: ‘"Title"’ tries to make the title
look nice by removing braces and LaTeX commands (leaving only their
obligatory arguments) and by displaying the arguments of ‘\emph’,
‘\textit’, ‘\textbf’ and ‘\textsc’ in italic, bold or caps.  Accented
characters that are created using LaTeX commands such as ‘\"{a}’ are
displayed as the actual accented characters and a number of LaTeX
commands for special characters are replaced with the corresponding
Unicode character.

The column labels ‘"Doi"’ and ‘"Url"’ don't display the contents of
these fields, but instead yield a clickable string ‘"www"’; clicking on
‘"www"’ takes you to the relevant web page.

The final predefined column label is ‘"Note"’.  This does not, as might
be expected, display the contents of the note field.  Rather, it checks
whether the entry in question has an external annotation (see *note
Notes Files: #notes-files.).  For those entries that have an annotation,
the ‘"Note"’ column displays a (clickable) ‘"N"’.  (Keep in mind,
though, that if you keep your notes in a single file, adding this column
to the index display can slow down the creation of the index buffer (and
thus Ebib's start-up).  If you wish to use this column, it is probably
best to keep notes in separate files.)

You can define new column labels and redefine the existing ones by
customising the option ‘ebib-field-transformation-functions’.  Note that
‘"Title"’, ‘"Doi"’, ‘"Url"’, and ‘"Note"’ are actually defined through
this option.  ‘"Entry Key"’, ‘"Author/Editor"’, and ‘"Year"’ are not
(they are hard-coded), but they can be overridden by adding an entry for
them in ‘ebib-field-transformation-functions’.  For example, if you do
not wish for TeX markup to be hidden in titles, remove the ‘"Title"’
entry in this option.

The first column defined in ‘ebib-index-colums’ is the column on which
the entries are sorted by default, i.e., when the database is first
opened and when you press ‘=’.  You can change the default sort field
and the default sort direction (which is ascending, i.e., A-Z and 0-9)
by customising the option ‘ebib-index-default-sort’.

By default, sorting is done on the string representation of the field
value, using the function ‘string-collate-lessp’.  For numeric fields,
this may not be appropriate, because it means that the value ‘10’ is
sorted between ‘1’ and ‘2’.  To specify a custom sort function for
particular fields, you can customise the option
‘ebib-field-sort-functions-alist’.  To sort numeric fields, you can use
the predefined function ‘ebib-compare-numerical-strings’, but you can
also define a custom sort function yourself.


File: ebib.info,  Node: Biblatex vs BibTeX,  Prev: Displaying and Sorting the Entries List,  Up: Getting Started

2.8 Biblatex vs. BibTeX
=======================

BibTeX has long been a core part of the TeX ecosystem, but it has not
received any substantial update since 1988(!)  and it has next to no
support for languages other than English.  Compared to BibTeX,
‘biblatex’ has an expanded set of entry types, allowing for more diverse
types of references, a larger number of fields, and a much more
sophisticated system of field value inheritances.  Most importantly,
however, ‘biblatex’ (and its back-end ‘Biber’) has proper Unicode
support.

For these reasons, the use of ‘biblatex’ is highly recommended for
anyone using LaTeX. For historical reasons, however, BibTeX is still the
default dialect, so if you intend to use ‘biblatex’ files, you need to
tell Ebib that your files are ‘biblatex’ files.

* Menu:

* Setting the BibTeX Dialect::
* Alias Types and Fields::


File: ebib.info,  Node: Setting the BibTeX Dialect,  Next: Alias Types and Fields,  Up: Biblatex vs BibTeX

2.8.1 Setting the BibTeX Dialect
--------------------------------

‘Biblatex’ files use the same ‘.bib’ suffix that BibTeX files use.
Whether Ebib interprets a file as a BibTeX or a ‘biblatex’ file is
determined by the user option ‘ebib-bibtex-dialect’.  Possible values
for this option are ‘BibTeX’ and ‘biblatex’, the default being ‘BibTeX’.
(These values are taken from the variable ‘bibtex-dialect-list’.)

The dialect specified determines which entry types Ebib recognises and
which fields it expects.  Reading a file with the wrong dialect setting
will most likely result in a series of "Illegal entry type" errors.
Note, however, that these entries will still be loaded and displayed,
but they will be highlighted with Emacs' ‘error’ face.  Fields that are
not defined for the current dialect are displayed as undefined fields
(i.e., below all other fields in the entry buffer).

The option ‘ebib-bibtex-dialect’ sets the default dialect, which is the
dialect that Ebib gives to newly created ‘.bib’ files and which it
assumes for files that are not otherwise specified.  If you wish to work
with a file that is in a different dialect than what you set as the
default, you can set the dialect for this particular file.  To do this,
load the file and then set the dialect through the menu option «Ebib |
BibTeX Dialect» or with the command ‘M-x ebib-set-dialect’.  You only
need to do this once for a file, because the setting is saved in the
‘.bib’ file in the local variable block.  (If no local variable block
exists, one is created.)  The setting is actually saved as a file-local
value for the variable ‘bibtex-dialect’, which means that if you should
open the file directly in ‘bibtex-mode’, Emacs will apply the dialect
setting as well.

The mode line of the index buffer shows the dialect that Ebib assumes
for the current database.  Note that this does not necessarily mean that
the dialect is set in the ‘.bib’ file: if the file does not have a
dialect setting, the mode line shows the default setting.


File: ebib.info,  Node: Alias Types and Fields,  Prev: Setting the BibTeX Dialect,  Up: Biblatex vs BibTeX

2.8.2 Alias Types and Fields
----------------------------

The set of entry types defined by ‘biblatex’ differs from the set used
by BibTeX. Mostly, ‘biblatex’ adds new entry types, but there are a few
BibTeX entry types that have been dropped.  For legacy reasons,
‘biblatex’ still recognises these entry types, but it treats them as
aliases for some of its own types:

BibTeX Entry       Biblatex entry type
type
-----------------------------------------------------------------
‘@Conference’      ‘@InProceedings’
‘@Electronic’      ‘@Online’
‘@MastersThesis’   ‘@Thesis’ with ‘type’ as 'Master's thesis'
‘@PhDThesis’       ‘@Thesis’ with ‘type’ as 'PhD thesis'
‘@TechReport’      ‘@Report’ with ‘type’ as 'technical report'
‘@www’             ‘@Online’

If an entry has such an alias as entry type, Ebib displays the entry
type that ‘biblatex’ treats it as in the entry buffer.  For example, the
entry type alias ‘PhDThesis’ is shown as ‘PhDThesis [==> Thesis]’.

Similarly, a number of fields are deprecated but still accepted as
aliases:

BibTeX Field      Biblatex Field
-----------------------------------
‘address’         ‘location’
‘annote’          ‘annotation’
‘archiveprefix’   ‘eprinttype’
‘journal’         ‘journaltitle’
‘key’             ‘sortkey’
‘pdf’             ‘file’
‘primaryclass’    ‘eprintclass’
‘school’          ‘institution’

These aliases are also indicated in the entry buffer: for example, if an
entry has a ‘journal’ field, its value is shown as the value of the
‘journaltitle’ field; a tag ‘[<== journal]’ is placed after the field
value, indicating that the value is actually contained in the journal
field.  The ‘journal’ field itself is shown as an undefined field, i.e.,
after all other fields.  Displaying the value twice this way means that
you can easily copy the value of the ‘journal’ field to the
‘journaltitle’ field, if you wish to bring your entries into line with
‘biblatex’'s conventions.


File: ebib.info,  Node: Editing the Database,  Next: Main and Dependent Databases,  Prev: Getting Started,  Up: Top

3 Editing the Database
**********************

Obviously, Ebib not only allows you to see the BibTeX entries in your
‘.bib’ files, you can also edit them.  This section describes the most
important editing facilities.

* Menu:

* Adding and Deleting Entries::
* Marking Entries::
* Editing Field Values::
* @String abbreviations in field values::
* Editing Multiline Values::
* Copy Cut Kill Paste Yank and Delete::
* Undefined Fields::
* Hiding Fields from Display::
* Timestamps::
* Saving a Database::
* Cross-referencing::
* Sorting the bib File::
* @Preamble Definition::
* @String Definitions::
* @Comments::
* Creating Entry Stubs::
* Multiline Edit Buffers::


File: ebib.info,  Node: Adding and Deleting Entries,  Next: Marking Entries,  Up: Editing the Database

3.1 Adding and Deleting Entries
===============================

To add an entry to a database, type ‘a’.  This creates a new entry with
a temporary key and puts you in the entry buffer, where you can edit the
fields of the entry.  When you finish editing the entry fields, the
temporary key is replaced with an automatically created key based on the
entry's content.  (Ebib uses the function ‘bibtex-generate-autokey’ for
this; see that function's documentation string for customisation
options.)  If you prefer to specify a key yourself, you can unset the
option ‘ebib-autogenerate-keys’.

Deleting an entry can be done in two ways.  The key ‘d’ deletes an entry
from the database.  This command asks for confirmation, because once an
entry has been deleted in this way, it cannot be retrieved again.
Alternatively, you can use ‘k’, which kills the current entry, i.e., the
entry is deleted from the database and added to the kill ring.

The key ‘y’ lets you yank an entry from the kill ring into the current
database.  In order for this to work, the item at the top of the kill
ring must be a string that constitutes a properly formatted BibTeX
entry.  If this is not the case, Ebib gives you a warning and rotates
the kill ring, so that you can press ‘y’ again to (try and) add the next
element in the kill ring to the database.

Killing an entry from a database obviously yields a properly formatted
BibTeX entry (so you can easily move entries from one database to
another by killing and then yanking them), but killing a BibTeX entry
from another buffer or copying one from an outside source (e.g., a
website) is also possible.

Note that yanking also works with ‘@Preamble’, ‘@String’ and ‘@Comment’
definitions.


File: ebib.info,  Node: Marking Entries,  Next: Editing Field Values,  Prev: Adding and Deleting Entries,  Up: Editing the Database

3.2 Marking Entries
===================

Commands in the index buffer generally operate on one single entry.
Some commands can be performed on multiple entries simultaneously.  To
do this, first mark the relevant entries with the key ‘m’ and then
perform the command.  Commands for which it makes sense automatically
operate on all marked entries if there are any.

With a prefix argument, i.e, with ‘C-u’ followed by ‘m’, you can unmark
all entries or, if there are no marked entries, mark all entries in the
current database.


File: ebib.info,  Node: Editing Field Values,  Next: @String abbreviations in field values,  Prev: Marking Entries,  Up: Editing the Database

3.3 Editing Field Values
========================

Editing the field values for an entry is done in the lower of the two
Ebib buffers, the 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:

Key                Action
---------------------------------------------
‘up’ ‘p’ ‘C-p’     move one field up
‘down’ ‘n’ ‘C-n’   move one field down
‘Space’ ‘PgDn’     move to previous set
‘b’ ‘PgUp’         move to next set
‘g’ ‘Home’         move to the first field
‘G’ ‘End’          move to the last field

To finish editing fields and move focus back to the index window, use
‘q’.

Editing a field value can be done with ‘e’ or ‘RET’.  For most fields,
Ebib simply asks you for a string value in the minibuffer.  There is no
need to put braces ‘{}’ around field values, Ebib adds them when it
saves the ‘.bib’ file.

Fields for which it makes sense offer completion when you edit them.
For example, when you edit the ‘type’ field, completion is offered on
all predefined entry types.  Similarly, if you edit the ‘crossref’
field, Ebib offers completion on the keys in the databases currently
open.  The ‘keywords’ field offers completion on all configured keywords
(see the section *note Managing Keywords: #managing-keywords.) and the
‘file’ field offers file name completion (see *note Viewing and
Importing Files: #viewing-and-importing-files.).

For other fields that offer completion, the completion candidates are
the values of these fields in other entries in the databases that you've
opened.  Offering these as completion candidates makes it easier to
ensure that you enter these values consistently.  This of course mainly
makes sense for fields that have values that will occur more than once.
By default, apart from the fields already mentioned, completion is
offered for the ‘author’, ‘editor’, ‘journal’, ‘journaltitle’,
‘organization’ and ‘publisher’ fields.

In the ‘author’ and ‘editor’ fields, completion takes into account that
these fields may contain more than one name.  Each name is a separate
completion candidate: when editing these fields, you can type the
individual names, Ebib adds the ‘"and"’ or the semicolon that separates
them.

If you want to edit a field value directly, without completion, you can
use a prefix argument: ‘C-u e’ lets you edit a field as a plain string.
If you wish to disable completion permanently for particular fields, or
if you want to enable completion for other fields, you can customise the
user option ‘ebib-edit-fields-functions’.

With fields that can contain lists of values, such as the ‘author’ and
‘editor’ fields, but also the ‘file’ field, Ebib offers multiple
completion: you can select one candidate with ‘TAB’ and then go on to
select the next one.  When you've selected all candidates you want, hit
‘RET’.  Ebib uses Emacs' standard ‘completing-read-multiple’ function
for this, but note that ‘crm-separator’ is set to something appropriate
for the field being edited.


File: ebib.info,  Node: @String abbreviations in field values,  Next: Editing Multiline Values,  Prev: Editing Field Values,  Up: Editing the Database

3.4 ‘@String’ abbreviations in field values
===========================================

BibTeX and ‘biblatex’ provide so-called ‘@String’ abbreviations, short
abbreviations for strings of text that occur often in your database,
e.g., publisher names, names of journals, etc.

You can define such abbreviations in Ebib in the _strings buffer_ (see
*note ‘@String’ Definitions: #string-definitions. for details).  To use
a ‘@String’ abbreviation in a field value, the field's value must be
marked as _special_.  Normally, when Ebib saves the database, it puts
braces around field values.  If a field has a ‘@string’ abbreviation in
it, it shouldn't be surrounded with braces, because that would prevent
‘biblatex’ or BibTeX from expanding the abbreviation.

A special field is a field whose value is not surrounded by braces when
the database is saved, so that it is recognised as a field with an
abbreviation.  To mark a field special, press ‘r’.  An asterisk will
appear before the field, indicating its status.  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.

By default, Ebib shows the _expanded_ value of a field that is marked
special.  So for example, if you have a ‘@String’ abbreviation ‘cup’ for
‘"Cambridge University Press"’, putting ‘cup’ in the ‘publisher’ field
and marking it special will show the expanded value ‘Cambridge
University Press’ in the entry buffer.  The field is still marked with
an asterisk and the expanded value is displayed in a different colour to
indicate that it is an expansion.  You can turn this behaviour off by
unsetting the user option ‘ebib-expand-strings’.

Note that a field value can actually be composed of a concatenation of
"normal" text 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 special.

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 special.  This method uses completion.


File: ebib.info,  Node: Editing Multiline Values,  Next: Copy Cut Kill Paste Yank and Delete,  Prev: @String abbreviations in field values,  Up: Editing the Database

3.5 Editing Multiline Values
============================

There are two other fields that Ebib handles in a special way when you
edit their value.  These are the ‘annotation’ field (or ‘annote’ in
BibTeX), and the ‘abstract’ field.  Most field values normally consist
of a single line of text.  However, because the ‘annotation’ and
‘abstract’ fields are meant for creating annotated bibliographies, it
would not be very useful if you could only write one line of text in
them.  Therefore, when you edit one of these fields, Ebib puts you in a
so-called _multiline edit buffer_.  This is essentially a text mode
buffer that allows you to enter text freely.

To store the text and leave the multiline edit buffer, type ‘C-c C-c’.
If you want to leave the multiline edit buffer and discard your changes,
type ‘C-c C-k’.  This command cancels the edit and leaves the multiline
edit buffer.  The text that is stored in the field you were editing is
not altered.

For more details on working with multiline edit buffers, see *note
Multiline Edit Buffers: #multiline-edit-buffers.

When a field has a multiline value, at most ten lines are shown in the
entry buffer.  If the text is longer, an ellipsis indicator ‘[...]’ is
added after the last line that is displayed.  If you want to see the
whole contents of a multiline field, you can use ‘v’: this will display
the contents of the current field in a ‘*Help*’ buffer (which can be
dismissed again with ‘q’).  It is possible to customise the way a
multiline value is displayed in the entry buffer.  See the options
‘ebib-multiline-display-function’ and ‘ebib-multiline-display-max-lines’
for details.

Note that multiline values are not restricted to the ‘annotation’ and
‘abstract’ fields.  Any field except the ‘type’ and ‘crossref’ fields
can in fact hold a multiline value.  To give a field a multiline value,
use ‘m’ instead of ‘e’.


File: ebib.info,  Node: Copy Cut Kill Paste Yank and Delete,  Next: Undefined Fields,  Prev: Editing Multiline Values,  Up: Editing the Database

3.6 Copy, Cut (Kill), Paste (Yank), and Delete
==============================================

A few more commands are available when you're in the entry buffer
editing field values.  The commands ‘c’, ‘k’ and ‘y’ implement copy,
kill and yank: ‘c’ copies the contents of the current field to the kill
ring, ‘k’ 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’.

The contents of a field can also be deleted with the command ‘d’.  This
command does not store the text in the kill ring: once deleted, the text
is gone.  It therefore asks for confirmation, just to be sure.

Note that ‘y’ only works when the current field does not have a value
yet.  This is to prevent you from accidentally overwriting a field
value.  If you do want to yank text into a field that already has a
value, simply hit ‘d’ first to delete the text.


File: ebib.info,  Node: Undefined Fields,  Next: Hiding Fields from Display,  Prev: Copy Cut Kill Paste Yank and Delete,  Up: Editing the Database

3.7 Undefined Fields
====================

‘Biblatex’ and BibTeX ignore fields that they do not know about, which
is a property that can be exploited to add any kind of information to an
entry.  Ebib accommodates this by allowing fields with any name, not
just the ones that are predefined.  Such undefined fields are displayed
last in the entry buffer, following the extra fields.

It is even possible to add such fields to an entry by pressing ‘a’ in
the entry buffer.  This asks for a field name and then a value.  If you
make heavy use of this option, though, it may be better to define the
relevant fields through the user option ‘ebib-extra-fields’.

Note that if you delete the contents of an undefined field, the field
itself is also deleted.  (In fact, the field remains in the database
until you close the database, but it will not be saved, so the next time
you load the ‘.bib’ file, the field is gone.)


File: ebib.info,  Node: Hiding Fields from Display,  Next: Timestamps,  Prev: Undefined Fields,  Up: Editing the Database

3.8 Hiding Fields from Display
==============================

‘Biblatex’ defines a large number of fields, many of which are optional
for most entry types.  Displaying all these fields in the entry buffer
would not be very practical, because you are most likely interested in
only a few of them.  For this reason, Ebib defines a (fairly large)
number of fields as 'hidden', meaning that they are not shown in the
entry buffer unless they have a value (i.e., if they are present in the
BibTeX entry).

If you want to insert a value into a field that is hidden by default,
you need to make the hidden fields visible first, which can be done with
the key ‘H’ (in the index buffer).  Alternatively, you can use ‘a’ in
the entry buffer to add a field, provided you know its exact name.
(Keep in mind that you can use ‘a’ to add fields that are not
predefined, so Ebib won't complain if you mistype the field name.
Completion is available, though.)

Which fields are treated as hidden is controlled by the option "Hidden
Fields" (‘ebib-hidden-fields’), which can be customised.  The default
value of this option contains a fairly long list of fields, most of
which are ‘biblatex’-specific, though the option can of course be used
for BibTeX files as well.

If you prefer Ebib to show _only_ the fields that have a value, (e.g.,
when you use Ebib mainly for viewing, not for editing, BibTeX entries),
you can set ‘ebib-hidden-fields’ to the value ‘t’: This essentially
makes all fields hidden, which means that all fields without a value are
suppressed and only fields with a value are shown.


File: ebib.info,  Node: Timestamps,  Next: Saving a Database,  Prev: Hiding Fields from Display,  Up: Editing the Database

3.9 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 (extra) field ‘timestamp’, which is hidden by default.

You can tell Ebib to create timestamps by setting the option
‘ebib-use-timestamp’.  With this option set, a timestamp is included in
entries added to the database with ‘a’.  Ebib also adds 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 are 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 is imported or exported.  Therefore, if you record timestamps
and want to im-/export entries without changing their timestamps,
temporarily unset this option, which can be done in the menu under
"Options".

Ebib uses the function ‘format-time-string’ to create the timestamp.
The format string that Ebib uses can be customised.  The default string
is ‘"%Y-%m-%d %T (%Z)"’, which produces a timestamp of the form
‘"2007-03-12 01:03:26 (CET)"’.  This string is sortable and has the
additional advantage that it can be converted to Emacs' internal time
representation with the function ‘date-to-time’.  The format can be
customised; see the documentation for ‘format-time-string’ on the
options that are available.

Adding timestamps in a format that ‘date-to-time’ can parse makes it
possible to list the most recent additions to the database.  Ebib
provides a function to do this: ‘ebib-list-recent’, which asks for a
number of days and lists the entries that were added since then.  See
*note Special Filters: #special-filters. for details.


File: ebib.info,  Node: Saving a Database,  Next: Cross-referencing,  Prev: Timestamps,  Up: Editing the Database

3.10 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 are saving a file for the
first time after loading it, Ebib creates a backup file.  (Ebib honours
‘backup-directory-alist’ when saving backups.  Note that you can also
disable backups altogether with the option ‘ebib-create-backups’.)

If you want to force-save a database that has not been modified, you can
use a prefix argument: ‘C-u s’.  Ebib still checks whether the
underlying file was modified, though.  If you also want to forego this
check, use a double prefix argument: ‘C-u C-u s’.  This saves the file
unconditionally.

You can also save a database to another name with ‘w’.  This command is
similar to ‘C-x C-w’ in Emacs: the new ‘.bib’ file becomes associated
with the database.  This command can also be prefixed with ‘C-u’ in
order to overwrite any existing file without asking for confirmation.

Note that by default, Ebib uses a single TAB to indent fields inside
BibTeX entries.  If you prefer to use spaces, set the option
‘ebib-save-indent-as-bibtex’.  When this option is set, Ebib uses the
value of the variables ‘bibtex-entry-offset’ and
‘bibtex-field-indentation’ to compute how many spaces to use to indent
fields.

* Menu:

* Exporting Entries::


File: ebib.info,  Node: Exporting Entries,  Up: Saving a Database

3.10.1 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 another database that you have open in Ebib, use the
command ‘x’.  This command operates on a single entry or on all marked
entries.

You can also export entries to a file.  To do this, call the command ‘x’
with a prefix argument: ‘C-u x’ and type the name of the file to export
the entries to.  If the file already exists, Ebib appends the entries to
it.  Note that in this case, there is no check to see if the exported
entries already exist in the target file, so you may end up with
duplicate entries in this way.

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 an open database to export the entry to.  With a prefix
argument, they ask for a filename, and then append the relevant data to
that file.


File: ebib.info,  Node: Cross-referencing,  Next: Sorting the bib File,  Prev: Saving a Database,  Up: Editing the Database

3.11 Cross-referencing
======================

Both ‘Biblatex’ and BibTeX allow entries to refer to other entries
through the ‘crossref’ field.  If an entry has a ‘crossref’ field, Ebib
displays the field values that nte entry inherits from its parent entry.
To indicate that they are just inherited values, they are marked with
‘ebib-crossref-face’, which by default inherits from
‘font-lock-comment-face’.  These values are merely displayed for
convenience: they cannot be edited.  (They can be copied, however).

‘Biblatex’'s inheritance rules are fairly sophisticated: they depend on
the fields and on the types of the child _and_ parent entry.  Ebib fully
supports this inheritance schema.  Since inheritance rules can be
customised in ‘biblatex’, they are defined in Ebib in the customisable
option ‘ebib-biblatex-inheritances’.  This is set up with the default
inheritance relations defined by ‘biblatex’, but can be customised if
needed.

BibTeX's inheritance mechanism is much more simplistic.  A field in a
child entry that does not have a value simply inherits the value of the
same-name field in the parent entry.  Customisation is not possible
here, neither in BibTeX nor in Ebib.

If you are viewing an entry that has a ‘crossref’ field and you want to
go to the parent entry you can type ‘C’.  This command reads the value
of the ‘crossref’ field and then jumps to the entry it contains.  If you
want to do the reverse, i.e., see if the current entry is the parent of
any other entries, you can use the same key ‘C’: if you type ‘C’ on an
entry that does not have a ‘crossref’ field, Ebib starts searching the
database for the current entry key.

Note that after Ebib has jumped to the first child entry, you cannot
type ‘C’ again to find the next one.  Since you are now on a child
entry, this key would take you back to the parent entry.  In order to
find the next child entry, you have to type ‘RET’, as with a normal
search.  (Also, if the cross-referenced entry appears alphabetically
before the cross-referencing entry, you need to type ‘g’ and then ‘/’.)

Note that if you want to use ‘biblatex’'s or BibTeX's cross-referencing
mechanism, the option ‘ebib-save-xrefs-first’ needs to be set (which it
is by default).  This tells Ebib to save all entries with a ‘crossref’
field first in the ‘.bib’ file.  Without this, cross-referencing will
not work reliably.


File: ebib.info,  Node: Sorting the bib File,  Next: @Preamble Definition,  Prev: Cross-referencing,  Up: Editing the Database

3.12 Sorting the ‘.bib’ File
============================

By default, the entries in the database are saved to the ‘.bib’ file in
alphabetical order according to entry key.  (Entries with a ‘crossref’
field are saved first, but also sorted alphabetically) For most
purposes, this is sufficient, but in some cases (e.g., in ConTeXt), it
is necessary to have more control over the order of entries in the
‘.bib’ file.

Ebib allows you to specify the sort order in the ‘.bib’ file with the
user option ‘ebib-sort-order’.  This is a list of _sort levels_: entries
are first sorted using the first sort level.  If two entries cannot be
sorted on the first sort level, they are sorted on the second level,
etc.

Each sort level is a list of field names (as case-insensitive strings).
Entries are sorted based on the first field in this list that yields a
value.  So if the first sort level is ‘(author editor)’, an entry is
sorted on the ‘author’ field if it has a value and on the ‘editor’ field
otherwise.  If neither the author nor the editor field yields a value
for a particular entry, that entry is sorted on the BibTeX key.

If two or more entries yield the same value for the first sort level,
meaning that they cannot be sorted on that level, are sorted on the
second sort level.  If, for example, the second sort level is ‘(year)’,
entries from the same author are sorted on the year of publication.

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 ‘ebib-sort-order’ has no value, which means that
the entries in the ‘.bib’ file are sorted according to entry key.  If
you wish to make use of this option, you will most likely want to set
the first sort level to ‘(author editor)’ and the second to ‘(year)’.
Keep in mind that if you do set this option, you need to unset the
option ‘ebib-save-xrefs-first’ (see *note Cross-referencing:
#cross-referencing.).  It is pointless to set a sort order if
cross-referenced entries are saved first.


File: ebib.info,  Node: @Preamble Definition,  Next: @String Definitions,  Prev: Sorting the bib File,  Up: Editing the Database

3.13 @Preamble Definition
=========================

Apart from database entries, BibTeX allows three more types of elements
to appear in a ‘.bib’ file.  These are ‘@Preamble’, ‘@String’ and
‘@Comment’ definitions.  Ebib provides facilities to handle these, which
are discussed here and in the following sections.

Ebib allows you to add one ‘@Preamble’ definition to the database.  In
principle, BibTeX allows more than one such definition, but 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
(uppercase) ‘P’ in the index buffer.  Ebib uses the multiline edit
buffer for editing the text of the ‘@Preamble’ definition, which means
that ‘C-c C-c’ stores the ‘@Preamble’ text and returns focus to the
index buffer, while ‘C-c C-k’ returns focus to the index buffer while
abandoning any changes you may have made.  (For details on using
multiline edit buffers, see *note Multiline Edit Buffers:
#multiline-edit-buffers.)

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.info,  Node: @String Definitions,  Next: @Comments,  Prev: @Preamble Definition,  Up: Editing the Database

3.14 @String Definitions
========================

If you press (uppercase) ‘S’ in the index buffer, Ebib hides the entry
buffer in the lower window and replaces it with the _strings buffer_.
In this buffer, you can add, delete and edit ‘@String’ definitions.

Adding a ‘@String’ definition is done with the command ‘a’.  This will
first ask you for an abbreviation and then for the value to be
associated with that abbreviation.  Once you've entered these, Ebib will
sort the new abbreviation into the buffer.

The following keys are available in the strings buffer:

Key                                      Action
--------------------------------------------------------------------------
‘up’ ‘p’ ‘C-p’                           move one string up
‘down’ ‘n’ ‘C-n’                         move one string down
‘Space’ ‘PgDn’                           move ten strings up
‘b’ ‘PgUp’                               move ten strings down
‘g’ ‘Home’                               move to the first string
‘G’ ‘End’                                move to the last string
‘e’                                      edit a ‘@String’ value
‘d’                                      delete a ‘@String’ definition
‘c’                                      copy a ‘@String’ value
‘x’                                      export a ‘@String’ definition
‘X’                                      export all ‘@String’
                                         definitions

It is not possible to cut the value of a ‘@String’ definition, because
they must have a value.  Yanking has not been implemented in the strings
buffer, but you can use ‘C-y’ / ‘M-y’ in the minibuffer when editing a
‘@String’ value.

‘@String’ definitions, like field values, can contain other
abbreviations.  That is, you can define an abbreviation ‘up’ with the
value ‘{University Press}’, and then define another abbreviation ‘cup’
with the value ‘{Cambridge } # up’.  This will expand to ‘"Cambridge
University Press"’.  When Ebib detects such a 'nested' ‘@String’
definition, it will display the full expansion in the strings buffer
next to the value.  Note that for this to work, such values need to be
marked _special_, just like field values that contain ‘@String’
definitions.


File: ebib.info,  Node: @Comments,  Next: Creating Entry Stubs,  Prev: @String Definitions,  Up: Editing the Database

3.15 @Comments
==============

If Ebib finds a ‘@Comment’ in a ‘.bib’ file, it will read it and store
it in the database.  When the database is saved, all the ‘@Comment’s
will be saved with it, at the top of the file, immediately after the
‘@Preamble’ (with the exception of a ‘@Comment’ surrounding a ‘Local
Variables:’ block, which is saved at the end of the file).  There is no
way to edit comments, nor can you specify where in the ‘.bib’ file a
comment is placed, but they won't be lost.


File: ebib.info,  Node: Creating Entry Stubs,  Next: Multiline Edit Buffers,  Prev: @Comments,  Up: Editing the Database

3.16 Creating Entry Stubs
=========================

If you have a directory full of (pdf) files of articles that you want to
add to your database, Ebib can make the task a little bit easier by
creating entry stubs for all the files.  You can do this with the
command ‘M-x ebib-add-file-entry’.  This command asks you for a file or
a directory and creates an entry in the current database for that file
or each file in the directory.  The entries only contain a file field
pointing to the file, all the other information still has to be filled
out by hand, but this way you can at least keep track of which files are
already in your database.  The keys of these entries are temporary keys.
They will be replaced by more permanent keys automatically when you edit
the entries.


File: ebib.info,  Node: Multiline Edit Buffers,  Prev: Creating Entry Stubs,  Up: Editing the Database

3.17 Multiline Edit Buffers
===========================

As mentioned several times before, field values that contain newlines
(so-called _multiline fields_) and the ‘@Preamble’ are edited in a
so-called _multiline edit buffer_.  This section discusses the details
of this buffer.

Ebib enters a multiline edit buffer in one of three cases: when you edit
the ‘@Preamble’ definition, when you hit ‘m’ in the entry buffer to edit
a field as multiline, or when you hit ‘e’ on the ‘annote’/‘annotation’
or ‘abstract’ fields, or on a field whose value already is multiline.

The major mode that is used in multiline edit buffers is
user-configurable.  The default value is ‘text-mode’, but if you prefer
to use some other mode, you can specify this through the customisation
option ‘ebib-multiline-major-mode’.

Three commands are relevant for interacting with Ebib when you're in the
multiline edit buffer, which are bound to key sequences in the minor
mode ‘ebib-multiline-edit-mode’, which is activated automatically in the
multiline edit buffer.

‘ebib-quit-multiline-buffer-and-save’, bound to ‘C-c C-c’, leaves the
multiline edit buffer and stores the text in the database.  If you
invoke this command when you've deleted all contents of the buffer
(including the final newline!)  and you were editing a field value or
the ‘@Preamble’, the field value or preamble is deleted.  (This is in
fact the _only_ way to delete the ‘@Preamble’ definition.  Field values
on the other hand can also be deleted by hitting ‘k’ or ‘d’ on them in
the entry buffer.)

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

‘ebib-save-from-multiline-buffer’, bound to ‘C-c C-s’, can be used in
the multiline edit buffer to save the database.  This command first
stores the text in the database and then saves it.  Because Ebib does
not do an autosave of the current database, it is advisable to save the
database manually every now and then to prevent data loss in case of
crashes.  It would be annoying to have to leave the multiline edit
buffer every time you want to do this, so this command has been provided
to allow you to do this from within the buffer.

Note that you do not need to finish a multiline edit before you can
return to the database and possibly edit other fields and even entries.
Ebib keeps track of which field in which entry of which database a
multiline edit buffer belongs to, so you can keep a multiline edit
buffer open while doing other work.  It is even possible to have several
multiline edit buffers open at the same time.  Ebib makes sure that when
you finish one, its contents is stored in the correct place.

The key combinations of the multiline edit buffer strictly speaking
violate Emacs' suggested key binding conventions.  They are defined in
the keymap of a minor mode (‘ebib-multiline-mode’, to be specific), but
a minor mode keymap should only use key bindings of ‘C-c’ plus a
non-alphanumeric character.  The bindings do follow practical
conventions, however: they are used for similar functions in e.g., Org's
capture mechanism, in ‘message-mode’, in VC, magit, etc.  For this
reason, Ebib uses them as well.

If you find that these key bindings conflict with key bindings in the
major mode you use in the multiline edit buffer, you can change them, of
course.  To do this, put something like the following in your init file:

(with-eval-after-load 'ebib
  (define-key ebib-multiline-mode-map
    "\C-c c" nil)
  (define-key ebib-multiline-mode-map
    "\C-c | c" 'ebib-quit-multiline-buffer-and-save)

  (define-key ebib-multiline-mode-map
    "\C-c s" nil)
  (define-key ebib-multiline-mode-map
    "\C-c | s" 'ebib-save-from-multiline-buffer))

  (define-key ebib-multiline-mode-map
    "\C-c k" nil)
  (define-key ebib-multiline-mode-map
    "\C-c | k" 'ebib-cancel-multiline-buffer)

This removes the key bindings for ‘C-c c’, ‘C-c s’ and ‘C-c k’ and sets
up ‘C-c | c’, ‘C-c | s’ and ‘C-c | k’ for use in the multiline edit
buffer.  You can obviously use other keys if you prefer.


File: ebib.info,  Node: Main and Dependent Databases,  Next: Inserting Citations into a Text Buffer,  Prev: Editing the Database,  Up: Top

4 Main and Dependent Databases
******************************

A common workflow with bibliographic data is to have a single database
containing all entries one works with and to export a ‘.bib’ file for a
paper or book with only the relevant entries.  Ebib enables such a
workflow with so-called dependent databases.  A dependent database, as
the name suggests, depends on another, normal database that is called
its main database.  The dependent database contains a subset of the
entries of its main database and all the data of the entries is shared
by both databases.  If you edit an entry in the dependent database, the
edit shows up in the main one as well, and vice versa.

To create a dependent database, type ‘M c’ in the database that is going
to be the main database.  Ebib asks you for a file name and then creates
a new empty database.  You can associate this database with a text
buffer in the normal way (see *note Associating a Database with a Text
Buffer: #associating-a-database-with-a-text-buffer.).  At this point,
when you insert a citation into the text buffer with ‘M-x
ebib-insert-citation’, Ebib offers all entries of the main database for
completion, not just the ones that are already in the dependent
database.  If you select an entry that is not in the dependent database
yet, it is added to it.

It is also possible to add entries in the usual way, i.e., by pressing
‘a’ in Ebib's index buffer.  If you do this in a dependent database,
instead of creating a new entry, you are prompted for an entry from the
main database to add to the dependent one.  In the main database, you
can also push entries to a dependent database with the command ‘M a’.
This command also works on marked entries, making it possible to add
multiple entries to a dependent database in one go.

Deleting an entry in a dependent database only removes it from the
dependent database, not from the main database.  If you delete an entry
from the main database that is also present in a dependent database, it
is removed from both, given that a dependent database can only have
entries that also exist in the main database.

A database can serve as the main database for more than one dependent
databases, but the reverse is not possible: each dependent database can
only have one main database.

If you save a dependent database, it is saved as a normal, standalone
‘.bib’ file that can be used with ‘biblatex’ or BibTeX. When you reopen
the file in Ebib, a special comment at the top of the file makes sure
that Ebib recognises it as a dependent database and loads the main
database as well, if necessary.  Note that when Ebib opens a dependent
database, it only reads the entry keys from the ‘.bib’ file.  The data
of each entry is taken from the main database.  This means that if you
edit a dependent database's ‘.bib’ file outside of Ebib, the changes you
make are ignored when you open the file in Ebib.


File: ebib.info,  Node: Inserting Citations into a Text Buffer,  Next: Searching,  Prev: Main and Dependent Databases,  Up: Top

5 Inserting Citations into a Text Buffer
****************************************

* Menu:

* Single Citations::
* Citations with multiple keys::
* Key Bindings::
* Defining Citation Commands::
* Associating a Database with a Text Buffer::
* Links and Citations in Org buffers::


File: ebib.info,  Node: Single Citations,  Next: Citations with multiple keys,  Up: Inserting Citations into a Text Buffer

5.1 Single Citations
====================

When you're in a text buffer and you have Ebib open in the background
(i.e., you lowered Ebib with ‘z’), you can insert a citation with the
command ‘ebib-insert-citation’.  This command asks for a key and inserts
a citation with that key in a (user-selectable) form that is appropriate
for the current buffer.  By default, this is set up for LaTeX and Pandoc
(http://johnmacfarlane.net/pandoc/) Markdown buffers.  There is some
support for Org mode (http://orgmode.org) as well, as discussed below.

When you invoke ‘ebib-insert-citation’, Emacs prompts you for a key from
the database(s) associated with the current buffer and for a citation
command to use.  You can use ‘TAB’ completion when typing the key.  If
you have selectrum (https://github.com/raxod502/selectrum), ivy
(https://github.com/abo-abo/swiper) or helm
(https://github.com/emacs-helm/helm) installed, however, Ebib uses a
more sophisticated method: instead of typing just the key, you can type
(parts of) the author name, publication year and title in order to find
the reference you wish to cite.

You can define different citation commands for each type of file that
you use.  That is, you can have one set of citation commands for LaTeX
files, another set for Org files, etc.  For LaTeX buffers, the citation
commands that have been predefined are those used by ‘biblatex’ (well,
the most common ones, anyway).  If you use BibTeX, you may need to
customise the option ‘ebib-citation-commands’, as discussed below, *note
Defining Citation Commands: #defining-citation-commands.

For Markdown buffers, three commands have been predefined: ‘text’, which
inserts a citation of the form ‘@Jones1992’, ‘paren’, which inserts a
citation of the form ‘[@Jones1992]’ and ‘year’, which inserts
‘[-@Jones1992]’.  Since these are the only types of citations that
Pandoc Markdown knows, you shouldn't need to change anything.

Ebib also provides a way to insert citations into a buffer from within
Ebib.  If you're in the index buffer and press ‘i’, Ebib asks you for a
buffer to insert the citation into (which defaults to the buffer you
started Ebib from, or the buffer you previously inserted an entry into),
a citation command and also any optional arguments, and then inserts a
citation at the current cursor position in the buffer you've supplied.


File: ebib.info,  Node: Citations with multiple keys,  Next: Key Bindings,  Prev: Single Citations,  Up: Inserting Citations into a Text Buffer

5.2 Citations with multiple keys
================================

Most citation commands in LaTeX can take multiple keys.  To add more
than one key to a citation, you can mark them in Ebib's index buffer
with ‘m’ and then insert them into a text buffer with ‘i’.  If you use
ivy or helm, the standard method that these packages provide for
selecting and acting on multiple candidates can be used if you insert a
citation from within your text buffer with ‘ebib-insert-citation’.  If
you use selectrum or Emacs' built-in completion method, you can enable
selection of multiple keys by setting the option
‘ebib-citations-insert-multiple’.  With this option set, you can select
multiple keys when calling ‘ebib-insert-citation’ by selecting a
candidate and then pressing ‘TAB’.  Once you hit ‘TAB’, you need to add
an ampersand ‘&’ as a separator (possibly surrounded by spaces) and then
you can select the next candidate.  Finish by typing ‘RET’.

Note that selectrum automatically adds the ampersand for you, so you
don't need to type it: after hitting ‘TAB’, you can immediately start
selecting the next candidate.  If you use default completion, however,
you need to type it yourself.

Also note that with default completion, ‘TAB’ completes partial input
strings just as it does in normal completion.  It only selects the
candidate once you've typed enough to narrow down the choices to a
single candidate.  With selectrum, ‘TAB’ always selects the currently
highlighted candidate.  This is the default behaviour of ‘TAB’ in both
completion systems, so should not be confusing.

This method of multiple selection may be somewhat cumbersome and it is
likely unfamiliar to most users.  For this reason, it is not enabled by
default, but it is there if you want to use it.


File: ebib.info,  Node: Key Bindings,  Next: Defining Citation Commands,  Prev: Citations with multiple keys,  Up: Inserting Citations into a Text Buffer

5.3 Key Bindings
================

Of course, the easiest way to use the commands discussed here is to bind
them to a key sequence.  For example, the following binds ‘C-c b’ to
‘ebib-insert-citation’ in AUCTeX's LaTeX mode:

(define-key 'LaTeX-mode-map "\C-cb" 'ebib-insert-citation)

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

‘ebib-insert-citation’ recognises the major mode of the buffer it is
called from and uses this information to determine which kinds of
citations to insert.  So you can bind the ‘ebib-insert-citation’ to the
same key sequence in every text mode in which you use citations and Ebib
will do the right thing.


File: ebib.info,  Node: Defining Citation Commands,  Next: Associating a Database with a Text Buffer,  Prev: Key Bindings,  Up: Inserting Citations into a Text Buffer

5.4 Defining Citation Commands
==============================

Citation commands are defined for specific major modes.  Ebib defines
commands for ‘latex-mode’ (a.k.a.  ‘LaTeX-mode’), for ‘org-mode’ and for
‘markdown-mode’.  As mentioned, the commands defined for LaTeX are those
used by ‘biblatex’.  If you use something else, you may need to set up
some commands yourself.  This can be done by customising the option
"Citation Commands" (‘ebib-citation-commands’).

Each command consists of an identifier, which you type when Ebib prompts
you for a citation command, plus a format string, which is used to
create the actual citation command.

The identifier should be a simple string which you can type easily when
Ebib asks you for a citation command (‘TAB’ completion is available,
though).  The format string can contain a few directives, which are used
to add the citation key and any optional arguments.  The following
directives are recognised:

‘%K’

     the entry key to be inserted.
‘%A’

     an argument, for which the user is prompted.
‘%<...%>’

     optional material surrounding a ‘%A’ directive.
‘%(...%<sep>)’

     a so-called _repeater_, which contains material that can be
     repeated.  If present, the repeater must contain the entry key
     directive ‘%K’.
‘%D’

     a description, for which the user is prompted.  Mainly for use in
     Org citations.

In the simplest case, the format string contains just a ‘%K’ directive:
‘\cite{%K}’.  In this case, ‘%K’ is replaced with the citation key and
the result inserted.  Usually, however, citation commands allow for
optional arguments that are formatted as pre- or postnotes to the
citation.  For example, using the ‘biblatex’ package, you have citation
commands available of the form:

\textcite[cf.][p. 50]{Jones1992}

In order to be able to insert such citations, the format string must
contain ‘%A’ directives:

\textcite[%A][%A]{%K}

With such a format string, Ebib asks the user to provide text for the
two arguments and inserts it at the locations specified by the
directives.  Of course, it is possible to leave the arguments empty (by
just hitting ‘RET’).  With the format string above, this would yield the
following citation in the LaTeX buffer:

\textcite[][]{Jones1992}

The empty brackets are completely harmless, because LaTeX will simply
ignore the empty arguments.  However, you may prefer for the brackets
not to appear if the arguments are empty.  In that case, you can wrap
the brackets and the ‘%A’ directives in a ‘%<...%>’ pair:

\textcite%<[%A]%>%<[%A]%>{%K}

Now, if you leave the arguments empty, Ebib produces the following
citation:

\textcite{Jones1992}

Note however, that this format string is problematic.  If you fill out
the first argument but not the second, Ebib produces the wrong format
string:

\textcite[cf.]{Jones1992}

If only one optional argument is provided, ‘biblatex’ assumes that it is
a postnote, while what you intended is actually a prenote.  Therefore,
it is best not to make the second argument optional:

\textcite%<[%A]%>[%A]{%K}

This way, the second pair of brackets is always inserted, regardless of
whether you provide a second argument or not.

‘Biblatex’ commands also accept multiple citation keys.  When you call
‘ebib-insert-citation’ from within a LaTeX buffer, you can only provide
one key, but when you're in Ebib, you can mark multiple entry keys and
then use ‘i’ to insert them to a buffer.  In this case, Ebib asks you
for a separator and then inserts all keys into the position of ‘%K’:

\textcite{Jones1992,Haddock2004}

It is, however, also possible to specify in the format string that a
certain sequence can be repeated and how the different elements should
be separated.  This is done by wrapping that portion of the format
string that can be repeated in a ‘%(...%)’ pair.  Normally, you'll want
to provide a separator, which is done by placing it between the ‘%’ and
the closing parenthesis:

\textcite[%A][%A]{%(%K%,)}

This format string says that the directive ‘%K’ can be repeated and that
multiple keys must be separated with a comma.  The advantage of this is
that you are no longer asked to provide a separator.

It is also possible to put ‘%A’ directives in the repeating part.  This
is useful for ‘biblatex’'s so-called _multicite_ commands that take the
following form:

\footcites[cf.][p. 50]{Jones1992}[][p. 201]{Haddock2004}

Multicite commands can take more than one citation key in braces ‘{}’
and each of those citation keys can take two optional arguments in
brackets ‘[]’.  In order to get such citations, you can provide the
following format string:

\footcites%(%<[%A]%>[%A]{%K}%)

Here, the entire sequence of two optional arguments and the obligatory
citation key is wrapped in ‘%(...%)’, so that Ebib knows it can be
repeated.  If you now mark multiple entries in Ebib, press ‘i’ and
select the ‘footcites’ command, Ebib will put all the keys in the
citation, asking you for two arguments for each citation key.

Of course it is also possible to combine parts that are repeated with
parts that are not repeated.  In fact, that already happens in the
previous example, because the part ‘\footcites’ is not repeated.  But
the part that is not repeated may contain ‘%A’ directives as well:

\footcites%<(%A)%>(%A)%(%<[%A]%>[%A]{%K}%)

Multicite commands in ‘biblatex’ take two additional arguments
surrounded with parentheses.  These are pre- and postnotes for the
entire sequence of citations.  They can be accommodated as shown.

Lastly, a citation command can also contain a ‘%D’ directive.  This is
mainly for use in Org citations, which take the form
‘[[ebib:<key>][<description>]]’.  The description is not an argument to
the citation command but the string that will be displayed in the Org
buffer.


File: ebib.info,  Node: Associating a Database with a Text Buffer,  Next: Links and Citations in Org buffers,  Prev: Defining Citation Commands,  Up: Inserting Citations into a Text Buffer

5.5 Associating a Database with a Text Buffer
=============================================

The commands ‘ebib-insert-citation’ 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.  How Ebib decides which
databases to consult depends on the major mode of the text buffer.

In a LaTeX buffer, Ebib looks for ‘\addbibresource’ commands or a
‘\bibliography’ command and uses the files specified in them.  If the
variable ‘TeX-master’ is set (which is used by AUCTeX to keep track of a
file's master file), the master file is searched instead.

In non-LaTeX buffers, Ebib first checks if ‘pandoc-mode’ is active; if
it is, Ebib uses the value of the ‘bibliography’ option.  If
‘pandoc-mode’ is not used, Ebib simply uses all databases that are
currently open.

Keep in mind that Ebib tries to determine the relevant databases only
once per buffer.  It stores the result of this search and uses it the
next time either of these commands is used.  Therefore, if you add,
rename or remove bibliography files in your project, you may need to
reload the file (use ‘M-x revert-buffer’ or ‘C-x C-v RET’).

You can override Ebib's automatic association of ‘.bib’ files to a
buffer by setting the variable ‘ebib-local-bibfiles’ to a list of files.
This can be done as a file-local or a directory-local variable, or as a
customisable option.


File: ebib.info,  Node: Links and Citations in Org buffers,  Prev: Associating a Database with a Text Buffer,  Up: Inserting Citations into a Text Buffer

5.6 Links and Citations in Org buffers
======================================

Currently, Org mode does not have real support for citations (though
support is planned for a future release).  Ebib provides a way to add
links to BibTeX entries to an Org file which, with some coaxing, can be
used as citations.

If you call ‘ebib-insert-citation’ in an Org buffer, you can add a link
to an entry in a ‘.bib’ file that's open in Ebib.  The link has the form
‘[[ebib:<key>][<description>]]’.  The description is a user-provided
string, which you are prompted for, but a default description is
provided, which you can accept by pressing ‘RET’.  This default
description is created by the function in
‘ebib-citation-description-function’ which uses the author name and
publication year to create a description.

If you use this type of Org link, you may want to load the ‘org-ebib’
package, which allows you to open Ebib with ‘org-open-at-point’ (by
default bound to ‘C-c C-o’), taking you to the entry in the link
(provided its database is opened in Ebib).

The ‘org-ebib’ package also allows you to create Org links to Ebib
entries with ‘org-store-link’ when you're in the entry buffer.  Links
created in this way have the same form, but they can also specify the
‘.bib’ file containing the entry by adding an ‘@’ sign after the key and
the name or full path of the file.  Which type of link is produced is
controlled by the user option ‘org-ebib-link-type’.


File: ebib.info,  Node: Searching,  Next: Filters,  Prev: Inserting Citations into a Text Buffer,  Up: Top

6 Searching
***********

Ebib provides several ways of searching through your database(s).  This
section describes two simple search strategies: jumping to an entry and
searching for a string or regular expression.  The next section
discusses a more powerful search mechanism in the form of filters.

If you want to look for a particular entry, the easiest way to do this
is to use ‘j’.  This command (‘ebib-jump-to-entry’) asks for an entry
key, offering completion while you type.  Note that you can use this
command to search for an entry in all open databases.  If you want to
restrict it to just the current database, use a prefix argument: ‘C-u
j’.

If you use selectrum (https://github.com/raxod502/selectrum), ivy
(https://github.com/abo-abo/swiper) or helm
(https://github.com/emacs-helm/helm), this method is actually very
convenient, because completion is more sophisticated: you can search not
on entry key but on any part of the author/editor name, the title and
the year.

If you want to search the entire contents of your entries, not just the
author/editor names and the titles, you can use ‘/’.  This command
(‘ebib-search’) searches for a string (more precisely, a regular
expression) starting from the current entry (i.e., _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.  (You can use filters for that.)  Note
that if the search term is found in a field with a multiline value, Ebib
will highlight the ellipsis symbol ‘[...]’ that is displayed after the
last line of the field value.

A search term may of course appear more than once in the database.  To
search for the next occurrence, type ‘RET’.  This continues searching
for the search term in the rest of the database.  Again, the first entry
found to contain the search string is displayed.  Note that the search
does not wrap: if the end of the database is reached, Ebib stops
searching and informs you that no further occurrence of the search
string was found.  If you want to continue searching from the top, type
‘g’ and then continue the search with ‘RET’.

Note that once you've started a search with ‘/’, Ebib activates a
transient key map called ‘ebib-search-map’.  It is this map that holds
the binding for ‘RET’ to continue searching after the current entry and
of the key ‘g’ to jump to the top of the database.  There are also
bindings for the left and right cursor keys, which take you to the
previous and next database, so you can continue searching there.

Exiting a search (i.e., getting rid of the transient key map) is done by
pressing any key other than ‘RET’, ‘g’ or the left/right cursor keys.
The search is ended and the command associated with this key is executed
normally.  If you want to repeat a previous search, you can pass a
prefix argument to ‘/’.  So typing ‘C-u /’ starts searching for the
previous search string again.

Note that if you start a search in a filtered database (i.e., a database
in which not all entries are visible; see the next section), only the
visible entries are searched.  If the search string is present in the
database but not in one of the visible entries, Ebib will respond with a
"search string not found" message.


File: ebib.info,  Node: Filters,  Next: Importing BibTeX entries,  Prev: Searching,  Up: Top

7 Filters
*********

Ebib also has a much more sophisticated search mechanism that makes use
of _filters_.  A filter is basically a search expression that selects
entries from the current database.  When you apply a filter to a
database, only the entries that match are shown.  With filters, you can,
for example, 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 hibernation" in the ‘keyword’ field,
etc.  Basically, the filter can consist of an arbitary number of search
criteria combined with the logical operators ‘and’, ‘or’ and ‘not’.

* Menu:

* Simple Selection::
* Complex Filters::
* Storing and Saving Filters::
* Special Filters::
* An Example Listing Recent Additions::
* Properties of Filtered Databases::


File: ebib.info,  Node: Simple Selection,  Next: Complex Filters,  Up: Filters

7.1 Simple Selection
====================

Creating a filter 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 then runs this filter on the database, and
only shows those entries that match the filter.  To indicate that a
filter is active, the active filter is displayed in the mode line of
index buffer.  (The filter can be displayed in Lisp form, if you prefer:
customise ‘ebib-filters-display-as-lisp’ to do so.)

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 will give you all entries that have a field
that contains ‘"Jones"’ in them.

Note that you can also select items based on their entry type.  In order
to do that, you need to specify ‘=type=’ as the field to search, which
is the field name under which Ebib stores the entry type internally.
(There is also a "normal" field called ‘type’, hence the equal signs.)
If you search the ‘=type=’ field, only exact matches are returned, so if
you search for ‘book’, only the entries that are of type ‘book’ are
returned, not those of type ‘inbook’.  You can use ‘TAB’ completion in
this case, by the way.

If you specify the ‘keywords’ field, the keywords associated with your
database are available for ‘TAB’ completion as well.  Though you can
enter any search term, of course.


File: ebib.info,  Node: Complex Filters,  Next: Storing and Saving Filters,  Prev: Simple Selection,  Up: Filters

7.2 Complex Filters
===================

Once you have filtered your database, you can refine or extend it.  For
example, suppose you have a filter selecting all entries with ‘"Jones"’
in the ‘author’ field and want to add all entries that have ‘"Jones"’ in
the editor field to your selection.  In this case you need to do 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 (i.e., most likely none at all).

To perform a logical ‘or’ operation, press the key ‘|’ (the pipe bar).
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 index
buffer.

It is also possible to perform a logical ‘and’ on the filter.  Use this
if you want to select those entries that contain ‘"Jones"’ in the
‘author’ field and e.g. ‘"symbiotic hibernation"’ in the ‘keyword’
field.  A logical ‘and’ operation is done with the key ‘&’.  (Note: this
is the same key that is used to create the filter.  In fact, you can
create a filter with ‘|’ as well: when used in an unfiltered database,
‘&’ and ‘|’ are equivalent.  They are only different when a filter is
already active.)

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.  For
example, 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.

There is another way of performing a logical ‘not’ operation, which is
only available when a filter is active: by pressing the key ‘~’, you
invert the current filter.  That is, if you have a filtered 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.

When a filter is active, the filter itself is displayed at the top of
the index buffer.  If the index window is too small to display the
entire filter (which can easily happen if Ebib is set to split the frame
vertically rather than horizontally), you can press ‘F v’ (uppercase
‘F’, small ‘v’), which will display the filter in the minibuffer.

To cancel the filter and return to the normal view of the database,
press ‘F c’.  For convenience, this action is also available with ‘c’,
which normally closes a database.  If a filter is active, however, it
simply cancels the filter.  (If you find this behaviour confusing, you
can rebind the ‘c’ key to the function ‘ebib-close-database’.  See *note
Modifying Key Bindings: #modifying-key-bindings. for details.)

By default, a filter does not check the values of fields in
cross-referenced entries.  The rationale for this is that if a filter
applies to, e.g., an entry of type ‘Collection’, any ‘InCollection’
entries contained in it will match the filter, which is not always
desirable.  If you do wish to include cross-referenced entries, however,
you can press ‘F x’, which toggles the inclusion of cross-referenced
entries.  If you wish to include cross-referenced entries by default,
customise the user option ‘ebib-filters-include-crossref’.


File: ebib.info,  Node: Storing and Saving Filters,  Next: Special Filters,  Prev: Complex Filters,  Up: Filters

7.3 Storing and Saving Filters
==============================

When you cancel a filter, it is automatically stored so that it can be
reapplied later.  To reapply a filter, type ‘F L’.  This will reapply
the last used filter regardless of which database you're in.  That is,
you can use this to search more than one database without having to type
the filter over and over.

However, Ebib only stores one filter this way.  If you want to store
more filters, you have to name them.  You can store the currently active
filter or the last used filter with ‘F s’.  Ebib will ask you for a name
for the filter in order to identify it later.  (By default, filter names
are case-insensitive, but if you prefer to use case-sensitive filter
names, you can unset the option ‘ebib-filters-ignore-case’.)  When Ebib
is closed, all stored filters are saved to a file and they're
automatically reloaded when you open Ebib again.  Stored filters are not
associated with a particular database: once a filter is stored, it is
available to all databases.

You can apply a stored filter with ‘F a’.  This will ask for the name of
a filter and apply it to the current database.  You can extend the
filter in the normal way, though the changes will not be stored
automatically.  To store it, type ‘F s’ again.  You can store the
extended filter under the old name, in which case Ebib will ask you for
confirmation, or under a new name, which will store it as a new filter,
keeping the old one.

The file that Ebib uses to store filters is ‘~/.emacs.d/ebib-filters’,
although that can of course be customised (‘ebib-filters-default-file’).
As mentioned, stored filters are saved automatically when Ebib closes,
but you can also save them manually with ‘F S’.  Note that if there are
no stored filters when Ebib is closed (or when you press ‘F S’), the
file is deleted.

You can also save your filters to a different file with ‘F w’.  Such a
filter file can be reloaded later with ‘F l’.  If you load filters from
a file while you still have stored filters, you are asked if you want to
replace them completely or if you want to add the new filters to the
existing ones.  In the latter case, however, filters whose name conflict
with existing filters are not loaded.  (Ebib will log a message about
this when it happens.)

To see what filters are currently stored, use ‘F V’.  If you want to
rename a filter, you can do so with ‘F R’.

Note that cancelling a filter with ‘F c’ does not delete it from the
list of stored filters, it will remain available for later application.
If you want to delete a filter from the list of stored filters, use ‘F
d’.  You can also delete all stored filters with ‘F D’.  These deletion
commands do not ask for confirmation, but if you delete any filters by
accident, you can reload them from ‘~/.emacs.d/ebib-filters’ with ‘F l’.


File: ebib.info,  Node: Special Filters,  Next: An Example Listing Recent Additions,  Prev: Storing and Saving Filters,  Up: Filters

7.4 Special Filters
===================

Filters are essentially Lisp expressions that consist of the functions
‘and’, ‘or’, and ‘not’, together with a special macro ‘contains’.
However, filters are not limited to these forms.  They can essentially
contain any Lisp expression.  It is not possible to create such special
filters interactively, but it is possible to write such filters and put
them in a filter file, or to write a function that creates such a
special filter.

A filter is a Lisp expression that should return either ‘t’ or ‘nil’,
indicating whether the entry being tested matches the filter or not.
The contents of the entry is available in a variable ‘ebib-entry’.  This
variable is given a value by the function that runs the filter, but it
is not passed as an argument.  Rather, it is a dynamic variable, which
means that the file that defines the filter function should declare the
variable with ‘(defvar ebib-entry)’.  When the filter is run, the value
of ‘ebib-entry’ is an alist of fields and their values.  These include
the fields ‘=key=’ and ‘=type=’ for the entry key and type.  For
example:

(("author" . "{Noam Chomsky}")
 ("title" . "{Syntactic Structures}")
 ("publisher" . "{The Hague: Mouton}")
 ("year" . "{1957}")
 ("timestamp" . "{2007-12-30 12:00:00 (CET)}")
 ("file" . "{c/Chomsky1957.pdf}")
 ("=type=" . "book")
 ("=key=" . "Chomsky1957"))


File: ebib.info,  Node: An Example Listing Recent Additions,  Next: Properties of Filtered Databases,  Prev: Special Filters,  Up: Filters

7.5 An Example: Listing Recent Additions
========================================

One special filter is included with Ebib.  It filters recent additions
to the database.  The command that creates the filter is
‘ebib-list-recent’:

(defun ebib-list-recent (days)
  "List entries created in the last DAYS days."
  (interactive "nNumber of days: ")
  ;; Save the database's current filter, if there is one.
  (let ((filter (ebib-db-get-filter ebib--cur-db)))
    (when filter (setq ebib--filters-last-filter filter)))
  (let*
      ;; Calculate the from-date in Emacs' time format.
      ((date (time-subtract (current-time) (days-to-time days)))
       ;; Create a Lisp expression that will function as the filter.
       (filter `(ebib--newer-than (quote ,date))))
    ;; Install it as the current database's filter.
    (ebib-db-set-filter filter ebib--cur-db)
    ;; Update the current entry key.
    (ebib-db-set-current-entry-key (ebib--get-key-at-point) ebib--cur-db)
    ;; Update the display, so that only filtered entries are visible.
    (ebib--update-buffers)))

First, this function saves the current filter if there is one.  It then
calculates a date in Emacs' internal time format by subtracting the
number of days provided by the user from the current date and creates a
Lisp expression that tests whether an entry's timestamp is earlier or
later than this date.  This expression is then installed as the filter
for the current database.  A call to ‘ebib--update-buffers’ then updates
the display, taking the filter into account.

The function ‘ebib--newer-than’ is defined as follows:

(defun ebib--newer-than (date)
  "Function for use in filters.
Return t if the entry being tested is newer than DATE.  DATE must
be a list of the format returned by `current-time' and is
compared to the timestamp of the entry being tested.  If the
entry has no timestamp, or a timestamp that cannot be converted
into a date representation, return nil."
  (let ((timestamp (cdr (assoc-string "timestamp" ebib-entry))))
    (when (and timestamp
               (setq timestamp (ignore-errors (date-to-time timestamp))))
      (time-less-p date timestamp))))

This function obtains the time stamp of the entry being tested from the
variable ‘ebib-entry’ and then tries to convert it to Emacs' time
format.  If successful, it compares this time to the date passed as an
argument and returns ‘t’ if the latter precedes the former.


File: ebib.info,  Node: Properties of Filtered Databases,  Prev: An Example Listing Recent Additions,  Up: Filters

7.6 Properties of Filtered Databases
====================================

When a filter is active, there are a few things that are not possible or
function differently.  First, it is not possible to add or delete
entries, either interactively or by merging or exporting.  Exporting
from a filtered database or saving a filtered database is also disabled.
Editing existing entries is possible, however.  Note that if the entry
doesn't match the filter anymore after the edit, it doesn't disappear
from view.  For that, you need to reapply the filter with ‘F r’.

It is also possible to mark entries.  Marked entries stay marked when
you cancel the filter, so in order to do something with all the entries
matching a filter, you can mark them all in the filter view with ‘C-u
m’, then cancel the filter and perform an action on them.

If a database has an active filter, the save command is disabled,
because it would not be clear whether you want to save the entire
database or just the filtered entries.  If you want to save only the
filtered entries to a file, you can use the command ‘w’ (or the menu
option "Database | Save As").  This also saves the ‘@String’,
‘@Preamble’ and ‘@comments’, as well as any file-local variables, so you
will have a self-contained ‘.bib’ file with only the filtered entries.
In order to save the entire database, you need to cancel the filter.
(After saving, you can reapply the filter with ‘F L’, of course.)

One final note: of all the filter-related commands, ‘~’, ‘F c’, ‘F r’,
‘F s’ and ‘F v’ are only available when a filter is active.  The other
commands operate on the stored filters and can be used when no filter is
active.


File: ebib.info,  Node: Importing BibTeX entries,  Next: Linking to external resources,  Prev: Filters,  Up: Top

8 Importing BibTeX entries
**************************

Manually entering new BibTeX entries can be tedious and error-prone.  If
an entry is already available in digital form somehow, there are other
ways to get entries into Ebib.

* Menu:

* Merging bib files::
* Importing entries from a buffer::
* Integration with the Biblio package::
* Multiple Identical Fields::


File: ebib.info,  Node: Merging bib files,  Next: Importing entries from a buffer,  Up: Importing BibTeX entries

8.1 Merging ‘.bib’ files
========================

In the index buffer, the Ebib menu has an option to merge a second
‘.bib’ file into the current database.  Ebib reads the entries in this
file and adds them to the database.  Duplicate entries (that is, entries
with an entry key that already exists in the database) will normally 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.  However, if you've customised Ebib to automatically generate
keys, duplicate entries will be merged into the current database under a
unique key.


File: ebib.info,  Node: Importing entries from a buffer,  Next: Integration with the Biblio package,  Prev: Merging bib files,  Up: Importing BibTeX entries

8.2 Importing entries from a buffer
===================================

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 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-entries’.  Ebib then goes through the buffer (or the active
region) and loads all BibTeX entries it finds into the current database
(i.e. the database that was active when you lowered Ebib).  Text in the
buffer that is not part of a BibTeX entry is ignored.

If a BibTeX entry in the buffer lacks an entry key (which sometimes
happens with BibTeX entries found on the internet), Ebib will generate a
temporary key for it of the form ‘<new-entryXX>’, where ‘XX’ is a
number.  You can change such keys by hitting ‘E’ in the index buffer.
Such a key will also automatically be replaced with a more sensible key
if you edit the entry.  See the option "Autogenerate Keys"
(‘ebib-autogenerate-keys’) for details.


File: ebib.info,  Node: Integration with the Biblio package,  Next: Multiple Identical Fields,  Prev: Importing entries from a buffer,  Up: Importing BibTeX entries

8.3 Integration with the Biblio package
=======================================

Biblio (https://github.com/cpitclaudel/biblio.el) is a package with
which you can browse a number of online bibliographic databases and
import BibTeX entries based on their DOI. If you use Biblio, you can add
support for it to Ebib by loading the package ‘ebib-biblio’ in your init
file and adding two keybindings: one to ‘ebib-index-mode-map’ and one to
‘biblio-selection-mode-map’:

(require 'ebib-biblio)
(define-key ebib-index-mode-map (kbd "B") #'ebib-biblio-import-doi)
(define-key biblio-selection-mode-map (kbd "e") #'ebib-biblio-selection-import)

Or with ‘use-package’:

(use-package ebib-biblio
  :after (ebib biblio)
  :bind (:map ebib-index-mode-map
              ("B" . ebib-biblio-import-doi)
              :map biblio-selection-mode-map
              ("e" . ebib-biblio-selection-import)))

If you now call ‘biblio-lookup’, you can use the key ‘e’ (or any other
key you choose, of course) in Biblio's selection buffer to import the
selected entry into the current Ebib database.

Additionally, you can use the key ‘B’ in Ebib's index buffer to import
an entry into the current database if you have its DOI. Here, too, you
can choose a different key, of course.

When fetching entries via Biblio, Ebib checks for duplicates based on
the key of the new entry.  This will only work reliably if both Ebib and
Biblio are configured to automatically generate BibTeX keys.  Ebib does
this by default (see the option ‘ebib-autogenerate-keys’), Biblio can be
configured to do so by setting the option ‘biblio-bibtex-use-autokey’.

Ebib and Biblio both use the functionality of ‘bibtex.el’ to generate
keys.  Refer to the documentation string of the function
‘bibtex-generate-autokey’ to find out how to customise this
functionality.


File: ebib.info,  Node: Multiple Identical Fields,  Prev: Integration with the Biblio package,  Up: Importing BibTeX entries

8.4 Multiple Identical Fields
=============================

Under normal circumstances, a BibTeX entry only contains one occurrence
of each field.  If ‘biblatex’ or BibTeX notices that an entry contains
more than one occurrence of a required 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
‘biblatex’ will use the value of the _first_ occurrence, not the last.)
When extra fields appear more than once in an entry, ‘biblatex’ does not
warn you, since it ignores those fields anyway.  Here, too, Ebib's
standard behaviour is to ignore all but the last value.

However, some online reference management services "use" this feature of
BibTeX in that they put multiple ‘keywords’ fields in the BibTeX entries
that they produce.  If you were to import such an entry into Ebib, you
would lose all your keywords except the last one.  To remedy this, you
can tell Ebib that it should allow multiple occurrences of a single
field in a BibTeX entry.  You can do this by setting the customisation
option "Allow Identical Fields".

With this option set, Ebib collapses the multiple occurrences into a
single occurrence.  All the values of the different occurrences are
collected and stored in the single occurrence, separated by the default
keywords separator (‘ebib-keywords-separator’).  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 = {hibernation}
}

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, hibernation}
}


File: ebib.info,  Node: Linking to external resources,  Next: Notes files,  Prev: Importing BibTeX entries,  Up: Top

9 Linking to external resources
*******************************

BibTeX entries can contain links to external files, URLs and DOIs.  Ebib
offers several facilities to work with these.

* Menu:

* Viewing and Importing Files::
* Calling a Browser for URLs and DOIs::


File: ebib.info,  Node: Viewing and Importing Files,  Next: Calling a Browser for URLs and DOIs,  Up: Linking to external resources

9.1 Viewing and Importing Files
===============================

If you have electronic versions of the papers in your database stored on
your computer, or any other file associated with your entries (e.g.,
notes, if you store those in separate files) you can use Ebib to call
external viewers for these files or have them opened in Emacs.  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.  If you
have more than one file in the ‘file’ field (separated by
‘ebib-filename-separator’), you are asked which one you want to open.
Alternatively, you can use a prefix argument: ‘M-2 f’ will open the
second file in the file field.

The file names in the ‘file’ field do not have to have full paths.  You
can set the option "File Search Dirs" to a list of directories that Ebib
should search when opening a file from the ‘file’ field.  Note that Ebib
searches only the directories in this list, not their subdirectories.
However, you can specify a relative path in the ‘file’ field: 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".  As an extra service, Ebib also searches
for the base filename, i.e., ‘Abney1987’ in this particular case.

Ebib can call different external programs depending on the file
extension of the relevant file.  The option ‘ebib-file-associations’
allows you to specify which programs to call for which types of files.
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 ‘exec-path’,
but you can of course specify the full path to the program.

If you need to pass further command-line options to the executable, you
can do so, but you will need to include a directive ‘%s’ in the string,
which will be replaced with the full path to the file you are opening.
If you have special requirements that cannot be handled in this way, you
can also specify an Elisp function to handle the file.  This function
should take one argument, the path of the file being opened.

If you do not specify any program for a particular extension (or if you
remove the extension from ‘ebib-file-associatons’ altogether), Ebib
opens the file in Emacs itself, using ‘find-file’.  Use this if you want
to read pdf files in Emacs, for example, with ‘doc-view-mode’ or
‘pdf-tools’ (https://github.com/politza/pdf-tools).

If the ‘file’ field of an entry is empty, pressing ‘f’ causes Ebib to
search for a pdf file with a name based on the entry key.  By default,
Ebib just appends ‘.pdf’ to the entry key and tries to find a file by
the name thus created.  If you want, you can modify the file name that
Ebib searches for by setting the option ‘ebib-name-transform-function’
to a function that performs the transformation.  This function takes the
key of the current entry as its argument (as a string), and should
return the file name to use (without ‘.pdf’, which is added
automatically).  Note that you can use the function
‘ebib-get-field-value’ to access the values of the entry's fields (you
need to pass ‘ebib--cur-db’ for the ‘db’ argument).

There are two functions that can help you to attach files to your
database: ‘ebib-download-url’ and ‘ebib-import-file’.  By default, these
are not bound to any keys, but they can of course be called with ‘M-x’.
The first of these, ‘ebib-download-url’ attempts to convert the URL in
the ‘url’ field into a URL that points to a pdf file, downloads that
file, renames it and saves it to a target directory specified by the
user.  The name under which the file is saved is created by applying the
function in ‘ebib-name-transform-function’ to the entry key and adding
‘.pdf’ to it.

How a URL should be converted to a URL pointing to the pdf file depends
on several factors, of course.  The option
‘ebib-url-download-transformations’ is used to decide how to convert a
particular URL. Currently, only three internet archives are supported:
arXiv (https://arxiv.org/), lingBuzz (https://ling.auf.net/lingBuzz/)
and JSTOR (https://www.jstor.org/).  Suggestions for other sites are of
course welcome.

The function ‘ebib-import-file’ can be used to import a file into the
database that is stored on your computer somewhere.  It asks for the
file name, renames the file and moves it to a target directory specified
by the user.  The file name is created in the same way as with
‘ebib-download-url’: by applying the function in
‘ebib-name-transform-function’ to the entry key.  The extension of the
original file is maintained, however, so it doesn't just work for pdf
files.

The target directory that ‘ebib-download-url’ and ‘ebib-import-file’ use
is determined by the user option ‘ebib-import-target-directory’.  By
default, this points to the first directory in ‘ebib-file-search-dirs’,
but you can set it to use the same directory as the database into which
the URL/file is imported, to a fixed directory, or you can have Ebib ask
you each time for a target directory.

Both ‘ebib-download-url’ and ‘ebib-import-file’ add the imported file to
the ‘file’ field if it is not already there.

* Menu:

* Editing the file field::


File: ebib.info,  Node: Editing the file field,  Up: Viewing and Importing Files

9.1.1 Editing the ‘file’ field
------------------------------

As mentioned above, editing the ‘file’ field is a bit different from
editing other fields.  Instead of typing the full contents of the file
field, you are asked to specify a single file name.  When you hit ‘RET’,
Ebib adds the filename to the ‘file’ field, appending it to any existing
contents (adding a separator if necessary), and then asks you for the
next file.  If you don't want to add another, just hit ‘RET’.  The
default separator is ‘"; "’ (semicolon-space), but this can be
customised (see the option "Filename Separator" for details).  The
advantage of this method is that you can use ‘TAB’ completion to
complete file names.

The first directory in the option "File Search Dirs" is used as the
starting directory for filename completion when editing the ‘file’
field.  Note that when completing file names, Ebib does not take the
directories in "File Search Dirs" into account: completion is done using
the standard Emacs file name completion mechanism.  However, when you
enter a file name, Ebib checks if it is in a (subdirectory of) one of
the directories in "File Search Dirs", and if so, cuts off the relevant
part of the file name to turn it into a relative path.  (You can disable
this behaviour with the option ‘ebib-truncate-file-names’: if unset,
file names are always stored as absolute paths.)


File: ebib.info,  Node: Calling a Browser for URLs and DOIs,  Prev: Viewing and Importing Files,  Up: Linking to external resources

9.2 Calling a Browser for URLs and DOIs
=======================================

With most scientific literature nowadays being available on-line, it is
common to store URLs and DOIs in a BibTeX database.  ‘Biblatex’ has
standardised fields for this information, for BibTeX, Ebib adds these
fields to each entry.

To open a URL in your default browser, you can type ‘u’ in the index or
entry buffer.  Ebib takes the URL stored in the ‘url’ field of the
current entry and passes it to your browser.  If you happen to have more
than one URL stored in the relevant field, Ebib will ask you which one
you want to open.  Alternatively, you can use a prefix argument: typing
‘M-2 u’ sends the second URL to your browser.

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. The semicolon is included here even though it is actually
a valid character in URLs.  This is done for consistency, because the
semicolon (actually, semicolon+space) is the standard separator for
files in the ‘file’ field and in this way, you can use the same
separator to distinguish multiple URLs in the ‘url’ field.

By default Ebib also regards everything that is enclosed in a LaTeX
‘\url{...}’ command as a URL. So if you use ‘;’ to separate URLs and
then happen to run into a URL that contains a semicolon, you can enclose
it in ‘\url{...}’ and it will be recognised properly.  You can, of
course, customise the regular expression that controls this behaviour.
See the option "Url Regexp" for details.

Similarly, with the key ‘I’ in the index buffer you can send a DOI to a
browser.  The DOI must be stored in the ‘doi’ field.  Unlike URLs, there
can only be one DOI in this field.  The DOI is extracted from this
field, and a resolver URL is prepended (‘https://doi.org/’ by default,
customisable as ‘ebib-doi-resolver’) before being sent to the browser.
Note that if the ‘doi’ field already contains a DOI resolver URL, it is
removed.

Ebib uses the Emacs function ‘browse-url’ to call the default browser on
the system.  If you prefer to use another browser, however, you can
specify this with the option "Browser Command".


File: ebib.info,  Node: Notes files,  Next: Managing a reading list,  Prev: Linking to external resources,  Up: Top

10 Notes files
**************

Ebib supports the ‘annotation’ field (or ‘annote’ field in BibTeX), but
if you prefer to keep notes outside the ‘.bib’ file, there is an easy
way to do that as well.  When you hit ‘N’ on an entry in the index
buffer, Ebib creates a note for the entry, which is saved in a separate
file.  If an entry already has a note associated with it, ‘N’ opens it.
By default, notes are created as Org entries.  (Changing that is
possible, though you may lose some convenience.  See below for some
pointers.)

In the entry buffer, the first few lines of the note are shown under a
pseudo-field ‘external note’.  This is not an actual field in the ‘.bib’
file, even though it is displayed as such.  (You can customise this
behaviour.)

When you record a new note, Ebib pops up a buffer and adds the note to
the end of the relevant notes file.  If you prefer, you can also use Org
mode's capture system to record new notes.  This has the advantage that
you have more control over the location where a note is stored and that
you can have more than one capture template.

Note that with Ebib version 2.30 (released Feb. 2021), the functionality
for notes files has changed and it may be necessary to update your
configuration.  See *note Upgrading from earlier Ebib versions:
#upgrading-from-earlier-ebib-versions. below for details.

* Menu:

* Configuring files for storing notes::
* Hooks::
* Upgrading from earlier Ebib versions::
* Customising the notes file format::
* Displaying notes::
* Using Markdown for notes::
* Using org-capture to record notes::


File: ebib.info,  Node: Configuring files for storing notes,  Next: Hooks,  Up: Notes files

10.1 Configuring files for storing notes
========================================

By default, Ebib saves each note to a separate file in the first
directory listed in ‘ebib-file-search-dirs’.  Since this is also the
main directory for your ‘.bib’ files, it is advisable to use a different
directory, which you can do by customising the option
‘ebib-notes-directory’.

Instead of using a separate file for each note, you can also store
multiple notes in a notes file.  To do this, you need to configure the
option ‘ebib-notes-storage’ and set it to ‘multiple-notes-per-file’.
Having done this, you can add the files you wish to use for notes to
‘ebib-notes-locations’.  You can also add directories to this list: all
Org files in those directories are considered notes files.  (This does
not mean that they _must_ contain notes.  Ebib searches all Org files in
‘ebib-notes-locations’ for notes, but it won't complain if it doesn't
find any, or if any of the files contain more than just notes.)

The procedure for creating a new note depends on the setting of
‘ebib-notes-storage’.  If this option is set to ‘one-note-per-file’ (the
default), Ebib creates a new note file in ‘ebib-notes-directory’ and
gives it a name that consists of the entry key plus the extension
".org".  Before creating the file name, however, Ebib applies the
function in ‘ebib-notes-name-transform-function’ to it, or, if this is
not set, the function in ‘ebib-name-transform-function’.  This means
that you can configure the name of the new note file to whatever you
prefer.  (See *note Viewing and Importing Files:
#viewing-and-importing-files. for some examples of the changes that can
be applied.  Note that if you do not wish to apply any changes but also
do not want the function in ‘ebib-name-transform-function’ to be
applied, you can set ‘ebib-notes-name-transform-function’ to
‘identity’.)

If ‘ebib-notes-storage’ is set to ‘multiple-notes-per-files’, Ebib won't
create a new file when you create a new note.  Instead, it will ask you
for the file to save the note to and offer the files in
‘ebib-notes-locations’ as candidates.  If you don't want to be asked,
you can set the option ‘ebib-notes-default-file’: new notes are then
automatically stored to that file.  You can subsequently use Org to move
notes around or archive them.

New notes are created based on a template (‘ebib-note-template’).  By
default, the note is a top-level item with an Org headline consisting of
the author(s), year and title of the entry.  The entry also has a
‘:PROPERTIES:’ block containing a custom ID for the entry, which
consists of the entry key.  If ‘ebib-notes-storage’ is set to
‘multiple-notes-per-file’, this custom ID is essential, because it is
what Ebib uses to find the note.  (If you use ‘one-file-per-note’, the
file name is used to identify an entry, even though the custom ID is
still included.)

The template can of course be customised.  Details are discussed below.


File: ebib.info,  Node: Hooks,  Next: Upgrading from earlier Ebib versions,  Prev: Configuring files for storing notes,  Up: Notes files

10.2 Hooks
==========

If ‘ebib-notes-storage’ is set to ‘multiple-notes-per-file’, Ebib uses
three hooks to control the way a note is displayed.  By default, when
you jump to a note from Ebib, the Org file is narrowed to the subtree
containing the note and point is positioned at the note's heading.

When an existing note is displayed, the hook
‘ebib-notes-open-note-after-hook’ is run.  By default, this contains two
functions: ‘org-back-to-header’, which puts point at the start of the
note, and ‘org-narrow-to-subtree’, which narrows the notes buffer to
just the note you're viewing.

When a new note is created, the hook ‘ebib-notes-new-note-hook’ is run.
By default, this contains the function ‘org-narrow-to-subtree’.  Point
is not positioned at the heading, but after the title and the
‘:PROPERTIES:’ block, so that you can start typing right away.  (The
position of point can be customised in the template.)

Because both these hooks narrow the notes buffer, the buffer must be
widened again when searching for another note.  This is handled by the
hook ‘ebib-notes-search-note-before-hook’, which is run every time Ebib
searches a note and by default contains the function ‘widen’, so that
the entire buffer is searched.

All three hooks are customisable.  For example, if you prefer not to
narrow the buffer, simply remove the corresponding functions from the
hooks.


File: ebib.info,  Node: Upgrading from earlier Ebib versions,  Next: Customising the notes file format,  Prev: Hooks,  Up: Notes files

10.3 Upgrading from earlier Ebib versions
=========================================

Ebib 2.30 added the option to have more than one file with multiple
notes.  This unfortunately required some changes to the customisation
options, which means that you may need to revisit your configuration.

If you have been using one file per note, there is nothing you need to
do.  This is now the default method and the user option
‘ebib-notes-directory’ has not changed.

If, however, you have been storing your notes in a single file, you will
need to set the user option ‘ebib-notes-storage’ to
‘multiple-notes-per-file’.  Furthermore, the option ‘ebib-notes-file’
has been deprecated in favour of ‘ebib-notes-default-file’.  Although
‘ebib-notes-file’ is still an alias for the new option, it is a good
idea to update your configuration.  You may also want to check out the
new option ‘ebib-notes-locations’, which allows you to have more than
one Org file for your notes.


File: ebib.info,  Node: Customising the notes file format,  Next: Displaying notes,  Prev: Upgrading from earlier Ebib versions,  Up: Notes files

10.4 Customising the notes file format
======================================

When creating a new note, the default template creates an Org entry
whose header consists of the author or editor, the year of publication
and the title.  The entry has a ‘:PROPERTIES:’ block containing a
‘Custom_id:’.  This can all be customised (although it is important to
keep the ‘Custom_id:’ property.)  To see how this can be done, it is
easiest to look at the default template first:

"* %T
:PROPERTIES:
%K
:END:
%%?
"

This template contains two format specifiers: ‘%K’ and ‘%T’.  ‘%K’ is
replaced with the key of the entry prepended with the string
‘"Custom_id: "’ in order to create an Org property.  The ‘%T’ specifier
is replaced with the title of the note, which consists of the author (or
editor), the year of publication and the title of the bibliography
entry.  The template also contains the string ‘"%%?"’, which indicates
the position of the cursor when a new note is created.  (For backward
compatibility, the string ‘">|<"’ can also be used to indicate the
cursor position, although this does not work if you use ‘org-capture’ to
record new notes.)

To change the template, you must customise the option
‘ebib-notes-template’.  If you use Org for your notes and keep your
notes in a single file, the template *must* contain a ‘:PROPERTIES:’
block with the ‘%K’ format specifier, because it is required in order to
identify the note and connect it to its BibTeX entry.  Without it, Ebib
won't be able to tell whether an entry has a note or not and won't be
able to display it.  Also keep in mind that the ‘%K’ specifier *must*
occur on a line of its own in the template.

If you use a separate file for each note, the notes are identified by
the file name, so there's no real need for the ‘:PROPERTIES:’ block, but
it can still be useful if you use other Org-based tools on your note
files (or if you ever want to collect your notes into a single file but
keep them available for Ebib.)

There are a few more specifiers that may be used in the template: ‘%F’
creates an Org link to the file in the BibTeX entry's ‘file’ field, ‘%D’
creates an Org link to the DOI in the entry's ‘doi’ field, and ‘%U’ an
Org link to the entry's ‘url’ field.  There is also a ‘%L’ specifier,
which creates an Org link to the entry's file, its DOI, or its URL,
whichever is found first.

It is possible to change the strings that the specifiers produce, or to
add new specifiers, by customising the option
‘ebib-notes-template-specifiers’.  This option contains pairs of
characters and functions.  Each function takes two arguments, ‘key’ and
‘db’, the key of the entry for which a note is created and the database
in which it is stored.  It should return a string (possibly empty),
which replaces the specifier in the template.  In order to change the
string that a specifier is replaced with, write your own function and
set ‘ebib-notes-template-specifiers’ to use it.

When the specifier functions are called, the ‘key’ argument is set to
the key of the current entry and the ‘db’ argument to the current
database.  With these arguments, it is possible to, e.g., retrieve the
value of a specific field in the entry:

(ebib-get-field-value <field> key db 'noerror 'unbraced 'xref 'expand-strings 'org)

where ‘<field>’ is the field as a (case-insensitive) string whose value
is to be retrieved.  The argument ‘'noerror’ is necessary to avoid
triggering an error if ‘field’ does not exist in the entry.  The other
arguments determine how the field value is returned.  See the doc string
of ‘ebib-get-field-value’ for details.

Instead of a function, you may also provide a variable.  The variable's
value is then used to replace the specifier.


File: ebib.info,  Node: Displaying notes,  Next: Using Markdown for notes,  Prev: Customising the notes file format,  Up: Notes files

10.5 Displaying notes
=====================

If an entry has an external note, the first few lines are shown in the
entry buffer as a field called ‘external note’.  The number of lines to
show can be customised with the option ‘ebib-notes-display-max-lines’,
which defaults to 10.  If you prefer, you can also have the entire note
shown, not just the first few lines, by customising the option
‘ebib-notes-show-note-method’.  The note is then shown in a separate
buffer that is displayed when an entry has a note.  This setting is only
really convenient if you use a multiple notes per file, because the
buffer is not closed after displaying the note.  If you use a separate
file for each note, you'll end up with a lot of open buffers.  (Showing
only the first few lines in the entry buffer does not have this
limitation, as it just reads the text of the note from the file, it does
not visit the file in a buffer.)

Note also that displaying the note inline in the entry buffer is only
possible with Org files, so your notes must use Org mode for it to work.
Showing the entire note in a separate buffer can be done with any
format, but only works if you use Ebib's default window layout (see the
section *note Window Management: #window-management. for details),
because that is the only window layout that ensures that the note can be
displayed without getting in the way.


File: ebib.info,  Node: Using Markdown for notes,  Next: Using org-capture to record notes,  Prev: Displaying notes,  Up: Notes files

10.6 Using Markdown for notes
=============================

Because the template can be customised and the major mode is determined
from the file extension, it is in principle possible to use another
format than Org for notes.  In this case, it is easier to use separate
note files, because in a single notes file, Ebib needs to be able to
identify the location of a note.  In Org files, this is fairly
straightforward using a ‘:PROPERTIES:’ block, but there is no similar
ready-made option for other formats.

Provided you use a single file for each note, however, it is possible to
use another format.  To do so, the following options will need to be
customised:

   • ‘ebib-note-file-extension’: set this to the extension you use for
     your notes files, without the dot.  The extension also determines
     the major mode Emacs uses to open note files.

   • ‘ebib-notes-directory’: this needs to be set to the directory
     containing your notes.  Ebib does not support single note files in
     multiple directories, so you need to put all note files in a single
     directory.

   • ‘ebib-notes-name-transform-function’: this can be set to a function
     that creates a name for a note file.  It should return just the
     base name, without the path and without the extension.  If you
     don't customise it, the option ‘ebib-name-transform-function’ will
     be used instead.  If you don't customise that option either, the
     entry key will be used as the file name.

   • ‘ebib-notes-template’: this needs to be customised to match the
     format you are using.  By default, this template creates an Org
     header with a properties block.  Note that if you have one note per
     file, the requirement that the template contain the ‘%K’ specifier
     does not apply, because the note is identified based on the file
     name.

   • ‘ebib-notes-template-specifiers’: create functions for the
     specifiers that you use in ‘ebib-notes-template’ and customise this
     option to use them.  Note that if you use Markdown, the relevant
     functions are already defined.  They are named with ‘markdown’
     instead of ‘org’, so for the ‘%T’ specifier, the Markdown function
     is ‘ebib-create-markdown-title’, etc.

   • ‘ebib-notes-show-note-method’: the default value of this option is
     only compatible with Org files.  If you use a different format, you
     must either unset it, or set it to the value ‘all’.  If you want to
     keep the default value (‘top-lines’), you need to customise
     ‘ebib-notes-extract-text-function’, which would involve writing a
     function that extracts the top N lines of a note.

It should be possible to make Ebib work with multiple notes per file in
a format other than Org, but this has not been tested.  If you wish to
try and make this work, two things are important: First, make sure to
include a unique identifier for each note.  Unique in this case means
not only unique for the entry, but also unique in the notes file,
because Ebib searches for this identifier to locate the note.  For
example, using just the entry key in a Markdown file does not guarantee
uniqueness, because the entry key can be used to insert a citation.
(Ebib includes the function ‘ebib-create-markdown-identifier’, which
creates a unique identifier by prepending ‘ID:’ to the entry key.)

Second, you will probably need to customise the hooks
‘ebib-notes-search-note-before-hook’, ‘ebib-notes-open-note-after-hook’
and ‘ebib-notes-new-note-hook’ discussed above.  They are needed to
ensure that Ebib positions point correctly when creating or editing a
note.


File: ebib.info,  Node: Using org-capture to record notes,  Prev: Using Markdown for notes,  Up: Notes files

10.7 Using ‘org-capture’ to record notes
========================================

Instead of using Ebib's own system to record notes, you can also use
‘org-capture’ to do so.  This has two advantages: first, Org capture
templates allow you to specify the type of the note and the location
where the note is to be stored more precisely than what Ebib's system
allows.  Second, you can define more than one template, so you can
capture different kinds of notes or record them in different files.

Note that ‘org-capture’ is only used for creating new notes, not for
displaying existing notes.  Therefore, you still need to configure Ebib
to look for notes in the right locations.

When using ‘org-capture’, you'll most likely want to set
‘ebib-notes-storage’ to ‘multiple-notes-per-file’.  (Though technically
it would be possible to have a single file for each note, there is
little reason to go through the trouble of setting that up.)  In
addition, you'll need to set ‘ebib-notes-locations’ to the files and/or
directories you use to store notes.  There is no point but also no harm
in setting ‘ebib-notes-default-file’; this setting is ignored when you
create notes through ‘org-capture’ but Ebib still uses it to search for
existing notes.

In order to use ‘org-capture’ for creating notes, you need to set
‘ebib-notes-use-org-capture’ and you need to add an entry to
‘org-capture-templates’ that you can use to create a note.  This entry
can have any key, description, type and target you like, but the
template should be a function.

The following is an example entry for ‘org-capture-templates’:

("e"
 "BibTeX note"
 entry
 (file+headline "~/Work/Bibtex/Bib_Notes.org" "Bibliography Notes")
 (function ebib-notes-create-org-template))

Because you are free to set the type and target to anything that
‘org-capture’ accepts, you have more control over the way a note is
created and where it is stored.

As mentioned, the only part of this entry that should not be changed is
the last line.  This line specifies that the actual template is created
by the function‘ebib-notes-create-org-template’.  This function takes
‘ebib-notes-template’ and converts it into a template that ‘org-capture’
can use.

The ‘%’-directives in ‘ebib-notes-template’ are interpreted by Ebib, not
by the Org capture mechanism.  It is therefore still essential that it
contains a ‘%K’ directive to create an identifier that Ebib can find.

It is possible to add ‘org-capture’ directives to the template, though.
To do this, put an additional ‘%’ before the directive.  For example,
‘org-capture’ can add a time stamp with ‘%t’.  In order to add a time
stamp to a bibliography note, write ‘%%t’:

(setq ebib-notes-template
      "* %T\n:PROPERTIES:\n%K\n:END:\n%%t\n%%?\n")

‘ebib-notes-create-org-template’ strips off one ‘%’ and passes the
result on to ‘org-capture’, which then sees ‘%t’ and replaces it with a
time stamp.  (Note that this is the reason why the cursor position is
indicated with ‘%%?’: ‘ebib-notes-create-org-template’ converts it to
‘%?’, which is used by ‘org-capture’ to position the cursor.)

Note that this ‘org-capture-templates’ entry should only be selected
when creating a note from within Ebib.  The function
‘ebib-notes-create-org-template’ needs some information about the
current entry to function properly and this can only be provided when it
is called from Ebib.  Therefore, you may want to disable the entry
altogether when you call ‘org-capture’ from somewhere else.  You can do
this by configuring the option ‘org-capture-template-contexts’:

(setq org-capture-template-contexts
      '(("e" ((in-mode ebib-index-mode)))))

The ‘"e"’ is the key that you've chosen for your template.  This setting
ensures that the ‘org-capture’ template associated with the key ‘"e"’ is
only shown when ‘org-capture’ is called from a buffer with major mode
‘ebib-index-mode’, which is Ebib's index buffer.

You can also bypass the ‘org-capture’ selection buffer altogether and
open an ‘org-capture’ buffer immediately with the appropriate template.
To do this, set ‘ebib-notes-use-org-capture’ to the key of the template
that you use for Ebib notes (‘"e"’ in the current example):

(setq ebib-notes-use-org-capture "e")

This will cause ‘org-capture’ to bypass the selection buffer and
immediately put you in the edit buffer with the relevant template.

Alternatively, it is also possible to set up more than one ‘org-capture’
entry for Ebib notes.  This can be useful if you want to use different
locations for storing notes or store different types of notes.  If you
do so, you still need to use the same function
‘ebib-notes-create-org-template’ to create the actual template, however.
‘org-capture’ itself does not know about Ebib's databases and cannot
access them.  This is what ‘ebib-notes-create-org-template’ is for.

If you wish to associate each ‘org-capture’ entry with a different
template, you can do so by setting ‘ebib-notes-template’ to a list.
Each element of the list should itself be a list of two items, the key
of the relevant template in ‘org-capture-templates’ and the template to
use.

Note that Ebib only searches for a single note for each entry, so if you
create more than one, Ebib only displays and opens the first one it
finds.  More than one note for an entry can still be useful, though, for
example as a reading list or to export entries to some Org-based format.
(You can customise ‘ebib-notes-template-specifiers’ and add new
‘%’-forms, as discussed above.)

Note that Ebib also provides an Ebib-friendly command to call
‘org-capture’ directly.  This command, ‘ebib-org-capture’ (not bound to
any key by default), takes the same arguments as ‘org-capture’ and can
be used in the same way.  It makes sure that
‘ebib-notes-create-org-template’ can find the current entry and then
calls ‘org-capture’.


File: ebib.info,  Node: Managing a reading list,  Next: Managing Keywords,  Prev: Notes files,  Up: Top

11 Managing a reading list
**************************

Ebib offers the ability to manage a reading list as an Org file.  In
order to make use of this functionality, you must set the option
‘ebib-reading-list-file’ to a file in which the reading list is stored.
Once you've specified a file, you can add the current entry to the
reading list with ‘R a’.  The mode line of the entry buffer will show
‘[R]’ to indicate that the current entry is on the reading list.

A reading list is simply an Org file with one entry (i.e., heading) per
item.  Each entry is marked with ‘TODO’, so that the items can be
included in the Org agenda.  If you prefer to use another todo state,
you can customise the option ‘ebib-reading-list-todo-marker’.  You can
mark an entry as done from within Ebib with the key ‘R d’.  This will
change the todo state of the item to ‘DONE’ (customisable through the
option ‘ebib-reading-list-done-marker’).  With ‘R v’ you can view the
reading list.

The format of a reading list item can be customised in much the same way
that notes are.  The default template for reading list items is provided
by the option ‘ebib-reading-list-template’, and the specifiers that can
be used in this template are in ‘ebib-reading-list-template-specifiers’.
Most of the specifiers are the same as for the notes template, with the
exception of ‘%K’.  For the reading list, this specifier uses a
different function, which adds a prefix ‘reading_’ to the key.  In this
way, the custom ID of a reading list item and a note will not interfere.
Furthermore, the reading list template accepts a specifier ‘%M’, which
is replaced with the todo marker specified in the option
‘ebib-reading-list-todo-marker’ (by default ‘TODO’).

Most aspects of the reading list can be customised.  First, the option
‘ebib-reading-list-add-item-function’ holds a function that places point
where the new item should be inserted.  By default, it puts point at the
end of the buffer.  Second, ‘ebib-reading-list-remove-item-function’
holds the function that marks a reading list item as done.  By default,
it is set to ‘ebib-reading-list-mark-item-as-done’, which simply changes
the todo state of the item to ‘DONE’, but you can set it to a function
that does something else (for example, completely removing the entry
from the list).

The option ‘ebib-reading-list-item-active-function’ holds a function
that should return ‘t’ if the current entry is on the reading list and
is still active.  The default function simply checks if the entry's todo
state is equal to ‘ebib-reading-list-todo-marker’.

Lastly, there are two hooks, ‘ebib-reading-list-new-item-hook’ and
‘ebib-reading-list-remove-item-hook’.  The former is run immediately
after a new reading list item is inserted in the reading list file (but
before saving it), the latter immediately after calling the function in
‘ebib-reading-list-remove-item-function’ (also before saving the
buffer).  By default, these hooks are empty.


File: ebib.info,  Node: Managing Keywords,  Next: Window Management,  Prev: Managing a reading list,  Up: Top

12 Managing Keywords
********************

Biblatex supports a ‘keywords’ field, which can contain a
(comma-separated) list of keywords for an entry.  BibTeX does not
support this field directly, but Ebib includes a ‘keywords’ field in the
extra fields for BibTeX entries.  Ebib offers some special facilities
for editing this field.

Ebib keeps a list of keywords used in your database(s) and offers these
for completion when you edit the ‘keywords’ field.  You can enter a
keyword and accept it with ‘RET’, after which you will be asked for the
next keyword.  Just hitting ‘RET’ without any input finishes the edit
and returns focus to the entry buffer.  (With selectrum, ivy or helm the
key binding to finish editing the ‘keywords’ field is different; the
prompt will indicate what key to press).  You can, of course, also enter
a keyword that is not on the completion list.  If you do, it will be
added to the list.

If you need to edit a keyword or remove one from the list, you need to
edit the ‘keywords’ field directly.  To do this, use a prefix argument:
‘C-u RET’ instead of just ‘RET’ to edit the field.  Note, though, that
this does not update the completion list.

The keywords completion list is composed of the keywords in all the
‘.bib’ files you have open and is available in every database.  If you
open another ‘.bib’ file, its keywords are added to the completion list.
(Note that if you close a database, its keywords are not removed from
the completion list, since Ebib does not keep track of which keywords
are used in which database.)

* Menu:

* Using a Canonical Keywords List::


File: ebib.info,  Node: Using a Canonical Keywords List,  Up: Managing Keywords

12.1 Using a Canonical Keywords List
====================================

By default, the completion list does not contain keywords that are not
used in any of your ‘.bib’ files.  If you wish to use a set of canonical
keywords that are always offered for completion, regardless of whether
they are used in a currently opened ‘.bib’ file or not, you can set the
option "Keywords" (‘ebib-keywords’).  This can be a list of keywords or
the name of a file containing the keywords.  If it is a file name, the
file should be a simple text file with one keyword per line.

If you set this option, keywords in a database that are not in the
canonical list are displayed in Ebib's warning face
(‘ebib-warning-face’).  You can add them to the canonical list with the
key sequence ‘K s’, which will ask you for the keyword to add, or with
‘K c’, which adds all keywords of the current entry to the canonical
list.  You can also remove all keywords from the ‘keywords’ field that
are not in the list of canonical keywords with the key sequence ‘K p’.

Even if you use a list of canonical keywords, you can still enter
keywords that are not in the list when you edit the ‘keywords’ field.
If you do so, the new keywords are added to the list automatically.  If
you do not wish this to happen, unset the option "Keywords Add New To
Canonical".

If new keywords were added to the list of canonical keywords, you will
be asked if you wish to save the list when you quit Ebib.  If you always
want this to happen without asking for confirmation, set the option
"Keywords Save On Exit" to ‘always’.  Note that you can also save the
list manually with the key sequence ‘K S’ (capital ‘K’, capital ‘S’).

If you haven't configured a list of canonical keywords, the key sequence
‘K S’ creates one from the keywords used in your open ‘.bib’ files.  The
list is then saved to your customisation file (usually
‘~/.emacs.d/init.el’).  If you prefer to keep your keywords in a
separate file, you need to create the file yourself (as mentioned, one
keyword per line; keywords may of course contain spaces), and configure
the option "Keywords" (‘ebib-keywords’) yourself.


File: ebib.info,  Node: Window Management,  Next: Copying Entries to the Kill Ring,  Prev: Managing Keywords,  Up: Top

13 Window Management
********************

By default, Ebib takes over the entire Emacs frame it is started in,
displaying the index window at the top and the entry window below it.
There are a few options to change this behaviour, however.  They are all
part of the customisation group ‘ebib-windows’, and allow you to specify
two alternative ways to deal with Ebib windows.  The main layout option
is simply called "Layout" and has four options: use the full frame (the
default), use the current window, use the right part of the frame, or
display only the index window.

If you set the layout to use only the right part of the frame, the Ebib
buffers are displayed on the right of the frame, with the (usually
larger) left part of the frame displaying some other buffer, normally
the buffer from which you called Ebib.  The width of the Ebib windows
can be set with the option "Width", which defaults to 80, and which can
be specified as an absolute value (the number of columns), but also as a
value relative to the current window.  In that case, you must specify a
value between 0 and 1.  Note that when this option is used, the key ‘z’
does not hide the Ebib buffers, it simply switches to a non-Ebib window
in the same frame.  You can use (uppercase) ‘Z’ to hide the Ebib
buffers.  Furthermore, with this option, the multiline edit buffer is
not displayed in the same window as the entry buffer.  Rather, Ebib uses
another, non-Ebib window to display it.

The fourth option that Ebib provides is to only show the index buffer on
start-up.  In this case, Ebib does not display the entry buffer when it
is started.  Instead, only the index buffer is displayed, which can be
navigated in the usual manner.  The entry buffer is only displayed when
you add or edit an entry.  When you've finished editing and move back to
the index buffer, the entry buffer is hidden again.

The entry buffer is also displayed if you press ‘RET’.  When you do
this, the index buffer remains selected, so you can use this to display
the fields of an entry without moving focus to the entry window.  If you
navigate the index buffer, the entry buffer remains visible, updating
its contents as you move around.

In this case, too, the key ‘z’ does not hide the index window.  Rather,
it just selects another, non-Ebib window.  In order to hide the index
window, you can use (uppercase) ‘Z’.

If you set Ebib's layout to display only the index buffer on startup,
you can additionally set the option "Popup Entry Window".  Normally,
Ebib will reuse an existing window to display the entry buffer (and
restore its original buffer when you leave the entry buffer).  With this
option set, however, Ebib uses the Emacs function
‘display-buffer-popup-window’ to create a new window (which is destroyed
again when you leave the entry buffer).

Further relevant options are "Window Vertical Split", which displays the
index buffer to the left of the frame rather than at the top, and "Index
Window Size", which determines the size of the index window (either its
height or its width, depending on whether the index window is displayed
at the top or on the left of the frame.)


File: ebib.info,  Node: Copying Entries to the Kill Ring,  Next: Printing the Database,  Prev: Window Management,  Up: Top

14 Copying Entries to the Kill Ring
***********************************

Ebib offers several ways to copy an entry to the kill ring (and the
system clipboard), which you can then insert into another buffer or
another application.  You can copy the entry key (‘C k’; note that this
is capital ‘C’ followed by ‘k’, _not_ ‘C-k’!)  the entire BibTeX entry
(‘C e’), a full reference as would appear in a list of references (‘C
r’) or a citation, by default of the Author-Year type (‘C c’).

The functions that copy a reference or citation make use of templates
that specify how such a reference/citation should be formatted.  These
templates can be customised: the relevant options are
‘ebib-reference-templates’ and ‘ebib-citation-template’.  (The latter
should not be confused with ‘ebib-citation-commands’, which defines
templates for inserting citation commands into a LaTeX / Markdown / etc.
buffer.)

These templates are strings that contain directives for inserting
specific fields from the entry being copied.  As an example, a simple
template for an author-year citation would be the following:

"{Author} ({Year})"

The directives are marked by braces {} around a field name.  In the
resulting citation, they are replaced by the contents of the fields.
(The field names are case-insensitive, they could also be written as
‘"{author} ({year})."’)

Alternative fields can be separated by a pipe bar ‘|’:

"{Author|Editor} ({Date|Year})"

This template uses the ‘Author’ field unless it's empty, in which case
the ‘Editor’ field is used.  Similarly for the year: first the contents
of the ‘Date’ field is checked.  The ‘Year’ field is used if the ‘Date’
field is empty.

If none of the fields in a directive has any contents, the directive is
discarded completely.  Most reference templates for example include a
directive for the ‘Doi’ or ‘Url’ field:

"{Author|Editor} ({Date|Year}). {\"Title\"}. {Publisher}. {Doi|Url.}"

If the ‘Doi’ and ‘Url’ fields are both empty, the directive is simply
ignored.

A directive may contain punctuation before or after the field name (or
sequence of field names), which is dropped if the field is empty.  The
‘{Doi|Url.}’ directive in the previous example contains a full stop,
which is only included in the reference if the ‘Doi’ or ‘Url’ field is
present.

The contents of the fields is used literally, with two exceptions: the
‘Date’ field may contain a full date+time specification or even a date
range, but only the year (or the year of the first date in a date range)
is used.  Similarly, the ‘Title’ field is stripped of LaTeX markup.
(See the user option ‘ebib-TeX-markup-replace-alist’ if you want to
customise what exactly is stripped.)


File: ebib.info,  Node: Printing the Database,  Next: Customisation,  Prev: Copying Entries to the Kill Ring,  Up: Top

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

If you print your entries as a bibliography, Ebib creates a simple LaTeX
document that essentially contains a ‘\nocite{*}’ command followed by a
‘\printbibliography’ command, adding a ‘\addbibresource’ command
referring to the current database.  You can then run the usual sequence
of LaTeX, Biber, LaTeX, LaTeX on this file, creating a document
containing a list of all the references in your database.  (Obviously,
BibTeX is also supported.)

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

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

By default, the index cards only show single-line field values.  That
is, multiline values are normally excluded.  If you want to include
multiline values in the print-out, you have to set the option ‘Print
Multiline’ in the Options menu or in Ebib's customisation buffer.  With
this option set, Ebib includes all multiline values in the LaTeX file
that it creates.  Note however that Ebib does not change anything about
the formatting of the text in a multiline value.  So if you plan to make
(heavy) use of this option, make sure that the way you type your text
conforms to LaTeX's conventions (e.g. empty lines to mark paragraphs,
etc.)  and doesn't contain any characters such as ‘&’ that are illegal
in LaTeX. (Or, alternatively, use LaTeX code in your multiline fields.)

As mentioned, when you "print" the database, Ebib really just creates a
LaTeX file.  More precisely, it creates a temporary buffer and writes
the LaTeX code into it, and then saves the contents of that buffer to a
file.  After it has done that, Ebib lowers itself and instruct Emacs to
open the file in a buffer, which will then be properly set up as a LaTeX
buffer.  From there you can run LaTeX and view the result.

Before doing all this, Ebib asks you which file to write to.  Be careful
with this: since this is supposed to be a temporary file, Ebib simply
assumes that if you provide a filename of an existing file, it can
overwrite that file without warning!

A better way to tell Ebib which file to use is to set the option "Print
Tempfile" in Ebib's customisation buffer to some temporary file.  When
this option is set, Ebib will always use this file to write to, and will
not ask you for a filename anymore.

Note that both print options operate on all entries of the database or
on the selected entries.

The option "Print Preamble" and "LaTeX Preamble" allow you to customise
the preamble of the LaTeX file that is created.


File: ebib.info,  Node: Customisation,  Prev: Printing the Database,  Up: Top

16 Customisation
****************

Ebib can be customised through Emacs' standard customisation interface.
The relevant customisation group is (obviously) called ‘ebib’, which has
five subgroups: ‘ebib-faces’, ‘ebib-filters’, ‘ebib-notes’, and
‘ebib-keywords’, whose functions should be obvious, and ‘ebib-windows’,
where options for Ebib's window management can be set.  All options are
documented in the customisation buffers.  You can go to Ebib's
customisation buffer with ‘M-x customize-group RET ebib RET’, or by
using the menu «Ebib | Options | Customize Ebib».

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

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

You can also set Ebib options in a ‘.dir-locals.el’ file.  Note,
however, that these only take effect if you start Ebib from the relevant
directory.  If you put Ebib in the background and return to it with ‘M-x
ebib’, a ‘.dir-locals.el’ is not taken into account.

* Menu:

* Modifying Key Bindings::


File: ebib.info,  Node: Modifying Key Bindings,  Up: Customisation

16.1 Modifying Key Bindings
===========================

If you would like to change Ebib's standard key bindings, or if you
would like to bind a command that is only available through the menu to
a key, you can do so by adding the relevant key bindings to Emacs init
file.  The relevant key maps are ‘ebib-index-mode-map’,
‘ebib-entry-mode-map’, ‘ebib-strings-mode-map’ for the index, entry, and
strings buffer, and ‘ebib-multiline-mode-map’, which contains the key
bindings in multiline edit buffers.

In addition, ‘ebib-search-map’ is a transient key map that is activated
when ‘ebib-search’ is called, and ‘ebib-filters-map’,
‘ebib-keywords-map’ and ‘ebib-reading-list-map’ are key maps (set up
using ‘define-prefix-command’) that contain bindings for filters,
keywords and the reading list, respectively.  Finally, there is
‘ebib-log-mode-map’ which is active in Ebib's log buffer.



Tag Table:
Node: Top188
Node: Installation1092
Ref: #installation1209
Node: Package manager1290
Ref: #package-manager1421
Node: Manual installation1601
Ref: #manual-installation1753
Node: News2030
Ref: #news2150
Node: Starting Ebib2261
Ref: #starting-ebib2371
Node: Getting Started2970
Ref: #getting-started3110
Node: Opening a bib File4623
Ref: #opening-a-bib-file4777
Node: Preloading bib Files6564
Ref: #preloading-bib-files6754
Node: Starting a New bib File7398
Ref: #starting-a-new-bib-file7594
Node: Closing a database7836
Ref: #closing-a-database8009
Node: The Database View8248
Ref: #the-database-view8419
Node: Navigating the Database10421
Ref: #navigating-the-database10625
Node: Displaying and Sorting the Entries List12861
Ref: #displaying-and-sorting-the-entries-list13098
Node: Biblatex vs BibTeX17855
Ref: #biblatex-vs-bibtex18020
Node: Setting the BibTeX Dialect18856
Ref: #setting-the-bibtex-dialect19033
Node: Alias Types and Fields21052
Ref: #alias-types-and-fields21221
Node: Editing the Database23278
Ref: #editing-the-database23444
Node: Adding and Deleting Entries24069
Ref: #adding-and-deleting-entries24240
Node: Marking Entries25937
Ref: #marking-entries26113
Node: Editing Field Values26613
Ref: #editing-field-values26809
Node: @String abbreviations in field values30020
Ref: #string-abbreviations-in-field-values30267
Node: Editing Multiline Values32869
Ref: #editing-multiline-values33097
Node: Copy Cut Kill Paste Yank and Delete35000
Ref: #copy-cut-kill-paste-yank-and-delete35243
Node: Undefined Fields36214
Ref: #undefined-fields36407
Node: Hiding Fields from Display37296
Ref: #hiding-fields-from-display37484
Node: Timestamps39041
Ref: #timestamps39198
Node: Saving a Database41105
Ref: #saving-a-database41269
Node: Exporting Entries42831
Ref: #exporting-entries42951
Node: Cross-referencing44323
Ref: #cross-referencing44497
Node: Sorting the bib File46925
Ref: #sorting-the-bib-file47118
Node: @Preamble Definition49366
Ref: #preamble-definition49551
Node: @String Definitions51514
Ref: #string-definitions51686
Node: @Comments54036
Ref: #comments54188
Node: Creating Entry Stubs54679
Ref: #creating-entry-stubs54856
Node: Multiline Edit Buffers55584
Ref: #multiline-edit-buffers55747
Node: Main and Dependent Databases60058
Ref: #main-and-dependent-databases60263
Node: Inserting Citations into a Text Buffer63149
Ref: #inserting-citations-into-a-text-buffer63363
Node: Single Citations63560
Ref: #single-citations63729
Node: Citations with multiple keys66094
Ref: #citations-with-multiple-keys66308
Node: Key Bindings68067
Ref: #key-bindings68259
Node: Defining Citation Commands69015
Ref: #defining-citation-commands69248
Node: Associating a Database with a Text Buffer75134
Ref: #associating-a-database-with-a-text-buffer75419
Node: Links and Citations in Org buffers76794
Ref: #links-and-citations-in-org-buffers77030
Node: Searching78459
Ref: #searching78594
Node: Filters82042
Ref: #filters82159
Node: Simple Selection83214
Ref: #simple-selection83339
Node: Complex Filters85042
Ref: #complex-filters85200
Node: Storing and Saving Filters89838
Ref: #storing-and-saving-filters90017
Node: Special Filters92868
Ref: #special-filters93045
Node: An Example Listing Recent Additions94428
Ref: #an-example-listing-recent-additions94653
Node: Properties of Filtered Databases97017
Ref: #properties-of-filtered-databases97210
Node: Importing BibTeX entries98857
Ref: #importing-bibtex-entries99028
Node: Merging bib files99342
Ref: #merging-bib-files99513
Node: Importing entries from a buffer100102
Ref: #importing-entries-from-a-buffer100335
Node: Integration with the Biblio package101364
Ref: #integration-with-the-biblio-package101613
Node: Multiple Identical Fields103398
Ref: #multiple-identical-fields103587
Node: Linking to external resources105501
Ref: #linking-to-external-resources105686
Node: Viewing and Importing Files105888
Ref: #viewing-and-importing-files106088
Node: Editing the file field111615
Ref: #editing-the-file-field111766
Node: Calling a Browser for URLs and DOIs113119
Ref: #calling-a-browser-for-urls-and-dois113335
Node: Notes files115750
Ref: #notes-files115900
Node: Configuring files for storing notes117475
Ref: #configuring-files-for-storing-notes117653
Node: Hooks120623
Ref: #hooks120786
Node: Upgrading from earlier Ebib versions122183
Ref: #upgrading-from-earlier-ebib-versions122406
Node: Customising the notes file format123316
Ref: #customising-the-notes-file-format123544
Node: Displaying notes127323
Ref: #displaying-notes127505
Node: Using Markdown for notes128850
Ref: #using-markdown-for-notes129048
Node: Using org-capture to record notes132706
Ref: #using-org-capture-to-record-notes132905
Node: Managing a reading list138901
Ref: #managing-a-reading-list139063
Node: Managing Keywords142078
Ref: #managing-keywords142234
Node: Using a Canonical Keywords List143841
Ref: #using-a-canonical-keywords-list143999
Node: Window Management146137
Ref: #window-management146302
Node: Copying Entries to the Kill Ring149437
Ref: #copying-entries-to-the-kill-ring149636
Node: Printing the Database152359
Ref: #printing-the-database152532
Node: Customisation155975
Ref: #customisation156091
Node: Modifying Key Bindings157582
Ref: #modifying-key-bindings157709

End Tag Table


Local Variables:
coding: utf-8
End: