<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "1.1.6">
  <!ENTITY manrevision "1.1.6">
  <!ENTITY date "October 2008">
  <!ENTITY appname "Referencer">
  <!ENTITY app "<application>&appname;</application>">
  <!-- Information about the entities
       The legal.xml file contains legal information, there is no need to edit the file. 
       Use the appversion entity to specify the version of the application.
       Use the manrevision entity to specify the revision number of this manual.
       Use the date entity to specify the release date of this manual.
       Use the app entity to specify the name of the application. -->
]>
<article id="index" lang="en">
  <articleinfo>
    <title>&app; Manual V&manrevision;</title>
    <abstract role="description">
      <para> 
        Referencer is a tool to help you manage your collection of documents, and to use them to generate a bibliography.
      </para>
    </abstract>
    <copyright> 
      <year>2008</year> 
      <holder>John Spray</holder> 
    </copyright>
    <publisher> 
      <publishername> Referencer Development Team </publishername> 
    </publisher> 
    &legal;
    <authorgroup>
      <author role="maintainer">
	<firstname>John</firstname> <surname>Spray</surname>
	<affiliation>
	  <address>
	    <email>jcspray@icculus.org</email>
	  </address>
	</affiliation>
      </author> 
    </authorgroup>
    <revhistory>
      <revision>
	<revnumber>Referencer Manual V 1.1.6</revnumber>
	<date>2008-10-22</date>
	<revdescription>
	  <para role="author">John Spray</para>
	</revdescription>
      </revision>
    </revhistory>

    <releaseinfo>This manual describes version &appversion; of &appname;.
    </releaseinfo> 
      <legalnotice> 
      <title>Feedback</title> 
      <para>To report a bug or make a suggestion regarding the &app; application or
      this manual, please visit the <ulink url="http://icculus.org/referencer"
	  type="help">Referencer home page</ulink>. 
      </para>
      </legalnotice>
  </articleinfo>

  <sect1 id="intro">
    <title>Introduction</title>
      <para>
      &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.
      </para>
      </sect1>
      
      <!-- =========== Getting Started ============================== -->
<!-- Use the Getting Started section to describe the steps required
     to start the application and to describe the user interface components
     of the application. If there is other information that it is important
     for readers to know before they start using the application, you should
     also include this information here.
     If the information about how to get started is very short, you can
     include it in the Introduction and omit this section. -->

  <sect1 id="referencer-getting-started">
    <title>Getting Started</title>

    <sect2 id="referencer-start">
      <title>Starting &app;</title>
      <para>You can start &app; in the following ways:</para>

      <variablelist>
        <varlistentry>
          <term><guimenu>Applications</guimenu> menu</term>
          <listitem>
            <para>
              Choose <menuchoice><guisubmenu>Office</guisubmenu>
              <guimenuitem>Referencer</guimenuitem></menuchoice>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Command line</term>
          <listitem>
            <para>
              To start &app; from a command line, type the following command,
              then press <keycap>Return</keycap>:
            </para>
            <para><command>referencer</command></para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="referencer-when-start">
      <title>When You Start &app;</title>
      <para>When you start &app;, the following window is displayed.</para>

      <figure id="referencer-window-fig">
        <title>&app; Start Up Window</title>
        <screenshot>
          <mediaobject>
            <imageobject><imagedata fileref="figures/referencer_window.png" format="PNG"/></imageobject>
            <textobject><phrase>Shows &app; main window.</phrase></textobject>
          </mediaobject>
        </screenshot>
      </figure>

      <para>The &app; window contains the following elements:</para>

      <variablelist>
        <varlistentry>
          <term>Menubar</term>
          <listitem>
            <para>
              The menus on the menubar contain all of the commands that you need to work with files in &app;.
            </para>            
          </listitem>
        </varlistentry>
        
		<varlistentry>
          <term>Toolbar</term>
          <listitem>
            <para>
              The toolbar provides quick access to some frequently used menu items.
            </para>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term>Document list</term>
          <listitem>
            <para>
              The document list shows the documents in the library being worked on.  It can 
			  be used in either <guimenuitem>List View</guimenuitem> or <guimenuitem>Icon 
			  View</guimenuitem>.
            </para>
          </listitem>
        </varlistentry>       

        <varlistentry>
          <term>Tag pane</term>
          <listitem>
            <para>
              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.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>
  </sect1>
  
  <sect1 id="usage">
      <title>Usage</title>  
   
   <para>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.</para>
  
  <para>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.</para>
  
  <note>
	  <para>If you've got a collection of already-downloaded PDFs of papers, this can save you a lot of typing!</para>
  </note>
  
  <para>&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.</para>
  
  <para>&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;.</para>
  
  
  
  <sect2 id="howto-bibtex">
      <title>To use &app; with BibTex</title> 
      <para>&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 <menuchoice><guisubmenu>Library</guisubmenu>
              <guimenuitem>Export to BibTex</guimenuitem></menuchoice>). By default this will include all documents in your library: if you would rather only export some documents then you can use the <guilabel>Selection:</guilabel> 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 (<menuchoice><guisubmenu>Library</guisubmenu>
              <guimenuitem>Manage BibTex File</guimenuitem></menuchoice>).</para>
              
              <para>&app; will automatically handle conversion of special characters (e.g. <literal>ß</literal>) to their <application>LaTex</application> equivalents (e.g. <literal>\ss</literal>). 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 <guilabel>Protect capitalization</guilabel> option in the BibTeX export dialog.</para>
              
              <para>If you already have a BibTeX file, you can import it into &app; by choosing <menuchoice><guisubmenu>Library</guisubmenu><guimenuitem>Import...</guimenuitem></menuchoice> from the menubar.</para>
              
	      <note><para>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!</para></note>
              
              <para>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.</para>

</sect2>  
  <sect2 id="howto-add-docs">
      <title>To add documents</title> 
      
   	<sect3 id="howto-add-docs-by-file">
      <title>To add documents by file/folder</title>
      	<para>Choose <menuchoice><guisubmenu>Documents</guisubmenu>
              <guimenuitem>Add file …</guimenuitem></menuchoice> from the menubar.</para>
        <para>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 <menuchoice><guisubmenu>Documents</guisubmenu>
              <guimenuitem>Add folder …</guimenuitem></menuchoice>), 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.</para>
	      <note><para>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.</para></note>
   	</sect3>
   	<sect3 id="howto-add-docs-by-DOI">
      <title>To add documents by DOI code</title>
      	<para>Choose <menuchoice><guisubmenu>Documents</guisubmenu>
              <guimenuitem>Add document with DOI …</guimenuitem></menuchoice> from the menubar.
        </para>
        <para>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.
        </para>
   	</sect3>
   	<sect3 id="howto-add-docs-by-hand">
      <title>To add documents by hand</title>
      	<para>Choose <menuchoice><guisubmenu>Documents</guisubmenu>
              <guimenuitem>Add empty reference …</guimenuitem></menuchoice> from the menubar.
        </para>
        <para>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.
        </para>
   	</sect3>
   	<sect3 id="howto-add-docs-from-bibtex">
      <title>To add documents from a BibTeX/EndNote/Refer file</title>
      <para>Choose <menuchoice><guisubmenu>Library</guisubmenu>
              <guimenuitem>Import …</guimenuitem></menuchoice> from the menubar.
              </para>
              <para>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.
              </para>
   	</sect3>
   	<sect3>
      <title>To add documents by Copy/Paste</title>
      <para>Choose <menuchoice><guisubmenu>Edit</guisubmenu>
              <guimenuitem>Paste BibTex</guimenuitem></menuchoice> from the menubar.
      </para>
      <para>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.
      </para>
   	</sect3>
   </sect2>
   
   <sect2 id="howto-use-different-docs">
      <title>To use different document types/fields</title> 
      <para><application>Referencer's</application> user interface is optimized for dealing with scientific papers. As such, the document type is "Article" by default and fields such as <guilabel>Title</guilabel>, <guilabel>Authors</guilabel>, <guilabel>Journal</guilabel> and <guilabel>Volume</guilabel> are shown. Other types of document may be selected in the properties window. To open this, choose <menuchoice><guisubmenu>Documents</guisubmenu>
              <guimenuitem>Properties</guimenuitem></menuchoice> from the menubar.</para>
              
              <para>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 <guilabel>Extra Fields</guilabel> section of the properties window, and clicking the <guilabel>New</guilabel> icon. To enter some data into your new field, select it and click the <guilabel>Edit</guilabel> icon. </para>


   </sect2>
  </sect1>
  
  <sect1 id="tagging-searching">
      <title>Tagging And Searching</title> 
      <para>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.
      </para>
	  <para>Once you've created a tag (by choosing <menuchoice><guisubmenu>Tags</guisubmenu>
              <guimenuitem>Create Tag …</guimenuitem></menuchoice>), a checkbox for the tag will appear in the bottom half of the Tag Pane (shown or hidden using <menuchoice><guisubmenu>View</guisubmenu>
              <guimenuitem>Show Tag Pane</guimenuitem></menuchoice>). Once you've selected one or more documents, you can set or unset this tag for the group by clicking the checkbox.
	  </para>
	  <para>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 <keycap>Ctrl</keycap> while clicking to select more than one tag.
	  </para>
	  <para>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 <guilabel>Title</guilabel>, <guilabel>Authors</guilabel> and <guilabel>Key</guilabel> fields of the documents.
	  </para>

   </sect1>
   
   <sect1 id="plugins">
      <title>Plugins</title> 
      <para>Additional functionality can be added to &app; using the versatile <ulink url="http://www.python.org" type="http">Python</ulink> language. As of version 1.1, two kinds of plugin are supported: <application>Metadata fetcher</application> plugins, and <application>Document action</application> 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.</para>
      
      <para>Interested developers should download the &app; source code and look in the plugins/ directory for examples and in plugins/README for a brief guide.</para>


   </sect1>
   
   <!-- ============= About ================================== -->
<!-- This section contains info about the program (not docs), such as
      author's name(s), web page, license, feedback address. This
      section is optional: primary place for this info is "About.." box of
      the program. However, if you do wish to include this info in the
      manual, this is the place to put it. Alternatively, you can put this information in the title page.-->
  <sect1 id="gnome-lirc-properties-about">
    <title>About &app;</title>

    <para>
     &app; and this manual were written by John Spray (<email>jcspray@icculus.org</email>).
     Some contributions to the manual came from Mario Blättermann 
     (<email>mario.blaettermann@t-online.de</email>. To find more information about
      &app; and the most recent documentation, please visit the <ulink url="http://icculus.org/referencer" type="http">project
     page</ulink>.
    </para>
    <para>
      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 <ulink url="ghelp:gpl" type="help">copy of this license</ulink>
      is included with this documentation; another can be found in the file
      COPYING included with the source code of this program.
     </para>
  </sect1>

</article>





