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

[Jeroen Ooms]

Hi Jonathan,

I've done a first attempt at a package to generate one-page html
reference manuals. The package is called 'postdoc' and you can read
about it here: https://ropensci.org/blog/2022/11/29/postdoc-docs/

To get a quick impression, find example manuals for base-R packages
here: https://r-universe.dev/manuals/ and many others on
https://r-universe.dev (examples linked in the above blog post).

I am interested to hear if this format works better for you than the
PDF manual, and how we can further improve it.

Jeroen



On Sat, Apr 16, 2022 at 8:49 AM Jonathan Godfrey
<A.J.Godfrey using massey.ac.nz> wrote:
>
>
> Hello all,
>
> I rarely contribute to discussions on this list, but learn lots while I hang about. I saw the first post in this thread and hoped that it would lead to a strong positive response from people I've come to respect.
>
> The idea of removing pdf manuals is hugely attractive to my community. The LaTeX driven pdf is as good for blind people today, as it was in the 20th century. It isn't, full stop, end of story. The ability to incorporate mathematical expressions in help pages has been awesome if done in HTML with MathJax, but has made the prospect of reliance on a pdf even less attractive than it was before.
>
> I'd really like to see someone justify the use of the single pdf manual with a 2022 lens. What is its value to the community? And what is its cost? I'm sure there was a need for the single pdf way back, but what is its real value today?
>
> I accept that there are other reasons why a package needs CRAN to do some pdf checking, including Sweave vignettes, but should every package have to play pdf games because some do? I loved LaTeX (and Sweave) in the day, but while those tools have stood still, R markdown and HTML have materially improved my life.
>
> Surely it ought to be possible for a package maintainer to choose the pdf or an HTML pathway. (?) 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. 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.
>
> As a package maintainer, I tire of the reminders that I don't have qpdf installed. I don't use the tool for anything else so I won't bother to install it. I know the pdf is not too big and don't need a tool to tell me. I'd love to see a reduction in the plethora of tools and tests needed to get a package thoroughly tested. I've been tempted to remove vignettes entirely because it takes too long to repeatedly process them, but I did cull the content dramatically and put most of it in an external location. If the intention of the designed process was to make me and others use external repositories instead of fully self-contained packages with all their associated documentation, then perhaps we have success.
>
>
> I'm now going to present some ideas that might seem unnecessary, but I spend a lot of my time as an advocate for disabled people. This is not the first time I've seen good people, albeit unwittingly ableist people, make life harder for disabled people in their midst. I say "unwitting" not to suggest foolishness of any kind, but blissful lack of awareness. Whether it is intentional or not, and I honestly believe it isn't, the outcome is the same in that marginalised people get marginalised.
>
> Asking package maintainers to go out and use another package is analogous to asking one architect to employ another architect to design the wheelchair ramps to the buildings they design, or worse, ask the wheelchair user to bring their own ramps.
>
> The best tools that provide accessibility for disabled users are the ones that no one knows they are using. R markdown to HTML creates extremely readable content and most authors won't ever know that this is so. They don't need to know, but my community benefits hugely.
>
> The HTML resulting from R markdown vignettes and other documentation and papers almost meets the Web Content Accessibility Guidelines (WCAG) put out by the WWW Consortium, whereas the LaTeX driven pdf always fails the international standard for pdf. I can help improve the HTML, but the LaTeX community has collectively failed to get their primary output files to an acceptable standard, and I therefore cannot help.
>
> My advice to everyone involved in running CRAN, and I do solely from a disabled person's perspective, is to make it hard to do the wrong thing, and much easier to do the right things. I'm sure that we'll all find the results are an improvement for everyone. After all, I could ask when you last chose to use the ramp in preference to the steps to get into a building.
>
> Please consider the HTML alternative to any pdf, in any context, but especially in anything relating to R.
>
> All the best,
> Jonathan
>
>
>
>
>
> -----Original Message-----
> From: R-package-devel <r-package-devel-bounces using r-project.org> On Behalf Of Deepayan Sarkar
> Sent: Saturday, 16 April 2022 6:36 am
> To: Duncan Murdoch <murdoch.duncan using gmail.com>
> Cc: Jeroen Ooms <jeroen using berkeley.edu>; R Package Development <r-package-devel using r-project.org>
> Subject: Re: [R-pkg-devel] Single page reference manual in html format
>
> On Fri, Apr 15, 2022 at 11:48 PM Duncan Murdoch <murdoch.duncan using gmail.com> wrote:
> >
> > On 15/04/2022 1:16 p.m., Deepayan Sarkar wrote:
> > > On Sat, Apr 9, 2022 at 8:35 PM Jeroen Ooms <jeroen using berkeley.edu> wrote:
> > >>
> > >> Is there a way to generate the package reference manual in a (one
> > >> page) html format? It would be nice to access reference manuals
> > >> from devices without a pdf reader.
> > >
> > > I don't think so, but it would certainly be a nice feature to have.
> > >
> > > Most of the necessary code is already there, so it shouldn't be too
> > > difficult. We'll work on it.
> >
> > I think this would be better done in a contributed package rather than
> > in core R, because there are lots of customizations that people would want:
> >
> > - Some people would want to execute the example code, like pkgdown does.
> > - Some people would want each help page in a separate HTML page (like
> > pkgdown), but with links to step through all the pages (I don't think
> > pkgdown does this).
> > - People would want to customize the look of the page, possibly with
> > syntax highlighting, or just different fonts and layouts.
> >
> > Adding an "all in one page" option to pkgdown might be the easiest way
> > to do this, because they already have a lot of customization
> > possibilities.  But there are probably other "make a web page for this
> > package" packages out there.
>
> Yes, that might be a good alternative.
>
> > If you do include it in base R, please at least allow the CSS to be
> > customized.
>
> Sure. So far I was only thinking of adding a couple of arguments to Rd2HTML()
>
> - 'standalone=TRUE' (FALSE would skip the header and footer), and possibly
>
> - 'Rhtml=FALSE' (TRUE would wrap the examples inside <!--begin.rcode and end.rcode-->
>
> This should make it easier to build up whatever is desired, regardless of what base R implements. HTMLheader() already has an option to specify the CSS file, so that could be used to create the header.
>
> Best,
> -Deepayan
>
> > Duncan Murdoch
>
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fstat.ethz.ch%2Fmailman%2Flistinfo%2Fr-package-devel&data=04%7C01%7Ca.j.godfrey%40massey.ac.nz%7Cff60d60fe13f4d00e28e08da1f0ef10b%7C388728e1bbd0437898dcf8682e644300%7C1%7C0%7C637856446305715235%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=6e8ipmcWsUoviATnNU0KpPDzkozRKUOPMfqy2CtAgPg%3D&reserved=0
>
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel