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