Pro Tip: Adding additional citation styles

The styles in Papers come directly from the official CSL repository. The CSL Library currently has over 6000 styles, and there are still a number of journals not represented. However, Papers regularly updates when new styles are added or amended in the repository. All the styles available with Papers are listed in the style browser that you can access as follows:

  • Go into the Papers Preferences/Options…Citations
  • Click on the popup menu 'Favorite Styles' and select 'More Styles...'
  • This will open the Style Browser

Adding existing styles from the CSL repository

  • The style repository on github has a wide selection of additional styles which are Citation Style Language (CSL) files. You can learn more about CSL files on the CitationStyles.org website.

  • Search for the style which you would like to add. It may be easier to find your style by pressing '⌘' + 'F' to search rather than scrolling through this long list. Note that some styles are named by their abbreviated version rather than their full name. Once you've found your style, save the CSL file to your hard drive. Keep in mind we take no responsibility for the accuracy of the styles from this site so it is always good to double-check this once your manuscript is formatted. However, the vast majority of these styles should be accurate.

Here is how to add the selected style to your library:

  • Make sure the style has the extension '.csl' (you can also check using the menu File > Get Info in the Finder)

  • Drag the file into the Papers window

Note that once a file has been added, you cannot drag it again as Papers will not erase a file already part of your library. You can however update the file directly where it is stored, in your library. Here is how to find the CSL file:

  • Locate your Papers library on your hard drive. If you're unsure where this is you can find its location by clicking on 'Preferences' in Papers for Mac or 'Options' in Papers for Windows and selecting the 'Library' tab.

  • Open the folder located at path Papers2 > Library.papers2 > Styles or Papers3 > Library.papers3 > Styles. This is where all your custom styles are stored.

ishot5.jpg

Note that you can even edit a style in your favorite text editor while checking the output in the 'Citations' preferences. The output will be shown when you open the style browser (menu item 'More Styles...' in the popup menu 'Favorites Styles') and select the style being edited. The bottom part of the sheet will show a preview of the output for the papers you have selected in your library. The output will be updated each time you select the window again, and switch back and forth between your text editor and Papers.

csl_style_preview.png

Contribute to the CSL Repository

If you think the style you created can be useful to others, we strongly encourage you to submit to the CSL repository. First of all, this is a great way to give back to the CSL community that has contributed hundreds of styles already. The styles you submit there are used not just by Papers, but by other software packages as well. If it's in the repository, it will eventually be added to the default list of styles in Papers (typically at the next update). That also means your name will be in the Papers acknowledgments as well!

If you want to do so, it's very straightforward. There are simple instructions on the wiki of the CSL repository:

https://github.com/citation-style-language/styles/wiki/Submitting-S...
https://github.com/citation-style-language/styles/wiki/Style-Requir...

Again, if you go through the trouble of reading the instructions below, consider contributing back to the repository!

General recommendations

If Papers or the CSL repository don't have the style you're after it is possible to make your own styles using one of the options below. After you create a CSL file using one of these options, you will need to move the file into your Papers library folder using the instructions above, and you will then need to restart Papers. However, it is also important to remember the following constraints:

  • make sure the file name is unique, and is not used by one of the built-in CSL files; the best way to make sure of that is to append a unique prefix or suffix to the file name

    This is correct: alex_csl-journal-irreproducible-results.csl

    This is not correct: nature.csl

  • make sure the file has the csl extension and no other extension after that

    This is correct: alex_csl-journal-irreproducible-results.csl

    This is not correct: alex_csl-journal-irreproducible-results.csl.xml

    This is not correct: alex_csl-journal-irreproducible-results.txt

  • make sure the id tag used in the XML file itself is unique, again for instance by adding a unique prefix, or use the zotero prefix if you submit to the official repository

    This is correct: <id>http://www.zotero.org/styles/journal-irreproducible-results</id>

    This is correct: <id>alex/journal-irreproducible-results</id>

    This is not correct: <id>1</id>

  • make sure the 'Title' tag in the XML file can be easily found later, as this is what will be displayed in Papers2 as the journal/style name

    This is correct: <title>Journal of Irreproducible Results</title>

    This is not correct: <title>j_irreproducible_res</title>

####Option 1

  • Edit the XML files that are used by CSL files using CSL specifications
  • This is tricky, but if you are comfortable with XML and have a good text editor like TextMate or similar, then it's not out of reach.

####Option 2

Some Papers2 users have reported success with creating CSL files at this CSL editor webpage.

  • Once you've navigated to this webpage, click on 'Info' and give your style a useful name (e.g., 'Astronomy')

ishot9.jpg

  • After you've created your desired style for citations and bibliographies press the 'Generate CSL' button on the bottom right of the page
  • Copy the CSL that's generated into the TextEdit application on your Mac
  • In the 'Format' menu of TextEdit click on 'Make Plain Text'

ishot7.jpg

  • edit the part with the id tag, to make sure it's unique and descriptive, e.g. <id>alex/journal-irreproducible-results</id>

  • Click on 'File', then 'Save'. Unselect the box at the bottom of the save dialog box that says 'If no text is provided, use '.txt'. Save your file with the .csl extension by manually typing in '.csl' after the name of your file.

ishot8.jpg

  • Move the file into your papers2 library folder using the instructions above making sure you restart Papers2.

####Option 3

A new experimental CSL editor is being currently developed. While still in flux and considered at a beta stage, it has many interesting features that could make it a better fit for CSL editing. If you give it a try, and find it useful, or find bugs, be sure to let the developers know.

The steps necessary to add a style developed with this editor to your Papers library are similar to the ones described in 'Option 2' above.

##Tweaking an existing style

  • If you have a CSL file of a style you'd like to tweak you can load this file into the CSL editor mentioned above and make the changes required.
  • To do this click on 'Load CSL' at the bottom of the page
  • When you're done making changes follow the instructions above to get this style into Papers.