Re: [R-pkg-devel] relation between vignettes and help files

[Duncan Murdoch]

On 13/07/2016 4:04 PM, Enrico Schumann wrote:

On Wed, 13 Jul 2016, "Boylan, Ross"  writes:


I have two questions, one substantive and one technical, about the
relation between vignettes and help files.  By "help files" I mean the
regular .Rd files.

Substantively, to what extent should material be duplicated between
the help files and the vignette?  For example, my vignette includes
some output summarizing the analysis.  The output has many different
kinds of information, and the details about what they mean are in the
help for the function generating the output.  Any advice on how much
of that information to put in the vignette?.  The vignette could, of
course, say to see the help for the function for details.

It seems natural to me to have the information in both places, except
that doing so invites inconsistencies as the code changes, if not
immediately.

The leads to the the technical question: is there a way to provide
links to the help from the vignette?  I'm using Sweave.  And,
similarly, is there a way to reference the vignettes from the help?
In particular, it seems natural to reference the vignette from the
package help.

Thanks.
Ross Boylan



I think this was discussed very recently on R-help:

https://stat.ethz.ch/pipermail/r-help/2016-June/439867.html


I seem to recall that links from PDF files into the help system don't 
work, because those *must* be relative links, and I think PDF files 
don't support relative links.  (It is possible to set up your system so 
you can use absolute links by always running the help system on the same 
port, but you can't count on your users to be doing that.)


So Ross is probably out of luck if he's using Sweave.

Duncan Murdoch

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

Re: [R-pkg-devel] relation between vignettes and help files

[Enrico Schumann]

On Wed, 13 Jul 2016, "Boylan, Ross"  writes:

> I have two questions, one substantive and one technical, about the
> relation between vignettes and help files.  By "help files" I mean the
> regular .Rd files.
>
> Substantively, to what extent should material be duplicated between
> the help files and the vignette?  For example, my vignette includes
> some output summarizing the analysis.  The output has many different
> kinds of information, and the details about what they mean are in the
> help for the function generating the output.  Any advice on how much
> of that information to put in the vignette?.  The vignette could, of
> course, say to see the help for the function for details.
>
> It seems natural to me to have the information in both places, except
> that doing so invites inconsistencies as the code changes, if not
> immediately.
>
> The leads to the the technical question: is there a way to provide
> links to the help from the vignette?  I'm using Sweave.  And,
> similarly, is there a way to reference the vignettes from the help?
> In particular, it seems natural to reference the vignette from the
> package help.
>
> Thanks.
> Ross Boylan


I think this was discussed very recently on R-help:

https://stat.ethz.ch/pipermail/r-help/2016-June/439867.html


-- 
Enrico Schumann
Lucerne, Switzerland
http://enricoschumann.net

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

Re: [R-pkg-devel] Is S3 class registration essential for CRAN?

[Henrik Bengtsson]

I second Dirk.  Also, from my experience:

A good rule of thumb is that you should fix all NOTEs (i.e. not have
them) when you submit to CRAN.  It's only when you have a really good
reason you could try to convince CRAN that they are there and that
they cannot be fixed easily.  I've got 20+ packages on CRAN and it's
been extremely rare that I ran into a NOTE that I couldn't fix.

Importantly, I'd assume that if your submission has issues (i.e.
ERRORs, WARNINGs or NOTEs), then CRAN needs to look at your package
manually and make a decision and most likely write you an email.  Even
if that would be a 2 min task (but I'd assume it's more) that's lots
of time spent on their end given they get so many submission every
day.  If your submission has all OKs, then it's much more likely that
your package is accepted and on CRAN very quickly (definitely < 24
hours; likely < 12 hours by my experience).  So, aim for all OKs to
save you and CRAN some time.


Registering S3 methods is as simple as specifying

S3method("mtd", "clss")

in the NAMESPACE file (for all your S3 methods).  If you use roxygen2,
this becomes nearly automatic.  It'll also improve the quality of your
package, e.g. make it play better with others.  I would certainly add
these.

Henrik


On Tue, Jul 12, 2016 at 10:13 AM, Dirk Eddelbuettel  wrote:
>
> On 12 July 2016 at 17:47, S Ellison wrote:
> | A short question: How necessary is explicit S3 class registration for CRAN 
> submission?
> | R-forge's check is giving me a note on this for a handful of methods in a 
> package, and I'm unclear whether it is something that _needs_  to be fixed 
> for CRAN submission by registering all S3 methods, needs to be fixed for 
> _some_, or doesn't need to be changed (the present version on cran is running 
> without apparent issues, but was submitted before the checks expanded to pick 
> this up).
>
> You are expected to test with the release and the development versions of R
> [1], and newer versions tend to only get stricter rather than more lenient.
>
> As for 'current version on CRAN does not have issues': well, yes, the absence
> of a time machine comes into play again. Tests that didn't exist at the time
> have a tendency to not get triggered.  Rest assurred that the _next_ upload
> will however so you are quite right to worry about this.
>
> So without knowing the pecularities of your (unnamed) package: I'd fix it.
>
> Dirk
>
>
> [1] Using win-builder can be a good trick to get access at the latter.
>
> --
> 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

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