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
[R-pkg-devel] Require <package>-package.Rd?
10 messages · Joris Meys, Dirk Eddelbuettel, Georgi Boshnakov +3 more
Dear Dr. Vichtbauer, I'm not a CRAN member, but I personally think this is a sensible requirement. I try to include those in every package myself, even if it's only to direct people to a vignette. That said, I do look for vignettes first when I encounter an unfamiliar package actually. That format gives more possibilities for giving a good introduction to the package imho. My humble 2 cents Cheers Joris On Tue, Sep 24, 2019 at 2:17 PM Viechtbauer, Wolfgang (SP) <
wolfgang.viechtbauer at maastrichtuniversity.nl> wrote:
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
______________________________________________ R-package-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Joris Meys Statistical consultant Department of Data Analysis and Mathematical Modelling Ghent University Coupure Links 653, B-9000 Gent (Belgium) <https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g> tel: +32 (0)9 264 61 79 ----------- Biowiskundedagen 2017-2018 http://www.biowiskundedagen.ugent.be/ ------------------------------- Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php [[alternative HTML version deleted]]
Wolfgang, Joris, This may not necessarily work -- see "Goodhart's Law" [1] Once you impose something like this, (some) will skirt it with just the minimum requirement of an (essentially) empty file. An existing set of examples is provided by the vignettes of (at least) one developer which each consist (or consisted ?) of just a single line with a hyperlink to the corresponding package website. Passes the letter of the law (hey, look, a vignette) and all possible tests, but clearly violates the spirit of the law that documentation and package should be self-contained (and no, connectivity should not be assumed). Moral persuasion may be better. We should encourage best practices and highlight packages that follow them. Dirk [1] https://en.wikipedia.org/wiki/Goodhart%27s_law
http://dirk.eddelbuettel.com | @eddelbuettel | edd at debian.org
Hi Dirk, Point well taken, but the same goes for many other CRAN requirements. For example, I can create totally useless help files for all the functions that pass all checks. Just because some will try to skirt around a requirement doesn't mean it's a useless requirement. In fact, the point of such requirements is to promote good practices and I would like to believe that most package authors would make an honest effort to create a somewhat useful <package>-package.Rd file, even (as Joris pointed out) it is essentially just a pointer to the vignette(s) (which is also useful). Best, Wolfgang -----Original Message----- From: Dirk Eddelbuettel [mailto:edd at debian.org] Sent: Tuesday, 24 September, 2019 14:39 To: Joris.Meys at ugent.be Cc: Viechtbauer, Wolfgang (SP); r-package-devel at r-project.org Subject: Re: [R-pkg-devel] Require <package>-package.Rd? Wolfgang, Joris, This may not necessarily work -- see "Goodhart's Law" [1] Once you impose something like this, (some) will skirt it with just the minimum requirement of an (essentially) empty file. An existing set of examples is provided by the vignettes of (at least) one developer which each consist (or consisted ?) of just a single line with a hyperlink to the corresponding package website. Passes the letter of the law (hey, look, a vignette) and all possible tests, but clearly violates the spirit of the law that documentation and package should be self-contained (and no, connectivity should not be assumed). Moral persuasion may be better. We should encourage best practices and highlight packages that follow them. Dirk [1] https://en.wikipedia.org/wiki/Goodhart%27s_law
http://dirk.eddelbuettel.com | @eddelbuettel | edd at debian.org
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 at r-project.org] On Behalf Of Viechtbauer, Wolfgang (SP) Sent: 24 September 2019 13:16 To: r-package-devel at 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 ______________________________________________ R-package-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
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 at manchester.ac.uk] Sent: Tuesday, 24 September, 2019 15:02 To: Viechtbauer, Wolfgang (SP); r-package-devel at 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 at r-project.org] On Behalf Of Viechtbauer, Wolfgang (SP) Sent: 24 September 2019 13:16 To: r-package-devel at 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
I would be in favour. I actually used R for several years before figuring out that the vignette was usually where the useful introduction was. Until then I was like ?R help is way too technical?
On Tue, 24 Sep 2019 at 13:26, Joris Meys <Joris.Meys at ugent.be> wrote:
Dear Dr. Vichtbauer, I'm not a CRAN member, but I personally think this is a sensible requirement. I try to include those in every package myself, even if it's only to direct people to a vignette. That said, I do look for vignettes first when I encounter an unfamiliar package actually. That format gives more possibilities for giving a good introduction to the package imho. My humble 2 cents Cheers Joris On Tue, Sep 24, 2019 at 2:17 PM Viechtbauer, Wolfgang (SP) < wolfgang.viechtbauer at maastrichtuniversity.nl> wrote:
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
______________________________________________ R-package-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
-- Joris Meys Statistical consultant Department of Data Analysis and Mathematical Modelling Ghent University Coupure Links 653, B-9000 Gent (Belgium) < https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g
tel: +32 (0)9 264 61 79 ----------- Biowiskundedagen 2017-2018 http://www.biowiskundedagen.ugent.be/ ------------------------------- Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php [[alternative HTML version deleted]]
______________________________________________ R-package-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Sent from Gmail Mobile [[alternative HTML version deleted]]
help(package="utils") shows the index, not utils-package.Rd.
Indeed, I should have run it before emailing, I meant:
package ? utils
which does show "utils-package.Rd" and similarly for other packages.
'help(topic)' shows a file which contains alias for 'topic'. In the case of 'help(utils)', fille "utils-package.Rd" has an alias for "utils", so tht is shown.
For what it's worth, the index shown by 'help(package = "package")' is very useful for html formatted pages, where everything is linked and the links to the vignettes appear at the top. If html is not the default rendering, one can use
help(package = "Matrix", help_type = "html")
to get this.
Georgi Boshnakov
-----Original Message-----
From: Viechtbauer, Wolfgang (SP) [mailto:wolfgang.viechtbauer at maastrichtuniversity.nl]
Sent: 24 September 2019 14:34
To: Georgi Boshnakov; r-package-devel at r-project.org
Subject: RE: Require <package>-package.Rd?
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 at manchester.ac.uk]
Sent: Tuesday, 24 September, 2019 15:02
To: Viechtbauer, Wolfgang (SP); r-package-devel at 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 at r-project.org] On Behalf Of Viechtbauer, Wolfgang (SP)
Sent: 24 September 2019 13:16
To: r-package-devel at 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
6 days later
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
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