Clean up links.md

[gracelawley]

File to edit: https://github.com/rstudio-education/stat545/blob/master/links.md (must be viewed on GitHub as raw to see the contents! See here)

• Only include links that are used in at least two .Rmds

• Look into a way to save base urls that appear multiple times as strings to recycle - e.g. https://happygitwithr.com/install-git.html, https://happygitwithr.com/git-client.html

• Change CRAN link from https://cran.r-project.org --> https://cloud.r-project.org

• Use rdrr.io instead of rdocumentation.org -- Use rdrr.io instead of rdocumentation.org #29

• Standardize formatting of link references in .Rmds

• Formalize the link reference formatting rules & add in a Contributing Guidelines section in the Appendix

[jennybc]

So, is this going to be a file with lots of entries like:

[wre]:https://cran.r-project.org/doc/manuals/R-exts.html

So that markdown links elsewhere can take the form [Writing R Extensions][wre]?

It would be good to articulate some policy around:

1. When to use an inline link vs. reference style link.

• Something like: whenever you link to something more than n times. n = 1?

1. When a reference style link should be defined locally or centrally (in links.md).

• Something like: whenever you link to something in more than n files. n = 1?

I also just read that you can use reference style links with just the link text, which is pretty interesting. I suspect that if a link gets used often enough to set up for reference style links, we might also be able to label it with link text that is what you want ~90% of the time.

To be clear, continuing the above example, I think that means that this definition:

[Writing R Extensions]:https://cran.r-project.org/doc/manuals/R-exts.html

would allow inline links like [Writing R Extensions]. Check me on that!

[jennybc]

Oh wow, just in case it baffles anyone else. This file:

https://github.com/rstudio-education/stat545/blob/master/links.md

must be viewed on GitHub as raw. Otherwise it renders as markdown and there's nothing visible to look at. So this:

https://raw.githubusercontent.com/rstudio-education/stat545/master/links.md

[gracelawley]

So, is this going to be a file with lots of entries like:

[wre]:https://cran.r-project.org/doc/manuals/R-exts.html

So that markdown links elsewhere can take the form [Writing R Extensions][wre]?

Yes, exactly. This is what the links.md file is currently - it's a bit monstrous right now, I'm working on cleaning it up.

It would be good to articulate some policy around:

1. When to use an inline link vs. reference style link.

• Something like: whenever you link to something more than n times. n = 1?

1. When a reference style link should be defined locally or centrally (in links.md).

• Something like: whenever you link to something in more than n files. n = 1?

I think that this sounds good, I can add this to the top of links.md and in the README.md I am working on for an admin/ folder.

I also just read that you can use reference style links with just the link text, which is pretty interesting. I suspect that if a link gets used often enough to set up for reference style links, we might also be able to label it with link text that is what you want ~90% of the time.

To be clear, continuing the above example, I think that means that this definition:

[Writing R Extensions]:https://cran.r-project.org/doc/manuals/R-exts.html

would allow inline links like [Writing R Extensions]. Check me on that!

I just tested this in a practice bookdown and it seems to work the way you suggested! I will incorporate that into this bookdown.

[gracelawley]

@jennybc What do you think of this set up?

If a link appears in 2 or more .Rmds, add it to links.md with this format:

[ref-label]: link

Otherwise, put it at the end of the .Rmd with this format:

[#]: link

So for example:

The [dplyr][1] package, ([CRAN][2], [GitHub][3])
...
[1]: https://dplyr.tidyverse.org
[2]: https://CRAN.R-project.org/package=dplyr
[3]: https://github.com/hadley/dplyr

Using numbers instead of labels would make it easy to distinguish between which are "global" links and which aren't.

My only worry with using a mixture of inline style links (i.e. [text](url)) and reference-style links is that it might make it harder to maintain the links long-term (e.g. updating broken links, etc.). If only reference-style links are used then all the links will all be together at the end of each .Rmd instead of mixed in throughout the text.

[jennybc]

I think for things that appear to be a one-off (one usage in one file) at the time of writing, inline or reference-style is acceptable. You're right that reference-style has some maintenance advantages, but it has other disadvantages re: readability and not concentrating info in one place, which is nice when writing. Not sure either is globally optimal.

I like your proposal and rationale for the single-file reference-style links, i.e. to use the numbers as an additional signal re: where the link is defined.

Also 👍 on the proposal for multi-file links in links.md.

[gracelawley]

Oops nevermind, using numbers for the reference-style links won't work in bookdown 😕 . I tested it out and the labels have to be unique across all of the .Rmds.

So the revised set up:

If a link appears in 2 or more .Rmds add it to links.md with this format:

[ref-label]: link

If it appears in only one .Rmd & is only used once, add it as an inline-style link, e.g.

[dplyr](https://dplyr.tidyverse.org) is a package for data manipulation...

If it appears in only one .Rmd & is used more than once, add it as a reference-style link (using reference style links with just the link text when possible), e.g.

We will be using the functions from the [tidyverse] ([GitHub][tidyverse-github]) throughout this chapter
...
httr is yet another star in the [tidyverse] ([GitHub][tidyverse-github])
...
[tidyverse]: https://tidyverse.tidyverse.org
[tidyverse-github]: https://github.com/tidyverse/tidyverse

[jennybc]

Looking good. I'll expand on a few things. I think you should record these "attitudes" somewhere ... maybe initiate a contributing guide in the appendix? It's OK if it feels half-baked and only has this section at first. Still an improvement.

If a link appears in 2 or more .Rmds add it to links.md with this format

Yeah, but spell out the idea is that the ref-label should be some text that we can usually live with as link text. Also, I think this is OK for a single link that feels like something we might use in more than one place. That is, it's OK to add a new link like this, even if it's used in one place.

If it appears in only one .Rmd & is only used once, add it as an inline-style link, e.g.

I'd signal that this is acceptable. But a reference-style link, in that file or in links.md is also OK if contributor thinks that makes sense.

If it appears in only one .Rmd & is used more than once, add it as a reference-style link

Yeah, but it's contributor's discretion whether to include in links.md or bottom of file.

[jennybc]

High-level advice: imagine yourself reviewing a PR and something's not quite right with the link style. I want to be able to link to a specific section of a specific appendix page that tells someone how we think about this.