[R-pkg-devel] Require <package>-package.Rd?
Sorry, in the sequence of emails the context was probably lost, package ? package was a side note. I was referring to (what I believe is a fact) that <package>-package.Rd is not treated by pkgdown as an overall package description but package.Rd is and I think that the recommendation by devtools-related tools is to use package.Rd for this purpose. There are probably subtleties with aliases, as well. In my experience pkgdown, doesn't treat specially package-package.Rd (i.e., it puts the topic in alphabetical order with the rest of the index), which has nudged me to create yaml files (a good practice!) which I otherwise would not have done. I was not criticising this, only pointing out the difference. I think it is unfortunate but it is not a big issue and I also see the point of avoiding a '-' in such a crucial name. On the other hand, some packages have a main function with the same name as the package, and it may or may not be appropriate package.Rd to serve as a doc for both the function and the overall description of such a package. Georgi -----Original Message----- From: Hadley Wickham [mailto:h.wickham at gmail.com] Sent: 30 September 2019 21:17 To: Georgi Boshnakov Cc: Viechtbauer, Wolfgang (SP); r-package-devel at r-project.org Subject: Re: [R-pkg-devel] Require <package>-package.Rd? On Tue, Sep 24, 2019 at 8:07 AM Georgi Boshnakov
<georgi.boshnakov at manchester.ac.uk> wrote:
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.
I'm not sure what lead you to that believe, but we definitely support (and have supported for years) package?<package>. See, e.g. https://usethis.r-lib.org/reference/use_package_doc.html Hadley