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

1. Within the folder $DATA, the subfolders
   • bib contains your bibtex files
   • pdf contains your pdf files (by default, but this can be customized)
   • 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

Location BibTeX entries

• In a special folder $DATA/bib. In that case, the file can be referred to by using directly the file name (with the extension).
• Anywhere on the Internet - papercite will download any file if the file begins by http://
• As a custom field prefixed by papercite_. For example, the URL custom://data will use the data in the papercite_data custom field

Attached files

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

    @?ppt@ <a href="@ppt@" title='Download PPT' class='papercite_pdf'<img src='@PAPERCITE_DATA_URL@/img/ppt.png' alt="[ppt]"/></a> @;@ 
  

Usages

Bibliography mode

Filtering mode

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

• displays 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

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

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.
• 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 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).
• 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:

    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, bibshow_template and bibcite_template are used to distinguish between the templates used respectively for bibshow and bibcite
• format: Template used to format one BibTeX entry
• show_links: Enable (1, default) or disable (0) use of hyperlinks from bibcite entries to the resulting list of publications
• highlight: Highlight name(s) of specific author(s)

Filtering options

• The publication type can be fitered using allow and deny.
• Publications can be filtered by author using the following syntax: author=name, author=name1|name2|name3, or 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 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 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

• process_titles can be set to 1 (normal BibTeX behaviour - lowercase everything which is not between braces) and 0 (no processing)

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
• plain

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
• av-bibtex is another template for the bibtex command. It adds support for abstract field (toggled like the bibtex entry), explicit doi: link and a Download PDF link for url field.
• default-bibshow is the 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 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 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.

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 the h3 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,

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

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},
   ...
}