Check styling of package names for consistency

[chartgerink]

We use the tidyverse style for package names, which does not do formatting. This issue is mentioned by @Bisaloo in #44.

Please also double check the formatting we use for package names in other pages as I think we usually use the tidyverse style (i.e., no formatting).

I tried finding the exact rule in the tidyverse style guide before going through everything, but am unsure I found it. @Bisaloo, might you be able to point me at the original resource so I don't do double work?

[Bisaloo]

Yes, it's correct:

Do not use code font for package names. If the package name is ambiguous in the context, disambiguate with words, e.g. “the foo package”.

https://style.tidyverse.org/documentation.html

In other words and from other discussions with the tidyverse team: package names are unformatted.

[chartgerink]

Thanks @Bisaloo!

Does that mean we want to drop the {package} style (with the curly braces) and rephrase to simply use the package title in a sentence - e.g. "using epiparameter you can"? Tidyverse doesn't say anything about the curly braces (and I had never seen this before the Epiverse slack)

[joshwlambert]

I'm personally in favour of using curly brackets without a monospace font. In 99% of cases the {} are redundant but in some cases it can make reference to a package unambiguous without requiring writing " the \<pkg> package" everytime.

Whichever style is chosen, it would be good to consistently use it across all Epiverse documentation.

[Bisaloo]

Tidyverse doesn't say anything about the curly braces (and I had never seen this before the Epiverse slack)

Yes, the tidyverse style doesn't add curly braces. This is a trend that started on twitter and has been used inconsistently in the R community.

They have muddied the water a little bit with the downlit package though, as {pkgname} is there used as markup to auto-link package site, but it's still ultimately formatted as plain text.

Whichever style is chosen, it would be good to consistently use it across all Epiverse documentation.

Yes, I 100% agree.

My initial intuition would be to use the tidyverse style but I could be convinced otherwise. The first step would probably to figure out the precise why the tidyverse team was never on board with the curly braces style. I seem to remember it is because of accessibility issues and screenreaders are confused by it. If that's indeed the case, then that's a good reason against the curly braces. If I'm remembering wrong and they don't have a specific reason, we can consider it.

[chartgerink]

I will do a bit of digging and report back 👍

[chartgerink]

Some findings:

1. It looks like the tidyverse issue suggesting curly braces is open since 2021 😅 https://github.com/tidyverse/style/issues/180 - my read is that this is unlikely to be implemented
2. Hadley mentioned in a related issue (2018): "We bold first use in books, blog posts etc" https://github.com/tidyverse/style/issues/50
3. Using the built-in screenreader for macOS reads {package} as follows: "left curly brace package right curly brace"

I'm running a poll on Mastodon right now; initial results indicate people prefer to write with the curly braces.

Convention would suggest using curly braces, which is not accessible for screenreaders. Based on this information, I would propose sticking to tidyverse and optionally add bolding for the first mention of a package, as Hadley suggests.

Does this affect your preferences?

[TimTaylor]

I'd never thought about the accessibility side of the curly braces (cheers for flagging). That seems like a very good reason to abandon their usage irrespective of poll results.

Based on this information, I would propose sticking to tidyverse and optionally add bolding for the first mention of a package, as Hadley suggests.

IMO - That or always bolding seems like a sensible approach.

[joshwlambert]

I'm happy to go with the tidyverse style to increase accessibility.

Might be good to run the same poll on the Epiverse-TRACE slack internally to check with the teams preferences.

[pratikunterwegs]

Thanks all for looking into this. I think it's helpful for users of all levels if software names are distinguishable from regular text throughout a page. We'd also want to distinguish package names from function or class names.

I think curly brackets work well where other formatting is unavailable as they are more obvious than backticks. I don't think the screen reader issue should hold us back from using them if they're a good option.

Since our docs do have formatting available, I would recommend the P3 approach which is to italicise package names where possible. Other style guides such as Google's recommend capitalising names but that isn't an option for us.

I also think that local contextual uniformity is more important than system wide uniformity. Most users will likely refer to the documentation of a single package at a time, or even only a single vignette - it doesn't really matter if different packages use different styles.

[chartgerink]

Update on the poll I ran - it seems like curly braces does not necessarily win out after all. For the blueprints, we'll move to bolding on first use (at least).

I will be making the relevant changes.

EDIT: The poll results can be found in their original form on Mastodon

[Bisaloo]

A potential argument for using the `{pkg}` markup: package names don't get automatically translated by babeldown.

As flagged above, this markup is recognized by downlit and will be formatted as plain text in pkgdown websites.