[R-pkg-devel] Require <package>-package.Rd?

[Viechtbauer, Wolfgang (SP)]

Hi Georgi,

help(package="utils") shows the index, not utils-package.Rd.

help(utils) shows utils-package.Rd.

Best,
Wolfgang

-----Original Message-----
From: Georgi Boshnakov [mailto:georgi.boshnakov using manchester.ac.uk] 
Sent: Tuesday, 24 September, 2019 15:02
To: Viechtbauer, Wolfgang (SP); r-package-devel using r-project.org
Subject: RE: Require <package>-package.Rd?

It is worth noting that 

help(package="<package>")

shows  file <package>-package.Rd, while 

help(<package>)

shows topic "package".

Topic <package>-package.Rd is also printed at the top of the pdf manual, while package.Rd follows the alphabetical ordering of the remaining topics. It is unfortunate that Hadley Wickham's tools (at least 'pkgdown') recommend and use <package>.Rd, instead of <package>-package.Rd as overall package description. 

Georgi Boshnakov

-----Original Message-----
From: R-package-devel [mailto:r-package-devel-bounces using r-project.org] On Behalf Of Viechtbauer, Wolfgang (SP)
Sent: 24 September 2019 13:16
To: r-package-devel using r-project.org
Subject: [R-pkg-devel] Require <package>-package.Rd?

Hi All,

When starting to work with an unfamiliar package, one might typically look for vignettes, a paper/book accompanying the package, a package website, and of course the help files themselves, but

help(package="<package>")

is often not so useful -- such a listing of functions (with titles) might not clarify what the main 'workhorses' of the package are and how to get started. Personally, the first thing I do is try:

help(<package>)

in the hopes that the package author(s) have created a <package>-package.Rd file to get new users started (or to point them to appropriate places to get going). In my experience, if such a package help file is available, it is tremendously useful.

Unfortunately, many packages do not provide a <package>-package.Rd file. I am curious how others and CRAN members would feel about making this a requirement (not retrospectively, but at least for new / resubmissions).

Best,
Wolfgang