New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
njbart opened this Issue Oct 11, 2014 · 15 comments

Comments

5 participants
@njbart

njbart commented Oct 11, 2014

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

This comment has been minimized.

Show comment
Hide comment
@wcaleb

wcaleb Oct 11, 2014

Contributor

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

Contributor

wcaleb commented Oct 11, 2014

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

This comment has been minimized.

Show comment
Hide comment
@njbart

njbart Oct 15, 2014

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)

njbart commented Oct 15, 2014

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

This comment has been minimized.

Show comment
Hide comment
@wcaleb

wcaleb Oct 15, 2014

Contributor

@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?

Contributor

wcaleb commented Oct 15, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@denten

denten Oct 20, 2014

Contributor

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

Contributor

denten commented Oct 20, 2014

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

This comment has been minimized.

Show comment
Hide comment
@njbart

njbart Nov 26, 2014

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

njbart commented Nov 26, 2014

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 added a commit that referenced this issue Nov 26, 2014

@wcaleb

This comment has been minimized.

Show comment
Hide comment
@wcaleb

wcaleb Nov 26, 2014

Contributor

I moved the period outside the brackets.

Contributor

wcaleb commented Nov 26, 2014

I moved the period outside the brackets.

@Jmuccigr

This comment has been minimized.

Show comment
Hide comment
@Jmuccigr

Jmuccigr Mar 17, 2015

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

Jmuccigr commented Mar 17, 2015

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

This comment has been minimized.

Show comment
Hide comment
@gwijthoff

gwijthoff Mar 17, 2015

@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 ?

gwijthoff commented Mar 17, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@Jmuccigr

Jmuccigr Mar 17, 2015

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 commented Mar 17, 2015

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

This comment has been minimized.

Show comment
Hide comment
@Jmuccigr

Jmuccigr Mar 17, 2015

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.

Jmuccigr commented Mar 17, 2015

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

This comment has been minimized.

Show comment
Hide comment
@njbart

njbart Mar 26, 2015

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

njbart commented Mar 26, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@Jmuccigr

Jmuccigr Mar 26, 2015

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

Jmuccigr commented Mar 26, 2015

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

This comment has been minimized.

Show comment
Hide comment
@njbart

njbart Mar 27, 2015

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

njbart commented Mar 27, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@Jmuccigr

Jmuccigr Mar 27, 2015

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

Jmuccigr commented Mar 27, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@denten

denten Mar 27, 2015

Contributor

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.

Contributor

denten commented Mar 27, 2015

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment