Introduction to Referencer

Overview

Referencer is a tool to help you manage your collection of documents, and to use them to generate a bibliography. It is designed with the scientist/researcher in mind, and "document" may be taken to mean "paper" in general, although Referencer can deal with any kind of document that BibTeX can.

At it's most basic, Referencer may be used for editing your documents and bibliography data (library). However, it also includes useful time-saving features. Chief amongst these is the automatic acquisition of bibliographic information (metadata) for some kinds of document. When you add a PDF file to your Referencer library, it will automatically be searched for key identifiers such as a DOI code or arXiv identifier. If either of these is found, Referencer uses your internet connection to retrieve the metadata for the document. If you've got a collection of already-downloaded PDFs of papers, this can save you a lot of typing!

Referencer also uses its knowledge of papers to provide handy functions such as opening the web page associated with the article, or opening the document itself. Additionally, you can attach tags to documents to catgorise them, and then browse documents more easily by filtering them by tag.

Referencer is intended to be extremely user-friendly, but to help you get up and running as smoothly as possible, the following sections explain how to use Referencer in more detail.

How do I...

use Referencer with BibTeX?

Referencer maintains its own library of your documents, rather than loading and editing a BibTeX file. As such, when you're ready to use your library in your LaTeX document, you can have Referencer generate a BibTeX file (Library->Export to BibTeX). By default this will include all documents in your library: if you would rather only export some documents then you can use the Selection: field in the export dialog to restrict the export to certain documents. Rather than repeatedly exporting when you make changes, you can tell Referencer to write the BibTeX file every time you change your library (Library->Manage BibTeX File).

Referencer will automatically handle conversion of special characters (e.g. ß) to their LaTeX equivalents (e.g. \ss). Depending on the BibTeX style you are using in your work, capitalisation of text in your latex output may differ from that in your Referencer library. This is to allow publishers to impose their own capitalisation schemes. If you want text to be capitalised in your work exactly as it is in your library, then you can use the Protect capitalization option in the BibTeX export dialog.

If you already have a BibTeX file, you can import it into Referencer (Library->Import...). Importing and then exporting a bibtex file is not guaranteed (or intended) to produce exactly the same file as went in: Referencer is not a BibTeX editor. Information such as document filenames and tags is not included in BibTeX files. You should always use your Referencer library file as the authoritative copy.

add documents?

• By file/folder: Documents->Add File...
  If you have some document files you'd like Referencer to know about, you can add one or more files, or a whole folder (Documents->Add Folder..), and Referencer will create entries for each file. PDF files will be read, and Referencer will do its best to fill out the metadata for you.

  Note: when adding a folder of files, files named ".svn", "CVS", files with the extension ".bib" or ".reflib" and files with names starting "." are automatically skipped. These files can still be added individually.

• By DOI code: Documents->Add Document with DOI...
  If you have the DOI code for a paper, you can save yourself the effort of inputting its metadata by simply giving Referencer the DOI and letting it look up the metadata for you.

• By hand: Documents->Add Empty Reference...
  As a last resort, Referencer provides a simple interface for manually creating a document and inputting metadata. A document with no information is created, and the properties window is opened for you to enter a name for the document and some metadata.

• From a BibTeX/EndNote/Refer file: Library->Import...
  Your existing bibliography files, or snippets from websites can be imported. Items from these files will be loaded and added to the currently open library.

• By copy/paste: Edit->Paste BibTeX
  To conveniently import references from the web, or particular references from an existing BibTeX file, you can simply copy and past BibTeX markup into referencer, where these references will be added as if you had imported them from a file.

use different document types/fields?

Referencer's user interface is optimised for dealing with scientific papers. As such, the document type is "Article" by default and fields such as Title, Authors, Journal and Volume are shown. Other types of document may be selected in the properties window (Documents->Properties...). If you don't see the BibTeX type you want, simply type it in and it will be passed through verbatim when exporting to your BibTeX file. Some document types may require additional metadata fields, for example "Book" documents should have an "Editor" field. You can add this by expanding the Extra Fields section of the properties window, and clicking the New icon. To enter some data into your new field, select it and click the Edit icon.

Tagging and Searching

Tagging allows you to categorise your documents. Unlike a traditional hierarchical directory type organisation, a tag-based system allows a document to belong to multiple overlapping categories. For instance, you might have tags called "Physics" and "Biology", and another called "Exciting papers". If these were directories, you would have to make arbitrary choices about which to put a paper into. As it is, you can just assign both "Physics" and "Exciting papers" to a document, and when you're not excited any more just remove the "Exciting papers" tag.

Once you've created a tag (Tags->Create Tag...), a checkbox for the tag will appear in the bottom half of the Tag Pane (shown or hidden using View->Show Tag Pane). Once you've selected one or more documents, you can set or unset this tag for the group by clicking the checkbox.

Once you've tagged some documents, you may want to filter your view by tag. You can do this by clicking on a tag in the list in the top half of the Tag Pane. To include more tags in the view, hold Ctrl while clicking to select more than one tag.

To complement the tagging system, a search box is provided above the document view. Entering text into the search box will cause only those documents featuring the search text to be shown. The search only considers the Title, Authors and Key fields of the documents.

Plugins

Additional functionality can be added to Referencer using the versatile Python language. As of version 1.1, two kinds of plugin are supported: Metadata fetcher plugins, and Document action plugins. The former might be a script that looks up metadata for a DOI code in an internet database, while the latter might be something that manipulates the metadata of an existing document in some way.

Interested developers should download the referencer source code and look in the plugins/ directory for examples and in plugins/README for a brief guide.