Here are the list of options that can be given to papercite.
- Bibtex parser (papercite >= 0.3.16): you can choose the pear parser (deprecated) or the OSBiB-based parser (default).
- Database backend (papercite >= 0.4.0): The database backend is used to store the result of bibtex parsing in a database, allowing to speed up the processing of shortcodes when the BibTeX file is big.
Some of these options can be set at a global level (through preferences) and page/post level. These options are shown
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:
file: The default bibtex URL(s) separated by commas (see what are the valid bibtex URLs).
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,
bibcite_templateare used to distinguish between the templates used respectively for
format: Template used to format one BibTeX entry
show_links: Enable (1, default) or disable (0) use of hyperlinks from
bibciteentries to the resulting list of publications
highlight: Highlight name(s) of specific author(s)
ssl_check: Enable (1) or disable (0, default) the verification of SSL certificates when downloading resources. This can be useful when fetching from a site with a self-signed certificate.
- The publication type can be fitered using
- Publications can be filtered by author using the following syntax:
author=name1&name2&name3. Filtering can match also authors whose name is substring of some other name (e.g. name "Su"). and is case sensitive in names which start with diacritics (e.g. Řehoř, Šimon..)
- The number of items to be displayed can be limited with the
limitargument. Its value, if greater than 0, gives the maximum number of items to be displayed
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 <)
Some options modify the bibtex processing:
process_titlescan be set to 1 (normal BibTeX behaviour - lowercase everything which is not between braces) and 0 (no processing)
You can modify the style of the citations by using the
format For example,
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, ...)
citeuses the bibtex key
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).
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-bibtexis the default template used for the
av-bibtexis another template for the
bibtexcommand. It adds support for
abstractfield (toggled like the bibtex entry), explicit
doi:link and a Download PDF link for
default-bibshowis the default template used for the
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:
@WP_PLUGIN_URL@will be replaced by the plugin URL.
@papercite_id@is a unique id within the page/post
@papercite_title@is the title sanitized for use in code or urls. It is sanitized with
[sanitize title()](http://codex.wordpress.org/Function_Reference/sanitize_title), specifically, HTML and PHP tags are stripped.
@key@is a the key as formatted with
@pdf@is the URL to the auto-detected PDF (or to the URL specified in the PDF field).
@positionInList@gives the position of the entry within the full list
@positionInGroup@gives the position of the entry within the list for the current group
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
||with the same semantics as in main programming languages.
- HTML in fields is preserved by default. All fields are stripped for html code by default, this behaviour can be disabled in the template on a field by field basis by adding the modifier
:htmlto the field. I.e. an abstract field that contains
This is the <b>greatest</b> book in the worldwill show:
@abstract:html@= This is the greatest book in the world
@abstract:strip@= This is the greatest book in the world
@abstract:protect@= This is the greatest book in the world
@abstract:sanitize@= This is the greatest book in the world This should only be used when with fully trusted bibtex sources, as it can be used to embed malicious code on the website
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:
papercitefor headers like the
h3header for grouping key display
papercite_entryfor a single bibtex
papercite_bibtexfor the bibtex code
papercite_pdffor the PDF link
papercite_doifor the DOI link
highlight option can be used to highlight specific parts of an author or editor list (see here for an example). You can specify arbitrary regular expressions. Each match of the regular expression will then be highlighted. For example,
will highlight all occurences of M. Mouse. Similarly,
You can group the citations using the
group option with values
none (by default),
entrytype or any other valid bibtex field. You can order the groups using the
group_order option which can take values among
none (none by default).
The grouping is defined by the
group value (
none). Group are sorted depending on the
none: No order
asc: Ascendant order
desc: Descendant order
You can sort the citations using the
sort option together by a description of the sorting key. Note that the sort
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
none: No order
asc: Ascendant order
desc: Descendant order