Magic Manuscripts Syntax References

This is a list of info you can refer to...

It's based on these three articles, pasted end to end:

http://support.mekentosj.com/kb/tutorials/papers-21-new-developments-in-magic-manuscripts
http://support.mekentosj.com/kb/read-write-cite/citations-modifiers-prefix-suffix-page-number-authoryear-suppression
http://support.mekentosj.com/kb/read-write-cite/whats-new-in-magic-manuscripts-in-papers-21




http://support.mekentosj.com/kb/read-write-cite/whats-new-in-magic-manuscripts-in-papers-21


Papers 2.1: New Developments in Magic Manuscripts

Magic Manuscripts is a revolutionary new way to cite articles using Papers. As we continue to develop new features and add to existing features, we added more functionality to Magic Manuscripts in Papers2.1.

Adding citations to your manuscripts has never been this flexible. Here is an overview of the main differences in how you can edit your citations:

  • Modify citekeys: You can add text before or after your cite keys. For example, that turns this cite key {Reips:2011jz} into {According to Reips:2011jz}. When you format your manuscript, Papers will turn this citation into (According to Reips & Garaizar, 2011), although final formatting depends on the citation style you chose.

    • Similarly, you can add page numbers to your cite key. E.g. {Smith:2011bl} becomes {Smith:2011bl p. 221}.
    • Author suppression is now possible. Add a * before the author's name in the cite key to suppress the name, or a * after the year to suppress the year. For example if you would like to add a citation like "...as shown by Smith (1997)", you can do so by adding a * prior to the name in the cite key "...as shown by Smith {*Smith:1997ww}".
    • Year suppression: If you would like to create a citation like "...as shown in 1997 (Smith)", you can do so my adding a * after the year ("...as shown in 1997 {Smith:1997ww*}").
    • If you would like to suppress both the name and year, you can combine the two concepts above: ...as shown by Smith in 1997 {*Smith:1997ww*}. This is useful when you want to create a citation like "As shown by Smith in 1997". Suppressing both the author and year avoids Papers adding in "(Smith, 1997)" in the text when it is not really appropriate in the context of the citation, but does still include this citation in the bibliography.
  • Papers can merge consecutive cite keys. For example, you might start a sentence in your manuscript as follows: "As has been shown in the literature {Smith:2011jz}", and then decide to add more cite keys: "As has been shown in the literature {Smith:2011jz}{Jones:2010ab}{Close:2011hg}". Once you format the manuscript, this now becomes "As has been shown in the literature (Smith, 2011; Jones, 2010; Close, 2011)"

  • Now you can unformat manuscripts, if you would like. After formatting the manuscript, this is now an option: 

  • Previously it was not possible to recognize text based cite keys in Word. We've worked around this issue and it is now possible to copy and paste a cite key into word, and Magic Manuscripts will recognize it. You can copy and paste cite keys from other applications, and you can drag/copy articles from Papers as a cite key by selecting this option in Papers -> Preferences -> Papers:

To see all new additions in Papers2.1, see our release notes.





















http://support.mekentosj.com/kb/read-write-cite/whats-new-in-magic-manuscripts-in-papers-21

What's new in Magic Manuscripts in Papers 2.1?

A complete and detailed list of all the changes and bug fixes in Papers 2.1 can be found in the release notes. This document gives an overview of the new features specific to Magic Manuscripts, with some more information and more context than the release notes.

Copy As Magic Citation

In Papers 2.0, we introduced 'Magic Manuscripts', an incredibly easy user interface to insert citations and format a manuscript, that does not requires you to leave the keyboard, or leave your text editor, and does not require you to install anything, and yet supports a wide variety of applications. Magic Manuscripts is always ready when you need it: press the control key twice, and you're ready to query your Papers library. Press enter a couple of times, the reference is inserted. You can focus on your manuscript, on the content and the ideas.

We found that the above workflow covers a lot of what our users do. But there are still cases where you have the publications to cite right there in Papers, maybe even already organized in a collection. In such cases, the Magic Manuscripts floating window can actually be superfluous and add friction. In Papers 2.1, we add an alternative workflow in the main Papers app itself, and introduce 'Magic Citation'. Here is how it works:

  • Switch to Papers
  • Select a paper, or multiple papers
  • Select the menu item Edit > Copy As... > Magic Citation (alt-cmd-M)
  • Switch back to your text editor
  • Paste in your manuscript
  • etc...

You can also change the settings in your preferences to 'Drag Papers as Magic Citation' (available in the 'Papers' pane), in which case you can also drag papers directly into your text editor, and get a Magic Citation inserted. With that setting, the 'Copy' menu item can also be used (cmd-C).

The 'Copy As... Magic Citation' coexists peacefully with the equivalent menu item 'Copy As... BibTeX command' (alt-cmd-C). But BibTeX users will also be happy to learn that the latter is now consistent with the citkey format selected in the Manuscripts preferences. Depending on that setting, the menu item will copy a \cite command, a \citep command, or even a ConTeXt, Pandoc or MMD citation. The same options are then also available in the 'Drag Papers as' setting in the preferences.

Citation Modifiers: Prefix, Suffix, Author Suppression, Year Suppression

The syntax and the use of citation modifiers are described in more details in a separate document. Here is a quick overview of how those modifiers can be added to the 'raw' citekey, and how it will look after formatting:

  • Prefix, Suffix and Page Number

    before formatting

    ... as shown before {see Smith:1997tu for stunning proof p.89}, birds can fly ...

    after formatting

    ... as shown before (see Smith, 1997, page 89 for stunning proof), birds can fly ...

  • Author and Year Suppression

    before formatting

    ... as shown by Smith {*Smith:1997tu} & in 1999 {Doe:1999kl*}, ...

    after formatting

    ... as shown by Smith (1997) & in 1999 (Doe), birds can fly ...

Unformat Manuscript in MS Word

Papers 2.1 introduces the new action 'Unformat Manuscript' when you are using Microsoft Word to edit your manuscript. This action can be used after formatting a manuscript to go back to the 'raw' citekeys that are normally inserted by the 'Insert Citation' action.

For instance, ayou may have the citation appearing in your formatted manuscript as follows:

"...[1]...[2-4]...[5]...etc..."

This may not be very useful if you need to do some more editing , and want to know what the citation numbers correspond to. The 'Unformat Manuscript' action will revert the cites to the 'Magic Citation' format:

"...{Smith:1997tu}...{Doe:1999kl, Doe:2010gt}, Dupont:2011vi}...{Smith:1992uv}...etc..."

Unformatting the manuscript can be useful for various reasons:

  • better see what you are citing, as the first author and year are clearly displayed
  • copy-paste or export the text to another application, like Pages or TextEdit, where Papers will also be able to recognize the citekeys
  • allow editing or addition of citation modifiers, like the prefix or page numbers
  • it will allow editing of the citekey themselves, like adding a citekey, removing one, copying a citekey, etc...
  • it will also allow collaborators and co-authors to edit the citekeys and modifiers, even if they don't use Papers

Note: if you had formatted the manuscript prior to Papers 2.1, you may first need to choose the 'Format Manuscript' action again, and thus reformat the manuscript, before 'Unformat Manuscript' is available.

Add Journal Style

You may or may not know it, but Papers relies on the fantastic CSL style repository to support formatting of your manuscript in hundreds of different styles (more than 1700 in Papers 2.1.8). Despite this large choice, your favorite journal may not be listed there. One option is to create your own CSL style, as described in another post on our support pages.

However, in many cases, there is already a style in Papers that conforms to the requirements of the journal. For instance, let's say you are writing a paper to be published in the Journal of Irreproducible Results. After reading the instruction to authors, you find that you can use the APA style. It's easy to use this style, but you'll have to remember from now on that for JIR, you'll need to use APA. It would be easier if the name of the style was simply the name of the journal. You already have enough on your mind with that manuscript and your irreproducible results, and you don't need one more thing that can go wrong.

In Papers 2.1, we added a very simple interface to copy an existing style, and give it its own name. It is not a full-blown style editor, but it can cover a lot of simple cases and make your life easier:

  • Go into the Papers Preferences...Manuscripts
  • Click on the popup menu 'Favorite Styles' and select 'More Styles...'
  • This will open the Style Browser
  • Select the style you would like to duplicate
  • Click the 'Duplicate Selected Style' button
  • Type the name you want to give to the new style
  • Click 'Add'

duplicate-csl-style.png

Citekey Formats

With Papers 2.1, new citekey formats become available and join the previous formats in the popup menu in the Manuscripts preferences.

  • Available since Papers 2.0:

    • Papers Magic Citation

      output: ...{Smith:1997tu}...

    • BibTeX \cite and \citep Command

      output: ...\cite{Smith:1997tu}...\citep{Smith:1997tu}...

  • New with Papers 2.1:

    • ConTeXt \cite command

      output: ...\cite[Smith:1997tu]...

    • Pandoc citation

      output: ...[@Smith:1997tu]...

    • MMD citation – 3 different options

      output: ...[Smith:1997tu]...[Smith:1997tu][]...[][Smith:1997tu]...






















































































































































































http://support.mekentosj.com/kb/read-write-cite/citations-modifiers-prefix-suffix-page-number-authoryear-suppression

Citations Modifiers: Prefix, Suffix, Page Number, Author/Year

 Suppression

Starting with Papers 2.1, Magic Manuscripts recognizes various citation modifiers, that allow the addition of a prefix, suffix or page number, and allow author or year suppression. This document describes their syntax and their use.

This page is only relevant if you use the standard 'Papers Magic Citation' format. If you use another format, as set in the 'Manuscripts' preferences in Papers, then this document is not relevant. Instead, you should use whatever syntax is supported by that format (like BibTeX, MMD, Pandoc or ConTeXt).

All the features and behaviors described here are available in Papers 2.1 and later, but not in earlier versions Papers 2.0.x.

Syntax

All the examples below assume you have citations already inserted in your manuscript, either using the floating 'Magic Manuscripts' window and search, or using the menu item 'Copy as... Magic Citation' in the main Papers application. This is where the citekey {Smith:1997tu} comes from. The exact formatting of the citation used in the examples depends also on the journal style applied to the manuscript: the output after formatting will be different for different styles (the example is APA).

  • No modifier:

    before formatting

    ... as shown before {Smith:1997tu}, birds can fly ...

    after formatting

    ... as shown before (Smith, 1997), birds can fly ...

  • Prefix

    before formatting

    ... as shown before {see Smith:1997tu}, birds can fly ...

    after formatting

    ... as shown before (see Smith, 1997), birds can fly ...

  • Suffix

    before formatting

    ... as shown before {Smith:1997tu and common sense}, birds can fly ...

    after formatting

    ... as shown before (Smith, 1997 and common sense), birds can fly ...

  • Page number

    before formatting

    ... as shown before {Smith:1997tu p.89}, birds can fly ...

    after formatting

    ... as shown before (Smith, 1997, page 89), birds can fly ...

    Note: you can also use other variants like 'p89', 'p 89', 'pp89-100', 'pp.89-100', 'pp. 89-100'

  • Author suppression

    before formatting

    ... as shown by Smith {*Smith:1997tu}, birds can fly ...

    after formatting

    ... as shown by Smith (1997), birds can fly ...

  • Year suppression

    before formatting

    ... as shown in 1997 {Smith:1997tu*}, birds can fly ...

    after formatting

    ... as shown in 1997 (Smith), birds can fly ...

Tips, Tricks and Limitations

  • You can combine several modifiers

    before formatting

    ... as shown by Smith {for instance *Smith:1997tu p.89}, birds can fly ...

    after formatting

    ... as shown by Smith (for instance 1997, page 89), birds can fly ...

  • You can use it with multi-paper citations

    before formatting

    ... as shown before {see Smith:1997tu, Wang:1998kp}, birds can fly ...

    after formatting

    ... as shown before (see Smith, 1997 & Wang, 1998), birds can fly ...

  • You can escape a comma by using a double-comma (otherwise, the comma would be intepreted as a cite delimiter)

    before formatting

    ... as shown in 1997 {for instance,, Smith:1997tu*}, birds can fly ...

    after formatting

    ... as shown in 1997 (for instance, Smith), birds can fly ...

  • You should add a space between the citekey and subsequent punctuation when applicable, and the space will be removed when formatted:

    before formatting

    ... as shown in 1997 {Smith:1997tu* ,, for instance}, birds can fly ...

    after formatting

    ... as shown in 1997 (Smith, for instance), birds can fly ...

  • The citekey is identified by Papers as the only word that contains a ':', or if no ':' is found, the last word. For non-standard citekeys that don't include a ':' character and that are not at the end of the cite, you can use quotes to clearly indicate where the citekey is:

    before formatting

    ... as shown in 1997 {see "Smith_on_birds*" or common sense}, birds can fly ...

    after formatting

    ... as shown in 1997 (see Smith or common sense), birds can fly ...

    Note: as an alternative to double quotes, you can use single quotes or the slash sign:

    ... as shown in 1997 {see 'Smith_on_birds*' or common sense}, birds can fly ... ... as shown in 1997 {see /Smith_on_birds*/ or common sense}, birds can fly ...

  • Because of the special role for the colon character ':' in citekey recognition, you might need to take some extra steps to "escape" that character when it is part of the prefix or suffix. For this, you can use quotes around the citekey to clearly identify it, and thus clearly mark that the other characters of the cite are to be considered part of the prefix or suffix:

    before formatting

    ... as shown in 1997 {see "Smith:1997tu*" : 86}, birds can fly ...

    after formatting

    ... as shown in 1997 (see Smith:86), birds can fly ...

  • Modifiers are recognized separately for each cited paper. In some styles, the order of the papers in the citation will be adjusted based on the specification, for example to have the earliest paper first. If the prefix is used on the first citekey, and if the corresponding paper move to another position, then the prefix will follow, which might not be what you intended:

    before formatting

    ... as shown before {see Wang:1998kp, Smith:1997tu}, birds can fly ...

    after formatting

    ... as shown before (Smith, 1997 & see Wang, 1998), birds can fly ...

  • Page numbers can only contain digits and dashes/hyphens. Other types of page numbers can still be added as a suffix. In this case, the CSL style rules for the page locator won't be applied, but that can simply be worked around by making sure the suffix follows the style specifications:

    before formatting

    ... as shown before {Smith:1997tu ,, page A1-A8}, birds can fly ...

    after formatting

    ... as shown before (Smith, 1997, page A1-A8), birds can fly ...

  • Only page locators are supported, but not other locators like chapter, verse,... Again, they can still be added as a suffix. In this case, the CSL style rules for the locator won't be applied, but that can simply be worked around by making sure the suffix follows the style specifications:

    before formatting

    ... as shown before {Smith:1997tu ,, chapter 2}, birds can fly ...

    after formatting

    ... as shown before (Smith, 1997, chapter 2), birds can fly ...

Text editors

  • Pages, TextEdit, and other plain text editors. For all the applications that you can use in conjunction with Papers to format a bibliography, adding a modifier is as simple as typing text. You just need to follow the syntax described above, and be aware of the few tricks and limitations mentioned. If you have used Magic Manuscripts before, you will know that there are always 2 versions of your manuscript: the raw unformatted version, and the formatted version (except Microsoft Word, see below). The unformatted version is the document you'll need to edit to add the modifiers. It is the document that contains the citekeys. The unformatted version is used as the template to generate the formatted version when you choose the 'Format Manuscript' action.

    Remember that the final formatted version should in general not be edited. Additional changes in the final formatted version will not be taken into account the next time you format again, and will have to be added back.

  • Micrsoft Word. Magic Manuscripts works differently with Microsoft Word. Citations are created as 'fields', that can contain both visible text (either the citekey, or the formatted citation), and invisible content. The invisible content is used by Magic Manuscripts to keep track of which citation is which. As a result, it can safely edit the visible text, and still keep the necessary information in the invisible data to later apply a different format. In other words, the process of formatting the manuscript is reversible.

    In Microsoft Word, you can add citation modifiers the same way as in other apps, by directly editing the citekey to add the prefix, suffix, etc... as described in the syntax above. Again, it's as simple as adding text. However, you cannot add those modifiers if the manuscript has already been formatted, and the citekeys have been replaced with the formatted citation. You will need to revert back to the 'raw' citekey output. For instance, you should not try to add a prefix if you have already '(Smith & Doe, 1991)', but only if you have the raw citekey '{Smith:1991tu}'. Edits you make in the formatted citation '(Smith & Doe, 1991)' will be overwritten the next time you format the manuscript again.

    It is very easy to revert to the raw citekeys, though. For this, you can use the action to 'Unformat Manuscript' (see more info in the document "What's new in Magic Manuscripts in Papers 2.1?". After unformatting the manuscript, the fields will again contain the original citekeys like '{Smith:1991tu}', and you can edit the citekeys and add modifiers. After you format the manuscript again, the modifiers will appear in the formatted citations. You can format and unformat as many times as you want, and the modifiers will be safely stored and restored as needed.

    Note: if you had formatted the manuscript prior to Papers 2.1, you may first need to choose the 'Format Manuscript' action again, and thus reformat the manuscript, before 'Unformat Manuscript' is available.















































    Comments