# Ideal API to expose for CSL processor? (and global citation affixes)

**URL:** <https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622>\
**Category:** CSL Development\
**Created:** [April 8, 2020, 10:18am UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622 "2020-04-08T10:18:35Z")\
**Posts on this page:** 16\
**Page:** 1

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [April 8, 2020, 10:18am UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/1 "2020-04-08T10:18:35Z")

</div>

Related to [this](https://discourse.citationstyles.org/t/status-of-citeproc-rs/1621/2), but want to broaden the audience.

Note that the subsequent discussion has uncovered a CSL development question.

Org-mode developer is [asking the question](https://lists.gnu.org/archive/html/emacs-orgmode/2020-04/msg00123.html) about what API they should expose to allow external tools (like CSL processors) to take over citation processing.

Specifically, he asks:

> we need to decide about how external processors could plug  
> into the export framework.
> 
> - For example, it could be a simple variable bound to a list of  
> functions. Each function accepts three arguments: the export  
> back-end, as a symbol, the full citation, as a list of triplets  
> (key, prefix, suffix) along with global prefix/suffix, and the  
> usual INFO communication channel. Does it need more?
> 
> - Also, the prefix/suffix may contain some Org markup, so this  
> needs to be also processed. Should it happen before, or after the  
> external processor does its job? I.e., should the function  
> translate into Org or target format?

My impulse on second question is the latter, and first question is … not sure.

And a little farther down, he says:

> Decide about API Org should provide for it to be useful. Here are  
> some low hanging fruits:
> 
> - List all “.bib” files associated to the document,
> 
> - List all citations,
> 
> - Return citation key at point, if any.
> 
> - Anything else?

It’s been awhile since I’ve thought about these details. What suggestions do you all have?

Is it providing a list of all citations (each of which is represented as a “triplet,” per his suggestion), bib data for those citations, and a style?

@Frank_Bennett  
@cormacrelf

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [April 9, 2020, 12:32am UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/2 "2020-04-09T00:32:40Z")

</div>

I’m going to test out an argument. Does this make sense?

The one thing I would say about this (the “triplet” model) is to think about the user experience.

At least for CSL processors like citeproc-org, locators are distinct from prefixes and suffixes.

So the code parses the full string, and converts it into a map, with possible keys something like cite\_key, prefix, suffix, locators, suppress\_author.

My thought is that if org citation syntax doesn’t explicitly incorporate that, then it leads greater room for user confusion and frustration.

So citation should have the following keys in the end?

- cite\_key
- prefix
- suffix
- locators
- suppress\_author (per @Denis_Maier below, better this not be a boolean, so “mode” would be better)

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [April 9, 2020, 8:22am UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/3 "2020-04-09T08:22:59Z")

</div>

I have just had a quick try with pandoc. Take this input document (test.md):

```auto
[@doe]

[@doe, 4]

[cf. @doe]

[cf. @doe, 4]

[cf. @doe, 4 for many interesting comments]

[cf. @doe, for many interesting comments]

[-@doe, 4]

@doe argues ...

@doe [4] argues ..

[@doeA; @doeB]

```

Now, `pandoc test.md -t native > pandoc-ast.txt` gives me:

```auto
[Para [Cite [Citation {citationId = "doe", citationPrefix = [], citationSuffix = [], citationMode = NormalCitation, citationNoteNum = 0, citationHash = 0}] [Str "[@doe]"]]
,Para [Cite [Citation {citationId = "doe", citationPrefix = [], citationSuffix = [Str ",",Space,Str "4"], citationMode = NormalCitation, citationNoteNum = 0, citationHash = 0}] [Str "[@doe,",Space,Str "4]"]]
,Para [Cite [Citation {citationId = "doe", citationPrefix = [Str "cf.\160"], citationSuffix = [], citationMode = NormalCitation, citationNoteNum = 0, citationHash = 0}] [Str "[cf.",Space,Str "@doe]"]]
,Para [Cite [Citation {citationId = "doe", citationPrefix = [Str "cf.\160"], citationSuffix = [Str ",",Space,Str "4"], citationMode = NormalCitation, citationNoteNum = 0, citationHash = 0}] [Str "[cf.",Space,Str "@doe,",Space,Str "4]"]]
,Para [Cite [Citation {citationId = "doe", citationPrefix = [Str "cf.\160"], citationSuffix = [Str ",",Space,Str "4",Space,Str "for",Space,Str "many",Space,Str "interesting",Space,Str "comments"], citationMode = NormalCitation, citationNoteNum = 0, citationHash = 0}] [Str "[cf.",Space,Str "@doe,",Space,Str "4",Space,Str "for",Space,Str "many",Space,Str "interesting",Space,Str "comments]"]]
,Para [Cite [Citation {citationId = "doe", citationPrefix = [Str "cf.\160"], citationSuffix = [Str ",",Space,Str "for",Space,Str "many",Space,Str "interesting",Space,Str "comments"], citationMode = NormalCitation, citationNoteNum = 0, citationHash = 0}] [Str "[cf.",Space,Str "@doe,",Space,Str "for",Space,Str "many",Space,Str "interesting",Space,Str "comments]"]]
,Para [Cite [Citation {citationId = "doe", citationPrefix = [], citationSuffix = [Str ",",Space,Str "4"], citationMode = SuppressAuthor, citationNoteNum = 0, citationHash = 0}] [Str "[-@doe,",Space,Str "4]"]]
,Para [Cite [Citation {citationId = "doe", citationPrefix = [], citationSuffix = [], citationMode = AuthorInText, citationNoteNum = 0, citationHash = 0}] [Str "@doe"],Space,Str "argues",Space,Str "\8230"]
,Para [Cite [Citation {citationId = "doe", citationPrefix = [], citationSuffix = [Str "4"], citationMode = AuthorInText, citationNoteNum = 0, citationHash = 0}] [Str "@doe",Space,Str "[4]"],Space,Str "argues",Space,Str ".."]
,Para [Cite [Citation {citationId = "doeA", citationPrefix = [], citationSuffix = [], citationMode = NormalCitation, citationNoteNum = 0, citationHash = 0},Citation {citationId = "doeB", citationPrefix = [], citationSuffix = [], citationMode = NormalCitation, citationNoteNum = 0, citationHash = 0}] [Str "[@doeA;",Space,Str "@doeB]"]]]

```

So, in pandoc each cite seems to be a list containing multiple citations. Each citation consists of the following keys:

- citationID
- citationPrefix
- citationSuffix
- citationMode
- citationNoteNum
- citationHash

After the list, there’s is also the original input as a string.

Now, concerning your suggestion.

1. Pandoc uses `citationMode` instead of `suppress_author`. I guess this is a good choice as it does also allow for other citation modes, like narrative citations, or so.

2. Pandoc does not explicitly use a key like `locators`. Instead, locators are inferred from the suffix, as the [manual](https://pandoc.org/MANUAL.html#citations) states:

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [April 9, 2020, 8:45am UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/4 "2020-04-09T08:45:10Z")

</div>

Concerning global affixes, this is currently not really supported by pandoc, as this is clearly not included in CSL. (Biblatex knows global pre- and suffixes, so this might come from there.)

Anyway, pandoc parses this org-mode-citation `[(cite): PREFIX; @doeA; cf. @doe p. 4; SUFFIX]` as:

```auto
,Para [Cite [Citation {citationId = "doeA", citationPrefix = [Str "PREFIX"], citationSuffix = [], citationMode = NormalCitation, citationNoteNum = 0, citationHash = 0},Citation {citationId = "doe", citationPrefix = [Str "cf."], citationSuffix = [Space,Str "p.",Space,Str "4",Str "SUFFIX"], citationMode = NormalCitation, citationNoteNum = 0, citationHash = 0}] []]]

```

The global prefix is merged with the first citation’s (non-existent) prefix, the global suffix is merged with the second citation’s suffix.

(Perhaps explicit support for global affixes would be something to be discussed for CSL 1.2, or later…)

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [April 9, 2020, 9:07am UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/5 "2020-04-09T09:07:07Z")

</div>

Thanks much @Denis_Maier; this is very helpful.

I’m also putting a screenshot of the Zotero citation UI here.

 ![Screenshot from 2020-04-09 04-59-06](https://canada1.discourse-cdn.com/flex029/uploads/citationstyles/original/1X/0001f804ab7ff6a331e9629812b1ff3915e4e947.png)

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [April 9, 2020, 11:02am UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/6 "2020-04-09T11:02:43Z")

</div>

> [@Denis\_Maier](#):
>
> (Perhaps explicit support for global affixes would be something to be discussed for CSL 1.2, or later…)

I’m totally agnostic about this question, either in org, or in CSL.

My impulse is to think it’s overkill though. Does anyone know the practical need for this feature, which cannot be addressed with the existing, flat, approach?

So to clarify, we have citations, which are lists of (let’s call them) cites.

In CSL implementations, including pandoc, cites can have affixes, but citations cannot.

In biblatex, and the proposed org syntax, both levels can have affixes.

So think of an example like:

> Doe has argued (see 2016, 2018).

Really, the “see” is a prefix for the citation, since its target is the group of cites that follow.

Obviously, we can still handle this, in say the pandoc syntax, by simply doing:

```
Doe has argued [see -@doe2016, -@doe2018].

```

Is that good enough?

Is there a situation where the current approach breaks down? Maybe where the cites need to be resorted within the citation? So a case like above, where user instead enters this, where cites are sorted in date order?

```
Doe has argued [see -@doe2018, -@doe2016].

```

Do we, as @Denis_Maier suggests, need to consider the two-level support for the next release?

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [April 9, 2020, 2:49pm UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/7 "2020-04-09T14:49:14Z")

</div>

> [@Bruce\_D\_Arcus1](#):
>
> Is there a situation where the current approach breaks down? Maybe where the cites need to be resorted within the citation? So a case like above, where user instead enters this, where cites are sorted in date order?

Yeah, I think that’s pretty much it. If cites are resorted automatically a global prefix would be much easier to handle, but also if you manually resort the cites later, a global prefix is probably more user friendly. Having said that, I have never been inclined to use this even in biblatex.

On the other hand, after thinking a bit more about it: Do affixes fall into the domain of CSL at all? At least currently this seems to be entirely out of the specs, right?

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [April 9, 2020, 2:58pm UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/8 "2020-04-09T14:58:16Z")

</div>

> [@Denis\_Maier](#):
>
> On the other hand, after thinking a bit more about it: Do affixes fall into the domain of CSL at all? At least currently this seems to be entirely out of the specs, right?

I think the expectations around this are more implicit currently.

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [April 9, 2020, 7:53pm UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/9 "2020-04-09T19:53:26Z")

</div>

So you think this should be added to the specs? Perhaps as an addendum dealing with API details?

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [April 10, 2020, 12:01am UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/10 "2020-04-10T00:01:08Z")

</div>

Perhaps yes.

I think we didn’t originally put anything in because we thought it premature, and less important than the core of the style spec.

But at this point, we have a lot of experience, so maybe worth revisiting?

---

<div class="post-metadata">

**Author:** ![bwiernik](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/bwiernik/32/438_2.png) [@bwiernik](https://discourse.citationstyles.org/u/bwiernik)\
**Post date:** [April 10, 2020, 12:02am UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/11 "2020-04-10T00:02:41Z")

</div>

Global affixes would definitely be an improvement. The current flat approach works, but it is a pain when revising a document. For example, let’s say I’m writing in APA style (cites sorted alphabetically), and I have the citation (cf. Jones, 2016; Smith, 2008). But then I later add a cite to “Bradley, 2020” to this citation. It now becomes (Bradley, 2020; cf. Jones, 2016; Smith, 2008), and the “cf.” has to be moved manually. It would be really helpful to be able to specify things like “cf.” as a global prefix.

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [April 11, 2020, 3:47pm UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/12 "2020-04-11T15:47:05Z")

</div>

> [@bwiernik](#):
>
> Global affixes would definitely be an improvement.

Based on this conversation, I suggested to the org devs to keep the global affixes.

If we do define an API in CSL, we should probably too.

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [April 13, 2020, 10:45am UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/13 "2020-04-13T10:45:42Z")

</div>

I also just suggested they add support for textual citations, since we’ve heard this feature request forever.

And I restarted discussion on how to implement this in CSL on [github](https://github.com/citation-style-language/schema/issues/141).

I had an epiphany that this might be much easier than I assumed. I hope I’m right, but feel free to tell me I’m wrong 😄

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [April 13, 2020, 12:01pm UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/14 "2020-04-13T12:01:25Z")

</div>

On API, I started [something](https://docs.google.com/document/d/1Mc1JyRzd7blga2pGhBrEPiJI7eUj2d4Ho__5eS-p0LI/edit#) while I’m thinking about this.

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [April 14, 2020, 11:02am UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/15 "2020-04-14T11:02:26Z")

</div>

It took me awhile to understand @Frank_Bennett’s work on intext support in CSL, but once I finally got it (thanks @bwiernik!), it’s pretty cool!

Nice to see we’ll be able to _finally_ cross this long-running request off the list.

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [April 25, 2020, 5:12pm UTC](https://discourse.citationstyles.org/t/ideal-api-to-expose-for-csl-processor-and-global-citation-affixes/1622/16 "2020-04-25T17:12:13Z")

</div>

If anyone is curious, here’s the [org citation code](https://code.orgmode.org/bzg/org-mode/commit/5773f181d9ca2c435557386f160de0d6ee9369cd), which partially prompted my question here.