Clickable hyperlinks inside vignettes

[legendre6891]

Thanks Rcpp maintainers for this excellent package.

I am wondering if it is possible to make the hyperlinks (e.g. table of contents, bibliography items) in the Rcpp-FAQ and other vignettes clickable(*)? I think it would be quite useful in navigating the documents.

There is an older version of the document with this feature; so I am not sure this is an intentional decision to change it to its current state. In any case, I'd be happy to contribute my time to make the improvement happen.

Cheers!

(*) Relatedly: Have the table of contents shows up in PDF readers' navigation sidebars?

[eddelbuettel]

The older version is deprecated, we now use the PNAS style from the pinp package. But I am not sure why its hyperlinks do not work.

[eddelbuettel]

Hm, if one looks at for example the vignette of the pinp package itself then hyperlinks work in the bibliography, the acknowledgements and links in the text.

So with that the question becomes more one of 'how does one make sectioning in markdown work as links in a table of contents' and that I do not know.

[eddelbuettel]

It also works when you locally build the pdf from the Rmd. But the package tries to be even more clever and does something else where we include the pre-made pdf inside the Rnw file and process as an Sweave file. And that seems to break the links. Which I had been unaware of.

[eddelbuettel]

Also looking more closely at the references in the e.g. the Rcpp FAQ vignette we that

• references as URL hyperlinks work eg on page 14 the second-to-last link for https://arma.sf.net works
• references as (newer) DOIs do not work eg also on page 14 just after it: 'doi:10.32614/CRAN.package.inline' should be a link but is not

When I re-render the vignette as pdf from Rmd both work, when I then wrap it into pdf via Rnw it is not. Hm.

[legendre6891]

Thank you Dirk. I took a look at the source and see that the Rcpp-FAQ is generated in this way

\documentclass{article}
\usepackage{pdfpages}
%\VignetteIndexEntry{Rcpp-FAQ}
%\VignetteKeywords{Rcpp, FAQ, R, Cpp}
%\VignettePackage{Rcpp}
%\VignetteEncoding{UTF-8}

\begin{document}
\includepdf[pages=-, fitpaper=true]{pdf/Rcpp-FAQ.pdf}
\end{document}

The culprit is in how the pdfpages package works: its documentation on page 2 reads:

When including pages of a PDF only the so called content stream of these pages is copied but no links. [...] Thus, all kinds
of links1 will get lost during inclusion.

Indeed it doesn't look trivial to fix.

[legendre6891]

But it's indeed good to know that the "raw" PDFs have working links. Perhaps the links at https://rcpp.org should point to that, instead of the CRAN's vignettes, e.g. one of these links

https://raw.githubusercontent.com/RcppCore/Rcpp/refs/heads/master/vignettes/pdf/Rcpp-FAQ.pdf
https://raw.githubusercontent.com/RcppCore/Rcpp/refs/tags/1.1.0/vignettes/pdf/Rcpp-FAQ.pdf

should just work.

[eddelbuettel]

Yes. I switched to relying on pdfpages (as describe in a short post by Mark here) when something frustrated me about the rmarkdown and knitr dependencies. But I also re-asserted today (like you) that pdfpages is the culprit here. (There was some hope in latex package pax and newpax, but alas does not seem to fix it).

So I think I will rewire the vignettes to not include the premade pdf files (destroying links) but by including the pre-made latex source (which rmarkdown writes to an intemediary file). That way we get the links, and Rcpp can remain zero-dependency at install or run-time.

[eddelbuettel]

The Rcpp website now contains local copies of the pdf files with working links.

[legendre6891]

Super, much thanks Dirk.

[eddelbuettel]

@Enchufa2 I see basically two ways out of this:

Method 1: As discussed, embed the generated latex source in the Rnw, i.e. make the Rnw essentially be the latex source plus the four lines of vignette meta information; this also requires the files Rcpp.bib, jss.bst and pinp.cls (all alreadin in viagnettes/rmd/ too) and a small touch up to the Makefile to also run bibtex; I seem to have this working on demonstrated by one vignette I modified locally. This also removes the vignettes/*.pdf file from your ghostscript re-rendering PR, we really only use the ones in pdf/ which I refreshed for 1.1.0.

Method 2: We could borrow Henrik's small 'asis' vignette builder (or call it, with a Suggests: on R.rsp). That might be cleaner but I hesitate of course over another Suggests. Copying the two functions he has (with full attribution, of course) may be an alternative.

Thoughts?

[eddelbuettel]

I have method 2 working in a small test package providing just the minimal subset of his two functions, plus one .onLoad() registration. 44 lines with plenty of empty lines, needs a minimal amount of roxygen docs around it so that the functions are then exportable so that my other packages can use it --- so it looks like this is viable, and should simplify the Rcpp a little at the cost of two new R functions.

[Enchufa2]

I really like method 1 because it means no more binary files will be added as vignettes are updated, right? Any shortcomings?

[eddelbuettel]

Manual editing is tedious to keep sync. Extra bibtex steps. The (created by Rmarkdown) tex file is ugly and not meant for humans. Overall method 2 is closer to what we have: build from rmd to pdf offline but now store the pdf in in vignettes/ directly instead of an extra directory pdf/ and no more .Rnw file wrapping the pdf. Instead a small *.pdf.asis file with the vignette info (see how package R.rsp does this for the pdf example, it does more we ignore the others). I can prepare two PRs if we want to ignore one, I really think method 1 is 'dirtier'.

There is a possible middle ground method 3. We can (from the Makefile) access the rendering of our .Rmd source, access the .tex file generated, prepend the four lines of vignette method info and thereby create the file using in method 1 on the fly (and the remove it). Do you like that better?