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

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 at r-project.org> On Behalf Of Deepayan Sarkar
Sent: Saturday, 16 April 2022 6:36 am
To: Duncan Murdoch <murdoch.duncan at gmail.com>
Cc: Jeroen Ooms <jeroen at berkeley.edu>; R Package Development <r-package-devel at 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 at 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 at 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

system(paste("open", file.path(base::system.file(), "../../doc/manual/R-exts.pdf")))
system(paste("open", file.path(base::system.file(), "../../doc/manual/R-exts.html")))

On Apr 18, 2022, at 17:40, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:

This seems like a strong argument to replace the PDF manual with an HTML version of the same document.

Duncan Murdoch

On 16/04/2022 2:49 a.m., Jonathan Godfrey 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 at r-project.org> On Behalf Of Deepayan Sarkar
Sent: Saturday, 16 April 2022 6:36 am
To: Duncan Murdoch <murdoch.duncan at gmail.com>
Cc: Jeroen Ooms <jeroen at berkeley.edu>; R Package Development <r-package-devel at 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 at 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 at 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

I am pleased to have an html option for all the reasons that have
been discussed.

I am opposed to dropping the pdf version.  I find it much more
convenient to have a document where the paragraphs and figures stay
where you put them, and not wander around based on accidents of
window size and magnification.  I like stable page numbers as well as
section numbers.

Having both html and pdf would be consistent with the other
documentation.

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.