Papercite
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, the 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 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.
BibTeX Entries
Locating BibTeX Entries
BibTex files can be stored:
Anywhere on the Internet – papercite will download any file if the
file
begins byhttp://
.As a custom field prefixed by
papercite_
. For example, the URL custom://data will use the data in thepapercite_data
custom field.
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.
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 a small HTML form where users can choose from authors and publication types. It:
displays a simple form.
reads data from the form (what is selected).
alters parameters (author & type) according to data from the form in the original command.
passes this modified command as “bibtex” for further processing.
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:
sortauthors=0/1
: sort authors alphabetically in the form if equal to 1
If no selection is made in the 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
If the
[/bibshow]
shortcode is not present, then the bibliography is automatically displayed at the end of the page/post.If the option is set, the
[bibshow]
tag can be automatically added when a[bibcite]
is encountered. In this case, a default BibTeX file should be given in the options.
bibshow
and bibtex
options
Here is 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).
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.
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:
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 publicationtemplate
: How to format the publication. At a global level,bibshow_template
andbibcite_template
are used to distinguish between the templates used respectively forbibshow
andbibcite
.format
: Template used to format one BibTeX entry.show_links
: Enable (1, default) or disable (0) use of hyperlinks frombibcite
entries to the resulting list of publications/highlight
: Highlight name(s) of specific author(s).
Filtering Options
The publication type can be filtered using
allow
anddeny
.Publications can be filtered by author using the following syntax:
author=name
,author=name1|name2|name3
, orauthor=name1&name2&name3
. Filtering can match also authors whose name is a substring of some other name (e.g., name “Su”) and is case sensitive in names that start with diacritics (e.g., Řehoř, Šimon..).The number of items to be displayed can be limited with the
limit
argument. 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 is 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
Some options modify the bibtex processing:
process_titles
can 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,
[bibtex file=mypub.bib format=ieee template=default-bibtex key_format=number]
The key_format
controls how a key is associated with a BibTeX entry. From within an 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
plain
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:
default-bibtex
is the default template used for thebibtex
command.av-bibtex
is another template for thebibtex
command. It adds support forabstract
field (toggled like the bibtex entry), explicitdoi:
link and a Download PDF link forurl
field.default-bibshow
is the default template used for thebibshow
command.
From a practical 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@key@
is the key as formatted withkey_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.
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:
papercite
for headers like theh3
header for grouping key display.papercite_entry
for a single BibTeX.papercite_bibtex
for the BibTeX code.papercite_pdf
for the PDF link.papercite_doi
for the DOI link.
The 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 occurrences of M. Mouse. Similarly,
will highlight all occurrences of M. Mouse or D. Duck.
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
). Groups 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.
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 orderasc
: Ascendant orderdesc
: Descendant order