Re: [R-pkg-devel] Require -package.Rd?

2019-09-30 Thread 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.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.wick...@gmail.com] 
Sent: 30 September 2019 21:17
To: Georgi Boshnakov
Cc: Viechtbauer, Wolfgang (SP); r-package-devel@r-project.org
Subject: Re: [R-pkg-devel] Require -package.Rd?

On Tue, Sep 24, 2019 at 8:07 AM Georgi Boshnakov
 wrote:
>
> It is worth noting that
>
> help(package="")
>
> shows  file -package.Rd, while
>
> help()
>
> shows topic "package".
>
> Topic -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 .Rd, instead of -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?.  See, e.g.
https://usethis.r-lib.org/reference/use_package_doc.html

Hadley

-- 
http://hadley.nz
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] Require -package.Rd?

2019-09-30 Thread Hadley Wickham 
On Tue, Sep 24, 2019 at 8:07 AM Georgi Boshnakov
 wrote:
>
> It is worth noting that
>
> help(package="")
>
> shows  file -package.Rd, while
>
> help()
>
> shows topic "package".
>
> Topic -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 .Rd, instead of -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?.  See, e.g.
https://usethis.r-lib.org/reference/use_package_doc.html

Hadley

-- 
http://hadley.nz

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] Require -package.Rd?

2019-09-24 Thread Georgi Boshnakov 
> 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.viechtba...@maastrichtuniversity.nl] 
Sent: 24 September 2019 14:34
To: Georgi Boshnakov; r-package-devel@r-project.org
Subject: RE: Require -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.boshna...@manchester.ac.uk] 
Sent: Tuesday, 24 September, 2019 15:02
To: Viechtbauer, Wolfgang (SP); r-package-devel@r-project.org
Subject: RE: Require -package.Rd?

It is worth noting that 

help(package="")

shows  file -package.Rd, while 

help()

shows topic "package".

Topic -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 
.Rd, instead of -package.Rd as overall package description. 

Georgi Boshnakov

-Original Message-
From: R-package-devel [mailto:r-package-devel-boun...@r-project.org] On Behalf 
Of Viechtbauer, Wolfgang (SP)
Sent: 24 September 2019 13:16
To: r-package-devel@r-project.org
Subject: [R-pkg-devel] Require -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="")

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()

in the hopes that the package author(s) have created a -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.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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] Require -package.Rd?

2019-09-24 Thread David Hugh-Jones 
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  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.viechtba...@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="")
> >
> > 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()
> >
> > in the hopes that the package author(s) have created a
> > -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.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@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=gmail=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@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>
-- 
Sent from Gmail Mobile

[[alternative HTML version deleted]]

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] Require -package.Rd?

2019-09-24 Thread Georgi Boshnakov 
It is worth noting that 

help(package="")

shows  file -package.Rd, while 

help()

shows topic "package".

Topic -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 
.Rd, instead of -package.Rd as overall package description. 

Georgi Boshnakov



-Original Message-
From: R-package-devel [mailto:r-package-devel-boun...@r-project.org] On Behalf 
Of Viechtbauer, Wolfgang (SP)
Sent: 24 September 2019 13:16
To: r-package-devel@r-project.org
Subject: [R-pkg-devel] Require -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="")

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()

in the hopes that the package author(s) have created a -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.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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] Require -package.Rd?

2019-09-24 Thread Viechtbauer, Wolfgang (SP) 
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.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:e...@debian.org] 
Sent: Tuesday, 24 September, 2019 14:39
To: joris.m...@ugent.be
Cc: Viechtbauer, Wolfgang (SP); r-package-devel@r-project.org
Subject: Re: [R-pkg-devel] Require -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 | e...@debian.org

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] Require -package.Rd?

2019-09-24 Thread Dirk Eddelbuettel 


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 | e...@debian.org

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] Require -package.Rd?

2019-09-24 Thread Joris Meys 
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.viechtba...@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="")
>
> 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()
>
> in the hopes that the package author(s) have created a
> -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.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@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)


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

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

2019-09-24 Thread Viechtbauer, Wolfgang (SP) 
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="")

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()

in the hopes that the package author(s) have created a -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.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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel