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

[Ivan Krylov]

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://CRAN.R-project.org/package=Dodge had a link to
https://search.r-project.org/CRAN/refmans/Dodge/html/00Index.html, 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://search.r-project.org/R/refmans/stats/html/nls.html 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://github.com/rstats-gsod/gsod2022/issues/5 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