Various issues detected in proofs for R Journal 2023-3

[zeileis]

When proofreading my contributions in the draft for R Journal 2023-3 at https://rjournal.github.io/issues/2023-3/ I noticed various issues that are likely caused by rjtools and/or distill. Hence Simon @s-u advised me to also post my feedback to him here.

General issues

• In general, the "Citation" generated at the end of every contribution should be fixed. The journal field "The R Journal" is repeated incorrectly at the beginning of the title field. Both in the text and in the BibTeX version.

• In several papers, inconsistencies in the "References" occur between the HTML and the PDF version. Book, manual and proceedings titles are written in title case in the PDF version. In the HTML version, however, they are coerced to sentence case which sometimes leads to proper names being written in lower case. An example is "vienna, austria" in the Ihaka (2003) reference in our color paper, see: https://rjournal.github.io/articles/RJ-2023-071/
  But I also noticed other cases (e.g., "Writing r extensions" in the Zhang et al. paper).

• In several papers the "supplements" link does not work. For example, in our color paper:
  https://rjournal.github.io/articles/RJ-2023-060/RJ-2023-060.zip
  But I noticed the same problem for several other papers.

Issues in our color paper

https://rjournal.github.io/articles/RJ-2023-071/

• The table at the end is labeled "Table 1" in the PDF while it has no label in the HTML version. Is this difference intentional? (We noticed this already when writing the paper, so that the text says "table below" which is correct in both versions.)

• The URL and the access date in the Wikipedia reference is shown in the PDF version but not in the HTML version. The access date is not so crucial but the URL should really be displayed.

Other issues

• In the "C443" paper the title is in sentence case while all the remaining titles are in title case. Also "R-package is hyphenated throughout the paper while it is typically not hyphenated elsewhere. In summary, the title should be: "C443: An R Package to See a Forest for the Trees"

• I found a small problem with the HTML version of our "Changes on CRAN" contribution. The subtitle and abstract have been interchanged, see: https://rjournal.github.io/news/RJ-2023-3-cran/
  Some additional details are described below.

  • The article has the subtitle "2023-05-01 to 2023-09-30" and no abstract.

  • This is shown correctly in the PDF version.

  • The HTML that I submitted showed the subtitle correctly and added the default abstract: "Changes on CRAN" published in The R Journal. This is ok.

  • But the current draft has now switched subtitle and abstract. Please revert this change.

[s-u]

Most of the above are indeed bugs in rjtools. I'll comment on some that I could trace, but authors of rjtools are needed to fix them - most of them stem from either the template and metadata processing.

• html text in the subtitle is replaced with "<title> published in The R Journal." and the actual subtitle is incorrectly pushed to the "abstract" field:

  title: Changes on CRAN
  subtitle: 2023-05-01 to 2023-09-30
  

  Changes on CRAN

  “Changes on CRAN” published in The R Journal.

  Abstract: 2023-05-01 to 2023-09-30

  ---

  but should be:

  Changes on CRAN

  2023-05-01 to 2023-09-30

• "Citation" entry in the footer duplicates the journal - likely from the title mangling:
  

  For attribution, please cite this work as

  Hornik, et al., "The R Journal: Changes on CRAN", The R Journal, 2023

• References in the html version have a several issues (see above) - they are not consistent with the PDF version and include
  - incorrect case
  - different (e.g., superfluous) tags

Issues from above that may not be directly rjtools-related:

• supplementaries are missing if they are not mentioned in the DESCRIPTION. However, this is legal if they consist of the single .R file, e.g. from .Rmd, so this is more likely an rj bug where it fails to create the ZIP file in those cases. (For the current issue I have created them by hand).
• The C443 had odd case which was partially corrected, but apparently not everywhere.

[s-u]

On the wrong title issue - this seems to come from distill::qualified_title https://github.com/rstudio/distill/blob/d88adcaacd6b3b4e96e3f2b88449b4b839ddff0a/R/metadata.R#L870-L876 but I don't see neither the logic nor a way to disable it so it looks like a "feature" of distill that cannot be disabled. I fail to see how that is helpful since the title is always wrong in citations, no matter what, as the journal name is never part of the article title when citing. The site title is used in other contexts so we cannot just remove it from the site config - it looks like a bad design. For the R Journal we just have to use modified distill - fixed in this fork rjournal/distill@72c26ad

[s-u]

Abstract handling is a mess, but 5f0fe0d at least fixes the look in the web output. It really needs a re-write to handle abstracts natively in cooperation with distill.

[huizezhang-sherry]

first dot point under Issues in our color paper: The table reference will show in the html version if

1. the markdown caption has a label, e.g. Table: (\#tab:foo) An overview … , and
2. proper in-text citation is used, i.e. The table \@ref(tab:foo) below summarizes

I will keep tracking on the other raised issues.

[zeileis]

Sherry, thanks for the information. It would be good to add some guidance on this in the documentation. I had checked out https://rjournal.github.io/rjtools/articles/format-details.html#tables and also tried

knitr::kable(head(cars), format = "markdown", caption = "Cars data", label = "cars")

In general it would be helpful to have more guidance on how to write content in Markdown directly (as opposed to generating content via R).

Simon, I don't want to add to all the time you already spent on this. If you want to update the .Rmd for our color paper, great - if not, no problem either. I would use

Table: (\#tab:overview) An overview  ...

and

Table  \@ref(tab:overview) below summarizes ...

[huizezhang-sherry]

added in commit b453331.

If using knitr::kable() with the label argument, the following also works:

• Table \@ref(tab:cars) says ....

• knitr::kable(head(cars), format = "markdown", caption = "Cars data", label = "cars")

[s-u]

@zeileis sure, I have modified the sources accordingly (rjournal/rjournal.github.io@c13141a) - it seems to do the trick, thanks.

[s-u]

I have filed the distill citation bug as rstudio/distill#504

[huizezhang-sherry]

second dot point under Issues in our color paper - Wikipedia URL display in web format

I suspect this might also be a distill issue that the howpublished field is not supported in the citation (need confirmation here).

A workaround here is to use the url field:

@Misc{Wiki+HCL,
  author = {Wikipedia},
  title = {{HCL Color Space} --- {W}ikipedia{,} The Free Encyclopedia aksdjflksjdfl},
  year = {2023},  
  url = {https://en.wikipedia.org/wiki/HCL_color_space},
  note = {accessed 2023-07-12}
}

I also added this instruction to the journal format detail vignette 7817168.

[zeileis]

In a plain distill_article I don't have any problems with the howpublished field. Using a slightly adapted example from https://rstudio.github.io/distill/citations.html I get:

The source code of the document is from the link above, just modified to use the color.bib file from our paper.

---
title: "Distill for R Markdown"
description: | 
  Scientific and technical writing, native to the web
output: distill::distill_article
date: May 4, 2018
author:
  - name: Nora Jones 
    url: https://example.com/norajones
    affiliation: Spacely Sprockets
    affiliation_url: https://example.com/spacelysprokets
bibliography: color.bib
---

This is in @Wiki+HCL.