pandoc citation syntax issue in "Sustainable Authorship ..."

[njbart]

In http://programminghistorian.org/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown you suggest using the following

Some sentence that needs citation.^[@fyfe_digital_2011 argues that too.]

This is not recommended since it keeps you from switching easily between footnote and author-date styles. Better use the following (no circumflex, no final period inside the square braces, and the final punctuation of the text sentence after the square braces; with footnote styles, pandoc automatically adjusts the position of the final punctuation):

Some sentence that needs citation [@fyfe_digital_2011 argues that too].

[wcaleb]

Thanks for noting this. But wouldn't best practice be just to wrap the citation key in square brackets? I.e,

Some sentence that needs citation.^[[@fyfe_digital_2011] argues that too.]

[njbart]

Unless you insist on producing a footnote, even with a
parenthetical/author-date referencing style: No.

On 11/10/2014, W. Caleb McDaniel notifications@github.com wrote:

Thanks for noting this. But wouldn't best practice be just to wrap the
citation key in square brackets? I.e,

Some sentence that needs citation.^[[@fyfe_digital_2011] argues that too.]

Sent from my iPhone

On Oct 11, 2014, at 2:27 PM, nickbart1980 notifications@github.com
wrote:

In
http://programminghistorian.org/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown
you suggest using the following

Some sentence that needs citation.^[@fyfe_digital_2011 argues that too.]
This is not recommended since it keeps you from switching easily between
footnote and author-date styles. Better use the following (no circumflex,
no final period inside the square braces, and the final punctuation of the
text sentence after the square braces; with footnote styles, the position
of the final punctuation is adjusted appopriately):

Some sentence that needs citation [@fyfe_digital_2011 argues that too].
—
Reply to this email directly or view it on GitHub.

---

Reply to this email directly or view it on GitHub:
#46 (comment)

[wcaleb]

@denten @gwijthoff Could you take a look at this part of your lesson and suggest (or PR) a revision that will account for these issues?

[denten]

I filed a pull request. Let me know if that worked.

On Wed, Oct 15, 2014 at 11:02 AM, W. Caleb McDaniel <
notifications@github.com> wrote:

@denten https://github.com/denten @gwijthoff
https://github.com/gwijthoff Could you take a look at this part of your
lesson and suggest (or PR) a revision that will account for these issues?

—
Reply to this email directly or view it on GitHub
#46 (comment)
.

[njbart]

Just spotted that it's not fully fixed yet; now the webpage says:

Some sentence that needs citation [@fyfe_digital_2011 argues that too.]

(Try this with any author-year or footnote style to see why it does not work.)

It should be:

Some sentence that needs citation [@fyfe_digital_2011 argues that too].

[wcaleb]

I moved the period outside the brackets.

[Jmuccigr]

I'm still looking into this, but it seems that this kind of note gets turned into a footnote by pandoc-cite only when it has a reference in it. When it doesn't, it gets left completely alone. So
This is a sentence.[This is a comment on the sentence.]
gets left completely alone. So if you want the simple text w/o a reference to be a footnote, it needs a leading ^.

[gwijthoff]

@Jmuccigr is right. I guess I don't see why our originally suggested format is an impediment to easily switching between footnotes and author-date citations. If you want an in text author-date citation, you just use brackets [@fyfe_digital_2011]. If you have explanatory text to go along with that source, you add a caret and make it a footnote.^[@fyfe_digital_2011 has some explaining to do.] Have a journal that needs a different citation style? Specify the .csl in your YAML and nothing about your markup needs to change -- both brackets and brackets with a leading caret are interpreted as footnotes if Chicago style is specified. Am I missing something, @nickbart1980 ?

[Jmuccigr]

For me what's pesky about the in-line, no-carat method is that it leaves all the notes mixed in with the text, which defeats the purpose of the caratted links that can go at the end of the doc (or paragraph or whatever).

Is there a way to maintain the convenience of not committing to footnotes (i.e., the in-line go-carat method) without keeping everything in-line?

It's also a little bothersome for me that my editor, MacDown, does a nice job with the carats, but leaves the no-carat text alone. Haven't looked into that at all yet.

[Jmuccigr]

Sorry for the double-post…it occurred to me that the ideal would be one type of note. Having to remember to watch the carat as you're editing is extra work.

So that would mean that pandoc-citeproc would handle no-citation references as well as it handles the citation-possessing ones.

[njbart]

@gwijthoff:

Am I missing something […]?

Yes. If you use Foo [@doe2000, p. 22]. or, with explanatory text, Foo [see @doe2000, p. 22, with case studies; but see @roe2015, pp. 33–34, who disagrees]., you can use any CSL style you want, it will always be rendered correctly without ever changing the markdown source. As soon as you start hardcoding footnotes, you lose this advantage. What's worse, if you use ^[@doe] together with a CSL footnote style, you will get format errors (capitalisation, punctuation, etc.). [EDIT: Since, quite obviously, you’re trying to insert a footnote in a footnote here.] pandoc just isn't designed for this kind of thing.

[Jmuccigr]

Yes, but you have to hard-code footnotes when they don't contain or immediately follow citations.

Footnotes without citations are hardly unusual, yet pandoc leaves [some text] alone at the same time as it processes [some text @citation]. That means that you really have no choice but to manually indicate footnotes without citations.

Or am I missing something?

(I'm trying to avoid pointing out that pandoc is breaking markdown with its treatment of citations inside square brackets.)

[njbart]

@Jmuccigr: Sorry, like it or not, these are the facts. If you really need to use many notes without citations and switch between parenthetical and footnote styles so frequently, I'm sure you could use ^[Bla.] footnotes for notes without citations as a default, and write a filter to map all ^[Bla.] to  (Bla.) whenever you want to use a style without footnotes.

[Jmuccigr]

@nickbart1980: I actually don't typically use in-line citation formats, so that's not an issue for me.

I'm not sure that we're disagreeing. It's simply a limitation that when writing notes without citations - which is a fairly common occurrence for me - it's necessary to force them to be footnotes with a carat. If they were to be parenthetical comments (like this one), I would just use parentheses directly without square brackets in the first place.

I like the idea of writing style-agnostic notes, which the simple square-bracket methods affords. Besides the fact that citation-less notes get ignored, the other thing I'm not a fan of is what these in-line notes do to the readability of my markdown. For that reason, I like the [^notemarker] method with the notes themselves down at the bottom of the doc. That keeps the text readable.

[denten]

Based on this thread I think [@fyfe_digital_2011 argues that too]. as is currently listed in the tutorial is the correct recommendation. The fact that [some note] does nothing is an issue for Pandoc and likely will be affected by Common Mark (see Example 387).Thank you everybody for a productive discussion.