=== Plugin Name ===
Contributors: bpiwowar
Tags: formatting, bibtex
Requires at least: 2.0
Tested up to: 3.0.1
Stable tag: 0.2.14

papercite helps to format bibtex entries to display a bibliography or
cite papers

== Description ==

papercite (based on bib2html 0.9.3) format bibtex entries as HTML so they can be inserted in WordPress pages and posts. The input data is a bibtex file (either local or remote) and entries can be formatted by default using various predefined styles. Bibtex source file and a link to the publication are also available from the HTML. 

Features:

* input data directly from the bibtex text file
* source files can be URL (e.g., from citeulike.org and bibsonomy.org)
* automatic HTML generation
* easy inclusion in wordpress pages/posts by means of dedicated tags
* possibility of filtering the bibtex entries based on their type (allow, deny)
* possibility to access the single bibtex entry source code to enable copy&paste (toggle-enabled visualization)
* expose URL of each document (if network-reachable)
* possibility of editing the bibtex file directly from the wordpress administration page

Features compared to bib2html (0.9.3):

* adds the possibility of writing a text with reference to a bibtex file, and to print the bibliography at the end.
* it checks if a PDF file whose name match the key exists and link to it if this is so
* it uses the DOI information to create an external link
* object oriented redesign of the plugin, so that further extensions are easy to make
* publications can be grouped by year

The papercite plugin has been developed and tested under Wordpress 3.0. It is based on bib2html version 0.9.3.

== Installation ==

Follow these step or use the plugin installer from WordPress to
install papercite:
1. download the zip file and extract the content of the zip file into a local folder
2. upload the folder papercite into your wp-content/plugins/ directory
3. log in the wordpress administration page and access the Plugins
menu

Then, you should activate papercite, and follow the instructions
given in *other notes*.

== Frequently Asked Questions ==

= How can I edit my bibtex files? =

If your file is local to the blog installation, you have two options:
- via FTP client with text editor
- via Wordpress Admin interface: Manage->Files->Other Files
-- use wp-content/plugins/papercite/data/mybibfile.bib as a path

Alternatively, you can maintain your updated biblilography by using systems such as citeulike.org and bibsonomy.org; 
specify the bib file using as a URL (e.g., in citeulike, you should use http://www.citeulike.org/bibtex/user/username)

= How are the entries sorted? =

Since version 0.1, the entries are sorted by year starting from the most
recent; in future revision, I plan to make this configurable by the user

= How can I personlize the HTML rendering? =

The HTML rendering is isolated in a template file called bibentry-html.tpl.
Just change it.

== Screenshots ==

1. Cite mode
2. bib2html mode

== Changelog ==

= 0.2.14 = 
  * Grouped by year option (patch due to S. Aiche)
  * Now generates an id which does not depend on the key (fix javascript related bugs)
= 0.2.13 = 
  * bug fix: wrong mappings from bibtex fields to arrays have been corrected, link to pdf is now working properly, polish characters
  are almost properly handled (thanks to Łukasz Radliński)
= 0.2.11 =
  * bug fix: name clash was preventing insertion of medias using the
  WP dialogs
= 0.2.10 =
  * papercite now looks in the pdf directory at two levels
    (wp-content,  and wp-content/plugins)
= 0.2.9 =
  * Small bug fix (removes a warning)
= 0.2.8 =
  * Documentation update
  * New parameter `format`
 = 0.2.5 =
  * Fixed a bug with the allow filter
= 0.2.4 =
  * Small bug fixes (if the file is an URL) and use of WP functions to
  retrieve remote data (useful when you have proxies)
= 0.2.3 =
 * Fixed a bug introduced in 0.2.2
 * Changed the default folder for data in order to avoid data loss
 when upgrading
 * Finished the encapsulation of all the code, so as to prevent name
 clash with wordpress and/or other plugins
= 0.2.2 =
 * Removed PHP 5 specific code
= 0.2.1 =
 * Added the template file
= 0.2 =
 * Added deny/allow parameters to [bibtex] so the plugin can replace bib2html
= 0.1 =
 * Adapted the plugin from bib2html 0.9.3
 * Added the bibshow and bibcite commands

== Upgrade Notice ==

= 0.2.9 = 
Removed a PHP warning with bibshow
= 0.2.8 =
Introduced the `format` parameter to format the entries
= 0.2.5 =
Bug fix - all users should upgrade
= 0.2.4 =
Users using remote URLs for their bibliography should upgrade
= 0.2.3 =
All users must upgrade to this version - Please read the information
about the new location of bibtex and pdfs.
= 0.2.2 =
Users using PHP 4 should upgrade
= 0.2.1 = 
All users should upgrade - plugin was broken until now
= 0.2 =
All bib2html users should at least use this version so they don't break their installation
= 0.1 =
First version

== A brief Markdown Example ==

= Data structure =

1. Create a folder in `wp-content/papercite-data`, with two
subfolders: `bib` (this will contain the bibtex files) and `pdf` (this
will contain the PDF file).
2. Copy your bibtex files into the `bib` folder, and your pdf files
into the `pdf` folder. To match a bibtex entry with a PDF file, the
PDF file should have be named **KEY**`.pdf` where **KEY** is the
bibtex key in lowercase, where `:` and `/` have been replaced by `-`.


= Bibliography mode =

This is my whole list of publications: 

`[bibtex file=mypub.bib]`

If you want to filter the type of bibtex items, you can use one of the attributes allow, deny and key as follows:

This is my latest conference paper:

`[bibtex file=mypub.bib key=CGW2006]`

You can also have a list of keys to display more than one paper:

`[bibtex file=mypub.bib key=CGW2006,CGW2007]`

This is my bibliography maintained at citeulike.org

`[bibtex file=http://www.citeulike.org/bibtex/user/username]`

This is my bibliography maintained at bibsonomy.org

`[bibtex file=http://bibsonomy.org/bib/user/username?items=1000]`

= Citation mode =

The second way of using this plug-in (new to papercite), is to use bibcite and bibshow commands

`[bibshow file=mybib.bib]
Here is one reference [bibcite key=key1]
and another [bibcite key=key2]`

You end with the following to print the list of references:

`[/bibshow]`


= Formatting the entries =

You can modify how publications are displayed using several options:

* format 
* groupByYear

You can modify the style of the citations by using the `format`
parameter with the `bibshow` and `bibtex` commands.
For example, 

`[bibtex file=mypub.bib format=britishmedicaljournal]`

The following format are currently available: 

* ieee (default)
* apa 
* britishmedicaljournal 
* chicago
* harvard 
* mla
* turabian

You can group the citations by year using the groupByYear

`[bibtex file=mypub.bib groupByYear=TRUE]`