Re: [R-pkg-devel] relation between vignettes and help files
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
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] relation between vignettes and help files
Afaik the only way to link to a vignette from the help file is to instruct the reader to do something like vignette('intro','mypkg') On the R command-line. In general, the Rd files describe the public API of your pkg. Each exported function should have a help file that ideally can be read and understood in isolation. The vignettes can provide walk-throughs for tasks that require a sequence of functions to be called. This helps the user to get around the package by focusing on tasks. Although you will probably duplicate a little information, try to focus on subject matter in the vignette, while focusing on the technical aspects in the Rd files. Hope that helps, Mark On Wed, Jul 13, 2016, 21:29 Boylan, Ross wrote: > 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 > __ > R-package-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-package-devel > [[alternative HTML version deleted]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
[R-pkg-devel] relation between vignettes and help files
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 __ 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?
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