[Rd] Proposal: improved vignette discovery in utils

[Kurt Hornik]

>>>>> James Curran via R-devel writes:

Dear James,

Sorry for the late reply, I was offline for the past 2 weeks.

Need to look at this in more detail, so a quick note for now: the
intended way of searching the docs from the R prompt is via
help.search(), e.g.

  help.search("display", package = "grid", types = "vig")

which in non-HTML mode gives

********************************************************************
Vignettes with name or keyword or title matching ‘display’ using fuzzy
matching:

grid::displaylist       Display Lists in grid

Type 'vignette(PKG::FOO)' to inspect entries 'PKG::FOO'.
********************************************************************

If options(help_type = "html"), it nicely uses the browser.

This only searches installed packages: one can also use the
RSiteSearch() interface to search.R-project.org.

Best
-k


> 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
> ______________________________________________
> R-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel