add package anchors to cross-refs

[LiNk-NY]

No description provided.

[hpages]

Hi Marcel,

I wonder why sometimes the \link[package]{...} syntax is used (e.g. \link[Rsamtools]{FaFile}) and sometimes the \link[package:file]{...} syntax is used (e.g. \link[GenomicRanges:GRanges-class]{GRanges}).

If there's no good reason for using the latter, we should avoid it because it generates links that tend to break more easily than when using the former.

In fact, at some point in the past someone started to systematically replace \link[package]{...} with \link[package:file]{...} in many core packages with no good reason, but this only made all the links harder to maintain when we need to move things around. I must have reverted hundreds of these changes in the past years so I just want to make sure that we have a good reason to reintroduce them 😉

Thanks!

[LiNk-NY]

Hi Hervé,

I used \link[package]{...} for plain functions and \link[package:file]{...} for linking to the class documentation.
I think it is better to be explicit about linking to the class documentation rather than the alias GRanges because
these are not always the same page, e.g., constructor functions can have different documentation pages so the former would point to a different page than intended. For GRanges though, these are the same page.

[LiNk-NY]

@hpages
bumping this topic

[hpages]

We're not allowed to have duplicated alias in a given package (this triggers an R CMD check warning) so something like \link[GenomicRanges]{GRanges} is unambiguous and well defined i.e. it will link to the uique man page in the GenomicRanges package that contains the GRanges alias.

As I mentioned above, years ago someone decided to replace all the links in core-team maintained packages with the \link[package:file]{alias} syntax and it turned out to make it more difficult to maintain these links when things move around. This is a case of overspecification IMO.