search

rstats-gsod / gsod2022

Website for planning Google Season of Docs 2022 for the R Project
1 stars 0 forks source link

Accessibility related project #5

Closed hturner closed 2 years ago

hturner commented 2 years ago

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

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

yihui commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

hturner commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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:

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

jangorecki commented 11 months ago

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

yihui commented 5 months ago

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)