Using hyperlinks instead of vignette() calls for readability; doing the same for vignette titles without links for consistency

[Anirban166]

Closes #6612

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.60%. Comparing base (03c647f) to head (daf7ba9).
Report is 2 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #6617   +/-   ##
=======================================
  Coverage   98.60%   98.60%           
=======================================
  Files          79       79           
  Lines       14518    14518           
=======================================
  Hits        14316    14316           
  Misses        202      202           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests

[Anirban166]

Two things that I can incorporate into this PR which I think are related or I hope not off-topic: (but need feedback/opinions)

A) Removal of the mentions for the non-existent(?) 'design' vignette, e.g.:

data.table/vignettes/datatable-reference-semantics.Rmd

Line 341 in 03c647f

However we could improve this functionality further by *shallow* copying instead of *deep* copying. In fact, we would very much like to [provide this functionality for `v1.9.8`](https://github.com/Rdatatable/data.table/issues/617). We will touch up on this again in the *data.table design* vignette.

data.table/vignettes/datatable-intro.Rmd

Line 317 in 03c647f

We could have accomplished the same operation by doing `nrow(flights[origin == "JFK" & month == 6L])`. However, it would have to subset the entire `data.table` first corresponding to the *row indices* in `i` *and then* return the rows using `nrow()`, which is unnecessary and inefficient. We will cover this and other optimisation aspects in detail under the *`data.table` design* vignette.

B) Changing items of the form text: link to be hyperlinks, or of the format [text](link), e.g.:

data.table/vignettes/datatable-joins.Rmd

Lines 685 to 695 in 03c647f

	## Reference
	- *Understanding data.table Rolling Joins*: https://www.r-bloggers.com/2016/06/understanding-data-table-rolling-joins/
	- *Semi-join with data.table*: https://stackoverflow.com/questions/18969420/perform-a-semi-join-with-data-table
	- *Cross join with data.table*: https://stackoverflow.com/questions/10600060/how-to-do-cross-join-in-r
	- *How does one do a full join using data.table?*: https://stackoverflow.com/questions/15170741/how-does-one-do-a-full-join-using-data-table
	- *Enhanced data.frame*: https://rdatatable.gitlab.io/data.table/reference/data.table.html

## Reference

- - *Understanding data.table Rolling Joins*: https://www.r-bloggers.com/2016/06/understanding-data-table-rolling-joins/ 
+ - [*Understanding data.table Rolling Joins*](https://www.r-bloggers.com/2016/06/understanding-data-table-rolling-joins/) 
  
- - *Semi-join with data.table*: https://stackoverflow.com/questions/18969420/perform-a-semi-join-with-data-table
+ - [*Semi-join with data.table*](https://stackoverflow.com/questions/18969420/perform-a-semi-join-with-data-table) 
  
- - *Cross join with data.table*: https://stackoverflow.com/questions/10600060/how-to-do-cross-join-in-r 
+ - [*Cross join with data.table*](https://stackoverflow.com/questions/10600060/how-to-do-cross-join-in-r)

- - *How does one do a full join using data.table?*: https://stackoverflow.com/questions/15170741/how-does-one-do-a-full-join-using-data-table   
+ - [*How does one do a full join using data.table?*](https://stackoverflow.com/questions/15170741/how-does-one-do-a-full-join-using-data-table)

- - *Enhanced data.frame*: https://rdatatable.gitlab.io/data.table/reference/data.table.html   
+ - [*Enhanced data.frame*](https://rdatatable.gitlab.io/data.table/reference/data.table.html)

[Anirban166]

Also, do we need to ping @Rdatatable/translators or the translation teams for this update? @tdhock

[tdhock]

to address off-line use, #6612 (comment)
can this be changed from

[*Keys and fast binary search based subset*](datatable-keys-fast-subset.html)

to

[`vignette("datatable-keys-fast-subset", package="data.table")`](datatable-keys-fast-subset.html)

which renders as vignette("datatable-keys-fast-subset", package="data.table")

[Anirban166]

Certainly, but what do you suggest for rephrasing the text around it? or should it stay the same? (it reads a bit odd, but it might just be me)

For e.g., in the case you highlighted above, it currently reads as '... in the Keys and fast binary search based subset vignette ...' so should I change it to:
i) ' ... in vignette("datatable-keys-fast-subset", package="data.table") ...' (discarding the word 'vignette' for repetition)
ii) or ' ... in the vignette("datatable-keys-fast-subset", package="data.table") ...' (sounding more natural as in 'the vignette')
iii) or simply ' ... in the vignette("datatable-keys-fast-subset", package="data.table") vignette ...'

[tdhock]

whatever is easiest is fine with me

if you have time to make it sound natural, that is great

[Anirban166]

Thanks! I think the current version looks fine and does a good job in considering both points (hyperlinks, off-line use) so I'm cool with it (let me know if you need any other changes)

[tdhock]

great thanx

[tdhock]

here is some code I used to check that the text and link are consistent,

vignette.line.vec <- c(
'We have seen this example already in the `vignette("datatable-reference-semantics", package="data.table")` and the `vignette("datatable-keys-fast-subset", package="data.table")`.',
'We have seen this example already in the vignettes [`vignette("datatable-reference-semantics", package="data.table")`](datatable-reference-semantics.html) and [`vignette("datatable-keys-fast-subset", package="data.table")`](datatable-keys-fast-subset.html).',
'We will discuss fast *subsets* using keys and secondary indices to *joins* in the next vignette, `vignette("datatable-joins", package="data.table")`.',
'We will discuss fast *subsets* using keys and secondary indices to *joins* in the [next vignette (`vignette("datatable-joins", package="data.table")`)](datatable-joins.html).')
  
Rmd.line.list <- list()
for(f in Sys.glob("*.Rmd")){
  Rmd.line.list[[f]] <- readLines(f)
}
Rmd.line.vec <- do.call(c, Rmd.line.list)
vignette.line.vec <- grep("vignette(",Rmd.line.vec,fixed=TRUE,value=TRUE)

nc::capture_all_str(
  vignette.line.vec,
  '\\[',
  text=".*?",
  '\\]\\(',
  vig_name='datatable-.*?',
  '.html'
)[
, pattern := sprintf('`vignette("%s", package="data.table")`', vig_name)
][
, .(expected=grepl(
  pattern,
  text, fixed=TRUE)
  ),
  by=.(text,pattern)
]

if links are consistent then we get TRUE in expected column.

[Anirban166]

Thanks for sharing, neat stuff with nc!

[MichaelChirico]

This is nice! I may have missed something -- is there a plan to prevent regression here (i.e., any future vignettes/updates to vignettes which generate new references to other vignettes, which do not wind up linked in this way)?

[tdhock]

good idea, is that something we can enforce via lint?

[MichaelChirico]

Yea, we can probably do something for most cases with a simple regex (probably in the md-lint job) check for vignette(..., package="data.table") that's not part of a markdown link.

The case changed here for datatable-intro is much harder though, maybe an LLM could find it.