[R] table of contents link style in R's PDF docs

[Duncan Murdoch]

On 25/09/2013 11:38 PM, Ben Harrison wrote:
> Hello,
> I am mildly annoyed each time I use a PDF doc of an R package that the
> table of contents hyperlinks are *only* on the page numbers. To activate
> a hyperlink, one must carefully scan sideways from the text item wanted
> to the far right of the page and click on a tiny box. Multiply that mild
> annoyance by the large number of times I need to look up package help
> docs, and I find myself here writing this message.
>
>   From my understanding (albeit poor), all of the R docs for packages are
> to be written in Rd format. From that they are converted by the
> functions in the tools package as required (to latex and PDF, or HTML,
> etc). So the only thing that controls in the PDF docs the hyperlinks one
> way or another is the latex style file used - in this case I believe it
> is Rd.sty (/usr/share/R/share/texmf/tex/latex/Rd.sty on my system).
>
> Line 303 of that file contains the single setting of the \hypersetup{}
> command for whether or not the text in the table of contents is
> hyperlinked, or the page number:
>
>       linktocpage,%
>
> which causes it to implicitly be set to True. Setting it to false (or
> just commenting out that line I suppose as false is the default) would
> mean the *text* in the TOC is hyperlinked.
>
> So, is the desired behaviour intended to be that only the page numbers
> are hyperlinked (and therefore to annoy me), or has no-one really
> bothered themselves with it that much, or something else?

It's been the way it is for about 14 years, and I don't recall anyone 
else complaining, so I'd conclude it must have been set that way with 
you in mind.

More seriously, I prefer having the page number clickable to having just 
the text clickable.  Having both would be fine for both of us. There's a 
partially documented option "linktoc=all" that does that; it was added 
to the hyperref package in 2008, so you can hardly blame R for not using 
it back in 1999.  The only problem I can see with using it now is that 
some users might not have a sufficiently up-to-date LaTeX installation 
to use it; if their hyperref package doesn't know about linktoc, they 
won't be able to build anything at all.

>
> Can I recreate all the documentation on my system after I make a change
> to Rd.sty?

Easiest would be to just do a rebuild of R, but you could also do the 
PDF manuals one at a time using

R CMD Rd2pdf  <pkg>

from the directory where the package is installed, or where its source 
lives.

Duncan Murdoch
>
> ______________________________________________
> R-help at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.