Hyperlinks into Writing R Extensions (the manual)

[jennybc]

Devise some standard approach where we can note, for each chapter, the most relevant section of WRE.

Split off and generalized from part of #805.

[jennybc]

Obviously that should be a hyperlink. Do it such a way that it's not terribly painful to switch from the official page to our Quarto-ized one (or vice versa) for these links.

[ateucher]

Unfortunately I think switching between the Quarto-ized version and the official pages will be painful because their structure is quite different, even though they're built from a common source (they leverage the nodes and sections/subsections etc differently). I don't think there's an easy way to reliably convert a url from one to the other except for possibly the basic chapter headings.

For example:
These two urls are for the same content on the two pages:

https://cran.r-project.org/doc/manuals/r-release/R-exts.html#An-example
vs
https://rstudio.github.io/r-manuals/r-exts/Creating-R-packages.html#an-example
(source)

as are these:

https://cran.r-project.org/doc/manuals/r-release/R-exts.html#An-external-pointer-example
vs
https://rstudio.github.io/r-manuals/r-exts/System-and-foreign-language-interfaces.html#an-example
(source)

[jennybc]

I think the right move might be to introduce one level of indirection and maintain a central list of WRE links, i.e. use reference-style links instead of inline. Or do something in the redirect file? Then, at least, those are collected and easy to enforce some sort of system on. But I haven't yet looked into how/if this works in Quarto or not. I figure the next stage of the publishing process will introduce various constraints around URLs and we'll tackle it then.

[ateucher]

The redirects file is a good idea, though I wonder how that will work when converted to print?

Unfortunately reference-style links don't appear to work in a multi-file book format (i.e., I don't think we could store the links in a single file and have them be referenced from different files across the book).

Another option, though maybe really ugly, would be to write an R function that you call in an inline r chunk that generates a markdown link from a table of links, with an argument for the cran or quarto version of the link?

[jennybc]

I asked Sara whether I should deal with this right now or let it wait for the next phase and the answer is to let it wait:

I think it's totally fine to leave hyperlinks as is for now and tackle them during copyediting and proofreading. I will include a note for the production team so they know what to expect.

[ateucher]

Ok great. Would it be worth at least making sure they are all to the CRAN pages or all to the quarto pages?

[jennybc]

If you made such a PR, that would be very welcome.

But basically from now-ish, an asciidoc version of the book will be leading a parallel life over in O'Reilly's system.

But rationalizing what's going here remains desirable and there will, no doubt, be instances of "good changes" flowing both directions. That will just be a rather manual process from this point on.