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.

[LiNk-NY]

Hi Hervé, @hpages

As far as I understand, \link[package:file]{alias} is a misconception. It should be thought of as \link[package:topic]{text} where if topic is missing, i.e., \link[package]{text} it is understood as \link[package:text]{text}.

More concretely, \link[MultiAssayExperiment:[[,MultiAssayExperiment,ANY,ANY-method]{subsetBy MAE method} would point to the subsetBy.Rd file where [[<-,MultiAssayExperiment,ANY,ANY-method is a topic / alias.

In otherwords, a tag such as \link[IRanges:DataFrameList-class]{DataFrameList} is merely cosmetic and is the same as \link[IRanges]{DataFrameList-class}.

With regards to moving files around, I think that as long as those topics / aliases are in the package's internal

system.file(package = "PACKAGE", "help", "aliases.rds")

there should be no issue finding the file.

Do you have a specific example where these type of changes make it harder to maintain?

Best regards,
Marcel

[hpages]

In otherwords, a tag such as \link[IRanges:DataFrameList-class]{DataFrameList} is merely cosmetic and is the same as \link[IRanges]{DataFrameList-class}.

My preference has always been to use \link[IRanges]{DataFrameList}. It's the shortest/simplest form. Also it has the nice property that the displayed text (DataFrameList) is the same as the alias. That means that when rendered in the man page, the text is something that the user can actually use if they want to follow the link at the command line with ?DataFrameList. Otherwise, the alias is hidding behind the text which doesn't help the user.

I've always been a big fan of the KISS principle but maybe I'm missing something about the benefits of using the complicated \link[package:topic]{text} form. If that's the case then feel free to go ahead with it.

Do you have a specific example where these type of changes make it harder to maintain?

When I refactored the IntegerRanges/IRanges class hierarchy in IRanges in 2018, I moved things around and broke some of the links in other packages that were using the \link[package:topic]{text} form. I don't remember the details but I remember that these links broke because of the :topic part that got added to them a few years before. In most cases the link would not have broken if it didn't have the :topic part, so the fix was to simply remove it.

[LiNk-NY]

I do prefer \link[IRanges]{DataFrameList} but this only works when both the constructor and the class are documented in the same page. For some classes this isn't the case and this link tag lacks specificity; that is where \link[IRanges:DataFrameList-class]{DataFrameList} may be used. I will take a look and minimize the more specific documentation links.