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.godf...@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-boun...@r-project.org> On Behalf Of > Deepayan Sarkar > Sent: Saturday, 16 April 2022 6:36 am > To: Duncan Murdoch <murdoch.dun...@gmail.com> > Cc: Jeroen Ooms <jer...@berkeley.edu>; R Package Development > <r-package-devel@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.dun...@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 <jer...@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@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@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-package-devel ______________________________________________ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
