File: ebib-manual.html

package info (click to toggle)
ebib 2.51.1-2
links: PTS, VCS
area: main
in suites: forky, sid
size: 2,460 kB
sloc: lisp: 8,839; sh: 80; makefile: 30
file content (3183 lines) | stat: -rw-r--r-- 189,152 bytes
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <meta name="author" content="Joost Kremers" />
  <title>Ebib Manual</title>
  <style>
    code{white-space: pre-wrap;}
    span.smallcaps{font-variant: small-caps;}
    div.columns{display: flex; gap: min(4vw, 1.5em);}
    div.column{flex: auto; overflow-x: auto;}
    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
    /* The extra [class] is a hack that increases specificity enough to
       override a similar rule in reveal.js */
    ul.task-list[class]{list-style: none;}
    ul.task-list li input[type="checkbox"] {
      font-size: inherit;
      width: 0.8em;
      margin: 0 0.8em 0.2em -1.6em;
      vertical-align: middle;
    }
    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
    /* CSS for syntax highlighting */
    html { -webkit-text-size-adjust: 100%; }
    pre > code.sourceCode { white-space: pre; position: relative; }
    pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
    pre > code.sourceCode > span:empty { height: 1.2em; }
    .sourceCode { overflow: visible; }
    code.sourceCode > span { color: inherit; text-decoration: inherit; }
    div.sourceCode { margin: 1em 0; }
    pre.sourceCode { margin: 0; }
    @media screen {
    div.sourceCode { overflow: auto; }
    }
    @media print {
    pre > code.sourceCode { white-space: pre-wrap; }
    pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
    }
    pre.numberSource code
      { counter-reset: source-line 0; }
    pre.numberSource code > span
      { position: relative; left: -4em; counter-increment: source-line; }
    pre.numberSource code > span > a:first-child::before
      { content: counter(source-line);
        position: relative; left: -1em; text-align: right; vertical-align: baseline;
        border: none; display: inline-block;
        -webkit-touch-callout: none; -webkit-user-select: none;
        -khtml-user-select: none; -moz-user-select: none;
        -ms-user-select: none; user-select: none;
        padding: 0 4px; width: 4em;
        color: #aaaaaa;
      }
    pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa;  padding-left: 4px; }
    div.sourceCode
      {   }
    @media screen {
    pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
    }
    code span.al { color: #ff0000; font-weight: bold; } /* Alert */
    code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
    code span.at { color: #7d9029; } /* Attribute */
    code span.bn { color: #40a070; } /* BaseN */
    code span.bu { color: #008000; } /* BuiltIn */
    code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
    code span.ch { color: #4070a0; } /* Char */
    code span.cn { color: #880000; } /* Constant */
    code span.co { color: #60a0b0; font-style: italic; } /* Comment */
    code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
    code span.do { color: #ba2121; font-style: italic; } /* Documentation */
    code span.dt { color: #902000; } /* DataType */
    code span.dv { color: #40a070; } /* DecVal */
    code span.er { color: #ff0000; font-weight: bold; } /* Error */
    code span.ex { } /* Extension */
    code span.fl { color: #40a070; } /* Float */
    code span.fu { color: #06287e; } /* Function */
    code span.im { color: #008000; font-weight: bold; } /* Import */
    code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
    code span.kw { color: #007020; font-weight: bold; } /* Keyword */
    code span.op { color: #666666; } /* Operator */
    code span.ot { color: #007020; } /* Other */
    code span.pp { color: #bc7a00; } /* Preprocessor */
    code span.sc { color: #4070a0; } /* SpecialChar */
    code span.ss { color: #bb6688; } /* SpecialString */
    code span.st { color: #4070a0; } /* String */
    code span.va { color: #19177c; } /* Variable */
    code span.vs { color: #4070a0; } /* VerbatimString */
    code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
  </style>
  <link rel="stylesheet" href="styles/manual.css" />
  <!-- Favicon -->
  <link href="favicon.ico" rel="icon" type='image/x-icon'/>

  <!-- Google Fonts -->
  <link rel="preconnect" href="https://fonts.gstatic.com">
  <link href="https://fonts.googleapis.com/css2?family=Merriweather+Sans&family=Roboto+Slab&display=swap" rel="stylesheet">
</head>
<body>
<header id="title-block-header">
<h1 class="title">Ebib Manual</h1>
<p class="author">Joost Kremers</p>
</header>
<nav id="TOC" role="doc-toc">
<ul>
<li><a href="#installation" id="toc-installation">Installation</a></li>
<li><a href="#getting-started" id="toc-getting-started">Getting
Started</a>
<ul>
<li><a href="#opening-a-.bib-file" id="toc-opening-a-.bib-file">Opening
a <code>.bib</code> File</a></li>
<li><a href="#preloading-.bib-files"
id="toc-preloading-.bib-files">Preloading <code>.bib</code>
Files</a></li>
<li><a href="#starting-a-new-.bib-file"
id="toc-starting-a-new-.bib-file">Starting a New <code>.bib</code>
File</a></li>
<li><a href="#closing-a-database" id="toc-closing-a-database">Closing a
database</a></li>
<li><a href="#the-database-view" id="toc-the-database-view">The Database
View</a></li>
<li><a href="#navigating-the-database"
id="toc-navigating-the-database">Navigating the Database</a></li>
<li><a href="#displaying-and-sorting-the-entries-list"
id="toc-displaying-and-sorting-the-entries-list">Displaying and Sorting
the Entries List</a></li>
<li><a href="#biblatex-vs.-bibtex" id="toc-biblatex-vs.-bibtex">Biblatex
vs. BibTeX</a></li>
</ul></li>
<li><a href="#editing-the-database"
id="toc-editing-the-database">Editing the Database</a>
<ul>
<li><a href="#adding-and-deleting-entries"
id="toc-adding-and-deleting-entries">Adding and Deleting
Entries</a></li>
<li><a href="#marking-entries" id="toc-marking-entries">Marking
Entries</a></li>
<li><a href="#editing-field-values"
id="toc-editing-field-values">Editing Field Values</a></li>
<li><a href="#string-abbreviations-in-field-values"
id="toc-string-abbreviations-in-field-values"><code>@String</code>
abbreviations in field values</a></li>
<li><a href="#editing-multiline-values"
id="toc-editing-multiline-values">Editing Multiline Values</a></li>
<li><a href="#copy-cut-kill-paste-yank-and-delete"
id="toc-copy-cut-kill-paste-yank-and-delete">Copy, Cut (Kill), Paste
(Yank), and Delete</a></li>
<li><a href="#undefined-fields" id="toc-undefined-fields">Undefined
Fields</a></li>
<li><a href="#hiding-fields-from-display"
id="toc-hiding-fields-from-display">Hiding Fields from Display</a></li>
<li><a href="#timestamps" id="toc-timestamps">Timestamps</a></li>
<li><a href="#saving-a-database" id="toc-saving-a-database">Saving a
Database</a></li>
<li><a href="#cross-referencing"
id="toc-cross-referencing">Cross-referencing</a></li>
<li><a href="#sorting-the-.bib-file"
id="toc-sorting-the-.bib-file">Sorting the <code>.bib</code>
File</a></li>
<li><a href="#preamble-definition" id="toc-preamble-definition"><span
class="citation" data-cites="Preamble">@Preamble</span>
Definition</a></li>
<li><a href="#string-definitions" id="toc-string-definitions"><span
class="citation" data-cites="String">@String</span> Definitions</a></li>
<li><a href="#comments" id="toc-comments"><span class="citation"
data-cites="Comments">@Comments</span></a></li>
<li><a href="#creating-entry-stubs"
id="toc-creating-entry-stubs">Creating Entry Stubs</a></li>
<li><a href="#multiline-edit-buffers"
id="toc-multiline-edit-buffers">Multiline Edit Buffers</a></li>
</ul></li>
<li><a href="#main-and-dependent-databases"
id="toc-main-and-dependent-databases">Main and Dependent
Databases</a></li>
<li><a href="#inserting-citations-into-a-text-buffer"
id="toc-inserting-citations-into-a-text-buffer">Inserting Citations into
a Text Buffer</a>
<ul>
<li><a href="#single-citations" id="toc-single-citations">Single
Citations</a></li>
<li><a href="#citations-with-multiple-keys"
id="toc-citations-with-multiple-keys">Citations with multiple
keys</a></li>
<li><a href="#key-bindings" id="toc-key-bindings">Key Bindings</a></li>
<li><a href="#defining-citation-commands"
id="toc-defining-citation-commands">Defining Citation Commands</a></li>
<li><a href="#associating-a-database-with-a-text-buffer"
id="toc-associating-a-database-with-a-text-buffer">Associating a
Database with a Text Buffer</a></li>
<li><a href="#links-and-citations-in-org-buffers"
id="toc-links-and-citations-in-org-buffers">Links and Citations in Org
buffers</a></li>
</ul></li>
<li><a href="#searching" id="toc-searching">Searching</a></li>
<li><a href="#filters" id="toc-filters">Filters</a></li>
<li><a href="#importing-bibtex-entries"
id="toc-importing-bibtex-entries">Importing BibTeX entries</a>
<ul>
<li><a href="#merging-.bib-files" id="toc-merging-.bib-files">Merging
<code>.bib</code> files</a></li>
<li><a href="#importing-entries-from-a-buffer"
id="toc-importing-entries-from-a-buffer">Importing entries from a
buffer</a></li>
<li><a href="#integration-with-the-biblio-package"
id="toc-integration-with-the-biblio-package">Integration with the Biblio
package</a></li>
<li><a href="#multiple-identical-fields"
id="toc-multiple-identical-fields">Multiple Identical Fields</a></li>
</ul></li>
<li><a href="#linking-to-external-resources"
id="toc-linking-to-external-resources">Linking to external resources</a>
<ul>
<li><a href="#viewing-and-importing-files"
id="toc-viewing-and-importing-files">Viewing and Importing
Files</a></li>
<li><a href="#calling-a-browser-for-urls-and-dois"
id="toc-calling-a-browser-for-urls-and-dois">Calling a Browser for URLs
and DOIs</a></li>
</ul></li>
<li><a href="#notes-files" id="toc-notes-files">Notes files</a></li>
<li><a href="#managing-a-reading-list"
id="toc-managing-a-reading-list">Managing a reading list</a></li>
<li><a href="#managing-keywords" id="toc-managing-keywords">Managing
Keywords</a></li>
<li><a href="#window-management" id="toc-window-management">Window
Management</a></li>
<li><a href="#copying-entries-to-the-kill-ring"
id="toc-copying-entries-to-the-kill-ring">Copying Entries to the Kill
Ring</a></li>
<li><a href="#printing-the-database"
id="toc-printing-the-database">Printing the Database</a></li>
<li><a href="#customisation"
id="toc-customisation">Customisation</a></li>
</ul>
</nav>
<p>Ebib is a program with which you can manage <code>biblatex</code> and
BibTeX database files without having to edit the raw <code>.bib</code>
files. It runs in GNU/Emacs, version 26.1 or higher.</p>
<p>It should be noted that Ebib is <em>not</em> a minor or major mode
for editing <code>.bib</code> 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.</p>
<h1 id="installation">Installation</h1>
<h2 class="unlisted unnumbered" id="package-manager">Package
manager</h2>
<p>The easiest way to install Ebib is to get it from the <a
href="http://melpa.org/">Melpa package archive</a>. This also installs
the Info file so you can access the Ebib manual within Emacs.</p>
<h2 class="unlisted unnumbered" id="manual-installation">Manual
installation</h2>
<p>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 <a
href="https://github.com/joostkremers/parsebib">parsebib</a> package,
which Ebib depends on.</p>
<h2 class="unlisted unnumbered" id="news">News</h2>
<p>New features and (possibly breaking) changes to existing features are
announced in the <a href="NEWS.html">NEWS</a> file.</p>
<h2 class="unlisted unnumbered" id="starting-ebib">Starting Ebib</h2>
<p>Once installed, Ebib can be started with <span
class="key"><code>M-x ebib</code></span>. 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., <span
class="key"><code>C-c e</code></span>, put something like the following
in Emacs’ init file:</p>
<pre><code>(global-set-key (kbd &quot;C-c e&quot;) &#39;ebib)</code></pre>
<p>Or, with <code>use-package</code>:</p>
<pre><code>(use-package ebib
  :bind (&quot;C-c e&quot; . ebib))</code></pre>
<p>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
<code>references.bib</code> exists in <code>~/Work/Papers/</code>, the
following command:</p>
<pre><code>~/Work/Papers $ ebib references.bib</code></pre>
<p>starts Ebib and loads the file <code>references.bib</code>.</p>
<h1 id="getting-started">Getting Started</h1>
<p>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.</p>
<p>When Ebib is started (with <span
class="key"><code>M-x ebib</code></span>), 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 <em>index buffer</em>, while the
lower window shows the <em>entry buffer</em>. 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.</p>
<p>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.</p>
<p>To quit Ebib and unload all <code>.bib</code> files, press <span
class="key"><code>q</code></span>. Alternatively, press <span
class="key"><code>z</code></span> to put Ebib in the background but keep
it active. This way, the <code>.bib</code> files that you have opened
remain loaded, and you can return to them by typing <span
class="key"><code>M-x ebib</code></span> again.</p>
<h2 id="opening-a-.bib-file">Opening a <code>.bib</code> File</h2>
<p>To open a <code>.bib</code> file, press <span
class="key"><code>o</code></span>. Ebib reads the file that you specify
and reports how many entries it found, how many <code>@String</code>
definitions it found, and whether a <code>@Preamble</code> was found. If
Ebib encounters entry types in the <code>.bib</code> file that it does
not know, a warning will be logged to a special buffer
<code>*Ebib-log*</code>. 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 <code>.bib</code> 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.</p>
<p>In order to parse <code>.bib</code> files, Ebib uses the entry type
definitions of <code>bibtex.el</code>, which is fairly complete, but if
you use non-standard entry types, you may need to customise
<code>bibtex-biblatex-entry-alist</code> or
<code>bibtex-bibtex-entry-alist</code>, depending on which of the two
you use. If Ebib finds entry types in a <code>.bib</code> file that are
not defined, those entries will still be loaded, but their entry type is
displayed using Emacs’ <code>error</code> face. The most likely case in
which this may happen is when you load a file that is
<code>biblatex</code>-specific, since by default, Ebib assumes that a
<code>.bib</code> file it loads is a BibTeX file. If you intend to use
<code>biblatex</code> files, make sure to read the section <a
href="#biblatex-vs-bibtex"><code>Biblatex</code> vs. Bibtex</a>.</p>
<p>When you open a <code>.bib</code> 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 <code>ebib-default-directory</code>.</p>
<h2 id="preloading-.bib-files">Preloading <code>.bib</code> Files</h2>
<p>Chances are that you will be doing most of your work with one or a
few <code>.bib</code> files. In order to open these files automatically
when Ebib is started, set the option
<code>ebib-preload-bib-files</code>. 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
<code>ebib-bib-search-dirs</code>.</p>
<p>It is also possible to set this variable as a file-local or
directory-local variable (i.e., in a <code>~.dir-locals.el</code> file).
You can use this method to only load the <code>.bib</code> file or files
associated with a specific project.</p>
<h2 id="starting-a-new-.bib-file">Starting a New <code>.bib</code>
File</h2>
<p>To start a new <code>.bib</code> file from scratch, you first need to
give the database a name. So, to start a new database, press <span
class="key"><code>o</code></span> first, and give the new file a name.
Once you have done this, you can start adding entries to the
database.</p>
<h2 id="closing-a-database">Closing a database</h2>
<p>If you are done with a database, press <span
class="key"><code>c</code></span> 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.</p>
<h2 id="the-database-view">The Database View</h2>
<p>Once you’ve opened a <code>.bib</code> 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. <code>Book</code>, <code>Article</code>, etc.)</p>
<p>Below the type field, Ebib displays (up to) four sets of fields. The
first set are the so-called required fields, the fields that
<code>biblatex</code> / 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 <code>bibtex</code>.</p>
<p>The third group comprises the so-called extra fields. These fields
are usually ignored by <code>biblatex</code> / BibTeX (note that
<code>biblatex</code> and BibTeX normally ignore <em>all</em> 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:</p>
<ul>
<li><code>abstract</code></li>
<li><code>annote</code> (<code>annotation</code> in
<code>biblatex</code>)</li>
<li><code>crossref</code></li>
<li><code>doi</code> (BibTeX only)</li>
<li><code>file</code></li>
<li><code>keywords</code></li>
<li><code>timestamp</code></li>
<li><code>url</code> (BibTeX only)</li>
</ul>
<p>The fields <code>url</code> and <code>doi</code> are defined only for
BibTeX because <code>biblatex</code> defines them as optional fields for
most entry types. If these fields are not sufficient for your use, you
can customise the option <code>ebib-extra-fields</code>.</p>
<p>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 <a
href="#undefined-fields">Undefined Fields</a> for some more
information.</p>
<h2 id="navigating-the-database">Navigating the Database</h2>
<p>The basic motion keys in the index buffer are the following:</p>
<table>
<thead>
<tr class="header">
<th>Key</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><span class="key"><code>up</code></span> <span
class="key"><code>p</code></span> <span
class="key"><code>C-p</code></span></td>
<td>move one entry up</td>
</tr>
<tr class="even">
<td><span class="key"><code>down</code></span> <span
class="key"><code>n</code></span> <span
class="key"><code>C-n</code></span></td>
<td>move one entry down</td>
</tr>
<tr class="odd">
<td><span class="key"><code>b</code></span> <span
class="key"><code>PgUp</code></span></td>
<td>move one page up</td>
</tr>
<tr class="even">
<td><span class="key"><code>Space</code></span> <span
class="key"><code>PgDn</code></span></td>
<td>move one page down</td>
</tr>
<tr class="odd">
<td><span class="key"><code>g</code></span> <span
class="key"><code>Home</code></span></td>
<td>move to the first entry</td>
</tr>
<tr class="even">
<td><span class="key"><code>G</code></span> <span
class="key"><code>End</code></span></td>
<td>move to the last entry</td>
</tr>
</tbody>
</table>
<p>If you have more than one database opened, you can use the keys <span
class="key"><code>1</code></span>–<span
class="key"><code>9</code></span> 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 <span
class="key"><code>left</code></span> and <span
class="key"><code>right</code></span> cursor keys to move to the
previous or next database (these keys wrap).</p>
<p>You can quickly jump to any entry in a database with the key <span
class="key"><code>j</code></span>. 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 <span
class="key"><code>C-u j</code></span>.</p>
<p>If you use <a
href="https://github.com/raxod502/selectrum">selectrum</a>, <a
href="https://github.com/abo-abo/swiper">ivy</a> or <a
href="https://github.com/emacs-helm/helm">helm</a> or the built-in
package ido, using <span class="key"><code>j</code></span> 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.</p>
<p>Ebib keeps a history of the entries that you’ve visited. You can move
through this history with <span class="key"><code>C-b</code></span> and
<span class="key"><code>C-f</code></span>. Furthermore, using the Emacs
command <code>point-to-register</code>, you can store an entry in a
register and jump back to it at a later point with
<code>jump-to-register</code>.</p>
<h2 id="displaying-and-sorting-the-entries-list">Displaying and Sorting
the Entries List</h2>
<p>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 <span
class="key"><code>&lt;</code></span> and <span
class="key"><code>&gt;</code></span>. 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 <span
class="key"><code>=</code></span>.</p>
<p>The fields that are displayed in the index buffer can be customised
with the user option <code>ebib-index-columns</code>. 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.</p>
<p>You can use any <code>biblatex</code> 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 <code>"Entry Key"</code>, which displays the entry key, is not a
field. Similarly, there is a column label <code>"Author/Editor"</code>,
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 <code>"Year"</code> does not simply display the contents of the
year field. Rather, it first checks the contents of the date field,
which is <code>biblatex</code>’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.</p>
<p>Three other column labels have special behaviour:
<code>"Title"</code>, <code>"Doi"</code>, and <code>"Url"</code>. These
do display information from the fields they correspond with, but in a
special way: <code>"Title"</code> tries to make the title look nice by
removing braces and LaTeX commands (leaving only their obligatory
arguments) and by displaying the arguments of <code>\emph</code>,
<code>\textit</code>, <code>\textbf</code> and <code>\textsc</code> in
italic, bold or caps. Accented characters that are created using LaTeX
commands such as <code>\"{a}</code> are displayed as the actual accented
characters and a number of LaTeX commands for special characters are
replaced with the corresponding Unicode character.</p>
<p>The column labels <code>"Doi"</code> and <code>"Url"</code> don’t
display the contents of these fields, but instead yield a clickable
string <code>"www"</code>; clicking on <code>"www"</code> takes you to
the relevant web page.</p>
<p>The final predefined column label is <code>"Note"</code>. 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 <a href="#notes-files">Notes Files</a>). For those
entries that have an annotation, the <code>"Note"</code> column displays
a (clickable) <code>"N"</code>. (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.)</p>
<p>You can define new column labels and redefine the existing ones by
customising the option <code>ebib-field-transformation-functions</code>.
Note that <code>"Title"</code>, <code>"Doi"</code>, <code>"Url"</code>,
and <code>"Note"</code> are actually defined through this option. For
example, if you do not wish for TeX markup to be hidden in titles,
remove the <code>"Title"</code> entry in this option. The
columns<code>"Entry Key"</code>, <code>"Author/Editor"</code>, and
<code>"Year"</code> are not defined in
<code>ebib-field-transformation-functions</code> (they are hard-coded),
but they <em>can</em> be overridden by adding an entry for them.</p>
<p>The first column defined in <code>ebib-index-colums</code> is the
column on which the entries are sorted by default, i.e., when the
database is first opened and when you press <span
class="key"><code>=</code></span>. 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 <code>ebib-index-default-sort</code>.</p>
<p>By default, sorting is done on the string representation of the field
value, using the function <code>string-collate-lessp</code>. For numeric
fields, this may not be appropriate, because it means that the value
<code>10</code> is sorted between <code>1</code> and <code>2</code>. To
specify a custom sort function for particular fields, you can customise
the option <code>ebib-field-sort-functions-alist</code>. To sort numeric
fields, you can use the predefined function
<code>ebib-compare-numerical-strings</code>, but you can also define a
custom sort function yourself.</p>
<h2 id="biblatex-vs.-bibtex">Biblatex vs. BibTeX</h2>
<p>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,
<code>biblatex</code> 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, <code>biblatex</code> (and its back-end <code>Biber</code>) has
proper Unicode support.</p>
<p>For these reasons, the use of <code>biblatex</code> is highly
recommended for anyone using LaTeX. For historical reasons, however,
BibTeX is still the default dialect, so if you intend to use
<code>biblatex</code> files, you need to tell Ebib that your files are
<code>biblatex</code> files.</p>
<h3 class="unlisted unnumbered" id="setting-the-bibtex-dialect">Setting
the BibTeX Dialect</h3>
<p><code>Biblatex</code> files use the same <code>.bib</code> suffix
that BibTeX files use. Whether Ebib interprets a file as a BibTeX or a
<code>biblatex</code> file is determined by the user option
<code>ebib-bibtex-dialect</code>. Possible values for this option are
<code>BibTeX</code> and <code>biblatex</code>, the default being
<code>BibTeX</code>. (These values are taken from the variable
<code>bibtex-dialect-list</code>.)</p>
<p>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’ <code>error</code>
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).</p>
<p>The option <code>ebib-bibtex-dialect</code> sets the default dialect,
which is the dialect that Ebib gives to newly created <code>.bib</code>
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 <span
class="key"><code>M-x ebib-set-dialect</code></span>. You only need to
do this once for a file, because the setting is saved in the
<code>.bib</code> 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 <code>bibtex-dialect</code>, which
means that if you should open the file directly in
<code>bibtex-mode</code>, Emacs will apply the dialect setting as
well.</p>
<p>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 <code>.bib</code> file: if the file does not
have a dialect setting, the mode line shows the default setting.</p>
<h3 class="unlisted unnumbered" id="alias-types-and-fields">Alias Types
and Fields</h3>
<p>The set of entry types defined by <code>biblatex</code> differs from
the set used by BibTeX. Mostly, <code>biblatex</code> adds new entry
types, but there are a few BibTeX entry types that have been dropped.
For legacy reasons, <code>biblatex</code> still recognises these entry
types, but it treats them as aliases for some of its own types:</p>
<table>
<thead>
<tr class="header">
<th>BibTeX Entry type</th>
<th>Biblatex entry type</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>@Conference</code></td>
<td><code>@InProceedings</code></td>
</tr>
<tr class="even">
<td><code>@Electronic</code></td>
<td><code>@Online</code></td>
</tr>
<tr class="odd">
<td><code>@MastersThesis</code></td>
<td><code>@Thesis</code> with <code>type</code> as ‘Master’s
thesis’</td>
</tr>
<tr class="even">
<td><code>@PhDThesis</code></td>
<td><code>@Thesis</code> with <code>type</code> as ‘PhD thesis’</td>
</tr>
<tr class="odd">
<td><code>@TechReport</code></td>
<td><code>@Report</code> with <code>type</code> as ‘technical
report’</td>
</tr>
<tr class="even">
<td><code>@www</code></td>
<td><code>@Online</code></td>
</tr>
</tbody>
</table>
<p>If an entry has such an alias as entry type, Ebib displays the entry
type that <code>biblatex</code> treats it as in the entry buffer. For
example, the entry type alias <code>PhDThesis</code> is shown as
<code>PhDThesis [==&gt; Thesis]</code>.</p>
<p>Similarly, a number of fields are deprecated but still accepted as
aliases:</p>
<table>
<thead>
<tr class="header">
<th>BibTeX Field</th>
<th>Biblatex Field</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>address</code></td>
<td><code>location</code></td>
</tr>
<tr class="even">
<td><code>annote</code></td>
<td><code>annotation</code></td>
</tr>
<tr class="odd">
<td><code>archiveprefix</code></td>
<td><code>eprinttype</code></td>
</tr>
<tr class="even">
<td><code>journal</code></td>
<td><code>journaltitle</code></td>
</tr>
<tr class="odd">
<td><code>key</code></td>
<td><code>sortkey</code></td>
</tr>
<tr class="even">
<td><code>pdf</code></td>
<td><code>file</code></td>
</tr>
<tr class="odd">
<td><code>primaryclass</code></td>
<td><code>eprintclass</code></td>
</tr>
<tr class="even">
<td><code>school</code></td>
<td><code>institution</code></td>
</tr>
</tbody>
</table>
<p>These aliases are also indicated in the entry buffer: for example, if
an entry has a <code>journal</code> field, its value is shown as the
value of the <code>journaltitle</code> field; a tag
<code>[&lt;== journal]</code> is placed after the field value,
indicating that the value is actually contained in the journal field.
The <code>journal</code> 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 <code>journal</code> field to
the <code>journaltitle</code> field, if you wish to bring your entries
into line with <code>biblatex</code>’s conventions.</p>
<h1 id="editing-the-database">Editing the Database</h1>
<p>Obviously, Ebib not only allows you to see the BibTeX entries in your
<code>.bib</code> files, you can also edit them. This section describes
the most important editing facilities.</p>
<h2 id="adding-and-deleting-entries">Adding and Deleting Entries</h2>
<p>To add an entry to a database, press <span
class="key"><code>a</code></span>. 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
<code>bibtex-generate-autokey</code> for this; see that function’s
documentation string for customisation options.) If you prefer to
specify a key yourself, you can unset the option
<code>ebib-autogenerate-keys</code>.</p>
<p>Deleting an entry can be done in two ways. The key <span
class="key"><code>d</code></span> 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 <span class="key"><code>k</code></span>, which kills the current
entry, i.e., the entry is deleted from the database and added to the
kill ring.</p>
<p>The key <span class="key"><code>y</code></span> 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 <span class="key"><code>y</code></span> again to (try and) add the
next element in the kill ring to the database. Yanking also works with
<code>@Preamble</code>, <code>@String</code> and <code>@Comment</code>
definitions.</p>
<p>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.</p>
<p>Note that it is possible to copy an entry to the kill ring (without
deleting it) with the key sequence <span
class="key"><code>C e</code></span>, i.e., capital <span
class="key"><code>C</code></span> followed by <span
class="key"><code>e</code></span>. (See <a
href="#copying-entries-to-the-kill-ring">Copying Entries to the Kill
Ring</a> for more copying commands.)</p>
<h2 id="marking-entries">Marking Entries</h2>
<p>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 <span
class="key"><code>m</code></span> and then perform the command. Commands
for which it makes sense automatically operate on all marked entries if
there are any.</p>
<p>With a prefix argument, i.e, with <span
class="key"><code>C-u</code></span> followed by <span
class="key"><code>m</code></span>, you can unmark all entries or, if
there are no marked entries, mark all entries in the current
database.</p>
<h2 id="editing-field-values">Editing Field Values</h2>
<p>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 <span class="key"><code>e</code></span> in the
index buffer.</p>
<p>You can move between fields with the same keys that you use to move
between entries in the index buffer:</p>
<table>
<thead>
<tr class="header">
<th>Key</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><span class="key"><code>up</code></span> <span
class="key"><code>p</code></span> <span
class="key"><code>C-p</code></span></td>
<td>move one field up</td>
</tr>
<tr class="even">
<td><span class="key"><code>down</code></span> <span
class="key"><code>n</code></span> <span
class="key"><code>C-n</code></span></td>
<td>move one field down</td>
</tr>
<tr class="odd">
<td><span class="key"><code>b</code></span> <span
class="key"><code>PgUp</code></span></td>
<td>move to previous set</td>
</tr>
<tr class="even">
<td><span class="key"><code>Space</code></span> <span
class="key"><code>PgDn</code></span></td>
<td>move to next set</td>
</tr>
<tr class="odd">
<td><span class="key"><code>g</code></span> <span
class="key"><code>Home</code></span></td>
<td>move to the first field</td>
</tr>
<tr class="even">
<td><span class="key"><code>G</code></span> <span
class="key"><code>End</code></span></td>
<td>move to the last field</td>
</tr>
</tbody>
</table>
<p>To finish editing fields and move focus back to the index window, use
<span class="key"><code>q</code></span>.</p>
<p>Editing a field value can be done with <span
class="key"><code>e</code></span> or <span
class="key"><code>RET</code></span>. For most fields, Ebib simply asks
you for a string value in the minibuffer. There is no need to put braces
<code>{}</code> around field values, Ebib adds them when it saves the
<code>.bib</code> file.</p>
<p>Fields for which it makes sense offer completion when you edit them.
For example, when you edit the <code>type</code> field, completion is
offered on all predefined entry types. Similarly, if you edit the
<code>crossref</code> field, Ebib offers completion on the keys in the
databases currently open. The <code>keywords</code> field offers
completion on all configured keywords (see the section <a
href="#managing-keywords">Managing Keywords</a>) and the
<code>file</code> field offers file name completion (see <a
href="#viewing-and-importing-files">Viewing and Importing
Files</a>).</p>
<p>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 <code>author</code>, <code>editor</code>,
<code>journal</code>, <code>journaltitle</code>,
<code>organization</code> and <code>publisher</code> fields.</p>
<p>In the <code>author</code> and <code>editor</code> 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 <code>"and"</code> or
the semicolon that separates them.</p>
<p>If you want to edit a field value directly, without completion, you
can use a prefix argument: <span class="key"><code>C-u e</code></span>
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
<code>ebib-edit-fields-functions</code>.</p>
<p>With fields that can contain lists of values, such as the
<code>author</code> and <code>editor</code> fields, but also the
<code>file</code> field, Ebib offers multiple completion: you can select
one candidate with <code>TAB</code> and then go on to select the next
one. When you’ve selected all candidates you want, hit <code>RET</code>.
Ebib uses Emacs’ standard <code>completing-read-multiple</code> function
for this, but note that <code>crm-separator</code> is set to something
appropriate for the field being edited.</p>
<h2 id="string-abbreviations-in-field-values"><code>@String</code>
abbreviations in field values</h2>
<p>BibTeX and <code>biblatex</code> provide so-called
<code>@String</code> abbreviations, short abbreviations for strings of
text that occur often in your database, e.g., publisher names, names of
journals, etc.</p>
<p>You can define such abbreviations in Ebib in the <em>strings
buffer</em> (see <a href="#string-definitions"><code>@String</code>
Definitions</a> for details). To use a <code>@String</code> abbreviation
in a field value, the field’s value must be marked as <em>special</em>.
Normally, when Ebib saves the database, it puts braces around field
values. If a field has a <code>@string</code> abbreviation in it, it
shouldn’t be surrounded with braces, because that would prevent
<code>biblatex</code> or BibTeX from expanding the abbreviation.</p>
<p>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 <span
class="key"><code>r</code></span>. An asterisk will appear before the
field, indicating its status. Pressing <span
class="key"><code>r</code></span> again will change the field back to
normal. If you press <span class="key"><code>r</code></span> on a field
that does not have a value yet, Ebib will ask you for one.</p>
<p>By default, Ebib shows the <em>expanded</em> value of a field that is
marked special. So for example, if you have a <code>@String</code>
abbreviation <code>cup</code> for
<code>"Cambridge University Press"</code>, putting <code>cup</code> in
the <code>publisher</code> field and marking it special will show the
expanded value <code>Cambridge University Press</code> 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
<code>ebib-expand-strings</code>.</p>
<p>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:</p>
<pre><code>@String{WGA = &quot;World Gnus Almanac&quot;}</code></pre>
<p>you can create a BibTeX field like this:</p>
<pre><code>title = 1966 # WGA</code></pre>
<p>which will produce “1966 World Gnus Almanac”. Or you can do:</p>
<pre><code>month = &quot;1~&quot; # jan</code></pre>
<p>which will produce something like “1 January” (assuming your
bibliography style has defined the abbreviation <code>jan</code>; note
that <code>~</code> yields a non-breaking space). 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.</p>
<p>An easy way to enter a <code>@String</code> abbreviation as a field
value is to use the key <span class="key"><code>s</code></span> instead
of <span class="key"><code>e</code></span>. If you press <span
class="key"><code>s</code></span>, Ebib asks you for a
<code>@String</code> abbreviation to put in the current field, and
automatically marks the field as special. This method uses
completion.</p>
<h2 id="editing-multiline-values">Editing Multiline Values</h2>
<p>There are two other fields that Ebib handles in a special way when
you edit their value. These are the <code>annotation</code> field (or
<code>annote</code> in BibTeX), and the <code>abstract</code> field.
Most field values normally consist of a single line of text. However,
because the <code>annotation</code> and <code>abstract</code> 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 <em>multiline
edit buffer</em>. This is essentially a text mode buffer that allows you
to enter text freely.</p>
<p>To store the text and leave the multiline edit buffer, press <span
class="key"><code>C-c C-c</code></span>. If you want to leave the
multiline edit buffer and discard your changes, press <span
class="key"><code>C-c C-k</code></span>. 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.</p>
<p>For more details on working with multiline edit buffers, see <a
href="#multiline-edit-buffers">Multiline Edit Buffers</a>.</p>
<p>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
<code>[...]</code> is added after the last line that is displayed. If
you want to see the whole contents of a multiline field, you can use
<span class="key"><code>v</code></span>: this will display the contents
of the current field in a <code>*Help*</code> buffer (which can be
dismissed again with <span class="key"><code>q</code></span>). It is
possible to customise the way a multiline value is displayed in the
entry buffer. See the options
<code>ebib-multiline-display-function</code> and
<code>ebib-multiline-display-max-lines</code> for details.</p>
<p>Note that multiline values are not restricted to the
<code>annotation</code> and <code>abstract</code> fields. Any field
except the <code>type</code> and <code>crossref</code> fields can in
fact hold a multiline value. To give a field a multiline value, use
<span class="key"><code>m</code></span> instead of <span
class="key"><code>e</code></span>.</p>
<h2 id="copy-cut-kill-paste-yank-and-delete">Copy, Cut (Kill), Paste
(Yank), and Delete</h2>
<p>A few more commands are available when you’re in the entry buffer
editing field values. The commands <span
class="key"><code>c</code></span>, <span
class="key"><code>k</code></span> and <span
class="key"><code>y</code></span> implement copy, kill and yank: <span
class="key"><code>c</code></span> copies the contents of the current
field to the kill ring, <span class="key"><code>k</code></span> kills
the contents of the current field to the kill ring, and <span
class="key"><code>y</code></span> yanks (pastes) the most recently
killed text in the kill ring. You can press <span
class="key"><code>y</code></span> repeatedly to get the same effect you
get in Emacs when you press <span class="key"><code>M-y</code></span>
after an initial <span class="key"><code>C-y</code></span>.</p>
<p>The contents of a field can also be deleted with the command <span
class="key"><code>d</code></span>. 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.</p>
<p>Note that <span class="key"><code>y</code></span> 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 <span
class="key"><code>d</code></span> first to delete the text.</p>
<h2 id="undefined-fields">Undefined Fields</h2>
<p><code>Biblatex</code> 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.</p>
<p>It is even possible to add such fields to an entry by pressing <span
class="key"><code>a</code></span> 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 <code>ebib-extra-fields</code>.</p>
<p>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 <code>.bib</code> file, the field is gone.)</p>
<h2 id="hiding-fields-from-display">Hiding Fields from Display</h2>
<p><code>Biblatex</code> 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).</p>
<p>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 <span class="key"><code>H</code></span> (in the index buffer).
Alternatively, you can use <span class="key"><code>a</code></span> in
the entry buffer to add a field, provided you know its exact name. (Keep
in mind that you can use <span class="key"><code>a</code></span> to add
fields that are not predefined, so Ebib won’t complain if you mistype
the field name. Completion is available, though.)</p>
<p>Which fields are treated as hidden is controlled by the option
<code>ebib-hidden-fields</code>, which can be customised. The default
value of this option contains a fairly long list of fields, most of
which are <code>biblatex</code>-specific, though the option can of
course be used for BibTeX files as well.</p>
<p>If you prefer Ebib to show <em>only</em> the fields that have a
value, (e.g., when you use Ebib mainly for viewing, not for editing,
BibTeX entries), you can set <code>ebib-hidden-fields</code> to the
value <code>t</code>: This essentially makes all fields hidden, which
means that all fields without a value are suppressed and only fields
with a value are shown.</p>
<h2 id="timestamps">Timestamps</h2>
<p>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 <code>timestamp</code>, which is hidden by
default.</p>
<p>You can tell Ebib to create timestamps by setting the option
<code>ebib-use-timestamp</code>. With this option set, a timestamp is
included in entries added to the database with <span
class="key"><code>a</code></span>. 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.</p>
<p>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”.</p>
<p>Ebib uses the function <code>format-time-string</code> to create the
timestamp. The format string that Ebib uses can be customised. The
default string is <code>"%Y-%m-%d %T (%Z)"</code>, which produces a
timestamp of the form <code>"2007-03-12 01:03:26 (CET)"</code>. This
string is sortable and has the additional advantage that it can be
converted to Emacs’ internal time representation with the function
<code>date-to-time</code>. The format can be customised; see the
documentation for <code>format-time-string</code> on the options that
are available.</p>
<p>Adding timestamps in a format that <code>date-to-time</code> can
parse makes it possible to list the most recent additions to the
database. Ebib provides a function to do this:
<code>ebib-list-recent</code>, which asks for a number of days and lists
the entries that were added since then. See <a
href="#special-filters">Special Filters</a> for details.</p>
<h2 id="saving-a-database">Saving a Database</h2>
<p>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 <span
class="key"><code>s</code></span>. This saves the database to the file
it was loaded from without asking for confirmation. (It is similar to
<span class="key"><code>C-x C-s</code></span> in Emacs.) If you are
saving a file for the first time after loading it, Ebib creates a backup
file. (Ebib honours <code>backup-directory-alist</code> when saving
backups. Note that you can also disable backups altogether with the
option <code>ebib-create-backups</code>.)</p>
<p>If you want to force-save a database that has not been modified, you
can use a prefix argument: <span class="key"><code>C-u s</code></span>.
Ebib still checks whether the underlying file was modified, though. If
you also want to forego this check, use a double prefix argument: <span
class="key"><code>C-u C-u s</code></span>. This saves the file
unconditionally.</p>
<p>You can also save a database to another name with <span
class="key"><code>w</code></span>. This command is similar to <span
class="key"><code>C-x C-w</code></span> in Emacs: the new
<code>.bib</code> file becomes associated with the database. This
command can also be prefixed with <span
class="key"><code>C-u</code></span> in order to overwrite any existing
file without asking for confirmation.</p>
<p>Note that by default, Ebib uses a single TAB to indent fields inside
BibTeX entries. If you prefer to use spaces, set the option
<code>ebib-save-indent-as-bibtex</code>. When this option is set, Ebib
uses the value of the variables <code>bibtex-entry-offset</code> and
<code>bibtex-field-indentation</code> to compute how many spaces to use
to indent fields.</p>
<h3 class="unlisted unnumbered" id="exporting-entries">Exporting
Entries</h3>
<p>Sometimes it can be useful to copy entries from one database to
another, or to create a new <code>.bib</code> 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 <span class="key"><code>x</code></span>. This
command operates on a single entry or on all marked entries.</p>
<p>You can also export entries to a file. To do this, call the command
<span class="key"><code>x</code></span> with a prefix argument: <span
class="key"><code>C-u x</code></span> 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.</p>
<p>Apart from entries, it is also possible to export the
<code>@Preamble</code> and <code>@String</code> definitions. The
<code>@Preamble</code> definition is exported with the command <span
class="key"><code>X</code></span> in the index buffer.
<code>@String</code> definitions can be exported in the strings buffer:
<span class="key"><code>x</code></span> in this buffer exports the
current string, while <span class="key"><code>X</code></span> exports
all <code>@String</code> 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.</p>
<h2 id="cross-referencing">Cross-referencing</h2>
<p>Both <code>Biblatex</code> and BibTeX allow entries to refer to other
entries through the <code>crossref</code> field. If an entry has a
<code>crossref</code> field, Ebib displays the field values that the
entry inherits from its parent entry. To indicate that they are just
inherited values, they are marked with <code>ebib-crossref-face</code>,
which by default inherits from <code>font-lock-comment-face</code>.
These values are merely displayed for convenience: they cannot be
edited. (They can be copied, however).</p>
<p><code>Biblatex</code>’s inheritance rules are fairly sophisticated:
they depend on the fields and on the types of the child <em>and</em>
parent entry. Ebib fully supports this inheritance schema. Since
inheritance rules can be customised in <code>biblatex</code>, they are
defined in Ebib in the customisable option
<code>ebib-biblatex-inheritances</code>. This is set up with the default
inheritance relations defined by <code>biblatex</code>, but can be
customised if needed.</p>
<p>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.</p>
<p>If you are viewing an entry that has a <code>crossref</code> field
and you want to go to the parent entry you can press <span
class="key"><code>C</code></span>. This command reads the value of the
<code>crossref</code> 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 <span
class="key"><code>C</code></span>: if you press <span
class="key"><code>C</code></span> on an entry that does not have a
<code>crossref</code> field, Ebib starts searching the database for the
current entry key.</p>
<p>Note that after Ebib has jumped to the first child entry, you cannot
press <span class="key"><code>C</code></span> 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
press <span class="key"><code>RET</code></span>, as with a normal
search. (Also, if the cross-referenced entry appears alphabetically
before the cross-referencing entry, you need to press <span
class="key"><code>g</code></span> and then <span
class="key"><code>/</code></span>.)</p>
<p>Note that if you want to use <code>biblatex</code>’s or BibTeX’s
cross-referencing mechanism, the option
<code>ebib-save-xrefs-first</code> needs to be set (which it is by
default). This tells Ebib to save all entries with a
<code>crossref</code> field first in the <code>.bib</code> file. Without
this, cross-referencing will not work reliably.</p>
<h2 id="sorting-the-.bib-file">Sorting the <code>.bib</code> File</h2>
<p>By default, the entries in the database are saved to the
<code>.bib</code> file in alphabetical order according to entry key.
(Entries with a <code>crossref</code> 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 <code>.bib</code> file.</p>
<p>Ebib allows you to specify the sort order in the <code>.bib</code>
file with the user option <code>ebib-sort-order</code>. This is a list
of <em>sort levels</em>: 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.</p>
<p>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
<code>(author editor)</code>, an entry is sorted on the
<code>author</code> field if it has a value and on the
<code>editor</code> 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.</p>
<p>If two or more entries yield the same value for the first sort level,
meaning that they cannot be sorted on that level, they are sorted on the
second sort level. If, for example, the second sort level is
<code>(year)</code>, entries from the same author are sorted on the year
of publication.</p>
<p>The difference between two sort fields within one sort level and two
sort levels is that a second sort <em>field</em> is an alternative for
the first field when it has no value, while a second sort <em>level</em>
is an additional sort criterion when two or more entries cannot be
sorted on the first level, because they have identical values.</p>
<p>By default, the option <code>ebib-sort-order</code> has no value,
which means that the entries in the <code>.bib</code> 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
<code>(author editor)</code> and the second to <code>(year)</code>. Keep
in mind that if you do set this option, you need to unset the option
<code>ebib-save-xrefs-first</code> (see <a
href="#cross-referencing">Cross-referencing</a>). It is pointless to set
a sort order if cross-referenced entries are saved first.</p>
<h2 id="preamble-definition"><span class="citation"
data-cites="Preamble">@Preamble</span> Definition</h2>
<p>Apart from database entries, BibTeX allows three more types of
elements to appear in a <code>.bib</code> file. These are
<code>@Preamble</code>, <code>@String</code> and <code>@Comment</code>
definitions. Ebib provides facilities to handle these, which are
discussed here and in the following sections.</p>
<p>Ebib allows you to add one <code>@Preamble</code> definition to the
database. In principle, BibTeX allows more than one such definition, but
one suffices, because you can use the concatenation character
<code>#</code> to include multiple TeX or LaTeX commands. So, rather
than having two <code>@Preamble</code> definitions such as:</p>
<pre><code>@Preamble{ &quot;\newcommand{\noopsort}[1]{} &quot; }
@Preamble{ &quot;\newcommand{\singleletter}[1]{#1} &quot; }</code></pre>
<p>you can write this in your <code>.bib</code> file:</p>
<pre><code>@Preamble{ &quot;\newcommand{\noopsort}[1]{} &quot;
         # &quot;\newcommand{\singleletter}[1]{#1} &quot; }</code></pre>
<p>Creating or editing a <code>@Preamble</code> definition in Ebib is
done by hitting (uppercase) <span class="key"><code>P</code></span> in
the index buffer. Ebib uses the multiline edit buffer for editing the
text of the <code>@Preamble</code> definition, which means that <span
class="key"><code>C-c C-c</code></span> stores the
<code>@Preamble</code> text and returns focus to the index buffer, while
<span class="key"><code>C-c C-k</code></span> returns focus to the index
buffer while abandoning any changes you may have made. (For details on
using multiline edit buffers, see <a
href="#multiline-edit-buffers">Multiline Edit Buffers</a>.)</p>
<p>In order to create a <code>@Preamble</code> as shown above in Ebib,
you only have to type the text between the braces. Ebib takes care of
including the braces of the <code>@Preamble</code> 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:</p>
<pre><code>&quot;\newcommand{\noopsort}[1]{} &quot; # &quot;\newcommand{\singleletter}[1]{#1} &quot;</code></pre>
<p>Note that when Ebib loads a <code>.bib</code> file that contains more
than one <code>@Preamble</code> definition, it concatenates all the
strings in them in the manner just described and saves them in one
<code>@Preamble</code> definition.</p>
<h2 id="string-definitions"><span class="citation"
data-cites="String">@String</span> Definitions</h2>
<p>If you press (uppercase) <span class="key"><code>S</code></span> in
the index buffer, Ebib hides the entry buffer in the lower window and
replaces it with the <em>strings buffer</em>. In this buffer, you can
add, delete and edit <code>@String</code> definitions.</p>
<p>Adding a <code>@String</code> definition is done with the command
<span class="key"><code>a</code></span>. 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.</p>
<p>The following keys are available in the strings buffer:</p>
<table>
<colgroup>
<col style="width: 55%" />
<col style="width: 44%" />
</colgroup>
<thead>
<tr class="header">
<th>Key</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><span class="key"><code>up</code></span> <span
class="key"><code>p</code></span> <span
class="key"><code>C-p</code></span></td>
<td>move one string up</td>
</tr>
<tr class="even">
<td><span class="key"><code>down</code></span> <span
class="key"><code>n</code></span> <span
class="key"><code>C-n</code></span></td>
<td>move one string down</td>
</tr>
<tr class="odd">
<td><span class="key"><code>b</code></span> <span
class="key"><code>PgUp</code></span></td>
<td>move ten strings up</td>
</tr>
<tr class="even">
<td><span class="key"><code>Space</code></span> <span
class="key"><code>PgDn</code></span></td>
<td>move ten strings down</td>
</tr>
<tr class="odd">
<td><span class="key"><code>g</code></span> <span
class="key"><code>Home</code></span></td>
<td>move to the first string</td>
</tr>
<tr class="even">
<td><span class="key"><code>G</code></span> <span
class="key"><code>End</code></span></td>
<td>move to the last string</td>
</tr>
<tr class="odd">
<td></td>
<td></td>
</tr>
<tr class="even">
<td><span class="key"><code>e</code></span></td>
<td>edit a <code>@String</code> value</td>
</tr>
<tr class="odd">
<td></td>
<td></td>
</tr>
<tr class="even">
<td><span class="key"><code>d</code></span></td>
<td>delete a <code>@String</code> definition</td>
</tr>
<tr class="odd">
<td><span class="key"><code>c</code></span></td>
<td>copy a <code>@String</code> value</td>
</tr>
<tr class="even">
<td></td>
<td></td>
</tr>
<tr class="odd">
<td><span class="key"><code>x</code></span></td>
<td>export a <code>@String</code> definition</td>
</tr>
<tr class="even">
<td><span class="key"><code>X</code></span></td>
<td>export all <code>@String</code> definitions</td>
</tr>
</tbody>
</table>
<p>It is not possible to cut the value of a <code>@String</code>
definition, because they must have a value. Yanking has not been
implemented in the strings buffer, but you can use <span
class="key"><code>C-y</code></span> / <span
class="key"><code>M-y</code></span> in the minibuffer when editing a
<code>@String</code> value.</p>
<p><code>@String</code> definitions, like field values, can contain
other abbreviations. That is, you can define an abbreviation
<code>up</code> with the value <code>{University Press}</code>, and then
define another abbreviation <code>cup</code> with the value
<code>{Cambridge } # up</code>. This will expand to
<code>"Cambridge University Press"</code>. When Ebib detects such a
‘nested’ <code>@String</code> 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 <em>special</em>, just like field
values that contain <code>@String</code> definitions.</p>
<h2 id="comments"><span class="citation"
data-cites="Comments">@Comments</span></h2>
<p>If Ebib finds a <code>@Comment</code> in a <code>.bib</code> file, it
will read it and store it in the database. When the database is saved,
all the <code>@Comment</code>s will be saved with it, at the top of the
file, immediately after the <code>@Preamble</code> (with the exception
of a <code>@Comment</code> surrounding a <code>Local Variables:</code>
block, which is saved at the end of the file). There is no way to edit
comments, nor can you specify where in the <code>.bib</code> file a
comment is placed, but they won’t be lost.</p>
<h2 id="creating-entry-stubs">Creating Entry Stubs</h2>
<p>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
<span class="key"><code>M-x ebib-add-file-entry</code></span>. 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.</p>
<h2 id="multiline-edit-buffers">Multiline Edit Buffers</h2>
<p>As mentioned several times before, field values that contain newlines
(so-called <em>multiline fields</em>) and the <code>@Preamble</code> are
edited in a so-called <em>multiline edit buffer</em>. This section
discusses the details of this buffer.</p>
<p>Ebib enters a multiline edit buffer in one of the following cases:
when you edit the <code>@Preamble</code> definition, when you press
<span class="key"><code>m</code></span> in the entry buffer to edit a
field as multiline, or when you press <span
class="key"><code>e</code></span> on the
<code>annote</code>/<code>annotation</code> or <code>abstract</code>
fields, or on a field whose value already is multiline.</p>
<p>The major mode that is used in multiline edit buffers is
user-configurable. The default value is <code>text-mode</code>, but if
you prefer to use some other mode, you can specify this through the
customisation option <code>ebib-multiline-major-mode</code>.</p>
<p>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 <code>ebib-multiline-edit-mode</code>, which is activated
automatically in the multiline edit buffer.</p>
<p><code>ebib-quit-multiline-buffer-and-save</code>, bound to <span
class="key"><code>C-c C-c</code></span>, 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
<code>@Preamble</code>, the field value or preamble is deleted. (This is
in fact the <em>only</em> way to delete the <code>@Preamble</code>
definition. Field values on the other hand can also be deleted by
hitting <span class="key"><code>k</code></span> or <span
class="key"><code>d</code></span> on them in the entry buffer.)</p>
<p><code>ebib-cancel-multiline-buffer</code>, bound to <span
class="key"><code>C-c C-k</code></span>, 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.</p>
<p><code>ebib-save-from-multiline-buffer</code>, bound to <span
class="key"><code>C-c C-s</code></span>, 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.</p>
<p>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.</p>
<p>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 (<code>ebib-multiline-mode</code>, to be
specific), but a minor mode keymap should only use key bindings of <span
class="key"><code>C-c</code></span> 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
<code>message-mode</code>, in VC, magit, etc. For this reason, Ebib uses
them as well.</p>
<p>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:</p>
<div class="sourceCode" id="cb10"><pre
class="sourceCode lisp"><code class="sourceCode commonlisp"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a>(with-eval-after-load <span class="dt">&#39;ebib</span></span>
<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a>  (define-key ebib-multiline-mode-map</span>
<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a>    <span class="st">&quot;\C-c c&quot;</span> <span class="kw">nil</span>)</span>
<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a>  (define-key ebib-multiline-mode-map</span>
<span id="cb10-5"><a href="#cb10-5" aria-hidden="true" tabindex="-1"></a>    <span class="st">&quot;\C-c | c&quot;</span> <span class="dt">&#39;ebib-quit-multiline-buffer-and-save</span>)</span>
<span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb10-7"><a href="#cb10-7" aria-hidden="true" tabindex="-1"></a>  (define-key ebib-multiline-mode-map</span>
<span id="cb10-8"><a href="#cb10-8" aria-hidden="true" tabindex="-1"></a>    <span class="st">&quot;\C-c s&quot;</span> <span class="kw">nil</span>)</span>
<span id="cb10-9"><a href="#cb10-9" aria-hidden="true" tabindex="-1"></a>  (define-key ebib-multiline-mode-map</span>
<span id="cb10-10"><a href="#cb10-10" aria-hidden="true" tabindex="-1"></a>    <span class="st">&quot;\C-c | s&quot;</span> <span class="dt">&#39;ebib-save-from-multiline-buffer</span>)</span>
<span id="cb10-11"><a href="#cb10-11" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb10-12"><a href="#cb10-12" aria-hidden="true" tabindex="-1"></a>  (define-key ebib-multiline-mode-map</span>
<span id="cb10-13"><a href="#cb10-13" aria-hidden="true" tabindex="-1"></a>    <span class="st">&quot;\C-c k&quot;</span> <span class="kw">nil</span>)</span>
<span id="cb10-14"><a href="#cb10-14" aria-hidden="true" tabindex="-1"></a>  (define-key ebib-multiline-mode-map</span>
<span id="cb10-15"><a href="#cb10-15" aria-hidden="true" tabindex="-1"></a>    <span class="st">&quot;\C-c | k&quot;</span> <span class="dt">&#39;ebib-cancel-multiline-buffer</span>))</span></code></pre></div>
<p>This removes the key bindings for <span
class="key"><code>C-c c</code></span>, <span
class="key"><code>C-c s</code></span> and <span
class="key"><code>C-c k</code></span> and sets up <span
class="key"><code>C-c | c</code></span>, <span
class="key"><code>C-c | s</code></span> and <span
class="key"><code>C-c | k</code></span> for use in the multiline edit
buffer. You can obviously use other keys if you prefer.</p>
<h1 id="main-and-dependent-databases">Main and Dependent Databases</h1>
<p>A common workflow with bibliographic data is to have a single
database containing all entries one works with and to export a
<code>.bib</code> 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.</p>
<p>To create a dependent database, press <span
class="key"><code>M c</code></span> 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 <a
href="#associating-a-database-with-a-text-buffer">Associating a Database
with a Text Buffer</a>). At this point, when you insert a citation into
the text buffer with <span
class="key"><code>M-x ebib-insert-citation</code></span>, 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.</p>
<p>It is also possible to add entries in the usual way, i.e., by
pressing <span class="key"><code>a</code></span> 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 <span
class="key"><code>M a</code></span>. This command also works on marked
entries, making it possible to add multiple entries to a dependent
database in one go.</p>
<p>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.</p>
<p>A database can serve as the main database for more than one dependent
database, but the reverse is not possible: each dependent database can
only have one main database.</p>
<p>If you save a dependent database, it is saved as a normal, standalone
<code>.bib</code> file that can be used with <code>biblatex</code> 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
<code>.bib</code> file. The data of each entry is taken from the main
database. This means that if you edit a dependent database’s
<code>.bib</code> file outside of Ebib, the changes you make are ignored
when you open the file in Ebib.</p>
<h1 id="inserting-citations-into-a-text-buffer">Inserting Citations into
a Text Buffer</h1>
<h2 id="single-citations">Single Citations</h2>
<p>When you’re in a text buffer and you have Ebib open in the background
(i.e., you lowered Ebib with <span class="key"><code>z</code></span>),
you can insert a citation with the command
<code>ebib-insert-citation</code>. 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 <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a> Markdown
buffers. There is some support for <a href="http://orgmode.org">Org
mode</a> as well, as discussed below.</p>
<p>When you invoke <code>ebib-insert-citation</code>, 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 <span
class="key"><code>TAB</code></span> completion when typing the key. If
you have <a href="https://github.com/raxod502/selectrum">selectrum</a>,
<a href="https://github.com/abo-abo/swiper">ivy</a> or <a
href="https://github.com/emacs-helm/helm">helm</a> 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.</p>
<p>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
<code>biblatex</code> (well, the most common ones, anyway). If you use
BibTeX, you may need to customise the option
<code>ebib-citation-commands</code>, as discussed below, <a
href="#defining-citation-commands">Defining Citation Commands</a>.</p>
<p>For Markdown buffers, three commands have been predefined:
<code>text</code>, which inserts a citation of the form
<code>@Jones1992</code>, <code>paren</code>, which inserts a citation of
the form <code>[@Jones1992]</code> and <code>year</code>, which inserts
<code>[-@Jones1992]</code>. Since these are the only types of citations
that Pandoc Markdown knows, you shouldn’t need to change anything.</p>
<p>Ebib also provides a way to insert citations into a buffer from
within Ebib. If you’re in the index buffer and press <span
class="key"><code>i</code></span>, 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.</p>
<h2 id="citations-with-multiple-keys">Citations with multiple keys</h2>
<p>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 <span class="key"><code>m</code></span> and then insert them into a
text buffer with <span class="key"><code>i</code></span>. 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 <code>ebib-insert-citation</code>. If
you use selectrum or Emacs’ built-in completion method, you can enable
selection of multiple keys by setting the option
<code>ebib-citations-insert-multiple</code>. With this option set, you
can select multiple keys when calling <code>ebib-insert-citation</code>
by selecting a candidate and then pressing <span
class="key"><code>TAB</code></span>. Once you hit <span
class="key"><code>TAB</code></span>, you need to add an ampersand <span
class="key"><code>&amp;</code></span> as a separator (possibly
surrounded by spaces) and then you can select the next candidate. Finish
by typing <span class="key"><code>RET</code></span>.</p>
<p>Note that selectrum automatically adds the ampersand for you, so you
don’t need to type it: after hitting <span
class="key"><code>TAB</code></span>, you can immediately start selecting
the next candidate. If you use default completion, however, you need to
type it yourself.</p>
<p>Also note that with default completion, <span
class="key"><code>TAB</code></span> 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, <span class="key"><code>TAB</code></span> always selects
the currently highlighted candidate. This is the default behaviour of
<span class="key"><code>TAB</code></span> in both completion systems, so
should not be confusing.</p>
<p>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.</p>
<h2 id="key-bindings">Key Bindings</h2>
<p>Of course, the easiest way to use the commands discussed here is to
bind them to a key sequence. For example, the following binds <span
class="key"><code>C-c b</code></span> to
<code>ebib-insert-citation</code> in AUCTeX’s LaTeX mode:</p>
<pre><code>(define-key &#39;LaTeX-mode-map &quot;\C-cb&quot; &#39;ebib-insert-citation)</code></pre>
<p>Note that commands of the form <span
class="key"><code>C-c &lt;letter&gt;</code></span> are reserved for the
user, and should therefore not be set by any package. For this reason,
Ebib does not set this command itself.</p>
<p><code>ebib-insert-citation</code> 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
<code>ebib-insert-citation</code> to the same key sequence in every text
mode in which you use citations and Ebib will do the right thing.</p>
<h2 id="defining-citation-commands">Defining Citation Commands</h2>
<p>Citation commands are defined for specific major modes. Ebib defines
commands for <code>latex-mode</code> (a.k.a. <code>LaTeX-mode</code>),
for <code>org-mode</code> and for <code>markdown-mode</code>. As
mentioned, the commands defined for LaTeX are those used by
<code>biblatex</code>. If you use something else, you may need to set up
some commands yourself. This can be done by customising the option
<code>ebib-citation-commands</code>.</p>
<p>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.</p>
<p>The identifier should be a simple string which you can type easily
when Ebib asks you for a citation command (<span
class="key"><code>TAB</code></span> 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:</p>
<dl>
<dt><code>%K</code></dt>
<dd>
the entry key to be inserted.
</dd>
<dt><code>%A</code></dt>
<dd>
an argument, for which the user is prompted.
</dd>
<dt><code>%&lt;...%&gt;</code></dt>
<dd>
optional material surrounding a <code>%A</code> directive.
</dd>
<dt><code>%(...%&lt;sep&gt;)</code></dt>
<dd>
a so-called <em>repeater</em>, which contains material that can be
repeated. If present, the repeater must contain the entry key directive
<code>%K</code>.
</dd>
<dt><code>%D</code></dt>
<dd>
a description, for which the user is prompted. Mainly for use in Org
citations.
</dd>
</dl>
<p>In the simplest case, the format string contains just a
<code>%K</code> directive: <code>\cite{%K}</code>. In this case,
<code>%K</code> 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 <code>biblatex</code> package, you have citation
commands available of the form:</p>
<pre><code>\textcite[cf.][p. 50]{Jones1992}</code></pre>
<p>In order to be able to insert such citations, the format string must
contain <code>%A</code> directives:</p>
<pre><code>\textcite[%A][%A]{%K}</code></pre>
<p>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 <span class="key"><code>RET</code></span>). With the format
string above, this would yield the following citation in the LaTeX
buffer:</p>
<pre><code>\textcite[][]{Jones1992}</code></pre>
<p>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 <code>%A</code> directives in a
<code>%&lt;...%&gt;</code> pair:</p>
<pre><code>\textcite%&lt;[%A]%&gt;%&lt;[%A]%&gt;{%K}</code></pre>
<p>Now, if you leave the arguments empty, Ebib produces the following
citation:</p>
<pre><code>\textcite{Jones1992}</code></pre>
<p>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:</p>
<pre><code>\textcite[cf.]{Jones1992}</code></pre>
<p>If only one optional argument is provided, <code>biblatex</code>
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:</p>
<pre><code>\textcite%&lt;[%A]%&gt;[%A]{%K}</code></pre>
<p>This way, the second pair of brackets is always inserted, regardless
of whether you provide a second argument or not.</p>
<p><code>Biblatex</code> commands also accept multiple citation keys.
When you call <code>ebib-insert-citation</code> 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 <span
class="key"><code>i</code></span> to insert them to a buffer. In this
case, Ebib asks you for a separator and then inserts all keys into the
position of <code>%K</code>:</p>
<pre><code>\textcite{Jones1992,Haddock2004}</code></pre>
<p>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 <code>%(...%)</code> pair. Normally, you’ll
want to provide a separator, which is done by placing it between the
<code>%</code> and the closing parenthesis:</p>
<pre><code>\textcite[%A][%A]{%(%K%,)}</code></pre>
<p>This format string says that the directive <code>%K</code> 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.</p>
<p>It is also possible to put <code>%A</code> directives in the
repeating part. This is useful for <code>biblatex</code>’s so-called
<em>multicite</em> commands that take the following form:</p>
<pre><code>\footcites[cf.][p. 50]{Jones1992}[][p. 201]{Haddock2004}</code></pre>
<p>Multicite commands can take more than one citation key in braces
<code>{}</code> and each of those citation keys can take two optional
arguments in brackets <code>[]</code>. In order to get such citations,
you can provide the following format string:</p>
<pre><code>\footcites%(%&lt;[%A]%&gt;[%A]{%K}%)</code></pre>
<p>Here, the entire sequence of two optional arguments and the
obligatory citation key is wrapped in <code>%(...%)</code>, so that Ebib
knows it can be repeated. If you now mark multiple entries in Ebib,
press <span class="key"><code>i</code></span> and select the
<code>footcites</code> command, Ebib will put all the keys in the
citation, asking you for two arguments for each citation key.</p>
<p>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 <code>\footcites</code> is not
repeated. But the part that is not repeated may contain <code>%A</code>
directives as well:</p>
<pre><code>\footcites%&lt;(%A)%&gt;(%A)%(%&lt;[%A]%&gt;[%A]{%K}%)</code></pre>
<p>Multicite commands in <code>biblatex</code> take two additional
arguments surrounded with parentheses. These are pre- and postnotes for
the entire sequence of citations. They can be accommodated as shown.</p>
<p>Lastly, a citation command can also contain a <code>%D</code>
directive. This is mainly for use in Org citations, which take the form
<code>[[ebib:&lt;key&gt;][&lt;description&gt;]]</code>. The description
is not an argument to the citation command but the string that will be
displayed in the Org buffer.</p>
<h2 id="associating-a-database-with-a-text-buffer">Associating a
Database with a Text Buffer</h2>
<p>The commands <code>ebib-insert-citation</code> and
<code>ebib-entry-summary</code> 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.</p>
<p>In a LaTeX buffer, Ebib looks for <code>\addbibresource</code>
commands or a <code>\bibliography</code> command and uses the files
specified in them. If the variable <code>TeX-master</code> is set (which
is used by AUCTeX to keep track of a file’s master file), the master
file is searched instead.</p>
<p>In non-LaTeX buffers, Ebib first checks if <code>pandoc-mode</code>
is active; if it is, Ebib uses the value of the
<code>bibliography</code> option. If <code>pandoc-mode</code> is not
used, Ebib simply uses all databases that are currently open.</p>
<p>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 <span
class="key"><code>M-x revert-buffer</code></span> or <span
class="key"><code>C-x C-v RET</code></span>).</p>
<p>You can override Ebib’s automatic association of <code>.bib</code>
files to a buffer by setting the variable
<code>ebib-local-bibfiles</code> to a list of files. This can be done as
a file-local or a directory-local variable, or as a customisable
option.</p>
<h2 id="links-and-citations-in-org-buffers">Links and Citations in Org
buffers</h2>
<p>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.</p>
<p>If you call <code>ebib-insert-citation</code> in an Org buffer, you
can add a link to an entry in a <code>.bib</code> file that’s open in
Ebib. The link has the form
<code>[[ebib:&lt;key&gt;][&lt;description&gt;]]</code>. The description
is a user-provided string, which you are prompted for, but a default
description is provided, which you can accept by pressing <span
class="key"><code>RET</code></span>. This default description is created
by the function in <code>ebib-citation-description-function</code> which
uses the author name and publication year to create a description.</p>
<p>If you use this type of Org link, you may want to load the
<code>org-ebib</code> package, which allows you to open Ebib with
<code>org-open-at-point</code> (by default bound to <span
class="key"><code>C-c C-o</code></span>), taking you to the entry in the
link (provided its database is opened in Ebib).</p>
<p>The <code>org-ebib</code> package also allows you to create Org links
to Ebib entries with <code>org-store-link</code> when you’re in the
entry buffer. Links created in this way have the same form, but they can
also specify the <code>.bib</code> file containing the entry by adding
an <code>@</code> 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
<code>org-ebib-link-type</code>.</p>
<h1 id="searching">Searching</h1>
<p>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.</p>
<p>If you want to look for a particular entry, the easiest way to do
this is to use <span class="key"><code>j</code></span>. This command
(<code>ebib-jump-to-entry</code>) 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: <span
class="key"><code>C-u j</code></span>.</p>
<p>If you use <a
href="https://github.com/raxod502/selectrum">selectrum</a>, <a
href="https://github.com/abo-abo/swiper">ivy</a> or <a
href="https://github.com/emacs-helm/helm">helm</a>, 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.</p>
<p>If you want to search the entire contents of your entries, not just
the author/editor names and the titles, you can use <span
class="key"><code>/</code></span>. This command
(<code>ebib-search</code>) searches for a string (more precisely, a
regular expression) starting from the current entry (i.e., <em>not</em>
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.</p>
<p>Ebib searches all the fields of each entry. It is not possible with
<span class="key"><code>/</code></span> 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
<code>[...]</code> that is displayed after the last line of the field
value.</p>
<p>A search term may of course appear more than once in the database. To
search for the next occurrence, press <span
class="key"><code>RET</code></span>. 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, press <span
class="key"><code>g</code></span> and then continue the search with
<span class="key"><code>RET</code></span>.</p>
<p>Note that once you’ve started a search with <span
class="key"><code>/</code></span>, Ebib activates a transient key map
called <code>ebib-search-map</code>. It is this map that holds the
binding for <span class="key"><code>RET</code></span> to continue
searching after the current entry and of the key <span
class="key"><code>g</code></span> 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.</p>
<p>Exiting a search (i.e., getting rid of the transient key map) is done
by pressing any key other than <span
class="key"><code>RET</code></span>, <span
class="key"><code>g</code></span> 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 <span class="key"><code>/</code></span>. So typing <span
class="key"><code>C-u /</code></span> starts searching for the previous
search string again.</p>
<p>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.</p>
<h1 id="filters">Filters</h1>
<p>Ebib also has a much more sophisticated search mechanism that makes
use of <em>filters</em>. 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 <code>author</code> field. A filter can be as complex
as you want: you can select all entries that do <em>not</em> contain
“Jones” in the <code>author</code> field, or all entries that contain
“Jones” in either the <code>author</code> or the <code>editor</code>
field, or all entries that contain “Jones” in the <code>author</code>
field, and “symbiotic hibernation” in the <code>keyword</code> field,
etc. Basically, the filter can consist of an arbitary number of search
criteria combined with the logical operators <code>and</code>,
<code>or</code> and <code>not</code>.</p>
<h2 class="unlisted unnumbered" id="simple-selection">Simple
Selection</h2>
<p>Creating a filter is simple: press <span
class="key"><code>&amp;</code></span>, 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 <code>"Jones"</code> in the
<code>author</code> field, you press <span
class="key"><code>&amp;</code></span> and type <code>author</code> as
the field and <code>Jones</code> 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
<code>ebib-filters-display-as-lisp</code> to do so.)</p>
<p>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 <code>any</code> as the field to filter on. So specifying
<code>any</code> as the field and <code>Jones</code> as the regexp will
give you all entries that have a field that contains
<code>"Jones"</code> in them.</p>
<p>Note that you can also select items based on their entry type. In
order to do that, you need to specify <code>=type=</code> 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
<code>type</code>, hence the equal signs.) If you search the
<code>=type=</code> field, only exact matches are returned, so if you
search for <code>book</code>, only the entries that are of type
<code>book</code> are returned, not those of type <code>inbook</code>.
You can use <span class="key"><code>TAB</code></span> completion in this
case, by the way.</p>
<p>If you specify the <code>keywords</code> field, the keywords
associated with your database are available for <span
class="key"><code>TAB</code></span> completion as well. Though you can
enter any search term, of course.</p>
<h2 class="unlisted unnumbered" id="complex-filters">Complex
Filters</h2>
<p>Once you have filtered your database, you can refine or extend it.
For example, suppose you have a filter selecting all entries with
<code>"Jones"</code> in the <code>author</code> field and want to add
all entries that have <code>"Jones"</code> in the editor field to your
selection. In this case you need to do a logical <code>or</code>
operation: you want to select an entry if it contains
<code>"Jones"</code> in the <code>author</code> field (which you already
did) <em>or</em> if it contains <code>"Jones"</code> in the
<code>editor</code> field.</p>
<p>A short sidenote: the first impulse in a case like this might be to
use <code>and</code> instead of <code>or</code>: after all, you want to
select all entries that contain <code>"Jones"</code> in the
<code>author</code> field <em>and</em> all entries that contain
<code>"Jones"</code> in the <code>editor</code> field. However, the
filter that you build up is used to test each entry
<em>individually</em> whether it meets the selection criterion. An entry
meets the criterion if it contains <code>"Jones"</code> in the
<code>author</code> field <em>or</em> if it contains
<code>"Jones"</code> in the <code>editor</code> field. Therefore,
<code>or</code> is the required operator in this case. If you would use
<code>and</code>, you would only get those entries that contain
<code>"Jones"</code> in both the <code>author</code> <em>and</em>
<code>editor</code> fields (i.e., most likely none at all).</p>
<p>To perform a logical <code>or</code> operation, press the key <span
class="key"><code>|</code></span> (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.</p>
<p>It is also possible to perform a logical <code>and</code> on the
filter. Use this if you want to select those entries that contain
<code>"Jones"</code> in the <code>author</code> field and
e.g. <code>"symbiotic hibernation"</code> in the <code>keyword</code>
field. A logical <code>and</code> operation is done with the key <span
class="key"><code>&amp;</code></span>. (Note: this is the same key that
is used to create the filter. In fact, you can create a filter with
<span class="key"><code>|</code></span> as well: when used in an
unfiltered database, <span class="key"><code>&amp;</code></span> and
<span class="key"><code>|</code></span> are equivalent. They are only
different when a filter is already active.)</p>
<p>Both the <span class="key"><code>&amp;</code></span> and <span
class="key"><code>|</code></span> commands can be used with the negative
prefix argument <span class="key"><code>M--</code></span> (or <span
class="key"><code>C-u -</code></span>, which is identical). In this
case, the search criterion is negated. That is, the negative prefix
argument performs a logical <code>not</code> operation on the search
criterion. For example, if you want to select all entries from a
database that do <em>not</em> contain “Jones” in the <code>author</code>
field, you can do this by typing <span
class="key"><code>M-- &amp;</code></span> and then filling out the
relevant field and regexp.</p>
<p>There is another way of performing a logical <code>not</code>
operation, which is only available when a filter is active: by pressing
the key <span class="key"><code>~</code></span>, you invert the current
filter. That is, if you have a filtered database with all the entries
containing <code>"Jones"</code> in the <code>author</code> or in the
<code>editor</code> field, and you press <span
class="key"><code>~</code></span>, the selection is inverted, and now
contains all entries that do <em>not</em> have <code>"Jones"</code> in
the <code>author</code> or <code>editor</code> field.</p>
<p>Although <span class="key"><code>~</code></span> and the negative
prefix argument to <span class="key"><code>&amp;</code></span> or <span
class="key"><code>|</code></span> both perform logical <code>not</code>
operations, they are <em>not</em> equivalent: <span
class="key"><code>~</code></span> negates the entire filter built up so
far, while the negative prefix argument only negates the single
selection criterion you enter with it.</p>
<p>When a filter is active, the filter itself is displayed in the index
buffer’s mode line. 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 <span
class="key"><code>F v</code></span> (uppercase <span
class="key"><code>F</code></span>, small <span
class="key"><code>v</code></span>), which will display the filter in the
minibuffer.</p>
<p>To cancel the filter and return to the normal view of the database,
press <span class="key"><code>F c</code></span>. For convenience, this
action is also available with <span class="key"><code>c</code></span>,
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 <span class="key"><code>c</code></span> key to the
function <code>ebib-close-database</code>. See <a
href="#modifying-key-bindings">Modifying Key Bindings</a> for
details.)</p>
<p>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 <code>Collection</code>, any
<code>InCollection</code> 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 <span
class="key"><code>F x</code></span>, which toggles the inclusion of
cross-referenced entries. If you wish to include cross-referenced
entries by default, customise the user option
<code>ebib-filters-include-crossref</code>.</p>
<h2 class="unlisted unnumbered" id="storing-and-saving-filters">Storing
and Saving Filters</h2>
<p>When you cancel a filter, it is automatically stored so that it can
be reapplied later. To reapply a filter, press <span
class="key"><code>F L</code></span>. 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.</p>
<p>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 <span
class="key"><code>F s</code></span>. 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 <code>ebib-filters-ignore-case</code>.) 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.</p>
<p>You can apply a stored filter with <span
class="key"><code>F a</code></span>. 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, press <span class="key"><code>F s</code></span> 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.</p>
<p>The file that Ebib uses to store filters is
<code>~/.emacs.d/ebib-filters</code>, although that can of course be
customised (<code>ebib-filters-default-file</code>). As mentioned,
stored filters are saved automatically when Ebib closes, but you can
also save them manually with <span class="key"><code>F S</code></span>.
Note that if there are no stored filters when Ebib is closed (or when
you press <span class="key"><code>F S</code></span>), the file is
deleted.</p>
<p>You can also save your filters to a different file with <span
class="key"><code>F w</code></span>. Such a filter file can be reloaded
later with <span class="key"><code>F l</code></span>. 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.)</p>
<p>To see what filters are currently stored, use <span
class="key"><code>F V</code></span>. If you want to rename a filter, you
can do so with <span class="key"><code>F R</code></span>.</p>
<p>Note that cancelling a filter with <span
class="key"><code>F c</code></span> 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 <span
class="key"><code>F d</code></span>. You can also delete all stored
filters with <span class="key"><code>F D</code></span>. These deletion
commands do not ask for confirmation, but if you delete any filters by
accident, you can reload them from <code>~/.emacs.d/ebib-filters</code>
with <span class="key"><code>F l</code></span>.</p>
<h2 class="unlisted unnumbered" id="special-filters">Special
Filters</h2>
<p>Filters are essentially Lisp expressions that consist of the
functions <code>and</code>, <code>or</code>, and <code>not</code>,
together with a special macro <code>contains</code>. 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.</p>
<p>A filter is a Lisp expression that should return either
<code>t</code> or <code>nil</code>, indicating whether the entry being
tested matches the filter or not. The contents of the entry is available
in a variable <code>ebib-entry</code>. 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
<code>(defvar ebib-entry)</code>. When the filter is run, the value of
<code>ebib-entry</code> is an alist of fields and their values. These
include the fields <code>=key=</code> and <code>=type=</code> for the
entry key and type. For example:</p>
<pre><code>((&quot;author&quot; . &quot;{Noam Chomsky}&quot;)
 (&quot;title&quot; . &quot;{Syntactic Structures}&quot;)
 (&quot;publisher&quot; . &quot;{The Hague: Mouton}&quot;)
 (&quot;year&quot; . &quot;{1957}&quot;)
 (&quot;timestamp&quot; . &quot;{2007-12-30 12:00:00 (CET)}&quot;)
 (&quot;file&quot; . &quot;{c/Chomsky1957.pdf}&quot;)
 (&quot;=type=&quot; . &quot;book&quot;)
 (&quot;=key=&quot; . &quot;Chomsky1957&quot;))</code></pre>
<h2 class="unlisted unnumbered"
id="an-example-listing-recent-additions">An Example: Listing Recent
Additions</h2>
<p>One special filter is included with Ebib. It filters recent additions
to the database. The command that creates the filter is
<code>ebib-list-recent</code>:</p>
<div class="sourceCode" id="cb25"><pre
class="sourceCode lisp"><code class="sourceCode commonlisp"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a>(<span class="kw">defun</span><span class="fu"> ebib-list-recent </span>(days)</span>
<span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a>  <span class="st">&quot;List entries created in the last DAYS days.&quot;</span></span>
<span id="cb25-3"><a href="#cb25-3" aria-hidden="true" tabindex="-1"></a>  (interactive <span class="st">&quot;nNumber of days: &quot;</span>)</span>
<span id="cb25-4"><a href="#cb25-4" aria-hidden="true" tabindex="-1"></a>  <span class="co">;; Save the database&#39;s current filter, if there is one.</span></span>
<span id="cb25-5"><a href="#cb25-5" aria-hidden="true" tabindex="-1"></a>  (<span class="kw">let</span> ((filter (ebib-db-get-filter ebib--cur-db)))</span>
<span id="cb25-6"><a href="#cb25-6" aria-hidden="true" tabindex="-1"></a>    (<span class="kw">when</span> filter (<span class="kw">setq</span> ebib--filters-last-filter filter)))</span>
<span id="cb25-7"><a href="#cb25-7" aria-hidden="true" tabindex="-1"></a>  (<span class="kw">let*</span></span>
<span id="cb25-8"><a href="#cb25-8" aria-hidden="true" tabindex="-1"></a>      <span class="co">;; Calculate the from-date in Emacs&#39; time format.</span></span>
<span id="cb25-9"><a href="#cb25-9" aria-hidden="true" tabindex="-1"></a>      ((date (time-subtract (current-time) (days-to-time days)))</span>
<span id="cb25-10"><a href="#cb25-10" aria-hidden="true" tabindex="-1"></a>       <span class="co">;; Create a Lisp expression that will function as the filter.</span></span>
<span id="cb25-11"><a href="#cb25-11" aria-hidden="true" tabindex="-1"></a>       (filter `(ebib--newer-than (<span class="kw">quote</span> ,date))))</span>
<span id="cb25-12"><a href="#cb25-12" aria-hidden="true" tabindex="-1"></a>    <span class="co">;; Install it as the current database&#39;s filter.</span></span>
<span id="cb25-13"><a href="#cb25-13" aria-hidden="true" tabindex="-1"></a>    (ebib-db-set-filter filter ebib--cur-db)</span>
<span id="cb25-14"><a href="#cb25-14" aria-hidden="true" tabindex="-1"></a>    <span class="co">;; Update the current entry key.</span></span>
<span id="cb25-15"><a href="#cb25-15" aria-hidden="true" tabindex="-1"></a>    (ebib-db-set-current-entry-key (ebib--get-key-at-point) ebib--cur-db)</span>
<span id="cb25-16"><a href="#cb25-16" aria-hidden="true" tabindex="-1"></a>    <span class="co">;; Update the display, so that only filtered entries are visible.</span></span>
<span id="cb25-17"><a href="#cb25-17" aria-hidden="true" tabindex="-1"></a>    (ebib--update-buffers)))</span></code></pre></div>
<p>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 <code>ebib--update-buffers</code>
then updates the display, taking the filter into account.</p>
<p>The function <code>ebib--newer-than</code> is defined as follows:</p>
<div class="sourceCode" id="cb26"><pre
class="sourceCode lisp"><code class="sourceCode commonlisp"><span id="cb26-1"><a href="#cb26-1" aria-hidden="true" tabindex="-1"></a>(<span class="kw">defun</span><span class="fu"> ebib--newer-than </span>(date)</span>
<span id="cb26-2"><a href="#cb26-2" aria-hidden="true" tabindex="-1"></a>  <span class="st">&quot;Function for use in filters.</span></span>
<span id="cb26-3"><a href="#cb26-3" aria-hidden="true" tabindex="-1"></a><span class="st">Return t if the entry being tested is newer than DATE.  DATE must</span></span>
<span id="cb26-4"><a href="#cb26-4" aria-hidden="true" tabindex="-1"></a><span class="st">be a list of the format returned by `current-time&#39; and is</span></span>
<span id="cb26-5"><a href="#cb26-5" aria-hidden="true" tabindex="-1"></a><span class="st">compared to the timestamp of the entry being tested.  If the</span></span>
<span id="cb26-6"><a href="#cb26-6" aria-hidden="true" tabindex="-1"></a><span class="st">entry has no timestamp, or a timestamp that cannot be converted</span></span>
<span id="cb26-7"><a href="#cb26-7" aria-hidden="true" tabindex="-1"></a><span class="st">into a date representation, return nil.&quot;</span></span>
<span id="cb26-8"><a href="#cb26-8" aria-hidden="true" tabindex="-1"></a>  (<span class="kw">let</span> ((timestamp (<span class="kw">cdr</span> (assoc-string <span class="st">&quot;timestamp&quot;</span> ebib-entry))))</span>
<span id="cb26-9"><a href="#cb26-9" aria-hidden="true" tabindex="-1"></a>    (<span class="kw">when</span> (<span class="kw">and</span> timestamp</span>
<span id="cb26-10"><a href="#cb26-10" aria-hidden="true" tabindex="-1"></a>               (<span class="kw">setq</span> timestamp (<span class="kw">ignore-errors</span> (date-to-time timestamp))))</span>
<span id="cb26-11"><a href="#cb26-11" aria-hidden="true" tabindex="-1"></a>      (time-less-p date timestamp))))</span></code></pre></div>
<p>This function obtains the time stamp of the entry being tested from
the variable <code>ebib-entry</code> 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 <code>t</code> if the latter precedes
the former.</p>
<h2 class="unlisted unnumbered"
id="properties-of-filtered-databases">Properties of Filtered
Databases</h2>
<p>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 <span
class="key"><code>F r</code></span>.</p>
<p>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 <span
class="key"><code>C-u m</code></span>, then cancel the filter and
perform an action on them.</p>
<p>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 <span
class="key"><code>w</code></span> (or the menu option “Database | Save
As”). This also saves the <code>@String</code>, <code>@Preamble</code>
and <code>@comments</code>, as well as any file-local variables, so you
will have a self-contained <code>.bib</code> 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 <span
class="key"><code>F L</code></span>, of course.)</p>
<p>One final note: of all the filter-related commands, <span
class="key"><code>~</code></span>, <span
class="key"><code>F c</code></span>, <span
class="key"><code>F r</code></span>, <span
class="key"><code>F s</code></span> and <span
class="key"><code>F v</code></span> 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.</p>
<h1 id="importing-bibtex-entries">Importing BibTeX entries</h1>
<p>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.</p>
<h2 id="merging-.bib-files">Merging <code>.bib</code> files</h2>
<p>In the index buffer, the Ebib menu has an option to merge a second
<code>.bib</code> 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
<code>.bib</code> 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.</p>
<h2 id="importing-entries-from-a-buffer">Importing entries from a
buffer</h2>
<p>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 &amp; paste them to any
Emacs buffer (e.g. the <code>*scratch*</code> buffer), and then execute
the command <span
class="key"><code>M-x ebib-import-entries</code></span>. 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.</p>
<p>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 <code>&lt;new-entryXX&gt;</code>, where
<code>XX</code> is a number. You can change such keys by hitting <span
class="key"><code>E</code></span> 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 <code>ebib-autogenerate-keys</code> for
details.</p>
<p>The user option <code>ebib-import-entries-filters</code> can be set
to a list of functions that are applied to each entry that is imported.
You can use this to make specific modifications to entries before they
are added to the database. Each function should take a single entry as
its sole argument and should return the modified entry. As a special
case, if a filter function returns <code>nil</code>, the entry is not
changed. (This is to make sure that a filter function cannot
accidentally drop an entry entirely.)</p>
<h2 id="integration-with-the-biblio-package">Integration with the Biblio
package</h2>
<p><a href="https://github.com/cpitclaudel/biblio.el">Biblio</a> 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
<code>ebib-biblio</code> in your init file and adding two keybindings:
one to <code>ebib-index-mode-map</code> and one to
<code>biblio-selection-mode-map</code>:</p>
<div class="sourceCode" id="cb27"><pre
class="sourceCode lisp"><code class="sourceCode commonlisp"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a>(<span class="kw">require</span> <span class="dt">&#39;ebib-biblio</span>)</span>
<span id="cb27-2"><a href="#cb27-2" aria-hidden="true" tabindex="-1"></a>(define-key ebib-index-mode-map (kbd <span class="st">&quot;B&quot;</span>) <span class="op">#&#39;</span>ebib-biblio-import-doi)</span>
<span id="cb27-3"><a href="#cb27-3" aria-hidden="true" tabindex="-1"></a>(define-key biblio-selection-mode-map (kbd <span class="st">&quot;e&quot;</span>) <span class="op">#&#39;</span>ebib-biblio-selection-import)</span></code></pre></div>
<p>Or with <code>use-package</code>:</p>
<div class="sourceCode" id="cb28"><pre
class="sourceCode lisp"><code class="sourceCode commonlisp"><span id="cb28-1"><a href="#cb28-1" aria-hidden="true" tabindex="-1"></a>(<span class="kw">use-package</span> ebib-biblio</span>
<span id="cb28-2"><a href="#cb28-2" aria-hidden="true" tabindex="-1"></a>  :after (ebib biblio)</span>
<span id="cb28-3"><a href="#cb28-3" aria-hidden="true" tabindex="-1"></a>  :bind (:map ebib-index-mode-map</span>
<span id="cb28-4"><a href="#cb28-4" aria-hidden="true" tabindex="-1"></a>              (<span class="st">&quot;B&quot;</span> . ebib-biblio-import-doi)</span>
<span id="cb28-5"><a href="#cb28-5" aria-hidden="true" tabindex="-1"></a>              :map biblio-selection-mode-map</span>
<span id="cb28-6"><a href="#cb28-6" aria-hidden="true" tabindex="-1"></a>              (<span class="st">&quot;e&quot;</span> . ebib-biblio-selection-import)))</span></code></pre></div>
<p>If you now call <code>biblio-lookup</code>, you can use the key <span
class="key"><code>e</code></span> (or any other key you choose, of
course) in Biblio’s selection buffer to import the selected entry into
the current Ebib database.</p>
<p>Additionally, you can use the key <span
class="key"><code>B</code></span> 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.</p>
<p>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 <code>ebib-autogenerate-keys</code>),
Biblio can be configured to do so by setting the option
<code>biblio-bibtex-use-autokey</code>.</p>
<p>Ebib and Biblio both use the functionality of <code>bibtex.el</code>
to generate keys. Refer to the documentation string of the function
<code>bibtex-generate-autokey</code> to find out how to customise this
functionality.</p>
<p>Entries imported through Biblio can also be modified using filter
functions. The relevant user option is
<code>ebib-biblio-import-filters</code>.</p>
<h2 id="multiple-identical-fields">Multiple Identical Fields</h2>
<p>Under normal circumstances, a BibTeX entry only contains one
occurrence of each field. If <code>biblatex</code> 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 <code>biblatex</code> will use the
value of the <em>first</em> occurrence, not the last.) When extra fields
appear more than once in an entry, <code>biblatex</code> does not warn
you, since it ignores those fields anyway. Here, too, Ebib’s standard
behaviour is to ignore all but the last value.</p>
<p>However, some online reference management services “use” this feature
of BibTeX in that they put multiple <code>keywords</code> 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 <code>ebib-allow-identical-fields</code>.</p>
<p>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 (<code>ebib-keywords-separator</code>). 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
<code>keywords</code> fields:</p>
<pre><code>@book{Jones1998,
    author = {Jones, Joan},
    year = {1998},
    ...
    keywords = {sleep},
    keywords = {winter},
    keywords = {hibernation}
}</code></pre>
<p>If you load this entry into Ebib with the option
<code>ebib-allow-identical-fields</code> set, you will get the
following:</p>
<pre><code>@book{Jones1998,
    author = {Jones, Joan},
    year = {1998},
    ...
    keywords = {sleep, winter, hibernation}
}</code></pre>
<h1 id="linking-to-external-resources">Linking to external
resources</h1>
<p>BibTeX entries can contain links to external files, URLs and DOIs.
Ebib offers several facilities to work with these.</p>
<h2 id="viewing-and-importing-files">Viewing and Importing Files</h2>
<p>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 <span class="key"><code>f</code></span> in the index buffer, Ebib
searches the <code>file</code> field for a filename and when it finds
one, calls an appropriate viewer. If you have more than one file in the
<code>file</code> field (separated by
<code>ebib-filename-separator</code>), you are asked which one you want
to open. Alternatively, you can use a prefix argument: <span
class="key"><code>M-2 f</code></span> will open the second file in the
file field.</p>
<p>The file names in the <code>file</code> field do not have to have
full paths. You can set the option <code>ebib-file-search-dirs</code> to
a list of directories that Ebib should search when opening a file from
the <code>file</code> field. Note that Ebib searches only the
directories in this list, not their subdirectories. However, you can
specify a relative path in the <code>file</code> field: if you put
something like <code>a/Abney1987.pdf</code> in the <code>file</code>
field, Ebib searches for the relevant file in a subdirectory
<code>a/</code> of the directories listed in the option
<code>ebib-file-search-dirs</code>. As an extra service, Ebib also
searches for the base filename, i.e., <code>Abney1987</code> in this
particular case.</p>
<p>Ebib can call different external programs depending on the file
extension of the relevant file. The option
<code>ebib-file-associations</code> allows you to specify which programs
to call for which types of files. By default, <code>.pdf</code> and
<code>.ps</code> files are handled, by <code>xpdf</code> and
<code>gv</code>, respectively. You can specify further file types by
their extensions (do not include the dot). The program is searched for
in <code>exec-path</code>, but you can of course specify the full path
to the program.</p>
<p>If you need to pass further command-line options to the executable,
you can do so, but you will need to include a directive <code>%s</code>
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.</p>
<p>If you do not specify any program for a particular extension (or if
you remove the extension from <code>ebib-file-associatons</code>
altogether), Ebib opens the file in Emacs itself, using
<code>find-file</code>. Use this if you want to read pdf files in Emacs,
for example, with <code>doc-view-mode</code> or <a
href="https://github.com/politza/pdf-tools"><code>pdf-tools</code></a>.</p>
<p>If the <code>file</code> field of an entry is empty, pressing <span
class="key"><code>f</code></span> causes Ebib to search for a pdf file
with a name based on the entry key. By default, Ebib just appends
<code>.pdf</code> 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
<code>ebib-name-transform-function</code> 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 <code>.pdf</code>, which is added automatically). Note that you
can use the function <code>ebib-get-field-value</code> to access the
values of the entry’s fields (you need to pass <code>ebib--cur-db</code>
for the <code>db</code> argument).</p>
<p>There are two functions that can help you to attach files to your
database: <code>ebib-download-url</code> and
<code>ebib-import-file</code>. By default, these are not bound to any
keys, but they can of course be called with <span
class="key"><code>M-x</code></span>. The first of these,
<code>ebib-download-url</code> attempts to convert the URL in the
<code>url</code> 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 <code>ebib-name-transform-function</code> to the entry
key and adding <code>.pdf</code> to it.</p>
<p>How a URL should be converted to a URL pointing to the pdf file
depends on several factors, of course. The option
<code>ebib-url-download-transformations</code> is used to decide how to
convert a particular URL. Currently, only three internet archives are
supported: <a href="https://arxiv.org/">arXiv</a>, <a
href="https://ling.auf.net/lingBuzz/">lingBuzz</a> and <a
href="https://www.jstor.org/">JSTOR</a>. Suggestions for other sites are
of course welcome.</p>
<p>The function <code>ebib-import-file</code> 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 <code>ebib-download-url</code>: by applying the function in
<code>ebib-name-transform-function</code> to the entry key. The
extension of the original file is maintained, however, so it doesn’t
just work for pdf files.</p>
<p>The target directory that <code>ebib-download-url</code> and
<code>ebib-import-file</code> use is determined by the user option
<code>ebib-import-target-directory</code>. By default, this points to
the first directory in <code>ebib-file-search-dirs</code>, 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.</p>
<p>Both <code>ebib-download-url</code> and <code>ebib-import-file</code>
add the imported file to the <code>file</code> field. In addition, both
functions come with an abnormal hook,
<code>ebib-import-file-functions</code> and
<code>ebib-url-download-functions</code>, which can be used to run
additional actions when you import a file. The functions in these hooks
are called with two arguments: the key of the current entry, and the
file path of the imported file. (In the functions, you can use the
variable <code>ebib--cur-db</code> to access the current database.) The
functions are called for side-effects, their return values are
ignored.</p>
<h3 class="unlisted unnumbered" id="editing-the-file-field">Editing the
<code>file</code> field</h3>
<p>As mentioned above, editing the <code>file</code> 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 <span class="key"><code>RET</code></span>, Ebib adds the filename to
the <code>file</code> 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 <span
class="key"><code>RET</code></span>. The default separator is
<code>"; "</code> (semicolon-space), but this can be customised (see the
option <code>ebib-filename-separator</code> for details). The advantage
of this method is that you can use <span
class="key"><code>TAB</code></span> completion to complete file
names.</p>
<p>The first directory in the option <code>ebib-file-search-dirs</code>
is used as the starting directory for filename completion when editing
the <code>file</code> field. Note that when completing file names, Ebib
does not take the directories in <code>ebib-file-search-dirs</code> 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
<code>ebib-file-search-dirs</code>, 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 <code>ebib-truncate-file-names</code>: if
unset, file names are always stored as absolute paths.)</p>
<h2 id="calling-a-browser-for-urls-and-dois">Calling a Browser for URLs
and DOIs</h2>
<p>With most scientific literature nowadays being available on-line, it
is common to store URLs and DOIs in a BibTeX database.
<code>Biblatex</code> has standardised fields for this information, for
BibTeX, Ebib adds these fields to each entry.</p>
<p>To open a URL in your default browser, you can press <span
class="key"><code>u</code></span> in the index or entry buffer. Ebib
takes the URL stored in the <code>url</code> 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 <span
class="key"><code>M-2 u</code></span> sends the second URL to your
browser.</p>
<p>It is not even necessary that the relevant field contains
<em>only</em> 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
<code>http://</code> or <code>https://</code> and that does not contain
whitespace or any of the characters <code>" ' ; &lt;</code> or
<code>&gt;</code> as a URL.</p>
<p>Note that the semicolon is included here even though it is actually a
valid character in URLs. This is done for consistency with the
<code>file</code> field, because the semicolon (actually,
semicolon+space) is the standard separator for files in the
<code>file</code> field. This way, you can use the same separator to
distinguish multiple URLs in the <code>url</code> field.</p>
<p>Ebib also regards everything that is enclosed in a LaTeX
<code>\url{...}</code> command as a URL. So if you use <code>;</code> to
separate URLs and then happen to run into a URL that contains a
semicolon, you can enclose it in <code>\url{...}</code> and it will be
recognised properly. Alternatively, you can customise the regular
expression that controls this behaviour. See the option
<code>ebib-url-regexp</code> for details.</p>
<p>By default, Ebib assumes URLs are stored in the <code>url</code>
field. If you have other fields that may contain URLs, you can add them
to the user option <code>ebib-url-fields</code>: URLs in those fields
will then be made clickable and they will be presented as options when
you press <span class="key"><code>u</code></span>.</p>
<p>If the <code>doi</code> field contains a valid DOI, you can send it
to a DOI resolver with the key <span class="key"><code>I</code></span>.
Unlike URLs, there can only be one DOI in the <code>doi</code> field.
The DOI is extracted from it and a resolver URL is prepended
(<code>https://doi.org/</code> by default, customisable as
<code>ebib-doi-resolver</code>) before being sent to the browser. Note
that if the <code>doi</code> field already contains a DOI resolver URL,
it is removed.</p>
<p>Ebib uses the Emacs function <code>browse-url</code> to call the
default browser on the system. If you prefer to use another browser,
however, you can specify this with the option
<code>ebib-browser-Command</code>.</p>
<h1 id="notes-files">Notes files</h1>
<p>Ebib supports the <code>annotation</code> field (or
<code>annote</code> field in BibTeX), but if you prefer to keep notes
outside the <code>.bib</code> file, there is an easy way to do that as
well. When you hit <span class="key"><code>N</code></span> 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,
<span class="key"><code>N</code></span> 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.)</p>
<p>In the entry buffer, the first few lines of the note are shown under
a pseudo-field <code>external note</code>. This is not an actual field
in the <code>.bib</code> file, even though it is displayed as such. (You
can customise this behaviour.)</p>
<p>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.</p>
<p>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 <a
href="#upgrading-from-earlier-ebib-versions">Upgrading from earlier Ebib
versions</a> below for details.</p>
<h2 class="unlisted unnumbered"
id="configuring-files-for-storing-notes">Configuring files for storing
notes</h2>
<p>By default, Ebib saves each note to a separate file in the first
directory listed in <code>ebib-file-search-dirs</code>. Since this is
also the main directory for your <code>.bib</code> files, it is
advisable to use a different directory, which you can do by customising
the option <code>ebib-notes-directory</code>.</p>
<p>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 <code>ebib-notes-storage</code> and set it to
<code>multiple-notes-per-file</code>. Having done this, you can add the
files you wish to use for notes to <code>ebib-notes-locations</code>.
You can also add directories to this list: all Org files in those
directories are considered notes files. (This does not mean that they
<em>must</em> contain notes. Ebib searches all Org files in
<code>ebib-notes-locations</code> for notes, but it won’t complain if it
doesn’t find any, or if any of the files contain more than just
notes.)</p>
<p>The procedure for creating a new note depends on the setting of
<code>ebib-notes-storage</code>. If this option is set to
<code>one-note-per-file</code> (the default), Ebib creates a new note
file in <code>ebib-notes-directory</code> 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
<code>ebib-notes-name-transform-function</code> to it, or, if this is
not set, the function in <code>ebib-name-transform-function</code>. This
means that you can configure the name of the new note file to whatever
you prefer. (See <a href="#viewing-and-importing-files">Viewing and
Importing Files</a> 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 <code>ebib-name-transform-function</code> to be
applied, you can set <code>ebib-notes-name-transform-function</code> to
<code>identity</code>.)</p>
<p>If <code>ebib-notes-storage</code> is set to
<code>multiple-notes-per-files</code>, 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 <code>ebib-notes-locations</code> as
candidates. If you don’t want to be asked, you can set the option
<code>ebib-notes-default-file</code>: new notes are then automatically
stored to that file. You can subsequently use Org to move notes around
or archive them.</p>
<p>New notes are created based on a template
(<code>ebib-note-template</code>). 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 <code>:PROPERTIES:</code> block
containing a custom ID for the entry, which consists of the entry key.
If <code>ebib-notes-storage</code> is set to
<code>multiple-notes-per-file</code>, this custom ID is essential,
because it is what Ebib uses to find the note. (If you use
<code>one-file-per-note</code>, the file name is used to identify an
entry, even though the custom ID is still included.)</p>
<p>The template can of course be customised. Details are discussed
below.</p>
<h2 class="unlisted unnumbered" id="hooks">Hooks</h2>
<p>If <code>ebib-notes-storage</code> is set to
<code>multiple-notes-per-file</code>, 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.</p>
<p>When an existing note is displayed, the hook
<code>ebib-notes-open-note-after-hook</code> is run. By default, this
contains two functions: <code>org-back-to-header</code>, which puts
point at the start of the note, and <code>org-narrow-to-subtree</code>,
which narrows the notes buffer to just the note you’re viewing.</p>
<p>When a new note is created, the hook
<code>ebib-notes-new-note-hook</code> is run. By default, this contains
the function <code>org-narrow-to-subtree</code>. Point is not positioned
at the heading, but after the title and the <code>:PROPERTIES:</code>
block, so that you can start typing right away. (The position of point
can be customised in the template.)</p>
<p>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 <code>ebib-notes-search-note-before-hook</code>, which is run every
time Ebib searches a note and by default contains the function
<code>widen</code>, so that the entire buffer is searched.</p>
<p>All three hooks are customisable. For example, if you prefer not to
narrow the buffer, simply remove the corresponding functions from the
hooks.</p>
<h2 class="unlisted unnumbered"
id="upgrading-from-earlier-ebib-versions">Upgrading from earlier Ebib
versions</h2>
<p>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.</p>
<p>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
<code>ebib-notes-directory</code> has not changed.</p>
<p>If, however, you have been storing your notes in a single file, you
will need to set the user option <code>ebib-notes-storage</code> to
<code>multiple-notes-per-file</code>. Furthermore, the option
<code>ebib-notes-file</code> has been deprecated in favour of
<code>ebib-notes-default-file</code>. Although
<code>ebib-notes-file</code> 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 <code>ebib-notes-locations</code>, which allows you to
have more than one Org file for your notes.</p>
<h2 class="unlisted unnumbered"
id="customising-the-notes-file-format">Customising the notes file
format</h2>
<p>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 <code>:PROPERTIES:</code> block
containing a <code>Custom_id:</code>. This can all be customised
(although it is important to keep the <code>Custom_id:</code> property.)
To see how this can be done, it is easiest to look at the default
template first:</p>
<pre><code>&quot;* %T
:PROPERTIES:
%K
:END:
%%?
&quot;</code></pre>
<p>This template contains two format specifiers: <code>%K</code> and
<code>%T</code>. <code>%K</code> is replaced with the key of the entry
prepended with the string <code>"Custom_id: "</code> in order to create
an Org property. The <code>%T</code> 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 <code>"%%?"</code>, which indicates the position of
the cursor when a new note is created. (For backward compatibility, the
string <code>"&gt;|&lt;"</code> can also be used to indicate the cursor
position, although this does not work if you use
<code>org-capture</code> to record new notes.)</p>
<p>To change the template, you must customise the option
<code>ebib-notes-template</code>. If you use Org for your notes and keep
your notes in a single file, the template <strong>must</strong> contain
a <code>:PROPERTIES:</code> block with the <code>%K</code> 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 <code>%K</code> specifier <strong>must</strong>
occur on a line of its own in the template.</p>
<p>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 <code>:PROPERTIES:</code>
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.)</p>
<p>There are a few more specifiers that may be used in the template:
<code>%F</code> creates an Org link to the file in the BibTeX entry’s
<code>file</code> field, <code>%D</code> creates an Org link to the DOI
in the entry’s <code>doi</code> field, and <code>%U</code> an Org link
to the entry’s <code>url</code> field. There is also a <code>%L</code>
specifier, which creates an Org link to the entry’s file, its DOI, or
its URL, whichever is found first.</p>
<p>It is possible to change the strings that the specifiers produce, or
to add new specifiers, by customising the option
<code>ebib-notes-template-specifiers</code>. This option contains pairs
of characters and functions. Each function takes two arguments,
<code>key</code> and <code>db</code>, 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 <code>ebib-notes-template-specifiers</code> to
use it.</p>
<p>When the specifier functions are called, the <code>key</code>
argument is set to the key of the current entry and the <code>db</code>
argument to the current database. With these arguments, it is possible
to, e.g., retrieve the value of a specific field in the entry:</p>
<pre><code>(ebib-get-field-value &lt;field&gt; key db &#39;noerror &#39;unbraced &#39;xref &#39;expand-strings &#39;org)</code></pre>
<p>where <code>&lt;field&gt;</code> is the field as a (case-insensitive)
string whose value is to be retrieved. The argument
<code>'noerror</code> is necessary to avoid triggering an error if
<code>field</code> does not exist in the entry. The other arguments
determine how the field value is returned. See the doc string of
<code>ebib-get-field-value</code> for details.</p>
<p>Instead of a function, you may also provide a variable. The
variable’s value is then used to replace the specifier.</p>
<h2 class="unlisted unnumbered" id="displaying-notes">Displaying
notes</h2>
<p>If an entry has an external note, the first few lines are shown in
the entry buffer as a field called <code>external note</code>. The
number of lines to show can be customised with the option
<code>ebib-notes-display-max-lines</code>, 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
<code>ebib-notes-show-note-method</code>. 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.)</p>
<p>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 <a href="#window-management">Window Management</a> for details),
because that is the only window layout that ensures that the note can be
displayed without getting in the way.</p>
<h2 class="unlisted unnumbered" id="using-markdown-for-notes">Using
Markdown for notes</h2>
<p>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 <code>:PROPERTIES:</code> block, but there is no
similar ready-made option for other formats.</p>
<p>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:</p>
<ul>
<li><p><code>ebib-note-file-extension</code>: 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.</p></li>
<li><p><code>ebib-notes-directory</code>: 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.</p></li>
<li><p><code>ebib-notes-name-transform-function</code>: 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 <code>ebib-name-transform-function</code> will
be used instead. If you don’t customise that option either, the entry
key will be used as the file name.</p></li>
<li><p><code>ebib-notes-template</code>: 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 <code>%K</code> specifier
does not apply, because the note is identified based on the file
name.</p></li>
<li><p><code>ebib-notes-template-specifiers</code>: create functions for
the specifiers that you use in <code>ebib-notes-template</code> and
customise this option to use them. Note that if you use Markdown, the
relevant functions are already defined. They are named with
<code>markdown</code> instead of <code>org</code>, so for the
<code>%T</code> specifier, the Markdown function is
<code>ebib-create-markdown-title</code>, etc.</p></li>
<li><p><code>ebib-notes-show-note-method</code>: 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
<code>all</code>. If you want to keep the default value
(<code>top-lines</code>), you need to customise
<code>ebib-notes-extract-text-function</code>, which would involve
writing a function that extracts the top N lines of a note.</p></li>
</ul>
<p>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 <code>ebib-create-markdown-identifier</code>, which creates
a unique identifier by prepending <code>ID:</code> to the entry
key.)</p>
<p>Second, you will probably need to customise the hooks
<code>ebib-notes-search-note-before-hook</code>,
<code>ebib-notes-open-note-after-hook</code> and
<code>ebib-notes-new-note-hook</code> discussed above. They are needed
to ensure that Ebib positions point correctly when creating or editing a
note.</p>
<h2 class="unlisted unnumbered"
id="using-org-capture-to-record-notes">Using <code>org-capture</code> to
record notes</h2>
<p>Instead of using Ebib’s own system to record notes, you can also use
<code>org-capture</code> 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.</p>
<p>Note that <code>org-capture</code> 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.</p>
<p>When using <code>org-capture</code>, you’ll most likely want to set
<code>ebib-notes-storage</code> to <code>multiple-notes-per-file</code>.
(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 <code>ebib-notes-locations</code>
to the files and/or directories you use to store notes. There is no
point but also no harm in setting <code>ebib-notes-default-file</code>;
this setting is ignored when you create notes through
<code>org-capture</code> but Ebib still uses it to search for existing
notes.</p>
<p>In order to use <code>org-capture</code> for creating notes, you need
to set <code>ebib-notes-use-org-capture</code> and you need to add an
entry to <code>org-capture-templates</code> 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.</p>
<p>The following is an example entry for
<code>org-capture-templates</code>:</p>
<div class="sourceCode" id="cb33"><pre
class="sourceCode lisp"><code class="sourceCode commonlisp"><span id="cb33-1"><a href="#cb33-1" aria-hidden="true" tabindex="-1"></a>(<span class="st">&quot;e&quot;</span></span>
<span id="cb33-2"><a href="#cb33-2" aria-hidden="true" tabindex="-1"></a> <span class="st">&quot;BibTeX note&quot;</span></span>
<span id="cb33-3"><a href="#cb33-3" aria-hidden="true" tabindex="-1"></a> entry</span>
<span id="cb33-4"><a href="#cb33-4" aria-hidden="true" tabindex="-1"></a> (file+headline <span class="st">&quot;~/Work/Bibtex/Bib_Notes.org&quot;</span> <span class="st">&quot;Bibliography Notes&quot;</span>)</span>
<span id="cb33-5"><a href="#cb33-5" aria-hidden="true" tabindex="-1"></a> (<span class="kw">function</span> ebib-notes-create-org-template))</span></code></pre></div>
<p>Because you are free to set the type and target to anything that
<code>org-capture</code> accepts, you have more control over the way a
note is created and where it is stored.</p>
<p>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 <code>ebib-notes-create-org-template</code>.
This function takes <code>ebib-notes-template</code> and converts it
into a template that <code>org-capture</code> can use.</p>
<p>The <code>%</code>-directives in <code>ebib-notes-template</code> are
interpreted by Ebib, not by the Org capture mechanism. It is therefore
still essential that it contains a <code>%K</code> directive to create
an identifier that Ebib can find.</p>
<p>It is possible to add <code>org-capture</code> directives to the
template, though. To do this, put an additional <code>%</code> before
the directive. For example, <code>org-capture</code> can add a time
stamp with <code>%t</code>. In order to add a time stamp to a
bibliography note, write <code>%%t</code>:</p>
<div class="sourceCode" id="cb34"><pre
class="sourceCode lisp"><code class="sourceCode commonlisp"><span id="cb34-1"><a href="#cb34-1" aria-hidden="true" tabindex="-1"></a>(<span class="kw">setq</span> ebib-notes-template</span>
<span id="cb34-2"><a href="#cb34-2" aria-hidden="true" tabindex="-1"></a>      <span class="st">&quot;* %T</span><span class="sc">\n</span><span class="st">:PROPERTIES:</span><span class="sc">\n</span><span class="st">%K</span><span class="sc">\n</span><span class="st">:END:</span><span class="sc">\n</span><span class="st">%%t</span><span class="sc">\n</span><span class="st">%%?</span><span class="sc">\n</span><span class="st">&quot;</span>)</span></code></pre></div>
<p><code>ebib-notes-create-org-template</code> strips off one
<code>%</code> and passes the result on to <code>org-capture</code>,
which then sees <code>%t</code> and replaces it with a time stamp. (Note
that this is the reason why the cursor position is indicated with
<code>%%?</code>: <code>ebib-notes-create-org-template</code> converts
it to <code>%?</code>, which is used by <code>org-capture</code> to
position the cursor.)</p>
<p>Note that this <code>org-capture-templates</code> entry should only
be selected when creating a note from within Ebib. The function
<code>ebib-notes-create-org-template</code> 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 <code>org-capture</code> from somewhere
else. You can do this by configuring the option
<code>org-capture-template-contexts</code>:</p>
<div class="sourceCode" id="cb35"><pre
class="sourceCode lisp"><code class="sourceCode commonlisp"><span id="cb35-1"><a href="#cb35-1" aria-hidden="true" tabindex="-1"></a>(<span class="kw">setq</span> org-capture-template-contexts</span>
<span id="cb35-2"><a href="#cb35-2" aria-hidden="true" tabindex="-1"></a>      &#39;((<span class="st">&quot;e&quot;</span> ((in-mode ebib-index-mode)))))</span></code></pre></div>
<div class="line-block"></div>
<p>The <code>"e"</code> is the key that you’ve chosen for your template.
This setting ensures that the <code>org-capture</code> template
associated with the key <code>"e"</code> is only shown when
<code>org-capture</code> is called from a buffer with major mode
<code>ebib-index-mode</code>, which is Ebib’s index buffer.</p>
<p>You can also bypass the <code>org-capture</code> selection buffer
altogether and open an <code>org-capture</code> buffer immediately with
the appropriate template. To do this, set
<code>ebib-notes-use-org-capture</code> to the key of the template that
you use for Ebib notes (<code>"e"</code> in the current example):</p>
<div class="sourceCode" id="cb36"><pre
class="sourceCode lisp"><code class="sourceCode commonlisp"><span id="cb36-1"><a href="#cb36-1" aria-hidden="true" tabindex="-1"></a>(<span class="kw">setq</span> ebib-notes-use-org-capture <span class="st">&quot;e&quot;</span>)</span></code></pre></div>
<p>This will cause <code>org-capture</code> to bypass the selection
buffer and immediately put you in the edit buffer with the relevant
template.</p>
<p>Alternatively, it is also possible to set up more than one
<code>org-capture</code> 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
<code>ebib-notes-create-org-template</code> to create the actual
template, however. <code>org-capture</code> itself does not know about
Ebib’s databases and cannot access them. This is what
<code>ebib-notes-create-org-template</code> is for.</p>
<p>If you wish to associate each <code>org-capture</code> entry with a
different template, you can do so by setting
<code>ebib-notes-template</code> to a list. Each element of the list
should itself be a list of two items, the key of the relevant template
in <code>org-capture-templates</code> and the template to use.</p>
<p>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 <code>ebib-notes-template-specifiers</code> and add
new <code>%</code>-forms, as discussed above.)</p>
<p>Note that Ebib also provides an Ebib-friendly command to call
<code>org-capture</code> directly. This command,
<code>ebib-org-capture</code> (not bound to any key by default), takes
the same arguments as <code>org-capture</code> and can be used in the
same way. It makes sure that <code>ebib-notes-create-org-template</code>
can find the current entry and then calls <code>org-capture</code>.</p>
<h1 id="managing-a-reading-list">Managing a reading list</h1>
<p>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
<code>ebib-reading-list-file</code> 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 <span class="key"><code>R a</code></span>. The
mode line of the entry buffer will show <code>[R]</code> to indicate
that the current entry is on the reading list.</p>
<p>A reading list is simply an Org file with one entry (i.e., heading)
per item. Each entry is marked with <code>TODO</code>, so that the items
can be included in the Org agenda. (If you prefer to use another todo
state, you can customise the option
<code>ebib-reading-list-todo-marker</code>.) You can mark an entry as
done from within Ebib with the key <span
class="key"><code>R d</code></span>. This will change the todo state of
the item to <code>DONE</code> (customisable through the option
<code>ebib-reading-list-done-marker</code>). With <span
class="key"><code>R v</code></span> you can view the reading list.</p>
<p>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 <code>ebib-reading-list-template</code>, and the
specifiers that can be used in this template are in
<code>ebib-reading-list-template-specifiers</code>. Most of the
specifiers are the same as for the notes template, with the exception of
<code>%K</code>. For the reading list, this specifier uses a different
function, which adds a prefix <code>reading_</code> 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
<code>%M</code>, which is replaced with the todo marker specified in the
option <code>ebib-reading-list-todo-marker</code> (by default
<code>TODO</code>).</p>
<p>Most aspects of the reading list can be customised. First, the option
<code>ebib-reading-list-add-item-function</code> 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,
<code>ebib-reading-list-remove-item-function</code> holds the function
that marks a reading list item as done. By default, it is set to
<code>ebib-reading-list-mark-item-as-done</code>, which simply changes
the todo state of the item to <code>DONE</code>, but you can set it to a
function that does something else (for example, completely removing the
entry from the list).</p>
<p>The option <code>ebib-reading-list-item-active-function</code> holds
a function that should return <code>t</code> 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
<code>ebib-reading-list-todo-marker</code>.</p>
<p>Lastly, there are two hooks,
<code>ebib-reading-list-new-item-hook</code> and
<code>ebib-reading-list-remove-item-hook</code>. 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 <code>ebib-reading-list-remove-item-function</code>
(also before saving the buffer). By default, these hooks are empty.</p>
<h1 id="managing-keywords">Managing Keywords</h1>
<p>Biblatex supports a <code>keywords</code> field, which can contain a
(comma-separated) list of keywords for an entry. BibTeX does not support
this field directly, but Ebib includes a <code>keywords</code> field in
the extra fields for BibTeX entries. Ebib offers some special facilities
for editing this field.</p>
<p>Ebib keeps a list of keywords used in your database(s) and offers
these for completion when you edit the <code>keywords</code> field. You
can enter a keyword and accept it with <span
class="key"><code>RET</code></span>, after which you will be asked for
the next keyword. Just hitting <span class="key"><code>RET</code></span>
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 <code>keywords</code> 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.</p>
<p>If you need to edit a keyword or remove one from the list, you need
to edit the <code>keywords</code> field directly. To do this, use a
prefix argument: <span class="key"><code>C-u RET</code></span> instead
of just <span class="key"><code>RET</code></span> to edit the field.
Note, though, that this does not update the completion list.</p>
<p>The keywords completion list is composed of the keywords in all the
<code>.bib</code> files you have open and is available in every
database. If you open another <code>.bib</code> 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.)</p>
<h2 class="unlisted unnumbered"
id="using-a-canonical-keywords-list">Using a Canonical Keywords
List</h2>
<p>By default, the completion list does not contain keywords that are
not used in any of your <code>.bib</code> 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
<code>.bib</code> file or not, you can set the option
<code>ebib-keywords</code>. 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.</p>
<p>If you set this option, keywords in a database that are not in the
canonical list are displayed in Ebib’s warning face
(<code>ebib-warning-face</code>). You can add them to the canonical list
with the key sequence <span class="key"><code>K s</code></span>, which
will ask you for the keyword to add, or with <span
class="key"><code>K c</code></span>, which adds all keywords of the
current entry to the canonical list. You can also remove all keywords
from the <code>keywords</code> field that are not in the list of
canonical keywords with the key sequence <span
class="key"><code>K p</code></span>.</p>
<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
<code>keywords</code> 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 <code>ebib-keywords-add-new-to-canonical</code>.</p>
<p>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 <code>ebib-keywords-save-on-exit</code> to <code>always</code>.
Note that you can also save the list manually with the key sequence
<span class="key"><code>K S</code></span> (capital <span
class="key"><code>K</code></span>, capital <span
class="key"><code>S</code></span>).</p>
<p>If you haven’t configured a list of canonical keywords, the key
sequence <span class="key"><code>K S</code></span> creates one from the
keywords used in your open <code>.bib</code> files. The list is then
saved to your customisation file (usually
<code>~/.emacs.d/init.el</code>). 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 <code>ebib-keywords</code> yourself.</p>
<h1 id="window-management">Window Management</h1>
<p>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 <code>ebib-windows</code>, and allow you
to specify two alternative ways to deal with Ebib windows. The main
layout option is simply called <code>ebib-layout</code> 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.</p>
<p>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 <code>ebib-width</code>, 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 <span class="key"><code>z</code></span> does not hide the
Ebib buffers, it simply switches to a non-Ebib window in the same frame.
You can use (uppercase) <span class="key"><code>Z</code></span> 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.</p>
<p>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.</p>
<p>The entry buffer is also displayed if you press <span
class="key"><code>RET</code></span>. 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.</p>
<p>In this case, too, the key <span class="key"><code>z</code></span>
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) <span class="key"><code>Z</code></span>.</p>
<p>If you set Ebib’s layout to display only the index buffer on startup,
you can additionally set the option
<code>ebib-popup-entry-window</code>. 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 <code>display-buffer-popup-window</code> to
create a new window (which is destroyed again when you leave the entry
buffer).</p>
<p>Further relevant options are <code>ebib-window-vertical-split</code>,
which displays the index buffer to the left of the frame rather than at
the top, and <code>ebib-index-window-size</code>, 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.)</p>
<h1 id="copying-entries-to-the-kill-ring">Copying Entries to the Kill
Ring</h1>
<p>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 (<span
class="key"><code>C k</code></span>; note that this is capital <span
class="key"><code>C</code></span> followed by <span
class="key"><code>k</code></span>, <em>not</em> <span
class="key"><code>C-k</code></span>!) the entire BibTeX entry (<span
class="key"><code>C e</code></span>), a full reference as would appear
in a list of references (<span class="key"><code>C r</code></span>) or a
citation, by default of the Author-Year type (<span
class="key"><code>C c</code></span>).</p>
<p>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
<code>ebib-reference-templates</code> and
<code>ebib-citation-template</code>. (The latter should not be confused
with <code>ebib-citation-commands</code>, which defines templates for
inserting citation commands into a LaTeX / Markdown / etc. buffer.)</p>
<p>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:</p>
<pre><code>&quot;{Author} ({Year})&quot;</code></pre>
<p>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
<code>"{author} ({year})."</code>)</p>
<p>Alternative fields can be separated by a pipe bar <code>|</code>:</p>
<pre><code>&quot;{Author|Editor} ({Date|Year})&quot;</code></pre>
<p>This template uses the <code>Author</code> field unless it’s empty,
in which case the <code>Editor</code> field is used. Similarly for the
year: first the contents of the <code>Date</code> field is checked. The
<code>Year</code> field is used if the <code>Date</code> field is
empty.</p>
<p>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 <code>Doi</code> or <code>Url</code> field:</p>
<pre><code>&quot;{Author|Editor} ({Date|Year}). {\&quot;Title\&quot;}. {Publisher}. {Doi|Url.}&quot;</code></pre>
<p>If the <code>Doi</code> and <code>Url</code> fields are both empty,
the directive is simply ignored.</p>
<p>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 <code>{Doi|Url.}</code> directive in the previous example contains a
full stop, which is only included in the reference if the
<code>Doi</code> or <code>Url</code> field is present.</p>
<p>The contents of the fields are used literally, with two exceptions:
the <code>Date</code> 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 <code>Title</code> field is
stripped of LaTeX markup. (See the user option
<code>ebib-TeX-markup-replace-alist</code> if you want to customise what
exactly is stripped.)</p>
<h1 id="printing-the-database">Printing the Database</h1>
<p>Sometimes it may be useful to have a <code>.pdf</code> 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.</p>
<p>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.</p>
<p>If you print your entries as a bibliography, Ebib creates a simple
LaTeX document that essentially contains a <code>\nocite{*}</code>
command followed by a <code>\printbibliography</code> command, adding a
<code>\addbibresource</code> 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.)</p>
<p>If you choose to print as index cards, Ebib also creates a LaTeX
file. However, instead of simply providing a <code>\nocite{*}</code>
command, this file contains a <code>tabular</code> environment for each
entry in the database listing all the fields of that entry and their
values.</p>
<p>The entries are separated by a <code>\bigskip</code>, but if you set
the option <code>ebib-print-newpage</code> in the customisation buffer
(or in the Print menu), the entries are separated by a
<code>\newpage</code>, 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 <code>geometry</code>
package as well).</p>
<p>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
<code>ebib-print-multiline</code> 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 <span class="key"><code>&amp;</code></span> that are illegal in
LaTeX. (Or, alternatively, use LaTeX code in your multiline fields.)</p>
<p>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.</p>
<p>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!</p>
<p>A better way to tell Ebib which file to use is to set the option
<code>ebib-print-tempfile</code> 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.</p>
<p>Note that both print options operate on all entries of the database
or on the selected entries.</p>
<p>The option <code>ebib-print-preamble</code> and
<code>ebib-latex-preamble</code> allow you to customise the preamble of
the LaTeX file that is created.</p>
<h1 id="customisation">Customisation</h1>
<p>Ebib can be customised through Emacs’ standard customisation
interface. The relevant customisation group is (obviously) called
<code>ebib</code>, which has five subgroups: <code>ebib-faces</code>,
<code>ebib-filters</code>, <code>ebib-notes</code>, and
<code>ebib-keywords</code>, whose functions should be obvious, and
<code>ebib-windows</code>, 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 <span
class="key"><code>M-x customize-group RET ebib RET</code></span>, or by
using the menu «Ebib | Options | Customize Ebib».</p>
<p>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.</p>
<p>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.</p>
<p>You can also set Ebib options in a <code>.dir-locals.el</code> 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 <span class="key"><code>M-x ebib</code></span>, a
<code>.dir-locals.el</code> is not taken into account.</p>
<h2 class="unlisted unnumbered" id="modifying-key-bindings">Modifying
Key Bindings</h2>
<p>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 <code>ebib-index-mode-map</code>,
<code>ebib-entry-mode-map</code>, <code>ebib-strings-mode-map</code> for
the index, entry, and strings buffer, and
<code>ebib-multiline-mode-map</code>, which contains the key bindings in
multiline edit buffers.</p>
<p>In addition, <code>ebib-search-map</code> is a transient key map that
is activated when <code>ebib-search</code> is called, and
<code>ebib-filters-map</code>, <code>ebib-keywords-map</code> and
<code>ebib-reading-list-map</code> are key maps (set up using
<code>define-prefix-command</code>) that contain bindings for filters,
keywords and the reading list, respectively. Finally, there is
<code>ebib-log-mode-map</code> which is active in Ebib’s log buffer.</p>
</body>
</html>