Question about citation processors [wip-cite branch]

Question about citation processors [wip-cite branch]

[Joost Kremers]

Hi list,

As the maintainer of Ebib, I have of course been following the threads on
citation support for Org with some interest. I have not been able to follow
every detail, however, in part probably due to my limited experience with CSL
and citeproc. (I use biblatex myself.)

Now I find myself with some specific questions that I cannot find an answer to.
(Possibly because I'm just daft enough to overlook them in the e-mails Nicolas
sent, but in that case feel free to point this out.)

So, on the assumption that there are Org users out there that may want to use
Ebib to manage their citations, what would Ebib need to do in order to be a good
citizen?

- A user should be able to insert citations into an Org document. IIUC nothing
  in org-cite provides any functionality for this, right? Is there a default
  list of styles a user would expect to be supported, or does this depend solely
  on the bibliography style one uses?

- =:active= just means "font-lock", right?

- Since I don't plan on writing an exporter, I assume that it is possible to
  mix and match processors? Say, have one for the =:follow= property, another
  for =:activate= and a third one for =:export-*=?

- What kind of data structure do the =:follow= and =:activate= functions take?
  Should I just look at =oc-basic.el= or is this written down somewhere?

- Is there a function or buffer-local variable that gives me a list of all the
  bibliography files of a buffer? Related to that: if a user has set
  =org-cite-global-bibliography= and also provides a =#+bibliography= keyword,
  are both sources used, or only the keyword?

Thanks for any and all comments!

-- 
Joost Kremers
Life has its moments

Re: Question about citation processors [wip-cite branch]

[Bruce D'Arcus]

On Tue, May 4, 2021 at 9:27 AM Joost Kremers <joostkremers@fastmail.fm> wrote:

> - A user should be able to insert citations into an Org document. IIUC nothing
>   in org-cite provides any functionality for this, right? Is there a default
>   list of styles a user would expect to be supported, or does this depend solely
>   on the bibliography style one uses?

I'll just comment on this Joost.

Correct on your first question.

As for your second, that's what the activity today is about. TBD, but
it seems there's some good ideas on that.

I tried to put this together into this wiki page, because doing it on
an email list is hard.

https://github.com/bdarcus/bibtex-actions/wiki/Org-cite

Bruce

Re: Question about citation processors [wip-cite branch]

[Joost Kremers]

On Tue, May 04 2021, Bruce D'Arcus wrote:
> On Tue, May 4, 2021 at 9:27 AM Joost Kremers <joostkremers@fastmail.fm> wrote:
>
>> - A user should be able to insert citations into an Org document. IIUC nothing
>>   in org-cite provides any functionality for this, right? Is there a default
>>   list of styles a user would expect to be supported, or does this depend
>> solely
>>   on the bibliography style one uses?
>
> I'll just comment on this Joost.

Thanks. :-)

> Correct on your first question.

ACK

> As for your second, that's what the activity today is about. TBD, but
> it seems there's some good ideas on that.
>
> I tried to put this together into this wiki page, because doing it on
> an email list is hard.
>
> https://github.com/bdarcus/bibtex-actions/wiki/Org-cite

I can add some comments regarding biblatex:

- default: \parencite[1]
- text: \textcite
- author: \citeauthor[2] 
- title: \citetitle[2]
- year: \citeyear[2]
- locators: \notecite[3]
- nocite: \nocite

Biblatex of course has a wealth of citation commands, most with variants of
different kinds. Not sure if that's relevant right now.

HTH

Joost



Footnotes:
[1] Note that biblatex also has \cite, which produces a citation without
     parentheses. But the natbib column has \citep here, so \parencite seems
     appropriate.

[2]  The biblatex manual states that this does not do "citation tracking",
     though what this implies is not clear to me.

[3]  There are variants \pnotecite and \fnotecite for parenthetical and
     footnote citations, respectively.

-- 
Joost Kremers
Life has its moments

Re: Question about citation processors [wip-cite branch]

[Bruce D'Arcus]

On Tue, May 4, 2021 at 10:47 AM Joost Kremers <joostkremers@fastmail.fm> wrote:

> I can add some comments regarding biblatex:
>
> - default: \parencite[1]

WDYT of \autocite for default?

It's conceptually the same as the CSL default.

> - text: \textcite
> - author: \citeauthor[2]
> - title: \citetitle[2]
> - year: \citeyear[2]
> - locators: \notecite[3]
> - nocite: \nocite

I will add these to the markdown, and include an org version of it to
the list when it is done-ish.

Thanks!

> Biblatex of course has a wealth of citation commands, most with variants of
> different kinds. Not sure if that's relevant right now.

Yes, why I like Nicolas' idea to allow sub-styles.

[cite/text/bar:@doe]

Bruce

Re: Question about citation processors [wip-cite branch]

[Bruce D'Arcus]

One other little thing:

On Tue, May 4, 2021 at 10:47 AM Joost Kremers <joostkremers@fastmail.fm> wrote:

> - locators: \notecite[3]

Are you sure about this?

Here's the use case:

https://github.com/jgm/pandoc/issues/7205

Bruce

Re: Question about citation processors [wip-cite branch]

[Joost Kremers]

On Tue, May 04 2021, Bruce D'Arcus wrote:
> One other little thing:
>
> On Tue, May 4, 2021 at 10:47 AM Joost Kremers <joostkremers@fastmail.fm> wrote:
>
>> - locators: \notecite[3]
>
> Are you sure about this?

Well, no, I hadn't tried it... I did mention there were variants, though. ;-)

> Here's the use case:
>
> https://github.com/jgm/pandoc/issues/7205

In order to get:

```
According to Jones (1998) , “students often had difficulty using APA
style, especially when it was their first time” (p. 199).
```

i.e., with parentheses around the locator, you need to use \pnotecite:

```
According to \textcite[]{Jones1998} , ``students often had difficulty using APA
style, especially when it was their first time'' \pnotecite[][199]{Jones1998}.
```

\notecite gives the locator without parentheses.

-- 
Joost Kremers
Life has its moments

Re: Question about citation processors [wip-cite branch]

[Joost Kremers]

On Tue, May 04 2021, Bruce D'Arcus wrote:
> On Tue, May 4, 2021 at 10:47 AM Joost Kremers <joostkremers@fastmail.fm> wrote:
>
>> I can add some comments regarding biblatex:
>>
>> - default: \parencite[1]
>
> WDYT of \autocite for default?
>
> It's conceptually the same as the CSL default.

If that is the case then it's probably the better choice. The biblatex manual
states that \autocite requires that the citation style defines a command for it
and that it is not appropriate for author-year style citations. I assume that's
something for the user to be aware of when using such citations?

-- 
Joost Kremers
Life has its moments

Re: Question about citation processors [wip-cite branch]

[Bruce D'Arcus]

On Tue, May 4, 2021 at 11:26 AM Joost Kremers <joostkremers@fastmail.fm> wrote:

> In order to get ... parentheses around the locator, you need to use \pnotecite:
> ...
> \notecite gives the locator without parentheses.

Ah, right then.

I updated the wiki table with that.

This is an example where sub-styles could be helpful.

Bruce

Re: Question about citation processors [wip-cite branch]

[Nicolas Goaziou]

Hello,

Joost Kremers <joostkremers@fastmail.fm> writes:

> - A user should be able to insert citations into an Org document. IIUC nothing
>   in org-cite provides any functionality for this, right? Is there a default
>   list of styles a user would expect to be supported, or does this depend solely
>   on the bibliography style one uses?

Org Cite does not provide anything in that area because there nothing to
provide. You can write your own function inserting citations without
plugging it anywhere in Org. For others capabilities (activate, follow,
export), you need Org to cooperate.

If you think my assumption is incorrect, please let me know what kind of
hook would be required.

> - =:active= just means "font-lock", right?

Yes, with the emphasis that more than faces could be provided (e.g.,
help-echo, specific keymap, …). I think that Org Ref only needs this
property (barring its export part).

> - Since I don't plan on writing an exporter, I assume that it is possible to
>   mix and match processors? Say, have one for the =:follow= property, another
>   for =:activate= and a third one for =:export-*=?

Exactly! A processor may only provide an :activate property.

> - What kind of data structure do the =:follow= and =:activate= functions take?
>   Should I just look at =oc-basic.el= or is this written down
>   somewhere?

Processors must be registered using `org-cite-register-processor'
function from "oc.el". See its docstring for details. All arguments are
detailed.

As an example, "oc-basic.el" is a citation processor. It calls the
function above at the end of the file and registers all three
capabilities (activate, follow and export).

At some point, we will need to write some documentation in the manual,
too...

> - Is there a function or buffer-local variable that gives me a list of all the
>   bibliography files of a buffer? Related to that: if a user has set
>   =org-cite-global-bibliography= and also provides a =#+bibliography= keyword,
>   are both sources used, or only the keyword?

"oc.el" provides a number of hopefully useful tools. Among them,
`org-cite-list-bibliography-files' function returns what you're asking
for. Global variable and keywords are cumulative.

HTH!

Regards,
-- 
Nicolas Goaziou

Re: Question about citation processors [wip-cite branch]

[Joost Kremers]

Hi Nicolas,

On Tue, May 04 2021, Nicolas Goaziou wrote:
> If you think my assumption is incorrect, please let me know what kind of
> hook would be required.

No, I don't think there's anything Org should provide. I just wanted to be sure
I hadn't missed anything.

>> - =:active= just means "font-lock", right?
>
> Yes, with the emphasis that more than faces could be provided (e.g.,
> help-echo, specific keymap, …).

Ah, that's good to know. I hadn't realised that.

>> - What kind of data structure do the =:follow= and =:activate= functions take?
>>   Should I just look at =oc-basic.el= or is this written down
>>   somewhere?
>
> Processors must be registered using `org-cite-register-processor'
> function from "oc.el". See its docstring for details. All arguments are
> detailed.

The docstring talks about a "citation object", and the "citation or citation
reference object at point". Do I assume correctly that these are structures as
returned by =org-element-parse-buffer=?

> At some point, we will need to write some documentation in the manual,
> too...

For the moment, I can follow the lead in =oc-basic.el= and do what it does.

> "oc.el" provides a number of hopefully useful tools. Among them,
> `org-cite-list-bibliography-files' function returns what you're asking
> for. Global variable and keywords are cumulative.

Great, thanks!

> HTH!

Yes, this was certainly very helpful. Thank you for your answer and thank you
for all the hard work you've put in.

The same goes for everyone else who put time and effort into making org-cite
happen, of course. :-)

-- 
Joost Kremers
Life has its moments

Re: Question about citation processors [wip-cite branch]

[Denis Maier]

Am 04.05.2021 um 17:27 schrieb Joost Kremers:
> 
> On Tue, May 04 2021, Bruce D'Arcus wrote:
>> On Tue, May 4, 2021 at 10:47 AM Joost Kremers <joostkremers@fastmail.fm> wrote:
>>
>>> I can add some comments regarding biblatex:
>>>
>>> - default: \parencite[1]
>>
>> WDYT of \autocite for default?
>>
>> It's conceptually the same as the CSL default.
> 
> If that is the case then it's probably the better choice. The biblatex manual
> states that \autocite requires that the citation style defines a command for it
> and that it is not appropriate for author-year style citations. I assume that's
> something for the user to be aware of when using such citations?

Well, IIRC, in author-year styles \autocite is equivalent to \parencite. 
I think, what the manual talks about is not that \autocite wouldn't be 
appropriate for author-year styles, but rather that relying /solely/ on 
\autocite doesn't give authors the flexibility they might want in these 
styles, like when you want something like in your example:
```
According to \textcite[]{Jones1998} , ``students often had difficulty 
using APA
style, especially when it was their first time'' 
\pnotecite[][199]{Jones1998}.
```

So, I think \autocite is the better choice.

Denis

Re: Question about citation processors [wip-cite branch]

[Joost Kremers]

On Tue, May 04 2021, Denis Maier wrote:
> Well, IIRC, in author-year styles \autocite is equivalent to \parencite. I
> think, what the manual talks about is not that \autocite wouldn't be appropriate
> for author-year styles, but rather that relying /solely/ on \autocite doesn't
> give authors the flexibility they might want in these styles, 

Yes, I did a quick test and you're right.

> So, I think \autocite is the better choice.

Yes.

-- 
Joost Kremers
Life has its moments

Re: Question about citation processors [wip-cite branch]

[Nicolas Goaziou]

Hello,

Joost Kremers <joostkremers@fastmail.fm> writes:

> The docstring talks about a "citation object", and the "citation or citation
> reference object at point". Do I assume correctly that these are structures as
> returned by =org-element-parse-buffer=?

That's correct. The citation contains the global prefix and suffix, each
reference contains the local prefix and suffix, and the citation key.

You can then use functions like `org-cite-get-references' and
`org-cite-key-boundaries' on them, in addition to usual
`org-element-property'.

Regards,
-- 
Nicolas Goaziou