Papercite documentation

Table of contents

  1. File data structure
  2. BibTex entries: how to store BibTeX entries, how special bibtex fields are used
  3. Attached files: how files associated to one bibtex entry can be detected
  4. Usage: describes the two ways to use papercite
  5. Options
    1. Global options
    2. Local options
    3. Formatting entries
    4. Formatting entries
    5. Sorting entries
  6. FAQ

Data structure

Using the Media Library

It is possible to use the WordPress media library. In this case, the name of the file is controlled by the permalink. By default, the permalink is a processed version of the file name: the name is lowercased, extension is removed, etc. Due to WordPress limitations, it is necessary to attach the media file to a post before being able to edit the permalink.

The matching process is determined by the papercite option page. See the help on attached files.

Note that bibtex files are matched using the same process, with application/x-bibtex as the mime-type and no suffix.

Using direct access to the WordPress files

The data folder where all custom files (bibtex, PDF, templates) will be denoted $DATA in this document. This folder is either wp-content/papercite-data or wp-content/blogs.dir/XXX/files/papercite-data (in case of multiple sites hosted on WordPress).
  1. Within the folder $DATA, the subfolders
  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 -.
Do not customize the files directly in the main plugin folder: when updating the plug-in, the full papercite plugin folder will be replaced by the new version.
Use the papercite-data folder.

BibTex entries

Location BibTeX entries

BibTex files can be stored:

Attached files

For each bibliographic entry, files can be automatically matched to retrieve e.g. the paper PDF, or the slides.

First, the key of the bibtex entry is transformed - lowercased, and the characters : and / are replaced by -. The field determines the bibtex field that will be populated when matching. Then,
Filesystem matching
A file will match if it is contained in the folder and its name is [key][suffix].extension
WordPress media matching
A file will match if its mime-type corresponds (or is empty) and its permalink name matches [key][suffix]
The URL of the matched file will be stored in the field FIELD of the bibtex entry, and will be available by templates. For example, this can be inserted to display a link to a presentation:
    @?ppt@ <a href="@ppt@" title='Download PPT' class='papercite_pdf'<img src='@PAPERCITE_DATA_URL@/img/ppt.png' alt="[ppt]"/></a> @;@ 
  
The FIELD, FOLDER, EXT and mime-type can all be set in the preferences. Papercite will process the list of such triplets, and will set the bibtex field to the last matched file (if any).

Usages

Bibliography mode

This is my whole list of publications:
[bibtex file=mypub.bib]
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]
This is a bibliography stored in the papercite_data custom field:
[bibtex file=custom://data]

Filtering mode

The bibfilter command adds small html form where user can choose from authors and publication types. It does:

Example of use:
[bibfilter group=year group_order=desc author=Nahodil|Vítků allow=incollection,mastersthesis sortauthors=0]

bibfilter uses the same parameters as bibtex command, with these modifications:

note: if no selection is made in form, bibtex parameters are not rewritten, this means that you can combine both commands as follows: -if no filter for type is made, bibtex command is called with e.g. type=INPROCEEDINGS|INCOLLECTIONS -the same for authors, the parameter "author" defines: -all authors for bibfilter menu -all authors for bibtex command

Known limitations: sorting names in the form does not work with Czech diacritics very well, (e.g. Šafář, Řasa..)

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 some others [bibcite key=key2,key3]

You can use [/bibshow] to end the bibshow section and print the list of references:

[/bibshow]
Remarks:

bibshow and bibtex options

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

Global options

Local options

Some of these options can be set at a global level (through preferences) and page/post level. These options are shown like this. To set options at the post/page level, use the papercite_options field with one line per option in the format:

    field_name = field_value
  

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

You can modify how publications are displayed using several options:

Filtering options

Grouping and order options

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:

Formatting

Some options modify the bibtex processing: 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:

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

Feel free to contribute new formats, but note that in the future the citation style might be written using the Citation Style Language (CSL).

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:

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 This to decouple the formatting of entries with the formatting of the full bibliography.

With respect to the bib2tpl code, some extra variables are defined:

Here are some more general modifications:

CSS can be used to customize the display of entries. Again, do not customize directly papercite files, this would be overwritten with plugin updates. The best solution is to use a plugin such as Simple custom CSS that allows custom CSS to be written and stored within the WordPress database.

In the default templates, the following classes are used:

Grouping

You can group the citations using the group option with values none (by default), firstauthor, entrytype or any other valid bibtex field. 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:

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=asc]

Entries (within groups) are sorted depending on the sort key (see grouping for the list of possible keys). The ordering is also influenced by the order value.

FAQ

Customizing templates

Adding extra text at the end of each publication (e.g. the number of citations, etc.)
Basically, in the $DATA/tpl folder, you can copy the default template (default-bibtex.tpl and default-bibshow.tpl depending on which command you use) and modify it by adding after @#entry@ the command
@?citations@@citations@ citations@;citations@.
Then you can use a custom field citations in your bibtex file, e.g.
@inproceedings{...
   citations = {3},
   ...
}