# &app; Manual V&manrevision;

Referencer is a tool to help you manage your collection of documents, and to use them to generate a bibliography.

2008
John Spray
Referencer Development Team
&legal; John Spray

    	    jcspray@icculus.org

Referencer Manual V 1.1.6
2008-10-22

John Spray

This manual describes version &appversion; of &appname;.

## Feedback

To report a bug or make a suggestion regarding the &app; application or this manual, please visit the Referencer home page.

## Introduction

&app; 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 &app; can deal with any kind of document that BibTeX can.

## Getting Started

### Starting &app;

You can start &app; in the following ways:

Applications menu

  Choose Office Referencer.

Command line

  To start &app; from a command line, type the following command, then press Return:

  `referencer`

### When You Start &app;

When you start &app;, the following window is displayed.

#### &app; Start Up Window

Shows &app; main window.

The &app; window contains the following elements:

Menubar

  The menus on the menubar contain all of the commands that you need to work with files in &app;.

Toolbar

  The toolbar provides quick access to some frequently used menu items.

Document list

  The document list shows the documents in the library being worked on. It can be used in either List View or Icon View.

Tag pane

  The tag pane provides a list of tags which can be applied to documents, as well as buttons for creatings and deleting tags. The document list can be filtered to certain tags by selecting them in the tag pane.

## Usage

At it's most basic, &app; 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 &app; library, it will automatically be searched for key identifiers such as a DOI code or arXiv identifier. If either of these is found, &app; 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!

&app; 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.

&app; is intended to be extremely user-friendly, but to help you get up and running as smoothly as possible, the following subsections explain how to use &app;.

### To use &app; with BibTex

&app; 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 &app; generate a BibTeX file (by choosing 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 &app; to write the BibTeX file every time you change your library (Library Manage BibTex File).

&app; 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, capitalization of text in your LaTex output may differ from that in your &app; library. This is to allow publishers to impose their own capitalization schemes. If you want text to be capitalized 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 &app; by choosing Library Import... from the menubar.

Importing and then exporting a BibTex file is not guaranteed (or intended) to produce exactly the same file as went in: &app; is not a BibTeX editor!

Information such as document filenames and tags is not included in BibTeX files. You should always use your &app; library file as the authoritative copy.

### To add documents

#### To add documents by file/folder

Choose Documents Add file … from the menubar.

If you have some document files you'd like Referencer to know about, you can add one or more files, or a whole folder (by choosing Documents Add folder …), and &app; will create entries for each file. PDF files will be read, and &app; will do its best to fill out the metadata for you.

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.

#### To add documents by DOI code

Choose Documents Add document with DOI … from the menubar.

If you have the DOI code for a paper, you can save yourself the effort of inputting its metadata by simply giving &app; the DOI and letting it look up the metadata for you.

#### To add documents by hand

Choose Documents Add empty reference … from the menubar.

As a last resort, &app; 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.

#### To add documents from a BibTeX/EndNote/Refer file

Choose Library Import … from the menubar.

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.

#### To add documents by Copy/Paste

Choose Edit Paste BibTex from the menubar.

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.

### To use different document types/fields

Referencer's user interface is optimized 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. To open this, choose Documents Properties from the menubar.

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 categorize 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 (by choosing 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 &app; 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 &app; source code and look in the plugins/ directory for examples and in plugins/README for a brief guide.

## About &app;

&app; and this manual were written by John Spray (jcspray@icculus.org). Some contributions to the manual came from Mario Blättermann (mario.blaettermann@t-online.de. To find more information about &app; and the most recent documentation, please visit the project page.

This program is distributed under the terms of the GNU General Public license as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of this license is included with this documentation; another can be found in the file COPYING included with the source code of this program.