====== JabRef - reference management ======

A guide about how to manage scientific references efficiently by creating a [[https://en.wikipedia.org/wiki/BibTeX/|BibTeX]] database in [[http://www.jabref.org/|JabRef]].  The JabRef source code can be downloaded from [[https://github.com/JabRef/jabref/releases|JabRef Github Releases]] while a Windows installer is available at [[http://sourceforge.net/projects/jabref/files/v3.2/|JabRef Sourceforge]].

{{ :devel:jabref:download.png?direct&600 }}


===== What is JabRef? =====

JabRef is an //open source bibliography reference manager//. The native file format used by JabRef is //BibTeX//, the standard LaTeX bibliography format. JabRef runs on the //Java VM// (version 1.8 or newer), and should work equally well on Windows, Linux and Mac OS X.


===== Why JabRef? =====

  * **Efficient reference management**: usually PDF references are saved in different folders indicating the topic of the article.  For instance, all the articles about Topic 1 are saved in a folder called Topic 1 and all the articles about Topic 2 in a folder called Topic 2.  References about Topic 1 and Topic 2 at the same time, would therefore have to be duplicated.  In JabRef, keywords, like Topic 1 and Topic 2, are simply added to the respective entry in the BibTeX database and the references can be searched for them; therefore no duplicates have to exist.  Besides adding these keywords, more //properties//, like the author, the read-status, ranking, ... can be added to each reference.  Hence, it is possible to //search// for much more information than simply the file name in the classical "folder/file" management structure.

  * **Easy BibTeX file editing**: references are commonly saved in the BibTeX file format to include them in a LaTeX document.  Theses files can easily become difficult to read and to edit because of their length.  JabRef simplifies this task by offering a clear //graphical user interface//.

  * **Free of charge**: unlike Mendeley, EndNote, RefWorks, Zotero, Citavi, ... JabRef is //free of charge//.

  * **Open source**: the JabRef source code is available at [[https://github.com/JabRef/jabref|JabRef Source Code]].

  * **Operating system independence**: since JabRef is written in Java, it can be run on any operating system, which supports the Java Virtual Machine, i.e. almost any OS.

  * **Service independence**: due to the fact that the whole database can be stored in a BibTeX file, all the information is always entirely available in one single file.  If one wants to work on a different computer, only this file is needed.  More importantly, the database is independent of sudden price raises or storage limitations of commercial alternatives.

  * **Direct link to references**: references files, e.g. articles in the PDF file format, can be opened from JabRef.  Hence, it is not necessary to spend much time searching for a specific file in the Explorer.


===== How to organize references? =====

A number of commercial reference managers operate as a //cloud service// to make your references available from anywhere.  This service can be emulated by storing the reference files and the BibTeX database in a //Dropbox// folder.  If Dropbox is not available, the reference files and the BibTex database can simply be stored in a usual folder.

{{ :devel:jabref:reference_organization.png?direct&600 }}

<note tip> It might be interesting to use the following naming syntax of reference files, like PDF articles: "Name of the first author + date of publication", e.g. Monaghan1992.  If the authour published several articles in the same year, simply add "b", "c", ..., e.g. Monaghan1992, Monaghan1992b, Monaghan1992c, ... Using the letter "a" for the first article of an author in the same year is an unnecessary burden since more than one article of the same first author in the same year is rather rare. </note>


===== How to use JabRef? =====

In this section, it will be explained how to create the database, how to include references to the BibTex file, how to cite references, how to create groups of topics and how to add additional properties.


==== Creating the database ====

A new database is simply created by clicking on ''File->New Database''.  Make sure that the database encoding is //UTF-8//, i.e. the most widely used character encoding, by clicking on ''File->Database properties'' and by selecting ''UTF-8'' in the ''Database encoding'' field.


==== Including references ====

References can mainly be included in two different ways: either the BibTeX file of the reference is directly downloaded from the //online database//, like ScienceDirect, Springer, … or the reference is added //manually//.


=== Including references from online databases ===

{{ :devel:jabref:sciencedirect.png?direct&600 }}

In this first case, the BibTeX file is downloaded from the website as shown in the previous picture.  Notice that the abstract can also be added.  This file is then opened in JabRef, the entry is copied and then pasted in the full database.  Usually, the BibTeX format is not entirely coherent in auto-generated files downloaded from the internet.  For this reason, some modifications have to be applied by opening the entry editor in JabRef.  As shown in the following picture, the modifications can be made by working directly on the BibTeX source.  This window is opened by double-clicking on the reference.  The different properties can, however, also be changed individually by modifing the values in the other tabs, like the ''Required fields'' tab.  


{{ :devel:jabref:editor.png?direct&600 }}

The following modifications are usually applied:

  * **Key**: the key property is the value, which follows the document identifier, i.e. ''Antoci2007'' in the previous picture, and which is used in the LaTeX document to cite the reference.  The key should ideally have the following format "Name of the first author + date of publication", which is followed by "b", "c", ... if the author wrote several articles in the same year, as explained earlier.

<note tip> It is also possible to create the keys automatically in JabRef by clicking on ''Tools->Autogenerate BibTeX Keys''. </note>

  * **Author**: if the authors are "James Joseph Rich, John Johnson and David Piana", the corresponding BibTeX entry should satisfy the following format: "Rich, J.~J. and Johnson, J. and Piana, D.".  Notice the tilde-symbol between J. and J.  This might be necessary to tell BibTeX that the name of the first author does not end after the first dot.

  * **File**: remember that we previously suggested to save the references, like PDF articles, in the same folder than the BibTeX data base.  This file can be linked to the database in the ''File'' field of the ''General'' tab by a relative path.  It can then be opened by clinking on the corresponding Adobe icon, as shown below.

{{ :devel:jabref:file.png?direct&600 }}

  * **Clean**: finally, to make sure that all the BibTeX style constraints are satisfied, click on ''Tools->Cleanup entries''.

<note tip> If you do not want to have your PDF references renamed, uncheck the corresponding option in the pop-up menu, which appears after clicking on ''Tools->Cleanup entries''. </note>


=== Including references manually ===

References are included //manually// by clicking on the ''New BibTeX'' entry button (see picture below).  The entry type is then selected in the pop-up menu and the different fields are filled out.  It might be interesting to respect the guidelines of the previous section, i.e. to use a standardized key and author format, to add a link to the corresponding PDF reference, ...

{{ :devel:jabref:add_manually.png?direct&600 }}


==== Citing references ====

//Citing references// in LaTeX is simplified by JabRef since the reference keys have not to be extracted manually.  In fact, the corresponding references can be selected and a right click makes it possible to ''Copy \cite{BibTeX key}''.  The clipboard then contains the citing command with the respective keys, which can be pasted in the LaTeX document.


==== Creating groups ====

Besides searching references by the //search bar//, they can be classified in //groups// based on keywords.  This feature eliminates the need to duplicate articles in a "file/folder" structure, if a references is relevant two multiple different domains.  Groups are created by clicking on ''Groups->Toogle groups interface'' and then on ''+'' in the Groups menu.  A group based on keywords is created by selecting the ''Dynamically group entries by searching a field for a keyword'' option.


==== Additional properties ====

Additional properties can be associated with a reference, like a //rating// variable, a //not-printed/printed// boolean or a //not read/skimmed/read// indicator, … These options are available at ''Options->Preferences->Entry table columns''.