I would like to suggest a few related improvements to vignette discovery
in utils.
The immediate motivation came from one of my own packages, which
currently has:
Vignettes in package 'RGenstat':
authentication-and-accounts Authentication and accounts with RGenstat
rgenstat-introduction Getting started with RGenstat
structured-genstat-tables Working with structured Genstat tables
A user who knows there is an introductory vignette might reasonably try
vignette("introduction", package = "RGenstat")
but currently needs to know the exact base name:
vignette("rgenstat-introduction", package = "RGenstat")
RGenstat is not currently on CRAN, but the same general issue can be
reproduced using the recommended grid package. For example, grid
contains a vignette named "displaylist", but
vignette("display", package = "grid")
does not find it.
I wonder whether vignette() could be a little smarter when an exact
match isn't found. In the latter case it might respond with something like
No vignette with topic 'display' was found.
Did you mean:
vignette("displaylist", package = "grid")
Similarly, where several partial or approximate matches are plausible,
it could list the corresponding valid vignette() calls.
I don't think an approximate match should automatically be opened. Exact
matches could retain their current behaviour, with partial/fuzzy
matching used only to suggest valid vignette names when exact lookup fails.
It also seems useful to have a vignette-specific analogue of help.search():
vignette.search("graphics")
vignette.search("display", package = "grid")
This could search vignette names, titles and keywords/concepts, using
the existing help-search infrastructure where possible. help.search()
already includes vignette names, titles and keywords, so this seems
conceptually close to functionality R already provides.
Searching vignette contents might also be worth considering at some
later point, if that can be done naturally and efficiently, but I don't
think it needs to be part of an initial implementation.
Finally, I wonder whether a simple
list.vignettes("grid")
would be worthwhile as a more discoverable wrapper of
vignette(package = "grid")
I realise that browseVignettes() already provides another way to
discover available vignettes. However, I see the two as serving somewhat
different purposes. browseVignettes() produces an HTML browser
interface, whereas vignette(package = ...) already provides a console
listing and returns the corresponding information as an R object.
list.vignettes() would therefore not replace browseVignettes() or add
fundamentally new functionality. Rather, it would give the existing
console/listing operation an explicit and discoverable name, instead of
requiring users to know that omitting the topic argument and specifying
the package name changes the role of vignette() from retrieving a
vignette to listing them.
This would give a fairly natural interface:
vignette("name") view a known vignette
list.vignettes() list available vignettes
vignette.search("term") search for relevant vignettes
browseVignettes() browse vignettes interactively in HTML
The main motivation is simply to make vignettes easier to discover
without changing the successful existing behaviour of vignette().
James