diff options
Diffstat (limited to 'biblio/bibtex/utils/ebib/doc/html/ebib-manual.html')
-rw-r--r-- | biblio/bibtex/utils/ebib/doc/html/ebib-manual.html | 2224 |
1 files changed, 2224 insertions, 0 deletions
diff --git a/biblio/bibtex/utils/ebib/doc/html/ebib-manual.html b/biblio/bibtex/utils/ebib/doc/html/ebib-manual.html new file mode 100644 index 0000000000..a5ba2de5b4 --- /dev/null +++ b/biblio/bibtex/utils/ebib/doc/html/ebib-manual.html @@ -0,0 +1,2224 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Ebib Manual</title> + <meta name="generator" content="muse.el" /> + <meta http-equiv="Content-Type" + content="text/html; charset=iso-8859-1" /> + <link rel="stylesheet" type="text/css" media="screen" href="ebib-manual.css" /> + </head> + <body> + <h1>Ebib Manual</h1> + <!-- Page published by Emacs Muse begins here --> +<div id="menu"> + +<div class="contents"> +<dl> +<dt> +<a href="#sec1">Installation</a> +</dt> +<dt> +<a href="#sec2">Basic Usage</a> +</dt> +<dd> +<dl> +<dt> +<a href="#sec3">Getting Started</a> +</dt> +<dt> +<a href="#sec4">Editing the Database</a> +</dt> +<dt> +<a href="#sec5">Saving a Database</a> +</dt> +<dt> +<a href="#sec6">Searching</a> +</dt> +<dt> +<a href="#sec7">LaTeX Integration</a> +</dt> +<dt> +<a href="#sec8">Cross-referencing</a> +</dt> +<dt> +<a href="#sec9">Printing the Database</a> +</dt> +<dt> +<a href="#sec10">Marking Entries</a> +</dt> +<dt> +<a href="#sec11">Calling a Browser</a> +</dt> +<dt> +<a href="#sec12">Viewing Files</a> +</dt> +</dl> +</dd> +<dt> +<a href="#sec13">Advanced Features</a> +</dt> +<dd> +<dl> +<dt> +<a href="#sec14">Screen Layout</a> +</dt> +<dt> +<a href="#sec15">Preloading <code>.bib</code> Files</a> +</dt> +<dt> +<a href="#sec16"><code>@Preamble</code> Definition</a> +</dt> +<dt> +<a href="#sec17"><code>@String</code> Definitions</a> +</dt> +<dt> +<a href="#sec18">Sorting the <code>.bib</code> file</a> +</dt> +<dt> +<a href="#sec19">Merging and Importing</a> +</dt> +<dt> +<a href="#sec20">Exporting Entries</a> +</dt> +<dt> +<a href="#sec21">Timestamps</a> +</dt> +<dt> +<a href="#sec22">Multiple Identical Fields</a> +</dt> +<dt> +<a href="#sec23">Virtual Databases</a> +</dt> +<dt> +<a href="#sec24">The Multiline Edit Buffer</a> +</dt> +</dl> +</dd> +<dt> +<a href="#sec25">The Ebib Buffers</a> +</dt> +<dd> +<dl> +<dt> +<a href="#sec26">The Index Buffer</a> +</dt> +<dt> +<a href="#sec27">The Entry Buffer</a> +</dt> +<dt> +<a href="#sec28">The Strings Buffer</a> +</dt> +</dl> +</dd> +<dt> +<a href="#sec29">Customisation</a> +</dt> +<dd> +<dl> +<dt> +<a href="#sec30">The Customisation Buffer</a> +</dt> +<dt> +<a href="#sec31">Modifying Key Bindings</a> +</dt> +</dl> +</dd> +</dl> +</div> + + +</div> + +<div id="main"> + +<p>Ebib is a program with which you can manage BibTeX database files without +having to edit the raw <code>.bib</code> files. It runs in GNU/Emacs, version 21.1 or +higher (lower versions are not supported) and XEmacs (at least from version +21.4; lower version have not been tested, but may work.)</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> + +<p>The advantage of having a BibTeX database manager inside Emacs is that X is +no longer required, as Emacs can run on the console, and also that some +integration with Emacs' TeX and LaTeX modes becomes possible. For example, +you can push a BibTeX key from Ebib to a LaTeX buffer, or, vice versa, when +you're in a LaTeX buffer, you can consult your BibTeX database and insert a +key from it into the document. Another advantage of Ebib is that it is +completely controlled by key commands: no stressful mouse movements are +required, as with most other (usually X-based) BibTeX database managers.</p> + + +<h2><a name="sec1" id="sec1"></a> +Installation</h2> + +<p class="first">To install Ebib, so that it will be loaded automatically when Emacs is +started, simply copy the file <code>ebib.el</code> to somewhere in your load path and +add the following line to Emacs' init file (<code>~/.emacs</code> for GNU/Emacs, +<code>~/.xemacs/init.el</code> for XEmacs):</p> + +<pre class="example"> +(autoload 'ebib "ebib" "Ebib, a BibTeX database manager." t) +</pre> + +<p>Note: if you do not know what your load path is set to, go to the <code>*scratch*</code> +buffer, type <code>load-path</code> on an empty line, put the cursor right after it and +type <code>C-j</code>. The value of <code>load-path</code> will then appear in the buffer.</p> + +<p>When Ebib is loaded, you can run 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 class="example"> +(global-set-key "\C-ce" 'ebib) +</pre> + +<p>You can of course choose any key combination you like. (In Emacs, key +combinations of <code>C-c <letter></code> are reserved for the user, so that no package +may set them.)</p> + +<p>It is recommended to byte-compile the source, Ebib runs quite a lot faster +when it is byte-compiled. You can do this either within Emacs with <code>M-x +byte-compile-file</code>, or from your shell by going into the directory where you +put <code>ebib.el</code> and typing:</p> + +<pre class="example"> +emacs -batch -f batch-byte-compile ebib.el +</pre> + +<p>(Substitute <code>emacs</code> with <code>xemacs</code> if you use XEmacs.) This will create a file +<code>ebib.elc</code>, which Emacs will load instead of <code>ebib.el</code>. Byte-compiling Ebib may +produce a warning about functions that are ``not known to be +defined''. This can be safely ignored. GNU Emacs and XEmacs have some small +differences, and the functions reported in this warning are those used by +the other version. Ebib makes sure that the correct functions are called.</p> + + + + +<h2><a name="sec2" id="sec2"></a> +Basic Usage</h2> + +<p class="first">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. You can move through these keys with the cursor +keys. In the entry buffer, the fields of the currently highlighted entry +are shown, with their values.</p> + +<p>In this chapter, all basic functions of Ebib are described, so that you can +get startet with it. At times, reference will be made to later chapters, +where more specific functions are described.</p> + + + +<h3><a name="sec3" id="sec3"></a> +Getting Started</h3> + +<p class="first">Ebib is started 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. The +command <code>z</code> can also be used to leave Ebib. 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> + + +<h4>Opening a <code>.bib</code> file</h4> + +<p class="first">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. Fields (e.g. <code>author, title, year</code> etc.) +that Ebib does not know about, are loaded (and saved) but not displayed, so +they cannot be edited. Therefore, you should make sure that all the entry +types and fields that your databases use are defined. A sensible set has +been predefined, so that anyone who's using standard BibTeX entry types +should have no problem loading an existing <code>.bib</code> file into Ebib. If, +however, you have custom entry types, or custom fields in your <code>.bib</code> files, +you should read the chapter on customising Ebib to learn how to define +them, so that Ebib knows about them. (See <a href="#entry-types">Entry types</a>.)</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, it will log a warning. If Ebib +finds something that it believes to be incorrect, an error will be +logged. If any warnings or errors occur while loading the <code>.bib</code> file, Ebib +tells you so after loading the file. To view the log file, press <code>l</code> in the +index buffer.</p> + +<p>Note that even if it detects warnings or errors, Ebib will try to continue +parsing the rest of the <code>.bib</code> file. That means that normally, only the entry +in which an error occurs is not read. Entries occurring after the +problematic one are read.</p> + + + +<h4>Navigating a <code>.bib</code> file</h4> + +<p class="first">Once you've opened a <code>.bib</code> file, the keys of all the entries in the file are +shown in alphabetical order in the index buffer in the top Ebib window. (In +fact, it is possible to show more than just the entry key in this +buffer. See <a href="#index-display-fields">Index Display Fields</a> on how to accomplish this.) The first +entry is highlighted, meaning it is the current entry. The fields it holds +and their values are shown in the entry buffer in the bottom Ebib +window. The first field is the type field, which tells you what kind of +entry you're dealing with (i.e. <code>book, article</code>, etc.).</p> + +<p>Below the type field, Ebib displays (up to) three sets of fields. The first +set are the so-called obligatory fields, the fields that BibTeX requires to +be filled. The second group are the optional fields, which do not have to +be filled but which BibTeX will normally add to the bibliography if they do +have a value. The third group are the so-called additional fields. These +fields are usually ignored by BibTeX (note that BibTeX normally ignores +<em>all</em> fields it does not know), although there are bibliography styles that +treat some of these fields as optional rather than as additional; (i.e., +the <code>harvard</code> styles do typeset the <code>url</code> field, if present.)</p> + +<p>The first two groups of fields are different for each entry type, while the +third group are common to all entry types. You can use the additional +fields, for example, to add personal comments to the works in your +database. Ebib by default defines the following additional fields: +<code>crossref, url, annote, abstract, keywords, file</code> and <code>timestamp</code>. If these are +not sufficient for you, you need to customise Ebib and add your own +fields. (See <a href="#additional-fields">Additional Fields</a>, if you need to find out how to do that.)</p> + +<p>To move around in the index buffer, you can use the <code>up</code> and <code>down</code> cursor +keys, <code>C-p</code> and <code>C-n</code>, or for those more used to mutt's key bindings, <code>k</code> and +<code>j</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> + +<p>Ebib is not restricted to opening just one <code>.bib</code> file at a time. You can +open more files by just typing <code>o</code> again and entering the filename. Ebib +numbers the databases: the number of each database is shown in the mode +line of the index buffer, directly before the database name. The keys 1—9 +provide a quick way of jumping from one database to another. Note that the +numbering is dynamic: if you have three databases opened and then close the +second, database 3 becomes database 2.</p> + +<p>With the <code>left</code> and <code>right</code> cursor keys, you can move to the previous or next +database. These keys wrap, so if you hit the <code>left</code> cursor key while the +first database is active, you move to the last database. If you are done +with a database and want to close it, type <code>c</code>. This closes the current +database. It does not leave Ebib, and all other databases you have open +will remain so.</p> + + + +<h4>Starting a New <code>.bib</code> File</h4> + +<p class="first">If you want to start a new <code>.bib</code> file from scratch, you cannot just go and +enter entries. You first have to give the database a name. So, to start a +new database, type <code>o</code> first, and give the new file a name. Once you have +done this, you can start adding entries to the database.</p> + + + + +<h3><a name="sec4" id="sec4"></a> +Editing the Database</h3> + +<p class="first">Of course, being able to open and view <code>.bib</code> 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.</p> + + +<h4>Adding and Deleting Entries</h4> + +<p class="first">To add an entry to a database, you type <code>a</code>. When you do this, Ebib first +asks you for an entry key, as every entry must be identified by a unique +key. Just type a name for the new entry (say <code>jones1998</code>). Since the entry +key must be unique, Ebib will complain if you enter a key that already +exists.</p> + +<p>Note that if you should later decide that you want to change the key of an +entry, you can do so with the command <code>E</code>. So if you have an entry with the +key <code>jones1998</code> and you want to add another entry by Jones from 1998, you can +call the new one <code>jones1998b</code> and rename the existing one to <code>jones1998a</code>.</p> + +<p>Deleting an entry is done with <code>d</code>. Be careful with this: you will be asked +for confirmation, but once you've confirmed, the entry is gone, and it is +not possible to bring it back. There is no undo in Ebib. (If you haven't +saved the database yet, it is still possible to retrieve the deleted entry +from the <code>.bib</code> file, and otherwise it may still be in the backup file that +Ebib creates. See <a href="#saving-database">Saving a Database</a>.)</p> + + + +<h4>Editing Fields Values</h4> + +<p class="first">Editing the field values for an entry is done in the lower of the two Ebib +buffers, the so-called entry buffer. You can move focus to the entry buffer +by typing the command <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>C-p</code> and <code>C-n</code>, or <code>j</code> +and <code>k</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>. 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.</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, it is best to set the +<code>type</code> field first, because the <code>type</code> field determines which other fields are +available for an entry.</p> + +<p>Note also that after editing a field, Ebib (usually) puts you on the next +field. This is convenient if you're creating a new entry and need to fill +out several fields in a row.</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> + + + +<h4>Editing Multiline Values</h4> + +<p class="first">Apart from the <code>type</code> and <code>crossref</code> field, there is another field that Ebib +handles in a special way when you edit its value. This is the <code>annote</code> +field. 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 the 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-x b</code>. (This is of course +the standard Emacs command to switch buffers. It is redefined in Ebib's +multiline edit buffer.)</p> + +<p>If you want to leave the multiline edit buffer without saving the text you +have just typed, you can use the command <code>C-x k</code>. This too is redefined in +the multiline edit buffer: it leaves the multiline edit buffer (and hides +it), but it does not actually kill the buffer.</p> + +<p>Multiline values are not restricted to the <code>annote</code> field. Any field can in +fact hold a multiline value. (Except of course the <code>type</code> and <code>crossref</code> +fields.) To give a field a multiline value, use <code>l</code> instead of <code>e</code>. You will +again be put in the multiline edit buffer, where you can edit the +value. Note that you can use <code>l</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.</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 the +multiline edit buffer. Therefore, you need <code>l</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 the multiline edit buffer, see +<a href="#multiline-edit-buffer">The Multiline Edit Buffer</a>.</p> + + + +<h4>Copy, cut, paste (yank), and delete</h4> + +<p class="first">A few more commands are available when you're in the entry buffer editing +field values. The commands <code>c</code>, <code>x</code> and <code>y</code> implement a copy and paste system: <code>c</code> +copies the contents of the current field to the kill ring, <code>x</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>: every additional use of <code>y</code> moves back in the kill ring.</p> + +<p>Lastly, there is the command <code>d</code>, which deletes the contents of the current +field, without asking questions and without storing the text in the kill +ring.</p> + +<p>Note that <code>y</code> only works when the current field does not have a value +yet. This is to prevent you from accidentally overwriting a field value. If +you do want to yank text into a field that already has a value, simply hit +<code>d</code> first to delete the text.</p> + + + + +<h3><a name="sec5" id="sec5"></a> +Saving a Database</h3> + +<p><a name="saving-database" id="saving-database"></a> +When you have undertaken any kind of editing action on a database, it is +marked as modified, which is indicated in the mode line for the index +buffer. A modified database can be saved by typing <code>s</code>. This saves the +database to the file it was loaded from without asking for +confirmation. (It is similar to <code>C-x C-s</code> in Emacs.) If you're saving a file +for the first time after loading it, Ebib creates a backup file under the +same name appended with a tilde: <code><filename>.bib~</code>.</p> + +<p>If you have multiple databases open, have made changes in more than one of +them, and want to save all of them without going through each yourself, you +can use <code>S</code>. (That's a capital <code>S</code>.) This command saves all modified databases.</p> + +<p>Another way to save a database is to use the command <code>w</code>. Use this if you +want to write the database to another file than the one it was loaded +from. Ebib will ask you for a filename to save to, and will of course warn +you if that file happens to exist already. Note that this command is +similar to <code>C-x C-w</code> in Emacs, so that after using it, the new <code>.bib</code> file +becomes associated with the database.</p> + + + +<h3><a name="sec6" id="sec6"></a> +Searching</h3> + +<p><a name="searching" id="searching"></a> +Ebib provides several search methods. First, if you are in the index +buffer, the normal Emacs incremental searches, <code>C-s</code> and <code>C-r</code>, function as +expected. You can use them to search entry keys. Note that once you've +found the key you're searching, you must hit <code>ENTER</code> to make it active. Ebib +does not update the entry buffer during incremental search, as this would +be rather pointless: you're only interested in the entry you're searching +for, not in the entries you pass along the way.</p> + +<p>Of course, it is also possible to search the database itself. If you type +<code>/</code>, Ebib asks you for a search term. This can be a regular expression, to +allow for flexibility in searching. After hitting <code>ENTER</code>, Ebib will start +searching the database (starting from the current entry, <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 it +displays in front of the field value. Keep an eye out for this when doing a +search, because Ebib only shows the first line of multiline values, and if +the search term appears in another line, the highlighted <code>+</code> is the only +indication that the search term was found. (Well, that and the fact that +Ebib does <em>not</em> say <code>Search string not found</code>, of course...)</p> + +<p>A search term may of course appear more than once in the database. To +search for the next occurrence, type <code>n</code>. This will continue searching for +the search string in the rest of the database. Again, the first entry found +to contain the search string is displayed. Note that <code>n</code> does not wrap: if +the end of the database is reached, Ebib stops searching. To continue +searching from the top, hit <code>g</code> and then <code>n</code>.</p> + +<p>The functions described here form Ebib's basic search functionality. Ebib +also has a much more powerful search mechanism in the form of <em>virtual +databases</em>. These are described later. (See <a href="#virtual-databases">Virtual Databases</a>.)</p> + + + +<h3><a name="sec7" id="sec7"></a> +LaTeX Integration</h3> + +<p class="first">Having a BibTeX database manager running inside Emacs has an additional +advantage: it makes it trivially easy to insert BibTeX keys in your LaTeX +documents.</p> + +<p>Ebib provides two functions for this. First, if you're in a LaTeX buffer, you +can call the function <code>ebib-insert-bibtex-key</code>. When you invoke this command, +Emacs prompts you for a key from the database(s) associated with the current +buffer, a citation command (that has to be typed <em>without</em> the backslash) and any +optional argument(s) the command allows. You can type the key using +TAB-completion, and after hitting <code>RET</code>, Emacs puts a BibTeX citation at the +cursor position in the current buffer with the key you selected.</p> + +<p>You can also do it the other way around: if you're in the index buffer in Ebib, +you can <em>push</em> an entry to a LaTeX buffer. To do this, use the key <code>p</code>. Ebib will +ask you for a buffer to push the entry to, a citation command and also any +optional arguments, and then insert a citation at the current cursor position in +the buffer you've supplied.</p> + +<p>For the citation command that <code>ebib-insert-bibtex-key</code> and the command key <code>p</code> ask +for can be any command that you need. But it is also possible to predefine a +list of citation commands which you can then enter at this prompt using tab +completion. For details on setting this up, see <a href="#insertion-commands">Insertion Commands</a>.</p> + +<p>There is another function that is available outside Ebib: +<code>ebib-entry-summary</code>. This command reads the key under the cursor in the +current buffer and displays the field values associated with that key in a +<code>*Help*</code> buffer. This allows you to quickly check a reference in a text.</p> + +<p>Probably the easiest way to use both <code>ebib-insert-bibtex-key</code> and +<code>ebib-entry-summary</code> is to bind them to a key sequence. For example, you +could put the following in your <code>~/.emacs</code>:</p> + +<pre class="example"> +(add-hook 'LaTeX-mode-hook #'(lambda () + (local-set-key "\C-cb" 'ebib-insert-bibtex-key))) +</pre> + +<p>This binds <code>C-c b</code> to the command <code>ebib-insert-bibtex-key</code> in AUCTeX's LaTeX +mode. (Note that commands of the form <code>C-c <letter></code> are reserved for the +user, and should therefore not be set by any package. For this reasons, +Ebib does not set this command automatically.)</p> + + +<h4>Consulting databases from within a LaTeX file</h4> + +<p class="first">The commands <code>ebib-insert-bibtex-key</code> and <code>ebib-entry-summary</code> must consult the +database or databases loaded in Ebib, and Ebib tries to be smart about +which database(s) to consult. Usually, a LaTeX file has a <code>\bibliography</code> +command somewhere toward the end, which names the <code>.bib</code> file or files that +contain the bibliography entries. If you consult a BibTeX database from +within a LaTeX file, Ebib first looks for a <code>\bibliography</code> command, reads +the <code>.bib</code> files from it, and then sees if those files happen to be open. If +they are, Ebib uses them to let you pick an entry key (in the case of +<code>ebib-insert-entry-key</code>) or to search for the entry (in the case of +<code>ebib-entry-summary</code>).</p> + +<p>Of course, it may be the case that the LaTeX file is actually part of a +bigger project, and that only the master file contains a <code>\bibliography</code> +command. To accommodate for this, Ebib checks whether the (buffer-local) +variable <code>TeX-master</code> is set to a filename. If it is, it reads that file and +tries to find the <code>\bibliography</code> command there. (Note: <code>TeX-master</code> is an +AUCTeX variable, which is used to keep track of multi-file projects. If you +don't use AUCTeX, this functionality doesn't work, and Ebib will only check +the current file for a <code>\bibliography</code> command.)</p> + +<p>Note that if one of the <code>.bib</code> files in the <code>\bibliography</code> command isn't +loaded, Ebib issues a warning message about this, and continues to check +for the next <code>.bib</code> file. These warning messages appear in the minibuffer, +but are probably directly overwritten again by further messages or prompts +Ebib produces, so check the <code>*Messages*</code> buffer if Ebib doesn't seem to be +able to find an entry that you're sure is in one of your databases.</p> + +<p>Another thing to keep in mind is that Ebib only looks for a <code>\bibliography</code> +command once: the first time either <code>ebib-insert-bibtex-entry</code> or +<code>ebib-entry-summary</code> is called. It stores the result of this search and uses +it the next time either of these commands is used. Therefore, if you make a +change to the <code>\bibliography</code> command, you must reload the file (use <code>M-x +revert-buffer</code>) to make sure Ebib rereads the <code>\bibliography</code> command.</p> + +<p>If no <code>\bibliography</code> command is found at all, either in the LaTeX file +itself, or in the master file, Ebib simply consults the current database, +i.e. the database that was active when Ebib was lowered with <code>z</code>.</p> + + + + +<h3><a name="sec8" id="sec8"></a> +Cross-referencing</h3> + +<p><a name="cross-referencing" id="cross-referencing"></a> +BibTeX has a cross-referencing facility. Suppose you have an entry <code>jones1998</code>, +which appeared in a book that is also in your database, say under <code>miller1998</code>. +You can tell BibTeX that <code>jones1998</code> is contained in <code>miller1998</code> by putting +<code>miller1998</code> in the <code>crossref</code> field. When BibTeX finds such a cross-reference, all +the fields of <code>jones1998</code> that don't have a value inherit their values from +<code>miller1998</code>. At the very least, this saves you some typing, but more importantly, +if two or more entries cross-reference the same entry, BibTeX automatically +includes the cross-referenced entry in the bibliography (and puts a reduced +reference in the cross-referencing entries).</p> + +<p>When you fill in the <code>crossref</code> field in Ebib, Ebib displays the values of the +cross-referenced entry in the entry buffer. To indicate that they are just +inherited values, they are marked with <code>ebib-crossref-face</code>, which by default is +red. (You can customise it, of course. See the customisation option +<a href="#crossref-face">Crossref Face</a>.) These values are just displayed for convenience: otherwise, Ebib +treats these fields as if they are empty. That is, they cannot be edited (to +edit them, you need to edit the cross-referenced entry), and it's not possible +to copy these values to the kill ring.</p> + +<p>If you're viewing an entry that has a cross-reference and you want to go to the +cross-referenced entry you can type <code>F</code>. This command reads the value of the +<code>crossref</code> field and then displays that entry. If you want to do the reverse, +i.e., see if the current entry is cross-referenced by any other entries, you can +use the key <code>N</code>. What this command actually does is to make the key of the current +entry the current search string and to search for its first occurrence <em>after</em> the +current entry. Like the normal search command <code>/</code>, <code>N</code> does not wrap and only +searches forward. So if you want to search for the next cross-referencing entry +you need to press <code>n</code> (i.e., lowercase <code>n</code>), and to continue searching from the +first entry, press <code>g</code> followed by <code>n</code>.</p> + +<p>Note that if you want to use BibTeX's cross-referencing options, you need to set +the option <a href="#save-xrefs-first">Save Xrefs first</a>. This tells Ebib to save all entries with a <code>crossref</code> +field first in the <code>.bib</code> file. Without this, BibTeX's cross-referencing will not +work reliably.</p> + + + +<h3><a name="sec9" id="sec9"></a> +Printing the Database</h3> + +<p><a name="printing-database" id="printing-database"></a> +Sometimes it may be useful to have a <code>.pdf</code> file or print-out of your +database. Although Ebib does not actually do the printing itself, it can +create a LaTeX file for you that you can compile and print. In fact, there +are two ways of doing this.</p> + +<p>The first is the command <code>L</code>. This command creates a simple LaTeX document +that essentially contains a <code>\nocite{*}</code> command followed by a +<code>\bibliography</code> command referring to the <code>.bib</code> file belonging to +the current database. You can then run the usual sequence of LaTeX, BibTeX, +LaTeX, LaTeX on this file, creating a document containing a list of all the +references in your database.</p> + +<p>The second command for printing a database is <code>P</code>. This command also creates +a LaTeX file. However, instead of simply providing a +<code>\nocite{*}</code> command, <code>P</code> creates a <code>tabular</code> environment for each +entry in the database listing all the fields of that entry and their +values.</p> + +<p>The difference between <code>L</code> and <code>P</code> should be obvious: with <code>L</code>, you get a list of +references created by BibTeX. This means that the references look the way +they will when actually used in a document, but it also means that the list +only contains the information that BibTeX deems relevant.</p> + +<p>With <code>P</code> you get an overview of your database with <em>all</em> the field values of +each entry, including the ones that BibTeX does not use. The entries are +not formatted as literature references, but in a way similar to how they +are shown in Ebib.</p> + +<p>By default, <code>P</code> only shows single-line field values. That is, multiline +values are normally excluded. If you want to include multiline values in +the print-out, you have to set the option <code>Print Multiline</code> in Ebib's +customisation buffer. (See <a href="#customisation-buffer">The Customisation Buffer</a>.) With this option set, +Ebib will include all multiline values in the LaTeX file that <code>P</code> +creates. Note however that Ebib does not change anything about the +formatting of the text in a multiline value. So if you plan to make (heavy) +use of this option, make sure that the way you type your text conforms to +LaTeX's conventions (e.g. empty lines to mark paragraphs, etc.) and doesn't +contain any characters such as <code>&</code> that are illegal in LaTeX. (Or, +alternatively, use LaTeX code in your multiline fields.)</p> + +<p>As mentioned, when you use either <code>L</code> or <code>P</code>, Ebib creates a LaTeX file. More +precisely, it creates a temporary buffer and writes the LaTeX code into it, +and then saves the contents of that buffer to a file. After it has done +that, Ebib lowers itself and instruct Emacs to open the file in a buffer, +which will then be properly set up as a LaTeX buffer. From there you can +run LaTeX and view the result.</p> + +<p>Before doing all this, Ebib asks you which file to write to. Be careful +with this: since this is supposed to be a temporary file, Ebib simply +assumes that if you provide a filename of an existing file, it can +overwrite that file without warning!</p> + +<p>A better way to tell Ebib which file to use is to set the option <code>Print +Tempfile</code> in Ebib's customisation buffer to some temporary file. When this +option is set, Ebib will always use this file to write to, and will not ask +you for a filename anymore when you type <code>L</code> or <code>P</code>.</p> + +<p>There are two more customisation options for printing the database. These +are <code>Print Preamble</code> and <code>LaTeX Preamble</code>. With these options, you can specify +what Ebib should put in the preamble of the LaTeX files it creates. Use +this if you want to use specific packages +(e.g. <code>\usepackage{a4}</code> or +<code>\usepackage{times})</code>. This is especially useful for <code>L</code>, since by +default, Ebib uses BibTeX's standard bibliography style. With the option +<code>LaTeX Preamble</code> you can set your preferred bibliography style. Details are +discussed in the chapter on customisation, see <a href="#customisation-buffer">The Customisation Buffer</a>.</p> + + + + +<h3><a name="sec10" id="sec10"></a> +Marking Entries</h3> + +<p class="first">Commands in the index buffer generally operate on one single entry, or on +all entries. For some, however, it may sometimes be useful to perform them +on more than one entry, but not necessarily all of them. This can be +achieved by marking entries. You can mark the entries you want to perform a +command on with the key <code>m</code>. This marks (or unmarks) the current +entry. Marked entries are displayed in inverse video (in GNU Emacs) or +white on red (in XEmacs; note that the face properties of marked entries +can be customised through the customisation option <a href="#marked-face">Marked Face</a>.)</p> + +<p>Of the commands discussed so far, four can be used on marked entries: <code>d</code>, <code>p</code>, +<code>L</code> and <code>P</code>. Note, however, that it is not enough to mark the entries you want +and then type any of these commands. If you do so, they will behave as if +no entries were marked. To get these commands to work on the marked +entries, you have to type a semicolon before them. That is, <code>; d</code> deletes all +marked entries, and <code>; L</code> and <code>; P</code> create a LaTeX file of only the marked +entries. The command <code>m</code> itself can also be used with the <code>;</code> prefix. If there +are any marked entries, <code>; m</code> unmarks them all. Otherwise, <code>; m</code> marks all +entries.</p> + +<p><code>; p</code> pushes all marked entries to a LaTeX buffer. It does so by putting them +all in a single <code>\cite</code> command, separated by commas, not by putting them in +separate <code>\cite</code> commands.</p> + + + +<h3><a name="sec11" id="sec11"></a> +Calling a Browser</h3> + +<p class="first">With more and more scientific literature becoming available on-line, it +becomes common to store URLs in a BibTeX database. Sometimes you may want +to load such a URL in your browser. Ebib provides a convenient way for +doing so.</p> + +<p>If you type <code>u</code> in the index buffer, Ebib takes the first 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, and you want to pass the second +(or third, etc.) to the browser, you can use a prefix argument. So typing +<code>M-2 u</code> sends the second URL to your browser, <code>M-3 u</code> the third, and so on.</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>" ' <</code> or <code>></code> as a URL. Furthermore, Ebib +regards everything that is enclosed in a LaTeX <code>\url{...}</code> +command as a URL. This behaviour is controlled by a regular expression that +can be customised. (See <a href="#url-regexp">Url Regexp</a>.)</p> + +<p>There exists an Emacs function <code>browse-url</code>, which provides a nifty interface +to calling an external browser. In principle, Ebib uses this +function. However, if this function is not present on your installation, +you can set the option <a href="#browser-command">Browser Command</a> to call the browser.</p> + +<p>As just explained, if you press <code>u</code> in the index buffer, Ebib searches the +<code>url</code> field of the current entry for URLs. If you have the habit of putting +your URLs in another field, however, you may change the customisation +option <a href="#standard-url-field">Standard Url Field</a> and tell Ebib to use another field for searching +the URLs. (Keep in mind, though, that in the entry buffer, you can load a +URL from any field.)</p> + + + +<h3><a name="sec12" id="sec12"></a> +Viewing Files</h3> + +<p class="first">If you have electronic versions of the papers in your database stored on +your computer, you can use Ebib to call external viewers for these +files. The interface for this is similar to that for calling a browser: if +you press <code>f</code> in the index buffer, Ebib searches the <code>file</code> field for a +filename and when it finds one, calls an appropriate viewer.</p> + +<p>Just as with <code>u</code>, you can use <code>f</code> in the entry buffer as well, in which case it +can be used on any field, not just the <code>file</code> field. It is also possible to +have more than one filename in a field: you can select the one you want to +view with the prefix argument.</p> + +<p>Just as in the case of URLs, you can customise several things about the +file view functionality. The option <a href="#standard-file-field">Standard File Field</a> allows you to +customise the field that <code>f</code> extracts filenames from when pressed in the +index buffer. Extracting filenames is done with a regular expression, which +can be customised through the option <a href="#file-regexp">File Regexp</a>.</p> + +<p>The option <a href="#file-search-dirs">File Search Dirs</a> allows you to tell Ebib which directories it +needs to search for files. The default value is <code>~</code>, which means Ebib just +looks in your home dir. Since this is probably not where you keep your +files, you may want to customise this. Note that you can specify more than +one directory.</p> + +<p>Note that Ebib does not search directories recursively. It is possible, +however, to put subdirectories in the filenames. That is, if you put +something like <code>a/abney1987.pdf</code> in the <code>file</code> field, Ebib searches for the +relevant file in a subdirectory <code>a/</code> of the directories listed in the option +<code>File Search Dirs</code>. (Note that if you want to do this under Windows, you may +want to remove the backslash from the file regexp.)</p> + +<p>Ebib can call different external programs depending on the file type of the +relevant file, but you have to specify which programs to call. The option +<a href="#file-associations">File Associations</a> allows you to do this. By default, <code>.pdf</code> and <code>.ps</code> files are +handled, by <code>xpdf</code> and <code>gv</code>, respectively. You can specify further file types by +their extensions (do not include the dot). The program is searched for in +<code>PATH</code>, but you can of course specify the full path to the program.</p> + + + + +<h2><a name="sec13" id="sec13"></a> +Advanced Features</h2> + +<p class="first">The features discussed in the previous chapter should be sufficient to get +started using Ebib. However, Ebib has several more advanced features, which +are described in this chapter.</p> + + +<h3><a name="sec14" id="sec14"></a> +Screen Layout</h3> + +<p><a name="screen-layout" id="screen-layout"></a> +By default, Ebib takes over the entire Emacs frame it is started in. If you +have a wide enough screen, however, it may be more convenient to have Ebib +take up only part of the frame, so that you can have the LaTeX text you're +working on and Ebib visible at the same time. The option <a href="#layout">Layout</a> allows you +to do this, by giving you the ability to choose between a full-frame or a +split-frame layout.</p> + +<p>In the split-frame layout, the Ebib windows are displayed on the right of +the current frame, with the left part free for your document. In this +layout, some aspects of Ebib behave somewhat differently. Most importantly, +the multiline edit buffer is not displayed in the lower Ebib window, but in +the non-Ebib window on the left. (Obviously, after leaving the multiline +edit buffer, the original buffer is restored to that window.)</p> + +<p>Furthermore, pressing <code>z</code> in the index buffer leaves Ebib, but keeps the +buffers visible. You can get back to Ebib with the command <code>M-x ebib</code> (or any +key bound to it, of course), or simply by manually switching to the index +buffer. If you want to remove the Ebib buffers from the frame but keep Ebib +in the background, you can use <code>Z</code> (i.e. capital <code>Z</code>) in the index +buffer. (Note that <code>Z</code> is also available in the full-frame layout, but there +it is identical to <code>z</code>.)</p> + +<p>Lastly, the command <code>ebib-entry-summary</code> checks whether the Ebib buffers are +visible in the frame. If they are, it does not output the entry info in a +<code>*Help*</code> buffer, but rather displays the entry in Ebib itself.</p> + + + +<h3><a name="sec15" id="sec15"></a> +Preloading <code>.bib</code> Files</h3> + +<p class="first">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 <a href="#preload-bib-files">Preload Bib Files</a>.</p> + + + +<h3><code><a name="sec16" id="sec16"></a>@Preamble</code> Definition</h3> + +<p class="first">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 the latter two. <code>@comment</code> +definitions cannot be added to a <code>.bib</code> file through Ebib, and if Ebib finds +one in a <code>.bib</code> file, it is simply ignored.</p> + +<p><code>@preamble</code> and <code>@string</code> definitions can be handled, however. 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 class="example"> +@preamble{ "\newcommand{\noopsort}[1]{} " } +@preamble{ "\newcommand{\singleletter}[1]{#1} " } +</pre> + +<p>you can write this in your <code>.bib</code> +file:</p> + +<pre class="example"> +@preamble{ "\newcommand{\noopsort}[1]{} " + # "\newcommand{\singleletter}[1]{#1} " } +</pre> + +<p>Creating or editing a <code>@preamble</code> definition in Ebib is done by hitting <code>r</code> in +the index buffer. Ebib uses the multiline edit buffer for editing the text +of the <code>@preamble</code> definition, which means that as discussed above, <code>C-x b</code> +stores the <code>@preamble</code> text and returns focus to the index buffer, while <code>C-x +k</code> returns focus to the index buffer while abandoning any changes you may +have made. (For details on using the multiline edit buffer, see +<a href="#multiline-edit-buffer">The Multiline Edit Buffer</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 class="example"> +"\newcommand{\noopsort}[1]{} " +# "\newcommand{\singleletter}[1]{#1} " +</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> + + + +<h3><code><a name="sec17" id="sec17"></a>@String</code> Definitions</h3> + +<p class="first">If you press <code>t</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>C-p</code> and <code>C-n</code> and <code>k</code> and <code>j</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 <em>raw</em>. A raw field is a +field whose value is not surrounded by braces when the database is saved, +so that BibTeX recognises it as an abbreviation. To mark a field raw, press +<code>r</code>. An asterisk will appear before the field, indicating that it is +raw. 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 class="example"> +@string{WGA = "World Gnus Almanac"} +</pre> + +<p>you can create a BibTeX field +like this:</p> + +<pre class="example"> +title = 1966 # WGA +</pre> + +<p>which will produce ``1966 World +Gnus Almanac''. Or you can do:</p> + +<pre class="example"> +month = "1~" # jan +</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 raw.</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 raw. 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> + + + +<h3><a name="sec18" id="sec18"></a> +Sorting the <code>.bib</code> file</h3> + +<p><a name="sorting-bib-file" id="sorting-bib-file"></a> +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> + +<p>A sort level is not restricted to a single field. You can specify more +fields for a single sort level. Within a single sort level, a second sort +field is used if the first sort field does not have a value. For example, +books that have an editor instead of an author will have an empty <code>author</code> +field. If you sort the database on the <code>author</code> field, such entries will all +appear at the beginning of the <code>.bib</code> file, which is most likely not what you +want.</p> + +<p>To remedy this, you can specify both the <code>author</code> and the <code>editor</code> fields for +the first sort level. Ebib will then sort an entry on its <code>author</code> field if +it has a value, and will otherwise use the value of the <code>editor</code> field.</p> + +<p>The difference between two sort fields within one sort level and two sort +levels is that a second sort <em>field</em> is an alternative for the first field +when it has no value, while a second sort <em>level</em> is an additional sort +criterion when two or more entries cannot be sorted on the first level, +because they have identical values.</p> + +<p>By default, the option <code>Sort Order</code> has no value, which means that the +entries in the <code>.bib</code> file are sorted according to entry key. Those that wish +to customise the sort order will usually want to set the first sort level +to <code>author editor</code>, and the second to <code>year</code>. In that way, the entries in the +<code>.bib</code> file are sorted according to author/editor, and entries with the same +author/editor are sorted by year.</p> + +<p>Entries that cannot be sorted on some sort level, because the sort fields +are empty, are sorted on entry key. (Keep in mind that if the first sort +level yields <em>no value</em> for a specific entry, Ebib does <em>not</em> use the second +sort level to sort that entry. It uses the entry key. The second sort level +is only used if the first yields <em>identical</em> values for two or more entries.)</p> + +<p>Note that if you have set the option <code>Save Xrefs First</code> (see +<a href="#cross-referencing">Cross-referencing</a>), it is pointless to set a sort order. Saving +cross-referencing entries first messes up any sort order, so Ebib simply +ignores the sort order if <code>Save Xrefs First</code> is set.</p> + + + +<h3><a name="sec19" id="sec19"></a> +Merging and Importing</h3> + +<p class="first">As described in the previous chapter, adding entries to a database can be +done manually with the key <code>a</code>. There are other ways of adding entries to a +database, however.</p> + +<p>With the command <code>M</code> you can merge a second <code>.bib</code> file into your current +database. When you hit <code>M</code>, you are asked for a filename. Ebib then reads the +entries in this file and adds them to the database. Duplicate entries (that +is, entries with an entry key that already exists in the database) will not +be loaded. Ebib logs a warning about each duplicate entry to its log +buffer, and displays a warning after loading the <code>.bib</code> file when this +happens.</p> + +<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 e.g. on the internet, you can copy & 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> + + + +<h3><a name="sec20" id="sec20"></a> +Exporting Entries</h3> + +<p class="first">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>. Ebib will ask you for a +filename to export the entry to. (If you have already exported an entry +before, Ebib will present the filename you used as default, but you can of +course change it.)</p> + +<p>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.</p> + +<p>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>Note that the command <code>x</code> can operate on marked entries. So to export several +entries in one go mark them and type <code>; x</code>. You can use a prefix argument in +the normal way: <code>M-2 ; x</code> exports the marked entries to database 2.</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> + + + +<h3><a name="sec21" id="sec21"></a> +Timestamps</h3> + +<p><a name="timestamps" id="timestamps"></a> +Ebib provides the possibility to add a timestamp to every new entry, +recording the time it was added to the database. The timestamp is recorded +in the (additional) field <code>timestamp</code>. (By default, this field is not shown, +but you can make it visible by pressing <code>H</code> in the index buffer.)</p> + +<p>You can tell Ebib to create timestamps by setting the option <code>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.</p> + +<p>Ebib uses the function <code>format-time-string</code> to create the timestamp. The +format string that Ebib uses can be customised in Ebib's customisation +buffer. The default string is <code>"%a %b %e %T %Y"</code>, which produces a timestamp +of the form <code>"Mon Mar 12 01:03:26 2007"</code>. Obviously, this string is not +suited for sorting, so if you want to be able to sort on timestamps, you'll +need to customise the format string. See the documentation for +<code>format-time-string</code> on the options that are available.</p> + + + +<h3><a name="sec22" id="sec22"></a> +Multiple Identical Fields</h3> + +<p><a name="multiple-identical-fields" id="multiple-identical-fields"></a> +Under normal circumstances, a BibTeX entry only contains one occurrence of +each field. If BibTeX notices that an entry contains more than one +occurrence of an obligatory or optional field, it issues a warning. Ebib is +somewhat less gracious, it simply takes the value of the last occurrence +without giving any warning. (Note, by the way, that BibTeX will use the +value of the <em>first</em> occurrence, not the last.) When additional fields appear +more than once in an entry, BibTeX does not warn you, since it ignores +those fields anyway. Here, too, Ebib's standard behaviour is to ignore all +but the last value.</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 +<a href="#allow-identical-fields">Allow Identical Fields</a>.</p> + +<p>With this option set, Ebib collapses the multiple occurrences into a single +occurrence. All the values of the different occurrences are collected and +stored in the single occurrence, separated by semicolons. That is, Ebib +does not retain the multiple occurrences, but it does retain the values. So +suppose you have an entry that contains the following <code>keywords</code> fields:</p> + +<pre class="example"> +@book{jones1998, + author = {Jones, Joan}, + year = {1998}, + ... + keywords = {sleep}, + keywords = {winter}, + keywords = {hybernation} +} +</pre> + +<p>If you load this entry into Ebib with the option <code>Allow Identical Fields</code> +set, you will get the following:</p> + +<pre class="example"> +@book{jones1998, + author = {Jones, Joan}, + year = {1998}, + ... + keywords = {sleep; winter; hybernation} +} +</pre> + + + +<h3><a name="sec23" id="sec23"></a> +Virtual Databases</h3> + +<p><a name="virtual-databases" id="virtual-databases"></a> +In the previous chapter, Ebib's basic search functionality was +discussed. (See <a href="#searching">Searching</a>.) Ebib also provides a much more sophisticated +search and filtering mechanism in the form of <em>virtual databases</em>.</p> + +<p>A virtual database is a database that is not associated with any <code>.bib</code> +file. Rather, it is created from another database by selecting entries from +it based on a specific search pattern, called a <em>filter</em>. This allows you, +for example, to 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 hybernation'' in the <code>keyword</code> field, etc. Basically, the +filter can consist of an arbitray number of search criteria combined with +the logical operators <code>and, or</code> and <code>not</code>.</p> + + +<h4>Simple Selection</h4> + +<p class="first">Creating a virtual database is simple: press <code>&</code>, and Ebib will ask you for a +field to select on, and for a regular expression to select with. So if you +want to select all entries that contain ``Jones'' in the <code>author</code> field, you +press <code>&</code> and type <code>author</code> as the field and <code>Jones</code> as the regexp to filter on.</p> + +<p>Ebib will then create a virtual database containing the entries matching +your selection criterion. A virtual database has the same name as the +database it is based on, prepended with <code>V:</code>. It also has a number like any +other database, and you can move back and forth to other databases with the +number or cursor keys.</p> + +<p>If you don't want to filter on one specific field but rather want to select +all entries that match a certain regexp in any field, you can type <code>any</code> as +the field to filter on. So specifying <code>any</code> as the field and <code>Jones</code> as the +regexp, the virtual database will select all entries that have a field that +contains ``Jones'' in them.</p> + + + +<h4>Complex Filters</h4> + +<p class="first">Once you have a virtual database, it remains associated with the database +it was created from. This means that you can refine or extend the selection +(i.e. the filter) that the virtual database is based on. If, in the current +example, you want to include all the entries that have ``Jones'' in the +<code>editor</code> field, you have to perform 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 virtual database with all entries in +the original database that match the additional criterion.</p> + +<p>It is also possible to perform a logical <code>and</code> on the virtual database. Use +this if you want to select those entries that contain ``Jones'' in the +<code>author</code> field and e.g. ``symbiotic hybernation'' in the <code>keyword</code> field. A +logical <code>and</code> operation is done with the key <code>&</code>. (Note: this is the same key +that is used to create a virtual database. In fact, you can also create a +virtual database with <code>|</code>: when used in a normal database, <code>&</code> and <code>|</code> are +equivalent. They are only different in virtual databases.)</p> + +<p>Both the <code>&</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.</p> + +<p>That is, 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-- &</code> and +then filling out the relevant field and regexp. This prefix argument is +available both in real and in virtual databases.</p> + +<p>There is another way of performing a logical <code>not</code> operation, which is only +available in virtual databases: by pressing the key <code>~</code>, you invert the +current filter. That is, if you have a virtual 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>&</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> + +<p>If you want to know what the filter for the current virtual database is +exactly, you can type <code>V</code>. This command displays the current filter in the +minibuffer. The filter is specified as a Lisp expression, meaning that the +operators appear before their operands, not in between them. That is, <code>x and +y</code> is written as <code>(and x y)</code>.</p> + +<p>With a prefix argument (any prefix argument will do), the command <code>V</code> not +only displays the current filter, but also reapplies it. This can be useful +when you've made changes to the source database: Ebib does not +automatically update a virtual database when its source database is +modified.</p> + + + +<h4>Properties of Virtual Databases</h4> + +<p class="first">Virtual databases differ from normal databases in several ways. First, they +cannot be modified: you cannot add or delete entries, and you cannot modify +the contents of fields. It is also not possible to import entries to them +or merge another file with them. Furthermore, it is not possible to export +entries to them or from them.</p> + +<p>A virtual database cannot be saved in the normal way with <code>s</code>, and the +command <code>S</code> to save all databases ignores virtual databases. If you want to +save a virtual database, you can use the command <code>w</code>. This command not only +saves the virtual database, it also changes it into a normal database, and +detaches it from its original source database, so that you can modify it +without affecting the source database.</p> + +<p>The command <code>L</code> also doesn't work with virtual databases. The reason for this +is that the virtual database is not associated with an actual <code>.bib</code> file, so +there is no file to create a list of references from. However, it is +possible to use the command <code>P</code> with a virtual database to create a list of +entries. See <a href="#printing-database">Printing the Database</a>, for details on these two commands.</p> + + + + +<h3><a name="sec24" id="sec24"></a> +The Multiline Edit Buffer</h3> + +<p><a name="multiline-edit-buffer" id="multiline-edit-buffer"></a> +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 press <code>P</code> in +the index buffer, to edit the <code>@preamble</code> definition, when you hit <code>l</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 multiline edit buffer uses a special major mode, +<code>ebib-multiline-edit-mode</code>, which is derived from <code>text-mode</code>. The changes with +respect to <code>text-mode</code> are minor (see below), which means that any +customisations you may have made to <code>text-mode</code> will be available in the +multiline edit buffer.</p> + +<p>The settings that are specific for <code>ebib-multiline-edit-mode</code> are the +functions assigned to the key sequences <code>C-x b</code>, <code>C-x k</code> and <code>C-x C-s</code>. These key +sequences do not have their usual functions, but rather are redefined to +fit Ebib. Both <code>C-x b</code> and <code>C-x k</code> can be used to leave the multiline edit +buffer. <code>C-x b</code> will store the text as it is to the database, while <code>C-x k</code> +leaves the multiline edit buffer <em>without</em> storing the text, i.e., the +original value of the field or preamble that you were editing is +retained. If the text in the buffer was modified, <code>C-x k</code> asks you if you +really want to abandon your changes.</p> + +<p>If you leave the multitiline edit buffer with <code>C-x b</code> when the buffer is +empty (i.e., you deleted all the text, including the final newline), and +you were editing a field value or the <code>@preamble</code> definition, the field value +or preambleis 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.)</p> + +<p>The third command that is redefined in the multiline edit buffer is <code>C-x +C-s</code>. This command can be used to save the database. Because Ebib does not +do an autosave of the current database, it is advisable to save the +database manually every now and then to prevent data loss in case of +crashes. It would be annoying to have to leave the multiline edit buffer +every time you want to do this, so <code>C-x C-s</code> has been redefined to allow you +to do this from within the buffer.</p> + + + + +<h2><a name="sec25" id="sec25"></a> +The Ebib Buffers</h2> + +<p><a name="ebib-buffers" id="ebib-buffers"></a> +This chapter lists all the key commands that exist in Ebib, with a short +description and the actual command that they call. The latter information +is needed if you want to customise Ebib's key bindings. (See +<a href="#modifying-key-bindings">Modifying Key Bindings</a>.)</p> + + + +<h3><a name="sec26" id="sec26"></a> +The Index Buffer</h3> + +<dl> +<dt><strong><code>Up</code></strong></dt> +<dd>go to previous entry. <code>(ebib-prev-entry)</code></dd> + +<dt><strong><code>Down</code></strong></dt> +<dd>go to next entry. <code>(ebib-next-entry)</code></dd> + +<dt><strong><code>Right</code></strong></dt> +<dd>move to the next database. <code>(ebib-next-database)</code></dd> + +<dt><strong><code>Left</code></strong></dt> +<dd>move to the previous database. <code>(ebib-prev-database)</code></dd> + +<dt><strong><code>PgUp</code></strong></dt> +<dd>scroll the index buffer down. <code>(ebib-index-scroll-down)</code></dd> + +<dt><strong><code>PgDn</code></strong></dt> +<dd>scroll the index buffer up. <code>(ebib-index-scroll-up)</code></dd> + +<dt><strong><code>Home</code></strong></dt> +<dd>go to first entry. <code>(ebib-goto-first-entry)</code></dd> + +<dt><strong><code>End</code></strong></dt> +<dd>go to last entry. <code>(ebib-goto-last-entry)</code></dd> + +<dt><strong><code>Return</code></strong></dt> +<dd>make the entry under the cursor current. Use after e.g. <code>C-s</code>. +<code>(ebib-select-entry)</code></dd> + +<dt><strong><code>Space</code></strong></dt> +<dd>equivalent to <code>PgDn</code>.</dd> + +<dt><strong><code>1-9</code></strong></dt> +<dd>jump to the corresponding database.</dd> + +<dt><strong><code>/</code></strong></dt> +<dd>search the database. <code>(ebib-search)</code></dd> + +<dt><strong><code>&</code></strong></dt> +<dd>Create a virtual database, or perform a logical <code>and</code> on the current +virtual database. With negative prefix argument: apply a logical <code>not</code> to the +selectional criterion. <code>(ebib-virtual-db-and)</code></dd> + +<dt><strong><code>|</code></strong></dt> +<dd>Create a virtual database, or perform a logical <code>or</code> on the current +virtual database. With negative prefix argument: apply a logical <code>not</code> to the +selectional criterion. <code>(ebib-virtual-db-or)</code></dd> + +<dt><strong><code>~</code></strong></dt> +<dd>Perform a logical <code>not</code> on the current virtual +database. <code>(ebib-virtual-db-not)</code></dd> + +<dt><strong><code>a</code></strong></dt> +<dd>add an entry. <code>(ebib-add-entry)</code></dd> + +<dt><strong><code>b</code></strong></dt> +<dd>equivalent to <code>Pgup</code>.</dd> + +<dt><strong><code>c</code></strong></dt> +<dd>close the database. <code>(ebib-close-database)</code></dd> + +<dt><strong><code>C</code></strong></dt> +<dd>customise Ebib. <code>(ebib-customize)</code></dd> + +<dt><strong><code>d</code></strong></dt> +<dd>delete the current entry. <code>(ebib-delete-entry)</code></dd> + +<dt><strong><code>; d</code></strong></dt> +<dd>delete all marked entries.</dd> + +<dt><strong><code>e</code></strong></dt> +<dd>edit the current entry. <code>(ebib-edit-entry)</code></dd> + +<dt><strong><code>E</code></strong></dt> +<dd>edit the key of the current entry. <code>(ebib-edit-keyname)</code></dd> + +<dt><strong><code>f</code></strong></dt> +<dd>extract a filename from the <code>file</code> field and send it to an +appropriate viewer. With numeric prefix argument, extract the <em>n</em>-th +filename.</dd> + +<dt><strong><code>F</code></strong></dt> +<dd>follow <code>crossref</code> field. <code>(ebib-follow-crossref)</code></dd> + +<dt><strong><code>g</code></strong></dt> +<dd>equivalent to <code>Home</code>.</dd> + +<dt><strong><code>G</code></strong></dt> +<dd>equivalent to <code>End</code>.</dd> + +<dt><strong><code>H</code></strong></dt> +<dd>show/hide hidden fields. <code>(ebib-toggle-hidden)</code></dd> + +<dt><strong><code>j</code></strong></dt> +<dd>equivalent to <code>Down</code>.</dd> + +<dt><strong><code>J</code></strong></dt> +<dd>jump to another database. This accepts a numeric prefix argument, +but will ask you for a database number if there is +none. <code>(ebib-switch-to-database)</code></dd> + +<dt><strong><code>k</code></strong></dt> +<dd>equivalent to <code>Up</code>.</dd> + +<dt><strong><code>l</code></strong></dt> +<dd>show the log buffer. (<code>ebib-show-log</code>)</dd> + +<dt><strong><code>L</code></strong></dt> +<dd>create a LaTeX file from the current database that produces a list +of references formatted by BibTeX. <code>(ebib-latex-database)</code></dd> + +<dt><strong><code>; L</code></strong></dt> +<dd>create a LaTeX file with the marked entries only.</dd> + +<dt><strong><code>m</code></strong></dt> +<dd>mark (or unmark) the current entry. <code>(ebib-mark-entry)</code></dd> + +<dt><strong><code>; m</code></strong></dt> +<dd>unmark all marked entries.</dd> + +<dt><strong><code>M</code></strong></dt> +<dd>merge a <code>.bib</code> file. <code>(ebib-merge-bibtex-file)</code></dd> + +<dt><strong><code>n</code></strong></dt> +<dd>find next occurrence of the search string. <code>(ebib-search-next)</code></dd> + +<dt><strong><code>N</code></strong></dt> +<dd>search for entries cross-referencing the current one. <code>(ebib-search-crossref)</code></dd> + +<dt><strong><code>C-n</code></strong></dt> +<dd>equivalent to <code>Down</code>.</dd> + +<dt><strong><code>M-n</code></strong></dt> +<dd>equivalent to <code>PgDn</code>.</dd> + +<dt><strong><code>o</code></strong></dt> +<dd>open a <code>.bib</code> file. <code>(ebib-load-bibtex-file)</code></dd> + +<dt><strong><code>p</code></strong></dt> +<dd>push an entry to a LaTeX buffer <code>(ebib-push-bibtex-key)</code></dd> + +<dt><strong><code>; p</code></strong></dt> +<dd>push the marked entries to a LaTeX buffer.</dd> + +<dt><strong><code>C-p</code></strong></dt> +<dd>equivalent to <code>Up</code>.</dd> + +<dt><strong><code>M-p</code></strong></dt> +<dd>equivalent to <code>PgUp</code>.</dd> + +<dt><strong><code>P</code></strong></dt> +<dd>create a LaTeX file for printing the database, listing the entire +contents of each entry. <code>(ebib-print-database)</code></dd> + +<dt><strong><code>; P</code></strong></dt> +<dd>create a LaTeX file with the marked entries.</dd> + +<dt><strong><code>r</code></strong></dt> +<dd>show and edit the <code>@preamble</code> definition in the +database. <code>(ebib-edit-preamble)</code></dd> + +<dt><strong><code>q</code></strong></dt> +<dd>quit Ebib. This sets all variables to nil, unloads the database(s) +and quits Ebib. <code>(ebib-quit)</code></dd> + +<dt><strong><code>s</code></strong></dt> +<dd>save the database. <code>(ebib-save-current-database)</code></dd> + +<dt><strong><code>S</code></strong></dt> +<dd>save all modified databases. <code>(ebib-save-all-databases)</code></dd> + +<dt><strong><code>t</code></strong></dt> +<dd>show and edit the <code>@string</code> definitions in the +database. <code>(ebib-edit-strings)</code></dd> + +<dt><strong><code>u</code></strong></dt> +<dd>extract a URL from the <code>url</code> field and send it to a browser. With +numeric prefix argument, extract the <em>n</em>-th url.</dd> + +<dt><strong><code>V</code></strong></dt> +<dd>Display the filter of the current virtual database in the +minibuffer. With prefix argument: reapply the filter. <code>(ebib-print-filter)</code></dd> + +<dt><strong><code>w</code></strong></dt> +<dd>write the database to a different file. <code>(ebib-write-database)</code></dd> + +<dt><strong><code>x</code></strong></dt> +<dd>export the current entry to a file, or, when used with numeric +prefix argument, to another database. <code>(ebib-export-entry)</code></dd> + +<dt><strong><code>; x</code></strong></dt> +<dd>export the marked entries to a file, or, when used with a numeric +prefix argument, to another database.</dd> + +<dt><strong><code>C-x b</code></strong></dt> +<dd>equivalent to <code>z</code>.</dd> + +<dt><strong><code>C-x k</code></strong></dt> +<dd>equivalent to <code>q</code>.</dd> + +<dt><strong><code>X</code></strong></dt> +<dd>export the <code>@preamble</code> definition to a file or, when used with a +numeric prefix argument, to another database. <code>(ebib-export-preamble)</code></dd> + +<dt><strong><code>z</code></strong></dt> +<dd>move focus away from the Ebib windows. <code>(ebib-leave-ebib-windows)</code></dd> + +<dt><strong><code>Z</code></strong></dt> +<dd>put Ebib in the background. <code>(ebib-lower)</code></dd> +</dl> + +<p>One function is not bound to any key: <code>ebib-print-filename</code>.</p> + + +<h3><a name="sec27" id="sec27"></a> +The Entry Buffer</h3> + +<dl> +<dt><strong><code>Up</code></strong></dt> +<dd>go to the previous field. <code>(ebib-prev-field)</code></dd> + +<dt><strong><code>Down</code></strong></dt> +<dd>go to the next field. <code>(ebib-next-field)</code></dd> + +<dt><strong><code>PgUp</code></strong></dt> +<dd>go to the previous set of fields. <code>(ebib-goto-prev-set)</code></dd> + +<dt><strong><code>PgDn</code></strong></dt> +<dd>go to the next set of fields. <code>(ebib-goto-next-set)</code></dd> + +<dt><strong><code>Home</code></strong></dt> +<dd>go to the first field. <code>(ebib-goto-first-field)</code></dd> + +<dt><strong><code>End</code></strong></dt> +<dd>go to the last field. <code>(ebib-goto-last-field)</code></dd> + +<dt><strong><code>Space</code></strong></dt> +<dd>equivalent to <code>PgDn</code>.</dd> + +<dt><strong><code>b</code></strong></dt> +<dd>equivalent to <code>PgUp</code>.</dd> + +<dt><strong><code>c</code></strong></dt> +<dd>copy the contents of the current field to the kill +ring. <code>(ebib-copy-field-contents)</code></dd> + +<dt><strong><code>d</code></strong></dt> +<dd>delete the value of the current field. The deleted contents will <em>not</em> +be put in the kill ring, and is therefore irretrievably +lost. <code>(ebib-delete-field-contents)</code></dd> + +<dt><strong><code>e</code></strong></dt> +<dd>edit the current field. <code>(ebib-edit-fields)</code></dd> + +<dt><strong><code>f</code></strong></dt> +<dd>extract a filename from the current field and send it to an +appropriate viewer. With numeric prefix argument, extract the <em>n</em>-th +filename.</dd> + +<dt><strong><code>g</code></strong></dt> +<dd>equivalent to <code>Home</code>.</dd> + +<dt><strong><code>G</code></strong></dt> +<dd>equivalent to <code>End</code>.</dd> + +<dt><strong><code>j</code></strong></dt> +<dd>go to the next field. <code>(ebib-next-field)</code></dd> + +<dt><strong><code>k</code></strong></dt> +<dd>go to the previous field. <code>(ebib-prev-field)</code></dd> + +<dt><strong><code>l</code></strong></dt> +<dd>edit the current field as multiline. <code>(ebib-edit-multiline-field)</code></dd> + +<dt><strong><code>C-n</code></strong></dt> +<dd>equivalent to <code>Down</code>.</dd> + +<dt><strong><code>M-n</code></strong></dt> +<dd>equivalent to <code>PgDn</code>.</dd> + +<dt><strong><code>C-p</code></strong></dt> +<dd>equivalent to <code>Up</code>.</dd> + +<dt><strong><code>M-p</code></strong></dt> +<dd>equivalent to <code>PgUp</code>.</dd> + +<dt><strong><code>q</code></strong></dt> +<dd>quit editing the current entry and return focus to the index +buffer. <code>(ebib-quit-entry-buffer)</code></dd> + +<dt><strong><code>r</code></strong></dt> +<dd>toggle a field's ``raw'' status. <code>(ebib-toggle-raw)</code></dd> + +<dt><strong><code>s</code></strong></dt> +<dd>insert an abbreviation from the <code>@string</code> definitions in the +database. <code>(ebib-insert-abbreviation)</code></dd> + +<dt><strong><code>u</code></strong></dt> +<dd>extract a URL from the current field and send it to a browser. With +numeric prefix argument, extract the <em>n</em>-th url.</dd> + +<dt><strong><code>x</code></strong></dt> +<dd>cut the contents of the current field. Like <code>c</code>, <code>x</code> puts the contents +of the current field in the kill ring. <code>(ebib-cut-field-contents)</code></dd> + +<dt><strong><code>y</code></strong></dt> +<dd>yank the last element in the kill ring to the current +field. Repeated use of <code>y</code> functions like <code>C-y/M-y</code>. Note that no text will be +yanked if the field already has a value. <code>(ebib-yank-field-contents)</code></dd> +</dl> + + + +<h3><a name="sec28" id="sec28"></a> +The Strings Buffer</h3> + +<dl> +<dt><strong><code>Up</code></strong></dt> +<dd>go to the previous string. <code>(ebib-prev-string)</code></dd> + +<dt><strong><code>Down</code></strong></dt> +<dd>go to the next string. <code>(ebib-next-string)</code></dd> + +<dt><strong><code>PgUp</code></strong></dt> +<dd>go ten strings up. <code>(ebib-strings-page-up)</code></dd> + +<dt><strong><code>PgDn</code></strong></dt> +<dd>go ten strings down. <code>(ebib-strings-page-down)</code></dd> + +<dt><strong><code>Home</code></strong></dt> +<dd>go to the first string. <code>(ebib-goto-first-string)</code></dd> + +<dt><strong><code>End</code></strong></dt> +<dd>go to the last string. <code>(ebib-goto-last-string)</code></dd> + +<dt><strong><code>Space</code></strong></dt> +<dd>equivalent to <code>PgDn</code>.</dd> + +<dt><strong><code>a</code></strong></dt> +<dd>add a new <code>@string</code> definition. <code>(ebib-add-string)</code></dd> + +<dt><strong><code>b</code></strong></dt> +<dd>equivalent to <code>PgUp</code>.</dd> + +<dt><strong><code>c</code></strong></dt> +<dd>copy the text of the current string to the kill +ring. <code>(ebib-copy-string-contents)</code></dd> + +<dt><strong><code>d</code></strong></dt> +<dd>delete the current <code>@string</code> definition from the database. You will be +asked for confirmation. <code>(ebib-delete-string)</code></dd> + +<dt><strong><code>e</code></strong></dt> +<dd>edit the value of the current string. <code>(ebib-edit-string)</code></dd> + +<dt><strong><code>g</code></strong></dt> +<dd>equivalent to <code>Home</code>.</dd> + +<dt><strong><code>G</code></strong></dt> +<dd>equivalent to <code>End</code>.</dd> + +<dt><strong><code>j</code></strong></dt> +<dd>equivalent to <code>Down</code>.</dd> + +<dt><strong><code>k</code></strong></dt> +<dd>equivalent to <code>Up</code>.</dd> + +<dt><strong><code>l</code></strong></dt> +<dd>edit the value of the current string as +multiline. <code>(ebib-edit-multiline-string)</code></dd> + +<dt><strong><code>C-n</code></strong></dt> +<dd>equivalent to <code>Down</code>.</dd> + +<dt><strong><code>M-n</code></strong></dt> +<dd>equivalent to <code>PgDn</code>.</dd> + +<dt><strong><code>C-p</code></strong></dt> +<dd>equivalent to <code>Up</code>.</dd> + +<dt><strong><code>M-p</code></strong></dt> +<dd>equivalent to <code>PgUp</code>.</dd> + +<dt><strong><code>q</code></strong></dt> +<dd>quit the strings buffer and return focus to the index +buffer. <code>(ebib-quit-strings-buffer)</code></dd> + +<dt><strong><code>x</code></strong></dt> +<dd>export the current <code>@string</code> definition to a file or, when used with a +prefix argument, to another database. <code>(ebib-export-string)</code></dd> + +<dt><strong><code>X</code></strong></dt> +<dd>export all the <code>@string</code> definitions to a file or, when used with a +prefix argument, to another database. <code>(ebib-export-all-strings)</code></dd> +</dl> + + + + +<h2><a name="sec29" id="sec29"></a> +Customisation</h2> + +<p><a name="customisation" id="customisation"></a> +Ebib can be customised through Emacs' standard customisation interface. The +only thing that cannot be customised in this way are the key bindings. If +you wish to customise those, you have to use the file <code>~/.ebibrc</code>.</p> + + +<h3><a name="sec30" id="sec30"></a> +The Customisation Buffer</h3> + +<p><a name="customisation-buffer" id="customisation-buffer"></a> +Ebib's customisation group is a subgroup of the <code>Tex</code> group. It can be +invoked by typing <code>M-x customize-group RET ebib RET</code>, or by pressing <code>C</code> in +the index buffer. This chapter gives a short description of all the options +available in the customisation buffer.</p> + + +<h4>Default Type</h4> + +<p class="first">The default type is the default entry type given to a new entry. Every +entry in the Ebib database must have a type, because the type defines which +fields are available. When a new entry is created, Ebib gives it a default +type, which can be customised through this option. The standard value is +<code>article</code>.</p> + + + +<h4>Preload Bib Files</h4> + +<p><a name="preload-bib-files" id="preload-bib-files"></a> +This option allows you to specify which file(s) Ebib is to load when it +starts up. Specify one file per line, press the <code>INS</code> button to add more +files. You can complete a partial filename with <code>M-TAB</code>.</p> + + + +<h4>Additional Fields</h4> + +<p><a name="additional-fields" id="additional-fields"></a> +The additional fields are those fields that are available for all entry +types, and which BibTeX generally ignores. This option allows you to +specify which additional fields you wish to use in your database. Specify +one field per line, press the <code>INS</code> button to add more fields.</p> + +<p>By default, the following additional fields are defined: <code>crossref, url, +annote, abstract, keywords, file</code> and <code>timestamp</code>.</p> + + + +<h4>Layout</h4> + +<p><a name="layout" id="layout"></a> +The default value of this option is <code>full</code>, which means that Ebib takes over +the entire frame when it runs. Alternatively, you can select to specify a +width (in characters) yourself, in which case Ebib takes up the right part +of the frame, leaving the left part free. See <a href="#screen-layout">Screen Layout</a> for details.</p> + + + + +<h4>Index Window Size</h4> + +<p class="first">This option lets you specify the size of the index window at the top of the +Ebib screen. The default value is 10.</p> + + + +<h4>Index Display Fields</h4> + +<p><a name="index-display-fields" id="index-display-fields"></a> +This option allows you to specify fields that should be displayed next to +the entry key in the index buffer. By default, the index buffer only shows +the key of each entry, but if this is too little information, you can use +this option to display e.g. the title of each entry as well.</p> + + + +<h4>Insertion Commands</h4> + +<p><a name="insertion-commands" id="insertion-commands"></a> +With the command <code>ebib-insert-bibtex-key</code> or with the command key <code>p</code> in the index +buffer, you can insert a BibTeX key into a LaTeX buffer. This option allows you +to define the commands that are available through tab completion when these +functions ask for a citation command.</p> + +<p>The citation commands must be given <em>without</em> the leading backslash, as Ebib adds one. +Furthermore, you need to specify how many optional arguments each command can +have. When Ebib prompts you for a citation key, it will ask for as many optional +arguments as you specify here. (If you don't want to be asked for those optional +arguments, just fill in 0.)</p> + +<p>When Ebib prompts you for a citation command, the commands specified in this +option can be obtained through tab completion. However, it is not necessary to +fill in a command from this list here. You can also enter another command (in +which case Ebib asks for exactly one optional argument) or even no command at +all. In the latter case, Ebib does not ask for any optional arguments and simply +puts the key in the buffer without adding a backslash or curly braces.</p> + + + + +<h4>Sort Order</h4> + +<p class="first">The use of this option is explained above, see <a href="#sorting-bib-file">Sorting the .bib file</a>. To +create a sort order, click the <code>INS</code> button to create a sort level, and then +click the <code>INS</code> button under that sort level to enter a sort field. If you +want to add more than one sort field to the sort level, simply hit <code>INS</code> +again.</p> + + + +<h4>Save Xrefs First</h4> + +<p><a name="save-xrefs-first" id="save-xrefs-first"></a> +For cross-referencing to work, the cross-referencing entries must appear in +the <code>.bib</code> file <em>before</em> the cross-referenced entries. In order to tell Ebib to +save all entries with a <code>crossref</code> field first, you must set the option <code>Save +Xrefs First</code> in Ebib's customisation buffer. With this option set, BibTeX's +crossreferencing options work as intended.</p> + +<p>By default, this option is unset, because it (marginally) slows down saving +the <code>.bib</code> file somewhat.</p> + + + +<h4>Crossref Face</h4> + +<p><a name="crossref-face" id="crossref-face"></a> +Field values inherited from a cross-referenced entry are marked with this +face. By default, the face has red as foreground colour.</p> + + + +<h4>Marked Face</h4> + +<p><a name="marked-face" id="marked-face"></a> +When entries are marked (with <code>m</code>), they are highlighted in this face. By +default, GNU Emacs uses the text property <code>highlight</code>. XEmacs only allows +this on terminals, therefore it displays marked entries with a red +background and a white foreground colour. This option allows you to change +these defaults.</p> + + + +<h4>Use Timestamp</h4> + +<p class="first">If this option is set, Ebib will add a <code>timestamp</code> field to every new entry, +recording the date and time it was added to the database. See <a href="#timestamps">Timestamps</a>.</p> + + + +<h4>Timestamp Format</h4> + +<p class="first">This option specifies the format string that is used to create the +timestamp. The format string is used by <code>format-time-string</code> to create a time +representation. The default value is <code>"%a %b %e %T %Y"</code>, which produces a +timestamp of the form <code>"Mon Mar 12 01:03:26 2007"</code>. See the documentation for +<code>format-time-string</code> for the forms that the format string can take.</p> + + + +<h4>Standard Url Field</h4> + +<p><a name="standard-url-field" id="standard-url-field"></a> +This is the field that Ebib searches for URLs if you press <code>u</code> in the index +buffer. Its default value is <code>url</code>.</p> + + + +<h4>Url Regexp</h4> + +<p><a name="url-regexp" id="url-regexp"></a> +This is the regular expression that Ebib uses to search for URLs in a +field. The default value is:</p> + +<pre class="example"> +\\url{\(.*\)}\|https?://[^ '<>\"\n\t\f]+ +</pre> + +<p>With this regular expression, Ebib considers everything that is in a LaTeX +<code>\url{...}</code> command as a URL, and furthermore every string of +text that starts with <code>http://</code> or <code>https://</code> and does not contain whitespace +or one of the characters <code>' " <</code> or <code>></code>.</p> + + + +<h4>Browser Command</h4> + +<p><a name="browser-command" id="browser-command"></a> +If this option is unset (which is the default), Ebib uses the Emacs +function <code>browse-url</code> to start a browser. If this function does not exist, +you can set this option. For example, if you use the Firefox browser, set +this option to <code>firefox</code>.</p> + +<p>For this to work, the browser that you use must be able to handle a URL on +the command line.</p> + + + +<h4>Standard File Field</h4> + +<p><a name="standard-file-field" id="standard-file-field"></a> +This is the field that Ebib searches for filenames if you press <code>f</code> in the +index buffer. Its default value is <code>file</code>.</p> + + + +<h4>File Associations</h4> + +<p><a name="file-associations" id="file-associations"></a> +The programs used to view files. By default, programs for <code>.pdf</code> and <code>.ps</code> +files are specified, which should be available on most linux systems. If +you prefer other programs or are running on Windows, you'll can specify +them here. Note that Ebib searches the PATH for the programs, but you can +also specify full path names. Of course, it is also possible to add new +associations.</p> + +<p>Note that GNU/Emacs 23 (as yet unreleased) comes with <code>doc-view-mode</code>, which +provides a way to view <code>.pdf</code> and <code>.ps</code> files inside Emacs. (The files are +converted to <code>.png</code> format first.) If you prefer to use this mode, simply +leave the program field blank for the relevant file type.</p> + + + +<h4>File Regexp</h4> + +<p><a name="file-regexp" id="file-regexp"></a> +In order to find files in a field, Ebib uses a regular expression. The +default value is:</p> + +<pre class="example"> + [^?|\:*<>\" \n\t\f]+ +</pre> + +<p>This essentially means that every string of characters not containing any +of the characters</p> + +<pre class="example"> +? | \ : * < > " +</pre> + +<p>or space, newline, tab of formfeed. URLs can easily by recognised by the +prefix <code>http:</code>, but recognising files is not so straightforward. It is +therefore not advisable to put anything but filenames in the <code>file</code> field.</p> + + + +<h4>File Search Dirs</h4> + +<p><a name="file-search-dirs" id="file-search-dirs"></a> +This is the list of directories that Ebib searches for files. Note that +searching is not recursive: only the files listed here are searched, not +their subdirectories.</p> + + + +<h4>Print Preamble</h4> + +<p class="first">This option specifies the preamble that is to be added to the LaTeX file +Ebib creates for printing the database (i.e., the <code>P</code> command). By default, +the preamble is empty. You can set your own <code>\usepackage</code> +commands, or anything else you may need.</p> + + + +<h4>Print Multiline</h4> + +<p class="first">When this options is set, Ebib includes multiline field values when it +creates a LaTeX file with <code>P</code> (<code>ebib-print-database</code>). When unset, multiline +values are excluded, which saves space. By default, this option is unset.</p> + + + +<h4>Latex Preamble</h4> + +<p class="first">This option specifies the preamble to be added to the LaTeX file for +creating a list of references from the database (i.e., the <code>L</code> command). By +default, the line <code>\bibliographystyle{plain}</code> is put in the +preamble, but you may want to specify your own BibTeX packages and options.</p> + + + +<h4>Print Tempfile</h4> + +<p class="first">This option specifies the name and location of the temporary file Ebib +creates with the commands <code>ebib-print-database</code> and +<code>ebib-latex-database</code>. By default, this option has no value, +which means that Ebib will ask for a filename each time either of these +commands is called.</p> + + + +<h4>Allow Identical Fields</h4> + +<p><a name="allow-identical-fields" id="allow-identical-fields"></a> +If this option is set, Ebib stores the values of multiple occurrences of a +single field within an entry in a single occurrence of that field, +separated by semicolons. By default, this option is unset, because it slows +down the loading of <code>.bib</code> files. See <a href="#multiple-identical-fields">Multiple Identical Fields</a>.</p> + + + +<h4>Entry Types</h4> + +<p><a name="entry-types" id="entry-types"></a> +This option allows you to customise the entry types that Ebib uses. Each +entry type has a name, a set of obligatory fields and a set of optional +fields. You can add, alter or delete single fields in an entry type, or +whole entry types.</p> + +<p>If you want to add an entry type, hit the <code>INS</code> key on the top level and give +the new entry a name, then add obligatory and/or optional fields. It is not +necessary that an entry type has both obligatory and optional fields, you +can define an entry that has only obligatory or only optional fields.</p> + + + + +<h3><a name="sec31" id="sec31"></a> +Modifying Key Bindings</h3> + +<p><a name="modifying-key-bindings" id="modifying-key-bindings"></a> +If you are unhappy about Ebib's standard key bindings, you can change them +to anything you like. To do this, you have to create a file <code>~/.ebibrc</code> and +write your preferred key bindings in it. A key binding definition is built +up as follows:</p> + +<pre class="example"> +(ebib-key <buffer> <key> <command>) +</pre> + +<p><code><buffer></code> is either <code>index</code>, <code>entry</code> or <code>strings</code>, for the corresponding +buffer. <code><key></code> is a standard Emacs key description, and <code><command></code> is the +Ebib command to be associated with the key. The commands that can be used +here are listed in <a href="#ebib-buffers">The Ebib Buffers</a>. Note that it is possible to bind more +than one key to a single function: just add as many <code>ebib-key</code> statements as +necessary.</p> + +<p>As an example, the following binds <code>C-s</code> to <code>ebib-search</code> in the index buffer, +so that the database can be searched with <code>C-s</code> as well as with <code>/</code>:</p> + +<pre class="example"> +(ebib-key index "\C-s" ebib-search) +</pre> + +<p>If you want to unbind a key, you can simply leave out <code><command></code>. So if you +want to bind the command <code>ebib-delete-entry</code> to <code>D</code> rather than <code>d</code>, you need to +put the following in <code>.ebibrc</code>:</p> + +<pre class="example"> +(ebib-key index "D" ebib-delete-entry) +(ebib-key index "d") +</pre> + +<p>The first line binds <code>D</code> to the command <code>ebib-delete-entry</code>. The second line +unbinds <code>d</code>.</p> + +<p>If a command can be called with a prefix key (as for example +<code>ebib-delete-entry</code> can), <code>ebib-key</code> will automatically rebind the prefixed +version as well. So in the example above, the first line not only binds <code>D</code>, +it also binds <code>; D</code>. Similarly, the second line not only unbinds <code>d</code>, but also +<code>; d</code>.</p> + +<p>It is also possible to redefine the prefix key itself. To do this, you must +specify <code>mark-prefix</code> for <code><buffer></code>. The value of <code><command></code> is irrelevant +here, so it can be left out:</p> + +<pre class="example"> +(ebib-key mark-prefix ":") +</pre> + +<p>This sets up <code>:</code> as the new prefix key. Doing this automatically unbinds the +existing prefix key.</p> + +</div> + + + + +<!-- Page published by Emacs Muse ends here --> + </body> +</html> |