Accessibility related project

[hturner]

The Forwards accessibility team have suggested many changes that would improve accessibility, e.g.

• dark mode on R project websites and/or help files
• HTML vs PDF vignettes
  • This could be tools to support almost automated conversion, helping CRAN developers to do it themselves. I think some Bioconductor folks did some work on this, I will add the link when I have a chance to dig it up
  • Alternatively, contributing to packages to replace the PDF vignette with an HTML one
• HTML package manual vs PDF reference manual
  • This already exists for every package but is hard to find. Adding a field to DESCRIPTION or replacing PDF in the Reference Manual field with a link such as https://search.r-project.org/CRAN/refmans/survival/html/00Index.html would help people to find this and prioritise HTML over PDF.

There are other places where HTML could be used instead of PDF, but the above would not require much to change in the core codebase, so perhaps would be good to start with.

[aitap]

If the intent is to migrate to HTML vignettes, perhaps some work could be done on bringing an HTML vignette engine into core R, or teaching Sweave to speak HTML. The popular vignette engine, rmarkdown (invoked via knitr::rmarkdown), adds length(setdiff(union(tools::package_dependencies('rmarkdown', recursive=TRUE)$rmarkdown, 'rmarkdown'), c('utils','tools','stats','methods', 'grDevices')))= 18 non-core or recommended packages to the dependencies of a package.

[dicook]

I'd be really supportive of this one. Having some help in migrating older R Journal articles to html would be good, as well as going over CRAN Task Views to clean them up or translate to different languages.

[hturner]

Oh yes, thanks for the reminder about R Journal articles. Possibly on the borderline of scope though (is the R Journal documentation?) - it may be better as an Outreachy project.

Not sure if you're aware but the CRAN Task Views have been receiving a lot of work lately, with a move to GitHub (https://github.com/cran-task-views). It's a good idea to think about possibly synergies, pinging @zeileis.

[zeileis]

Thanks for including me in the discussion. Some background on the current state of the CRAN Task Views: We have migrated all task views from R-Forge to GitHub with a separate repository for each view in order to facilitate community contributions. (Not all repositories are public, yet, some maintainers are still working on the transition.) We're also strongly encouraging to moving to teams of co-maintainers in order to make maintenance more active.

Therefore, I hope that clean-ups are in progress although a certain heterogeneity will certainly remain due to the way the task views are set up and maintained. And for translations the content is not static enough, I think. I haven't got a good idea how to maintain the translations going forward. So off the top of my head I haven't got a good idea how to leverage a GSOD project.

As for some of the other proposals: Making it easier to convert vignettes to HTML, possibly with a leaner engine than rmarkdown would be really nice. I have recently migrated various {beamer} slides to bookdown and have some Rnw2Rmd conversion function (extended from the mdsr package) which does a lot of useful things but the resulting file still needs to be finalized/polished. Also, if you have more complex LaTeX components (e.g., more complex tables, advanced math formatting, algorithm environments, etc.) more work is likely needed.

Re: Dark mode. Isn't this something that can be enabled in many browsers these days? Or is this not good/reliable enough?

[hturner]

If an "rmarkdownlite" is a potential goal, perhaps @yihui has some thoughts.

[yihui]

I'm highly interested in developing a much leaner package than rmarkdown, which could take only one dependency (i.e., commonmark) instead of 18 as @aitap pointed out above. Of course, this "lite" package would have much fewer features than rmarkdown and knitr, but I think it should be good enough for package vignettes.

I can put this on my agenda if people are really interested in it (especially if R core can consider making it a recommended package).

[dmurdoch]

I haven't used commonmark, but if it avoids the requirement for Pandoc, it would be helpful. Of course, if it doesn't add a big load of other packages it wouldn't support rgl, plotly, leaflet etc.

One thing that would make it a little easier on users (as opposed to package authors) would be to split Suggests into two categories: packages needed for optional features for users, and packages needed for building.

[yihui]

Yes, the main reason of using commonmark is to avoid the external dependency on Pandoc.

[hturner]

I think a leaner rmarkdown package would be a welcome development, regardless of whether it gets adopted as a recommended package (though I have posted on the R-Devel mailing list to raise the possibility). This would potentially suffice for the majority of packages. So it would be great if you put this on your agenda Yihui.

For GSoD we will most likely prioritise further work on the R Development Guide (since this is directly technical writing, covers work that was already on the R Contribution Working Group agenda, and we have at least one interested candidate). So if we want coding support on developing a leaner rmarkdown or converting existing vignettes, this is best redirected to GSoC (https://github.com/rstats-gsoc/gsoc2022/wiki, project submission deadline April 3) or Outreachy (https://www.outreachy.org/communities/cfp/the-r-project-for-statistical-computing/, project submission deadline March 23). I'm co-ordinating the latter if interested (co-)mentors want to get in touch (heather@r-project.org). Possibly converting vignettes could be combined with converting R Journal articles for Outreachy (360 hours) or a GSoC large project (350 hours).

[djvanderlaan]

Self-plug after seeing hturner's message on R-devel: Having ran into issues with the dependencies and complexities of rmarkdown, I developed simplermarkdown as a much leaner and simpler markdown engine. Initially not as a vignette engine, but it actually works well as light weight vignette engine and it is used a such be a number of packages now. It does depend on pandoc, but that is about it.

[yihui]

regardless of whether it gets adopted as a recommended package

@hturner I agree. Thanks for posting to the mailing list!

I developed simplermarkdown as a much leaner and simpler markdown engine

@djvanderlaan Thanks for letting me know! I was not aware of it (perhaps I saw it briefly somewhere some time ago but forgot it). I'll definitely take a closer look at your package before I decide to do anything. Perhaps you have already done what I hoped for in simplermarkdown.

[hturner]

Closing this issue as we went with #3 for GSoD 2022 and we have hired writers for this project - https://github.com/rstats-gsod/gsod2022/wiki/GSoD-2022-Writers

If people would like to work on this issue on a voluntary basis or plan to make a proposal to another funding source, please reach out via one of the following:

• R-Devel Slack #core-documentation channel
• R Contribution Working Group meetings
• R Contributors Twitter DM

This idea can also be proposed for GSoD 2023 when that repo is set up.

[jangorecki]

@hturner @dmurdoch I filled rstudio/markdown#109, in case you want to subscribe to status of pandoc-less, and even knitr-less, vignette engine.

[yihui]

litedown is mostly done (https://github.com/yihui/litedown), and vignette engines have also been added: https://yihui.org/litedown/#sec-package-vignettes (warning: package is not released yet, and documentation is incomplete and disorganized)