As of 2021, the internet might be the single greatest source of knowledge that ever existed, especially for programming. Via any web search engine it is possible to find an answer to most of the questions one could come across when working on an R script. Good ol' copy and paste from StackOverflow. However, there are times when you just want to RTFM – read the freaking manual. Be it for really understanding what this one obscure parameter really does or for understanding the return value of a function.

And this is where R does an amazing job at providing the user an easy-to-use way and consistent of interacting with the package help. Having had a look at some other languages, to this day I think R does a solid job at providing help and documntaiton to the user. Even more, the integration in RStudio is just amazing – hitting F1 on any function for help; just genious. Or even working on a headless server, running ?somefunction drops you into a pager for the help page.

However, there are times, when the standardized PDF package documentation is just a better place to find help on a subject. Sometimes, you know there is a function in a specific package, and you want to search for it, or you need to look up a bunch of functions from the same package. Or sometimes it is just to explore the possibilities a package can provide. In these cases I personally like to download the packages' PDF reference from the Reference manual section of package page such as this one.

But, when working with a lot of packages, it might be daunting to download all the PDFs and, even more, keep them organized and up-to-date. This is where I wanted to improve my life a bit. I wanted to have an easy-to-use interface to all PDFs of the packages I needed to read up on. This is when I came up with a simple dmenu script that helps download, cache, open and update my R reference PDFs. I have bound that script to a shortcut key chord SUPER+Z R to launch it from anywhere on my desktop. In short, here is what it does:

Once launched, a dmenu prompt appears which asks for the package you want to read.

/posts/img/r_pdf_dmenu.png
Dmenu prompt asking for which PDF reference to launch.

You can either select one of the packages you searched for previously or type a new package name. If a package was previously included, it will be loaded from the cached files located in $HOME/.cache/R-pdfs/. If a new package is asked for, it will be downloaded and cached locally. Either way, eventually the package reference PDF will be shown in zathura for you to explore.

/posts/img/r_pdf_sf.png
Example of the PDF reference manual of the sf package.

As a nice feature, the option ~~update~~ will go through all cached PDFs and check whether there is a new version of the package available. If so, the new pacakge will be downloaded and cached.

Under the hood, the script uses nothing fancy, just some GNU core utils, dmenu, notify-send, pdftotext and of course a PDF reader of choice. As for the latter, I use zathura as it is light, minimal and fast.

Feel free to use the script as you whish. If you encounter any problems feel free to open an issue on GitHub.