emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* Question about citation processors [wip-cite branch]
@ 2021-05-04 10:41 Joost Kremers
  2021-05-04 13:45 ` Bruce D'Arcus
  2021-05-04 16:22 ` Nicolas Goaziou
  0 siblings, 2 replies; 13+ messages in thread
From: Joost Kremers @ 2021-05-04 10:41 UTC (permalink / raw)
  To: emacs-orgmode

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Question about citation processors [wip-cite branch]
  2021-05-04 10:41 Question about citation processors [wip-cite branch] Joost Kremers
@ 2021-05-04 13:45 ` Bruce D'Arcus
  2021-05-04 14:07   ` Joost Kremers
  2021-05-04 16:22 ` Nicolas Goaziou
  1 sibling, 1 reply; 13+ messages in thread
From: Bruce D'Arcus @ 2021-05-04 13:45 UTC (permalink / raw)
  To: Joost Kremers; +Cc: org-mode-email

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Question about citation processors [wip-cite branch]
  2021-05-04 13:45 ` Bruce D'Arcus
@ 2021-05-04 14:07   ` Joost Kremers
  2021-05-04 15:04     ` Bruce D'Arcus
  2021-05-04 15:10     ` Bruce D'Arcus
  0 siblings, 2 replies; 13+ messages in thread
From: Joost Kremers @ 2021-05-04 14:07 UTC (permalink / raw)
  To: Bruce D'Arcus; +Cc: emacs-orgmode


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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Question about citation processors [wip-cite branch]
  2021-05-04 14:07   ` Joost Kremers
@ 2021-05-04 15:04     ` Bruce D'Arcus
  2021-05-04 15:27       ` Joost Kremers
  2021-05-04 15:10     ` Bruce D'Arcus
  1 sibling, 1 reply; 13+ messages in thread
From: Bruce D'Arcus @ 2021-05-04 15:04 UTC (permalink / raw)
  To: Joost Kremers; +Cc: org-mode-email

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Question about citation processors [wip-cite branch]
  2021-05-04 14:07   ` Joost Kremers
  2021-05-04 15:04     ` Bruce D'Arcus
@ 2021-05-04 15:10     ` Bruce D'Arcus
  2021-05-04 15:22       ` Joost Kremers
  1 sibling, 1 reply; 13+ messages in thread
From: Bruce D'Arcus @ 2021-05-04 15:10 UTC (permalink / raw)
  To: Joost Kremers; +Cc: org-mode-email

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Question about citation processors [wip-cite branch]
  2021-05-04 15:10     ` Bruce D'Arcus
@ 2021-05-04 15:22       ` Joost Kremers
  2021-05-04 15:39         ` Bruce D'Arcus
  0 siblings, 1 reply; 13+ messages in thread
From: Joost Kremers @ 2021-05-04 15:22 UTC (permalink / raw)
  To: Bruce D'Arcus; +Cc: emacs-orgmode


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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Question about citation processors [wip-cite branch]
  2021-05-04 15:04     ` Bruce D'Arcus
@ 2021-05-04 15:27       ` Joost Kremers
  2021-05-04 19:34         ` Denis Maier
  0 siblings, 1 reply; 13+ messages in thread
From: Joost Kremers @ 2021-05-04 15:27 UTC (permalink / raw)
  To: Bruce D'Arcus; +Cc: emacs-orgmode


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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Question about citation processors [wip-cite branch]
  2021-05-04 15:22       ` Joost Kremers
@ 2021-05-04 15:39         ` Bruce D'Arcus
  0 siblings, 0 replies; 13+ messages in thread
From: Bruce D'Arcus @ 2021-05-04 15:39 UTC (permalink / raw)
  To: org-mode-email

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Question about citation processors [wip-cite branch]
  2021-05-04 10:41 Question about citation processors [wip-cite branch] Joost Kremers
  2021-05-04 13:45 ` Bruce D'Arcus
@ 2021-05-04 16:22 ` Nicolas Goaziou
  2021-05-04 19:17   ` Joost Kremers
  1 sibling, 1 reply; 13+ messages in thread
From: Nicolas Goaziou @ 2021-05-04 16:22 UTC (permalink / raw)
  To: Joost Kremers; +Cc: emacs-orgmode

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Question about citation processors [wip-cite branch]
  2021-05-04 16:22 ` Nicolas Goaziou
@ 2021-05-04 19:17   ` Joost Kremers
  2021-05-05 14:09     ` Nicolas Goaziou
  0 siblings, 1 reply; 13+ messages in thread
From: Joost Kremers @ 2021-05-04 19:17 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Question about citation processors [wip-cite branch]
  2021-05-04 15:27       ` Joost Kremers
@ 2021-05-04 19:34         ` Denis Maier
  2021-05-04 20:04           ` Joost Kremers
  0 siblings, 1 reply; 13+ messages in thread
From: Denis Maier @ 2021-05-04 19:34 UTC (permalink / raw)
  To: Joost Kremers, Bruce D'Arcus; +Cc: emacs-orgmode

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








^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Question about citation processors [wip-cite branch]
  2021-05-04 19:34         ` Denis Maier
@ 2021-05-04 20:04           ` Joost Kremers
  0 siblings, 0 replies; 13+ messages in thread
From: Joost Kremers @ 2021-05-04 20:04 UTC (permalink / raw)
  To: Denis Maier; +Cc: emacs-orgmode, Bruce D'Arcus


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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Question about citation processors [wip-cite branch]
  2021-05-04 19:17   ` Joost Kremers
@ 2021-05-05 14:09     ` Nicolas Goaziou
  0 siblings, 0 replies; 13+ messages in thread
From: Nicolas Goaziou @ 2021-05-05 14:09 UTC (permalink / raw)
  To: Joost Kremers; +Cc: emacs-orgmode

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2021-05-05 14:12 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-04 10:41 Question about citation processors [wip-cite branch] Joost Kremers
2021-05-04 13:45 ` Bruce D'Arcus
2021-05-04 14:07   ` Joost Kremers
2021-05-04 15:04     ` Bruce D'Arcus
2021-05-04 15:27       ` Joost Kremers
2021-05-04 19:34         ` Denis Maier
2021-05-04 20:04           ` Joost Kremers
2021-05-04 15:10     ` Bruce D'Arcus
2021-05-04 15:22       ` Joost Kremers
2021-05-04 15:39         ` Bruce D'Arcus
2021-05-04 16:22 ` Nicolas Goaziou
2021-05-04 19:17   ` Joost Kremers
2021-05-05 14:09     ` Nicolas Goaziou

Code repositories for project(s) associated with this inbox:

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).