Add citekey variable to csl-data.json and csl-variables.rnc

[denismaier]

Description

This adds citekey to csl-data.json and csl-variables.rnc.

This should make switching from word-processors to plain text based systems (pandoc, latex) easier.

Closes #243

Question

Do we need to add this also to csl-citation.json in addition to id here.

Type of change

Please delete options that are not relevant.

• Variable Addition (adds a new variable or type string)
• This change requires a documentation update

Checklist

• If I modified any of the schema files, I have run trang and/or prettier on the files, per CONTRIBUTING
• I have performed a self-review of my own code
• I have included suggested corresponding changes to the documentation (if relevant)

[bdarcus]

Do we need to add this also to csl-citation.json in addition to id here.

This is related to this question I had: #241?

[bdarcus]

Do you mean to have this in draft?

[denismaier]

Yes, I was thinking we need to settle this here first:

Do we need to add this also to csl-citation.json in addition to id here.

[bdarcus]

Who do we need input from to answer that question? I'm not sure myself.

To make it easier to see the changes, could you please rebase, per here?

You want to do git rebase -i HEAD~2 in your case, though, since you only have two commits on this branch.

[denismaier]

Question was: do we need to add the citekey variable to csl-citation.json? In addition to id.

[bdarcus]

Question was: do we need to add the citekey variable to csl-citation.json?

Yes, but who are we tagging to plea for input?

[denismaier]

@adam3smith @fbennett @dstillman @jgm
What do you think here? Do we need citekey in addition to id in csl-citation.json?

[bdarcus]

I'm saying there is a specific use case for having it in styles: to facilitate transfer between GUI and text-based editors.

Can you briefly explain this, here, or on the linked issue?

[denismaier]

I'm saying there is a specific use case for having it in styles: to facilitate transfer between GUI and text-based editors.

Can you briefly explain this, here, or on the linked issue?

The idea is basically this: You edit in, say Word, with a regular citation style that gives you formatted citations. At some point you decide to switch to a plain-text system, e.g. pandoc . So, you'll switch to a citation style that renders the citation in pandoc's citation syntax: [@doe, 34]. For this, you need to access the citekey that will be used by pandoc.

[bwiernik]

Yes, so for example. I am writing a paper in Word using Zotero. Zotero embeds CSL-JSON into each of its citations. Then, I decide to switch to pandoc. That's currently not easily possible and requires at least a fair number of hacks. What this would let me do is to reformat all of my citations to show the plain-text citation syntax [@doe, 34] and then extract the CSL JSON into one data file (e.g., using https://rintze.zelle.me/ref-extractor/). Then I can copy-paste my text into a text editor or convert the Word document to markdown using pandoc, etc.

[bdarcus]

Thanks.

But couldn't pandoc simply read the embedded citations and convert it to markdown?

In any case, at this point I'm less worried about this than about my last question on the linked issue; the need for both this and citation-label. The only reason I can see ATM for both is if GUI apps need to be able to pre-render citations, and want to store those in that variable.

[bwiernik]

citation-label has nothing to do with citekey at all. There is no connection.

[adam3smith]

The way I understand Bruce's question is that he's asking: if citation-label can be a customizable, human-readable label for a citation, why couldn't it be customizable to be equal to the citekey and thus satisfy the use case.

Am I understanding this correctly?

I think that might technically work, but it's conceptually confusing and requires upstream apps to do some very weird gymnastics in generating the citation label. E.g. if you just allow people to manually specify the citation label, this won't work at all. CSL-JSON will include the manually specified citation label, not the otherwise existing citekey.
If you have auto-generated citation labels that allow for different metadata-based rules (possibly specifiable in the citation style proper), then you'd have to have a completely separate setting for "ignore all rules and just use the citekey".
Finally, to the extent that we are using CSL JSON as some sort of exchange format (and it is being used for that), using a field for two conceptually completely different things seems fraught with issues. I think conflating the two (even if technically possible) would be a bad idea.

[denismaier]

But couldn't pandoc simply read the embedded citations and convert it to markdown?

Maybe pandoc could do it, but I don't know if that's simple. This would most likely be implemented in the reader. There seems to be a function that performs some sort of normalization for fields.
@jgm What do you think?

But, of course, it's not only about pandoc. There's org, latex, etc.

[bdarcus]

@bwiernik:

citation-label has nothing to do with citekey at all. There is no connection.

From the standpoint of CSL design history, this is simply not true.

As I said in that 2009 thread, we added the "citation-label" to put citekey data in. That's the connection.

If you want to say that was a bad decision; that's fine, and in retrospect, I'd agree with you. But we can't ignore that history and legacy.

@adam3smith:

The way I understand Bruce's question is that he's asking: if citation-label can be a customizable, human-readable label for a citation, why couldn't it be customizable to be equal to the citekey and thus satisfy the use case.

Am I understanding this correctly?

Basically, yes.

But per above, I'm also saying that the input citation-label variable IS, already, an implicit alias for citekey.

I think that might technically work, but it's conceptually confusing and requires upstream apps to do some very weird gymnastics in generating the citation label ...

So I think we all agree the confusion is using citation-label to refer to different things on input vs output.

But I don't believe anyone has yet to answer why we can't just do this

1. add citation-key or citekey to the input json
2. remove citation-label from the input json (since it would then serve no purpose for input)
3. add citation-key to the output style

Then documentation would be something like:

• citation-key: the locally-unique human-readable id associated with the entry input data
• citation-label: the human-readable id generated by the CSL processor to associate a formatted citation with its reference entry

[bwiernik]

But I don't believe anyone has yet to answer why we can't just do this

add citation-key or citekey to the input json
remove citation-label from the input json (since it would then serve no purpose for input)
add citation-key to the output style
Then documentation would be something like:

citation-key: the locally-unique human-readable id associated with the entry input data
citation-label: the human-readable id generated by the CSL processor to associate a formatted citation with its reference entry

That's the proposal on the table no, with the understanding that id remains in place as a fallback if citation-key is absent from input?

[bdarcus]

But I thought you said earlier `citation-label` must stay, as is? #243 (comment) That's been the remaining thing that's holding this up for me. Did I misunderstand, or did you change your mind? And the PR doesn't currently remove it on input.

[denismaier]

And the PR doesn't currently remove it on input.

The question is if citation-label will always and without exception be generated by the processor. If so, there's indeed no need for this on the input side of things.

[denismaier]

Concerning:

Do we need to add this also to csl-citation.json in addition to id here.

I wouldn't add it at the moment. In citations I don't really see a need for both. Pandoc or other text-based systems will use citation-key as id, other tools might use id, but in both cases we are just talking about an identificator.

[bdarcus]

And the PR doesn't currently remove it on input.

The question is if citation-label will always and without exception be generated by the processor. If so, there's indeed no need for this on the input side of things.

That's right.

As I may have mentioned, the only reason I can see for it is in a GUI app that wants to store the rendered label for some reason.

[bdarcus]

We can remove label on input on a separate PR, if needed.