Papercite documentation

Table of contents

1. File data structure
2. BibTex entries: how special bibtex fields are used
3. Usage: describes the two ways to use papercite
4. Options
   1. Global options
   2. Local options

Data structure

1. 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
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 -.

BibTex entries

Usages

Bibliography mode

Citation mode

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

If the [/bibshow] shortcode is not present, then the bibliography is automatically displayed at the end of the page/post.

bibshow and bibtex options

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

Global options

• Bibtex parser (papercite >= 0.3.16): you can choose the pear parser (deprecated) or the OSBiB-based parser (default).

Local options

Some of these options can be set at a global level (through preferences) 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(s) separated by commas. Files are either stored as described in the papercite-data folder, or an URL can be given
• 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

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 formats are currently available:

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

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 respect to 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).

Here are some more general modifications:

• More generally, @#fieldname prints the number of entries in the field name (works with authors, editor and pages)
• A general if-then-else structure can be encoded by @?condition@ ... @:@ ... @;@, where the "else" and "end if" can be used in a short version (no need to specify the condition), and where the condition can be more elaborate than in bib2tpl: you can use the operators >, <, = and || with the same semantics as in main programming languages.

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:

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

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.

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