Feature request: Numbered in-text citations in flextables

[altonrus]

ftExtra::colformat_md() lets you put in-text citations within cells of flextables. Because it treats each cell as it's own Rmarkdown document, this doesn't work properly when using an in-text citation format that uses the number of the reference (i.e., [3] instead of Russell 2019, as dictated by the CSL file). All citations show up as a [1] regardless of their number in the reference list of the actual Rmd document. The desired behavior would be for the in-text citation within the table to be consistent with the overall Rmd document.

This issue first came up on twitter: https://twitter.com/altonrus/status/1366856898943852551?s=20

Thank you for offering to look into it @atusy!

[atusy]

I think I need three features:

• 1. tell colformat_md how many citations occurred before its evaluation in the body
• 2. treat all the cells as a single document and then split them into cells again
• 3. tell body content after colformat_md how many citations added by colformat_md

Each of them are quite tough..., especially (1).
This requires knitting Rmd for multiple times because

• prior chunks may dynamically produce citations (like colformat_md)
• a robust way to detect citation is to parse markdown with Pandoc

(2) is going to be a big change in ftExtra's internal formatting.

(3) can be done by inserting yaml metadata block together with flextable object.
This feature will require parsing cells one more time: first for formatting and second for collecting citation keys (e.g., @R-ftExtra).

I will start with (3) because this feature improves user experience. Users will no longer have to write nocite key in YAML metadata blocks.
(2) will also be a good change in terms of performance.
However, I currently have no ideas about implementating (1).

[altonrus]

An alternative that would be adequate for many use cases would be for the user to specify a second citation style (CSL file) specifically for flextables. Medical journals typically use [1] as the main citation style but often allow Russell 2019 in tables.

An important consideration is what happens when a work is cited in the flextable but not the main text. Does that citation not show up in the reference list? If so there are simple workarounds for the end user but clear documentation would be helpful.

[atusy]

Thank you for suggesting the alternative way. It is already possible with a example below (you need to add bib and csl files).

what happens when a work is cited in the flextable but not the main text.

In that case, citations not show up in the reference list, and that is why I mention It may also be required to cite references in the nocite field. in https://ftextra.atusy.net/articles/format_columns.html.

---
title: "Untitled"
output:
  html_document:
    keep_md: true
bibliography: example.bib
csl: vancouver.csl
---

@bookdown2016

---
# This is a YAML metadata block, not a front matter
# Cite materials that are cited by flextable like below
# Note that string must be quoted
nocite: '@rmarkdown2018 @rmarkdown2020'
---

```{r}
library(ftExtra)
data.frame(pkg = 'bookdown @rmarkdown2018 @rmarkdown2020') %>%
  as_flextable() %>%
  colformat_md(pandoc_args = c('--csl', 'apa.csl'))
```

[atusy]

3. tell body content after colformat_md how many citations added by colformat_md

this is the attempt to include citations to reference list without asking users for YAML metadata block.

[atusy]

(2) is done via #46.
I said I start with (3), but found that solving (2) is the way to solve (3) cleanly.

[atusy]

(3) is done via #48

[atusy]

@altonrus I tried to partially solve (1) by manually offset citation numbers in #50 but gave up. I might come back in the future, but have no idea for now.

[altonrus]

Thanks @atusy! I'll make do with the workaround of using a different CSL in-table for now. I'm glad this request helped prompt two useful enhancements

[atusy]

@altonrus I finally come up with an idea and implemented in #60 . Would you give a try and give me feedbacks if any? Install it by remotes::install_github("atusy/ftExtra#60")

[atusy]

@altonrus

I'd be happy if you could review the usage before merge. However, if it is not likely to happen, I will merge anyway in a week or so. Feel free to feed me back even after the merge.

Thank you!

[altonrus]

Hi @atusy. This feature works for me, thank you! However, this doesn't handle the fact that some sources cited in the table may also be cited in the main text and should be given the same number that was used earlier. Because of this, I think using a different citation style in the table may still be the best approach for my purposes.

[atusy]

Thanks, @altonrus , for the check.

this doesn't handle the fact that some sources cited in the table may also be cited in the main text and should be given the same number that was used earlier

Would you provide a reproducible example so that I can attempt a fix without misunderstanding the context?

[atusy]

I figured out the reproducible example and closed #60.