[R-pkg-devel] FW: Single page reference manual in html format

[Jonathan Godfrey]

-----Original Message-----
From: Jonathan Godfrey 
Sent: Tuesday, 19 April 2022 8:24 pm
To: 'Ivan Krylov' <krylov.r00t using gmail.com>
Subject: RE: [R-pkg-devel] Single page reference manual in html format

Hello Ivan and all,


Thanks for the pointers. I love some of the little surprises I get when reading contributions to this list, and will now look forward to v4.2.0 albeit that it arrives in the middle of a southern hemisphere semester in which I work with less experienced R users, who always seem to share the love of a version upgrade with me. Let's not digress too far though...


My initial reason for commenting on anything pdf v HTML was for the help pages and single file manual historically generated, but the comments and preferences apply to vignettes and ultimately, to every other document.

Can I acknowledge the R Journal moving to HTML, primarily for reasons not relating to accessibility, but improving access nonetheless. Numerous other journals are now available in both HTML and pdf. Different publishers have included differing levels of quality in terms of full rendering of content in HTML, but we see a lot of progress being made, even with their back-catalogues.

WRT R documentation: I am well aware that the opportunities for having all documentation in both HTML and pdf is going to be impractical if the wrong starting point and processing is used. An Rmd file can go to pdf and to HTML, but an Rnw file won't always do so. I have tinkered with various processing of Rnw vignettes into HTML, but the outcomes are rather hit and miss. I'm continuing this work in order to support my community.


This sort of trouble automatically pushes users like me towards the packages and tools that present documentation in the consumers' format. For my community that is much more readily used if it is HTML, and the packages that do use pkgdown and authors that use bookdown really are making a difference for me and other blind users, and I bet most of them don't know that this is happening.  The explosion in the amount of readily available (accessible) and readable (accessible) content is life-changing for blind students and professionals alike. N.B. my intentional observation that "accessible" has a multitude of interpretations and I therefore try to avoid the term as much as possible nowadays. 

WRT packages using MathJax: your example has some simple mathematical elements, and one of them has a known irritation. My screen reading software and MathJax don't render the character created by \epsilon, only determined by a quick request of the closest sighted human. I'm not sure if that proves the accessibility of the specific method of creating and rendering such content or not.

BTW:  Using \varepsilon is preferred, but this is rendered in my ears as "epsilon" This is just something blind users have become accustomed to doing in our own documents, and while we have not been able to use the print-ready format, many blind users have resorted to reading the source files themselves. That does make for some trouble of course, but the options have been trouble or a vacuum.  This is why I said the HTML is almost meeting the WCAG.

There are other imperfections with MathJax rendering for screen readers, but none of them are as commonplace in statistics and data science documents.

I hope I've addressed your comments and questions without distracting myself and others, but if something else needs addressing, please do ask.
Jonathan


-----Original Message-----
From: Ivan Krylov <krylov.r00t using gmail.com> 
Sent: Tuesday, 19 April 2022 7:35 pm
To: Jonathan Godfrey <A.J.Godfrey using massey.ac.nz>
Cc: R-package-devel using r-project.org
Subject: Re: [R-pkg-devel] Single page reference manual in html format

Dear Jonathan,

I appreciate your struggle for better accessibility (and your advice to choose HTML over PDF for accessibility reasons is well taken), but re-reading your message now, I'm not sure whether it's about the manual or the vignettes of a package.

It may be not publicised widely enough, but there is HTML documentation hosted for every CRAN package, including (as of R-devel that is to become R-4.2.0) KaTeX-rendered math (or MathJax, if you set a few options on your computer). Would it help if
https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fcran.r-project.org%2Fpackage%3DDodge&data=04%7C01%7CA.J.Godfrey%40massey.ac.nz%7C526b5d381ea048ef59b008da21d71e4f%7C388728e1bbd0437898dcf8682e644300%7C1%7C0%7C637859505066354863%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=3FYFVAz9%2BUl7XDODDyrUyEi5lHk1X3xMS%2B3sn7Di5DE%3D&reserved=0 had a link to https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fsearch.r-project.org%2FCRAN%2Frefmans%2FDodge%2Fhtml%2F00Index.html&data=04%7C01%7CA.J.Godfrey%40massey.ac.nz%7C526b5d381ea048ef59b008da21d71e4f%7C388728e1bbd0437898dcf8682e644300%7C1%7C0%7C637859505066354863%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=6l%2Bh0ivWItyYOSkAjN%2BDG%2BYL2R%2F1KRk74zBQNZg%2FAB0%3D&reserved=0, in addition to the PDF manual? It's probably easier to argue in favour of adding something than replacing or removing it.

By the way, is KaTeX-rendered mathematics accessible enough, or would there be something you think should be changed? See
https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fsearch.r-project.org%2FR%2Frefmans%2Fstats%2Fhtml%2Fnls.html&data=04%7C01%7CA.J.Godfrey%40massey.ac.nz%7C526b5d381ea048ef59b008da21d71e4f%7C388728e1bbd0437898dcf8682e644300%7C1%7C0%7C637859505066354863%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=d5RQv3Zutpmid2hzDGBavJjGeqwegOVazkyJRk%2Fcejg%3D&reserved=0 for an example.

On Sat, 16 Apr 2022 06:49:20 +0000
Jonathan Godfrey <A.J.Godfrey using massey.ac.nz> wrote:

> Surely it ought to be possible for a package maintainer to choose the 
> pdf or an HTML pathway.

This is probably a reading comprehension problem on my part, but is this about the manual (which is written in Rd and automatically translated to HTML/PDF/plain text as needed by the user), or the vignettes (where the package maintainer currently has to depend on a third-party package to use HTML)? Sure, Rd is a crazy, hard to parse language, but it's possible to author decent manuals without having to take all the edge cases into account.

> It must surely be possible to accomplish sufficient tests for quality 
> of a package's documentation with an HTML destination as it is in the 
> current pdf manual process.

In R-4.2.0 (and in current R-devel already), there will be HTML Tidy checks to ensure the quality of all manual pages rendered to HTML. They don't produce any warnings if Tidy is not installed. Some other checks (e.g. for URL validity) also don't warn if their dependencies (e.g.
"xml2" package) aren't installed, making it possible to miss a problem before CRAN submission.

> To meet the CRAN standards, a single HTML construct (one file or a 
> collection of linked ones) is all that needs to be put on the table.
> After all, there's only one pdf option on the table at present and no 
> one seems to have wanted to change that in the 15+ years I've been 
> using R. I don't see a full bells and whistles solution as necessary 
> for CRAN's needs; anyone who wants the fancy stuff can already do that 
> with tools like pkgdown anyway.

See https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Frstats-gsod%2Fgsod2022%2Fissues%2F5&data=04%7C01%7CA.J.Godfrey%40massey.ac.nz%7C526b5d381ea048ef59b008da21d71e4f%7C388728e1bbd0437898dcf8682e644300%7C1%7C0%7C637859505066354863%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=sikKC2mU1D6Uw1gJz9deQl%2FRoz0pz%2B58nEsalcNxwB4%3D&reserved=0 for a related project. I'm not sure how it's progressing, but one of the ideas is to bring an HTML vignette engine into core R. The new HTML manual enhancements ("run examples in the browser") already depend on knitr.
Perhaps a few versions of R later, it'll become a Recommended package.

--
Best regards,
Ivan