Pro Tip: BibTeX and Magic Citations

To use the features described here, please be sure to run Papers 2.0.3 or later.


See also public discussions:

Magic Citations

If you have never used Citations before, you may want to first get familiar with this feature by watching the screencasts in the corresponding tutorial:

http://support.mekentosj.com/kb/tutorials/magic-citations

Enabling Bibtex commands

By default, the citekeys are inserted using the Papers format, which simply places the citekey inside curly braces. If you want to format your bibliography using BibTeX, you should change the citekey format in Papers Preferences, under the Citations tab. The setting needs to be changed before you start inserting citations in your LaTeX documents. For now, Papers offers 2 options for BibTeX commands, the '\cite' or the \citep' commands.

scrivener_bibtex_citekey_preference.png

Inserting Bibtex commands with Magic Citations

The workflow to insert BibTeX commands is very similar to what you would do in Pages:

  • Invoke the Citations window by using the keyboard shortcut (typically type the control key twice)
  • Search the paper you'd like to cite and press Enter when you found it
  • Optionally add more papers to the citation by typing another query
  • When the citation is to your liking, press Enter on the 'Insert Citation' or 'Insert Citekey' command (or double-click)

This will insert the BibTeX command followed by the citekey within brackets at the insertion point in the current document.

Supported Applications

The following applications offer higher level of support: Papers is able to scan the file content and identify inserted commands (even after modifications by the user), and Papers can even format the manuscript with its own CSL-based engine (probably not a very useful feature when using BibTeX anyway). The default action after selecting a paper in the search result is 'Insert Citation'

  • TexShop
  • TextMate
  • TextWrangler
  • SubEthaEdit
  • BBEdit
  • TextEdit
  • Writeroom

The following applications offer a lower level of support. The default action after selecting a paper in the search result is 'Insert Citekey'. Papers will not always track the file in its Citations section, and it will not always be able to keep track of cited papers in the document. However, the inserted commands will work fine with BibTeX.

  • Terminal
  • Lyx
  • TexMaker
  • Smultron
  • MacVim
  • Aquamacs
  • Scrivener
  • Kod

A BibTeX command can still be inserted into many other applications, though in those other applications, the default action may typically be 'Insert Formatted Reference' or 'Copy to Clipboard'. The option to 'Insert Citekey' will also be offered in many cases, though potentially as the second or third choice. Please let us know of other applications that make sense for citekey insertion in the context of BibTeX.

Locking citekeys

With Papers2, we introduced a new default citekey, which we call a 'universal citekey'. By using a hash on the title or on the doi, Papers2 is able to generate a citekey that will very likely be different for two different papers), and that will always be the same value for two different users, even if they do not share their Papers library, and as long as they both have correct metadata. This citekey is however dependent on how much metadata you already have added on that particular publication. For starter, until you have authors and year, the citekey obsviously won't include the first author or year. In the absence of good metadata, the citekey is not very useful. But, if the publication has a title and it appears to have reliable metadata, or even better, if it has a doi, Papers2 can generate a reliable universal citekey (if you are curious: the description of how a universal citekey is generated will be explained in more details in a future entry in our Knowledge Base).

As long as you do not export the publication to BibTeX, or don't generate a cite command (via the copy menu item or in a manuscript), the citekey will keep adapting to changes in the metadata and will remain dynamic. This dynamic citekey will be displayed in the table view in your main library, and will be used to name your PDFs on disk if you choose to do so in the preferences.

As soon as you export the publication to BibTeX, or generate a BibTeX cite command, the citekey is 'locked' (and uniqued if necessary, though that should be rarely needed). The reason is simple: it is crucial for the proper functioning of BibTeX that the citekey remains constant (note that Papers2 is more flexible in that regard, it can read any universal citekey or any custom citekey you have entered in your library). Thus, you should not worry as the citekey intially changes and while it is still dynamic. Papers2 makes sure it is locked in when it needs to be locked in.

You can also use the inspector to either manually set a citekey of your choice, or conversely, 'unlock' a citekey that may have been set at a time when there was no useful metadata. To unlock a citekey you can simply delete the value, or choose the 'Unlock' item in the contextual menu that will appear when you click on the 'citekey' label itself.

papers2_unlock_citekey.png

Resurrection of Papers1 citekeys

New in Papers 2.0.3

When Papers 2.0 launched, we decided to not migrate from Papers1 the autogenerated citekeys (but still migrate the citekeys you had set manually). However, the migration process does not completely throw them away. They are still stored in the Papers2 database, but remain unused unless you actively set to apply them to a collection (or to your entire library). Even if you migrated before Papers 2.0.3, these Papers1 citekey are there, and the following instructions should bring them back to the forefront.

Before you proceed, there are a few things to keep in mind:

  • The procedure will override any locked citekey you may have already set since you started using Papers2
  • The procedure is pretty much irreversible; once the Papers1 citekeys are applied, the citekeys are 'locked' for the corresponding publications, as explained above; this means to undo the resurrection of Papers1 citekeys, you will have to edit each of them individually
  • Citekeys for papers that were not migrated from Papers1 will not have a Papers1 citekey applied; Papers2 does not apply a 'Papers1-like' citekey style, it only resurrects a citekey that may have been used before on that publication; for some of you, we know the inconsistency in citekey style will be unbearable :-)
  • The Papers1 citekeys do not have the nice properties that we introduced in Papers2 with the 'universal citekey' (again, read above for some details)

Because of the above, we recommend you think twice about it, and then only resurrect Papers1 citekeys for the publications that you need (the publications already cited in manuscripts prepared with Papers1 would be a good reason).

Here is how to proceed:

  • Select the publications for which you want to resurrect the Papers1 citekey (for instance, put them all in a collection)
  • Choose the menu item File...Export...BibTeX Library
  • Enter the name of the exported library
  • Choose to only export the selected publications or the selected collection
  • Check the option 'Use Papers1 Citekeys'
  • Click Export

bibtex_apply_papers1_citekey.png

It is likely you have no use of the exported BibTeX library, so you can throw it away after the export has completed. The export interface represents a simply way to apply the Papers1 citekey to a specific set of publications in one go. We hope you find it useful, and that it will help you transition from Papers1 to Papers2.

What's next

There is still more we would like to do for BibTeX integration:

  • auto-generate a BibTeX library next to the manuscript, in sync with citation insertions
  • better parsing of BibTeX citekeys to properly identify commands like '\citet' or other variants
  • improve export to BibTeX based on your input (see http://support.mekentosj.com/discussions/suggestions/361)
  • integrate Magic Manuscripts with some of the BibTeX-friendly tools like TexShop, depending on feasibility

Please share your thoughts, ideas, feedback, suggestions on these public discussions:

Please do not ask there for timelines on future developments :-) ... and please keep the discussion limited to the BibTeX/LaTeX topic; other bugs and feature requests should be sent to support at mekentosj dot com.