Enable pkgdown/downlit cross-package links to rmarkdown

[hadley]

See https://github.com/r-lib/downlit#cross-package-links for details

[yihui]

@cderv I didn't merge this PR because I don't like having two URLs here. Is there a way to configure pkgdown so that it doesn't have to read the URL from DESCRIPTION?

[hadley]

There isn’t, sorry.

[yihui]

Perhaps it's a stupid question, but what is url in _pkgdown.yml for?

[hadley]

It's the url of the site? pkgdown needs it in order to generate the full path to the reference and article parts of the site.

[yihui]

I mean why we have to define the same URL in both DESCRIPTION and _pkgdown.yml? i.e. why not use this url in _pkgdown.yml?

[hadley]

Because many people have existing urls in their DESCRIPTION file that are not pkgdown sites. Additionally, people often want to list both the user facing website and the github website, so pkgdown would then need some heuristic to figure out which url you mean when there were multiple urls.

[cderv]

@yihui I did not know that as there was not comment. I just thought is was waiting to be reviewed and merged.

I felt it was better to have the link from downlit autolinking points toward our pkgdown website instead of the default, currently

> downlit::autolink("rmarkdown::render")
[1] "<a href='https://rdrr.io/pkg/rmarkdown/man/render.html'>rmarkdown::render</a>"

IMO it seems better to have this

> downlit::autolink("rmarkdown::render")
[1] "<a href='https://rmarkdown.rstudio.com/docs//reference/render.html'>rmarkdown::render</a>"

What is the drawback of having two URLs in DESCRIPTION ?

[yihui]

Because many people have existing urls in their DESCRIPTION file that are not pkgdown sites.

@hadley Sorry I didn't get it. I was asking, since you have url in _pkgdown.yml, why not use this url directly? Why must we duplicate it in DESCRIPTION? To me, it feels more natural that if pkgdown needs a URL, we should be able to provide this URL in pkgdown's config file, i.e., _pkgdown.yml.

Additionally, people often want to list both the user facing website and the github website

I don't know if this "people often want to list both" is true. Even if it is true, it feels weird to me that pkgdown needs to force users into listing a pkgdown website in DESCRIPTION, especially after it has already been provided in _pkgdown.yml.

---

I did not know that as there was not comment. I just thought is was waiting to be reviewed and merged.

@cderv The PR came at a difficult time of mine, and was left behind. I'll try to be more active in the future if I have concerns about certain PRs.

I felt it was better to have the link from downlit autolinking points toward our pkgdown website instead of the default, currently

I have no question with that.

What is the drawback of having two URLs in DESCRIPTION ?

First, I prefer a single entry point. When you have two URLs, users have to think about or try to decide which URL to open. This URL could be either the Github repo, or rmarkdown.rstudio.com.

Second, for citation entries automatically generated from toBibtex(citation('rmarkdown')), we may have problems with multiple URLs, e.g.,

@Manual{,
  title = {rmarkdown: Dynamic Documents for R},
  author = {JJ Allaire and Yihui Xie and Jonathan McPherson and Javier Luraschi and Kevin Ushey and Aron Atkins and Hadley Wickham and Joe Cheng and Winston Chang and Richard Iannone},
  year = {2021},
  note = {R package version 2.7.0},
  url = {https://rmarkdown.rstudio.com/docs/, https://github.com/rstudio/rmarkdown},
}

The URL may end up being \url{https://rmarkdown.rstudio.com/docs/, https://github.com/rstudio/rmarkdown} in LaTeX output, which is wrong, and should have been \url{https://rmarkdown.rstudio.com/docs/}, \url{https://github.com/rstudio/rmarkdown}. Similarly, it could become <a href="https://rmarkdown.rstudio.com/docs/, https://github.com/rstudio/rmarkdown">https://rmarkdown.rstudio.com/docs/, https://github.com/rstudio/rmarkdown</a> in HTML output.

[hadley]

@yihui pkgdown needs a url at two times — it needs a url when you build the site in order to generate (e.g.) https://rmarkdown.rstudio.com/docs/pkgdown.yml. It also needs the url when other packages build their websites in order to find the pkgdown.yml file for that package. Since _pkgdown.yml is not included in the built package, and since most people want to advertise their package website, it makes the most sense to put this in the URL field of the description. There are of course other ways that this could have been designed, but this approach seemed like a simple solution and no one complained about it at the time.

I can't replicate your problem with citation():

packageDescription("dplyr")$URL
#> [1] "https://dplyr.tidyverse.org, https://github.com/tidyverse/dplyr"

toBibtex(citation("dplyr"))
#> @Manual{,
#>   title = {dplyr: A Grammar of Data Manipulation},
#>   author = {Hadley Wickham and Romain François and Lionel Henry and Kirill Müller},
#>   year = {2021},
#>   note = {R package version 1.0.4},
#>   url = {https://CRAN.R-project.org/package=dplyr},
#> }

^{Created on 2021-02-08 by the reprex package (v1.0.0)}

[cderv]

After installing the dev version, see the two url in citation

toBibtex(citation("rmarkdown"))
#> @Manual{,
#>   title = {rmarkdown: Dynamic Documents for R},
#>   author = {JJ Allaire and Yihui Xie and Jonathan McPherson and Javier Luraschi and Kevin Ushey and Aron Atkins and Hadley Wickham and Joe Cheng and Winston Chang and Richard Iannone},
#>   year = {2021},
#>   note = {R package version 2.6.6},
#>   url = {https://rmarkdown.rstudio.com/docs/,
#> https://github.com/rstudio/rmarkdown},
#> }
#> 
#> @Book{,
#>   title = {R Markdown: The Definitive Guide},
#>   author = {Yihui Xie and J.J. Allaire and Garrett Grolemund},
#>   publisher = {Chapman and Hall/CRC},
#>   address = {Boca Raton, Florida},
#>   year = {2018},
#>   note = {ISBN 9781138359338},
#>   url = {https://bookdown.org/yihui/rmarkdown},
#> }
#> 
#> @Book{,
#>   title = {R Markdown Cookbook},
#>   author = {Yihui Xie and Christophe Dervieux and Emily Riederer},
#>   publisher = {Chapman and Hall/CRC},
#>   address = {Boca Raton, Florida},
#>   year = {2020},
#>   note = {ISBN 9780367563837},
#>   url = {https://bookdown.org/yihui/rmarkdown-cookbook},
#> }

^{Created on 2021-02-09 by the reprex package (v1.0.0)}

But I think this because of what we use in CITATION

rmarkdown/inst/CITATION

Lines 8 to 19 in de0e2ec

	citEntry(
	entry = 'manual',
	title = paste('rmarkdown:', meta$Title),
	author = auth,
	year = year,
	note = vers,
	url = meta$URL,
	textVersion = paste0(
	paste(auth, collapse = ' and '), ' (', year, '). rmarkdown: ', meta$Title, '. ', vers, '.',
	' URL https://rmarkdown.rstudio.com.'
	)
	)

You don't have that file in dplyr so the citation generated if the default one, which is NOT using the URL field in DESCRIPTION
https://github.com/wch/r-source/blob/b12ffba7584825d6b11bba8b7dbad084a74c1c20/src/library/utils/R/citation.R#L1321-L1323

So we could in rmarkdown directly handle the multiple url cases to only keep one of them for citation.
I even wonder if using the URL to CRAN is not better than to github. I think that would solve the 2 urls problem in citation @yihui, right ?