Papercite documentation

Data structure

Create a folder in wp-content/papercite-data or wp-content/blogs.dir/XXX/files/papercite-data (in case of multiple sites hosted on WordPress), with the following subfolders (none is mandatory):
- bib contains your bibtex files
- pdf contains your pdf files
- tpl contains your custom templates
- format contains your custom entry formats
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 -.

Usages

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]

`bibshow` and `bibtex` options

Here are the list of options that can be given to papercite.

Some of these options can be set at a global level (through ) and page/post level (using custom fields with a prefix papercite_). These options are shown like this.

First, some options are necessary to tell which bibtex file should be used:

file: The default bibtex file (can be a URL)
timeout: The default time-out before reloading an external resource

You can modify how publications are displayed using several options:

key_format: How to format the citing key of the publication
template: How to format the publication. At a global level, bibshow_template and bibcite_template are used to distinguish between the template used respectively for bibshow and bibcite
format: Template used to format one BibTeX entry

Grouping and order options

group: How to group publications
group-order: Group sort order
sort: How to order publications within groups
order: Sort order within groups

Each of these options are described next. Finally, the template language used to format entries is described on the bib2tpl site, with the following modifications:

@#field@ gives the number of entries in a field (author or editor)
Conditions can be more expressive, e.g. @?field=abc@ is true if the field is equal to abc (numeric comparisons are possible with > and <)

Formatting

You can modify the style of the citations by using the format For example,

[bibtex file=mypub.bib format=ieee template=default-bibtex key_format=number]

The key_format controls how a key is associated to a BibTeX entry. From within a entry template, the value of the key is given by @key@. The following values are accepted:

numeric (default) gives a unique increasing number to each entry (1, 2, ...)
cite uses the bibtex key

The format described how an entry is displayed. The following format are currently available:

ieee (default) is the default format loosely based on IEEE

Feel free to contribute new formats.

Eventually, the template option controls which template is used to format the entries. It is based on the tpl code. For the moment, the following templates are defined:

default-bibtex is the default template used for the bibtex command
default-bibshow is he default template used for the bibshow command

From a pratical point of view, the final format follows bib2tpl. In order to create a bib2tpl template, templates and formats are merged: in the template, @#entry@ is replaced by the content of the format file. This allows to decouple the formatting of entries with the formatting of the full bibliography.

With the bib2tpl code, some extra variables are defined:

@WP_PLUGIN_URL@ will be replaced by the plugin URL.
@papercite_id@ is a unique id within the page/post
@key@ is a the key as formatted with key_format.
@pdf@ is the URL to the auto-detected PDF (or to the URL specified in the PDF field).

Grouping

You can group the citations using the `group` option with values `none` (by default), `year`, `firstauthor`, or `entrytype`. You can order the groups using the `group-order` option which can take values among `asc`, `desc` or `none` (none by default). Example:

[bibtex file=mypub.bib group=year group_order=desc]

The grouping is defined by the group value (year, firstauthor, entrytype or none). Group are sorted depending on the group_order value:

none: No order
asc: Ascendant order
desc: Descendant order

Sorting

You can sort the citations using the sort option together by a description of the sorting key. Note that the sort

[bibtex file=mypub.bib sort=year order=esc]

Entries (within groups) are sorted depending on the sort key (year, firstauthor, entrytype or none). The ordering is also influenced by the order value.

none: No order
asc: Ascendant order
desc: Descendant order