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

[Georgi Boshnakov]

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 using gmail.com] 
Sent: 30 September 2019 21:17
To: Georgi Boshnakov
Cc: Viechtbauer, Wolfgang (SP); r-package-devel using 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 using 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

-- 
http://hadley.nz