summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSean Whitton <spwhitton@spwhitton.name>2019-01-12 09:41:35 -0700
committerSean Whitton <spwhitton@spwhitton.name>2019-01-12 09:41:35 -0700
commit3b97525a014b6b4090db0739f0a41b40380bca73 (patch)
tree8ee72931e11108644ebe1824d87c58c4f1d9e30e
parent844c27c994f333e2427dfec8c5d0374e7d9ca929 (diff)
parent5b7759f0a19af3d713218b2c3e4b8aacd8830b75 (diff)
Merge tag '2.15.4'
-rw-r--r--.dir-locals.el2
-rw-r--r--README.md2
-rw-r--r--Vagrantfile7
-rw-r--r--docs/.index.text.html.pandoc4
-rw-r--r--docs/ebib-manual.html297
-rw-r--r--docs/images/Search-view.pngbin139470 -> 198939 bytes
-rw-r--r--docs/images/tn-Search-view.pngbin8676 -> 10138 bytes
-rw-r--r--docs/index.html28
-rw-r--r--docs/index.text2
-rw-r--r--ebib-db.el236
-rw-r--r--ebib-filters.el15
-rw-r--r--ebib-keywords.el7
-rw-r--r--ebib-notes.el11
-rw-r--r--ebib-reading-list.el4
-rw-r--r--ebib-utils.el398
-rw-r--r--ebib.el909
-rw-r--r--ebib.info987
-rw-r--r--manual/ebib.text245
-rw-r--r--manual/older-news.text55
19 files changed, 1647 insertions, 1562 deletions
diff --git a/.dir-locals.el b/.dir-locals.el
index 4a240c0..10a6a18 100644
--- a/.dir-locals.el
+++ b/.dir-locals.el
@@ -2,5 +2,5 @@
;;; For more information see (info "(emacs) Directory Variables")
((emacs-lisp-mode
+ (eval . (nameless-mode 1))
(nameless-current-name . "ebib")))
-
diff --git a/README.md b/README.md
index d1c79f9..d2c4b79 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
Ebib
-(c) 2003-2018 Joost Kremers
+(c) 2003-2019 Joost Kremers
Ebib is a BibTeX database manager that runs in GNU Emacs. With Ebib, you
can create and manage `.bib`-files, all within Emacs. It supports `@string` and
diff --git a/Vagrantfile b/Vagrantfile
index 416b642..5fe0ff6 100644
--- a/Vagrantfile
+++ b/Vagrantfile
@@ -7,7 +7,7 @@ Vagrant.configure("2") do |config|
# please see the online documentation at vagrantup.com.
# Every Vagrant virtual environment requires a box to build off of.
- config.vm.box = "ubuntu/trusty64"
+ config.vm.box = "ubuntu/bionic64"
# The url from where the 'config.vm.box' box will be fetched if it
# doesn't already exist on the user's system.
@@ -32,7 +32,10 @@ Vagrant.configure("2") do |config|
# the path on the guest to mount the folder. And the optional third
# argument is a set of non-required options.
# config.vm.synced_folder "../data", "/vagrant_data"
- config.vm.synced_folder "../../tmp", "/home/vagrant/tmp"
+ # config.vm.synced_folder ".", "/home/src/ebib"
+
+ # Avoiding https://superuser.com/questions/1160025/how-to-solve-ttyname-failed-inappropriate-ioctl-for-device-in-vagrant/1277604#1277604
+ config.ssh.shell="bash"
# Provider-specific configuration so you can fine-tune various
# backing providers for Vagrant. These expose provider-specific options.
diff --git a/docs/.index.text.html.pandoc b/docs/.index.text.html.pandoc
index 34aa688..6e12b5a 100644
--- a/docs/.index.text.html.pandoc
+++ b/docs/.index.text.html.pandoc
@@ -1,7 +1,7 @@
;; -*- mode: emacs-lisp -*-
;; pandoc-mode local settings file for index.text
-;; saved on 2016.02.22 13:56
+;; saved on 2019.01.07 15:16
((latexmathml)
(mathml)
@@ -43,7 +43,7 @@
(slide-level)
(reference-odt)
(reference-docx)
- (standalone)
+ (standalone . t)
(template)
(variable)
(dpi)
diff --git a/docs/ebib-manual.html b/docs/ebib-manual.html
index 1f70503..accabdb 100644
--- a/docs/ebib-manual.html
+++ b/docs/ebib-manual.html
@@ -30,7 +30,7 @@ a.sourceLine { text-indent: -1em; padding-left: 1em; }
pre.numberSource a.sourceLine
{ position: relative; left: -4em; }
pre.numberSource a.sourceLine::before
- { content: attr(data-line-number);
+ { content: attr(title);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; pointer-events: all; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
@@ -81,32 +81,26 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<![endif]-->
</head>
<body>
-<header>
+<header id="title-block-header">
<h1 class="title">Ebib Manual</h1>
<p class="author">Joost Kremers</p>
</header>
<nav id="TOC">
<ul>
<li><a href="#news">News</a><ul>
+<li><a href="#version-2.15-january-2019">Version 2.15, January 2019</a></li>
+<li><a href="#version-2.14-december-2018">Version 2.14, December 2018</a></li>
+<li><a href="#version-2.13-november-2018">Version 2.13, November 2018</a></li>
+<li><a href="#version-2.12.3-november-2018">Version 2.12.3, November 2018</a></li>
+<li><a href="#version-2.12.2-november-2018">Version 2.12.2, November 2018</a></li>
<li><a href="#version-2.12-august-2018">Version 2.12, August 2018</a></li>
<li><a href="#version-2.11.12-july-2018">Version 2.11.12, July 2018</a></li>
-<li><a href="#version-2.11-january-2017">Version 2.11, January 2017</a></li>
-<li><a href="#version-2.10-january-2017">Version 2.10, January 2017</a></li>
-<li><a href="#version-2.9-january-2017">Version 2.9, January 2017</a></li>
-<li><a href="#december-2016">19 December 2016</a></li>
-<li><a href="#december-2016-1">7 December 2016</a></li>
-<li><a href="#december-2016-2">5 December 2016</a></li>
-<li><a href="#november-2016">7 November 2016</a></li>
-<li><a href="#version-2.8-26-october-2016">Version 2.8, 26 October 2016</a></li>
-<li><a href="#version-2.7-22-september-2016">Version 2.7, 22 September 2016</a></li>
-<li><a href="#version-2.6.3-31-august-2016">Version 2.6.3, 31 August 2016</a></li>
</ul></li>
<li><a href="#installation">Installation</a><ul>
<li><a href="#package-manager">Package manager</a></li>
<li><a href="#debian-and-ubuntu">Debian and Ubuntu</a></li>
<li><a href="#manual-installation">Manual installation</a></li>
<li><a href="#starting-ebib">Starting Ebib</a></li>
-<li><a href="#upgrading-from-ebib-1.x">Upgrading from Ebib 1.x</a></li>
</ul></li>
<li><a href="#getting-started">Getting Started</a><ul>
<li><a href="#opening-a-.bib-file">Opening a <code>.bib</code> File</a></li>
@@ -174,71 +168,44 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
</ul>
</nav>
<article>
-<p>Ebib is a program with which you can manage BibTeX and BibLateX database files without having to edit the raw <code>.bib</code> files. It runs in GNU/Emacs, version 24.3 or higher. (Users of GNU/Emacs 23.1 and up can install Ebib 1.x, which is available in the pasture branch on Github or as a zip or tar archive on Github’s releases page.)</p>
+<p>Ebib is a program with which you can manage BibTeX and BibLateX database files without having to edit the raw <code>.bib</code> files. It runs in GNU/Emacs, version 25.3 or higher.</p>
<p>It should be noted that Ebib is <em>not</em> a minor or major mode for editing BibTeX files. It is a program in itself, which just happens to make use of Emacs as a working environment, in the same way that for example Gnus is.</p>
<h1 id="news">News</h1>
-<h2 id="version-2.12-august-2018">Version 2.12, August 2018</h2>
-<ul>
-<li>Add an option to specify the default sort field and direction. It is no longer necessary to set the desired sort field as the first column in the index buffer, but Ebib still defaults to this if the default sort field and direction are not set explicitly.</li>
-</ul>
-<h2 id="version-2.11.12-july-2018">Version 2.11.12, July 2018</h2>
-<ul>
-<li>Use BibLaTeX’s <code>Date</code> field, if present, for displaying the year.</li>
-<li>Check for changed files on disk when saving all databases, not just when saving the current database.</li>
-<li>Improve handling of multiple databases: <code>crossref</code> entries can now occur in other open databases as well, and searches with <code>/</code> can be continued in other databases.</li>
-<li>Autogenerating keys is now on by default.</li>
-</ul>
-<h2 id="version-2.11-january-2017">Version 2.11, January 2017</h2>
-<ul>
-<li>Update for <code>parsebib</code> v. 2.3.</li>
-</ul>
-<h2 id="version-2.10-january-2017">Version 2.10, January 2017</h2>
+<h2 id="version-2.15-january-2019">Version 2.15, January 2019</h2>
<ul>
-<li>Improved index column display.</li>
+<li>Multiline field values can now be displayed in the entry buffer.</li>
+<li>Do not warn about aliased entry types when loading BibLaTeX files.</li>
+<li>The abstract field is now treated as a multiline field by default, similar to the annote/annotation field.</li>
+<li>Bug fix: <code>ebib-show-annotation</code> (bound to <code>A</code>) shows the contents of the annote field in BibTeX databases, not the annotation field (which is BibLaTeX-specific).</li>
</ul>
-<h2 id="version-2.9-january-2017">Version 2.9, January 2017</h2>
+<h2 id="version-2.14-december-2018">Version 2.14, December 2018</h2>
<ul>
-<li>Allow <code>%s</code> in the program strings in <code>ebib-file-associations</code>, making it possible to pass command line arguments to the program being called.</li>
+<li>Change the user interface of the export functions. Calling one of the export functions now exports to another database. The user is asked to specify the database, enabling completion on the database names. To export to a file, the export functions have to be called with a prefix argument.</li>
+<li>Bug fix: Handle overwriting the local BibTeX dialect correctly.</li>
+<li>Bug fix: Add braces to the crossref field.</li>
</ul>
-<h2 id="december-2016">19 December 2016</h2>
+<h2 id="version-2.13-november-2018">Version 2.13, November 2018</h2>
<ul>
-<li>Remove support for a separate rc file for Ebib. User configuration should be moved to Emacs’ <code>init.el</code> file. To keep Ebib customisation in a separate file, simply load it from <code>init.el</code>.</li>
-<li>The macro <code>ebib-key</code> has also been removed. Simply use <code>define-key</code> or any other key binding mechanism to define keys for Ebib. See the section <a href="#modifying-key-bindings">Modifying Key Bindings</a> for details.</li>
+<li>Use a separate index buffer for each open <code>.bib</code> file. Filling the index buffer can be slow for large <code>.bib</code> files, because of the need to calculate the tabulated columns.</li>
</ul>
-<h2 id="december-2016-1">7 December 2016</h2>
+<h2 id="version-2.12.3-november-2018">Version 2.12.3, November 2018</h2>
<ul>
-<li>Upgrade Emacs dependency to 24.4.</li>
+<li>Bug fix: when searching the database, only search visible entries.</li>
</ul>
-<h2 id="december-2016-2">5 December 2016</h2>
+<h2 id="version-2.12.2-november-2018">Version 2.12.2, November 2018</h2>
<ul>
-<li>New library <code>org-ebib</code>. This defines a new Org link type <code>ebib:</code>, which uses the command <code>org-ebib-open</code> to open Ebib. The previous commands to do this, <code>ebib-show-entry</code> and <code>ebib-open-org-link</code> have been removed. <code>org-ebib</code> also allows the creation of Org links to Ebib entries with <code>org-store-link</code>.</li>
-<li>New citation insertion command <code>ebib-insert-citation</code>. This replaces <code>ebib-insert-bibtex-key</code>, so please update your key bindings. The new command uses <code>ivy</code> for completion if this package is available, so that it is possible to select an entry by typing parts of its author and/or title.</li>
+<li>Bug fix: when editing the <code>crossref</code> field, offer keys from all databases as completion targets, not just the current one.</li>
</ul>
-<h2 id="november-2016">7 November 2016</h2>
-<ul>
-<li>New tabulated list interface in index buffer. This interface is not based on Emacs’ built-in <code>tabulated-list-mode</code>, hence sorting cannot be done by clicking on the column headers. Sorting can be done with <code>&lt;</code>, <code>&gt;</code> (sort ascending and sort descending, respectively, which ask for the column to sort) and <code>=</code>, to reset to default sort (which is on the entry key).</li>
-<li>The user option <code>ebib-index-display-fields</code> is replaced with <code>ebib-index-columns</code>, which has a different format: each element in <code>ebib-index-columns</code> describes a column in the tabulated view and consists of a list containing the field name, the column’s width and a boolean indicating whether sorting on this column is possible.</li>
-</ul>
-<h2 id="version-2.8-26-october-2016">Version 2.8, 26 October 2016</h2>
-<ul>
-<li>Changed key bindings: <code>j</code> and <code>k</code> no longer move up/down in the index, entry and strings buffers; use <code>p</code> and <code>n</code> instead. Furthermore, <code>i</code> now executes <code>ebib-push-bibtex-key</code> (used to be <code>p</code>), and <code>I</code> (capital i) executes <code>ebib-browse-doi</code> (used to be <code>i</code>).</li>
-<li>In the index buffer, <code>ebib-search-next</code> (which used to be bound to <code>n</code>) is no longer bound. Instead, <code>ebib-search</code> (still bound to <code>/</code>) activates a transient map which binds the keys <code>/</code> and <code>RET</code> to <code>ebib-search-next</code>. Any other key disables the transient keymap and is executed normally.</li>
-<li>In the index buffer, <code>C-u /</code> repeats the previous search. (This fixes a small bug that has so far gone unnoticed: moving to the top of the databas and calling <code>ebib-search-next</code>, as previously suggested in the manual to get around the fact that <code>ebib-search-next</code> does not wrap, would not search the first entry.)</li>
-<li>In the entry buffer, <code>x</code> is replaced by <code>k</code> (<code>ebib-kill-field-contents</code>).</li>
-<li>New functions: <code>ebib-kill-entry</code> and <code>ebib-yank-entry</code> for killing and yanking BibTeX entries. <code>ebib-kill-entry</code> deletes the current entry from the database and puts it in the kill ring. <code>ebib-yank-entry</code> adds an entry from the kill ring to the current database.</li>
-</ul>
-<h2 id="version-2.7-22-september-2016">Version 2.7, 22 September 2016</h2>
+<h2 id="version-2.12-august-2018">Version 2.12, August 2018</h2>
<ul>
-<li>Reading list management: add and remove BibTeX entries to an Org reading list.</li>
-<li>Remove options <code>ebib-notes-identifier-function</code> and <code>ebib-notes-title-function</code>.</li>
-<li>Add option <code>ebib-notes-template-specifiers</code>: allow customisation of the format specs used in <code>ebib-notes-template</code>. (This option replaces <code>ebib-notes-identifier-function</code> and <code>ebib-notes-title-function</code>).</li>
+<li>Add an option to specify the default sort field and direction. It is no longer necessary to set the desired sort field as the first column in the index buffer, but Ebib still defaults to this if the default sort field and direction are not set explicitly.</li>
</ul>
-<h2 id="version-2.6.3-31-august-2016">Version 2.6.3, 31 August 2016</h2>
+<h2 id="version-2.11.12-july-2018">Version 2.11.12, July 2018</h2>
<ul>
-<li>Allow storing notes in a single file rather than using one file per note.</li>
-<li>Correct handling of DOIs.</li>
-<li>Add option <code>ebib-truncate-file-names</code>: if set (the default), file names added to the <code>file</code> field are truncated relative to <code>ebib-file-search-dirs</code>.</li>
-<li>Add option <code>ebib-file-name-mod-function</code>: modify file paths before storing them in the <code>file</code> field.</li>
+<li>Use BibLaTeX’s <code>Date</code> field, if present, for displaying the year.</li>
+<li>Check for changed files on disk when saving all databases, not just when saving the current database.</li>
+<li>Improve handling of multiple databases: <code>crossref</code> entries can now occur in other open databases as well, and searches with <code>/</code> can be continued in other databases.</li>
+<li>Autogenerating keys is now on by default.</li>
</ul>
<h1 id="installation">Installation</h1>
<h2 id="package-manager">Package manager</h2>
@@ -246,7 +213,7 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<h2 id="debian-and-ubuntu">Debian and Ubuntu</h2>
<p>Users of Debian 9 or later and Ubuntu 16.10 or later can also use their distro’s package manager: <code>apt-get install elpa-ebib</code>.</p>
<h2 id="manual-installation">Manual installation</h2>
-<p>It’s also possible to install Ebib manually by downloading the source, compiling it and telling Emacs where to find it. 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 Ebib’s dependencies, the <a href="https://github.com/magnars/dash.el">dash</a> and <a href="https://github.com/joostkremers/parsebib">parsebib</a> libraries.</p>
+<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 id="starting-ebib">Starting Ebib</h2>
<p>Once Ebib has been installed and is loaded, you can start it with <code>M-x ebib</code>. This command is also used to return to Ebib when you have put the program in the background. You can bind this command to a key sequence by putting something like the following in Emacs’ init file:</p>
<pre><code>(global-set-key &quot;\C-ce&quot; &#39;ebib)</code></pre>
@@ -254,22 +221,6 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<p>You can also call Ebib from an Eshell command line. This in itself is entirely unspectacular (in Eshell, you can invoke any Emacs function), but the nice thing is that you can then 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>
-<h2 id="upgrading-from-ebib-1.x">Upgrading from Ebib 1.x</h2>
-<p>If you upgrade from Ebib 1.x to the current version 2, there are a few things you need to be aware of. First, Ebib 2 does not support Emacs versions below 24.3. If you’re on an older version of Emacs, either upgrade Emacs, or do not upgrade Ebib. Ebib 1.x will continue to be available in the <code>pasture</code> branch on Github or as a package on the Github releases page, so if for some reason you do not want to upgrade, you can continue to use this branch. Ebib 1.x will continue to be supported with bug fixes and possibly the occasional (small) feature addition, though no major changes will take place.</p>
-<p>If you do upgrade, it is important to note that a few customisation options have changed. If you never made any customisations to Ebib, the upgrade should not pose any problems. If you have, however, read on.</p>
-<p>The most important change is that the variable <code>ebib-entry-types</code> (option “Entry Types”) has been removed. Ebib now uses the entry type definitions of the built-in <code>bibtex-mode</code>, which means that if you wish to customise the entry types, you should customise <code>bibtex-BibTeX-entry-alist</code> or <code>bibtex-biblatex-entry-alist</code>.</p>
-<p>Secondly, a few user options have been renamed because their types have changed. (Mainly from <code>symbol</code> to <code>string</code>). The name change means that existing customisations are lost, but it also prevents Ebib from throwing cryptic errors and refusing to run. If you customised any of the following options, you should redo them after upgrading Ebib (and preferably remove the old ones from your init file):</p>
-<ul>
-<li><code>ebib-default-entry</code>: renamed to <code>ebib-default-entry-type</code>.</li>
-<li><code>ebib-additional-fields</code>: renamed to <code>ebib-extra-fields</code>.</li>
-<li><code>ebib-standard-url-field</code>: renamed to <code>ebib-url-field</code>.</li>
-<li><code>ebib-standard-file-field</code>: renamed to <code>ebib-file-field</code>.</li>
-<li><code>ebib-standard-doi-field</code>: renamed to <code>ebib-doi-field</code>.</li>
-<li><code>ebib-biblatex-inheritance</code>: renamed to <code>ebib-biblatex-inheritances</code> (note the <code>s</code>).</li>
-</ul>
-<p>Note that even if you customised <code>ebib-biblatex-inheritance</code>, there is most likely no need to customise its replacement <code>ebib-biblatex-inheritances</code>, because the latter is set up with the default inheritance rules that Biblatex defines.</p>
-<p>Another thing to note is that four user options have a new default value. First, the default location of the rc file has moved to <code>~/.emacs.d/ebibrc</code>, in line with the recommendation to keep all Emacs-related files in <code>~/.emacs.d</code>. If you kept an <code>.ebibrc</code> file in your home directory, move it to <code>~/.emacs.d</code>. Second, a <code>\documentclass</code> definition has been added to the user options “Latex Preamble” (<code>ebib-latex-preamble</code>) and “Print Preamble” (<code>ebib-print-preamble</code>). If you customised one of these, you should add a document class specification, otherwise the LaTeX file won’t compile. Third, the option <code>ebib-save-xrefs-first</code> now defaults to <code>t</code>.</p>
-<p>Lastly, if you use Biblatex, make sure to read the section on using Ebib with Biblatex files.</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. Furthermore, each entry is known by a unique key. The way that Ebib navigates this database is by having two windows, one that contains a list of all the entry keys in the database, and one that contains the fields and values of the currently highlighted entry.</p>
<p>When Ebib is started, the current windows in Emacs are hidden and the Emacs frame is divided into two windows. The top one contains a buffer that is called the <em>index buffer</em>, while the lower window contains 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. You can move through the entries with the cursor keys. In the entry buffer, the fields of the currently highlighted entry are shown, with their values.</p>
@@ -278,14 +229,14 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<p>You can start Ebib with the command <code>M-x ebib</code>. Entering this command hides all the windows in the current Emacs frame and replaces them with two windows: the top one contains the index buffer, the bottom one, taking up the larger part of the screen, contains the entry buffer. The index buffer is named <code>none</code>, to indicate that no database has been loaded. If you open a database, or start a new one, the index buffer will carry its name.</p>
<p>You can quit Ebib by typing <code>q</code>. You will be asked for confirmation, and you will receive a warning if you happen to have an unsaved database. You can also leave Ebib with the command <code>z</code>. However, unlike <code>q</code>, which completely quits Ebib, <code>z</code> only lowers it, so that it remains active in the background. The <code>.bib</code> files that you have opened remain loaded, and you can return to them by typing <code>M-x ebib</code> again.</p>
<h2 id="opening-a-.bib-file">Opening a <code>.bib</code> File</h2>
-<p>Loading a <code>.bib</code> file into Ebib is done with the command <code>o</code>. 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. Note that when Ebib reads a <code>.bib</code> file, it only reads entry types (e.g. <code>book, article, phdthesis</code> etc.) that it knows about. Therefore, you should make sure that all the entry types and fields that your databases use are defined. 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-bibtex-entry-alist</code> or <code>bibtex-biblatex-entry-alist</code>, depending on which of the two you use.</p>
+<p>Loading a <code>.bib</code> file into Ebib is done with the command <code>o</code>. 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.</p>
<p>Every time Ebib reads a <code>.bib</code> file, it produces a few log messages. These are written into a special buffer <code>*Ebib-log*</code>. If Ebib encounters entry types in the <code>.bib</code> file that it doesn’t know, a warning will be logged. If Ebib finds something that it cannot parse, it will log an error. If warnings and/or errors occurred during loading, Ebib will issue a message when it finishes loading the <code>.bib</code> and direct you to the log buffer.</p>
-<p>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 will happen is when you load a Biblatex file without letting Ebib know the file is Biblatex-specific. By default, Ebib assumes that a <code>.bib</code> file it loads is a BibTeX file. If you intend to use Biblatex files, make sure to read the section on Biblatex (<a href="#using-biblatex">Using Biblatex</a>).</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-bibtex-entry-alist</code> or <code>bibtex-biblatex-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 Biblatex file without letting Ebib know the file is Biblatex-specific. By default, Ebib assumes that a <code>.bib</code> file it loads is a BibTeX file. If you intend to use Biblatex files, make sure to read the section on Biblatex (<a href="#using-biblatex">Using Biblatex</a>).</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, and you may find yourself opening the same file or files every time you start Ebib. If so, you can tell Ebib to always load specific <code>.bib</code> files on startup. To do this, specify the files in Ebib’s customisation buffer, under the option “Preload Bib Files” (<code>ebib-preload-bib-files</code>).</p>
<p>By default, <code>.bib</code> files are searched for in your home directory. Since this is most likely not where you keep the files, you need to specify either the file’s full path or a relative path starting from your home directory. Alternatively, you can customise the option “Bib Search Dirs” (<code>ebib-bib-search-dirs</code>) to specify one or more directories in which Ebib should search the <code>.bib</code> files.</p>
<h2 id="navigating-a-.bib-file">Navigating a <code>.bib</code> File</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 first entry is highlighted, meaning it is the current entry. The fields it holds and their values are shown in the entry buffer in the bottom Ebib window. The first field is the type field, which tells you what kind of entry you’re dealing with (i.e. <code>book</code>, <code>article</code>, etc.).</p>
+<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 first entry is highlighted, meaning it is the current entry. The fields it holds and their values are shown in the entry buffer in the bottom Ebib window. The first field is the type field, which tells you what kind of entry you’re dealing with (i.e. <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 Bib(La)TeX requires to be filled. The second group are the optional fields, which do not have to be filled but which Bib(La)TeX will normally add to the bibliography if they do have a value. The third group is the so-called extra fields. These fields are usually ignored by Bib(La)TeX (note that Bib(La)TeX normally ignores <em>all</em> fields it does not know), although there are bibliography styles that treat some of these fields as optional rather than as extra. Extra fields are defined in the user option “Extra Fields” (<code>ebib-extra-fields</code>). Lastly, the fourth set of fields shown in the entry buffer are fields that exist in the entry but are not defined as part of the entry type nor as extra fields.</p>
<p>The first two groups of fields are different for each entry type, while the third group is common to all entry types. You can use the extra fields, for example, to add personal comments to the works in your database. Ebib by default defines the following extra fields: <code>crossref</code>, <code>url</code> (BibTeX only), <code>annote</code> (<code>annotation</code> for Biblatex), <code>abstract</code>, <code>keywords</code>, <code>file</code>, <code>timestamp</code>, and <code>doi</code> (BibTeX only). <code>url</code> and <code>doi</code> are defined only for BibTeX, since Biblatex defines them as optional fields for most entry types. If these are not sufficient for you, you can customise the option “Extra Fields”.</p>
<p>To move around in the index buffer, you can use the <code>up</code> and <code>down</code> cursor keys, <code>p</code> and <code>n</code> and also the versions with the control key <code>C-p</code> and <code>C-n</code>. Furthermore, <code>Space</code> and <code>PgDn</code> move a screenful of entries down, while <code>b</code> and <code>PgUp</code> move in the other direction. Lastly, <code>g</code> and <code>Home</code> move to the first entry, while <code>G</code> and <code>End</code> move to the last one.</p>
@@ -305,16 +256,17 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<h2 id="editing-fields-values">Editing Fields Values</h2>
<p>Editing the field values for an entry is done in the lower of the two Ebib buffers, the so-called entry buffer. You can move focus to the entry buffer and start editing field values by typing the command <code>e</code> 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: the cursor keys <code>up</code> and <code>down</code>, <code>p</code> and <code>n</code> or <code>C-p</code> and <code>C-n</code>. <code>Space</code> and <code>PgDn</code> move to the next set of fields, while <code>PgUp</code> and <code>b</code> move to the previous set of fields. <code>g</code> and <code>G</code>, and <code>Home</code> and <code>End</code> also work as expected.</p>
-<p>Editing a field value can be done with <code>e</code>. (In fact, in the entry buffer, <code>RET</code> is equivalent to <code>e</code>.) For most fields, Ebib simply asks you for a string value in the minibuffer. (Here, <code>RET</code> confirms the edit, while <code>C-g</code> cancels it.) Although BibTeX requires that field values be surrounded by braces {} (or double quotes &quot;&quot;, but Ebib does not use those, even though it can of course handle them when they are used in an existing <code>.bib</code> file) you do not need to type these. Ebib adds them when it saves the <code>.bib</code> file.</p>
+<p>Editing a field value can be done with <code>e</code>. (In fact, in the entry buffer, <code>RET</code> is equivalent to <code>e</code>.) For most fields, Ebib simply asks you for a string value in the minibuffer. (Here, <code>RET</code> confirms the edit, while <code>C-g</code> cancels it.) Although BibTeX requires that field values be surrounded by braces {} (or double quotes "", but Ebib does not use those, even though it can of course handle them when they are used in an existing <code>.bib</code> file) you do not need to type these. Ebib adds them when it saves the <code>.bib</code> file.</p>
<p>Some fields, however, are handled in a special way. The first of these is the <code>type</code> field: if you edit this field, you must enter one of the predefined entry types. Ebib won’t allow you to enter anything else. You can use TAB completion in this case. Similarly, if you edit the <code>crossref</code> field, Ebib requires that you fill in a key from the database. Here, too, you can use TAB completion. The fields <code>keywords</code> and <code>file</code> are also treated differently, see <a href="#managing-keywords">Managing keywords</a> and <a href="#viewing-files">Viewing Files</a>, respectively.</p>
<p>Note that if you’re adding a new entry, Ebib automatically puts you in the entry buffer after you’ve typed the entry key: you don’t have to type <code>e</code> to move to the entry buffer. When creating a new entry, you should set the <code>type</code> field first, because the <code>type</code> field determines which other fields are available for an entry. After editing a field, Ebib puts you on the next field. This is convenient if you’re creating a new entry and need to fill out several fields in a row.</p>
<p>If you’re done editing the fields of the entry, type <code>q</code> to move focus back to the index buffer. (Note: keys may have different functions in the index buffer and the entry buffer. <code>q</code> is a typical example: in the entry buffer, it quits editing the entry and moves focus back to the index buffer. In the index buffer, however, <code>q</code> quits Ebib.)</p>
<h2 id="editing-multiline-values">Editing Multiline Values</h2>
-<p>Apart from the <code>type</code>, <code>keywords</code>, <code>file</code> and <code>crossref</code> fields, there is another field that Ebib handles in a special way when you edit its value. This is the <code>annote</code> field (<code>annotation</code> in Biblatex). Most field values normally consist of a single line of text. However, because the <code>annote</code> field is meant for creating annotated bibliographies, it would not be very useful if you could only write one line of text in this field. Therefore, when you edit the <code>annote</code> field, Ebib puts you in a so-called <em>multiline edit buffer</em>. This is essentially a text mode buffer that allows you to enter as much text as you like. To store the text and leave the multiline edit buffer, type <code>C-c | q</code>.</p>
+<p>Apart from the <code>type</code>, <code>keywords</code>, <code>file</code> and <code>crossref</code> fields, there are two other fields that Ebib handles in a special way when you edit its value. These are the <code>annote</code> field (or <code>annotation</code> in Biblatex), and the <code>abstract</code> field. Most field values normally consist of a single line of text. However, because the <code>annote</code>/<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 as much text as you like. To store the text and leave the multiline edit buffer, type <code>C-c | q</code>.</p>
<p>If you want to leave the multiline edit buffer without saving the text you have just typed, type <code>C-c | c</code>. 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>Multiline values are not restricted to the <code>annote</code> field. 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 <code>m</code> instead of <code>e</code>. You will again be put in a multiline edit buffer, where you can edit the value. Note that you can use <code>m</code> even if a field already has a single line value. Ebib will just make that the first line in the multiline edit buffer.</p>
-<p>When a field has a multiline value, only the first line is shown in the entry buffer, for space reasons. To indicate that the value is multiline, a plus sign <code>+</code> is placed in front of the value. If you want to see the whole contents of a multiline field, you can use <code>v</code>: this will display the contents of the current field in a <code>*Help*</code> buffer. This buffer can be dismissed again with <code>q</code>. This is quicker than entering the multiline edit buffer just to read the contents of a field and it has the advantage that the other fields stay visible.</p>
-<p>By the way, the <code>e</code> key is smart about the way an entry must be edited. If you press <code>e</code> on a field that already has a multiline value, regardless of the fact whether it is the <code>annote</code> field or not, Ebib puts you in a multiline edit buffer. Therefore, you need <code>m</code> only if you want to give a field a multiline value when it doesn’t have one yet.</p>
+<p>Multiline values are not restricted to the <code>annote</code>/<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 <code>m</code> instead of <code>e</code>. You will again be put in a multiline edit buffer, where you can edit the value. Note that you can use <code>m</code> even if a field already has a single line value. Ebib will just make that the first line in the multiline edit buffer.</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 <code>v</code>: this will display the contents of the current field in a <code>*Help*</code> buffer. This buffer can be dismissed again with <code>q</code>. This is quicker than entering the multiline edit buffer just to read the contents of a field and it has the advantage that the other fields stay visible.</p>
+<p>It’s 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>By the way, the <code>e</code> key is smart about the way an entry must be edited. If you press <code>e</code> on a field that already has a multiline value, regardless of the fact whether it is the <code>annote</code>/<code>annotation</code> or <code>abstract</code> field or not, Ebib puts you in a multiline edit buffer. Therefore, you need <code>m</code> only if you want to give a field a multiline value when it doesn’t have one yet.</p>
<p>For more details on working with multiline edit buffers, see <a href="#multiline-edit-buffers">Multiline Edit Buffers</a>.</p>
<h2 id="undefined-fields">Undefined Fields</h2>
<p>Bib(la)TeX ignores fields that it does not know, 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>
@@ -327,7 +279,7 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<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 “Use Timestamp” (<code>ebib-use-timestamp</code>) in Ebib’s customisation buffer. With this option set, a timestamp is included in entries added to the database with <code>a</code>. Ebib will also add a timestamp to entries imported from a buffer or merged from a file, and to entries exported to another database or to a file. When importing or exporting entries, existing timestamps will be overwritten. The logic behind this is that the timestamp records the date and time when the entry was added to the database, not when it was first created.</p>
<p>Note that if this option is unset, the timestamp of an entry is retained when it’s imported or exported. Therefore, if you record timestamps and want to im-/export entries without changing their timestamps, temporarily unset this option, 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>&quot;%a %b</code> <code>%e %T %Y&quot;</code>, which produces a timestamp of the form <code>&quot;Mon Mar 12 01:03:26 2007&quot;</code>. This string is not directly suitable for sorting, so if you want to be able to sort on timestamps, you’ll need to customise the format string. See the documentation for <code>format-time-string</code> on the options that are available. (Alternatively, the default time stamp format can be converted into a sortable time format using <code>date-to-time</code>, but currently Ebib is not able to do this automatically.)</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>"%a %b</code> <code>%e %T %Y"</code>, which produces a timestamp of the form <code>"Mon Mar 12 01:03:26 2007"</code>. This string is not directly suitable for sorting, so if you want to be able to sort on timestamps, you’ll need to customise the format string. See the documentation for <code>format-time-string</code> on the options that are available. (Alternatively, the default time stamp format can be converted into a sortable time format using <code>date-to-time</code>, but currently Ebib is not able to do this automatically.)</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.</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 <code>c</code>, <code>k</code> and <code>y</code> implement copy, kill and yank: <code>c</code> copies the contents of the current field to the kill ring, <code>k</code> kills the contents of the current field to the kill ring, and <code>y</code> yanks (pastes) the most recently killed text in the kill ring. You can type <code>y</code> repeatedly to get the same effect you get in Emacs when you type <code>M-y</code> after an initial <code>C-y</code>.</p>
@@ -350,16 +302,20 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<h1 id="the-entries-list">The Entries List</h1>
<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 <code>&lt;</code> and <code>&gt;</code>. 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 <code>=</code>.</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.</p>
-<p>You can use any BibTeX / BibLaTeX field to define a column in the index buffer. In addition, there are two column labels with a special meaning: <code>&quot;Entry Key&quot;</code>, which displays the entry key, and <code>&quot;Author/Editor&quot;</code>, which displays the contents of the author field if it is not empty, and the contents of the editor field otherwise.</p>
+<p>You can use any BibTeX / BibLaTeX field to define a column in the index buffer. In addition, there are two column labels that do not correspond directly to a field name. These are <code>"Entry Key"</code>, which displays the entry key, <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 display the contents of the year field unconditionally. Rather, it first checks the contents of the date field, which is BibLaTeX’s replacement of the year field, and extracts the first year in it. Only if the date field is empty does it display the year field.</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 (including their optional 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. <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 “Note”. This does not, as might be expected, display the contents of the note field. Rather, it checks whether the entry in question has a note associated with it in Ebib’s own notes system, discussed in <a href="#notes-files">Notes Files</a>. For those entries that have a note, the <code>"Note"</code> column will display 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. <code>"Entry Key"</code>, <code>"Author/Editor"</code>, and <code>"Year"</code> are not (they are hard-coded), but they can be overridden by adding an entry for them in <code>ebib-field-transformation-functions</code>.</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 <code>=</code>. 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>
<h1 id="searching">Searching</h1>
<h2 id="simple-searches">Simple Searches</h2>
<p>Ebib provides several search methods. First of all, in the index buffer, the normal Emacs incremental searches, <code>C-s</code> and <code>C-r</code>, can be used to search entry keys. Once you’ve found the key you’re searching, you must hit <code>RET</code> to quit the search and again <code>RET</code> to make the entry you found active: Ebib does not update the entry buffer during incremental search. If you make frequent use of this option, you may want to make the cursor visible in the Ebib buffers. Unset the customisation option “Hide Cursor” (<code>ebib-hide-cursor</code>) to do so.</p>
<p>The contents of the entries can be searched with <code>/</code>. 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 <code>/</code> to specify the fields to search. Note that if the search term is found in a field with a multiline value, Ebib will highlight the <code>+</code> sign that is displayed in front of the field value. When the search term is found, Ebib gives a message saying so, similarly if the search term was not found.</p>
-<p>A search term may of course appear more than once in the database. To search for the next occurrence, type <code>/</code> again (or, alternatively type <code>RET</code>). This continues searching for the search term in the rest of the database. Again, the first entry found to contain the search string is displayed. Note that the search does not wrap: if the end of the database is reached, Ebib stops searching and informs you that no further occurrence of the search string was found. If you want to continue searching from the top, type <code>g</code> and then continue the search with <code>/</code> or <code>RET</code>.</p>
-<p>Note that once you’ve started a search with <code>/</code>, Ebib activates a transient key map called <code>ebib-search-map</code>. It is this map that holds the bindings of <code>/</code> and <code>RET</code> to continue searching after the current entry and of the key <code>g</code> to jump to the top of the database. You can, of course, bind or rebind keys in this map.</p>
-<p>Exiting a search (i.e., getting rid of the transient key map) is done by pressing any key other than <code>/</code>, <code>RET</code> or <code>g</code>. 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 <code>/</code>. So typing <code>C-u /</code> (or any other prefix argument) starts searching for the previous search string again.</p>
+<p>A search term may of course appear more than once in the database. To search for the next occurrence, type <code>RET</code>. This continues searching for the search term in the rest of the database. Again, the first entry found to contain the search string is displayed. Note that the search does not wrap: if the end of the database is reached, Ebib stops searching and informs you that no further occurrence of the search string was found. If you want to continue searching from the top, type <code>g</code> and then continue the search with <code>RET</code>.</p>
+<p>Note that once you’ve started a search with <code>/</code>, Ebib activates a transient key map called <code>ebib-search-map</code>. It is this map that holds the binding for <code>RET</code> to continue searching after the current entry and of the key <code>g</code> 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 <code>RET</code>, <code>g</code> 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 <code>/</code>. So typing <code>C-u /</code> 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>
<h2 id="filters">Filters</h2>
<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>
<h3 id="simple-selection">Simple Selection</h3>
@@ -371,7 +327,7 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<p>Once you have a filter on your database, you can refine or extend it. For example, suppose you have a filter selecting all entries with “Jones” in the <code>author</code> field and want to add all entries that have “Jones” in the editor field to your selection. In this case you need to do a logical <code>or</code> operation: you want to select an entry if it contains “Jones” in the <code>author</code> field (which you already did) <em>or</em> if it contains “Jones” 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 “Jones” in the <code>author</code> field <em>and</em> all entries that contain “Jones” 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 “Jones” in the <code>author</code> field <em>or</em> if it contains “Jones” 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 “Jones” in both the <code>author</code> <em>and</em> <code>editor</code> fields.</p>
<p>To perform a logical <code>or</code> operation, press the key <code>|</code>. 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 “Jones” in the <code>author</code> field and e.g. “symbiotic hibernation” in the <code>keyword</code> field. A logical <code>and</code> operation is done with the key <code>&amp;</code>. (Note: this is the same key that is used to create the filter. In fact, you can create a filter with <code>|</code> as well: when used in an unfiltered database, <code>&amp;</code> and <code>|</code> are equivalent. They are only different when a filter is already active.)</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 “Jones” in the <code>author</code> field and e.g. “symbiotic hibernation” in the <code>keyword</code> field. A logical <code>and</code> operation is done with the key <code>&amp;</code>. (Note: this is the same key that is used to create the filter. In fact, you can create a filter with <code>|</code> as well: when used in an unfiltered database, <code>&amp;</code> and <code>|</code> are equivalent. They are only different when a filter is already active.)</p>
<p>Both the <code>&amp;</code> and <code>|</code> commands can be used with the negative prefix argument <code>M--</code> (or <code>C-u -</code>, 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 <code>M-- &amp;</code> 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 <code>~</code>, you invert the current filter. That is, if you have a filtered database with all the entries containing “Jones” in the <code>author</code> or in the <code>editor</code> field, and you press <code>~</code>, the selection is inverted, and now contains all entries that do <em>not</em> have “Jones” in the <code>author</code> or <code>editor</code> field.</p>
<p>Although <code>~</code> and the negative prefix argument to <code>&amp;</code> or <code>|</code> both perform logical <code>not</code> operations, they are <em>not</em> equivalent: <code>~</code> negates the entire filter built up so far, while the negative prefix argument only negates the single selection criterion you enter with it.</p>
@@ -386,9 +342,8 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<p>To see what filters are currently stored, use <code>F V</code>. If you want to rename a filter, you can do so with <code>F R</code>.</p>
<p>Note that cancelling a filter with <code>F c</code> 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 <code>F d</code>. You can also delete all stored filters with <code>F D</code>. 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 <code>F l</code>.</p>
<h3 id="special-filters">Special Filters</h3>
-<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 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>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 local dynamic variable, which means that the file that defines the filter function should have the variable <code>lexical-binding</code> set to <code>nil</code>.</p>
-<p>The value of <code>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:</p>
+<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:</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;)
@@ -400,39 +355,41 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
(&quot;=key=&quot; . &quot;Chomsky1957&quot;))</code></pre>
<h3 id="an-example-listing-recent-additions">An Example: Listing Recent Additions</h3>
<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="cb4"><pre class="sourceCode lisp"><code class="sourceCode commonlisp"><a class="sourceLine" id="cb4-1" data-line-number="1">(<span class="kw">defun</span><span class="fu"> ebib-list-recent </span>(days)</a>
-<a class="sourceLine" id="cb4-2" data-line-number="2"> <span class="st">&quot;List entries created in the last DAYS days.&quot;</span></a>
-<a class="sourceLine" id="cb4-3" data-line-number="3"> (interactive <span class="st">&quot;nNumber of days: &quot;</span>)</a>
-<a class="sourceLine" id="cb4-4" data-line-number="4"> <span class="co">;; save the database&#39;s current filter, if there is one.</span></a>
-<a class="sourceLine" id="cb4-5" data-line-number="5"> (<span class="kw">let</span> ((filter (ebib-db-get-filter ebib--cur-db)))</a>
-<a class="sourceLine" id="cb4-6" data-line-number="6"> (<span class="kw">when</span> filter (<span class="kw">setq</span> ebib--filters-last-filter filter))) </a>
-<a class="sourceLine" id="cb4-7" data-line-number="7"> (<span class="kw">let*</span></a>
-<a class="sourceLine" id="cb4-8" data-line-number="8"> <span class="co">;; calculate the from-date in Emacs&#39; time format</span></a>
-<a class="sourceLine" id="cb4-9" data-line-number="9"> ((date (time-subtract (current-time) (days-to-time days)))</a>
-<a class="sourceLine" id="cb4-10" data-line-number="10"> <span class="co">;; create a Lisp expression that will function as the filter</span></a>
-<a class="sourceLine" id="cb4-11" data-line-number="11"> (filter `(ebib--newer-than (<span class="kw">quote</span> ,date))))</a>
-<a class="sourceLine" id="cb4-12" data-line-number="12"> <span class="co">;; install it as the curretn database&#39;s filter</span></a>
-<a class="sourceLine" id="cb4-13" data-line-number="13"> (ebib-db-set-filter filter ebib--cur-db)</a>
-<a class="sourceLine" id="cb4-14" data-line-number="14"> <span class="co">;; update the display, so that only filtered entries are visible</span></a>
-<a class="sourceLine" id="cb4-15" data-line-number="15"> (ebib--redisplay)))</a></code></pre></div>
-<p>First, this function saves the current filter if there is one. It then creates a date in Emacs’ internal time format by subtracting the number of days provided by the user from the current date and uses this date to create a Lisp expression which is then installed as the filter for the current database. A call to <code>ebib--redisplay</code> then updates the display, taking the filter into account.</p>
+<div class="sourceCode" id="cb4"><pre class="sourceCode lisp"><code class="sourceCode commonlisp"><a class="sourceLine" id="cb4-1" title="1">(<span class="kw">defun</span><span class="fu"> ebib-list-recent </span>(days)</a>
+<a class="sourceLine" id="cb4-2" title="2"> <span class="st">&quot;List entries created in the last DAYS days.&quot;</span></a>
+<a class="sourceLine" id="cb4-3" title="3"> (interactive <span class="st">&quot;nNumber of days: &quot;</span>)</a>
+<a class="sourceLine" id="cb4-4" title="4"> <span class="co">;; Save the database&#39;s current filter, if there is one.</span></a>
+<a class="sourceLine" id="cb4-5" title="5"> (<span class="kw">let</span> ((filter (ebib-db-get-filter ebib--cur-db)))</a>
+<a class="sourceLine" id="cb4-6" title="6"> (<span class="kw">when</span> filter (<span class="kw">setq</span> ebib--filters-last-filter filter)))</a>
+<a class="sourceLine" id="cb4-7" title="7"> (<span class="kw">let*</span></a>
+<a class="sourceLine" id="cb4-8" title="8"> <span class="co">;; Calculate the from-date in Emacs&#39; time format.</span></a>
+<a class="sourceLine" id="cb4-9" title="9"> ((date (time-subtract (current-time) (days-to-time days)))</a>
+<a class="sourceLine" id="cb4-10" title="10"> <span class="co">;; Create a Lisp expression that will function as the filter.</span></a>
+<a class="sourceLine" id="cb4-11" title="11"> (filter `(ebib--newer-than (<span class="kw">quote</span> ,date))))</a>
+<a class="sourceLine" id="cb4-12" title="12"> <span class="co">;; Install it as the current database&#39;s filter.</span></a>
+<a class="sourceLine" id="cb4-13" title="13"> (ebib-db-set-filter filter ebib--cur-db)</a>
+<a class="sourceLine" id="cb4-14" title="14"> <span class="co">;; Update the current entry key.</span></a>
+<a class="sourceLine" id="cb4-15" title="15"> (ebib-db-set-current-entry-key (ebib--get-key-at-point) ebib--cur-db)</a>
+<a class="sourceLine" id="cb4-16" title="16"> <span class="co">;; Update the display, so that only filtered entries are visible.</span></a>
+<a class="sourceLine" id="cb4-17" title="17"> (ebib--update-buffers)))</a></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="cb5"><pre class="sourceCode lisp"><code class="sourceCode commonlisp"><a class="sourceLine" id="cb5-1" data-line-number="1">(<span class="kw">defun</span><span class="fu"> ebib--newer-than </span>(date)</a>
-<a class="sourceLine" id="cb5-2" data-line-number="2"> <span class="st">&quot;Function for use in filters.</span></a>
-<a class="sourceLine" id="cb5-3" data-line-number="3"><span class="st">Return t if the entry being tested is newer than DATE. DATE must</span></a>
-<a class="sourceLine" id="cb5-4" data-line-number="4"><span class="st">be a list of the format returned by `current-time&#39; and is</span></a>
-<a class="sourceLine" id="cb5-5" data-line-number="5"><span class="st">compared to the timestamp of the entry being tested. If the</span></a>
-<a class="sourceLine" id="cb5-6" data-line-number="6"><span class="st">entry has no timestamp, or a timestamp that cannot be converted</span></a>
-<a class="sourceLine" id="cb5-7" data-line-number="7"><span class="st">into a date representation, return nil.&quot;</span></a>
-<a class="sourceLine" id="cb5-8" data-line-number="8"> (<span class="kw">let</span> ((timestamp (<span class="kw">cdr</span> (assoc-string <span class="st">&quot;timestamp&quot;</span> entry))))</a>
-<a class="sourceLine" id="cb5-9" data-line-number="9"> (<span class="kw">when</span> (<span class="kw">and</span> timestamp</a>
-<a class="sourceLine" id="cb5-10" data-line-number="10"> (<span class="kw">setq</span> timestamp (<span class="kw">ignore-errors</span> (date-to-time timestamp))))</a>
-<a class="sourceLine" id="cb5-11" data-line-number="11"> (time-less-p date timestamp))))</a></code></pre></div>
-<p>This function obtains the time stamp of the entry being tested from the variable <code>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>
+<div class="sourceCode" id="cb5"><pre class="sourceCode lisp"><code class="sourceCode commonlisp"><a class="sourceLine" id="cb5-1" title="1">(<span class="kw">defun</span><span class="fu"> ebib--newer-than </span>(date)</a>
+<a class="sourceLine" id="cb5-2" title="2"> <span class="st">&quot;Function for use in filters.</span></a>
+<a class="sourceLine" id="cb5-3" title="3"><span class="st">Return t if the entry being tested is newer than DATE. DATE must</span></a>
+<a class="sourceLine" id="cb5-4" title="4"><span class="st">be a list of the format returned by `current-time&#39; and is</span></a>
+<a class="sourceLine" id="cb5-5" title="5"><span class="st">compared to the timestamp of the entry being tested. If the</span></a>
+<a class="sourceLine" id="cb5-6" title="6"><span class="st">entry has no timestamp, or a timestamp that cannot be converted</span></a>
+<a class="sourceLine" id="cb5-7" title="7"><span class="st">into a date representation, return nil.&quot;</span></a>
+<a class="sourceLine" id="cb5-8" title="8"> (<span class="kw">let</span> ((timestamp (<span class="kw">cdr</span> (assoc-string <span class="st">&quot;timestamp&quot;</span> ebib-entry))))</a>
+<a class="sourceLine" id="cb5-9" title="9"> (<span class="kw">when</span> (<span class="kw">and</span> timestamp</a>
+<a class="sourceLine" id="cb5-10" title="10"> (<span class="kw">setq</span> timestamp (<span class="kw">ignore-errors</span> (date-to-time timestamp))))</a>
+<a class="sourceLine" id="cb5-11" title="11"> (time-less-p date timestamp))))</a></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>
<h3 id="properties-of-filtered-databases">Properties of Filtered Databases</h3>
<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 <code>F r</code>.</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 <code>M</code>, 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 <code>w</code> (or the menu option “Save Database 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 <code>F L</code>, of course.</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 <code>w</code> (or the menu option “Save Database 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 <code>F L</code>, of course.</p>
<p>One final note: of all the filter-related commands, <code>~</code>, <code>F c</code>, <code>F r</code>, <code>F s</code> and <code>F v</code> 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="accessing-bibtex-databases-outside-ebib">Accessing BibTeX Databases outside Ebib</h1>
<p>When you’re in a text buffer, 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, and for <a href="http://orgmode.org">Org mode</a>.</p>
@@ -546,7 +503,7 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<h1 id="calling-a-browser">Calling a Browser</h1>
<p>With most scientific literature nowadays being available on-line, it is common to store URLs and DOIs in a BibTeX database. (Biblatex of course has standardised fields for this information.) Sometimes you may want to load such a URL or a DOI in your browser. Ebib provides a convenient way for doing so.</p>
<p>If you type <code>u</code> in the index buffer, Ebib takes the URL stored in the <code>url</code> field of the current entry and passes it to your browser. Furthermore, in the entry buffer, you can use <code>u</code> on <em>any</em> field. 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 <code>M-2 u</code> 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>&quot; ' ; &lt;</code> or <code>&gt;</code> as a URL. The semicolon is included here even though it is actually a valid character in URLs. This is done for consistency, because the semicolon (actually, semicolon+space) is the standard separator for files in the <code>file</code> field and in this way, you can use the same separator to distinguish multiple URLs in the <code>url</code> field. By default 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. You can, of course, customise the regular expression that controls this behaviour. See the option “Url Regexp” for details.</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. The semicolon is included here even though it is actually a valid character in URLs. This is done for consistency, because the semicolon (actually, semicolon+space) is the standard separator for files in the <code>file</code> field and in this way, you can use the same separator to distinguish multiple URLs in the <code>url</code> field. By default 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. You can, of course, customise the regular expression that controls this behaviour. See the option “Url Regexp” for details.</p>
<p>Similarly, with the key <code>i</code> in the index buffer you can send a DOI to a browser. The DOI must be stored in the <code>doi</code> field. Unlike URLs, there can only be one DOI in this field. The whole contents of the field is assumed to be the DOI and is sent to the browser. Ebib adds the URL <code>http://dx.doi.org/</code> before sending the DOI to the browser, so the <code>doi</code> field should contain just the DOI itself.</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 “Browser Command”. You can also customise the field that Ebib takes URLs from, with the option “Standard Url Field”. The same can be done for the DOI field.</p>
<h1 id="viewing-files">Viewing Files</h1>
@@ -561,7 +518,7 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<p>For the entry key <code>Chomsky1995</code>, this produces <code>C/Chomsky1995</code>, which is then appended with the extension <code>.pdf</code>.</p>
<p>Of course, the function in <code>ebib-name-transform-function</code> does not have to be a lambda. It can also be the name of a function that you’ve defined for the purpose.</p>
<h2 id="editing-the-file-field">Editing the <code>file</code> field</h2>
-<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 ENTER, Ebib adds the filename to the <code>file</code> field, appending it no 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 ENTER. The default separator is <code>&quot;; &quot;</code> (semicolon-space), but this can be customised (see the option “Filename Separator” for details). The advantage of this method is that you can use TAB completion to complete file names.</p>
+<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 ENTER, Ebib adds the filename to the <code>file</code> field, appending it no 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 ENTER. The default separator is <code>"; "</code> (semicolon-space), but this can be customised (see the option “Filename Separator” for details). The advantage of this method is that you can use TAB completion to complete file names.</p>
<p>The first directory in the option “File Search Dirs” 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 “File Search Dirs” into account: completion is done using the standard Emacs file name completion mechanism. However, when you enter a file name, Ebib checks if it is in a (subdirectory of) one of the directories in “File Search Dirs”, and if so, cuts off the relevant part of the file name to turn it into a relative path. (You can disable this behaviour with the option <code>ebib-truncate-file-names</code>: if unset, file names are always stored as absolute paths.)</p>
<h1 id="notes-files">Notes files</h1>
<p>Ebib supports the <code>annote</code> (or <code>annotation</code>) field, 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 <code>N</code> 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, <code>N</code> opens it. The mode line of the entry buffer indicates whether an entry has a note associated with it by displaying the string <code>[N]</code> (customisable with <code>ebib-notes-symbol</code>).</p>
@@ -583,7 +540,7 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
:END:
&gt;|&lt;
&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>&quot;Custom_id: &quot;</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>&quot;&gt;|&lt;&quot;</code>, which indicates the position of the cursor when a new note is created.</p>
+<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>"&gt;|&lt;"</code>, which indicates the position of the cursor when a new note is created.</p>
<p>It is possible to change the template by customising the option <code>ebib-notes-template</code>. Note that if you do this, the <code>%K</code> directive should not be removed. 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 a BibTeX entry has a note or not. The <code>%T</code> directive and the cursor indicator may be left out.</p>
<p>There are in fact a few more specifiers that may be used in the template: <code>%F</code> creates a link to the file in the BibTeX entry’s <code>file</code> field, <code>%D</code> creates a link to the DOI in the entry’s <code>doi</code> field, and <code>%U</code> a link to the entry’s <code>url</code> field. There is also a <code>%L</code> specifier, which creates a 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 by customising <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>
@@ -611,34 +568,34 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<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 <code>M-x ebib-add-file-entry</code>. 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.</p>
<p>Note that the entry keys for the stubs are temporary keys. They will be replaced by more permanent keys automatically when you edit the entries. This behaviour is controlled by the function <code>bibtex-generate-autokey</code>, which has a number of customisation options. Check out its doc string for details. If you prefer to edit the keys by hand, you can do so by pressing <code>E</code> in the index buffer.</p>
<h1 id="preamble-definition"><span class="citation" data-cites="Preamble">@Preamble</span> Definition</h1>
-<p>Apart from database entries, BibTeX allows three more types of elements to appear in a <code>.bib</code> file. These are <code>@comment</code>, <code>@preamble</code> and <code>@string</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 really 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>Apart from database entries, BibTeX allows three more types of elements to appear in a <code>.bib</code> file. These are <code>@comment</code>, <code>@Preamble</code> and <code>@String</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 really 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;
+<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) <code>P</code> in the index buffer. Ebib uses the multiline edit buffer for editing the text of the <code>@preamble</code> definition, which means that <code>C-c | q</code> stores the <code>@preamble</code> text and returns focus to the index buffer, while <code>C-c | c</code> 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>
+<p>Creating or editing a <code>@Preamble</code> definition in Ebib is done by hitting (uppercase) <code>P</code> in the index buffer. Ebib uses the multiline edit buffer for editing the text of the <code>@Preamble</code> definition, which means that <code>C-c | q</code> stores the <code>@Preamble</code> text and returns focus to the index buffer, while <code>C-c | c</code> 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>
+<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>
<h1 id="string-definitions"><span class="citation" data-cites="String">@String</span> Definitions</h1>
-<p>If you press (uppercase) <code>S</code> 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 <code>a</code>. 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>Moving between the <code>@string</code> definitions can be done in the usual way: the cursor keys <code>up</code> and <code>down</code>, <code>p</code> and <code>n</code> or <code>C-p</code> and <code>C-n</code> move up and down. <code>Space</code> and <code>PgDn</code> move ten strings down, while <code>b</code> and <code>PgUp</code> move in the other direction. The keys <code>g</code>, <code>G</code>, <code>Home</code> and <code>End</code> also function as expected.</p>
-<p>To delete a <code>@string</code> definition, use <code>d</code>. To edit the value of a definition, use <code>e</code>. There is also a command <code>c</code>, which copies the value of the current <code>@string</code> definition to the kill ring. Unlike in the entry buffer, there are no corresponing commands <code>y</code> and <code>x</code>. (In fact, <code>x</code> does exist, but has another function.) Yanking from the kill ring can be done with <code>C-y/M-y</code> in the minibuffer when you edit a <code>@string</code>’s value. Cutting a <code>@string</code>’s value is pointless, because a <code>@string</code> definition must have a value.</p>
-<p>Having defined <code>@string</code> definitions, there must of course be a way to use them. Just giving a field a string abbreviation as value will not do, because Ebib puts braces around the value that you enter when it writes the <code>.bib</code> file, so that BibTeX will not recognise the abbreviation, and will not expand it. BibTeX will only recognise an abbreviation if it appears in the <code>.bib</code> file outside of any braces.</p>
+<p>If you press (uppercase) <code>S</code> 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 <code>a</code>. 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>Moving between the <code>@String</code> definitions can be done in the usual way: the cursor keys <code>up</code> and <code>down</code>, <code>p</code> and <code>n</code> or <code>C-p</code> and <code>C-n</code> move up and down. <code>Space</code> and <code>PgDn</code> move ten strings down, while <code>b</code> and <code>PgUp</code> move in the other direction. The keys <code>g</code>, <code>G</code>, <code>Home</code> and <code>End</code> also function as expected.</p>
+<p>To delete a <code>@String</code> definition, use <code>d</code>. To edit the value of a definition, use <code>e</code>. There is also a command <code>c</code>, which copies the value of the current <code>@String</code> definition to the kill ring. Unlike in the entry buffer, there are no corresponing commands <code>y</code> and <code>x</code>. (In fact, <code>x</code> does exist, but has another function.) Yanking from the kill ring can be done with <code>C-y/M-y</code> in the minibuffer when you edit a <code>@String</code>’s value. Cutting a <code>@String</code>’s value is pointless, because a <code>@String</code> definition must have a value.</p>
+<p>Having defined <code>@String</code> definitions, there must of course be a way to use them. Just giving a field a string abbreviation as value will not do, because Ebib puts braces around the value that you enter when it writes the <code>.bib</code> file, so that BibTeX will not recognise the abbreviation, and will not expand it. BibTeX will only recognise an abbreviation if it appears in the <code>.bib</code> file outside of any braces.</p>
<p>To accomplish this, you must mark a field’s value as special. A special field is a field whose value is not surrounded by braces when the database is saved, so that BibTeX recognises it as an abbreviation. To mark a field special, press <code>r</code>. An asterisk will appear before the field, indicating that has no braces. Pressing <code>r</code> again will change the field back to normal. If you press <code>r</code> on a field that does not have a value yet, Ebib will ask you for one.</p>
<p>Note that this also makes it possible to enter field values that are composed of concatenations of strings and abbreviations. The BibTeX documentation for example explains that if you have defined:</p>
-<pre><code>@string{WGA = &quot;World Gnus Almanac&quot;}</code></pre>
+<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 someting like “1 January”, assuming your bibliography style has defined the abbreviation <code>jan</code>. 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 <code>s</code> instead of <code>e</code>. If you type <code>s</code>, Ebib asks you for a <code>@string</code> abbreviation to put in the current field, and automatically marks the field as special. With this command, Ebib only accepts <code>@string</code> definitions that are in the database, so that by using <code>s</code> you can make sure you don’t make any typos. Note that you can use TAB completion to complete a partial string.</p>
+<p>An easy way to enter a <code>@String</code> abbreviation as a field value is to use the key <code>s</code> instead of <code>e</code>. If you type <code>s</code>, Ebib asks you for a <code>@String</code> abbreviation to put in the current field, and automatically marks the field as special. With this command, Ebib only accepts <code>@String</code> definitions that are in the database, so that by using <code>s</code> you can make sure you don’t make any typos. Note that you can use TAB completion to complete a partial string.</p>
<h1 id="comments"><span class="citation" data-cites="Comments">@Comments</span></h1>
-<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 (right after the <code>@preamble</code>.) 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>
+<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 (right after the <code>@Preamble</code>.) 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>
<h1 id="managing-keywords">Managing Keywords</h1>
<p>Ebib provides some special functionality for handling keywords. By default, there is a <code>keywords</code> field in the list of extra fields. Editing this field is a bit different from other fields. Instead of just entering a string and hitting ENTER to store it and return to the entry buffer, you should enter a single keyword and hit enter. The keyword will then be added to the keywords already present and you are asked to enter the next keyword. If you’ve added all keywords you want, just hit ENTER to finish.</p>
<p>The advantage of doing it this way is that you can reuse keywords: once you’ve added a keyword to one entry, Ebib remembers it. The next time you want to use the same keyword for a different entry, you just need to type the first (few) letters, hit TAB and the keyword will be completed. That makes it easier to ensure you use the exact same keywords in different entries. Note that Ebib’s keyword functionality is not used to check the contents of keyword fields. It is simply a way to make it easier to stick to specific keywords, which should make it easier to categorise and search your entries.</p>
@@ -651,7 +608,7 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<p>When you close a database, Ebib checks if you have added new keywords to it and asks you if you want to save them. You can tell Ebib to save new keywords automatically by setting the option “Keywords File Save On Exit” to <code>always</code>. Note that this doesn’t save the keywords when you enter them, only when you close the database or quit Ebib. You can also set this option to <code>never</code>, which means Ebib will discard new keywords when the database is closed. Note that if you want to save the keywords file without having to close the database, you can do so through the menu.</p>
<p>The option “Keywords Use Only File” controls whether Ebib uses only the keyword file, or both the keyword file and the configured keyword list. This option is only useful when you have configured a keyword file. In that case, setting this option to use both the keyword list and the keyword file tells Ebib to offer keywords from both sources when you edit the keyword field. Otherwise, only the keyword file is used.</p>
<p>It is also possible to tell Ebib to sort the keywords in the <code>keywords</code> field in alphabetical order. Set the option “Keywords Field Keep Sorted” if you want to do this. Note that setting this option also automatically removes duplicates.</p>
-<p>Lastly, you can configure the separator used between keywords in the keyword field. By default, it is set to <code>&quot;, &quot;</code>, i.e., comma-space. (The separator is a comma because that is what Biblatex expects in the <code>keywords</code> field.) If you change it, keep in mind that Ebib does not add a space between keywords, so if you want a space, make sure to add it to the separator.</p>
+<p>Lastly, you can configure the separator used between keywords in the keyword field. By default, it is set to <code>", "</code>, i.e., comma-space. (The separator is a comma because that is what Biblatex expects in the <code>keywords</code> field.) If you change it, keep in mind that Ebib does not add a space between keywords, so if you want a space, make sure to add it to the separator.</p>
<h1 id="sorting-the-.bib-file">Sorting the <code>.bib</code> File</h1>
<p>By default, the entries in the database are saved to the <code>.bib</code> file in alphabetical order according to entry key. If you only deal with the <code>.bib</code> file through Ebib, you may not care in which order the entries are saved. However, it may sometimes be desirable to be able to specify the sort order of entries in more detail. (Apparently, this can be useful with ConTeXt, for example.)</p>
<p>You can specify a sort order in Ebib’s customisation buffer. To sort the entries, you must set at least one sort level (that is, a field to sort the entries on). You can also specify more than one sort level: if two entries have identical values for the first sort level, they will be sorted on the second sort level. E.g., if the first sort level is <code>author</code> and the second is <code>year</code>, then the entries are sorted by author, and those entries that have identical values for the <code>author</code> field are sorted by year.</p>
@@ -667,10 +624,9 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
<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 <code>M-x ebib-import</code>. Ebib then goes through the buffer and loads all BibTeX entries it finds into the current database (i.e. the database that was active when you lowered Ebib). If you call <code>ebib-import</code> while the region is active, Ebib only reads the BibTeX entries in the region.</p>
<p>If a BibTeX entry in the buffer lack 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-keyXX&gt;</code>, where <code>XX</code> is a number. You can change such keys by hitting <code>E</code> in the index buffer. They will also automatically be replaced with a more sensible key when you edit them. See the option “Autogenerate Keys” for details.</p>
<h1 id="exporting-entries">Exporting Entries</h1>
-<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 a <code>.bib</code> file, use the command <code>x</code>. This command operates on a single entry or on all marked entries.</p>
-<p>When you export one or more entries, Ebib will ask you for a filename to export them to. If you have already exported an entry before, Ebib will present the filename you used as default, but you can of course change it. For obvious reasons, Ebib appends the entry to the file that you enter if it already exists, it does not overwrite the file. If this is not what you want, delete the file first, as Ebib provides no way to do this.</p>
-<p>If you have more than one database open in Ebib, it is also possible to copy entries from one database to another. To do this, use the <code>x</code> command with a numeric prefix argument. E.g., if the database you want to export an entry to is the second database, type <code>M-2 x</code> to export the current entry to it. The number of the database is given in the modeline of the index buffer. If the database you’re copying an entry to already contains an entry with the same entry key, Ebib won’t copy the entry, and issues an appropriate warning message.</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 <code>X</code> in the index buffer. <code>@string</code> definitions can be exported in the strings buffer: <code>x</code> in this buffer exports the current string, while <code>X</code> 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 a filename, and then append the relevent data to that file. With a numeric prefix argument, they copy the relevant data to the corresponding open database.</p>
+<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, use the command <code>x</code>. This command operates on a single entry or on all marked entries. Ebib will ask you for the database to export the entry or entries to. TAB-completion is available, based on the file names of the databases.</p>
+<p>You can also export entries to a file. To do this, call the command <code>x</code> with a prefix argument: <code>C-u x</code>. You will be prompted for the file name 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 it’s possible to 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 <code>X</code> in the index buffer. <code>@String</code> definitions can be exported in the strings buffer: <code>x</code> in this buffer exports the current string, while <code>X</code> 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>
<h1 id="multiple-identical-fields">Multiple Identical Fields</h1>
<p>Under normal circumstances, a BibTeX entry only contains one occurrence of each field. If BibTeX notices that an entry contains more than one occurrence of an 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 BibTeX will use the value of the <em>first</em> occurrence, not the last.) When extra fields appear more than once in an entry, BibTeX does not warn you, since it ignores those fields anyway. Here, too, Ebib’s standard behaviour is to ignore all but the last value.</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 “Allow Identical Fields”.</p>
@@ -691,40 +647,39 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
keywords = {sleep, winter, hibernation}
}</code></pre>
<h1 id="multiline-edit-buffers">Multiline Edit Buffers</h1>
-<p>As mentioned several times before, Ebib has a special multiline edit buffer, which is used to edit field values that contain newlines (so-called <em>multiline fields</em>), and also to edit the contents of the <code>@preamble</code> command. This section discusses the details of this buffer.</p>
-<p>Ebib enters multiline edit mode in one of three cases: when you edit the <code>@preamble</code> definition, when you hit <code>m</code> in the entry buffer to edit the current field as multiline, or when you hit <code>e</code> on the <code>annote</code> field, or on a field whose value already is multiline.</p>
-<p>The mode that is used in the multiline edit buffer 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 options. (Personally, I use <code>markdown-mode</code> in the multiline edit buffer, so that I can use <a href="http://daringfireball.net/projects/markdown/"><code>Markdown</code></a> to write annotations, which provides an easy way to create headers, use bold and italic, etc., in plain text.)</p>
+<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 three cases: when you edit the <code>@Preamble</code> definition, when you hit <code>m</code> in the entry buffer to edit the current field as multiline, or when you hit <code>e</code> on the <code>annote</code>/<code>annotation</code> or `abstract 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 <code>C-c | q</code>, 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 <code>x</code> or <code>d</code> on them in the entry buffer.) If you were editing a <code>@string</code> value, Ebib will just complain, because string definitions cannot be empty.</p>
+<p><code>ebib-quit-multiline-buffer-and-save</code>, bound to <code>C-c | q</code>, 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 <code>k</code> or <code>d</code> on them in the entry buffer.)</p>
<p><code>ebib-cancel-multiline-buffer</code>, bound to <code>C-c | c</code>, 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 <code>C-c | s</code>, 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>Admittedly, the key combinations of the multiline edit buffer are somewhat awkward. The reason for this is that these commands are part of a minor mode, which restricts the available keys to combinations of <code>C-c</code> plus a non-alphanumeric character. However, it is possible to change the key commands, if you wish. Ebib itself provides a method to change the second key of these commands, <a href="#modifying-key-bindings">Modifying Key Bindings</a>. You could change the <code>|</code> to e.g., <code>c</code> or <code>C-c</code>, if these do not conflict with any key commands in the major mode used for the multiline edit buffer.</p>
-<p>Even more drastically, you could put something like the following in your <code>~/.emacs</code>:</p>
-<div class="sourceCode" id="cb32"><pre class="sourceCode commonlisp"><code class="sourceCode commonlisp"><a class="sourceLine" id="cb32-1" data-line-number="1">(eval-after-load &#39;ebib</a>
-<a class="sourceLine" id="cb32-2" data-line-number="2"> &#39;(<span class="kw">progn</span></a>
-<a class="sourceLine" id="cb32-3" data-line-number="3"> (define-key ebib-multiline-mode-map</a>
-<a class="sourceLine" id="cb32-4" data-line-number="4"> <span class="st">&quot;\C-c\C-c&quot;</span> &#39;ebib-quit-multiline-buffer-and-save)</a>
-<a class="sourceLine" id="cb32-5" data-line-number="5"> (define-key ebib-multiline-mode-map</a>
-<a class="sourceLine" id="cb32-6" data-line-number="6"> <span class="st">&quot;\C-c\C-q&quot;</span> &#39;ebib-cancel-multiline-buffer)</a>
-<a class="sourceLine" id="cb32-7" data-line-number="7"> (define-key ebib-multiline-mode-map</a>
-<a class="sourceLine" id="cb32-8" data-line-number="8"> <span class="st">&quot;\C-c\C-s&quot;</span> &#39;ebib-save-from-multiline-buffer)))</a></code></pre></div>
+<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>Admittedly, the key combinations of the multiline edit buffer are somewhat awkward. The reason for this is that these commands are part of a minor mode, which restricts the available keys to combinations of <code>C-c</code> plus a non-alphanumeric character. However, it is possible to change the key commands, if you wish. For example, you could put something like the following in your <code>~/.emacs</code>:</p>
+<div class="sourceCode" id="cb32"><pre class="sourceCode commonlisp"><code class="sourceCode commonlisp"><a class="sourceLine" id="cb32-1" title="1">(with-eval-after-load &#39;ebib</a>
+<a class="sourceLine" id="cb32-2" title="2"> (define-key ebib-multiline-mode-map</a>
+<a class="sourceLine" id="cb32-3" title="3"> <span class="st">&quot;\C-c\C-c&quot;</span> &#39;ebib-quit-multiline-buffer-and-save)</a>
+<a class="sourceLine" id="cb32-4" title="4"> (define-key ebib-multiline-mode-map</a>
+<a class="sourceLine" id="cb32-5" title="5"> <span class="st">&quot;\C-c\C-q&quot;</span> &#39;ebib-cancel-multiline-buffer)</a>
+<a class="sourceLine" id="cb32-6" title="6"> (define-key ebib-multiline-mode-map</a>
+<a class="sourceLine" id="cb32-7" title="7"> <span class="st">&quot;\C-c\C-s&quot;</span> &#39;ebib-save-from-multiline-buffer)))</a></code></pre></div>
<p>This sets up <code>C-c C-c</code>, <code>C-c C-q</code> and <code>C-c C-s</code> for use in the multiline edit buffer. Since such key combinations are restricted for use with major modes, however, Ebib cannot set these up automatically, but as an Emacs user, you are free to do as you like, of course.</p>
<h1 id="the-options-menu">The Options Menu</h1>
<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>
<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 <code>M-x customize-group RET ebib RET</code>, or by using the menu «Ebib | Options | Customize Ebib».</p>
-<p>Another way to customise Ebib is to use the initialisation file <code>~/.emacs.d/ebibrc</code>. (Actually, the location and name of this file can be customised as well.) This file contains normal Lisp code and is the best way to customise key bindings (as discussed in the next section), but it can in fact be used to run any Lisp code.</p>
<h2 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 (<code>~.emacs.d/init.el</code> by default). 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 adds keys to finish writing multiline field values.</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>
<p>As an example, the default keybindings in<code>ebib-multiline-mode-map</code>, which are rather awkward to type, can be redefined as follows:</p>
-<div class="sourceCode" id="cb33"><pre class="sourceCode commonlisp"><code class="sourceCode commonlisp"><a class="sourceLine" id="cb33-1" data-line-number="1">(define-key ebib-multiline-mode-map</a>
-<a class="sourceLine" id="cb33-2" data-line-number="2"> <span class="st">&quot;\C-c\C-c&quot;</span> &#39;ebib-quit-multiline-buffer-and-save)</a>
-<a class="sourceLine" id="cb33-3" data-line-number="3">(define-key ebib-multiline-mode-map</a>
-<a class="sourceLine" id="cb33-4" data-line-number="4"> <span class="st">&quot;\C-c\C-q&quot;</span> &#39;ebib-cancel-multiline-buffer)</a>
-<a class="sourceLine" id="cb33-5" data-line-number="5">(define-key ebib-multiline-mode-map</a>
-<a class="sourceLine" id="cb33-6" data-line-number="6"> <span class="st">&quot;\C-c\C-s&quot;</span> &#39;ebib-save-from-multiline-buffer)</a></code></pre></div>
+<div class="sourceCode" id="cb33"><pre class="sourceCode commonlisp"><code class="sourceCode commonlisp"><a class="sourceLine" id="cb33-1" title="1">(with-eval-after-load &#39;ebib</a>
+<a class="sourceLine" id="cb33-2" title="2"> (define-key ebib-multiline-mode-map</a>
+<a class="sourceLine" id="cb33-3" title="3"> <span class="st">&quot;\C-c\C-c&quot;</span> &#39;ebib-quit-multiline-buffer-and-save)</a>
+<a class="sourceLine" id="cb33-4" title="4"> (define-key ebib-multiline-mode-map</a>
+<a class="sourceLine" id="cb33-5" title="5"> <span class="st">&quot;\C-c\C-q&quot;</span> &#39;ebib-cancel-multiline-buffer)</a>
+<a class="sourceLine" id="cb33-6" title="6"> (define-key ebib-multiline-mode-map</a>
+<a class="sourceLine" id="cb33-7" title="7"> <span class="st">&quot;\C-c\C-s&quot;</span> &#39;ebib-save-from-multiline-buffer)))</a></code></pre></div>
</article>
</body>
</html>
diff --git a/docs/images/Search-view.png b/docs/images/Search-view.png
index 6201454..def385e 100644
--- a/docs/images/Search-view.png
+++ b/docs/images/Search-view.png
Binary files differ
diff --git a/docs/images/tn-Search-view.png b/docs/images/tn-Search-view.png
index b855efa..b5add04 100644
--- a/docs/images/tn-Search-view.png
+++ b/docs/images/tn-Search-view.png
Binary files differ
diff --git a/docs/index.html b/docs/index.html
index aab331c..088fe79 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -1,3 +1,25 @@
+<!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" />
+ <title>Ebib: a BibTeX database manager for Emacs</title>
+ <style type="text/css">
+ code{white-space: pre-wrap;}
+ span.smallcaps{font-variant: small-caps;}
+ span.underline{text-decoration: underline;}
+ div.column{display: inline-block; vertical-align: top; width: 50%;}
+ </style>
+ <link rel="stylesheet" href="ebib.css" />
+ <!--[if lt IE 9]>
+ <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
+ <![endif]-->
+</head>
+<body>
+<header id="title-block-header">
+<h1 class="title">Ebib: a BibTeX database manager for Emacs</h1>
+</header>
<div id="menu">
<p><a href="#features">Features</a></p>
<p><a href="#screenshots">Screenshots</a></p>
@@ -55,7 +77,7 @@
</ul>
<h2 id="screenshots">Screenshots</h2>
<p>Visually, Ebib is not very spectacular. But to get an impression of what it looks like, you can look at the following three screenshots. The first shows Ebib’s standard lay-out, with the list of entry keys in the top window and the fields of the currently highlighted entry in the bottom window. The field values displayed in a greenish colour come from the cross-referenced entry. (The colours Ebib uses are inherited from the current colour theme, but they can be customised independently.)</p>
-<p>In the second image, which uses the alternative vertical layout, the string ‘Reuland’ is highlighted as the result of a text search. The third screenshot shows the strings buffer, where you can edit the <code>@string</code> definitions in the database.</p>
+<p>In the second image, which uses an alternative partial-frame layout, the string <code>"Geraci"</code> is highlighted as the result of a text search. It also shows a buffer with a note for the highlighted entry. The third screenshot shows the strings buffer, where you can edit the <code>@String</code> definitions in the database.</p>
<p><a href="images/Main-view.png"> <img style="width:192px;height:106px" src="images/tn-Main-view.png" alt="screenshot 1" /></a> <a href="images/Search-view.png"> <img style="width:192px;height:106px" src="images/tn-Search-view.png" alt="screenshot 1" /></a> <a href="images/Strings-buffer.png"> <img style="width:192px;height:106px" src="images/tn-Strings-buffer.png" alt="screenshot 2" /></a></p>
<h2 id="manual">Manual</h2>
<p>The complete user manual for Ebib is available in html format <a href="ebib-manual.html">here</a>.</p>
@@ -66,6 +88,8 @@
<h2 id="support">Support</h2>
<p>The quickest way to ask questions or report issues is to use the <a href="https://github.com/joostkremers/ebib/issues?state=open">Github issue tracker</a>. Alternatively, send me an <a href="&#x6d;&#x61;&#x69;&#108;&#116;&#x6f;&#58;&#106;&#x6f;&#x6f;&#x73;&#116;&#x6b;&#114;&#x65;&#x6d;&#x65;&#114;&#x73;&#64;&#102;&#x61;&#x73;&#116;&#x6d;&#x61;&#x69;&#108;&#46;&#102;&#x6d;" class="email">&#x65;&#x6d;&#x61;&#x69;&#108;</a>.</p>
<div class="bottom-dweller">
-<p>Joost Kremers (<em>last modified:</em> <em>05 Feb 2018</em>)</p>
+<p>Joost Kremers (<em>last modified:</em> <em>07 Jan 2019</em>)</p>
</div>
</article>
+</body>
+</html>
diff --git a/docs/index.text b/docs/index.text
index f68e3e7..5b258c3 100644
--- a/docs/index.text
+++ b/docs/index.text
@@ -79,7 +79,7 @@ Ebib provides the standard capabilities that one would expect from a BibTeX data
Visually, Ebib is not very spectacular. But to get an impression of what it looks like, you can look at the following three screenshots. The first shows Ebib's standard lay-out, with the list of entry keys in the top window and the fields of the currently highlighted entry in the bottom window. The field values displayed in a greenish colour come from the cross-referenced entry. (The colours Ebib uses are inherited from the current colour theme, but they can be customised independently.)
-In the second image, which uses the alternative vertical layout, the string 'Reuland' is highlighted as the result of a text search. The third screenshot shows the strings buffer, where you can edit the `@string` definitions in the database.
+In the second image, which uses an alternative partial-frame layout, the string `"Geraci"` is highlighted as the result of a text search. It also shows a buffer with a note for the highlighted entry. The third screenshot shows the strings buffer, where you can edit the `@String` definitions in the database.
<a href="images/Main-view.png"> <img style="width:192px;height:106px" src="images/tn-Main-view.png" alt="screenshot 1" /></a> <a href="images/Search-view.png"> <img style="width:192px;height:106px" src="images/tn-Search-view.png" alt="screenshot 1" /></a> <a href="images/Strings-buffer.png"> <img style="width:192px;height:106px" src="images/tn-Strings-buffer.png" alt="screenshot 2" /></a>
diff --git a/ebib-db.el b/ebib-db.el
index 0c744ef..c38ea4f 100644
--- a/ebib-db.el
+++ b/ebib-db.el
@@ -1,6 +1,6 @@
;;; ebib-db.el --- Part of Ebib, a BibTeX database manager -*- lexical-binding: t -*-
-;; Copyright (c) 2003-2018 Joost Kremers
+;; Copyright (c) 2003-2019 Joost Kremers
;; All rights reserved.
;; Author: Joost Kremers <joostkremers@fastmail.fm>
@@ -37,16 +37,17 @@
;;; Code:
(require 'cl-lib)
-(require 'bibtex)
+(require 'subr-x) ; hash-table-keys
;; Each database is represented by a struct.
(cl-defstruct ebib--db-struct
(database (make-hash-table :test 'equal)) ; Hashtable containing the database itself.
(strings) ; Alist with the @STRING definitions.
- (preamble) ; String with the @PREAMBLE definition.
+ (preamble) ; String with the @Preamble definition.
(comments) ; List of @COMMENTS.
(local-vars) ; The file's local variable block.
(dialect) ; The dialect of this database.
+ (buffer) ; The index buffer.
(cur-entry) ; The current entry.
(marked-entries) ; List of marked entries.
(filter) ; The active filter.
@@ -62,14 +63,19 @@
(defun ebib-db-clear-database (db)
"Remove all information in DB.
-The database object itself is retained, only the information in
-it is deleted."
+The database object itself is retained, only the references to
+the relevant data in it is deleted.
+
+Note that the data itself is not destroyed, but may eventually be
+GC'ed, with the exception of the buffer pointed to by the buffer
+field. This should be killed separately."
(clrhash (ebib--db-struct-database db))
(setf (ebib--db-struct-strings db) nil)
(setf (ebib--db-struct-preamble db) nil)
(setf (ebib--db-struct-comments db) nil)
(setf (ebib--db-struct-local-vars db) nil)
(setf (ebib--db-struct-dialect db) nil)
+ (setf (ebib--db-struct-buffer db) nil)
(setf (ebib--db-struct-cur-entry db) nil)
(setf (ebib--db-struct-marked-entries db) nil)
(setf (ebib--db-struct-filter db) nil)
@@ -107,6 +113,23 @@ No check is performed to see if VARS is really a local variable block."
"Return the local variable block of DB."
(ebib--db-struct-local-vars db))
+(defun ebib-db-get-buffer (db)
+ "Return the index buffer of DB."
+ (ebib--db-struct-buffer db))
+
+(defun ebib-db-set-buffer (buffer db)
+ "Set BUFFER as DB's index buffer."
+ (setf (ebib--db-struct-buffer db) buffer))
+
+(defun ebib-db-kill-buffer (db)
+ "Kill the index buffer of DB.
+This function can be used when entries are added to or removed
+from DB non-interactively, to ensure that the index buffer is
+recreated the next time DB becomes active."
+ (when (ebib--db-struct-buffer db)
+ (kill-buffer (ebib--db-struct-buffer db))
+ (setf (ebib--db-struct-buffer db) nil)))
+
(defun ebib--db-get-current-entry-key (db)
"Return the key of the current entry in DB."
(ebib--db-struct-cur-entry db))
@@ -192,6 +215,10 @@ is suffixed, then `ab' etc."
"Return a list of keys in DB."
(hash-table-keys (ebib--db-struct-database db)))
+(defun ebib-db-has-key (key db)
+ "Return t if KEY exists in DB."
+ (gethash key (ebib--db-struct-database db)))
+
(defun ebib-db-change-key (key new-key db &optional if-exists)
"Change entry key KEY to NEW-KEY in DB.
ENTRY must be a key itself. IF-EXISTS determines what to do when
@@ -209,61 +236,40 @@ Return the new key upon succes, or nil if nothing was updated."
(ebib-db-remove-entry key db)
actual-new-key)))
-(defun ebib-db-set-field-value (field value key db &optional if-exists nobrace)
+(defun ebib-db-set-field-value (field value key db &optional overwrite)
"Set FIELD to VALUE in entry KEY in database DB.
-IF-EXISTS determines what to do if the field already exists. If
-it is `overwrite', the existing value is overwritten. If it is
-`noerror', the value is not stored and the function returns nil.
-If it is nil (or any other value), an error is raised.
-
-IF-EXISTS can also be the symbol `append' or a string. In this
-case, the new value is appended to the old value, separated by a
-space or by the string. Before appending, braces/double quotes
-are removed from both values.
-
-If NOBRACE is t, the value is stored without braces. If it is
-nil, braces are added if not already present. NOBRACE may also be
-the symbol `as-is', in which case the value is stored as is.
+OVERWRITE determines what to do if the field already exists. If
+it is t, the existing value is overwritten. If it is nil, the
+value is not stored and the function returns nil. OVERWRITE can
+can also be the symbol `error', in which case an error is raised
+and the value is not changed.
A field can be removed from the entry by passing nil as VALUE and
-setting IF-EXISTS to 'overwrite.
+setting OVERWRITE to t.
-Return non-nil upon success, or nil if the value could not be stored."
- (if (eq if-exists 'append)
- (setq if-exists " "))
+Return t upon success, or nil if the value could not be stored."
(let* ((entry (ebib-db-get-entry key db))
(elem (assoc-string field entry 'case-fold))
(old-value (cdr elem)))
;; If the field has a value, decide what to do:
(if old-value
(cond
- ((eq if-exists 'overwrite)
- (setq old-value nil))
- ((stringp if-exists)
- (setq value (concat (ebib-db-unbrace old-value) if-exists (ebib-db-unbrace value)))
- (setq old-value nil))
- ((not (eq if-exists 'noerror))
- (error "[Ebib] Field `%s' exists in entry `%s'; cannot overwrite" field key)))
- ;; Otherwise add the new field. We just add the field here, the value is
- ;; added later, so that we can put braces around it if needed. This also
- ;; makes it easier to return nil when storing/changing the field value
- ;; wasn't successful. Note that if `elem' is non-nil, we mustn't add the
- ;; field again. Note also: we use `setcdr' to modify the entry in place.
+ ((eq overwrite 'error)
+ (error "[Ebib] Field `%s' exists in entry `%s'; cannot overwrite" field key))
+ (overwrite
+ (setq old-value nil)))
+ ;; Create the field if it doesn't exist yet. The value is initially set to nil.
(unless elem
(setq elem (car (setcdr (last entry) (list (cons field nil))))))) ; Make sure `elem' points to the newly added field.
;; If there is (still) an old value, do nothing.
(unless old-value
- ;; Otherwise overwrite the existing entry. Note that to delete a field,
- ;; we set its value to nil, rather than removing it altogether from the
- ;; database. In `ebib--display-fields', such fields are ignored, so they're
+ ;; Otherwise overwrite the existing entry. Note that to delete a field, we
+ ;; set its value to nil, rather than removing it altogether from the
+ ;; database. In `ebib--display-fields', such fields are ignored, and they're
;; not saved.
- (if (and value nobrace)
- (unless (eq nobrace 'as-is)
- (setq value (ebib-db-unbrace value)))
- (setq value (ebib-db-brace value)))
(setcdr elem value)
- t))) ; Make sure we return non-nil.
+ t))) ; Make sure we return non-nil, `value' may be nil, after all.
(defun ebib-db-remove-field-value (field key db)
"Remove FIELD from entry KEY in DB."
@@ -282,52 +288,53 @@ otherwise return nil."
(setq value noerror))
value))
-(defun ebib-db-set-string (abbr value db &optional if-exists)
+(defun ebib-db-set-string (abbr value db &optional overwrite)
"Set the @string definition ABBR to VALUE in database DB.
-If ABBR does not exist, create it. VALUE is enclosed in braces if
-it isn't already.
+If ABBR does not exist, create it.
-IF-EXISTS determines what to do when ABBR already exists. If it
-is `overwrite', the new string replaces the existing one. If it is
-`noerror', the string is not stored and the function returns nil.
-If it is nil (or any other value), an error is raised.
+OVERWRITE determines what to do when ABBR already exists. If it
+is t, the new string replaces the existing one. If it is nil,
+the string is not stored and the function returns nil. If it is
+the symbol `error', an error is raised.
In order to remove a @STRING definition, pass nil as VALUE and
set IF-EXISTS to `overwrite'."
- (let* ((old-string (ebib-db-get-string abbr db 'noerror))
- (strings-list (delete (cons abbr old-string) (ebib--db-struct-strings db))))
- (when old-string
- (cond
- ((eq if-exists 'overwrite)
- (setq old-string nil))
- ((not (eq if-exists 'noerror))
- (error "[Ebib] @STRING abbreviation `%s' exists in database %s" abbr (ebib-db-get-filename db 'short)))))
- (unless old-string
- (setf (ebib--db-struct-strings db)
- (if (null value)
- strings-list
- ;; Put the new string at the end of the list, to keep them in the
- ;; order in which they appear in the .bib file. This is
- ;; preferable for version control.
- (append strings-list (list (cons abbr (ebib-db-brace value)))))))))
+ (let* ((strings-list (ebib--db-struct-strings db))
+ (old-string (cdr (assoc abbr strings-list))))
+ (if old-string
+ (cond
+ ((eq overwrite 'error)
+ (error "[Ebib] @STRING abbreviation `%s' exists in database %s"
+ abbr (ebib-db-get-filename db 'short)))
+ ((and overwrite value)
+ (setcdr (assoc-string abbr strings-list) value)
+ (setq value nil)) ; Set `value' to nil to indicate we're done.
+ (overwrite
+ (setq strings-list (delete (cons abbr old-string) strings-list))
+ (setq value nil)))) ; Set `value' to nil to indicate we're done.
+ (when value
+ ;; Put the new string at the end of the list, to keep them in the order in
+ ;; which they appear in the .bib file. This is preferable for version
+ ;; control.
+ (if strings-list
+ (setcdr (last strings-list) (list (cons abbr value)))
+ (setq strings-list (list (cons abbr value)))))
+ (setf (ebib--db-struct-strings db) strings-list)))
(defun ebib-db-remove-string (abbr db)
"Remove @STRING definition ABBR ttfrom DB."
(ebib-db-set-string abbr nil db 'overwrite))
-(defun ebib-db-get-string (abbr db &optional noerror unbraced)
+(defun ebib-db-get-string (abbr db &optional noerror)
"Return the value of @STRING definition ABBR in database DB.
If ABBR does not exist, trigger an error, unless NOERROR is
-non-nil, in which case return nil. If UNBRACED is non-nil, return
-the value without braces."
+non-nil, in which case return nil."
;; I assume abbreviations should be case-sensitive, so I use assoc
;; instead of assoc-string here.
(let ((value (cdr (assoc abbr (ebib--db-struct-strings db)))))
(unless (or value noerror)
(error "[Ebib] @STRING abbreviation `%s' does not exist" abbr))
- (if unbraced
- (ebib-db-unbrace value)
- value)))
+ value))
(defun ebib-db-get-all-strings (db)
"Return the alist containing all @STRING definitions in DB."
@@ -365,7 +372,7 @@ Return non-nil on success or nil if PREAMBLE could not be stored."
(error "[Ebib] Preamble is not empty; cannot overwrite")))))
(defun ebib-db-remove-preamble (db)
- "Remove the @PREAMBLE definition from DB."
+ "Remove the @Preamble definition from DB."
(ebib-db-set-preamble nil db 'overwrite))
(defun ebib-db-get-preamble (db)
@@ -400,10 +407,11 @@ IF-EXISTS is nil, an existing filename triggers an error."
(defun ebib-db-get-filename (db &optional shortened)
"Return the filename of DB.
If SHORTENED is non-nil, return only the filename part, otherwise
-return the full path."
- (if shortened
- (file-name-nondirectory (ebib--db-struct-filename db))
- (ebib--db-struct-filename db)))
+return the full path. If DB is nil, return nil."
+ (when db
+ (if shortened
+ (file-name-nondirectory (ebib--db-struct-filename db))
+ (ebib--db-struct-filename db))))
(defun ebib-db-get-modtime (db)
"Return the mod time stored for DB."
@@ -495,80 +503,6 @@ make backup at next save)."
"Return backup flag of DB."
(ebib--db-struct-backup db))
-;; EBIB-DB-UNBRACED-P determines if STRING is enclosed in braces. Note that
-;; we cannot do this by simply checking whether STRING begins with { and
-;; ends with } (or begins and ends with "), because something like "{abc} #
-;; D # {efg}" would then be incorrectly recognised as braced. So we need to
-;; do the following: take out everything that is between braces or quotes,
-;; and see if anything is left. If there is, the original string was
-;; braced, otherwise it was not.
-
-;; So we first check whether the string begins with { or ". if not, we
-;; certainly have an unbraced string. (EBIB-DB-UNBRACED-P recognises this
-;; through the default clause of the COND.) If the first character is { or
-;; ", we first take out every occurrence of backslash-escaped { and } or ",
-;; so that the rest of the function does not get confused over them.
-
-;; Then, if the first character is {, REMOVE-FROM-STRING takes out every
-;; occurrence of the regex "{[^{]*?}", which translates to "the smallest string
-;; that starts with { and ends with }, and does not contain another {. IOW, it
-;; takes out the innermost braces and their contents. Because braces may be
-;; embedded, we have to repeat this step until no more balanced braces are found
-;; in the string. (Note that it would be unwise to check for just the occurrence
-;; of { or }, because that would throw EBIB-DB-UNBRACED-P in an infinite loop if
-;; a string contains an unbalanced brace.)
-
-;; For strings beginning with " we do the same, except that it is not
-;; necessary to repeat this in a WHILE loop, for the simple reason that
-;; strings surrounded with double quotes cannot be embedded; i.e.,
-;; "ab"cd"ef" is not a valid (BibTeX) string, while {ab{cd}ef} is.
-
-;; Note: because these strings are to be fed to BibTeX and ultimately
-;; (La)TeX, it might seem that we don't need to worry about strings
-;; containing unbalanced braces, because (La)TeX would choke on them. But
-;; the user may inadvertently enter such a string, and we therefore need to
-;; be able to handle it. (Alternatively, we could perform a check on
-;; strings and warn the user.)
-
-(defun ebib-db-unbraced-p (string)
- "Non-nil if STRING is not enclosed in braces or quotes."
- (cl-flet ((remove-from-string (string remove)
- (apply #'concat (split-string string remove))))
- (when (stringp string)
- (cond
- ((eq (string-to-char string) ?\{)
- ;; First, remove all escaped { and } from the string:
- (setq string (remove-from-string (remove-from-string string "[\\][{]")
- "[\\][}]"))
- ;; Then remove the innermost braces with their contents and continue until
- ;; no more braces are left.
- (while (and (member ?\{ (string-to-list string)) (member ?\} (string-to-list string)))
- (setq string (remove-from-string string "{[^{]*?}")))
- ;; If STRING is not empty, the original string contains material not in braces
- (> (length string) 0))
- ((eq (string-to-char string) ?\")
- ;; Remove escaped ", then remove any occurrences of balanced quotes with
- ;; their contents and check for the length of the remaining string.
- (> (length (remove-from-string (remove-from-string string "[\\][\"]")
- "\"[^\"]*?\""))
- 0))
- (t t)))))
-
-(defun ebib-db-unbrace (string)
- "Convert STRING to its unbraced counterpart.
-If STRING is already unbraced, do nothing."
- (if (and (stringp string)
- (not (ebib-db-unbraced-p string)))
- (substring string 1 -1)
- string))
-
-(defun ebib-db-brace (string)
- "Put braces around STRING.
-If STRING is already braced, do nothing."
- (if (ebib-db-unbraced-p string)
- (concat "{" string "}")
- string))
-
(provide 'ebib-db)
;;; ebib-db.el ends here
diff --git a/ebib-filters.el b/ebib-filters.el
index 437af6b..eafd91b 100644
--- a/ebib-filters.el
+++ b/ebib-filters.el
@@ -1,6 +1,6 @@
;;; ebib-filters.el --- Part of Ebib, a BibTeX database manager -*- lexical-binding: nil -*-
-;; Copyright (c) 2003-2018 Joost Kremers
+;; Copyright (c) 2003-2019 Joost Kremers
;; All rights reserved.
;; Author: Joost Kremers <joostkremers@fastmail.fm>
@@ -73,7 +73,7 @@ a logical `not' is applied to the selection."
(field (completing-read (format "Filter: %s<field> contains <search string>%s. Enter field: "
(if (< not 0) "not " "")
(if (< not 0) "" ""))
- (append (list "any" "=type=") (-union (ebib--list-fields-uniquely dialect) (cdr (assq dialect ebib-extra-fields))))
+ (append (list "any" "=type=") (seq-uniq (seq-concatenate 'list (ebib--list-fields-uniquely dialect) (cdr (assq dialect ebib-extra-fields)))))
nil nil nil 'ebib--field-history)))
(let* ((prompt (format "Filter: %s%s contains <search string>%s. Enter %s: "
(if (< not 0) "not " "")
@@ -228,17 +228,20 @@ If there are no stored filters, the filter file is deleted."
(let ((file (read-file-name "Save filters to file: ")))
(ebib--filters-save-file file))))
+(defvar ebib-entry nil "Variable used to store an entry during filtering.
+See `ebib--filters-run-filter'.")
+
(defun ebib--filters-run-filter (db)
"Run the filter of DB and return a list of matching keys."
;; The filter uses a macro `contains', which we locally define here. This
- ;; macro in turn uses a dynamic variable `entry', which we must set
+ ;; macro in turn uses a dynamic variable `ebib-entry', which we must set
;; before eval'ing the filter.
(let ((filter (ebib-db-get-filter db)))
(eval
`(cl-macrolet ((contains (field regexp)
- `(ebib--search-in-entry ,regexp entry ,(unless (cl-equalp field "any") field))))
+ `(ebib--search-in-entry ,regexp ebib-entry ,(unless (cl-equalp field "any") field))))
(delq nil (mapcar (lambda (key)
- (let ((entry (ebib-db-get-entry key db 'noerror)))
+ (let ((ebib-entry (ebib-db-get-entry key db 'noerror)))
(when ,filter
key)))
(ebib-db-list-keys db)))))))
@@ -353,7 +356,7 @@ be a list of the format returned by `current-time' and is
compared to the timestamp of the entry being tested. If the
entry has no timestamp, or a timestamp that cannot be converted
into a date representation, return nil."
- (let ((timestamp (cdr (assoc-string "timestamp" entry))))
+ (let ((timestamp (cdr (assoc-string "timestamp" ebib-entry))))
(when (and timestamp
(setq timestamp (ignore-errors (date-to-time timestamp))))
(time-less-p date timestamp))))
diff --git a/ebib-keywords.el b/ebib-keywords.el
index d5d4530..da3fe54 100644
--- a/ebib-keywords.el
+++ b/ebib-keywords.el
@@ -1,6 +1,6 @@
;;; ebib-keywords.el --- Part of Ebib, a BibTeX database manager -*- lexical-binding: t -*-
-;; Copyright (c) 2003-2018 Joost Kremers
+;; Copyright (c) 2003-2019 Joost Kremers
;; All rights reserved.
;; Author: Joost Kremers <joostkremers@fastmail.fm>
@@ -37,7 +37,6 @@
;;; Code:
(require 'cl-lib)
-(require 'dash)
(require 'ebib-utils)
(require 'ebib-db)
@@ -145,7 +144,9 @@ Note: KEYWORDS should be unbraced."
KEYWORDS is a list of keywords. The return value is a list of
keywords that do not exist in DB."
(let ((all-keywords (ebib--keywords-for-database db)))
- (--remove (member-ignore-case it all-keywords) keywords)))
+ (seq-remove (lambda (elt)
+ (member-ignore-case elt all-keywords))
+ keywords)))
(defun ebib--keywords-for-database (db)
"Return the list of keywords for database DB.
diff --git a/ebib-notes.el b/ebib-notes.el
index 6c0cd14..e5559ce 100644
--- a/ebib-notes.el
+++ b/ebib-notes.el
@@ -1,6 +1,6 @@
;;; ebib-notes.el --- Part of Ebib, a BibTeX database manager -*- lexical-binding: t -*-
-;; Copyright (c) 2003-2018 Joost Kremers
+;; Copyright (c) 2003-2019 Joost Kremers
;; All rights reserved.
;; Author: Joost Kremers <joostkremers@fastmail.fm>
@@ -170,6 +170,15 @@ string where point should be located."
(ebib--notes-locate-note key)))
(file-readable-p (ebib--create-notes-file-name key))))
+(defun ebib-notes-display-note-symbol (_field key _db)
+ "Return the note symbol for displaying if a note exists for KEY."
+ (if (ebib--notes-exists-note key)
+ (propertize ebib-notes-symbol
+ 'face '(:height 0.8 :inherit link)
+ 'mouse-face 'highlight)
+ (propertize (make-string (string-width ebib-notes-symbol) ?\s)
+ 'face '(:height 0.8))))
+
;;; One file per note.
(defun ebib--create-notes-file-name (key)
diff --git a/ebib-reading-list.el b/ebib-reading-list.el
index dc6b952..61c6d03 100644
--- a/ebib-reading-list.el
+++ b/ebib-reading-list.el
@@ -1,6 +1,6 @@
;;; ebib-reading-list.el --- Part of Ebib, a BibTeX database manager -*- lexical-binding: t -*-
-;; Copyright (c) 2003-2018 Joost Kremers
+;; Copyright (c) 2003-2019 Joost Kremers
;; All rights reserved.
;; Author: Joost Kremers <joostkremers@fastmail.fm>
@@ -38,6 +38,8 @@
(require 'ebib-utils)
+(declare-function org-get-todo-state "org.el")
+
(defgroup ebib-reading-list nil "Settings for the reading list." :group 'ebib)
(defcustom ebib-reading-list-symbol "R"
diff --git a/ebib-utils.el b/ebib-utils.el
index 0b5a782..94bcba9 100644
--- a/ebib-utils.el
+++ b/ebib-utils.el
@@ -1,6 +1,6 @@
;;; ebib-utils.el --- Part of Ebib, a BibTeX database manager -*- lexical-binding: t -*-
-;; Copyright (c) 2003-2018 Joost Kremers
+;; Copyright (c) 2003-2019 Joost Kremers
;; All rights reserved.
;; Author: Joost Kremers <joostkremers@fastmail.fm>
@@ -37,8 +37,9 @@
;;; Code:
(require 'cl-lib)
-(require 'dash)
+(require 'seq)
(require 'bibtex)
+(require 'format-spec)
(require 'ebib-db)
;; Make a bunch of variables obsolete.
@@ -272,7 +273,7 @@ not change the default sort."
(defcustom ebib-field-transformation-functions '(("Title" . ebib-clean-TeX-markup)
("Doi" . ebib-display-www-link)
("Url" . ebib-display-www-link)
- ("Note" . ebib-display-note-symbol))
+ ("Note" . ebib-notes-display-note-symbol))
"Functions transforming field contents to appropriate forms.
Each function should accept three arguments, the field to be
displayed, the key of the entry being displayed, and the database
@@ -387,7 +388,7 @@ contains the entry."
:group 'ebib
:type '(choice (function-item :tag "Author/Year" ebib-author-year-description)
(function-item :tag "Title" ebib-title-description)
- (function :tag "Custom function")))
+ (function :tag "Custom Function")))
(defun ebib-author-year-description (key db)
"Provide an author/year description for an Org Ebib link.
@@ -408,6 +409,48 @@ database that contains the entry."
:group 'ebib
:type '(function :tag "Mode function"))
+(defcustom ebib-multiline-display-function 'ebib-multiline-display-as-is
+ "The way in which multiline field values are shown in the index buffer.
+By default, the value is shown as-is, but never more than
+`ebib-multiline-display-max-lines' lines. The option \"First
+Paragraph\" displays the first paragraph (also with a maximum of
+`ebib-multiline-display-max-lines' lines), but in addition
+refills the text, which is useful if you use long lines in your
+multiline values.
+
+It is possible to provide a custom function for this option.
+This function should take a (multiline) string as argument and
+return a list of lines to be displayed."
+ :group 'ebib
+ :type '(choice (function-item :tag "Show Value As-Is" ebib-multiline-display-as-is)
+ (function-item :tag "Show First Paragraph" ebib-multiline-display-paragraph)
+ (function :tag "Custom Function")))
+
+(defun ebib-multiline-display-as-is (string)
+ "Reduce the multiline text STRING.
+The text is split into lines and returned. No other
+modifications are made."
+ (split-string string "\n"))
+
+(defun ebib-multiline-display-paragraph (string)
+ "Reduce the multiline text STRING.
+The text is filled to account for the posibility that the
+original text is meant to be used with `visual-line-mode'.
+Return a list of strings, each a single line."
+ (split-string (with-temp-buffer
+ (insert string)
+ (goto-char (point-min))
+ (forward-paragraph)
+ (delete-region (point) (point-max))
+ (fill-region (point-min) (point-max))
+ (buffer-string))
+ "\n" t))
+
+(defcustom ebib-multiline-display-max-lines 10
+ "The maximum number of lines to display for multiline field values."
+ :group 'ebib
+ :type 'integer)
+
(defcustom ebib-sort-order nil
"The fields on which the BibTeX entries are to be sorted in the BibTeX file.
This option is described in the manual/info file in the section
@@ -855,7 +898,7 @@ Currently, the following problems are marked:
(defvar-local ebib--multiline-info nil "Information about the multiline text being edited.")
(defvar ebib--log-error nil "Indicates whether an error was logged.")
(defvar-local ebib--local-bibtex-filenames nil "A list of a buffer's .bib file(s)")
-(put 'ebib--local-bibtex-filenames 'safe-local-variable (lambda (v) (null (--remove (stringp it) v))))
+(put 'ebib--local-bibtex-filenames 'safe-local-variable (lambda (v) (null (seq-remove #'stringp v))))
;; The databases.
@@ -1235,7 +1278,7 @@ ignored."
(if (stringp string)
(string-match-p "\n" string)))
-(defsubst ebib--first-line (string)
+(defun ebib--first-line (string)
"Return the first line of a multiline STRING."
(car (split-string string "\n")))
@@ -1270,8 +1313,10 @@ form (\"<variable>\" \"<value>\"). If STR is not a local variable
block, the return value is nil."
(let ((vars (split-string str "[{}\n]+" t "[{} \t\r]+")))
(when (and (string= (car vars) "Local Variables:")
- (string= (-last-item vars) "End:"))
- (--map (split-string it ": " t "[ \t]+") (-slice vars 1 -1)))))
+ (string= (car (last vars)) "End:"))
+ (mapcar (lambda (elt)
+ (split-string elt ": " t "[ \t]+"))
+ (seq-subseq vars 1 -1)))))
(defun ebib--get-dialect (db)
"Get the dialect of DB.
@@ -1287,10 +1332,10 @@ DIALECT must be a symbol, possible values are listed in
`bibtex-dialect-list'. If OVERWRITE is non-nil, overwrite an
existing dialect variable, otherwise do nothing. The return
value is the (un)modified list."
- (let ((ind (--find-index (string= (car it) "bibtex-dialect") vars)))
- (if ind
+ (let ((item (seq-find (lambda (elt) (string= (car elt) "bibtex-dialect")) vars)))
+ (if item
(when overwrite
- (setq vars (-replace-at ind (list "bibtex-dialect" (symbol-name dialect)) vars)))
+ (setcdr item (list (symbol-name dialect))))
(setq vars (push (list "bibtex-dialect" (symbol-name dialect)) vars)))
vars))
@@ -1298,7 +1343,9 @@ value is the (un)modified list."
"Delete the dialect definition from VARS.
VARS is a list as returned by `ebib--local-vars-to-list'. VARS is
not modified, instead the new list is returned."
- (--remove (string= (car it) "bibtex-dialect") vars))
+ (seq-remove (lambda (elt)
+ (string= (car elt) "bibtex-dialect"))
+ vars))
;; The numeric prefix argument is 1 if the user gave no prefix argument at all.
;; The raw prefix argument is not always a number. So we need to do our own
@@ -1310,6 +1357,73 @@ argument to a function or not."
(when (numberp num)
num))
+;;; Functions for database access
+;;
+;; We can mostly use the ebib-db-* functions directly, but we don't want to handle
+;; the braces in `ebib-db.el', so we define some extra access functions here.
+
+(defun ebib--store-entry (entry-key fields db &optional timestamp if-exists)
+ "Store the entry defined by ENTRY-KEY and FIELDS into DB.
+Optional argument TIMESTAMP indicates whether a timestamp is to
+be added to the entry. Note that for a timestamp to be added,
+`ebib-use-timestamp' must also be set to T. IF-EXISTS is as for
+`ebib-db-set-entry'.
+
+Return ENTRY-KEY if storing the entry was succesful, nil
+otherwise. Depending on the value of IF-EXISTS, storing an entry
+may also result in an error."
+ (let ((result (ebib-db-set-entry entry-key fields db if-exists)))
+ (when (and result timestamp ebib-use-timestamp)
+ (ebib-set-field-value "timestamp" (format-time-string ebib-timestamp-format) entry-key db 'overwrite))
+ result))
+
+(defun ebib-set-field-value (field value key db &optional if-exists nobrace)
+ "Set FIELD to VALUE in entry KEY in database DB.
+
+IF-EXISTS determines what to do if the field already exists. If
+it is `overwrite', the existing value is overwritten. If it is
+`noerror', the value is not stored and the function returns nil.
+If it is nil (or any other value), an error is raised.
+
+IF-EXISTS can also be the symbol `append' or a string. In this
+case, the new value is appended to the old value, separated by a
+space or by the string. Before appending, braces/double quotes
+are removed from both values. Whether braces are added to the
+new value depends on the value of NOBRACE.
+
+If NOBRACE is t, the value is stored without braces. If it is
+nil, braces are added if not already present. NOBRACE may also be
+the symbol `as-is', in which case the value is stored as is.
+
+A field can be removed from the entry by passing nil as VALUE and
+setting IF-EXISTS to 'overwrite.
+
+Return t upon success, or nil if the value could not be stored."
+ (if (eq if-exists 'append)
+ (setq if-exists " "))
+ (let ((old-value (ebib-db-get-field-value field key db 'norerror)))
+ ;; If the field has a value, decide what to do:
+ (if old-value
+ (cond
+ ((eq if-exists 'overwrite)
+ (setq old-value nil))
+ ((stringp if-exists)
+ (setq value (concat (ebib-unbrace old-value) if-exists (ebib-unbrace value)))
+ (setq old-value nil))
+ ((not (eq if-exists 'noerror))
+ (error "[Ebib] Field `%s' exists in entry `%s'; cannot overwrite" field key))))
+ ;; If there is (still) an old value, do nothing.
+ (unless old-value
+ ;; Otherwise overwrite the existing entry. Note that to delete a field, we
+ ;; set its value to nil, rather than removing it altogether from the
+ ;; database. In `ebib--display-fields', such fields are ignored, and they're
+ ;; not saved.
+ (if (and value nobrace)
+ (unless (eq nobrace 'as-is)
+ (setq value (ebib-unbrace value)))
+ (setq value (ebib-brace value)))
+ (ebib-db-set-field-value field value key db 'overwrite))))
+
(defun ebib-get-field-value (field key db &optional noerror unbraced xref)
"Return the value of FIELD in entry KEY in database DB.
If FIELD or KEY does not exist, trigger an error, unless NOERROR
@@ -1330,7 +1444,7 @@ string has the text property `ebib--alias' with value t."
(xref-key)
(alias))
(when (and (not value) xref) ; Check if there's a cross-reference.
- (setq xref-key (ebib-db-unbrace (ebib-db-get-field-value "crossref" key db 'noerror)))
+ (setq xref-key (ebib-unbrace (ebib-db-get-field-value "crossref" key db 'noerror)))
(when xref-key
(let ((xref-db (ebib--find-db-for-key xref-key db)))
(when xref-db
@@ -1347,7 +1461,7 @@ string has the text property `ebib--alias' with value t."
(unless (= 0 (length value)) ; (length value) == 0 if value is nil or if value is "".
(setq value (copy-sequence value)) ; Copy the value so we can add text properties.
(when unbraced
- (setq value (ebib-db-unbrace value)))
+ (setq value (ebib-unbrace value)))
(when alias
(add-text-properties 0 1 '(ebib--alias t) value))
(when xref
@@ -1357,6 +1471,133 @@ string has the text property `ebib--alias' with value t."
(setq value noerror))
value))
+;; Functions for writing out Bib(La)TeX entries.
+(defun ebib--format-entry (key db &optional timestamp sort)
+ "Write entry KEY in DB into the current buffer in BibTeX format.
+If TIMESTAMP is non-nil and `ebib-use-timestamp' is set, a
+timestamp is added to the entry, possibly overwriting an existing
+timestamp. If SORT is non-nil, the fields are sorted before
+formatting the entry."
+ (let* ((entry (copy-alist (ebib-db-get-entry key db 'noerror)))
+ (type (cdr (assoc "=type=" entry))))
+ (when entry
+ (if (and timestamp ebib-use-timestamp)
+ (setcdr (assoc-string "timestamp" entry 'case-fold) (format-time-string (concat "{" ebib-timestamp-format "}"))))
+ (setq entry (seq-filter (lambda (field)
+ (and (cdr field) ; Remove fields with value nil. See `ebib-set-field-value'.
+ (not (ebib--special-field-p (car field)))))
+ entry))
+ (setq entry (if sort
+ (cl-sort entry #'string< :key #'car)
+ ;; When reading, fields are stored with `push', so if we don't
+ ;; sort, we need to reverse them to get the original order
+ ;; back. See github issues #42, #55, #62.
+ (reverse entry)))
+ (insert (format "@%s{%s,\n" type key))
+ (insert (mapconcat (lambda (field)
+ (format "\t%s = %s" (car field) (cdr field)))
+ entry
+ ",\n"))
+ (insert "\n}\n\n"))))
+
+(defun ebib--format-comments (db)
+ "Write the @COMMENTS of DB into the current buffer in BibTeX format."
+ (mapc (lambda (c)
+ (insert (format "@Comment%s\n\n" c)))
+ (ebib-db-get-comments db)))
+
+(defun ebib--format-strings (db)
+ "Write the @Strings of DB into the current buffer in BibTeX format."
+ (mapc (lambda (str)
+ (insert (format "@String{%s = %s}\n" (car str) (cdr str))))
+ (ebib-db-get-all-strings db))
+ (insert "\n"))
+
+(defun ebib--get-sortstring (entry-key sortkey-list db)
+ "Return the field value on which the entry ENTRY-KEY is to be sorted.
+SORTKEY-LIST is a list of fields that are considered in order for
+the sort value. DB is the database that contains the entry
+referred to by ENTRY-KEY."
+ (let ((sort-string nil))
+ (while (and sortkey-list
+ (null (setq sort-string (ebib-get-field-value (car sortkey-list) entry-key db 'noerror 'unbraced))))
+ (setq sortkey-list (cdr sortkey-list)))
+ sort-string))
+
+(defun ebib--format-local-vars (db)
+ "Write the local variables of DB into the current buffer."
+ (let ((lvars (ebib-db-get-local-vars db)))
+ (when lvars
+ (insert (concat "@Comment{\n"
+ ebib-local-variable-indentation "Local Variables:\n"
+ (mapconcat (lambda (e) (format "%s%s: %s\n" ebib-local-variable-indentation (car e) (cadr e))) lvars "")
+ ebib-local-variable-indentation "End:\n"
+ "}\n\n")))))
+
+(defun ebib--format-database-as-bibtex (db)
+ "Write database DB into the current buffer in BibTeX format."
+ (ebib--format-comments db)
+ (when (ebib-db-get-preamble db)
+ (insert (format "@Preamble{%s}\n\n" (ebib-db-get-preamble db))))
+ (ebib--format-strings db)
+ ;; We define two comparison functions for `sort'. These must simply
+ ;; return non-NIL if the first element is to be sorted before the second.
+ (cl-flet
+ ;; The first one is simple: if X has a crossref field, it must be
+ ;; sorted before Y (or at least *can* be, if Y also has a crossref
+ ;; field).
+ ((compare-xrefs (x _)
+ (ebib-get-field-value "crossref" x db 'noerror))
+ ;; This one's a bit trickier. We iterate over the lists of fields in
+ ;; `ebib-sort-order'. For each level, `ebib--get-sortstring' then returns the
+ ;; string that can be used for sorting. If all fails, sorting is done on
+ ;; the basis of the entry key.
+ (entry< (x y)
+ (let (sortstring-x sortstring-y)
+ (cl-loop for sort-list in ebib-sort-order do
+ (setq sortstring-x (ebib--get-sortstring x sort-list db))
+ (setq sortstring-y (ebib--get-sortstring y sort-list db))
+ while (cl-equalp sortstring-x sortstring-y))
+ (if (and sortstring-x sortstring-y)
+ (string< sortstring-x sortstring-y)
+ (string< x y))))) ; compare entry keys
+ ;; Only entries in visible the index buffer are saved, in case we're writing
+ ;; a filtered db to a new file.
+ (let ((sorted-list (sort (ebib-db-list-keys ebib--cur-db) #'string<)))
+ (cond
+ (ebib-save-xrefs-first
+ (setq sorted-list (sort sorted-list #'compare-xrefs)))
+ (ebib-sort-order
+ (setq sorted-list (sort sorted-list #'entry<))))
+ (mapc (lambda (key) (ebib--format-entry key db nil)) sorted-list))
+ (ebib--format-local-vars db)))
+
+(defun ebib--export-entries-to-db (entries target-db source-db)
+ "Export ENTRIES from SOURCE-DB to TARGET-DB.
+ENTRIES is a list of entry keys."
+ (let ((target-keys-list (ebib-db-list-keys target-db))
+ (modified nil))
+ (mapc (lambda (key)
+ (if (member key target-keys-list)
+ (ebib--log 'message "Entry key `%s' already exists in database %s" key (ebib-db-get-filename target-db 'short))
+ (ebib--store-entry key (copy-tree (ebib-db-get-entry key source-db)) target-db t)
+ (setq modified t)))
+ entries)
+ (when modified
+ (ebib-db-kill-buffer target-db)
+ (ebib-db-set-modified t target-db))))
+
+(defun ebib--export-entries-to-file (entries filename source-db)
+ "Export ENTRIES from SOURCE-DB to FILENAME.
+ENTRIES is a list of entry keys."
+ (with-temp-buffer
+ (insert "\n")
+ (mapc (lambda (key)
+ (ebib--format-entry key source-db nil))
+ entries)
+ (append-to-file (point-min) (point-max) filename)
+ (setq ebib--export-filename filename)))
+
(defun ebib--find-db-for-key (key db)
"Return the database containing KEY.
First see if KEY is in DB. If not, check all members of
@@ -1365,7 +1606,7 @@ nil."
(if (ebib-db-get-entry key db 'noerror)
db
(let ((dbs (reverse ebib--databases)))
- (while (and dbs (not (ebib-db-get-entry key (car dbs) 'noerror)))
+ (while (and dbs (not (ebib-db-has-key key (car dbs))))
(setq dbs (cdr dbs)))
(car dbs))))
@@ -1391,6 +1632,109 @@ inherit a value, this function returns nil."
(or (car (rassoc (downcase target-field) inheritance))
target-field))))
+;; ebib-set-string is just a front-end for `ebib-db-set-string'. The only additional
+;; functionality is that it wraps the string value in braces if it isn't
+;; already. We need to do this because the brace functions are in this file and
+;; `ebib-db.el' cannot depend on `ebib-utils.el' (because `ebib-utils.el' already depends on
+;; `ebib-db.el'). Similar considerations apply to `ebib-get-string' below.
+
+(defun ebib-set-string (abbr value db &optional overwrite)
+ "Set the @string definition ABBR to VALUE in database DB.
+If ABBR does not exist, create it. OVERWRITE functions as in
+`ebib-db-set-string'. VALUE is enclosed in braces if it isn't
+already.
+
+This function basically just calls `ebib-db-set-string' to do the
+ real work."
+ (ebib-db-set-string abbr (if (ebib-unbraced-p value)
+ (ebib-brace value)
+ value)
+ db overwrite))
+
+(defun ebib-get-string (abbr db &optional noerror unbraced)
+ "Return the value of @STRING definition ABBR in database DB.
+NOERROR functions as in `ebib-db-get-string', which this
+functions calls to get the actual value. The braces around the
+value are removed if UNBRACED is non-nil."
+ (let ((value (ebib-db-get-string abbr db noerror)))
+ (if unbraced
+ (ebib-unbrace value)
+ value)))
+
+;; EBIB-UNBRACED-P determines if STRING is enclosed in braces. Note that we
+;; cannot do this by simply checking whether STRING begins with { and ends with
+;; } (or begins and ends with "), because something like "{abc} # D # {efg}"
+;; would then be incorrectly recognised as braced. So we need to do the
+;; following: take out everything that is between braces or quotes, and see if
+;; anything is left. If there is, the original string was braced, otherwise it
+;; was not.
+
+;; So we first check whether the string begins with { or ". If not, we
+;; certainly have an unbraced string. (EBIB-UNBRACED-P recognises this
+;; through the default clause of the COND.) If the first character is { or ",
+;; we first take out every occurrence of backslash-escaped { and } or ", so that
+;; the rest of the function does not get confused over them.
+
+;; Then, if the first character is {, REMOVE-FROM-STRING takes out every
+;; occurrence of the regex "{[^{]*?}", which translates to "the smallest string
+;; that starts with { and ends with }, and does not contain another {. IOW, it
+;; takes out the innermost braces and their contents. Because braces may be
+;; embedded, we have to repeat this step until no more balanced braces are found
+;; in the string. (Note that it would be unwise to check for just the occurrence
+;; of { or }, because that would throw EBIB-UNBRACED-P in an infinite loop if
+;; a string contains an unbalanced brace.)
+
+;; For strings beginning with " we do the same, except that it is not
+;; necessary to repeat this in a WHILE loop, for the simple reason that
+;; strings surrounded with double quotes cannot be embedded; i.e.,
+;; "ab"cd"ef" is not a valid (BibTeX) string, while {ab{cd}ef} is.
+
+;; Note: because these strings are to be fed to BibTeX and ultimately
+;; (La)TeX, it might seem that we don't need to worry about strings
+;; containing unbalanced braces, because (La)TeX would choke on them. But
+;; the user may inadvertently enter such a string, and we therefore need to
+;; be able to handle it. (Alternatively, we could perform a check on
+;; strings and warn the user.)
+
+(defun ebib-unbraced-p (string)
+ "Non-nil if STRING is not enclosed in braces or quotes."
+ (cl-flet ((remove-from-string (string remove)
+ (apply #'concat (split-string string remove))))
+ (when (stringp string)
+ (cond
+ ((eq (string-to-char string) ?\{)
+ ;; first, remove all escaped { and } from the string:
+ (setq string (remove-from-string (remove-from-string string "[\\][{]")
+ "[\\][}]"))
+ ;; then remove the innermost braces with their contents and continue until
+ ;; no more braces are left.
+ (while (and (member ?\{ (string-to-list string)) (member ?\} (string-to-list string)))
+ (setq string (remove-from-string string "{[^{]*?}")))
+ ;; if STRING is not empty, the original string contains material not in braces
+ (> (length string) 0))
+ ((eq (string-to-char string) ?\")
+ ;; remove escaped ", then remove any occurrences of balanced quotes with
+ ;; their contents and check for the length of the remaining string.
+ (> (length (remove-from-string (remove-from-string string "[\\][\"]")
+ "\"[^\"]*?\""))
+ 0))
+ (t t)))))
+
+(defun ebib-unbrace (string)
+ "Convert STRING to its unbraced counterpart.
+If STRING is already unbraced, do nothing."
+ (if (and (stringp string)
+ (not (ebib-unbraced-p string)))
+ (substring string 1 -1)
+ string))
+
+(defun ebib-brace (string)
+ "Put braces around STRING.
+If STRING is already braced, do nothing."
+ (if (ebib-unbraced-p string)
+ (concat "{" string "}")
+ string))
+
(defun ebib--list-fields (entry-type type dialect)
"List the fields of ENTRY-TYPE.
TYPE specifies which fields to list. It is a symbol and can be
@@ -1416,7 +1760,9 @@ which ENTRY-TYPE is an alias."
(when (memq type '(optional extra all))
(setq optional (mapcar #'car (nth 4 (assoc-string entry-type (bibtex-entry-alist dialect) 'case-fold)))))
(when (memq type '(all extra))
- (setq extra (--remove (member-ignore-case it (append required optional)) (cdr (assq dialect ebib-extra-fields)))))
+ (setq extra (seq-remove (lambda (elt)
+ (member-ignore-case elt (append required optional)))
+ (cdr (assq dialect ebib-extra-fields)))))
(cond
((eq type 'required) required)
((eq type 'optional) optional)
@@ -1435,7 +1781,9 @@ in `bibtex-dialect-list' or NIL, in which case the value of
`ebib-bibtex-dialect' is used."
(or dialect (setq dialect ebib-bibtex-dialect))
(let ((fields (ebib--list-fields (cdr (assoc "=type=" entry)) 'all dialect)))
- (--remove (member-ignore-case (car it) (cons "=type=" fields)) entry)))
+ (seq-remove (lambda (elt)
+ (member-ignore-case (car elt) (cons "=type=" fields)))
+ entry)))
(defun ebib--list-entry-types (&optional dialect include-aliases)
"Return a list of entry types.
@@ -1461,7 +1809,7 @@ Possible values for DIALECT are those listed in
(or (cdr (assq dialect ebib--unique-field-alist))
(let (fields)
(mapc (lambda (entry)
- (setq fields (-union fields (ebib--list-fields (car entry) 'all dialect))))
+ (setq fields (seq-uniq (seq-concatenate 'list fields (ebib--list-fields (car entry) 'all dialect)))))
(bibtex-entry-alist dialect))
(push (cons dialect fields) ebib--unique-field-alist)
fields)))
@@ -1549,15 +1897,6 @@ are returned as a string."
'("A" "An" "At" "Of" "On" "And" "For"))))
str)))
-(defun ebib-display-note-symbol (_field key _db)
- "Return the note symbol for displaying if a note exists for KEY."
- (if (ebib--notes-exists-note key)
- (propertize ebib-notes-symbol
- 'face '(:height 0.8 :inherit link)
- 'mouse-face 'highlight)
- (propertize (make-string (string-width ebib-notes-symbol) ?\s)
- 'face '(:height 0.8))))
-
(defun ebib-display-www-link (field key db)
"Return the content of FIELD from KEY in DB as a link.
This function is mainly intended for the DOI and URL fields."
@@ -1597,10 +1936,7 @@ characters in fields."
(list (mapcar (lambda (key)
(cons (ebib--get-field-value-for-display field key db) key))
keys)))
- (setq list (cl-stable-sort list (if (fboundp 'string-collate-lessp)
- #'string-collate-lessp
- #'string-lessp)
- :key #'car))
+ (setq list (cl-stable-sort list #'string-collate-lessp :key #'car))
(setq keys (mapcar #'cdr list))
;; Reverse the list if necessary.
(if (eq direction 'descend)
diff --git a/ebib.el b/ebib.el
index df389a7..4bd36d8 100644
--- a/ebib.el
+++ b/ebib.el
@@ -1,14 +1,14 @@
;;; ebib.el --- a BibTeX database manager -*- lexical-binding: t -*-
-;; Copyright (c) 2003-2018 Joost Kremers
+;; Copyright (c) 2003-2019 Joost Kremers
;; All rights reserved.
;; Author: Joost Kremers <joostkremers@fastmail.fm>
;; Maintainer: Joost Kremers <joostkremers@fastmail.fm>
;; Created: 2003
-;; Version: 2.12
+;; Version: 2.15
;; Keywords: text bibtex
-;; Package-Requires: ((dash "2.5.0") (seq "2.15") (parsebib "2.3") (emacs "24.4"))
+;; Package-Requires: ((parsebib "2.3") (emacs "25.3"))
;; Redistribution and use in source and binary forms, with or without
;; modification, are permitted provided that the following conditions
@@ -51,10 +51,9 @@
(require 'cl-lib)
(require 'easymenu)
(require 'bibtex)
-(require 'subr-x) ; hash-table-keys
(require 'seq)
-(require 'dash)
(require 'pp)
+(require 'hl-line)
(require 'parsebib)
(require 'ebib-utils)
(require 'ebib-db)
@@ -88,9 +87,9 @@ can be found, return NIL."
(not (eq ebib-layout 'full)))
(setq window nil))
;; Find a buffer other than the index buffer that's being displayed.
- (t (setq window (let ((b (cdr (--find (and (not (eq (car it) 'index))
- (get-buffer-window (cdr it)))
- ebib--buffer-alist))))
+ (t (setq window (let ((b (cdr (seq-find (lambda (elt) (and (not (eq (car elt) 'index))
+ (get-buffer-window (cdr elt))))
+ ebib--buffer-alist))))
(if b (get-buffer-window b))))))
(when window
(select-window window)
@@ -210,22 +209,55 @@ If MARK is non-nil, `ebib-mark-face' is applied to the entry."
(with-current-ebib-buffer 'strings
(let ((inhibit-read-only t))
(let* ((string (ebib--current-string))
- (val (ebib-db-get-string string ebib--cur-db nil 'unbraced)))
+ (val (ebib-get-string string ebib--cur-db nil 'unbraced)))
(delete-region (point-at-bol) (point-at-eol))
(insert (format "%-18s %s" string
(if (ebib--multiline-p val)
(concat "+" (ebib--first-line val))
(concat " " val))))))))
+(defun ebib--make-multiline-display (string matched)
+ "Return a string for multiline field values to display in the entry buffer.
+STRING is the text to display. MATCHED indicates whether a
+search string match was found. If the text is longer than
+`ebib-multiline-display-max-lines' lines, it is truncated and a
+continuation marker \"[...]\" is added. If MATCHED is non-nil,
+this continuation marker is highlighted. Empty lines from the
+beginning and end of STRING are removed.
+
+This function calls the function in
+`ebib-multiline-display-function' to convert the text to a list
+of strings."
+ (let ((multilines (funcall ebib-multiline-display-function string))
+ (truncated nil))
+ (when (> (length multilines) ebib-multiline-display-max-lines)
+ (setq multilines (seq-subseq multilines 0 ebib-multiline-display-max-lines))
+ (setq truncated t))
+ (setq multilines (thread-last multilines
+ (seq-drop-while (lambda (elt) (string= elt "")))
+ (reverse)
+ (seq-drop-while (lambda (elt) (string= elt "")))
+ (reverse)))
+ (let ((first-line (car multilines))
+ (rest-lines (mapcar (lambda (line)
+ (concat (make-string 19 ?\s) line))
+ (cdr multilines))))
+ (cl-values (concat first-line
+ (if rest-lines
+ (concat "\n" (string-join rest-lines "\n"))))
+ (if truncated
+ (concat "\n" (make-string 19 ?\s)
+ (if matched
+ (propertize "[...]" 'face 'highlight)
+ "[...]")))))))
+
(defun ebib--get-field-highlighted (field key &optional db match-str)
"Return the contents of FIELD in entry KEY in DB with MATCH-STR highlighted."
- ;; Note: we need to work on a copy of the value, otherwise the highlights
- ;; are made to the value as stored in the database. Hence copy-sequence.
(or db (setq db ebib--cur-db))
(let* ((case-fold-search t)
(value (ebib-get-field-value field key db 'noerror nil 'xref))
+ (multiline "")
(raw " ")
- (multiline " ")
(matched nil)
(alias ""))
;; We have to do a couple of things now:
@@ -239,11 +271,11 @@ If MARK is non-nil, `ebib-mark-face' is applied to the entry."
(if (stringp (get-text-property 0 'ebib--xref value))
(setq value (propertize value 'face 'ebib-crossref-face 'fontified t)))
(if (and (member-ignore-case field '("crossref" "xref" "related"))
- (not (ebib-db-get-entry key db 'noerror)))
+ (not (ebib--find-db-for-key (ebib-unbrace value) ebib--cur-db)))
(setq value (propertize value 'face 'ebib-warning-face)))
(if (cl-equalp field "keywords")
- (let* ((unbraced (ebib-db-unbraced-p value))
- (keywords (ebib--keywords-to-list (ebib-db-unbrace value)))
+ (let* ((unbraced (ebib-unbraced-p value))
+ (keywords (ebib--keywords-to-list (ebib-unbrace value)))
(new-keywords (ebib--keywords-remove-existing keywords ebib--cur-db))
(new-value (mapconcat (lambda (keyword)
(if (member-ignore-case keyword new-keywords)
@@ -253,19 +285,15 @@ If MARK is non-nil, `ebib-mark-face' is applied to the entry."
ebib-keywords-separator)))
(setq value (if unbraced
new-value
- (ebib-db-brace new-value)))))
- (if (ebib-db-unbraced-p value)
+ (ebib-brace new-value)))))
+ (if (ebib-unbraced-p value)
(setq raw "*")
- (setq value (ebib-db-unbrace value))) ; We have to make the value look nice.
+ (setq value (ebib-unbrace value))) ; We have to make the value look nice.
(when match-str
(cl-multiple-value-setq (value matched) (ebib--match-all-in-string match-str value)))
(when (ebib--multiline-p value)
- (setq multiline (propertize "+" 'face nil)) ; Sometimes the face property persists.
- (setq value (ebib--first-line value)))
- (when (and matched
- (string= multiline "+"))
- (add-text-properties 0 1 '(face highlight) multiline)))
- (concat raw multiline value alias)))
+ (cl-multiple-value-setq (value multiline) (ebib--make-multiline-display value matched))))
+ (concat raw value alias multiline)))
(defun ebib--display-fields (key &optional db match-str)
"Display the fields of entry KEY in DB.
@@ -280,8 +308,8 @@ it is highlighted. DB defaults to the current database."
(req-fields (ebib--list-fields entry-type 'required dialect))
(opt-fields (ebib--list-fields entry-type 'optional dialect))
(extra-fields (ebib--list-fields entry-type 'extra dialect))
- (undef-fields (-remove #'ebib--special-field-p (mapcar #'car (ebib--list-undefined-fields (ebib-db-get-entry key db) dialect)))))
- (insert (format "%-19s %s%s\n"
+ (undef-fields (seq-remove #'ebib--special-field-p (mapcar #'car (ebib--list-undefined-fields (ebib-db-get-entry key db) dialect)))))
+ (insert (format "%-18s %s%s\n"
(propertize "type" 'face 'ebib-field-face)
(if (assoc-string entry-type (ebib--list-entry-types dialect t) 'case-fold)
entry-type
@@ -319,43 +347,73 @@ If point is not on a BibTeX entry, return nil."
(with-current-ebib-buffer 'index
(get-text-property (point) 'ebib-key)))
-(defun ebib--update-buffers ()
- "Redisplay the index and entry buffers."
- (ebib--update-index-buffer)
+(defun ebib--update-buffers (&optional no-index-refresh)
+ "Redisplay the index and entry buffers.
+The contents of both buffers are recreated, unless
+NO-INDEX-REFRESH is non-nil, in which case the index buffer is
+not recreated. Instead, the index buffer of `ebib--cur-db' is
+simply displayed. If `ebib--cur-db' has no index buffer yet, one
+is created.
+
+Note that NO-INDEX-REFRESH does not affect the entry buffer: its
+contents is recreated unconditionally."
+ (ebib--update-index-buffer no-index-refresh)
(ebib--update-entry-buffer))
-(defun ebib--update-index-buffer ()
- "Fill the index buffer with the list of keys in `ebib--cur-db'.
-If `ebib--cur-db' is nil, the buffer is just erased and its name set
-to \"none\"."
+(defun ebib--update-index-buffer (&optional no-refresh)
+ "Recreate the contents of the index buffer using the keys of `ebib--cur-db'.
+If `ebib--cur-db' is nil, the buffer is just erased and its name
+set to \"Ebib (no file)\". If NO-REFRESH is non-nil, display the
+index buffer associated with `ebib--cur-db' but do not refresh
+its contents. If NO-REFRESH in non-nil but `ebib--cur-db' does
+not have an associated index buffer, create an index buffer and
+fill it."
+ (let ((window (get-buffer-window (ebib--buffer 'index)))
+ (index-buffer (when ebib--cur-db
+ (ebib-db-get-buffer ebib--cur-db))))
+ (when (not index-buffer)
+ (setq index-buffer (ebib--get-or-create-index-buffer ebib--cur-db))
+ (setq no-refresh nil)) ; We just created the index buffer, so we need to fill it.
+ (setcdr (assq 'index ebib--buffer-alist) index-buffer)
+ (when window ; This function is also called from `ebib-import', in which case `window' would be nil.
+ (with-selected-window window
+ (with-ebib-window-nondedicated
+ (switch-to-buffer index-buffer))))
+ (with-current-ebib-buffer 'index
+ (unless no-refresh
+ (let ((inhibit-read-only t))
+ (erase-buffer)
+ (when ebib--cur-db
+ (let ((cur-keys-list (ebib--list-keys))
+ (marked-entries (ebib-db-list-marked-entries ebib--cur-db))
+ (cur-entry (ebib--db-get-current-entry-key ebib--cur-db)))
+ ;; We may call this function when there are no entries in the
+ ;; database. If so, we don't need to do this:
+ (unless (= 0 (ebib-db-count-entries ebib--cur-db))
+ ;; It may be that no entry satisfies the filter.
+ (if (not cur-keys-list)
+ (message "No entries matching the filter")
+ ;; Fill the buffer
+ (dolist (entry cur-keys-list)
+ (ebib--display-entry-key entry (member entry marked-entries)))
+ ;; Make sure the current entry is among the visible entries.
+ (unless (member cur-entry cur-keys-list)
+ (setq cur-entry (car cur-keys-list)))
+ (if cur-entry
+ (ebib--goto-entry-in-index cur-entry)
+ (goto-char (point-min)))
+ (hl-line-highlight)))))))
+ (ebib--rename-index-buffer))))
+
+(defun ebib--rename-index-buffer ()
+ "Rename the index buffer."
(with-current-ebib-buffer 'index
- (let ((inhibit-read-only t)
- (new-buf-name " none"))
- (erase-buffer)
- (when ebib--cur-db
- (setq new-buf-name (concat (format " %d:" (1+ (- (length ebib--databases)
- (length (member ebib--cur-db ebib--databases)))))
- (ebib-db-get-filename ebib--cur-db 'shortened)))
- (let ((cur-keys-list (ebib--list-keys))
- (marked-entries (ebib-db-list-marked-entries ebib--cur-db))
- (cur-entry (ebib--db-get-current-entry-key ebib--cur-db)))
- ;; We may call this function when there are no entries in the
- ;; database. If so, we don't need to do this:
- (unless (= 0 (ebib-db-count-entries ebib--cur-db))
- ;; It may be that no entry satisfies the filter.
- (if (not cur-keys-list)
- (message "No entries matching the filter")
- ;; Fill the buffer.
- (dolist (entry cur-keys-list)
- (ebib--display-entry-key entry (member entry marked-entries)))
- ;; Make sure the current entry is among the visible entries.
- (unless (member cur-entry cur-keys-list)
- (setq cur-entry (car cur-keys-list)))
- (if cur-entry
- (ebib--goto-entry-in-index cur-entry)
- (goto-char (point-min)))
- (hl-line-highlight)))))
- (rename-buffer new-buf-name))))
+ (rename-buffer (or (and ebib--cur-db
+ (concat (format " %d:" (1+ (- (length ebib--databases)
+ (length (member ebib--cur-db ebib--databases)))))
+ (ebib-db-get-filename ebib--cur-db 'short)))
+ " Ebib (no file)")
+ 'unique)))
(defun ebib--update-entry-buffer (&optional match-str)
"Fill the entry buffer with the fields of the current entry.
@@ -397,33 +455,27 @@ Returns the first modified database, or NIL if none was modified."
(setq ebib--databases (append ebib--databases (list new-db)))
new-db))
-(defun ebib--store-entry (entry-key fields db &optional timestamp if-exists)
- "Store the entry defined by ENTRY-KEY and FIELDS into DB.
-Optional argument TIMESTAMP indicates whether a timestamp is to
-be added to the entry. Note that for a timestamp to be added,
-`ebib-use-timestamp' must also be set to T. IF-EXISTS is as for
-`ebib-db-set-entry'.
-
-Return ENTRY-KEY if storing the entry was succesful, nil
-otherwise. Depending on the value of IF-EXISTS, storing an entry
-may also result in an error."
- (let ((result (ebib-db-set-entry entry-key fields db if-exists)))
- (when result
- (ebib--set-modified t db)
- (when (and timestamp ebib-use-timestamp)
- (ebib-db-set-field-value "timestamp" (format-time-string ebib-timestamp-format) entry-key db 'overwrite)))
- result))
-
-(defun ebib--list-keys ()
- "Return a list of entry keys in the current database.
+(defun ebib--list-keys (&optional db)
+ "Return a list of entry keys in DB.
If a filter is active, only the keys of entries that match the
-filter are returned. The returned list is sorted."
- (when ebib--cur-db
- (let ((keys (if (ebib-db-get-filter ebib--cur-db)
- (ebib--filters-run-filter ebib--cur-db)
- (ebib-db-list-keys ebib--cur-db))))
- (ebib--sort-keys-list keys ebib--cur-db))))
-
+filter are returned. The returned list is sorted. DB defaults
+to the current database."
+ (or db (setq db ebib--cur-db))
+ (let ((keys (if (ebib-db-get-filter db)
+ (ebib--filters-run-filter db)
+ (ebib-db-list-keys db))))
+ (ebib--sort-keys-list keys db)))
+
+(defun ebib-read-database (prompt)
+ "Read the filename of a database, with completion.
+The filenames of the databases in `ebib--databases' are offered
+for completion, the database associated with the selected
+filename is returned. PROMPT is a string used to prompt the
+user."
+ (ebib--get-db-from-filename (completing-read prompt (mapcar (lambda (s)
+ (ebib-db-get-filename s 'shortened))
+ ebib--databases)
+ nil t)))
;;; Main
;;;###autoload
@@ -506,7 +558,7 @@ the buffers and loads the files in `ebib-preload-bib-files'."
(when ebib-preload-bib-files
(mapc (lambda (file)
(ebib--load-bibtex-file-internal (or (locate-file file ebib-bib-search-dirs)
- (expand-file-name file))))
+ (expand-file-name file))))
ebib-preload-bib-files)
(setq ebib--cur-db (car ebib--databases))) ; Display the first database in the list.
(setq ebib--initialized t))
@@ -553,7 +605,7 @@ window and make the frame active,"
(with-current-ebib-buffer 'entry
(ebib-entry-mode)
(buffer-disable-undo))
- ;; Then we create a buffer to hold the @STRING definitions.
+ ;; Then we create a buffer to hold the @String definitions.
(push (cons 'strings (get-buffer-create "*Ebib-strings*")) ebib--buffer-alist)
(with-current-ebib-buffer 'strings
(ebib-strings-mode)
@@ -566,12 +618,24 @@ window and make the frame active,"
(ebib-log-mode)
(buffer-disable-undo))
;; And lastly we create a buffer for the entry keys.
- (push (cons 'index (get-buffer-create " none")) ebib--buffer-alist)
- (with-current-ebib-buffer 'index
- (ebib-index-mode)
- (buffer-disable-undo)
- (if ebib-index-mode-line
- (setq mode-line-format ebib-index-mode-line))))
+ (push (cons 'index (ebib--get-or-create-index-buffer)) ebib--buffer-alist))
+
+(defun ebib--get-or-create-index-buffer (&optional db)
+ "Create an index buffer for DB.
+If DB already has an index buffer, return it instead. If DB is
+nil, get or create a buffer named \" Ebib (no file)\". Return
+the new buffer."
+ (let ((buffer (if db
+ (or (ebib-db-get-buffer db)
+ (get-buffer-create (ebib-db-get-filename db 'short)))
+ (get-buffer-create " Ebib (no file)"))))
+ (with-current-buffer buffer
+ (ebib-index-mode)
+ (if ebib-index-mode-line
+ (setq mode-line-format ebib-index-mode-line)))
+ (when db
+ (ebib-db-set-buffer buffer db))
+ buffer))
(defun ebib-force-quit ()
"Force quit Ebib by call `ebib-quit'."
@@ -595,6 +659,10 @@ ask for confirmation."
(mapc (lambda (x)
(kill-buffer (cdr x)))
ebib--buffer-alist)
+ (mapc (lambda (db)
+ (let ((buf (ebib-db-get-buffer db)))
+ (when buf (kill-buffer buf))))
+ ebib--databases)
(setq ebib--databases nil
ebib--cur-db nil
ebib--buffer-alist nil
@@ -627,7 +695,8 @@ keywords before Emacs is killed."
(defun ebib--kill-multiline-query-function ()
"Function to call when killing a multiline edit buffer."
- (if (and ebib-multiline-mode
+ (if (and (with-no-warnings ; `ebib-multiline-mode' is not defined yet.
+ ebib-multiline-mode)
(buffer-modified-p))
(yes-or-no-p (format "Multiline edit buffer `%s' not saved. Quit anyway? " (buffer-name)))
t))
@@ -694,7 +763,7 @@ keywords before Emacs is killed."
(define-key map "S" #'ebib-edit-strings)
(define-key map "u" #'ebib-browse-url)
(define-key map "w" #'ebib-write-database)
- (define-key map "x" #'ebib-export-entry) ; prefix
+ (define-key map "x" #'ebib-export-entries) ; prefix
(define-key map "\C-xb" #'ebib-leave-ebib-windows)
(define-key map "\C-xk" #'ebib-quit)
(define-key map "X" #'ebib-export-preamble)
@@ -725,6 +794,7 @@ character ?1-?9, which is converted to the corresponding number."
(if ebib-hide-cursor
(setq cursor-type nil))
(setq truncate-lines t)
+ (setq default-directory "~/") ; Make sure Ebib always thinks it's in $HOME.
(set (make-local-variable 'hl-line-face) 'ebib-highlight-face)
(hl-line-mode 1))
@@ -802,7 +872,7 @@ character ?1-?9, which is converted to the corresponding number."
"Open the BibTeX file FILE."
(interactive)
(unless file
- (setq file (ebib--ensure-extension (expand-file-name (read-file-name "File to open: " "~/")) (car ebib-bibtex-extensions))))
+ (setq file (ebib--ensure-extension (expand-file-name (read-file-name "File to open: ")) (car ebib-bibtex-extensions))))
(ebib--load-bibtex-file-internal file)
(ebib--update-buffers))
@@ -861,8 +931,11 @@ FILE must be a fully expanded filename."
"Reload database DB from disk."
(let ((file (ebib-db-get-filename db))
(cur-key (ebib--db-get-current-entry-key db)))
- ;; First clear out some variables.
- (ebib-db-clear-database db)
+ ;; First clear out the database. Note that this does not destroy DB's
+ ;; index buffer, which is good, because we want to re-use it.
+ (let ((buffer (ebib-db-get-buffer db)))
+ (ebib-db-clear-database db)
+ (ebib-db-set-buffer buffer db))
;; Then load the file.
(ebib--log 'log "%s: Reloading file %s" (format-time-string "%d-%b-%Y: %H:%M:%S") file)
(ebib-db-set-filename file db)
@@ -899,7 +972,7 @@ unless IGNORE-MODTIME is non-nil."
(ebib-db-set-dialect (parsebib-find-bibtex-dialect) db))
(let ((result (ebib--find-bibtex-entries db nil)))
;; Log the results.
- (ebib--log 'message "%d entries, %d @STRINGs and %s @PREAMBLE found in file."
+ (ebib--log 'message "%d entries, %d @Strings and %s @Preamble found in file."
(car result)
(cadr result)
(if (nth 2 result)
@@ -913,8 +986,8 @@ unless IGNORE-MODTIME is non-nil."
The search is started at the beginnig of the buffer. All entries
found are stored in DB. Return value is a three-element list: the
first element is the number of entries found, the second the
-number of @STRING definitions, and the third is T or NIL,
-indicating whether a @PREAMBLE was found.
+number of @String definitions, and the third is T or NIL,
+indicating whether a @Preamble was found.
TIMESTAMP indicates whether a timestamp is to be added to each
entry. Note that a timestamp is only added if `ebib-use-timestamp'
@@ -968,21 +1041,21 @@ DB."
(ebib-db-set-comment comment db))))))
(defun ebib--read-string (db)
- "Read an @STRING definition and store it in DB.
+ "Read an @String definition and store it in DB.
Return value is the string if one was read, nil otherwise."
(let* ((def (parsebib-read-string))
(abbr (car def))
(string (cdr def)))
(if def
- (if (ebib-db-set-string abbr string db 'noerror)
+ (if (ebib-set-string abbr string db)
string
- (ebib--log 'warning (format "Line %d: @STRING definition `%s' duplicated. Skipping."
- (line-number-at-pos) abbr)))
+ (ebib--log 'warning (format "Line %d: @String definition `%s' duplicated. Skipping."
+ (line-number-at-pos) abbr)))
(ebib--log 'error "Error: illegal string identifier at line %d. Skipping" (line-number-at-pos)))))
(defun ebib--read-preamble (db)
- "Read a @PREAMBLE definition and store it in DB.
-If there was already another @PREAMBLE definition, the new one is
+ "Read a @Preamble definition and store it in DB.
+If there was already another @Preamble definition, the new one is
added to the existing one with a hash sign `#' between them."
(let ((preamble (substring (parsebib-read-preamble) 1 -1))) ; We need to remove the braces around the text.
(if preamble
@@ -1000,7 +1073,8 @@ be added. (Whether a timestamp is actually added also depends on
(when (string= entry-key "")
(setq entry-key (ebib--generate-tempkey db))
(ebib--log 'warning "Line %d: Temporary key generated for entry." (line-number-at-pos beg)))
- (unless (ebib--store-entry entry-key entry db timestamp (if ebib-uniquify-keys 'uniquify 'noerror))
+ (if (ebib--store-entry entry-key entry db timestamp (if ebib-uniquify-keys 'uniquify 'noerror))
+ (ebib--set-modified t)
(ebib--log 'warning "Line %d: Entry `%s' duplicated. Skipping." (line-number-at-pos beg) entry-key))
entry-key)) ; Return the entry key.
@@ -1069,13 +1143,14 @@ interactively."
(beep))))
(defun ebib-show-annotation ()
- "Show the contents of the `annote' field in a *Help* window."
+ "Show the contents of the `annote' or `annotation' field in a *Help* window."
(interactive)
- (let ((help-window-select t)) ; Make sure the help window is selected.
+ (let ((help-window-select t) ; Make sure the help window is selected.
+ (field (cdr (assq (ebib-db-get-dialect ebib--cur-db) '((BibTeX . "annote") (biblatex . "annotation"))))))
(with-help-window (help-buffer)
(princ (propertize (format "Annotation for `%s' [%s]" (ebib--get-key-at-point) (ebib-db-get-filename ebib--cur-db 'shortened)) 'face '(:weight bold)))
(princ "\n\n")
- (let ((contents (ebib-get-field-value "annotation" (ebib--get-key-at-point) ebib--cur-db 'noerror 'unbraced)))
+ (let ((contents (ebib-get-field-value field (ebib--get-key-at-point) ebib--cur-db 'noerror 'unbraced)))
(if contents
(princ contents)
(princ "[No annotation]"))))))
@@ -1114,9 +1189,9 @@ is replaced with a number in ascending sequence."
(push props fields))
((cl-equalp (car props) ebib-file-field)
(let ((short-file (ebib--file-relative-name (expand-file-name (cdr props)))))
- (push (cons ebib-file-field (ebib-db-brace short-file)) fields)))
+ (push (cons ebib-file-field (ebib-brace short-file)) fields)))
(t
- (push (cons (car props) (ebib-db-brace (cdr props))) fields))))
+ (push (cons (car props) (ebib-brace (cdr props))) fields))))
;; Check for required.
(unless entry-key
(setq entry-key (ebib--generate-tempkey db)))
@@ -1124,6 +1199,7 @@ is replaced with a number in ascending sequence."
(push (cons "=type=" ebib-default-entry-type) fields))
;; Insert.
(ebib--store-entry entry-key fields db t ebib-uniquify-keys)
+ (ebib--set-modified t)
entry-key))
(defun ebib-add-entry ()
@@ -1250,33 +1326,45 @@ Keys are in the form: <new-entry1>, <new-entry2>, ..."
(mapc (lambda (buffer)
(unless (kill-buffer buffer)
(throw 'return nil)))
- (--filter (string= (ebib-db-get-filename ebib--cur-db) (cl-second (buffer-local-value 'ebib--multiline-info it)))
- ebib--multiline-buffer-list))
+ (seq-filter (lambda (elt)
+ (string= (ebib-db-get-filename ebib--cur-db)
+ (cl-second (buffer-local-value 'ebib--multiline-info elt))))
+ ebib--multiline-buffer-list))
;; Save keywords.
(ebib--keywords-save-new-keywords ebib--cur-db)
- ;; Remove the database from `ebib--databases' and redisplay.
- (let ((new-db (ebib--next-elem ebib--cur-db ebib--databases)))
+ ;; Remove the database from `ebib--databases', redisplay and kill the index buffer.
+ (let ((new-db (ebib--next-elem ebib--cur-db ebib--databases))
+ (index-buffer (ebib-db-get-buffer ebib--cur-db)))
(setq ebib--databases (delq ebib--cur-db ebib--databases))
(setq ebib--cur-db (if ebib--databases ; Do we still have another database loaded?
- (or new-db (-last-item ebib--databases))
+ (or new-db (car (last ebib--databases)))
nil))
- (ebib--update-buffers)
+ (ebib--update-buffers 'no-refresh)
+ (kill-buffer index-buffer)
(message "Database closed."))))))
(defun ebib-index-sort-ascending (field)
"Sort the entries in the index buffer in ascending order.
Sort key is FIELD, which must be one of the fields specified in
`ebib-index-columns'."
- (interactive (list (completing-read "Sort field (ascending): " (-map #'car (--filter (nth 2 it) ebib-index-columns)) nil t nil 'ebib--field-history)))
+ (interactive (list (completing-read "Sort field (ascending): " (mapcar #'car
+ (seq-filter (lambda (elt)
+ (nth 2 elt))
+ ebib-index-columns))
+ nil t nil 'ebib--field-history)))
(ebib--index-sort field 'ascend))
(defun ebib-index-sort-descending (field)
"Sort the entries in the index buffer in descending order.
Sort key is FIELD, which must be one of the fields specified in
`ebib-index-columns'."
- (interactive (list (completing-read "Sort field (descending): " (-map #'car (--filter (nth 2 it) ebib-index-columns)) nil t nil 'ebib--field-history)))
+ (interactive (list (completing-read "Sort field (descending): " (mapcar #'car
+ (seq-filter (lambda (elt)
+ (nth 2 elt))
+ ebib-index-columns))
+ nil t nil 'ebib--field-history)))
(ebib--index-sort field 'descend))
(defun ebib--index-sort (field order)
@@ -1417,104 +1505,6 @@ all entries are marked."
((default)
(beep))))
-(defun ebib--format-entry (key db &optional timestamp sort)
- "Write entry KEY in DB into the current buffer in BibTeX format.
-If TIMESTAMP is non-nil and `ebib-use-timestamp' is set, a
-timestamp is added to the entry, possibly overwriting an existing
-timestamp. If SORT is non-nil, the fields are sorted before
-formatting the entry."
- (let ((entry (ebib-db-get-entry key db 'noerror)))
- (setq entry (if sort
- (cl-sort (copy-sequence entry) #'string< :key #'car)
- ;; When reading, fields are stored with `push', so if we don't
- ;; sort, we need to reverse them to get the original order
- ;; back. See github issues #42, #55, #62.
- (reverse entry)))
- (when entry
- (insert (format "@%s{%s,\n" (cdr (assoc "=type=" entry)) key))
- (mapc (lambda (field)
- (unless (or (not (cdr field)) ; Deleted fields have their value set to nil. See `ebib-db-set-field-value'.
- (ebib--special-field-p (car field))
- (and (cl-equalp (car field) "timestamp") timestamp ebib-use-timestamp))
- (insert (format "\t%s = %s,\n" (car field) (cdr field)))))
- entry)
- (if (and timestamp ebib-use-timestamp)
- (insert (format "\ttimestamp = {%s}" (format-time-string ebib-timestamp-format)))
- (delete-char -2)) ; The final ",\n" must be deleted.
- (insert "\n}\n\n"))))
-
-(defun ebib--format-comments (db)
- "Write the @COMMENTS of DB into the current buffer in BibTeX format."
- (mapc (lambda (c)
- (insert (format "@Comment%s\n\n" c)))
- (ebib-db-get-comments db)))
-
-(defun ebib--format-strings (db)
- "Write the @STRINGs of DB into the current buffer in BibTeX format."
- (mapc (lambda (str)
- (insert (format "@STRING{%s = %s}\n" (car str) (cdr str))))
- (ebib-db-get-all-strings db))
- (insert "\n"))
-
-(defun ebib--get-sortstring (entry-key sortkey-list db)
- "Return the field value on which the entry ENTRY-KEY is to be sorted.
-SORTKEY-LIST is a list of fields that are considered in order for
-the sort value. DB is the database that contains the entry
-referred to by ENTRY-KEY."
- (let ((sort-string nil))
- (while (and sortkey-list
- (null (setq sort-string (ebib-get-field-value (car sortkey-list) entry-key db 'noerror 'unbraced))))
- (setq sortkey-list (cdr sortkey-list)))
- sort-string))
-
-(defun ebib--format-local-vars (db)
- "Write the local variables of DB into the current buffer."
- (let ((lvars (ebib-db-get-local-vars db)))
- (when lvars
- (insert (concat "@Comment{\n"
- ebib-local-variable-indentation "Local Variables:\n"
- (mapconcat (lambda (e) (format "%s%s: %s\n" ebib-local-variable-indentation (car e) (cadr e))) lvars "")
- ebib-local-variable-indentation "End:\n"
- "}\n\n")))))
-
-(defun ebib--format-database-as-bibtex (db)
- "Write database DB into the current buffer in BibTeX format."
- (ebib--format-comments db)
- (when (ebib-db-get-preamble db)
- (insert (format "@Preamble{%s}\n\n" (ebib-db-get-preamble db))))
- (ebib--format-strings db)
- ;; We define two comparison functions for `sort'. These must simply
- ;; return non-NIL if the first element is to be sorted before the second.
- (cl-flet
- ;; The first one is simple: if X has a crossref field, it must be
- ;; sorted before Y (or at least *can* be, if Y also has a crossref
- ;; field).
- ((compare-xrefs (x _)
- (ebib-get-field-value "crossref" x db 'noerror))
- ;; This one's a bit trickier. We iterate over the lists of fields in
- ;; `ebib-sort-order'. For each level, `ebib--get-sortstring' then returns the
- ;; string that can be used for sorting. If all fails, sorting is done on
- ;; the basis of the entry key.
- (entry< (x y)
- (let (sortstring-x sortstring-y)
- (cl-loop for sort-list in ebib-sort-order do
- (setq sortstring-x (ebib--get-sortstring x sort-list db))
- (setq sortstring-y (ebib--get-sortstring y sort-list db))
- while (cl-equalp sortstring-x sortstring-y))
- (if (and sortstring-x sortstring-y)
- (string< sortstring-x sortstring-y)
- (string< x y))))) ; compare entry keys
- ;; Only entries in visible the index buffer are saved, in case we're writing
- ;; a filtered db to a new file.
- (let ((sorted-list (sort (ebib-db-list-keys ebib--cur-db) #'string<)))
- (cond
- (ebib-save-xrefs-first
- (setq sorted-list (sort sorted-list #'compare-xrefs)))
- (ebib-sort-order
- (setq sorted-list (sort sorted-list #'entry<))))
- (mapc (lambda (key) (ebib--format-entry key db nil)) sorted-list))
- (ebib--format-local-vars db)))
-
(defun ebib--make-backup (file)
"Create a backup of FILE.
Honour `ebib-create-backups' and BACKUP-DIRECTORY-ALIST."
@@ -1561,7 +1551,7 @@ unconditionally, even if the new file already exists."
(interactive "P")
(ebib--execute-when
((database)
- (ebib--ifstring (new-filename (expand-file-name (read-file-name "Save to file: " "~/")))
+ (ebib--ifstring (new-filename (expand-file-name (read-file-name "Save to file: ")))
(when (or force
(not (file-exists-p new-filename))
(y-or-n-p (format (format "File %s already exists; overwrite? " new-filename))))
@@ -1613,32 +1603,6 @@ file was modified."
(interactive)
(message (ebib-db-get-filename ebib--cur-db)))
-(defun ebib-follow-crossref ()
- "Follow the crossref field and jump to that entry.
-If the current entry's crossref field is empty, search for the
-first entry with the current entry's key in its crossref field."
- (interactive)
- (let ((xref (ebib-get-field-value "crossref" (ebib--get-key-at-point) ebib--cur-db 'noerror 'unbraced)))
- (if xref
- ;; If the entry has a crossref, see if we can find the relevant entry.
- (let ((database (seq-find (lambda (db)
- (ebib-db-get-entry xref db 'noerror))
- ebib--databases)))
- (unless database
- (error "[Ebib] Entry `%s' not found in any open database" xref))
- ;; If the entry exists, switch to the relevant database and try to
- ;; show the entry.
- (ebib-switch-to-database database)
- (if (not (ebib--key-in-index-p xref))
- (error "[Ebib] Crossreference `%s' not visible due to active filter" xref)
- (ebib--goto-entry-in-index xref)
- (ebib--update-entry-buffer)))
- ;; If the entry has no crossref, we assume the user wants to search for
- ;; entries cross-referencing the current one.
- (setq ebib--search-string (ebib--get-key-at-point))
- (set-transient-map ebib-search-map t (lambda () (message "Search ended. Use `C-u /' to resume.")))
- (ebib-search-next))))
-
(defun ebib-toggle-hidden ()
"Toggle viewing hidden fields."
(interactive)
@@ -1785,7 +1749,7 @@ The prefix argument ARG functions as with \\[yank] / \\[yank-pop]."
(if entry-key
(progn (ebib-db-set-current-entry-key entry-key ebib--cur-db)
(setq needs-update t)
- (if (assoc-string entry-type (ebib--list-entry-types (ebib--get-dialect ebib--cur-db)) 'case-fold)
+ (if (assoc-string entry-type (ebib--list-entry-types (ebib--get-dialect ebib--cur-db) t) 'case-fold)
(message "[Ebib] Yanked entry.")
(message "[Ebib] Yanked unknown entry type `%s'." entry-type)))
(message "[Ebib] Could not yank a valid entry")
@@ -1822,120 +1786,29 @@ buffer and switch to it."
(ebib-db-set-current-entry-key key ebib--cur-db)
(ebib--update-entry-buffer))))
-;; The exporting functions will have to be redesigned completely. For now (1
-;; Feb 2012) we just define a new function ebib--export-entries. In the long run,
-;; this should be the general exporting function, calling other functions as the
-;; need arises.
-
-(defun ebib--export-to-db (num message copy-fn)
- "Export data to another database.
-NUM is the number of the database to which the data is to be copied.
-
-MESSAGE is a string displayed in the echo area if the export was
-succesful. It must contain a %d directive, which is used to
-display the database number to which the entry was exported.
-
-COPY-FN is the function that actually copies the relevant
-data. It must take as argument the database to which the data is
-to be copied. COPY-FN must return T if the copying was
-successful, and NIL otherwise."
- (let ((goal-db (nth (1- num) ebib--databases)))
- (if (not goal-db)
- (error "[Ebib] Database %d does not exist" num)
- (when (funcall copy-fn goal-db)
- (ebib--set-modified t goal-db)
- (message message num)))))
-
-(defun ebib--export-to-file (prompt-string insert-fn)
- "Export data to a file.
-PROMPT-STRING is the string that is used to ask for the filename
-to export to. INSERT-FN must insert the data to be exported into
-the current buffer: it is called within a `with-temp-buffer',
-whose contents is appended to the file the user enters."
- (let ((insert-default-directory (not ebib--export-filename)))
- (ebib--ifstring (filename (read-file-name
- prompt-string "~/" nil nil ebib--export-filename))
- (with-temp-buffer
- (funcall insert-fn)
- (append-to-file (point-min) (point-max) filename)
- (setq ebib--export-filename filename)))))
-
-(defun ebib--export-entries (entries &optional source-db filename)
- "Export ENTRIES from SOURCE-DB to FILENAME.
-ENTRIES is a list of entry keys. SOURCE-DB defaults to the
-current database. If FILENAME is not provided, the user is asked
-for one."
- (unless filename
- (setq filename (read-file-name
- "File to export entries to:" "~/" nil nil ebib--export-filename)))
- (unless source-db
- (setq source-db ebib--cur-db))
- (with-temp-buffer
- (insert "\n")
- (mapc (lambda (key)
- (ebib--format-entry key ebib--cur-db nil))
- entries)
- (append-to-file (point-min) (point-max) filename)
- (setq ebib--export-filename filename)))
-
-(defun ebib-export-entry (prefix)
- "Copy entries to another database.
-The PREFIX argument indicates which database to copy the entry
-to. If no prefix argument is present, a filename is asked to
-which the entry is appended."
+(defun ebib-export-entries (prefix)
+ "Export entries to another database.
+With PREFIX argument, export entries to a file. Otherwise export
+entries to another open database. The user is asked for the file
+or database to export entries to.
+
+This function operates on the marked entries or, if no entries
+are marked, on the current entry."
(interactive "P")
- (let ((num (ebib--prefix prefix)))
- (ebib--execute-when
- ((marked-entries)
- (ebib--export-marked-entries num))
- ((entries)
- (ebib--export-single-entry num)))))
-
-(defun ebib--export-single-entry (num)
- "Copy the current entry to another database.
-NUM indicates which database to copy the entry to. If it is nil,
-a filename is asked to which the entry is appended."
(ebib--execute-when
((entries)
- (if num
- (ebib--export-to-db num (format "Entry `%s' copied to database %%d." (ebib--get-key-at-point))
- (lambda (db)
- (let ((entry-key (ebib--get-key-at-point)))
- (if (member entry-key (ebib-db-list-keys db))
- (error "[Ebib] Entry key `%s' already exists in database %d" entry-key num)
- (ebib--store-entry entry-key (copy-tree (ebib-db-get-entry entry-key ebib--cur-db)) db t)
- t)))) ; We must return T, WHEN does not always do this.
- (ebib--export-to-file (format "Export `%s' to file: " (ebib--get-key-at-point))
- (lambda ()
- (insert "\n")
- (ebib--format-entry (ebib--get-key-at-point) ebib--cur-db t)))))
- ((default)
- (beep))))
-
-(defun ebib--export-marked-entries (num)
- "Copy the marked entries to another database.
-NUM indicates which database to copy the entry to. If it is nil,
-a filename is asked to which the entry is appended."
- (ebib--execute-when
- ((marked-entries)
- (if num
- (ebib--export-to-db
- num "Entries copied to database %d."
- (lambda (db)
- (mapc (lambda (entry-key)
- (if (member entry-key (ebib-db-list-keys db))
- (error "[Ebib] Entry key `%s' already exists in database %d" entry-key num)
- (ebib--store-entry entry-key (copy-tree (ebib-db-get-entry entry-key ebib--cur-db)) db t)))
- (ebib-db-list-marked-entries ebib--cur-db))
- t)) ; We must return T, WHEN does not always do this.
- (ebib--export-to-file "Export to file: "
- (lambda ()
- (mapc (lambda (entry-key)
- (insert "\n")
- (ebib--format-entry entry-key ebib--cur-db t))
- (ebib-db-list-marked-entries ebib--cur-db))))))
- ((default)
- (beep))))
+ (let ((entries (or (ebib-db-list-marked-entries ebib--cur-db)
+ (list (ebib--get-key-at-point)))))
+ (if prefix
+ (let ((filename (expand-file-name (read-file-name "File to export entries to: " nil nil nil ebib--export-filename))))
+ (if (file-writable-p filename)
+ (ebib--export-entries-to-file entries filename ebib--cur-db)
+ (error "[Ebib] Cannot write to file `%s'" filename)))
+ (let* ((target-db (ebib-read-database "Export entries to database: ")))
+ (if target-db
+ (ebib--export-entries-to-db entries target-db ebib--cur-db)
+ (error "[Ebib] Could not export entries"))))))
+ ((default) (beep))))
(defvar ebib-search-map
(let ((map (make-keymap)))
@@ -1983,7 +1856,7 @@ are searched."
((entries)
(if (null ebib--search-string)
(message "No search string")
- (let ((cur-search-entry (cdr (member (ebib--get-key-at-point) (ebib--sort-keys-list (ebib-db-list-keys ebib--cur-db) ebib--cur-db)))))
+ (let ((cur-search-entry (cdr (member (ebib--get-key-at-point) (ebib--list-keys)))))
(while (and cur-search-entry
(null (ebib--search-in-entry ebib--search-string
(ebib-db-get-entry (car cur-search-entry) ebib--cur-db 'noerror))))
@@ -2026,6 +1899,33 @@ result."
entry))
result))
+
+(defun ebib-follow-crossref ()
+ "Follow the crossref field and jump to that entry.
+If the current entry's crossref field is empty, search for the
+first entry with the current entry's key in its crossref field."
+ (interactive)
+ (let ((xref (ebib-get-field-value "crossref" (ebib--get-key-at-point) ebib--cur-db 'noerror 'unbraced)))
+ (if xref
+ ;; If the entry has a crossref, see if we can find the relevant entry.
+ (let ((database (seq-find (lambda (db)
+ (ebib-db-get-entry xref db 'noerror))
+ ebib--databases)))
+ (unless database
+ (error "[Ebib] Entry `%s' not found in any open database" xref))
+ ;; If the entry exists, switch to the relevant database and try to
+ ;; show the entry.
+ (ebib-switch-to-database database)
+ (if (not (ebib--key-in-index-p xref))
+ (error "[Ebib] Crossreference `%s' not visible due to active filter" xref)
+ (ebib--goto-entry-in-index xref)
+ (ebib--update-entry-buffer)))
+ ;; If the entry has no crossref, we assume the user wants to search for
+ ;; entries cross-referencing the current one.
+ (setq ebib--search-string (ebib--get-key-at-point))
+ (set-transient-map ebib-search-map t (lambda () (message "Search ended. Use `C-u /' to resume.")))
+ (ebib-search-next))))
+
(defun ebib-search-goto-first-entry ()
"Goto the first entry and issue a message that search is still active."
(interactive)
@@ -2045,7 +1945,7 @@ result."
(message "Switched to next database. Continue searching with RET."))
(defun ebib-edit-strings ()
- "Edit the @STRING definitions in the database."
+ "Edit the @String definitions in the database."
(interactive)
(ebib--execute-when
((real-db)
@@ -2056,7 +1956,7 @@ result."
(beep))))
(defun ebib-edit-preamble ()
- "Edit the @PREAMBLE definition in the database."
+ "Edit the @Preamble definition in the database."
(interactive)
(ebib--execute-when
((real-db)
@@ -2065,25 +1965,33 @@ result."
(beep))))
(defun ebib-export-preamble (prefix)
- "Export the @PREAMBLE definition.
-If a PREFIX argument is given, it is taken as the database to
-export the preamble to. If the goal database already has a
-preamble, the new preamble will be appended to it. If no prefix
-argument is given, the user is asked to enter a filename to which
-the preamble is appended."
+ "Export the @Preamble definition.
+
+With PREFIX argument, export the @Preamble to a file. Otherwise export
+the @Preamble to another open database. The user is asked for the file
+or database to export the @Preamble to.
+
+If the goal database already has a preamble, the @Preamble is be
+appended to it."
(interactive "P")
(ebib--execute-when
((real-db)
(if (null (ebib-db-get-preamble ebib--cur-db))
- (error "[Ebib] No @PREAMBLE defined")
- (let ((num (ebib--prefix prefix)))
- (if num
- (ebib--export-to-db num "@PREAMBLE copied to database %d"
- (lambda (db)
- (ebib-db-set-preamble (ebib-db-get-preamble ebib--cur-db) db 'append)))
- (ebib--export-to-file "Export @PREAMBLE to file: "
- (lambda ()
- (insert (format "\n@preamble{%s}\n\n" (ebib-db-get-preamble ebib--cur-db)))))))))
+ (error "[Ebib] No @Preamble defined"))
+ (if prefix
+ (let ((filename (expand-file-name (read-file-name "File to export @Preamble to: " nil nil nil ebib--export-filename))))
+ (if (file-writable-p filename)
+ (with-temp-buffer
+ (insert "\n")
+ (insert (format "\n@Preamble{%s}\n\n" (ebib-db-get-preamble ebib--cur-db)))
+ (append-to-file (point-min) (point-max) filename)
+ (setq ebib--export-filename filename))
+ (error "[Ebib] Cannot write to file `%s'" filename)))
+ (let* ((target-db (ebib-read-database "Export @Preamble to database: ")))
+ (unless target-db
+ (error "[Ebib] Could not export @Preamble"))
+ (ebib-db-set-preamble (ebib-db-get-preamble ebib--cur-db) target-db 'append)
+ (ebib-db-set-modified t target-db))))
((default)
(beep))))
@@ -2098,7 +2006,7 @@ Either prints the entire database, or the marked entries."
ebib--cur-db)))
(ebib--ifstring (tempfile (if (not (string= "" ebib-print-tempfile))
ebib-print-tempfile
- (read-file-name "Use temp file: " "~/" nil nil)))
+ (read-file-name "Use temp file: ")))
(progn
(with-temp-buffer
(when ebib-print-preamble
@@ -2120,7 +2028,7 @@ Either prints the entire database, or the marked entries."
(when (or (not (ebib--multiline-p value))
ebib-print-multiline)
(insert (format "%s: & %s\\\\\n"
- field (ebib-db-unbrace value))))))
+ field (ebib-unbrace value))))))
;; Note: ebib--list-fields returns a list with `=type=' as its first element.
(cdr (ebib--list-fields (cdr (assoc "=type=" entry)) 'all (ebib--get-dialect ebib--cur-db)))))
(insert "\\end{tabular}\n\n")
@@ -2144,7 +2052,7 @@ Operates either on all entries or on the marked entries."
((real-db entries)
(ebib--ifstring (tempfile (if (not (string= "" ebib-print-tempfile))
ebib-print-tempfile
- (read-file-name "Use temp file: " "~/" nil nil)))
+ (read-file-name "Use temp file: ")))
(progn
(with-temp-buffer
(when ebib-latex-preamble
@@ -2177,7 +2085,7 @@ Operates either on all entries or on the marked entries."
;; First save the current entry key of the still current database.
(ebib-db-set-current-entry-key (ebib--get-key-at-point) ebib--cur-db)
(setq ebib--cur-db db)
- (ebib--update-buffers))
+ (ebib--update-buffers 'no-refresh))
(defun ebib-next-database (&optional arg)
"Switch to the next database.
@@ -2193,7 +2101,7 @@ new database."
(setq ebib--cur-db new-db)
(if arg
(ebib-db-set-current-entry-key nil ebib--cur-db))
- (ebib--update-buffers)))))
+ (ebib--update-buffers 'no-refresh)))))
(defun ebib-prev-database (&optional arg)
"Switch to the preceding database.
@@ -2204,12 +2112,12 @@ new database."
((database)
(let ((new-db (ebib--prev-elem ebib--cur-db ebib--databases)))
(unless new-db
- (setq new-db (-last-item ebib--databases)))
+ (setq new-db (car (last ebib--databases))))
(ebib-db-set-current-entry-key (ebib--get-key-at-point) ebib--cur-db)
(setq ebib--cur-db new-db)
(if arg
(ebib-db-set-current-entry-key nil ebib--cur-db))
- (ebib--update-buffers)))))
+ (ebib--update-buffers 'no-refresh)))))
(defun ebib-index-open-at-point ()
"Open link, note or files at point."
@@ -2411,7 +2319,7 @@ for which the user is prompted."
(let ((templates (or (cadr (assq mode ebib-citation-commands))
(cadr (assq 'any ebib-citation-commands)))))
(ebib--ifstring (template (cadr (assoc (completing-read "Command to use: " templates nil nil nil 'ebib--citation-history)
- templates)))
+ templates)))
(cl-multiple-value-bind (before repeater separator after) (ebib--split-citation-string template)
(when (and (not separator) (> (length keys) 1))
(setq separator (read-string "Separator: ")))
@@ -2563,7 +2471,7 @@ uses standard Emacs completion."
Return the keywords entered as a list. Any keywords not in
COLLECTION are added to the current database's keywords list. If
no keywords are entered, the return value is nil."
- (let ((keywords (cl-loop for keyword = (completing-read (format "Add keyword (ENTER to finish) [%s]: " (mapconcat #'identity keywords " ")) collection nil nil nil 'ebib-keyword-history)
+ (let ((keywords (cl-loop for keyword = (completing-read (format "Add keyword (ENTER to finish) [%s]: " (mapconcat #'identity keywords " ")) collection nil nil nil 'ebib--keywords-history)
until (string= keyword "")
collecting keyword into keywords
finally return keywords)))
@@ -2584,11 +2492,11 @@ the current entry."
(new-conts (if conts
(concat conts ebib-keywords-separator keywords)
keywords)))
- (ebib-db-set-field-value "keywords"
- (if ebib-keywords-field-keep-sorted
- (ebib--keywords-sort new-conts)
- new-conts)
- entry-key ebib--cur-db 'overwrite))))
+ (ebib-set-field-value "keywords"
+ (if ebib-keywords-field-keep-sorted
+ (ebib--keywords-sort new-conts)
+ new-conts)
+ entry-key ebib--cur-db 'overwrite))))
(let* ((minibuffer-local-completion-map (make-composed-keymap '(keymap (32)) minibuffer-local-completion-map))
(collection (ebib--keywords-for-database ebib--cur-db))
(keywords (ebib--completing-read-keywords collection)))
@@ -2655,9 +2563,9 @@ the filter."
(ebib--execute-when
((filtered-db)
(ebib-db-set-filter (if (eq (car (ebib-db-get-filter ebib--cur-db)) 'not)
- (cadr (ebib-db-get-filter ebib--cur-db))
- `(not ,(ebib-db-get-filter ebib--cur-db)))
- ebib--cur-db)
+ (cadr (ebib-db-get-filter ebib--cur-db))
+ `(not ,(ebib-db-get-filter ebib--cur-db)))
+ ebib--cur-db)
(ebib-db-set-current-entry-key (ebib--get-key-at-point) ebib--cur-db)
(ebib--update-buffers))
((default)
@@ -2822,6 +2730,7 @@ hook `ebib-reading-list-remove-item-hook' is run."
(if ebib-hide-cursor
(setq cursor-type nil))
(setq truncate-lines t)
+ (setq default-directory "~/") ; Make sure Ebib always thinks it's in $HOME.
(set (make-local-variable 'hl-line-face) 'ebib-highlight-face)
(hl-line-mode 1)
(ebib-entry-minor-mode 1))
@@ -2879,12 +2788,20 @@ the beginning of the current line."
(point))))
(buffer-substring-no-properties beg end)))))))
+(defun ebib--outside-field-p ()
+ "Return t if point is at an empty line in the entry buffer.
+Return t if point is on an empty line or on a line that starts
+with spaces (which is part of a multiline value). Return nil
+otherwise."
+ (or (eolp)
+ (looking-at-p "[[:space:]]")))
+
(defun ebib-prev-field ()
"Move to the previous field."
(interactive)
(if (= (forward-line -1) -1)
(beep) ; We're at the first field already.
- (while (eolp) ; If we're at an empty line,
+ (while (ebib--outside-field-p) ; If we're at an empty line,
(forward-line -1)))) ; move up until we're not.
(defun ebib-next-field (&optional pfx)
@@ -2897,7 +2814,7 @@ was called interactively."
(if pfx ; the last field, beep and adjust.
(beep))
(forward-line -1))
- (while (eolp) ; If we're at an empty line,
+ (while (ebib--outside-field-p) ; If we're at an empty line,
(forward-line))) ; move down until we're not.
(defun ebib-goto-first-field ()
@@ -2909,7 +2826,7 @@ was called interactively."
"Move to the last field."
(interactive)
(goto-char (point-max))
- (while (eolp) ; Move up as long as we're at an empty line.
+ (while (ebib--outside-field-p) ; Move up as long as we're at an empty line.
(forward-line -1)))
(defun ebib-goto-next-set ()
@@ -2937,7 +2854,7 @@ was called interactively."
(interactive "sField: ")
;; We store the field with a nil value and let the user edit it later.
(let ((key (ebib--get-key-at-point)))
- (if (not (ebib-db-set-field-value field nil key ebib--cur-db 'noerror))
+ (if (not (ebib-set-field-value field nil key ebib--cur-db 'noerror))
(message "Field `%s' already has a value in entry `%s'" field key)
(ebib--update-entry-buffer)
(re-search-forward (concat "^" field))
@@ -2946,19 +2863,20 @@ was called interactively."
(defun ebib--edit-entry-type ()
"Edit the entry type."
- (ebib--ifstring (new-type (completing-read "type: " (ebib--list-entry-types (ebib--get-dialect ebib--cur-db)) nil t))
+ (ebib--ifstring (new-type (completing-read "type: " (ebib--list-entry-types (ebib--get-dialect ebib--cur-db) t) nil t))
(progn
- (ebib-db-set-field-value "=type=" new-type (ebib--get-key-at-point) ebib--cur-db 'overwrite 'unbraced)
+ (ebib-set-field-value "=type=" new-type (ebib--get-key-at-point) ebib--cur-db 'overwrite 'unbraced)
(ebib--update-entry-buffer)
(ebib--set-modified t))))
(defun ebib--edit-crossref (field)
"Edit cross-referencing FIELD."
- (ebib--ifstring (key (completing-read (format "Key to insert in `%s': " field) (ebib-db-list-keys ebib--cur-db) nil t nil 'ebib--key-history))
- (progn
- (ebib-db-set-field-value field key (ebib--get-key-at-point) ebib--cur-db 'overwrite)
- (ebib--redisplay-current-field)
- (ebib--set-modified t))))
+ (let ((keys (apply #'append (mapcar #'ebib-db-list-keys ebib--databases))))
+ (ebib--ifstring (key (completing-read (format "Key to insert in `%s': " field) keys nil t nil 'ebib--key-history))
+ (progn
+ (ebib-set-field-value field key (ebib--get-key-at-point) ebib--cur-db 'overwrite)
+ (ebib--redisplay-current-field)
+ (ebib--set-modified t)))))
(defun ebib--edit-keywords-field ()
"Edit the keywords field."
@@ -2972,13 +2890,13 @@ was called interactively."
(new-conts (if conts
(concat conts ebib-keywords-separator keyword)
keyword)))
- (ebib-db-set-field-value "keywords"
- (if ebib-keywords-field-keep-sorted
- (ebib--keywords-sort new-conts)
- new-conts)
- (ebib--get-key-at-point)
- ebib--cur-db
- 'overwrite)
+ (ebib-set-field-value "keywords"
+ (if ebib-keywords-field-keep-sorted
+ (ebib--keywords-sort new-conts)
+ new-conts)
+ (ebib--get-key-at-point)
+ ebib--cur-db
+ 'overwrite)
(unless (member keyword collection)
(ebib--keywords-add-keyword keyword ebib--cur-db))
(ebib--redisplay-current-field)
@@ -3008,7 +2926,7 @@ otherwise they are stored as absolute paths."
(new-conts (if conts
(concat conts ebib-filename-separator file-name)
file-name)))
- (ebib-db-set-field-value ebib-file-field new-conts (ebib--get-key-at-point) ebib--cur-db 'overwrite)
+ (ebib-set-field-value ebib-file-field new-conts (ebib--get-key-at-point) ebib--cur-db 'overwrite)
(ebib--redisplay-current-field)
(ebib--set-modified t))
finally return (ebib-db-modified-p ebib--cur-db)))) ; Return t if the field was modified.
@@ -3049,12 +2967,12 @@ If FILE is not in (a subdirectory of) one of the directories in
(if (ebib--multiline-p init-contents)
(ebib-edit-multiline-field) ; This always returns nil.
(when init-contents
- (setq unbraced? (ebib-db-unbraced-p init-contents))
- (setq init-contents (ebib-db-unbrace init-contents)))
+ (setq unbraced? (ebib-unbraced-p init-contents))
+ (setq init-contents (ebib-unbrace init-contents)))
(ebib--ifstring (new-contents (read-string (format "%s: " cur-field)
(if init-contents
(cons init-contents 0))))
- (ebib-db-set-field-value cur-field new-contents (ebib--get-key-at-point) ebib--cur-db 'overwrite unbraced?)
+ (ebib-set-field-value cur-field new-contents (ebib--get-key-at-point) ebib--cur-db 'overwrite unbraced?)
(ebib-db-remove-field-value cur-field (ebib--get-key-at-point) ebib--cur-db))
(ebib--redisplay-current-field)
(ebib--set-modified t))))
@@ -3068,12 +2986,12 @@ If FILE is not in (a subdirectory of) one of the directories in
"Edit a field of a BibTeX entry.
Most fields are edited directly using the minibuffer, but a few
are handled specially: the `type' `crossref', `xref' and
-`related' fields offer completion, the `annote' field is edited
-as a multiline field, the `keywords' field adds keywords one by
-one, also allowing completion, and the field in `ebib-file-field'
-uses filename completion and shortens filenames if they are in (a
-subdirectory of) one of the directories in
-`ebib-file-search-dirs'.
+`related' fields offer completion, the `annote', `annotation' and
+`abstract' fields is edited as a multiline field, the `keywords'
+field adds keywords one by one, also allowing completion, and the
+field in `ebib-file-field' uses filename completion and shortens
+filenames if they are in (a subdirectory of) one of the
+directories in `ebib-file-search-dirs'.
With a prefix argument PFX, the `keywords' field and the field in
`ebib-file-field' can be edited directly. For other fields, the
@@ -3091,7 +3009,7 @@ prefix argument has no meaning."
((and (cl-equalp field ebib-file-field)
(= 1 pfx))
(ebib--edit-file-field))
- ((member-ignore-case field '("annote" "annotation"))
+ ((member-ignore-case field '("annote" "annotation" "abstract"))
;; A multiline edit differs from the other ones, because
;; the edit isn't done when `ebib-edit-multiline-field'
;; returns. This means we cannot move to the next field.
@@ -3102,7 +3020,7 @@ prefix argument has no meaning."
nil)
(t (ebib--edit-normal-field)))))
;; When the edit returns, see if we need to move to the next field and
- ;; whether we need to update the index display.
+ ;; check whether we need to update the index display.
(when result
(when pfx
(ebib-next-field))
@@ -3188,7 +3106,7 @@ Prefix argument ARG functions as with \\[yank] / \\[yank-pop]."
((eq arg '-) -2)
(t (1- arg))))))
(when new-contents
- (ebib-db-set-field-value field new-contents (ebib--get-key-at-point) ebib--cur-db 'overwrite)
+ (ebib-set-field-value field new-contents (ebib--get-key-at-point) ebib--cur-db 'overwrite)
(ebib--redisplay-current-field)
(ebib--redisplay-index-item field)
(ebib--set-modified t))))))
@@ -3219,7 +3137,7 @@ The deleted text is not put in the kill ring."
(ebib-edit-field) ; which we must then store unbraced.
(setq contents (ebib-get-field-value field (ebib--get-key-at-point) ebib--cur-db 'noerror)))
(when contents ; We must check to make sure the user entered some value.
- (ebib-db-set-field-value field contents (ebib--get-key-at-point) ebib--cur-db 'overwrite (not (ebib-db-unbraced-p contents)))
+ (ebib-set-field-value field contents (ebib--get-key-at-point) ebib--cur-db 'overwrite (not (ebib-unbraced-p contents)))
(ebib--redisplay-current-field)
(ebib--set-modified t)))))))
@@ -3229,9 +3147,9 @@ The deleted text is not put in the kill ring."
(let ((field (ebib--current-field)))
(unless (member-ignore-case field '("=type=" "crossref" "xref" "related"))
(let ((text (ebib-get-field-value field (ebib--get-key-at-point) ebib--cur-db 'noerror)))
- (if (ebib-db-unbraced-p text) ; Unbraced fields cannot be multiline.
+ (if (ebib-unbraced-p text) ; Unbraced fields cannot be multiline.
(beep)
- (ebib--multiline-edit (list 'field (ebib-db-get-filename ebib--cur-db) (ebib--get-key-at-point) field) (ebib-db-unbrace text)))))))
+ (ebib--multiline-edit (list 'field (ebib-db-get-filename ebib--cur-db) (ebib--get-key-at-point) field) (ebib-unbrace text)))))))
(defun ebib-insert-abbreviation ()
"Insert an abbreviation from the ones defined in the database."
@@ -3244,7 +3162,7 @@ The deleted text is not put in the kill ring."
(with-selected-window (get-buffer-window (ebib--buffer 'index))
(let ((string (completing-read "Abbreviation to insert: " strings nil t)))
(when string
- (ebib-db-set-field-value field string (ebib--get-key-at-point) ebib--cur-db 'overwrite 'unbraced)
+ (ebib-set-field-value field string (ebib--get-key-at-point) ebib--cur-db 'overwrite 'unbraced)
(ebib--set-modified t))))
(ebib--redisplay-current-field)
(ebib-next-field))))))
@@ -3309,11 +3227,12 @@ The deleted text is not put in the kill ring."
(if ebib-hide-cursor
(setq cursor-type nil))
(setq truncate-lines t)
+ (setq default-directory "~/") ; Make sure Ebib always thinks it's in $HOME.
(set (make-local-variable 'hl-line-face) 'ebib-highlight-face)
(hl-line-mode 1))
(defun ebib-quit-strings-buffer ()
- "Quit editing the @STRING definitions."
+ "Quit editing the @String definitions."
(interactive)
(if (and (eq ebib-layout 'index-only)
ebib-popup-entry-window)
@@ -3325,7 +3244,7 @@ The deleted text is not put in the kill ring."
(defun ebib--current-string ()
"Return the currently selected string.
The current string is simply the string that point is on. If
-point is on an empty line (e.g., when there are no @string
+point is on an empty line (e.g., when there are no @String
definitions), return nil. This function leaves point at the
beginning of the current line."
(with-current-ebib-buffer 'strings
@@ -3376,12 +3295,12 @@ beginning of the current line."
(forward-line -1)))
(defun ebib--fill-strings-buffer ()
- "Fill the strings buffer with the @STRING definitions."
+ "Fill the strings buffer with the @String definitions."
(with-current-ebib-buffer 'strings
(let ((inhibit-read-only t))
(erase-buffer)
(cl-dolist (elem (sort (ebib-db-list-strings ebib--cur-db) #'string<))
- (let ((str (ebib-db-get-string elem ebib--cur-db 'noerror 'unbraced)))
+ (let ((str (ebib-get-string elem ebib--cur-db 'noerror 'unbraced)))
(insert (format "%-18s %s\n" elem
(if (ebib--multiline-p str)
(concat "+" (ebib--first-line str))
@@ -3390,51 +3309,51 @@ beginning of the current line."
(set-buffer-modified-p nil)))
(defun ebib-edit-string ()
- "Edit the value of an @STRING definition.
+ "Edit the value of an @String definition.
When the user enters an empty string, the value is not changed."
(interactive)
(let* ((string (ebib--current-string))
- (init-contents (ebib-db-get-string string ebib--cur-db 'noerror 'unbraced)))
+ (init-contents (ebib-get-string string ebib--cur-db 'noerror 'unbraced)))
(ebib--ifstring (new-contents (read-string (format "%s: " string)
(if init-contents
(cons init-contents 0)
nil)))
(progn
- (ebib-db-set-string string new-contents ebib--cur-db 'overwrite)
+ (ebib-set-string string new-contents ebib--cur-db 'overwrite)
(ebib--redisplay-current-string)
(ebib-next-string)
(ebib--set-modified t))
- (error "[Ebib] @STRING definition cannot be empty"))))
+ (error "[Ebib] @String definition cannot be empty"))))
(defun ebib-copy-string-contents ()
"Copy the contents of the current string to the kill ring."
(interactive)
- (let ((contents (ebib-db-get-string (ebib--current-string) ebib--cur-db nil 'unbraced)))
+ (let ((contents (ebib-get-string (ebib--current-string) ebib--cur-db nil 'unbraced)))
(kill-new contents)
(message "String value copied.")))
(defun ebib-delete-string ()
- "Delete the current @STRING definition from the database."
+ "Delete the current @String definition from the database."
(interactive)
(let ((string (ebib--current-string)))
- (when (y-or-n-p (format "Delete @STRING definition %s? " string))
+ (when (y-or-n-p (format "Delete @String definition %s? " string))
(ebib-db-remove-string string ebib--cur-db)
(let ((inhibit-read-only t))
(delete-region (point-at-bol) (1+ (point-at-eol))))
(when (eobp) ; Deleted the last string.
(forward-line -1))
(ebib--set-modified t)
- (message "@STRING definition deleted."))))
+ (message "@String definition deleted."))))
(defun ebib-add-string ()
- "Create a new @STRING definition."
+ "Create a new @String definition."
(interactive)
- (ebib--ifstring (new-abbr (read-string "New @STRING abbreviation: " nil 'ebib--key-history))
+ (ebib--ifstring (new-abbr (read-string "New @String abbreviation: " nil 'ebib--key-history))
(if (member new-abbr (ebib-db-list-strings ebib--cur-db))
(error "[Ebib] %s already exists" new-abbr)
(ebib--ifstring (new-string (read-string (format "Value for %s: " new-abbr)))
(progn
- (ebib-db-set-string new-abbr new-string ebib--cur-db)
+ (ebib-set-string new-abbr new-string ebib--cur-db 'error)
(let ((inhibit-read-only t))
(goto-char (point-min))
(insert (format "%-19s %s\n" new-abbr new-string))
@@ -3445,42 +3364,67 @@ When the user enters an empty string, the value is not changed."
(ebib--set-modified t))))))
(defun ebib-export-string (prefix)
- "Export the current @STRING.
-The PREFIX argument indicates which database to copy the string
-to. If no prefix argument is present, a filename is asked to
-which the string is appended."
+ "Export the current @String to another database.
+With PREFIX argument, export the @String to a file. Otherwise export
+the @String to another open database. The user is asked for the file
+or database to export the @String to."
(interactive "P")
- (let ((string (ebib--current-string))
- (num (ebib--prefix prefix)))
- (if num
- (ebib--export-to-db num (format "@STRING definition `%s' copied to database %%d" string)
- (lambda (db)
- (ebib-db-set-string string (ebib-db-get-string string ebib--cur-db) db)))
- (ebib--export-to-file (format "Export @STRING definition `%s' to file: " string)
- (lambda ()
- (insert (format "\n@string{%s = %s}\n"
- string
- (ebib-db-get-string string ebib--cur-db))))))))
+ (let ((string (ebib--current-string)))
+ (unless string
+ (error "No current string found"))
+ (if prefix
+ ;; Export to file.
+ (let ((filename (expand-file-name (read-file-name "File to export @String to:" nil nil nil ebib--export-filename))))
+ (if (file-writable-p filename)
+ (with-temp-buffer
+ (insert (format "\n@String{%s = %s}\n"
+ string
+ (ebib-db-get-string string ebib--cur-db))))
+ (error "[Ebib] Cannot write to file `%s'" filename)))
+ ;; Export to another database.
+ (let ((target-db (ebib-read-database "Export @String to database:")))
+ (unless target-db
+ (error "[Ebib] Could not export @Strings"))
+ (if (member string (ebib-db-list-strings target-db))
+ (ebib--log 'message "@String `%s' already exists in database %d" string (ebib-db-get-filename target-db 'short))
+ (ebib-set-string string (ebib-db-get-string string ebib--cur-db) target-db 'error)
+ (ebib-db-set-modified t target-db))))))
(defun ebib-export-all-strings (prefix)
- "Export all @STRING definitions.
-If a PREFIX argument is given, it is taken as the database to
-copy the definitions to. Without prefix argument, asks for a file
-to append them to."
+ "Export all @String definitions to another database.
+With PREFIX argument, export the @String definitions to a file.
+Otherwise export the @String definitions to another open
+database. The user is asked for the file or database to export
+the @String definitions to."
(interactive "P")
- (when (ebib--current-string) ; There is always a current string, unless there are no strings.
- (let ((num (ebib--prefix prefix)))
- (if num
- (ebib--export-to-db
- num "All @STRING definitions copied to database %d"
- (lambda (db)
- (mapc (lambda (abbr)
- (ebib-db-set-string abbr (ebib-db-get-string abbr ebib--cur-db) db 'noerror))
- (ebib-db-list-strings ebib--cur-db))))
- (ebib--export-to-file "Export all @STRING definitions to file: "
- (lambda ()
- (insert (format "\n")) ; To keep things tidy.
- (ebib--format-strings ebib--cur-db)))))))
+ (let ((strings (ebib-db-list-strings ebib--cur-db)))
+ (unless strings
+ (error "No @String definitions found"))
+ (if prefix
+ ;; Export to file.
+ (let ((filename (expand-file-name (read-file-name "File to export @String to:" nil nil nil ebib--export-filename))))
+ (if (file-writable-p filename)
+ (with-temp-buffer
+ (mapc (lambda (string)
+ (insert (format "\n@String{%s = %s}\n"
+ string
+ (ebib-db-get-string string ebib--cur-db))))
+ strings))
+ (error "[Ebib] Cannot write to file `%s'" filename)))
+ ;; Export to another database.
+ (let ((target-db (ebib-read-database "Export @String to database:")))
+ (unless target-db
+ (error "[Ebib] Could not export @Strings"))
+ (let ((modified nil)
+ (target-strings (ebib-db-list-strings target-db)))
+ (mapc (lambda (string)
+ (if (member string target-strings)
+ (ebib--log 'message "@String `%s' already exists in database %d" string (ebib-db-get-filename target-db 'short))
+ (ebib-set-string string (ebib-db-get-string string ebib--cur-db) target-db 'error)
+ (setq modified t)))
+ strings)
+ (when modified
+ (ebib-db-set-modified t target-db)))))))
(defun ebib-strings-help ()
"Show the info node on Ebib's strings buffer."
@@ -3524,7 +3468,7 @@ Otherwise, create a new buffer and add it to
STARTTEXT is a string that contains the initial text of the
buffer."
(ebib--pop-to-buffer (or (ebib--get-multiline-buffer info)
- (ebib--create-multiline-buffer info starttext))))
+ (ebib--create-multiline-buffer info starttext))))
(defun ebib--get-multiline-buffer (info)
"Return the multiline edit buffer associated with INFO."
@@ -3591,7 +3535,7 @@ Also return focus to the index or entry buffer."
;; Make sure we display the correct entry & field.
(setq ebib--cur-db (ebib--get-db-from-filename (cl-second info)))
(ebib-db-set-current-entry-key (cl-third info) ebib--cur-db)
- (ebib--update-buffers)
+ (ebib--update-buffers 'no-refresh)
(ebib--pop-to-buffer (ebib--buffer 'entry))
(re-search-forward (concat "^" (regexp-quote (cl-fourth info))) nil t)
(beginning-of-line))))
@@ -3621,7 +3565,7 @@ The text being edited is stored before saving the database."
(field (cl-fourth ebib--multiline-info)))
(if (string= text "")
(ebib-db-remove-field-value field key db)
- (ebib-db-set-field-value field text key db 'overwrite)))))
+ (ebib-set-field-value field text key db 'overwrite)))))
(set-buffer-modified-p nil)))
(ebib--set-modified t))
@@ -3646,7 +3590,8 @@ The text being edited is stored before saving the database."
fundamental-mode "Ebib-log"
"Major mode for the Ebib log buffer."
(local-set-key "\C-xb" 'ebib-quit-log-buffer)
- (local-set-key "\C-xk" 'ebib-quit-log-buffer))
+ (local-set-key "\C-xk" 'ebib-quit-log-buffer)
+ (setq default-directory "~/")) ; Make sure Ebib always thinks it's in $HOME.
(defun ebib-quit-log-buffer ()
"Exit the log buffer."
@@ -3679,7 +3624,7 @@ or on the region if it is active."
(let ((result (ebib--find-bibtex-entries ebib--cur-db t)))
(ebib--update-buffers)
(ebib--set-modified t)
- (message (format "%d entries, %d @STRINGs and %s @PREAMBLE found in buffer."
+ (message (format "%d entries, %d @Strings and %s @Preamble found in buffer."
(car result)
(cadr result)
(if (nth 2 result) "a" "no"))))))))))
@@ -3800,7 +3745,7 @@ created containing only these entries."
ebib--local-bibtex-filenames))))
(with-temp-buffer
(insert-file-contents bbl-file)
- (ebib--export-entries (ebib-read-entries-from-bbl) databases bib-file))))))
+ (ebib--export-entries-to-file (ebib-read-entries-from-bbl) bib-file databases))))))
((default)
(beep))))
diff --git a/ebib.info b/ebib.info
index 7867962..94fa9cf 100644
--- a/ebib.info
+++ b/ebib.info
@@ -1,4 +1,4 @@
-This is ebib.info, produced by makeinfo version 6.1 from ebib.texi.
+This is ebib.info, produced by makeinfo version 6.5 from ebib.texi.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
@@ -13,14 +13,13 @@ Ebib Manual
Ebib is a program with which you can manage BibTeX and BibLateX database
files without having to edit the raw ‘.bib’ files. It runs in
-GNU/Emacs, version 24.3 or higher. (Users of GNU/Emacs 23.1 and up can
-install Ebib 1.x, which is available in the pasture branch on Github or
-as a zip or tar archive on Github’s releases page.)
+GNU/Emacs, version 25.3 or higher.
It should be noted that Ebib is _not_ a minor or major mode for
editing BibTeX files. It is a program in itself, which just happens to
make use of Emacs as a working environment, in the same way that for
example Gnus is.
+
* Menu:
* News::
@@ -61,187 +60,93 @@ File: ebib.info, Node: News, Next: Installation, Prev: Top, Up: Top
* Menu:
+* Version 215 January 2019::
+* Version 214 December 2018::
+* Version 213 November 2018::
+* Version 2123 November 2018::
+* Version 2122 November 2018::
* Version 212 August 2018::
* Version 21112 July 2018::
-* Version 211 January 2017::
-* Version 210 January 2017::
-* Version 29 January 2017::
-* 19 December 2016::
-* 7 December 2016::
-* 5 December 2016::
-* 7 November 2016::
-* Version 28 26 October 2016::
-* Version 27 22 September 2016::
-* Version 263 31 August 2016::
-
-
-File: ebib.info, Node: Version 212 August 2018, Next: Version 21112 July 2018, Up: News
-
-1.1 Version 2.12, August 2018
-=============================
-
- • Add an option to specify the default sort field and direction. It
- is no longer necessary to set the desired sort field as the first
- column in the index buffer, but Ebib still defaults to this if the
- default sort field and direction are not set explicitly.

-File: ebib.info, Node: Version 21112 July 2018, Next: Version 211 January 2017, Prev: Version 212 August 2018, Up: News
+File: ebib.info, Node: Version 215 January 2019, Next: Version 214 December 2018, Up: News
-1.2 Version 2.11.12, July 2018
+1.1 Version 2.15, January 2019
==============================
- • Use BibLaTeX’s ‘Date’ field, if present, for displaying the year.
- • Check for changed files on disk when saving all databases, not just
- when saving the current database.
- • Improve handling of multiple databases: ‘crossref’ entries can now
- occur in other open databases as well, and searches with ‘/’ can be
- continued in other databases.
- • Autogenerating keys is now on by default.
+ • Multiline field values can now be displayed in the entry buffer.
+ • Do not warn about aliased entry types when loading BibLaTeX files.
+ • The abstract field is now treated as a multiline field by default,
+ similar to the annote/annotation field.
+ • Bug fix: ‘ebib-show-annotation’ (bound to ‘A’) shows the contents
+ of the annote field in BibTeX databases, not the annotation field
+ (which is BibLaTeX-specific).

-File: ebib.info, Node: Version 211 January 2017, Next: Version 210 January 2017, Prev: Version 21112 July 2018, Up: News
-
-1.3 Version 2.11, January 2017
-==============================
+File: ebib.info, Node: Version 214 December 2018, Next: Version 213 November 2018, Prev: Version 215 January 2019, Up: News
- • Update for ‘parsebib’ v. 2.3.
-
-
-File: ebib.info, Node: Version 210 January 2017, Next: Version 29 January 2017, Prev: Version 211 January 2017, Up: News
-
-1.4 Version 2.10, January 2017
-==============================
-
- • Improved index column display.
-
-
-File: ebib.info, Node: Version 29 January 2017, Next: 19 December 2016, Prev: Version 210 January 2017, Up: News
-
-1.5 Version 2.9, January 2017
-=============================
-
- • Allow ‘%s’ in the program strings in ‘ebib-file-associations’,
- making it possible to pass command line arguments to the program
- being called.
-
-
-File: ebib.info, Node: 19 December 2016, Next: 7 December 2016, Prev: Version 29 January 2017, Up: News
-
-1.6 19 December 2016
-====================
+1.2 Version 2.14, December 2018
+===============================
- • Remove support for a separate rc file for Ebib. User configuration
- should be moved to Emacs’ ‘init.el’ file. To keep Ebib
- customisation in a separate file, simply load it from ‘init.el’.
- • The macro ‘ebib-key’ has also been removed. Simply use
- ‘define-key’ or any other key binding mechanism to define keys for
- Ebib. See the section *note Modifying Key Bindings:
- #modifying-key-bindings. for details.
+ • Change the user interface of the export functions. Calling one of
+ the export functions now exports to another database. The user is
+ asked to specify the database, enabling completion on the database
+ names. To export to a file, the export functions have to be called
+ with a prefix argument.
+ • Bug fix: Handle overwriting the local BibTeX dialect correctly.
+ • Bug fix: Add braces to the crossref field.

-File: ebib.info, Node: 7 December 2016, Next: 5 December 2016, Prev: 19 December 2016, Up: News
+File: ebib.info, Node: Version 213 November 2018, Next: Version 2123 November 2018, Prev: Version 214 December 2018, Up: News
-1.7 7 December 2016
-===================
+1.3 Version 2.13, November 2018
+===============================
- • Upgrade Emacs dependency to 24.4.
+ • Use a separate index buffer for each open ‘.bib’ file. Filling the
+ index buffer can be slow for large ‘.bib’ files, because of the
+ need to calculate the tabulated columns.

-File: ebib.info, Node: 5 December 2016, Next: 7 November 2016, Prev: 7 December 2016, Up: News
+File: ebib.info, Node: Version 2123 November 2018, Next: Version 2122 November 2018, Prev: Version 213 November 2018, Up: News
-1.8 5 December 2016
-===================
+1.4 Version 2.12.3, November 2018
+=================================
- • New library ‘org-ebib’. This defines a new Org link type ‘ebib:’,
- which uses the command ‘org-ebib-open’ to open Ebib. The previous
- commands to do this, ‘ebib-show-entry’ and ‘ebib-open-org-link’
- have been removed. ‘org-ebib’ also allows the creation of Org
- links to Ebib entries with ‘org-store-link’.
- • New citation insertion command ‘ebib-insert-citation’. This
- replaces ‘ebib-insert-bibtex-key’, so please update your key
- bindings. The new command uses ‘ivy’ for completion if this
- package is available, so that it is possible to select an entry by
- typing parts of its author and/or title.
+ • Bug fix: when searching the database, only search visible entries.

-File: ebib.info, Node: 7 November 2016, Next: Version 28 26 October 2016, Prev: 5 December 2016, Up: News
+File: ebib.info, Node: Version 2122 November 2018, Next: Version 212 August 2018, Prev: Version 2123 November 2018, Up: News
-1.9 7 November 2016
-===================
+1.5 Version 2.12.2, November 2018
+=================================
- • New tabulated list interface in index buffer. This interface is
- not based on Emacs’ built-in ‘tabulated-list-mode’, hence sorting
- cannot be done by clicking on the column headers. Sorting can be
- done with ‘<’, ‘>’ (sort ascending and sort descending,
- respectively, which ask for the column to sort) and ‘=’, to reset
- to default sort (which is on the entry key).
- • The user option ‘ebib-index-display-fields’ is replaced with
- ‘ebib-index-columns’, which has a different format: each element in
- ‘ebib-index-columns’ describes a column in the tabulated view and
- consists of a list containing the field name, the column’s width
- and a boolean indicating whether sorting on this column is
- possible.
+ • Bug fix: when editing the ‘crossref’ field, offer keys from all
+ databases as completion targets, not just the current one.

-File: ebib.info, Node: Version 28 26 October 2016, Next: Version 27 22 September 2016, Prev: 7 November 2016, Up: News
-
-1.10 Version 2.8, 26 October 2016
-=================================
+File: ebib.info, Node: Version 212 August 2018, Next: Version 21112 July 2018, Prev: Version 2122 November 2018, Up: News
- • Changed key bindings: ‘j’ and ‘k’ no longer move up/down in the
- index, entry and strings buffers; use ‘p’ and ‘n’ instead.
- Furthermore, ‘i’ now executes ‘ebib-push-bibtex-key’ (used to be
- ‘p’), and ‘I’ (capital i) executes ‘ebib-browse-doi’ (used to be
- ‘i’).
- • In the index buffer, ‘ebib-search-next’ (which used to be bound to
- ‘n’) is no longer bound. Instead, ‘ebib-search’ (still bound to
- ‘/’) activates a transient map which binds the keys ‘/’ and ‘RET’
- to ‘ebib-search-next’. Any other key disables the transient keymap
- and is executed normally.
- • In the index buffer, ‘C-u /’ repeats the previous search. (This
- fixes a small bug that has so far gone unnoticed: moving to the top
- of the databas and calling ‘ebib-search-next’, as previously
- suggested in the manual to get around the fact that
- ‘ebib-search-next’ does not wrap, would not search the first
- entry.)
- • In the entry buffer, ‘x’ is replaced by ‘k’
- (‘ebib-kill-field-contents’).
- • New functions: ‘ebib-kill-entry’ and ‘ebib-yank-entry’ for killing
- and yanking BibTeX entries. ‘ebib-kill-entry’ deletes the current
- entry from the database and puts it in the kill ring.
- ‘ebib-yank-entry’ adds an entry from the kill ring to the current
- database.
-
-
-File: ebib.info, Node: Version 27 22 September 2016, Next: Version 263 31 August 2016, Prev: Version 28 26 October 2016, Up: News
-
-1.11 Version 2.7, 22 September 2016
-===================================
+1.6 Version 2.12, August 2018
+=============================
- • Reading list management: add and remove BibTeX entries to an Org
- reading list.
- • Remove options ‘ebib-notes-identifier-function’ and
- ‘ebib-notes-title-function’.
- • Add option ‘ebib-notes-template-specifiers’: allow customisation of
- the format specs used in ‘ebib-notes-template’. (This option
- replaces ‘ebib-notes-identifier-function’ and
- ‘ebib-notes-title-function’).
+ • Add an option to specify the default sort field and direction. It
+ is no longer necessary to set the desired sort field as the first
+ column in the index buffer, but Ebib still defaults to this if the
+ default sort field and direction are not set explicitly.

-File: ebib.info, Node: Version 263 31 August 2016, Prev: Version 27 22 September 2016, Up: News
+File: ebib.info, Node: Version 21112 July 2018, Prev: Version 212 August 2018, Up: News
-1.12 Version 2.6.3, 31 August 2016
-==================================
+1.7 Version 2.11.12, July 2018
+==============================
- • Allow storing notes in a single file rather than using one file per
- note.
- • Correct handling of DOIs.
- • Add option ‘ebib-truncate-file-names’: if set (the default), file
- names added to the ‘file’ field are truncated relative to
- ‘ebib-file-search-dirs’.
- • Add option ‘ebib-file-name-mod-function’: modify file paths before
- storing them in the ‘file’ field.
+ • Use BibLaTeX’s ‘Date’ field, if present, for displaying the year.
+ • Check for changed files on disk when saving all databases, not just
+ when saving the current database.
+ • Improve handling of multiple databases: ‘crossref’ entries can now
+ occur in other open databases as well, and searches with ‘/’ can be
+ continued in other databases.
+ • Autogenerating keys is now on by default.

File: ebib.info, Node: Installation, Next: Getting Started, Prev: News, Up: Top
@@ -255,7 +160,6 @@ File: ebib.info, Node: Installation, Next: Getting Started, Prev: News, Up:
* Debian and Ubuntu::
* Manual installation::
* Starting Ebib::
-* Upgrading from Ebib 1x::

File: ebib.info, Node: Package manager, Next: Debian and Ubuntu, Up: Installation
@@ -285,15 +189,14 @@ File: ebib.info, Node: Manual installation, Next: Starting Ebib, Prev: Debian
2.3 Manual installation
=======================
-It’s also possible to install Ebib manually by downloading the source,
-compiling it and telling Emacs where to find it. 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 Ebib’s
-dependencies, the dash (https://github.com/magnars/dash.el) and parsebib
-(https://github.com/joostkremers/parsebib) libraries.
+It’s also possible to install Ebib manually. If you prefer this method,
+then you probably know what you’re doing so detailed instructions are
+omitted here. Just be sure to also install the parsebib
+(https://github.com/joostkremers/parsebib) package, which Ebib depends
+on.

-File: ebib.info, Node: Starting Ebib, Next: Upgrading from Ebib 1x, Prev: Manual installation, Up: Installation
+File: ebib.info, Node: Starting Ebib, Prev: Manual installation, Up: Installation
2.4 Starting Ebib
=================
@@ -320,66 +223,6 @@ the following command:
starts Ebib and loads the file ‘references.bib’.

-File: ebib.info, Node: Upgrading from Ebib 1x, Prev: Starting Ebib, Up: Installation
-
-2.5 Upgrading from Ebib 1.x
-===========================
-
-If you upgrade from Ebib 1.x to the current version 2, there are a few
-things you need to be aware of. First, Ebib 2 does not support Emacs
-versions below 24.3. If you’re on an older version of Emacs, either
-upgrade Emacs, or do not upgrade Ebib. Ebib 1.x will continue to be
-available in the ‘pasture’ branch on Github or as a package on the
-Github releases page, so if for some reason you do not want to upgrade,
-you can continue to use this branch. Ebib 1.x will continue to be
-supported with bug fixes and possibly the occasional (small) feature
-addition, though no major changes will take place.
-
- If you do upgrade, it is important to note that a few customisation
-options have changed. If you never made any customisations to Ebib, the
-upgrade should not pose any problems. If you have, however, read on.
-
- The most important change is that the variable ‘ebib-entry-types’
-(option “Entry Types”) has been removed. Ebib now uses the entry type
-definitions of the built-in ‘bibtex-mode’, which means that if you wish
-to customise the entry types, you should customise
-‘bibtex-BibTeX-entry-alist’ or ‘bibtex-biblatex-entry-alist’.
-
- Secondly, a few user options have been renamed because their types
-have changed. (Mainly from ‘symbol’ to ‘string’). The name change
-means that existing customisations are lost, but it also prevents Ebib
-from throwing cryptic errors and refusing to run. If you customised any
-of the following options, you should redo them after upgrading Ebib (and
-preferably remove the old ones from your init file):
-
- • ‘ebib-default-entry’: renamed to ‘ebib-default-entry-type’.
- • ‘ebib-additional-fields’: renamed to ‘ebib-extra-fields’.
- • ‘ebib-standard-url-field’: renamed to ‘ebib-url-field’.
- • ‘ebib-standard-file-field’: renamed to ‘ebib-file-field’.
- • ‘ebib-standard-doi-field’: renamed to ‘ebib-doi-field’.
- • ‘ebib-biblatex-inheritance’: renamed to
- ‘ebib-biblatex-inheritances’ (note the ‘s’).
-
- Note that even if you customised ‘ebib-biblatex-inheritance’, there
-is most likely no need to customise its replacement
-‘ebib-biblatex-inheritances’, because the latter is set up with the
-default inheritance rules that Biblatex defines.
-
- Another thing to note is that four user options have a new default
-value. First, the default location of the rc file has moved to
-‘~/.emacs.d/ebibrc’, in line with the recommendation to keep all
-Emacs-related files in ‘~/.emacs.d’. If you kept an ‘.ebibrc’ file in
-your home directory, move it to ‘~/.emacs.d’. Second, a
-‘\documentclass’ definition has been added to the user options “Latex
-Preamble” (‘ebib-latex-preamble’) and “Print Preamble”
-(‘ebib-print-preamble’). If you customised one of these, you should add
-a document class specification, otherwise the LaTeX file won’t compile.
-Third, the option ‘ebib-save-xrefs-first’ now defaults to ‘t’.
-
- Lastly, if you use Biblatex, make sure to read the section on using
-Ebib with Biblatex files.
-
-
File: ebib.info, Node: Getting Started, Next: Editing the Database, Prev: Installation, Up: Top
3 Getting Started
@@ -424,6 +267,7 @@ database. You can also leave Ebib with the command ‘z’. However,
unlike ‘q’, which completely quits Ebib, ‘z’ only lowers it, so that it
remains active in the background. The ‘.bib’ files that you have opened
remain loaded, and you can return to them by typing ‘M-x ebib’ again.
+
* Menu:
* Opening a bib File::
@@ -439,14 +283,8 @@ File: ebib.info, Node: Opening a bib File, Next: Preloading bib Files, Up: Ge
Loading a ‘.bib’ file into Ebib is done with the command ‘o’. Ebib
reads the file that you specify, and reports how many entries it found,
-how many ‘@string’ definitions it found, and whether a ‘@preamble’ was
-found. Note that when Ebib reads a ‘.bib’ file, it only reads entry
-types (e.g. ‘book, article, phdthesis’ etc.) that it knows about.
-Therefore, you should make sure that all the entry types and fields that
-your databases use are defined. Ebib uses the entry type definitions of
-‘bibtex.el’, which is fairly complete, but if you use non-standard entry
-types, you may need to customise ‘bibtex-bibtex-entry-alist’ or
-‘bibtex-biblatex-entry-alist’, depending on which of the two you use.
+how many ‘@String’ definitions it found, and whether a ‘@Preamble’ was
+found.
Every time Ebib reads a ‘.bib’ file, it produces a few log messages.
These are written into a special buffer ‘*Ebib-log*’. If Ebib
@@ -456,14 +294,17 @@ it will log an error. If warnings and/or errors occurred during
loading, Ebib will issue a message when it finishes loading the ‘.bib’
and direct you to the log buffer.
- If Ebib finds entry types in a ‘.bib’ file that are not defined,
-those entries will still be loaded, but their entry type is displayed
-using Emacs’ ‘error’ face. The most likely case in which this will
-happen is when you load a Biblatex file without letting Ebib know the
-file is Biblatex-specific. By default, Ebib assumes that a ‘.bib’ file
-it loads is a BibTeX file. If you intend to use Biblatex files, make
-sure to read the section on Biblatex (*note Using Biblatex:
-#using-biblatex.).
+ In order to parse ‘.bib’ files, Ebib uses the entry type definitions
+of ‘bibtex.el’, which is fairly complete, but if you use non-standard
+entry types, you may need to customise ‘bibtex-bibtex-entry-alist’ or
+‘bibtex-biblatex-entry-alist’, depending on which of the two you use.
+If Ebib finds entry types in a ‘.bib’ file that are not defined, those
+entries will still be loaded, but their entry type is displayed using
+Emacs’ ‘error’ face. The most likely case in which this may happen is
+when you load a Biblatex file without letting Ebib know the file is
+Biblatex-specific. By default, Ebib assumes that a ‘.bib’ file it loads
+is a BibTeX file. If you intend to use Biblatex files, make sure to
+read the section on Biblatex (*note Using Biblatex: #using-biblatex.).

File: ebib.info, Node: Preloading bib Files, Next: Navigating a bib File, Prev: Opening a bib File, Up: Getting Started
@@ -497,7 +338,7 @@ in the index buffer in the top Ebib window. The first entry is
highlighted, meaning it is the current entry. The fields it holds and
their values are shown in the entry buffer in the bottom Ebib window.
The first field is the type field, which tells you what kind of entry
-you’re dealing with (i.e. ‘book’, ‘article’, etc.).
+you’re dealing with (i.e. ‘book’, ‘article’, etc.).
Below the type field, Ebib displays (up to) four sets of fields. The
first set are the so-called required fields, the fields that Bib(La)TeX
@@ -565,6 +406,7 @@ File: ebib.info, Node: Editing the Database, Next: Saving a Database, Prev: G
Of course, being able to open and view ‘.bib’ files is only half the
fun. One needs to be able to edit the files as well. Ebib’s essential
editing facilities are discussed here.
+
* Menu:
* Adding and Deleting Entries::
@@ -683,44 +525,49 @@ File: ebib.info, Node: Editing Multiline Values, Next: Undefined Fields, Prev
============================
Apart from the ‘type’, ‘keywords’, ‘file’ and ‘crossref’ fields, there
-is another field that Ebib handles in a special way when you edit its
-value. This is the ‘annote’ field (‘annotation’ in Biblatex). Most
-field values normally consist of a single line of text. However,
-because the ‘annote’ field is meant for creating annotated
-bibliographies, it would not be very useful if you could only write one
-line of text in this field. Therefore, when you edit the ‘annote’
-field, Ebib puts you in a so-called _multiline edit buffer_. This is
-essentially a text mode buffer that allows you to enter as much text as
-you like. To store the text and leave the multiline edit buffer, type
-‘C-c | q’.
+are two other fields that Ebib handles in a special way when you edit
+its value. These are the ‘annote’ field (or ‘annotation’ in Biblatex),
+and the ‘abstract’ field. Most field values normally consist of a
+single line of text. However, because the ‘annote’/‘annotation’ and
+‘abstract’ fields are meant for creating annotated bibliographies, it
+would not be very useful if you could only write one line of text in
+them. Therefore, when you edit one of these fields, Ebib puts you in a
+so-called _multiline edit buffer_. This is essentially a text mode
+buffer that allows you to enter as much text as you like. To store the
+text and leave the multiline edit buffer, type ‘C-c | q’.
If you want to leave the multiline edit buffer without saving the
text you have just typed, type ‘C-c | c’. This command cancels the edit
and leaves the multiline edit buffer. The text that is stored in the
field you were editing is not altered.
- Multiline values are not restricted to the ‘annote’ field. Any field
-(except the ‘type’ and ‘crossref’ fields) can in fact hold a multiline
-value. To give a field a multiline value, use ‘m’ instead of ‘e’. You
-will again be put in a multiline edit buffer, where you can edit the
-value. Note that you can use ‘m’ even if a field already has a single
-line value. Ebib will just make that the first line in the multiline
-edit buffer.
-
- When a field has a multiline value, only the first line is shown in
-the entry buffer, for space reasons. To indicate that the value is
-multiline, a plus sign ‘+’ is placed in front of the value. If you want
-to see the whole contents of a multiline field, you can use ‘v’: this
-will display the contents of the current field in a ‘*Help*’ buffer.
-This buffer can be dismissed again with ‘q’. This is quicker than
-entering the multiline edit buffer just to read the contents of a field
-and it has the advantage that the other fields stay visible.
+ Multiline values are not restricted to the ‘annote’/‘annotation’ and
+‘abstract’ fields. Any field (except the ‘type’ and ‘crossref’ fields)
+can in fact hold a multiline value. To give a field a multiline value,
+use ‘m’ instead of ‘e’. You will again be put in a multiline edit
+buffer, where you can edit the value. Note that you can use ‘m’ even if
+a field already has a single line value. Ebib will just make that the
+first line in the multiline edit buffer.
+
+ When a field has a multiline value, at most ten lines are shown in
+the entry buffer. If the text is longer, an ellipsis indicator ‘[...]’
+is added after the last line that is displayed. If you want to see the
+whole contents of a multiline field, you can use ‘v’: this will display
+the contents of the current field in a ‘*Help*’ buffer. This buffer can
+be dismissed again with ‘q’. This is quicker than entering the
+multiline edit buffer just to read the contents of a field and it has
+the advantage that the other fields stay visible.
+
+ It’s possible to customise the way a multiline value is displayed in
+the entry buffer. See the options ‘ebib-multiline-display-function’ and
+‘ebib-multiline-display-max-lines’ for details.
By the way, the ‘e’ key is smart about the way an entry must be
edited. If you press ‘e’ on a field that already has a multiline value,
-regardless of the fact whether it is the ‘annote’ field or not, Ebib
-puts you in a multiline edit buffer. Therefore, you need ‘m’ only if
-you want to give a field a multiline value when it doesn’t have one yet.
+regardless of the fact whether it is the ‘annote’/‘annotation’ or
+‘abstract’ field or not, Ebib puts you in a multiline edit buffer.
+Therefore, you need ‘m’ only if you want to give a field a multiline
+value when it doesn’t have one yet.
For more details on working with multiline edit buffers, see *note
Multiline Edit Buffers: #multiline-edit-buffers.
@@ -879,6 +726,7 @@ Compared to BibTeX, Biblatex has a greatly expanded number of fields, a
somewhat different set of entry types and a much more complex system of
field value inheritances. Ebib can handle both kinds of files, provided
it is set up for the right “dialect”.
+
* Menu:
* Setting the BibTeX Dialect::
@@ -985,10 +833,42 @@ the column can be sorted. You can add or remove fields, or reorder the
existing ones.
You can use any BibTeX / BibLaTeX field to define a column in the
-index buffer. In addition, there are two column labels with a special
-meaning: ‘"Entry Key"’, which displays the entry key, and
-‘"Author/Editor"’, which displays the contents of the author field if it
-is not empty, and the contents of the editor field otherwise.
+index buffer. In addition, there are two column labels that do not
+correspond directly to a field name. These are ‘"Entry Key"’, which
+displays the entry key, ‘"Author/Editor"’, which displays the contents
+of the author field if it is not empty, and the contents of the editor
+field otherwise. Furthermore, the column label ‘"Year"’ does not
+display the contents of the year field unconditionally. Rather, it
+first checks the contents of the date field, which is BibLaTeX’s
+replacement of the year field, and extracts the first year in it. Only
+if the date field is empty does it display the year field.
+
+ Three other column labels have special behaviour: ‘"Title"’, ‘"Doi"’,
+and ‘"Url"’. These do display information from the fields they
+correspond with, but in a special way: ‘"Title"’ tries to make the title
+look nice by removing braces and LaTeX commands (including their
+optional arguments) and by displaying the arguments of ‘\emph’,
+‘\textit’, ‘\textbf’ and ‘\textsc’ in italic, bold or caps. ‘"Doi"’ and
+‘"Url"’ don’t display the contents of these fields, but instead yield a
+clickable string ‘"www"’. Clicking on ‘"www"’ takes you to the relevant
+web page.
+
+ The final predefined column label is “Note”. This does not, as might
+be expected, display the contents of the note field. Rather, it checks
+whether the entry in question has a note associated with it in Ebib’s
+own notes system, discussed in *note Notes Files: #notes-files. For
+those entries that have a note, the ‘"Note"’ column will display a
+(clickable) ‘"N"’. Keep in mind, though, that if you keep your notes in
+a single file, adding this column to the index display can slow down the
+creation of the index buffer (and thus Ebib’s start-up). If you wish to
+use this column, it is probably best to keep notes in separate files.
+
+ You can define new column labels and redefine the existing ones by
+customising the option ‘ebib-field-transformation-functions’. Note that
+‘"Title"’, ‘"Doi"’, ‘"Url"’, and ‘"Note"’ are actually defined through
+this option. ‘"Entry Key"’, ‘"Author/Editor"’, and ‘"Year"’ are not
+(they are hard-coded), but they can be overridden by adding an entry for
+them in ‘ebib-field-transformation-functions’.
The first column defined in ‘ebib-index-colums’ is the column on
which the entries are sorted by default, i.e., when the database is
@@ -1037,27 +917,33 @@ term is found, Ebib gives a message saying so, similarly if the search
term was not found.
A search term may of course appear more than once in the database.
-To search for the next occurrence, type ‘/’ again (or, alternatively
-type ‘RET’). This continues searching for the search term in the rest
-of the database. Again, the first entry found to contain the search
-string is displayed. Note that the search does not wrap: if the end of
-the database is reached, Ebib stops searching and informs you that no
-further occurrence of the search string was found. If you want to
-continue searching from the top, type ‘g’ and then continue the search
-with ‘/’ or ‘RET’.
+To search for the next occurrence, type ‘RET’. This continues searching
+for the search term in the rest of the database. Again, the first entry
+found to contain the search string is displayed. Note that the search
+does not wrap: if the end of the database is reached, Ebib stops
+searching and informs you that no further occurrence of the search
+string was found. If you want to continue searching from the top, type
+‘g’ and then continue the search with ‘RET’.
Note that once you’ve started a search with ‘/’, Ebib activates a
transient key map called ‘ebib-search-map’. It is this map that holds
-the bindings of ‘/’ and ‘RET’ to continue searching after the current
-entry and of the key ‘g’ to jump to the top of the database. You can,
-of course, bind or rebind keys in this map.
+the binding for ‘RET’ to continue searching after the current entry and
+of the key ‘g’ to jump to the top of the database. There are also
+bindings for the left and right cursor keys, which take you to the
+previous and next database, so you can continue searching there.
Exiting a search (i.e., getting rid of the transient key map) is done
-by pressing any key other than ‘/’, ‘RET’ or ‘g’. The search is ended
-and the command associated with this key is executed normally. If you
-want to repeat a previous search, you can pass a prefix argument to ‘/’.
-So typing ‘C-u /’ (or any other prefix argument) starts searching for
-the previous search string again.
+by pressing any key other than ‘RET’, ‘g’ or the left/right cursor keys.
+The search is ended and the command associated with this key is executed
+normally. If you want to repeat a previous search, you can pass a
+prefix argument to ‘/’. So typing ‘C-u /’ starts searching for the
+previous search string again.
+
+ Note that if you start a search in a filtered database (i.e., a
+database in which not all entries are visible; see the next section),
+only the visible entries are searched. If the search string is present
+in the database but not in one of the visible entries, Ebib will respond
+with a “search string not found” message.

File: ebib.info, Node: Filters, Prev: Simple Searches, Up: Searching
@@ -1077,6 +963,7 @@ want: you can select all entries that do _not_ contain “Jones” in the
the ‘author’ field, and “symbiotic hibernation” in the ‘keyword’ field,
etc. Basically, the filter can consist of an arbitary number of search
criteria combined with the logical operators ‘and’, ‘or’ and ‘not’.
+
* Menu:
* Simple Selection::
@@ -1152,7 +1039,7 @@ you want to filter with. Ebib will then update the index buffer.
It is also possible to perform a logical ‘and’ on the filter. Use
this if you want to select those entries that contain “Jones” in the
-‘author’ field and e.g. “symbiotic hibernation” in the ‘keyword’ field.
+‘author’ field and e.g. “symbiotic hibernation” in the ‘keyword’ field.
A logical ‘and’ operation is done with the key ‘&’. (Note: this is the
same key that is used to create the filter. In fact, you can create a
filter with ‘|’ as well: when used in an unfiltered database, ‘&’ and
@@ -1260,19 +1147,18 @@ Filters are essentially Lisp expressions that consist of the functions
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 a special
-filter.
+them in a filter file, or to write a function that creates such a
+special filter.
A filter is a Lisp expression that should return either ‘t’ or ‘nil’,
indicating whether the entry being tested matches the filter or not.
-The contents of the entry is available in a variable ‘entry’. This
+The contents of the entry is available in a variable ‘ebib-entry’. This
variable is given a value by the function that runs the filter, but it
-is not passed as an argument. Rather, it is a local dynamic variable,
-which means that the file that defines the filter function should have
-the variable ‘lexical-binding’ set to ‘nil’.
-
- The value of ‘entry’ is an alist of fields and their values. These
-include the fields ‘=key=’ and ‘=type=’ for the entry key and type:
+is not passed as an argument. Rather, it is a dynamic variable, which
+means that the file that defines the filter function should declare the
+variable with ‘(defvar ebib-entry)’. When the filter is run, the value
+of ‘ebib-entry’ is an alist of fields and their values. These include
+the fields ‘=key=’ and ‘=type=’ for the entry key and type:
(("author" . "{Noam Chomsky}")
("title" . "{Syntactic Structures}")
@@ -1297,25 +1183,28 @@ to the database. The command that creates the filter is
(defun ebib-list-recent (days)
"List entries created in the last DAYS days."
(interactive "nNumber of days: ")
- ;; save the database's current filter, if there is one.
+ ;; Save the database's current filter, if there is one.
(let ((filter (ebib-db-get-filter ebib--cur-db)))
(when filter (setq ebib--filters-last-filter filter)))
(let*
- ;; calculate the from-date in Emacs' time format
+ ;; Calculate the from-date in Emacs' time format.
((date (time-subtract (current-time) (days-to-time days)))
- ;; create a Lisp expression that will function as the filter
+ ;; Create a Lisp expression that will function as the filter.
(filter `(ebib--newer-than (quote ,date))))
- ;; install it as the curretn database's filter
+ ;; Install it as the current database's filter.
(ebib-db-set-filter filter ebib--cur-db)
- ;; update the display, so that only filtered entries are visible
- (ebib--redisplay)))
+ ;; Update the current entry key.
+ (ebib-db-set-current-entry-key (ebib--get-key-at-point) ebib--cur-db)
+ ;; Update the display, so that only filtered entries are visible.
+ (ebib--update-buffers)))
First, this function saves the current filter if there is one. It
-then creates a date in Emacs’ internal time format by subtracting the
-number of days provided by the user from the current date and uses this
-date to create a Lisp expression which is then installed as the filter
-for the current database. A call to ‘ebib--redisplay’ then updates the
-display, taking the filter into account.
+then calculates a date in Emacs’ internal time format by subtracting the
+number of days provided by the user from the current date and creates a
+Lisp expression that tests whether an entry’s timestamp is earlier or
+later than this date. This expression is then installed as the filter
+for the current database. A call to ‘ebib--update-buffers’ then updates
+the display, taking the filter into account.
The function ‘ebib--newer-than’ is defined as follows:
@@ -1326,15 +1215,15 @@ be a list of the format returned by `current-time' and is
compared to the timestamp of the entry being tested. If the
entry has no timestamp, or a timestamp that cannot be converted
into a date representation, return nil."
- (let ((timestamp (cdr (assoc-string "timestamp" entry))))
+ (let ((timestamp (cdr (assoc-string "timestamp" ebib-entry))))
(when (and timestamp
(setq timestamp (ignore-errors (date-to-time timestamp))))
(time-less-p date timestamp))))
This function obtains the time stamp of the entry being tested from
-the variable ‘entry’ and then tries to convert it to Emacs’ time format.
-If successful, it compares this time to the date passed as an argument
-and returns ‘t’ if the latter precedes the former.
+the variable ‘ebib-entry’ and then tries to convert it to Emacs’ time
+format. If successful, it compares this time to the date passed as an
+argument and returns ‘t’ if the latter precedes the former.

File: ebib.info, Node: Properties of Filtered Databases, Prev: An Example Listing Recent Additions, Up: Filters
@@ -1359,7 +1248,7 @@ then cancel the filter and perform an action on them.
because it would not be clear whether you want to save the entire
database or just the filtered entries. If you want to save only the
filtered entries to a file, you can use the command ‘w’ (or the menu
-option “Save Database As”). This also saves the ‘@string’, ‘@preamble’
+option “Save Database As”). This also saves the ‘@String’, ‘@Preamble’
and ‘@comments’, as well as any file-local variables, so you will have a
self-contained ‘.bib’ file with only the filtered entries. In order to
save the entire database, you need to cancel the filter. After saving,
@@ -1463,6 +1352,7 @@ used in the document. Note, however, that this command does not add
cross-referenced entries to the newly created ‘.bib’ file, nor does it
add ‘@String’ definitions and the ‘@Preamble’. So make sure to add
those after using ‘ebib-create-bib-from-bbl’.
+
* Menu:
* Key Bindings::
@@ -1970,6 +1860,7 @@ is then appended with the extension ‘.pdf’.
Of course, the function in ‘ebib-name-transform-function’ does not
have to be a lambda. It can also be the name of a function that you’ve
defined for the purpose.
+
* Menu:
* Editing the file field::
@@ -2080,6 +1971,7 @@ searched.
All three hooks are customisable. For example, if you prefer not to
narrow the buffer, simply remove the corresponding functions from the
hooks.
+
* Menu:
* Customising the notes template::
@@ -2300,44 +2192,44 @@ File: ebib.info, Node: @Preamble Definition, Next: @String Definitions, Prev:
***********************
Apart from database entries, BibTeX allows three more types of elements
-to appear in a ‘.bib’ file. These are ‘@comment’, ‘@preamble’ and
-‘@string’ definitions. Ebib provides facilities to handle these, which
+to appear in a ‘.bib’ file. These are ‘@comment’, ‘@Preamble’ and
+‘@String’ definitions. Ebib provides facilities to handle these, which
are discussed here and in the following sections.
- Ebib allows you to add one ‘@preamble’ definition to the database.
+ Ebib allows you to add one ‘@Preamble’ definition to the database.
In principle, BibTeX allows more than one such definition, but really
one suffices, because you can use the concatenation character ‘#’ to
include multiple TeX or LaTeX commands. So, rather than having two
-‘@preamble’ definitions such as:
+‘@Preamble’ definitions such as:
-@preamble{ "\newcommand{\noopsort}[1]{} " }
-@preamble{ "\newcommand{\singleletter}[1]{#1} " }
+@Preamble{ "\newcommand{\noopsort}[1]{} " }
+@Preamble{ "\newcommand{\singleletter}[1]{#1} " }
you can write this in your ‘.bib’ file:
-@preamble{ "\newcommand{\noopsort}[1]{} "
+@Preamble{ "\newcommand{\noopsort}[1]{} "
# "\newcommand{\singleletter}[1]{#1} " }
- Creating or editing a ‘@preamble’ definition in Ebib is done by
+ Creating or editing a ‘@Preamble’ definition in Ebib is done by
hitting (uppercase) ‘P’ in the index buffer. Ebib uses the multiline
-edit buffer for editing the text of the ‘@preamble’ definition, which
-means that ‘C-c | q’ stores the ‘@preamble’ text and returns focus to
+edit buffer for editing the text of the ‘@Preamble’ definition, which
+means that ‘C-c | q’ stores the ‘@Preamble’ text and returns focus to
the index buffer, while ‘C-c | c’ returns focus to the index buffer
while abandoning any changes you may have made. (For details on using
multiline edit buffers, see *note Multiline Edit Buffers:
#multiline-edit-buffers.)
- In order to create a ‘@preamble’ as shown above in Ebib, you only
+ In order to create a ‘@Preamble’ as shown above in Ebib, you only
have to type the text between the braces. Ebib takes care of including
-the braces of the ‘@preamble’ command, but otherwise it saves the text
+the braces of the ‘@Preamble’ command, but otherwise it saves the text
exactly as you enter it. So in order to get the preamble above, you’d
have to type the following in Ebib:
"\newcommand{\noopsort}[1]{} " # "\newcommand{\singleletter}[1]{#1} "
Note that when Ebib loads a ‘.bib’ file that contains more than one
-‘@preamble’ definition, it concatenates all the strings in them in the
-manner just described and saves them in one ‘@preamble’ definition.
+‘@Preamble’ definition, it concatenates all the strings in them in the
+manner just described and saves them in one ‘@Preamble’ definition.

File: ebib.info, Node: @String Definitions, Next: @Comments, Prev: @Preamble Definition, Up: Top
@@ -2347,29 +2239,29 @@ File: ebib.info, Node: @String Definitions, Next: @Comments, Prev: @Preamble
If you press (uppercase) ‘S’ in the index buffer, Ebib hides the entry
buffer in the lower window and replaces it with the _strings buffer_.
-In this buffer, you can add, delete and edit ‘@string’ definitions.
+In this buffer, you can add, delete and edit ‘@String’ definitions.
- Adding a ‘@string’ definition is done with the command ‘a’. This
+ Adding a ‘@String’ definition is done with the command ‘a’. This
will first ask you for an abbreviation and then for the value to be
associated with that abbreviation. Once you’ve entered these, Ebib will
sort the new abbreviation into the buffer.
- Moving between the ‘@string’ definitions can be done in the usual
+ Moving between the ‘@String’ definitions can be done in the usual
way: the cursor keys ‘up’ and ‘down’, ‘p’ and ‘n’ or ‘C-p’ and ‘C-n’
move up and down. ‘Space’ and ‘PgDn’ move ten strings down, while ‘b’
and ‘PgUp’ move in the other direction. The keys ‘g’, ‘G’, ‘Home’ and
‘End’ also function as expected.
- To delete a ‘@string’ definition, use ‘d’. To edit the value of a
+ To delete a ‘@String’ definition, use ‘d’. To edit the value of a
definition, use ‘e’. There is also a command ‘c’, which copies the
-value of the current ‘@string’ definition to the kill ring. Unlike in
+value of the current ‘@String’ definition to the kill ring. Unlike in
the entry buffer, there are no corresponing commands ‘y’ and ‘x’. (In
fact, ‘x’ does exist, but has another function.) Yanking from the kill
ring can be done with ‘C-y/M-y’ in the minibuffer when you edit a
-‘@string’’s value. Cutting a ‘@string’’s value is pointless, because a
-‘@string’ definition must have a value.
+‘@String’’s value. Cutting a ‘@String’’s value is pointless, because a
+‘@String’ definition must have a value.
- Having defined ‘@string’ definitions, there must of course be a way
+ Having defined ‘@String’ definitions, there must of course be a way
to use them. Just giving a field a string abbreviation as value will
not do, because Ebib puts braces around the value that you enter when it
writes the ‘.bib’ file, so that BibTeX will not recognise the
@@ -2388,7 +2280,7 @@ have a value yet, Ebib will ask you for one.
composed of concatenations of strings and abbreviations. The BibTeX
documentation for example explains that if you have defined:
-@string{WGA = "World Gnus Almanac"}
+@String{WGA = "World Gnus Almanac"}
you can create a BibTeX field like this:
@@ -2403,11 +2295,11 @@ bibliography style has defined the abbreviation ‘jan’. All this is
possible with Ebib, simply by entering the exact text including quotes
or braces around the strings, and marking the relevant field as special.
- An easy way to enter a ‘@string’ abbreviation as a field value is to
+ An easy way to enter a ‘@String’ abbreviation as a field value is to
use the key ‘s’ instead of ‘e’. If you type ‘s’, Ebib asks you for a
-‘@string’ abbreviation to put in the current field, and automatically
+‘@String’ abbreviation to put in the current field, and automatically
marks the field as special. With this command, Ebib only accepts
-‘@string’ definitions that are in the database, so that by using ‘s’ you
+‘@String’ definitions that are in the database, so that by using ‘s’ you
can make sure you don’t make any typos. Note that you can use TAB
completion to complete a partial string.
@@ -2420,7 +2312,7 @@ File: ebib.info, Node: @Comments, Next: Managing Keywords, Prev: @String Defi
If Ebib finds a ‘@comment’ in a ‘.bib’ file, it will read it and store
it in the database. When the database is saved, all the ‘@comment’s
will be saved with it, at the top of the file (right after the
-‘@preamble’.) There is no way to edit comments, nor can you specify
+‘@Preamble’.) There is no way to edit comments, nor can you specify
where in the ‘.bib’ file a comment is placed, but they won’t be lost.

@@ -2634,35 +2526,27 @@ File: ebib.info, Node: Exporting Entries, Next: Multiple Identical Fields, Pr
Sometimes it can be useful to copy entries from one database to another,
or to create a new ‘.bib’ file with several entries from an existing
database. For this purpose, Ebib provides exporting facilities. To
-export an entry to a ‘.bib’ file, use the command ‘x’. This command
-operates on a single entry or on all marked entries.
-
- When you export one or more entries, Ebib will ask you for a filename
-to export them to. If you have already exported an entry before, Ebib
-will present the filename you used as default, but you can of course
-change it. For obvious reasons, Ebib appends the entry to the file that
-you enter if it already exists, it does not overwrite the file. If this
-is not what you want, delete the file first, as Ebib provides no way to
-do this.
-
- If you have more than one database open in Ebib, it is also possible
-to copy entries from one database to another. To do this, use the ‘x’
-command with a numeric prefix argument. E.g., if the database you want
-to export an entry to is the second database, type ‘M-2 x’ to export the
-current entry to it. The number of the database is given in the
-modeline of the index buffer. If the database you’re copying an entry
-to already contains an entry with the same entry key, Ebib won’t copy
-the entry, and issues an appropriate warning message.
-
- Apart from entries, it is also possible to export the ‘@preamble’ and
-‘@string’ definitions. The ‘@preamble’ definition is exported with the
-command ‘X’ in the index buffer. ‘@string’ definitions can be exported
+export an entry to another database, use the command ‘x’. This command
+operates on a single entry or on all marked entries. Ebib will ask you
+for the database to export the entry or entries to. TAB-completion is
+available, based on the file names of the databases.
+
+ You can also export entries to a file. To do this, call the command
+‘x’ with a prefix argument: ‘C-u x’. You will be prompted for the file
+name 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 it’s possible
+to end up with duplicate entries in this way.
+
+ Apart from entries, it is also possible to export the ‘@Preamble’ and
+‘@String’ definitions. The ‘@Preamble’ definition is exported with the
+command ‘X’ in the index buffer. ‘@String’ definitions can be exported
in the strings buffer: ‘x’ in this buffer exports the current string,
-while ‘X’ exports all ‘@string’ definitions in one go. All these
+while ‘X’ exports all ‘@String’ definitions in one go. All these
commands function in the same way: when used without a prefix argument,
-they ask for a filename, and then append the relevent data to that file.
-With a numeric prefix argument, they copy the relevant data to the
-corresponding open database.
+they ask for an open database to export the entry to. With a prefix
+argument, they ask for a filename, and then append the relevant data to
+that file.

File: ebib.info, Node: Multiple Identical Fields, Next: Multiline Edit Buffers, Prev: Exporting Entries, Up: Top
@@ -2721,24 +2605,21 @@ File: ebib.info, Node: Multiline Edit Buffers, Next: The Options Menu, Prev:
27 Multiline Edit Buffers
*************************
-As mentioned several times before, Ebib has a special multiline edit
-buffer, which is used to edit field values that contain newlines
-(so-called _multiline fields_), and also to edit the contents of the
-‘@preamble’ command. This section discusses the details of this buffer.
+As mentioned several times before, field values that contain newlines
+(so-called _multiline fields_) and the ‘@Preamble’ are edited in a
+so-called _multiline edit buffer_. This section discusses the details
+of this buffer.
- Ebib enters multiline edit mode in one of three cases: when you edit
-the ‘@preamble’ definition, when you hit ‘m’ in the entry buffer to edit
-the current field as multiline, or when you hit ‘e’ on the ‘annote’
-field, or on a field whose value already is multiline.
+ Ebib enters a multiline edit buffer in one of three cases: when you
+edit the ‘@Preamble’ definition, when you hit ‘m’ in the entry buffer to
+edit the current field as multiline, or when you hit ‘e’ on the
+‘annote’/‘annotation’ or ‘abstract fields, or on a field whose value
+already is multiline.
- The mode that is used in the multiline edit buffer is
+ The major mode that is used in multiline edit buffers is
user-configurable. The default value is ‘text-mode’, but if you prefer
to use some other mode, you can specify this through the customisation
-options. (Personally, I use ‘markdown-mode’ in the multiline edit
-buffer, so that I can use ‘Markdown’
-(http://daringfireball.net/projects/markdown/) to write annotations,
-which provides an easy way to create headers, use bold and italic, etc.,
-in plain text.)
+option ‘ebib-multiline-major-mode’.
Three commands are relevant for interacting with Ebib when you’re in
the multiline edit buffer, which are bound to key sequences in the minor
@@ -2749,11 +2630,10 @@ multiline edit buffer.
multiline edit buffer and stores the text in the database. If you
invoke this command when you’ve deleted all contents of the buffer
(including the final newline!) and you were editing a field value or
-the ‘@preamble’, the field value or preamble is deleted. (This is in
-fact the _only_ way to delete the ‘@preamble’ definition. Field values
-on the other hand can also be deleted by hitting ‘x’ or ‘d’ on them in
-the entry buffer.) If you were editing a ‘@string’ value, Ebib will
-just complain, because string definitions cannot be empty.
+the ‘@Preamble’, the field value or preamble is deleted. (This is in
+fact the _only_ way to delete the ‘@Preamble’ definition. Field values
+on the other hand can also be deleted by hitting ‘k’ or ‘d’ on them in
+the entry buffer.)
‘ebib-cancel-multiline-buffer’, bound to ‘C-c | c’, also leaves the
multiline edit buffer, but it does so without storing the text. The
@@ -2770,27 +2650,28 @@ crashes. It would be annoying to have to leave the multiline edit
buffer every time you want to do this, so this command has been provided
to allow you to do this from within the buffer.
+ Note that you do not need to finish a multiline edit before you can
+return to the database and possibly edit other fields and even entries.
+Ebib keeps track of which field in which entry of which database a
+multiline edit buffer belongs to, so you can keep a multiline edit
+buffer open while doing other work. It is even possible to have several
+multiline edit buffers open at the same time. Ebib makes sure that when
+you finish one, its contents is stored in the correct place.
+
Admittedly, the key combinations of the multiline edit buffer are
somewhat awkward. The reason for this is that these commands are part
of a minor mode, which restricts the available keys to combinations of
‘C-c’ plus a non-alphanumeric character. However, it is possible to
-change the key commands, if you wish. Ebib itself provides a method to
-change the second key of these commands, *note Modifying Key Bindings:
-#modifying-key-bindings. You could change the ‘|’ to e.g., ‘c’ or
-‘C-c’, if these do not conflict with any key commands in the major mode
-used for the multiline edit buffer.
-
- Even more drastically, you could put something like the following in
-your ‘~/.emacs’:
-
-(eval-after-load 'ebib
- '(progn
- (define-key ebib-multiline-mode-map
- "\C-c\C-c" 'ebib-quit-multiline-buffer-and-save)
- (define-key ebib-multiline-mode-map
- "\C-c\C-q" 'ebib-cancel-multiline-buffer)
- (define-key ebib-multiline-mode-map
- "\C-c\C-s" 'ebib-save-from-multiline-buffer)))
+change the key commands, if you wish. For example, you could put
+something like the following in your ‘~/.emacs’:
+
+(with-eval-after-load 'ebib
+ (define-key ebib-multiline-mode-map
+ "\C-c\C-c" 'ebib-quit-multiline-buffer-and-save)
+ (define-key ebib-multiline-mode-map
+ "\C-c\C-q" 'ebib-cancel-multiline-buffer)
+ (define-key ebib-multiline-mode-map
+ "\C-c\C-s" 'ebib-save-from-multiline-buffer)))
This sets up ‘C-c C-c’, ‘C-c C-q’ and ‘C-c C-s’ for use in the
multiline edit buffer. Since such key combinations are restricted for
@@ -2830,11 +2711,6 @@ documented in the customisation buffers. You can go to Ebib’s
customisation buffer with ‘M-x customize-group RET ebib RET’, or by
using the menu «Ebib | Options | Customize Ebib».
- Another way to customise Ebib is to use the initialisation file
-‘~/.emacs.d/ebibrc’. (Actually, the location and name of this file can
-be customised as well.) This file contains normal Lisp code and is the
-best way to customise key bindings (as discussed in the next section),
-but it can in fact be used to run any Lisp code.
* Menu:
* Modifying Key Bindings::
@@ -2863,163 +2739,152 @@ keywords and the reading list, respectively. Finally, there is
As an example, the default keybindings in‘ebib-multiline-mode-map’,
which are rather awkward to type, can be redefined as follows:
-(define-key ebib-multiline-mode-map
- "\C-c\C-c" 'ebib-quit-multiline-buffer-and-save)
-(define-key ebib-multiline-mode-map
- "\C-c\C-q" 'ebib-cancel-multiline-buffer)
-(define-key ebib-multiline-mode-map
- "\C-c\C-s" 'ebib-save-from-multiline-buffer)
+(with-eval-after-load 'ebib
+ (define-key ebib-multiline-mode-map
+ "\C-c\C-c" 'ebib-quit-multiline-buffer-and-save)
+ (define-key ebib-multiline-mode-map
+ "\C-c\C-q" 'ebib-cancel-multiline-buffer)
+ (define-key ebib-multiline-mode-map
+ "\C-c\C-s" 'ebib-save-from-multiline-buffer)))

Tag Table:
Node: Top186
-Node: News1485
-Ref: #news1575
-Node: Version 212 August 20181903
-Ref: #version-2.12-august-20182058
-Node: Version 21112 July 20182338
-Ref: #version-2.11.12-july-20182528
-Node: Version 211 January 20172961
-Ref: #version-2.11-january-20173152
-Node: Version 210 January 20173195
-Ref: #version-2.10-january-20173386
-Node: Version 29 January 20173425
-Ref: #version-2.9-january-20173606
-Node: 19 December 20163774
-Ref: #december-20163928
-Node: 7 December 20164389
-Ref: #december-2016-14533
-Node: 5 December 20164575
-Ref: #december-2016-24718
-Node: 7 November 20165410
-Ref: #november-20165564
-Node: Version 28 26 October 20166354
-Ref: #version-2.8-26-october-20166549
-Node: Version 27 22 September 20167987
-Ref: #version-2.7-22-september-20168197
-Node: Version 263 31 August 20168634
-Ref: #version-2.6.3-31-august-20168807
-Node: Installation9226
-Ref: #installation9344
-Node: Package manager9465
-Ref: #package-manager9594
-Node: Debian and Ubuntu9945
-Ref: #debian-and-ubuntu10106
-Node: Manual installation10240
-Ref: #manual-installation10403
-Node: Starting Ebib10806
-Ref: #starting-ebib10962
-Node: Upgrading from Ebib 1x11870
-Ref: #upgrading-from-ebib-1.x12018
-Node: Getting Started15135
-Ref: #getting-started15275
-Node: Opening a bib File17649
-Ref: #opening-a-.bib-file17803
-Node: Preloading bib Files19514
-Ref: #preloading-.bib-files19702
-Node: Navigating a bib File20508
-Ref: #navigating-a-.bib-file20703
-Node: Starting a New bib File24035
-Ref: #starting-a-new-.bib-file24205
-Node: Editing the Database24497
-Ref: #editing-the-database24652
-Node: Adding and Deleting Entries25029
-Ref: #adding-and-deleting-entries25206
-Node: Editing Fields Values27786
-Ref: #editing-fields-values27984
-Node: Editing Multiline Values30633
-Ref: #editing-multiline-values30826
-Node: Undefined Fields33340
-Ref: #undefined-fields33509
-Node: Hidden Fields34505
-Ref: #hidden-fields34654
-Node: Timestamps35550
-Ref: #timestamps35712
-Node: Copy Cut Kill Paste Yank and Delete37775
-Ref: #copy-cut-kill-paste-yank-and-delete37979
-Node: Saving a Database38931
-Ref: #saving-a-database39079
-Node: Using Biblatex40754
-Ref: #using-biblatex40892
-Node: Setting the BibTeX Dialect41219
-Ref: #setting-the-bibtex-dialect41388
-Node: Alias Types and Fields43428
-Ref: #alias-types-and-fields43589
-Node: The Entries List45775
-Ref: #the-entries-list45909
-Node: Searching47556
-Ref: #searching47701
-Node: Simple Searches47743
-Ref: #simple-searches47859
-Node: Filters50558
-Ref: #filters50658
-Node: Simple Selection51732
-Ref: #simple-selection51861
-Node: Complex Filters53555
-Ref: #complex-filters53717
-Node: Storing and Saving Filters57760
-Ref: #storing-and-saving-filters57943
-Node: Special Filters60822
-Ref: #special-filters61003
-Node: An Example Listing Recent Additions62358
-Ref: #an-example-listing-recent-additions62587
-Node: Properties of Filtered Databases64755
-Ref: #properties-of-filtered-databases64952
-Node: Accessing BibTeX Databases outside Ebib66610
-Ref: #accessing-bibtex-databases-outside-ebib66816
-Node: Key Bindings71736
-Ref: #key-bindings71892
-Node: Defining Citation Commands72656
-Ref: #defining-citation-commands72889
-Node: Associating a Database with a LaTeX File78805
-Ref: #associating-a-database-with-a-latex-file79045
-Node: Cross-referencing81988
-Ref: #cross-referencing82158
-Node: Marking Entries85471
-Ref: #marking-entries85619
-Node: Printing the Database86602
-Ref: #printing-the-database86762
-Node: Calling a Browser90569
-Ref: #calling-a-browser90719
-Node: Viewing Files93351
-Ref: #viewing-files93483
-Node: Editing the file field97276
-Ref: #editing-the-file-field97411
-Node: Notes files98770
-Ref: #notes-files98904
-Node: Customising the notes template103049
-Ref: #customising-the-notes-template103198
-Node: Managing a reading list106244
-Ref: #managing-a-reading-list106406
-Node: Window Management109501
-Ref: #window-management109660
-Node: Creating Entry Stubs112836
-Ref: #creating-entry-stubs112998
-Node: @Preamble Definition113999
-Ref: #preamble-definition114163
-Node: @String Definitions116149
-Ref: #string-definitions116300
-Node: @Comments119816
-Ref: #comments119944
-Node: Managing Keywords120309
-Ref: #managing-keywords120454
-Node: Sorting the bib File126363
-Ref: #sorting-the-.bib-file126536
-Node: Merging and Importing129675
-Ref: #merging-and-importing129840
-Node: Exporting Entries131616
-Ref: #exporting-entries131778
-Node: Multiple Identical Fields133753
-Ref: #multiple-identical-fields133932
-Node: Multiline Edit Buffers135841
-Ref: #multiline-edit-buffers136013
-Node: The Options Menu140143
-Ref: #the-options-menu140291
-Node: Customisation140912
-Ref: #customisation141023
-Node: Modifying Key Bindings141966
-Ref: #modifying-key-bindings142093
+Node: News1323
+Ref: #news1413
+Node: Version 215 January 20191630
+Ref: #version-2.15-january-20191790
+Node: Version 214 December 20182243
+Ref: #version-2.14-december-20182439
+Node: Version 213 November 20182881
+Ref: #version-2.13-november-20183079
+Node: Version 2123 November 20183278
+Ref: #version-2.12.3-november-20183481
+Node: Version 2122 November 20183556
+Ref: #version-2.12.2-november-20183757
+Node: Version 212 August 20183897
+Ref: #version-2.12-august-20184087
+Node: Version 21112 July 20184367
+Ref: #version-2.11.12-july-20184524
+Node: Installation4957
+Ref: #installation5075
+Node: Package manager5169
+Ref: #package-manager5298
+Node: Debian and Ubuntu5649
+Ref: #debian-and-ubuntu5810
+Node: Manual installation5944
+Ref: #manual-installation6107
+Node: Starting Ebib6387
+Ref: #starting-ebib6512
+Node: Getting Started7420
+Ref: #getting-started7560
+Node: Opening a bib File9935
+Ref: #opening-a-.bib-file10089
+Node: Preloading bib Files11591
+Ref: #preloading-.bib-files11779
+Node: Navigating a bib File12585
+Ref: #navigating-a-.bib-file12780
+Node: Starting a New bib File16111
+Ref: #starting-a-new-.bib-file16281
+Node: Editing the Database16573
+Ref: #editing-the-database16728
+Node: Adding and Deleting Entries17106
+Ref: #adding-and-deleting-entries17283
+Node: Editing Fields Values19863
+Ref: #editing-fields-values20061
+Node: Editing Multiline Values22710
+Ref: #editing-multiline-values22903
+Node: Undefined Fields25752
+Ref: #undefined-fields25921
+Node: Hidden Fields26917
+Ref: #hidden-fields27066
+Node: Timestamps27962
+Ref: #timestamps28124
+Node: Copy Cut Kill Paste Yank and Delete30187
+Ref: #copy-cut-kill-paste-yank-and-delete30391
+Node: Saving a Database31343
+Ref: #saving-a-database31491
+Node: Using Biblatex33166
+Ref: #using-biblatex33304
+Node: Setting the BibTeX Dialect33632
+Ref: #setting-the-bibtex-dialect33801
+Node: Alias Types and Fields35841
+Ref: #alias-types-and-fields36002
+Node: The Entries List38188
+Ref: #the-entries-list38322
+Node: Searching42035
+Ref: #searching42180
+Node: Simple Searches42222
+Ref: #simple-searches42338
+Node: Filters45386
+Ref: #filters45486
+Node: Simple Selection46561
+Ref: #simple-selection46690
+Node: Complex Filters48384
+Ref: #complex-filters48546
+Node: Storing and Saving Filters52588
+Ref: #storing-and-saving-filters52771
+Node: Special Filters55650
+Ref: #special-filters55831
+Node: An Example Listing Recent Additions57211
+Ref: #an-example-listing-recent-additions57440
+Node: Properties of Filtered Databases59819
+Ref: #properties-of-filtered-databases60016
+Node: Accessing BibTeX Databases outside Ebib61674
+Ref: #accessing-bibtex-databases-outside-ebib61880
+Node: Key Bindings66801
+Ref: #key-bindings66957
+Node: Defining Citation Commands67721
+Ref: #defining-citation-commands67954
+Node: Associating a Database with a LaTeX File73870
+Ref: #associating-a-database-with-a-latex-file74110
+Node: Cross-referencing77053
+Ref: #cross-referencing77223
+Node: Marking Entries80536
+Ref: #marking-entries80684
+Node: Printing the Database81667
+Ref: #printing-the-database81827
+Node: Calling a Browser85634
+Ref: #calling-a-browser85784
+Node: Viewing Files88416
+Ref: #viewing-files88548
+Node: Editing the file field92342
+Ref: #editing-the-file-field92477
+Node: Notes files93836
+Ref: #notes-files93970
+Node: Customising the notes template98116
+Ref: #customising-the-notes-template98265
+Node: Managing a reading list101311
+Ref: #managing-a-reading-list101473
+Node: Window Management104568
+Ref: #window-management104727
+Node: Creating Entry Stubs107903
+Ref: #creating-entry-stubs108065
+Node: @Preamble Definition109066
+Ref: #preamble-definition109230
+Node: @String Definitions111216
+Ref: #string-definitions111367
+Node: @Comments114883
+Ref: #comments115011
+Node: Managing Keywords115376
+Ref: #managing-keywords115521
+Node: Sorting the bib File121430
+Ref: #sorting-the-.bib-file121603
+Node: Merging and Importing124742
+Ref: #merging-and-importing124907
+Node: Exporting Entries126683
+Ref: #exporting-entries126845
+Node: Multiple Identical Fields128361
+Ref: #multiple-identical-fields128540
+Node: Multiline Edit Buffers130449
+Ref: #multiline-edit-buffers130621
+Node: The Options Menu134523
+Ref: #the-options-menu134671
+Node: Customisation135292
+Ref: #customisation135403
+Node: Modifying Key Bindings136011
+Ref: #modifying-key-bindings136138

End Tag Table
diff --git a/manual/ebib.text b/manual/ebib.text
index dd907e2..61b8005 100644
--- a/manual/ebib.text
+++ b/manual/ebib.text
@@ -3,78 +3,48 @@
<article>
-Ebib is a program with which you can manage BibTeX and BibLateX database files without having to edit the raw `.bib` files. It runs in GNU/Emacs, version 24.3 or higher. (Users of GNU/Emacs 23.1 and up can install Ebib 1.x, which is available in the pasture branch on Github or as a zip or tar archive on Github's releases page.)
+Ebib is a program with which you can manage BibTeX and BibLateX database files without having to edit the raw `.bib` files. It runs in GNU/Emacs, version 25.3 or higher.
It should be noted that Ebib is *not* a minor or major mode for editing BibTeX files. It is a program in itself, which just happens to make use of Emacs as a working environment, in the same way that for example Gnus is.
# News #
-## Version 2.12, August 2018 ##
-
-- Add an option to specify the default sort field and direction. It is no longer necessary to set the desired sort field as the first column in the index buffer, but Ebib still defaults to this if the default sort field and direction are not set explicitly.
-
-## Version 2.11.12, July 2018##
-
-- Use BibLaTeX's `Date` field, if present, for displaying the year.
-- Check for changed files on disk when saving all databases, not just when saving the current database.
-- Improve handling of multiple databases: `crossref` entries can now occur in other open databases as well, and searches with `/` can be continued in other databases.
-- Autogenerating keys is now on by default.
-
-## Version 2.11, January 2017 ##
-
-- Update for `parsebib` v. 2.3.
+## Version 2.15, January 2019 ##
-## Version 2.10, January 2017 ##
+- Multiline field values can now be displayed in the entry buffer.
+- Do not warn about aliased entry types when loading BibLaTeX files.
+- The abstract field is now treated as a multiline field by default, similar to the annote/annotation field.
+- Bug fix: `ebib-show-annotation` (bound to `A`) shows the contents of the annote field in BibTeX databases, not the annotation field (which is BibLaTeX-specific).
-- Improved index column display.
+## Version 2.14, December 2018 ##
-## Version 2.9, January 2017 ##
+- Change the user interface of the export functions. Calling one of the export functions now exports to another database. The user is asked to specify the database, enabling completion on the database names. To export to a file, the export functions have to be called with a prefix argument.
+- Bug fix: Handle overwriting the local BibTeX dialect correctly.
+- Bug fix: Add braces to the crossref field.
-- Allow `%s` in the program strings in `ebib-file-associations`, making it possible to pass command line arguments to the program being called.
+## Version 2.13, November 2018 ##
-## 19 December 2016 ##
+- Use a separate index buffer for each open `.bib` file. Filling the index buffer can be slow for large `.bib` files, because of the need to calculate the tabulated columns.
-- Remove support for a separate rc file for Ebib. User configuration should be moved to Emacs' `init.el` file. To keep Ebib customisation in a separate file, simply load it from `init.el`.
-- The macro `ebib-key` has also been removed. Simply use `define-key` or any other key binding mechanism to define keys for Ebib. See the section [Modifying Key Bindings](#modifying-key-bindings) for details.
+## Version 2.12.3, November 2018 ##
-## 7 December 2016 ##
+- Bug fix: when searching the database, only search visible entries.
-- Upgrade Emacs dependency to 24.4.
+## Version 2.12.2, November 2018 ##
-## 5 December 2016 ##
+- Bug fix: when editing the `crossref` field, offer keys from all databases as completion targets, not just the current one.
-- New library `org-ebib`. This defines a new Org link type `ebib:`, which uses the command `org-ebib-open` to open Ebib. The previous commands to do this, `ebib-show-entry` and `ebib-open-org-link` have been removed. `org-ebib` also allows the creation of Org links to Ebib entries with `org-store-link`.
-- New citation insertion command `ebib-insert-citation`. This replaces `ebib-insert-bibtex-key`, so please update your key bindings. The new command uses `ivy` for completion if this package is available, so that it is possible to select an entry by typing parts of its author and/or title.
-
-
-## 7 November 2016 ##
-
-- New tabulated list interface in index buffer. This interface is not based on Emacs' built-in `tabulated-list-mode`, hence sorting cannot be done by clicking on the column headers. Sorting can be done with `<`, `>` (sort ascending and sort descending, respectively, which ask for the column to sort) and `=`, to reset to default sort (which is on the entry key).
-- The user option `ebib-index-display-fields` is replaced with `ebib-index-columns`, which has a different format: each element in `ebib-index-columns` describes a column in the tabulated view and consists of a list containing the field name, the column's width and a boolean indicating whether sorting on this column is possible.
-
-
-## Version 2.8, 26 October 2016 ##
-
-- Changed key bindings: `j` and `k` no longer move up/down in the index, entry and strings buffers; use `p` and `n` instead. Furthermore, `i` now executes `ebib-push-bibtex-key` (used to be `p`), and `I` (capital i) executes `ebib-browse-doi` (used to be `i`).
-- In the index buffer, `ebib-search-next` (which used to be bound to `n`) is no longer bound. Instead, `ebib-search` (still bound to `/`) activates a transient map which binds the keys `/` and `RET` to `ebib-search-next`. Any other key disables the transient keymap and is executed normally.
-- In the index buffer, `C-u /` repeats the previous search. (This fixes a small bug that has so far gone unnoticed: moving to the top of the databas and calling `ebib-search-next`, as previously suggested in the manual to get around the fact that `ebib-search-next` does not wrap, would not search the first entry.)
-- In the entry buffer, `x` is replaced by `k` (`ebib-kill-field-contents`).
-- New functions: `ebib-kill-entry` and `ebib-yank-entry` for killing and yanking BibTeX entries. `ebib-kill-entry` deletes the current entry from the database and puts it in the kill ring. `ebib-yank-entry` adds an entry from the kill ring to the current database.
-
-
-## Version 2.7, 22 September 2016 ##
+## Version 2.12, August 2018 ##
-- Reading list management: add and remove BibTeX entries to an Org reading list.
-- Remove options `ebib-notes-identifier-function` and `ebib-notes-title-function`.
-- Add option `ebib-notes-template-specifiers`: allow customisation of the format specs used in `ebib-notes-template`. (This option replaces `ebib-notes-identifier-function` and `ebib-notes-title-function`).
+- Add an option to specify the default sort field and direction. It is no longer necessary to set the desired sort field as the first column in the index buffer, but Ebib still defaults to this if the default sort field and direction are not set explicitly.
-## Version 2.6.3, 31 August 2016 ##
+## Version 2.11.12, July 2018##
-- Allow storing notes in a single file rather than using one file per note.
-- Correct handling of DOIs.
-- Add option `ebib-truncate-file-names`: if set (the default), file names added to the `file` field are truncated relative to `ebib-file-search-dirs`.
-- Add option `ebib-file-name-mod-function`: modify file paths before storing them in the `file` field.
+- Use BibLaTeX's `Date` field, if present, for displaying the year.
+- Check for changed files on disk when saving all databases, not just when saving the current database.
+- Improve handling of multiple databases: `crossref` entries can now occur in other open databases as well, and searches with `/` can be continued in other databases.
+- Autogenerating keys is now on by default.
# Installation #
@@ -89,7 +59,7 @@ Users of Debian 9 or later and Ubuntu 16.10 or later can also use their distro's
## Manual installation ##
-It's also possible to install Ebib manually by downloading the source, compiling it and telling Emacs where to find it. 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 Ebib's dependencies, the [dash](https://github.com/magnars/dash.el) and [parsebib](https://github.com/joostkremers/parsebib) libraries.
+It's also possible to install Ebib manually. If you prefer this method, then you probably know what you're doing so detailed instructions are omitted here. Just be sure to also install the [parsebib](https://github.com/joostkremers/parsebib) package, which Ebib depends on.
## Starting Ebib ##
@@ -107,30 +77,6 @@ You can also call Ebib from an Eshell command line. This in itself is entirely u
starts Ebib and loads the file `references.bib`.
-## Upgrading from Ebib 1.x ##
-
-If you upgrade from Ebib 1.x to the current version 2, there are a few things you need to be aware of. First, Ebib 2 does not support Emacs versions below 24.3. If you're on an older version of Emacs, either upgrade Emacs, or do not upgrade Ebib. Ebib 1.x will continue to be available in the `pasture` branch on Github or as a package on the Github releases page, so if for some reason you do not want to upgrade, you can continue to use this branch. Ebib 1.x will continue to be supported with bug fixes and possibly the occasional (small) feature addition, though no major changes will take place.
-
-If you do upgrade, it is important to note that a few customisation options have changed. If you never made any customisations to Ebib, the upgrade should not pose any problems. If you have, however, read on.
-
-The most important change is that the variable `ebib-entry-types` (option "Entry Types") has been removed. Ebib now uses the entry type definitions of the built-in `bibtex-mode`, which means that if you wish to customise the entry types, you should customise `bibtex-BibTeX-entry-alist` or `bibtex-biblatex-entry-alist`.
-
-Secondly, a few user options have been renamed because their types have changed. (Mainly from `symbol` to `string`). The name change means that existing customisations are lost, but it also prevents Ebib from throwing cryptic errors and refusing to run. If you customised any of the following options, you should redo them after upgrading Ebib (and preferably remove the old ones from your init file):
-
-- `ebib-default-entry`: renamed to `ebib-default-entry-type`.
-- `ebib-additional-fields`: renamed to `ebib-extra-fields`.
-- `ebib-standard-url-field`: renamed to `ebib-url-field`.
-- `ebib-standard-file-field`: renamed to `ebib-file-field`.
-- `ebib-standard-doi-field`: renamed to `ebib-doi-field`.
-- `ebib-biblatex-inheritance`: renamed to `ebib-biblatex-inheritances` (note the `s`).
-
-Note that even if you customised `ebib-biblatex-inheritance`, there is most likely no need to customise its replacement `ebib-biblatex-inheritances`, because the latter is set up with the default inheritance rules that Biblatex defines.
-
-Another thing to note is that four user options have a new default value. First, the default location of the rc file has moved to `~/.emacs.d/ebibrc`, in line with the recommendation to keep all Emacs-related files in `~/.emacs.d`. If you kept an `.ebibrc` file in your home directory, move it to `~/.emacs.d`. Second, a `\documentclass` definition has been added to the user options "Latex Preamble" (`ebib-latex-preamble`) and "Print Preamble" (`ebib-print-preamble`). If you customised one of these, you should add a document class specification, otherwise the LaTeX file won't compile. Third, the option `ebib-save-xrefs-first` now defaults to `t`.
-
-Lastly, if you use Biblatex, make sure to read the section on using Ebib with Biblatex files.
-
-
# Getting Started #
A BibTeX database is somewhat of a free-form database. A BibTeX entry consists of a set of field-value pairs. Furthermore, each entry is known by a unique key. The way that Ebib navigates this database is by having two windows, one that contains a list of all the entry keys in the database, and one that contains the fields and values of the currently highlighted entry.
@@ -148,11 +94,11 @@ You can quit Ebib by typing `q`. You will be asked for confirmation, and you wil
## Opening a `.bib` File ##
-Loading a `.bib` file into Ebib is done with the command `o`. Ebib reads the file that you specify, and reports how many entries it found, how many `@string` definitions it found, and whether a `@preamble` was found. Note that when Ebib reads a `.bib` file, it only reads entry types (e.g. `book, article, phdthesis` etc.) that it knows about. Therefore, you should make sure that all the entry types and fields that your databases use are defined. Ebib uses the entry type definitions of `bibtex.el`, which is fairly complete, but if you use non-standard entry types, you may need to customise `bibtex-bibtex-entry-alist` or `bibtex-biblatex-entry-alist`, depending on which of the two you use.
+Loading a `.bib` file into Ebib is done with the command `o`. Ebib reads the file that you specify, and reports how many entries it found, how many `@String` definitions it found, and whether a `@Preamble` was found.
Every time Ebib reads a `.bib` file, it produces a few log messages. These are written into a special buffer `*Ebib-log*`. If Ebib encounters entry types in the `.bib` file that it doesn't know, a warning will be logged. If Ebib finds something that it cannot parse, it will log an error. If warnings and/or errors occurred during loading, Ebib will issue a message when it finishes loading the `.bib` and direct you to the log buffer.
-If Ebib finds entry types in a `.bib` file that are not defined, those entries will still be loaded, but their entry type is displayed using Emacs' `error` face. The most likely case in which this will happen is when you load a Biblatex file without letting Ebib know the file is Biblatex-specific. By default, Ebib assumes that a `.bib` file it loads is a BibTeX file. If you intend to use Biblatex files, make sure to read the section on Biblatex ([Using Biblatex](#using-biblatex)).
+In order to parse `.bib` files, Ebib uses the entry type definitions of `bibtex.el`, which is fairly complete, but if you use non-standard entry types, you may need to customise `bibtex-bibtex-entry-alist` or `bibtex-biblatex-entry-alist`, depending on which of the two you use. If Ebib finds entry types in a `.bib` file that are not defined, those entries will still be loaded, but their entry type is displayed using Emacs' `error` face. The most likely case in which this may happen is when you load a Biblatex file without letting Ebib know the file is Biblatex-specific. By default, Ebib assumes that a `.bib` file it loads is a BibTeX file. If you intend to use Biblatex files, make sure to read the section on Biblatex ([Using Biblatex](#using-biblatex)).
## Preloading `.bib` Files ##
@@ -219,15 +165,17 @@ If you're done editing the fields of the entry, type `q` to move focus back to t
## Editing Multiline Values ##
-Apart from the `type`, `keywords`, `file` and `crossref` fields, there is another field that Ebib handles in a special way when you edit its value. This is the `annote` field (`annotation` in Biblatex). Most field values normally consist of a single line of text. However, because the `annote` field is meant for creating annotated bibliographies, it would not be very useful if you could only write one line of text in this field. Therefore, when you edit the `annote` field, Ebib puts you in a so-called *multiline edit buffer*. This is essentially a text mode buffer that allows you to enter as much text as you like. To store the text and leave the multiline edit buffer, type `C-c | q`.
+Apart from the `type`, `keywords`, `file` and `crossref` fields, there are two other fields that Ebib handles in a special way when you edit its value. These are the `annote` field (or `annotation` in Biblatex), and the `abstract` field. Most field values normally consist of a single line of text. However, because the `annote`/`annotation` and `abstract` fields are meant for creating annotated bibliographies, it would not be very useful if you could only write one line of text in them. Therefore, when you edit one of these fields, Ebib puts you in a so-called *multiline edit buffer*. This is essentially a text mode buffer that allows you to enter as much text as you like. To store the text and leave the multiline edit buffer, type `C-c | q`.
If you want to leave the multiline edit buffer without saving the text you have just typed, type `C-c | c`. This command cancels the edit and leaves the multiline edit buffer. The text that is stored in the field you were editing is not altered.
-Multiline values are not restricted to the `annote` field. Any field (except the `type` and `crossref` fields) can in fact hold a multiline value. To give a field a multiline value, use `m` instead of `e`. You will again be put in a multiline edit buffer, where you can edit the value. Note that you can use `m` even if a field already has a single line value. Ebib will just make that the first line in the multiline edit buffer.
+Multiline values are not restricted to the `annote`/`annotation` and `abstract` fields. Any field (except the `type` and `crossref` fields) can in fact hold a multiline value. To give a field a multiline value, use `m` instead of `e`. You will again be put in a multiline edit buffer, where you can edit the value. Note that you can use `m` even if a field already has a single line value. Ebib will just make that the first line in the multiline edit buffer.
-When a field has a multiline value, only the first line is shown in the entry buffer, for space reasons. To indicate that the value is multiline, a plus sign `+` is placed in front of the value. If you want to see the whole contents of a multiline field, you can use `v`: this will display the contents of the current field in a `*Help*` buffer. This buffer can be dismissed again with `q`. This is quicker than entering the multiline edit buffer just to read the contents of a field and it has the advantage that the other fields stay visible.
+When a field has a multiline value, at most ten lines are shown in the entry buffer. If the text is longer, an ellipsis indicator `[...]` is added after the last line that is displayed. If you want to see the whole contents of a multiline field, you can use `v`: this will display the contents of the current field in a `*Help*` buffer. This buffer can be dismissed again with `q`. This is quicker than entering the multiline edit buffer just to read the contents of a field and it has the advantage that the other fields stay visible.
-By the way, the `e` key is smart about the way an entry must be edited. If you press `e` on a field that already has a multiline value, regardless of the fact whether it is the `annote` field or not, Ebib puts you in a multiline edit buffer. Therefore, you need `m` only if you want to give a field a multiline value when it doesn't have one yet.
+It's possible to customise the way a multiline value is displayed in the entry buffer. See the options `ebib-multiline-display-function` and `ebib-multiline-display-max-lines` for details.
+
+By the way, the `e` key is smart about the way an entry must be edited. If you press `e` on a field that already has a multiline value, regardless of the fact whether it is the `annote`/`annotation` or `abstract` field or not, Ebib puts you in a multiline edit buffer. Therefore, you need `m` only if you want to give a field a multiline value when it doesn't have one yet.
For more details on working with multiline edit buffers, see [Multiline Edit Buffers](#multiline-edit-buffers).
@@ -308,7 +256,13 @@ By default, the index buffer displays the list of entries in the database in a t
The fields that are displayed in the index buffer can be customised with the user option `ebib-index-columns`. Each element in this option describes a column and consists of the field to display (which is also the column label), the width of the column and a flag indicating whether the column can be sorted. You can add or remove fields, or reorder the existing ones.
-You can use any BibTeX / BibLaTeX field to define a column in the index buffer. In addition, there are two column labels with a special meaning: `"Entry Key"`, which displays the entry key, and `"Author/Editor"`, which displays the contents of the author field if it is not empty, and the contents of the editor field otherwise.
+You can use any BibTeX / BibLaTeX field to define a column in the index buffer. In addition, there are two column labels that do not correspond directly to a field name. These are `"Entry Key"`, which displays the entry key, `"Author/Editor"`, which displays the contents of the author field if it is not empty, and the contents of the editor field otherwise. Furthermore, the column label `"Year"` does not display the contents of the year field unconditionally. Rather, it first checks the contents of the date field, which is BibLaTeX's replacement of the year field, and extracts the first year in it. Only if the date field is empty does it display the year field.
+
+Three other column labels have special behaviour: `"Title"`, `"Doi"`, and `"Url"`. These do display information from the fields they correspond with, but in a special way: `"Title"` tries to make the title look nice by removing braces and LaTeX commands (including their optional arguments) and by displaying the arguments of `\emph`, `\textit`, `\textbf` and `\textsc` in italic, bold or caps. `"Doi"` and `"Url"` don't display the contents of these fields, but instead yield a clickable string `"www"`. Clicking on `"www"` takes you to the relevant web page.
+
+The final predefined column label is "Note". This does not, as might be expected, display the contents of the note field. Rather, it checks whether the entry in question has a note associated with it in Ebib's own notes system, discussed in [Notes Files](#notes-files). For those entries that have a note, the `"Note"` column will display a (clickable) `"N"`. Keep in mind, though, that if you keep your notes in a single file, adding this column to the index display can slow down the creation of the index buffer (and thus Ebib's start-up). If you wish to use this column, it is probably best to keep notes in separate files.
+
+You can define new column labels and redefine the existing ones by customising the option `ebib-field-transformation-functions`. Note that `"Title"`, `"Doi"`, `"Url"`, and `"Note"` are actually defined through this option. `"Entry Key"`, `"Author/Editor"`, and `"Year"` are not (they are hard-coded), but they can be overridden by adding an entry for them in `ebib-field-transformation-functions`.
The first column defined in `ebib-index-colums` is the column on which the entries are sorted by default, i.e., when the database is first opened and when you press `=`. You can change the default sort field and the default sort direction (which is ascending, i.e., A-Z and 0-9) by customising the option `ebib-index-default-sort`.
@@ -323,11 +277,13 @@ The contents of the entries can be searched with `/`. This command (`ebib-search
Ebib searches all the fields of each entry. It is not possible with `/` to specify the fields to search. Note that if the search term is found in a field with a multiline value, Ebib will highlight the `+` sign that is displayed in front of the field value. When the search term is found, Ebib gives a message saying so, similarly if the search term was not found.
-A search term may of course appear more than once in the database. To search for the next occurrence, type `/` again (or, alternatively type `RET`). This continues searching for the search term in the rest of the database. Again, the first entry found to contain the search string is displayed. Note that the search does not wrap: if the end of the database is reached, Ebib stops searching and informs you that no further occurrence of the search string was found. If you want to continue searching from the top, type `g` and then continue the search with `/` or `RET`.
+A search term may of course appear more than once in the database. To search for the next occurrence, type `RET`. This continues searching for the search term in the rest of the database. Again, the first entry found to contain the search string is displayed. Note that the search does not wrap: if the end of the database is reached, Ebib stops searching and informs you that no further occurrence of the search string was found. If you want to continue searching from the top, type `g` and then continue the search with `RET`.
+
+Note that once you've started a search with `/`, Ebib activates a transient key map called `ebib-search-map`. It is this map that holds the binding for `RET` to continue searching after the current entry and of the key `g` to jump to the top of the database. There are also bindings for the left and right cursor keys, which take you to the previous and next database, so you can continue searching there.
-Note that once you've started a search with `/`, Ebib activates a transient key map called `ebib-search-map`. It is this map that holds the bindings of `/` and `RET` to continue searching after the current entry and of the key `g` to jump to the top of the database. You can, of course, bind or rebind keys in this map.
+Exiting a search (i.e., getting rid of the transient key map) is done by pressing any key other than `RET`, `g` or the left/right cursor keys. The search is ended and the command associated with this key is executed normally. If you want to repeat a previous search, you can pass a prefix argument to `/`. So typing `C-u /` starts searching for the previous search string again.
-Exiting a search (i.e., getting rid of the transient key map) is done by pressing any key other than `/`, `RET` or `g`. The search is ended and the command associated with this key is executed normally. If you want to repeat a previous search, you can pass a prefix argument to `/`. So typing `C-u /` (or any other prefix argument) starts searching for the previous search string again.
+Note that if you start a search in a filtered database (i.e., a database in which not all entries are visible; see the next section), only the visible entries are searched. If the search string is present in the database but not in one of the visible entries, Ebib will respond with a "search string not found" message.
## Filters ##
@@ -386,11 +342,10 @@ Note that cancelling a filter with `F c` does not delete it from the list of sto
### Special Filters ###
-Filters are essentially Lisp expressions that consist of the functions `and`, `or`, and `not`, together with a special macro `contains`. However, filters are not limited to these forms. They can essentially contain any Lisp expression. It is not possible to create such special filters interactively, but it is possible to write such filters and put them in a filter file, or to write a function that creates a special filter.
-
-A filter is a Lisp expression that should return either `t` or `nil`, indicating whether the entry being tested matches the filter or not. The contents of the entry is available in a variable `entry`. This variable is given a value by the function that runs the filter, but it is not passed as an argument. Rather, it is a local dynamic variable, which means that the file that defines the filter function should have the variable `lexical-binding` set to `nil`.
+Filters are essentially Lisp expressions that consist of the functions `and`, `or`, and `not`, together with a special macro `contains`. However, filters are not limited to these forms. They can essentially contain any Lisp expression. It is not possible to create such special filters interactively, but it is possible to write such filters and put them in a filter file, or to write a function that creates such a special filter.
-The value of `entry` is an alist of fields and their values. These include the fields `=key=` and `=type=` for the entry key and type:
+A filter is a Lisp expression that should return either `t` or `nil`, indicating whether the entry being tested matches the filter or not. The contents of the entry is available in a variable `ebib-entry`. This variable is given a value by the function that runs the filter, but it is not passed as an argument. Rather, it is a dynamic variable, which means that the file that defines the filter function should declare the variable with `(defvar ebib-entry)`.
+When the filter is run, the value of `ebib-entry` is an alist of fields and their values. These include the fields `=key=` and `=type=` for the entry key and type:
```
(("author" . "{Noam Chomsky}")
@@ -412,21 +367,23 @@ One special filter is included with Ebib. It filters recent additions to the dat
(defun ebib-list-recent (days)
"List entries created in the last DAYS days."
(interactive "nNumber of days: ")
- ;; save the database's current filter, if there is one.
+ ;; Save the database's current filter, if there is one.
(let ((filter (ebib-db-get-filter ebib--cur-db)))
- (when filter (setq ebib--filters-last-filter filter)))
+ (when filter (setq ebib--filters-last-filter filter)))
(let*
- ;; calculate the from-date in Emacs' time format
+ ;; Calculate the from-date in Emacs' time format.
((date (time-subtract (current-time) (days-to-time days)))
- ;; create a Lisp expression that will function as the filter
+ ;; Create a Lisp expression that will function as the filter.
(filter `(ebib--newer-than (quote ,date))))
- ;; install it as the curretn database's filter
+ ;; Install it as the current database's filter.
(ebib-db-set-filter filter ebib--cur-db)
- ;; update the display, so that only filtered entries are visible
- (ebib--redisplay)))
+ ;; Update the current entry key.
+ (ebib-db-set-current-entry-key (ebib--get-key-at-point) ebib--cur-db)
+ ;; Update the display, so that only filtered entries are visible.
+ (ebib--update-buffers)))
```
-First, this function saves the current filter if there is one. It then creates a date in Emacs’ internal time format by subtracting the number of days provided by the user from the current date and uses this date to create a Lisp expression which is then installed as the filter for the current database. A call to `ebib--redisplay` then updates the display, taking the filter into account.
+First, this function saves the current filter if there is one. It then calculates a date in Emacs’ internal time format by subtracting the number of days provided by the user from the current date and creates a Lisp expression that tests whether an entry's timestamp is earlier or later than this date. This expression is then installed as the filter for the current database. A call to `ebib--update-buffers` then updates the display, taking the filter into account.
The function `ebib--newer-than` is defined as follows:
@@ -438,13 +395,13 @@ be a list of the format returned by `current-time' and is
compared to the timestamp of the entry being tested. If the
entry has no timestamp, or a timestamp that cannot be converted
into a date representation, return nil."
- (let ((timestamp (cdr (assoc-string "timestamp" entry))))
+ (let ((timestamp (cdr (assoc-string "timestamp" ebib-entry))))
(when (and timestamp
(setq timestamp (ignore-errors (date-to-time timestamp))))
(time-less-p date timestamp))))
```
-This function obtains the time stamp of the entry being tested from the variable `entry` and then tries to convert it to Emacs’ time format. If successful, it compares this time to the date passed as an argument and returns `t` if the latter precedes the former.
+This function obtains the time stamp of the entry being tested from the variable `ebib-entry` and then tries to convert it to Emacs’ time format. If successful, it compares this time to the date passed as an argument and returns `t` if the latter precedes the former.
### Properties of Filtered Databases ###
@@ -453,7 +410,7 @@ When a filter is active, there are a few things that are not possible or functio
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 `M`, then cancel the filter and perform an action on them.
-If a database has an active filter, the save command is disabled, because it would not be clear whether you want to save the entire database or just the filtered entries. If you want to save only the filtered entries to a file, you can use the command `w` (or the menu option "Save Database As"). This also saves the `@string`, `@preamble` and `@comments`, as well as any file-local variables, so you will have a self-contained `.bib` file with only the filtered entries. In order to save the entire database, you need to cancel the filter. After saving, you can reapply the filter with `F L`, of course.
+If a database has an active filter, the save command is disabled, because it would not be clear whether you want to save the entire database or just the filtered entries. If you want to save only the filtered entries to a file, you can use the command `w` (or the menu option "Save Database As"). This also saves the `@String`, `@Preamble` and `@comments`, as well as any file-local variables, so you will have a self-contained `.bib` file with only the filtered entries. In order to save the entire database, you need to cancel the filter. After saving, you can reapply the filter with `F L`, of course.
One final note: of all the filter-related commands, `~`, `F c`, `F r`, `F s` and `F v` are only available when a filter is active. The other commands operate on the stored filters and can be used when no filter is active.
@@ -798,44 +755,44 @@ Note that the entry keys for the stubs are temporary keys. They will be replaced
# @Preamble Definition #
-Apart from database entries, BibTeX allows three more types of elements to appear in a `.bib` file. These are `@comment`, `@preamble` and `@string` definitions. Ebib provides facilities to handle these, which are discussed here and in the following sections.
+Apart from database entries, BibTeX allows three more types of elements to appear in a `.bib` file. These are `@comment`, `@Preamble` and `@String` definitions. Ebib provides facilities to handle these, which are discussed here and in the following sections.
-Ebib allows you to add one `@preamble` definition to the database. In principle, BibTeX allows more than one such definition, but really one suffices, because you can use the concatenation character `#` to include multiple TeX or LaTeX commands. So, rather than having two `@preamble` definitions such as:
+Ebib allows you to add one `@Preamble` definition to the database. In principle, BibTeX allows more than one such definition, but really one suffices, because you can use the concatenation character `#` to include multiple TeX or LaTeX commands. So, rather than having two `@Preamble` definitions such as:
- @preamble{ "\newcommand{\noopsort}[1]{} " }
- @preamble{ "\newcommand{\singleletter}[1]{#1} " }
+ @Preamble{ "\newcommand{\noopsort}[1]{} " }
+ @Preamble{ "\newcommand{\singleletter}[1]{#1} " }
you can write this in your `.bib` file:
- @preamble{ "\newcommand{\noopsort}[1]{} "
+ @Preamble{ "\newcommand{\noopsort}[1]{} "
# "\newcommand{\singleletter}[1]{#1} " }
-Creating or editing a `@preamble` definition in Ebib is done by hitting (uppercase) `P` in the index buffer. Ebib uses the multiline edit buffer for editing the text of the `@preamble` definition, which means that `C-c | q` stores the `@preamble` text and returns focus to the index buffer, while `C-c | c` returns focus to the index buffer while abandoning any changes you may have made. (For details on using multiline edit buffers, see [Multiline Edit Buffers](#multiline-edit-buffers).)
+Creating or editing a `@Preamble` definition in Ebib is done by hitting (uppercase) `P` in the index buffer. Ebib uses the multiline edit buffer for editing the text of the `@Preamble` definition, which means that `C-c | q` stores the `@Preamble` text and returns focus to the index buffer, while `C-c | c` returns focus to the index buffer while abandoning any changes you may have made. (For details on using multiline edit buffers, see [Multiline Edit Buffers](#multiline-edit-buffers).)
-In order to create a `@preamble` as shown above in Ebib, you only have to type the text between the braces. Ebib takes care of including the braces of the `@preamble` command, but otherwise it saves the text exactly as you enter it. So in order to get the preamble above, you'd have to type the following in Ebib:
+In order to create a `@Preamble` as shown above in Ebib, you only have to type the text between the braces. Ebib takes care of including the braces of the `@Preamble` command, but otherwise it saves the text exactly as you enter it. So in order to get the preamble above, you'd have to type the following in Ebib:
"\newcommand{\noopsort}[1]{} " # "\newcommand{\singleletter}[1]{#1} "
-Note that when Ebib loads a `.bib` file that contains more than one `@preamble` definition, it concatenates all the strings in them in the manner just described and saves them in one `@preamble` definition.
+Note that when Ebib loads a `.bib` file that contains more than one `@Preamble` definition, it concatenates all the strings in them in the manner just described and saves them in one `@Preamble` definition.
# @String Definitions #
-If you press (uppercase) `S` in the index buffer, Ebib hides the entry buffer in the lower window and replaces it with the *strings buffer*. In this buffer, you can add, delete and edit `@string` definitions.
+If you press (uppercase) `S` in the index buffer, Ebib hides the entry buffer in the lower window and replaces it with the *strings buffer*. In this buffer, you can add, delete and edit `@String` definitions.
-Adding a `@string` definition is done with the command `a`. This will first ask you for an abbreviation and then for the value to be associated with that abbreviation. Once you've entered these, Ebib will sort the new abbreviation into the buffer.
+Adding a `@String` definition is done with the command `a`. This will first ask you for an abbreviation and then for the value to be associated with that abbreviation. Once you've entered these, Ebib will sort the new abbreviation into the buffer.
-Moving between the `@string` definitions can be done in the usual way: the cursor keys `up` and `down`, `p` and `n` or `C-p` and `C-n` move up and down. `Space` and `PgDn` move ten strings down, while `b` and `PgUp` move in the other direction. The keys `g`, `G`, `Home` and `End` also function as expected.
+Moving between the `@String` definitions can be done in the usual way: the cursor keys `up` and `down`, `p` and `n` or `C-p` and `C-n` move up and down. `Space` and `PgDn` move ten strings down, while `b` and `PgUp` move in the other direction. The keys `g`, `G`, `Home` and `End` also function as expected.
-To delete a `@string` definition, use `d`. To edit the value of a definition, use `e`. There is also a command `c`, which copies the value of the current `@string` definition to the kill ring. Unlike in the entry buffer, there are no corresponing commands `y` and `x`. (In fact, `x` does exist, but has another function.) Yanking from the kill ring can be done with `C-y/M-y` in the minibuffer when you edit a `@string`'s value. Cutting a `@string`'s value is pointless, because a `@string` definition must have a value.
+To delete a `@String` definition, use `d`. To edit the value of a definition, use `e`. There is also a command `c`, which copies the value of the current `@String` definition to the kill ring. Unlike in the entry buffer, there are no corresponing commands `y` and `x`. (In fact, `x` does exist, but has another function.) Yanking from the kill ring can be done with `C-y/M-y` in the minibuffer when you edit a `@String`'s value. Cutting a `@String`'s value is pointless, because a `@String` definition must have a value.
-Having defined `@string` definitions, there must of course be a way to use them. Just giving a field a string abbreviation as value will not do, because Ebib puts braces around the value that you enter when it writes the `.bib` file, so that BibTeX will not recognise the abbreviation, and will not expand it. BibTeX will only recognise an abbreviation if it appears in the `.bib` file outside of any braces.
+Having defined `@String` definitions, there must of course be a way to use them. Just giving a field a string abbreviation as value will not do, because Ebib puts braces around the value that you enter when it writes the `.bib` file, so that BibTeX will not recognise the abbreviation, and will not expand it. BibTeX will only recognise an abbreviation if it appears in the `.bib` file outside of any braces.
To accomplish this, you must mark a field's value as special. A special field is a field whose value is not surrounded by braces when the database is saved, so that BibTeX recognises it as an abbreviation. To mark a field special, press `r`. An asterisk will appear before the field, indicating that has no braces. Pressing `r` again will change the field back to normal. If you press `r` on a field that does not have a value yet, Ebib will ask you for one.
Note that this also makes it possible to enter field values that are composed of concatenations of strings and abbreviations. The BibTeX documentation for example explains that if you have defined:
- @string{WGA = "World Gnus Almanac"}
+ @String{WGA = "World Gnus Almanac"}
you can create a BibTeX field like this:
@@ -847,12 +804,12 @@ which will produce "1966 World Gnus Almanac". Or you can do:
which will produce someting like "1 January", assuming your bibliography style has defined the abbreviation `jan`. All this is possible with Ebib, simply by entering the exact text including quotes or braces around the strings, and marking the relevant field as special.
-An easy way to enter a `@string` abbreviation as a field value is to use the key `s` instead of `e`. If you type `s`, Ebib asks you for a `@string` abbreviation to put in the current field, and automatically marks the field as special. With this command, Ebib only accepts `@string` definitions that are in the database, so that by using `s` you can make sure you don't make any typos. Note that you can use TAB completion to complete a partial string.
+An easy way to enter a `@String` abbreviation as a field value is to use the key `s` instead of `e`. If you type `s`, Ebib asks you for a `@String` abbreviation to put in the current field, and automatically marks the field as special. With this command, Ebib only accepts `@String` definitions that are in the database, so that by using `s` you can make sure you don't make any typos. Note that you can use TAB completion to complete a partial string.
# @Comments #
-If Ebib finds a `@comment` in a `.bib` file, it will read it and store it in the database. When the database is saved, all the `@comment`s will be saved with it, at the top of the file (right after the `@preamble`.) There is no way to edit comments, nor can you specify where in the `.bib` file a comment is placed, but they won't be lost.
+If Ebib finds a `@comment` in a `.bib` file, it will read it and store it in the database. When the database is saved, all the `@comment`s will be saved with it, at the top of the file (right after the `@Preamble`.) There is no way to edit comments, nor can you specify where in the `.bib` file a comment is placed, but they won't be lost.
# Managing Keywords #
@@ -914,13 +871,11 @@ If a BibTeX entry in the buffer lack an entry key (which sometimes happens with
# Exporting Entries #
-Sometimes it can be useful to copy entries from one database to another, or to create a new `.bib` file with several entries from an existing database. For this purpose, Ebib provides exporting facilities. To export an entry to a `.bib` file, use the command `x`. This command operates on a single entry or on all marked entries.
+Sometimes it can be useful to copy entries from one database to another, or to create a new `.bib` file with several entries from an existing database. For this purpose, Ebib provides exporting facilities. To export an entry to another database, use the command `x`. This command operates on a single entry or on all marked entries. Ebib will ask you for the database to export the entry or entries to. TAB-completion is available, based on the file names of the databases.
-When you export one or more entries, Ebib will ask you for a filename to export them to. If you have already exported an entry before, Ebib will present the filename you used as default, but you can of course change it. For obvious reasons, Ebib appends the entry to the file that you enter if it already exists, it does not overwrite the file. If this is not what you want, delete the file first, as Ebib provides no way to do this.
+You can also export entries to a file. To do this, call the command `x` with a prefix argument: `C-u x`. You will be prompted for the file name 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 it's possible to end up with duplicate entries in this way.
-If you have more than one database open in Ebib, it is also possible to copy entries from one database to another. To do this, use the `x` command with a numeric prefix argument. E.g., if the database you want to export an entry to is the second database, type `M-2 x` to export the current entry to it. The number of the database is given in the modeline of the index buffer. If the database you're copying an entry to already contains an entry with the same entry key, Ebib won't copy the entry, and issues an appropriate warning message.
-
-Apart from entries, it is also possible to export the `@preamble` and `@string` definitions. The `@preamble` definition is exported with the command `X` in the index buffer. `@string` definitions can be exported in the strings buffer: `x` in this buffer exports the current string, while `X` exports all `@string` definitions in one go. All these commands function in the same way: when used without a prefix argument, they ask for a filename, and then append the relevent data to that file. With a numeric prefix argument, they copy the relevant data to the corresponding open database.
+Apart from entries, it is also possible to export the `@Preamble` and `@String` definitions. The `@Preamble` definition is exported with the command `X` in the index buffer. `@String` definitions can be exported in the strings buffer: `x` in this buffer exports the current string, while `X` exports all `@String` definitions in one go. All these commands function in the same way: when used without a prefix argument, they ask for an open database to export the entry to. With a prefix argument, they ask for a filename, and then append the relevant data to that file.
# Multiple Identical Fields #
@@ -952,33 +907,32 @@ If you load this entry into Ebib with the option "Allow Identical Fields" set, y
# Multiline Edit Buffers #
-As mentioned several times before, Ebib has a special multiline edit buffer, which is used to edit field values that contain newlines (so-called *multiline fields*), and also to edit the contents of the `@preamble` command. This section discusses the details of this buffer.
+As mentioned several times before, field values that contain newlines (so-called *multiline fields*) and the `@Preamble` are edited in a so-called *multiline edit buffer*. This section discusses the details of this buffer.
-Ebib enters multiline edit mode in one of three cases: when you edit the `@preamble` definition, when you hit `m` in the entry buffer to edit the current field as multiline, or when you hit `e` on the `annote` field, or on a field whose value already is multiline.
+Ebib enters a multiline edit buffer in one of three cases: when you edit the `@Preamble` definition, when you hit `m` in the entry buffer to edit the current field as multiline, or when you hit `e` on the `annote`/`annotation` or `abstract fields, or on a field whose value already is multiline.
-The mode that is used in the multiline edit buffer is user-configurable. The default value is `text-mode`, but if you prefer to use some other mode, you can specify this through the customisation options. (Personally, I use `markdown-mode` in the multiline edit buffer, so that I can use [`Markdown`](http://daringfireball.net/projects/markdown/) to write annotations, which provides an easy way to create headers, use bold and italic, etc., in plain text.)
+The major mode that is used in multiline edit buffers is user-configurable. The default value is `text-mode`, but if you prefer to use some other mode, you can specify this through the customisation option `ebib-multiline-major-mode`.
Three commands are relevant for interacting with Ebib when you're in the multiline edit buffer, which are bound to key sequences in the minor mode `ebib-multiline-edit-mode`, which is activated automatically in the multiline edit buffer.
-`ebib-quit-multiline-buffer-and-save`, bound to `C-c | q`, leaves the multiline edit buffer and stores the text in the database. If you invoke this command when you've deleted all contents of the buffer (including the final newline!) and you were editing a field value or the `@preamble`, the field value or preamble is deleted. (This is in fact the *only* way to delete the `@preamble` definition. Field values on the other hand can also be deleted by hitting `x` or `d` on them in the entry buffer.) If you were editing a `@string` value, Ebib will just complain, because string definitions cannot be empty.
+`ebib-quit-multiline-buffer-and-save`, bound to `C-c | q`, leaves the multiline edit buffer and stores the text in the database. If you invoke this command when you've deleted all contents of the buffer (including the final newline!) and you were editing a field value or the `@Preamble`, the field value or preamble is deleted. (This is in fact the *only* way to delete the `@Preamble` definition. Field values on the other hand can also be deleted by hitting `k` or `d` on them in the entry buffer.)
`ebib-cancel-multiline-buffer`, bound to `C-c | c`, also leaves the multiline edit buffer, but it does so without storing the text. The original value of the field, string or preamble will be retained. If the text was modified, Ebib will ask for a confirmation before leaving the buffer.
`ebib-save-from-multiline-buffer`, bound to `C-c | s`, can be used in the multiline edit buffer to save the database. This command first stores the text in the database and then saves it. Because Ebib does not do an autosave of the current database, it is advisable to save the database manually every now and then to prevent data loss in case of crashes. It would be annoying to have to leave the multiline edit buffer every time you want to do this, so this command has been provided to allow you to do this from within the buffer.
-Admittedly, the key combinations of the multiline edit buffer are somewhat awkward. The reason for this is that these commands are part of a minor mode, which restricts the available keys to combinations of `C-c` plus a non-alphanumeric character. However, it is possible to change the key commands, if you wish. Ebib itself provides a method to change the second key of these commands, [Modifying Key Bindings](#modifying-key-bindings). You could change the `|` to e.g., `c` or `C-c`, if these do not conflict with any key commands in the major mode used for the multiline edit buffer.
+Note that you do not need to finish a multiline edit before you can return to the database and possibly edit other fields and even entries. Ebib keeps track of which field in which entry of which database a multiline edit buffer belongs to, so you can keep a multiline edit buffer open while doing other work. It is even possible to have several multiline edit buffers open at the same time. Ebib makes sure that when you finish one, its contents is stored in the correct place.
-Even more drastically, you could put something like the following in your `~/.emacs`:
+Admittedly, the key combinations of the multiline edit buffer are somewhat awkward. The reason for this is that these commands are part of a minor mode, which restricts the available keys to combinations of `C-c` plus a non-alphanumeric character. However, it is possible to change the key commands, if you wish. For example, you could put something like the following in your `~/.emacs`:
```Commonlisp
-(eval-after-load 'ebib
- '(progn
- (define-key ebib-multiline-mode-map
- "\C-c\C-c" 'ebib-quit-multiline-buffer-and-save)
- (define-key ebib-multiline-mode-map
- "\C-c\C-q" 'ebib-cancel-multiline-buffer)
- (define-key ebib-multiline-mode-map
- "\C-c\C-s" 'ebib-save-from-multiline-buffer)))
+(with-eval-after-load 'ebib
+ (define-key ebib-multiline-mode-map
+ "\C-c\C-c" 'ebib-quit-multiline-buffer-and-save)
+ (define-key ebib-multiline-mode-map
+ "\C-c\C-q" 'ebib-cancel-multiline-buffer)
+ (define-key ebib-multiline-mode-map
+ "\C-c\C-s" 'ebib-save-from-multiline-buffer)))
```
This sets up `C-c C-c`, `C-c C-q` and `C-c C-s` for use in the multiline edit buffer. Since such key combinations are restricted for use with major modes, however, Ebib cannot set these up automatically, but as an Emacs user, you are free to do as you like, of course.
@@ -995,8 +949,6 @@ The same is true for the printing options that are in the Print menu. When set o
Ebib can be customised through Emacs' standard customisation interface. The relevant customisation group is (obviously) called `ebib`, which has five subgroups: `ebib-faces`, `ebib-filters`, `ebib-notes`, and `ebib-keywords`, whose functions should be obvious, and `ebib-windows`, where options for Ebib's window management can be set. All options are documented in the customisation buffers. You can go to Ebib's customisation buffer with `M-x customize-group RET ebib RET`, or by using the menu «Ebib | Options | Customize Ebib».
-Another way to customise Ebib is to use the initialisation file `~/.emacs.d/ebibrc`. (Actually, the location and name of this file can be customised as well.) This file contains normal Lisp code and is the best way to customise key bindings (as discussed in the next section), but it can in fact be used to run any Lisp code.
-
## Modifying Key Bindings ##
@@ -1007,12 +959,13 @@ In addition, `ebib-search-map` is a transient key map that is activated when `eb
As an example, the default keybindings in`ebib-multiline-mode-map`, which are rather awkward to type, can be redefined as follows:
```Commonlisp
-(define-key ebib-multiline-mode-map
- "\C-c\C-c" 'ebib-quit-multiline-buffer-and-save)
-(define-key ebib-multiline-mode-map
- "\C-c\C-q" 'ebib-cancel-multiline-buffer)
-(define-key ebib-multiline-mode-map
- "\C-c\C-s" 'ebib-save-from-multiline-buffer)
+(with-eval-after-load 'ebib
+ (define-key ebib-multiline-mode-map
+ "\C-c\C-c" 'ebib-quit-multiline-buffer-and-save)
+ (define-key ebib-multiline-mode-map
+ "\C-c\C-q" 'ebib-cancel-multiline-buffer)
+ (define-key ebib-multiline-mode-map
+ "\C-c\C-s" 'ebib-save-from-multiline-buffer)))
```
</article>
diff --git a/manual/older-news.text b/manual/older-news.text
new file mode 100644
index 0000000..5f5b163
--- /dev/null
+++ b/manual/older-news.text
@@ -0,0 +1,55 @@
+
+## Version 2.11, January 2017 ##
+
+- Update for `parsebib` v. 2.3.
+
+## Version 2.10, January 2017 ##
+
+- Improved index column display.
+
+## Version 2.9, January 2017 ##
+
+- Allow `%s` in the program strings in `ebib-file-associations`, making it possible to pass command line arguments to the program being called.
+
+## 19 December 2016 ##
+
+- Remove support for a separate rc file for Ebib. User configuration should be moved to Emacs' `init.el` file. To keep Ebib customisation in a separate file, simply load it from `init.el`.
+- The macro `ebib-key` has also been removed. Simply use `define-key` or any other key binding mechanism to define keys for Ebib. See the section [Modifying Key Bindings](#modifying-key-bindings) for details.
+
+## 7 December 2016 ##
+
+- Upgrade Emacs dependency to 24.4.
+
+## 5 December 2016 ##
+
+- New library `org-ebib`. This defines a new Org link type `ebib:`, which uses the command `org-ebib-open` to open Ebib. The previous commands to do this, `ebib-show-entry` and `ebib-open-org-link` have been removed. `org-ebib` also allows the creation of Org links to Ebib entries with `org-store-link`.
+- New citation insertion command `ebib-insert-citation`. This replaces `ebib-insert-bibtex-key`, so please update your key bindings. The new command uses `ivy` for completion if this package is available, so that it is possible to select an entry by typing parts of its author and/or title.
+
+
+## 7 November 2016 ##
+
+- New tabulated list interface in index buffer. This interface is not based on Emacs' built-in `tabulated-list-mode`, hence sorting cannot be done by clicking on the column headers. Sorting can be done with `<`, `>` (sort ascending and sort descending, respectively, which ask for the column to sort) and `=`, to reset to default sort (which is on the entry key).
+- The user option `ebib-index-display-fields` is replaced with `ebib-index-columns`, which has a different format: each element in `ebib-index-columns` describes a column in the tabulated view and consists of a list containing the field name, the column's width and a boolean indicating whether sorting on this column is possible.
+
+
+## Version 2.8, 26 October 2016 ##
+
+- Changed key bindings: `j` and `k` no longer move up/down in the index, entry and strings buffers; use `p` and `n` instead. Furthermore, `i` now executes `ebib-push-bibtex-key` (used to be `p`), and `I` (capital i) executes `ebib-browse-doi` (used to be `i`).
+- In the index buffer, `ebib-search-next` (which used to be bound to `n`) is no longer bound. Instead, `ebib-search` (still bound to `/`) activates a transient map which binds the keys `/` and `RET` to `ebib-search-next`. Any other key disables the transient keymap and is executed normally.
+- In the index buffer, `C-u /` repeats the previous search. (This fixes a small bug that has so far gone unnoticed: moving to the top of the databas and calling `ebib-search-next`, as previously suggested in the manual to get around the fact that `ebib-search-next` does not wrap, would not search the first entry.)
+- In the entry buffer, `x` is replaced by `k` (`ebib-kill-field-contents`).
+- New functions: `ebib-kill-entry` and `ebib-yank-entry` for killing and yanking BibTeX entries. `ebib-kill-entry` deletes the current entry from the database and puts it in the kill ring. `ebib-yank-entry` adds an entry from the kill ring to the current database.
+
+
+## Version 2.7, 22 September 2016 ##
+
+- Reading list management: add and remove BibTeX entries to an Org reading list.
+- Remove options `ebib-notes-identifier-function` and `ebib-notes-title-function`.
+- Add option `ebib-notes-template-specifiers`: allow customisation of the format specs used in `ebib-notes-template`. (This option replaces `ebib-notes-identifier-function` and `ebib-notes-title-function`).
+
+## Version 2.6.3, 31 August 2016 ##
+
+- Allow storing notes in a single file rather than using one file per note.
+- Correct handling of DOIs.
+- Add option `ebib-truncate-file-names`: if set (the default), file names added to the `file` field are truncated relative to `ebib-file-search-dirs`.
+- Add option `ebib-file-name-mod-function`: modify file paths before storing them in the `file` field.