Collating package vignettes

[HenrikBengtsson]

Background

In the HTML help and on CRAN package pages, vignettes are ordered by their filenames.

Issue

To control the ordering of the vignettes, developers rename the vignette files, for instance, by adding numbers as in future-1-overview.md, future-2-details.md, ... The problem with this approach, other than being tedious, is that when injecting new vignettes, or reordering existing ones, the filenames need to be renamed. Renaming files change existing URLs on CRAN pages, which will break any links to the online vignettes and it might also affect search engines.

Proposal

Add a mechanism to control the ordering of package vignettes. This could be done by adding a new vignette markup, e.g. %\VignetteIndex{2} where 2 can be any non-missing integer. The vignettes will be ordered by their relative %\VignetteIndex{<index>} and then by their filenames. A vignette without an explicit index is treated as %\VignetteIndex{+Inf}.

Note how %\VignetteIndex{<index>} resembles the %\VignetteIndexEntry{<title>} markup name.

What needs to be updated

I think that the implemention of this would take place in the tools package, because where package builing is taking place. Specifically, I believe it's src/library/tools/R/Vignettes.R that needs to be updated. The functions that I can imagine need to be updated are:

• tools::vignetteInfo()

• tools:::.build_vignette_index()

PS. This proposals was taken from HenrikBengtsson/Wishlist-for-R#92.

[MichaelChirico]

To me the natural place for this would be in the DESCRIPTION, e.g. a VignetteCollate field analogous to Collate for R sources. Could you comment on the advantages of the proposed VignetteIndex approach?

[HenrikBengtsson]

Could you comment on the advantages of the proposed VignetteIndex approach?

The idea was that you could tweak individual entries without having to list all. Oth, it's rare to have very many vignettes, so to listing them manually is not that big of a deal.

One thing that needs to be dealt with is what should happen if the set of files listed under VignetteCollate does not match the set of package vignettes. By only specifying the VignetteIndex and sort by them, that is a non-issue.

No biggie, but that could be something a sprint could discuss.

[mmaechler]

Partly a matter of taste, of course, notably of R-core. ... (who would typically see proposals once they are on R's bugzilla).
Personally, I'd prefer if the DESCRIPTION file is not "polluted" by such things, and so would prefer '@HenrikBengtsson 's proposal.

[MichaelChirico]

Makes sense... I guess the reason we're stuck with Collate in DESCRIPTION for the R/ sources, then, is the lack of a metadata markup for R sources. E.g. we could imagine something like #<01> at the top of a file telling the collate order. (not advocating for that or anything like it, just thinking aloud to be sure I understand the difference vs. vignettes)

[hturner]

Thanks for this idea @HenrikBengtsson, I think this has good potential as a sprint project as it would suit people that have some experience of package development but are new to contributing to base R. It is also good to have some support for your proposal from @mmaechler. Would you mind opening a wishlist item on Bugzilla - that way we may get feedback from other members of R Core and there is a report against which a patch could be submitted during the sprint.

Some people that come to mind for this project are @kakopo, @paocorrales, @BerylKanali.

People working on this item might pick up other open issues related to vignettes, e.g.

Bug ID	Level	Status	Topic	Action(s)	Programming skills
https://bugs.r-project.org/show_bug.cgi?id=16333	Intermediate	patch welcome	enabling custom vignette engine	create patch	R
https://bugs.r-project.org/show_bug.cgi?id=17185	Intermediate	FIXME issue	avoiding file name ambiguities	create patch	R
https://bugs.r-project.org/show_bug.cgi?id=17416	Intermediate	suggested solution	documenting use of child documents	create patch	texinfo
https://bugs.r-project.org/show_bug.cgi?id=18191	Intermediate	patch welcome	allowing package to provide own vignette engine	create patch	R
https://bugs.r-project.org/show_bug.cgi?id=18226	Intermediate	suggested solution	avoiding earlier vignette affecting later one	create patch	R

Note that 17185 and 18226 were discussed at the Bug BBQ last year, so there is some useful discussion on the bug-bbq repo issues and it would be nice to move forward on these issues. @gmbecker and @bastistician contributed to the discussion there and may be interested to mentor people working on these/related issues at the sprint.

[HenrikBengtsson]

I've added this feature request to BugZilla, cf. PR18576.