Re: [Rd] Suggestion: help(package name)
On Tue, 7 Jun 2005, Duncan Murdoch wrote: [...] My proposal (modified following the suggestions I've heard so far) is as follows: - to check that a couple of help topic aliases exist (pkg.package and pkg) - to recommend that pkg.package contain general information about the package, and that pkg be an alias for it, if it isn't used for some other purpose. - to write promptPackage() to help create an initial version of pkg.package.Rd. It can get some information from the DESCRIPTION file; perhaps it could go looking for a vignette, or the INDEX, or - to modify the other help system tools to make use of this (e.g. the package:pkg heading on a page would become a link to the pkg.package alias, etc.) I've now committed some of this to R-devel, and I invite comments. I've abandoned the idea of the check, which seems too controversial. I've done the second and third items, but not the 4th. I wrote about a dozen of these files this afternoon as I was refining promptPackage. It is very quick to generate a basic man page using promptPackage with an option saying you want a final version. Manually editing this file, running it through checks, etc. took me around 10-20 minutes per package. I only did the base packages, and they probably have less in their overview than most contributors would want, so someone starting from nothing would probably take longer --- but many packages already have the text written somewhere, and they just need to add an alias to an Rd file, or perhaps reformat an INDEX file. Duncan Murdoch __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
On Tue, 7 Jun 2005, Duncan Murdoch wrote: [...] My proposal (modified following the suggestions I've heard so far) is as follows: - to check that a couple of help topic aliases exist (pkg.package and pkg) - to recommend that pkg.package contain general information about the package, and that pkg be an alias for it, if it isn't used for some other purpose. - to write promptPackage() to help create an initial version of pkg.package.Rd. It can get some information from the DESCRIPTION file; perhaps it could go looking for a vignette, or the INDEX, or - to modify the other help system tools to make use of this (e.g. the package:pkg heading on a page would become a link to the pkg.package alias, etc.) as a package author who already provides help pages for general package descriptions (`?multcomp' and `?coin' work and, if I remember correctly, Martin suggested to include the advertisement this way) I must admit that I never say `?foo' when I'm interested in a global overview about a new package `foo'. Instead, `library(help = foo)' gives what I want to see, namely the title and description of a package and all documented topics. One may argue that asking `library' for help is not the most obvious thing to do. But people able to recall that fitting an ANOVA model requires `aov' and comparing two models needs `anova' should be able to have `library' in mind for general package information. So, for me having infrastructure for _automatically_ generated overviews is very nice, but _forcing_ package authors to provide additional meta-information would be less welcome. Best, Torsten __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
On 6/8/05, Torsten Hothorn [EMAIL PROTECTED] wrote: On Tue, 7 Jun 2005, Duncan Murdoch wrote: [...] My proposal (modified following the suggestions I've heard so far) is as follows: - to check that a couple of help topic aliases exist (pkg.package and pkg) - to recommend that pkg.package contain general information about the package, and that pkg be an alias for it, if it isn't used for some other purpose. - to write promptPackage() to help create an initial version of pkg.package.Rd. It can get some information from the DESCRIPTION file; perhaps it could go looking for a vignette, or the INDEX, or - to modify the other help system tools to make use of this (e.g. the package:pkg heading on a page would become a link to the pkg.package alias, etc.) as a package author who already provides help pages for general package descriptions (`?multcomp' and `?coin' work and, if I remember correctly, Martin suggested to include the advertisement this way) I must admit that I never say `?foo' when I'm interested in a global overview about a new package `foo'. Instead, `library(help = foo)' gives what I want to see, namely the title and description of a package and all documented topics. One may argue that asking `library' for help is not the most obvious thing to do. But people able to recall that fitting an ANOVA model requires `aov' and comparing two models needs `anova' should be able to have `library' in mind for general package information. So, for me having infrastructure for _automatically_ generated overviews is very nice, but _forcing_ package authors to provide additional meta-information would be less welcome. I'm in the Robert/Brian school of thought -- this can be solved with better DESCRIPTIONS, or by explicitly writing such a file (which one can already do), or through better advertisement / incorporation of the vignette tools. Requiring anything additional is a PITA. Sure, it doesn't look like much time, but it is. much is in the eye of the beholder. Perhaps one thing to do is to map ?pkgname.package to library(help=pkgname) as was previously suggested, and let authors put information in the DESCRIPTION, perhaps with a lead towards the right help file to use to get more. best, -tony Commit early,commit often, and commit in a repository from which we can easily roll-back your mistakes (AJR, 4Jan05). A.J. Rossini [EMAIL PROTECTED] __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
A J Rossini writes: On 6/8/05, Torsten Hothorn [EMAIL PROTECTED] wrote: On Tue, 7 Jun 2005, Duncan Murdoch wrote: [...] My proposal (modified following the suggestions I've heard so far) is as follows: - to check that a couple of help topic aliases exist (pkg.package and pkg) - to recommend that pkg.package contain general information about the package, and that pkg be an alias for it, if it isn't used for some other purpose. - to write promptPackage() to help create an initial version of pkg.package.Rd. It can get some information from the DESCRIPTION file; perhaps it could go looking for a vignette, or the INDEX, or - to modify the other help system tools to make use of this (e.g. the package:pkg heading on a page would become a link to the pkg.package alias, etc.) as a package author who already provides help pages for general package descriptions (`?multcomp' and `?coin' work and, if I remember correctly, Martin suggested to include the advertisement this way) I must admit that I never say `?foo' when I'm interested in a global overview about a new package `foo'. Instead, `library(help = foo)' gives what I want to see, namely the title and description of a package and all documented topics. One may argue that asking `library' for help is not the most obvious thing to do. But people able to recall that fitting an ANOVA model requires `aov' and comparing two models needs `anova' should be able to have `library' in mind for general package information. So, for me having infrastructure for _automatically_ generated overviews is very nice, but _forcing_ package authors to provide additional meta-information would be less welcome. I'm in the Robert/Brian school of thought -- this can be solved with better DESCRIPTIONS, or by explicitly writing such a file (which one can already do), or through better advertisement / incorporation of the vignette tools. Yep. Requiring anything additional is a PITA. Sure, it doesn't look like much time, but it is. much is in the eye of the beholder. Perhaps one thing to do is to map ?pkgname.package to library(help=pkgname) as was previously suggested, and let authors put information in the DESCRIPTION, perhaps with a lead towards the right help file to use to get more. If we want to do something along these lines, then we could map package ? pkgname = help(package = pkgname) I don't think we can do something which possibly masks topics for objects of class package :-) -k __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
Henrik Bengtsson wrote:
It seems that it comes down to two things: 1) a standard Rd topic or
alias pkg.package, and 2) enforcing this standard with R CMD check.
Pro's and con's for (1):
Pros:
- Easy to find overview information on a package, that is, you know
*where* to find it.
- Allows a packages to link to another package.
- Shows up in the HTML index page.
- The pkg.package.html can be included on the CRAN package overview.
This can then also become the author's webpage (kiosk?) for the
package including installation instructions, license, future plans etc.
Searchable on the web (==you can get information before trying to
download/install, which sometimes fails; catch 22.)
Cons:
- Conflicts with other topic of the same name.
- Just another vignette (?)
Pro's and con's for (2):
Pros:
- Guarantees that a package can link to another package.
- Standard immediately adopted.
Cons:
- Requires more maintainance.
- Without automatic tools, redundancy is introduced (more maintainance).
My comments:
I think it is hard to argue that a standard similar to (1) is unwanted.
Also, I don't think anyone has objected on this. The objection has been
on (2). So my suggestion is that one writes up a standard on (1) and
*ask* developers to follow it.
If enforcement by R CMD check (2) was implemented too, then I think it
only requires a single \alias{pkg.package} in any of the Rd files,
because as far as I understand it at least one is required. This would
not require much work (almost cheap). This would guarantee a link at
least to something. A more advanced version is that the pkg.package.Rd
file is automatically created by R CMD build if missing (zero cost).
I really like this zero cost option. I think it addresses the main
problem with the proposal (all the work for package writers that it
creates), while keeping the main benefit (a standard place for package
help *within the help system*).
It might be tricky to implement (the build tools aren't all in R and
aren't consistent across platforms), but it seems like a reasonable
compromise to me.
Duncan Murdoch
To follow up on Gabor's suggestion to add more R CMD check granuality
than errors and warnings. Using classes and the new exception
handling, one could introduce a warning class called Suggestion
(CranSuggestion), which gives suggestions to the user, but not enforce
them (warning are not allowed on CRAN).
To extend this idea further, one could add non-enforced checks if a
package follows certain standardizations or not. I can image such
checks to be plugins to R CMD check or standalone. Other solutions may
also used. For instance, R CMD checkRCC could check a package against
the coding convention RCC (http://www.maths.lth.se/help/R/RCC/).
Supplementary or complementary standards can provide their own checks.
Such tools would be helpful for large projects to conform to the same
standards, but not enforcing them. Packages following certain standards
could then advertize this to help the user and other developers
utilizing their packages and so.
To summarize, I think it is good if you can communicate that you follow
a certain standard, and it is even better if more peoples are using the
same standard. I agree, that enforced standards are painful, if you
disagree with them (or find the unnecessary).
Cheers
Henrik
Robin Hankin wrote:
The reason I like .Rd files is that I can run the examples easily and,
as Martin points out,
one does not need to learn a new syntax.
How about adding the following to R-exts:
We encourage the package developer to include a file named
foo.package.Rd in the man
directory, to provide a terse overview of the foo package. This Rd file
is intended to be
the first port of call for a new user of the package, and should provide
(or point to)
working examples of the package's functionality. It may also provide
details or rationale
for the package's structure, if non-standard; and perhaps document other
features of
the package that might escape a new user's notice.
See package foo for an example
and package.skeleton() could be modified to write a skeleton version of
foo.package.Rd
and put it in the man directory.
best wishes everyone
rksh
Duncan writes:
My proposal (modified following the suggestions I've heard so far) is
as follows:
- to check that a couple of help topic aliases exist (pkg.package
and pkg)
- to recommend that pkg.package contain general information about
the package, and that pkg be an alias for it, if it isn't used for
some other purpose.
- to write promptPackage() to help create an initial version of
pkg.package.Rd. It can get some information from the DESCRIPTION
file; perhaps it could go looking for a vignette, or the INDEX, or
- to modify the other help system tools to make use of this (e.g. the
package:pkg heading on a page would become a link to the
pkg.package alias, etc.)
Martin:
And as much as I do like (and
Re: [Rd] Suggestion: help(package name)
Torsten Hothorn wrote: On Tue, 7 Jun 2005, Duncan Murdoch wrote: [...] My proposal (modified following the suggestions I've heard so far) is as follows: - to check that a couple of help topic aliases exist (pkg.package and pkg) - to recommend that pkg.package contain general information about the package, and that pkg be an alias for it, if it isn't used for some other purpose. - to write promptPackage() to help create an initial version of pkg.package.Rd. It can get some information from the DESCRIPTION file; perhaps it could go looking for a vignette, or the INDEX, or - to modify the other help system tools to make use of this (e.g. the package:pkg heading on a page would become a link to the pkg.package alias, etc.) as a package author who already provides help pages for general package descriptions (`?multcomp' and `?coin' work and, if I remember correctly, Martin suggested to include the advertisement this way) I must admit that I never say `?foo' when I'm interested in a global overview about a new package `foo'. I do occasionally, but usually it's a waste of time. This proposal is intended to address that. Instead, `library(help = foo)' gives what I want to see, namely the title and description of a package and all documented topics. One may argue that asking `library' for help is not the most obvious thing to do. But people able to recall that fitting an ANOVA model requires `aov' and comparing two models needs `anova' should be able to have `library' in mind for general package information. As I pointed out, this is okay for people who know R already, but not so good for beginners. The answer to the question how do I get help on foo? is too complex. So, for me having infrastructure for _automatically_ generated overviews is very nice, but _forcing_ package authors to provide additional meta-information would be less welcome. What do you think of Henrik's suggestion to generate a help topic giving information equivalent to library(help=pkg)? I think this would happen at install time (not build time as he said; no need to put this in the source tarballs). If the pkg.package alias wasn't defined, the installer would automatically create one. If we had this in place, I'd strengthen the advice in R-Exts not to bother with a manually created INDEX file: that information should go into a manually created pkg.package topic instead. Duncan Murdoch __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
On Wed, 8 Jun 2005, Duncan Murdoch wrote: Torsten Hothorn wrote: On Tue, 7 Jun 2005, Duncan Murdoch wrote: [...] My proposal (modified following the suggestions I've heard so far) is as follows: - to check that a couple of help topic aliases exist (pkg.package and pkg) - to recommend that pkg.package contain general information about the package, and that pkg be an alias for it, if it isn't used for some other purpose. - to write promptPackage() to help create an initial version of pkg.package.Rd. It can get some information from the DESCRIPTION file; perhaps it could go looking for a vignette, or the INDEX, or - to modify the other help system tools to make use of this (e.g. the package:pkg heading on a page would become a link to the pkg.package alias, etc.) as a package author who already provides help pages for general package descriptions (`?multcomp' and `?coin' work and, if I remember correctly, Martin suggested to include the advertisement this way) I must admit that I never say `?foo' when I'm interested in a global overview about a new package `foo'. I do occasionally, but usually it's a waste of time. This proposal is intended to address that. Instead, `library(help = foo)' gives what I want to see, namely the title and description of a package and all documented topics. One may argue that asking `library' for help is not the most obvious thing to do. But people able to recall that fitting an ANOVA model requires `aov' and comparing two models needs `anova' should be able to have `library' in mind for general package information. As I pointed out, this is okay for people who know R already, but not so good for beginners. The answer to the question how do I get help on foo? is too complex. So, for me having infrastructure for _automatically_ generated overviews is very nice, but _forcing_ package authors to provide additional meta-information would be less welcome. What do you think of Henrik's suggestion to generate a help topic giving information equivalent to library(help=pkg)? I think this would happen at install time (not build time as he said; no need to put this in the source tarballs). If the pkg.package alias wasn't defined, the installer would automatically create one. If we had this in place, I'd strengthen the advice in R-Exts not to bother with a manually created INDEX file: that information should go into a manually created pkg.package topic instead. yes, this sounds reasonable - as long as ?pkg.package is a link to library(help = pkg) (or help(package = pkg as I learned only recently) when no pkg.package.Rd file exists in pkg, this would be fine, of course. Best, Torsten Duncan Murdoch __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
Henrik Bengtsson writes: Hi, I would like to suggest a standard where all packages provide an Rd page with the same name (or aliased) as the name of package so that help(package name) or ?package name is always here. This especially of interest to large packages with a large package index. This page could explain the package in general and gives some hints on how to start - not like extensive vignettes, but just to get started, e.g. list the most important functions. This page could typically contain information that is in the DESCRIPTION file (which contains valuable information hardly every accessed by a general user), such as who is the maintainer, how to report bugs and so on. How would this be different from the results of help(package = package name) ? -k If you think the above is a good idea, then, would it even be useful to enforce the existance of such a Rd page in R CMD check? Henrik Bengtsson __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
Henrik Bengtsson writes: I would like to suggest a standard where all packages provide an Rd page with the same name (or aliased) as the name of package so that help(package name) or ?package name is always here. This especially of interest to large packages with a large package index. This page could explain the package in general and gives some hints on how to start - not like extensive vignettes, but just to get started, e.g. list the most important functions. But isn't that just what vignettes are there for? And I think nobody has said that vignettes should be extensive, and if they end up being so, that is a problem of the package author, and probably would end up being the same with yet another form of documentation. Best regards Wolfgang - Wolfgang Huber European Bioinformatics Institute European Molecular Biology Laboratory Cambridge CB10 1SD England Phone: +44 1223 494642 Fax: +44 1223 494486 Http: www.ebi.ac.uk/huber __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
Kurt Hornik wrote: Henrik Bengtsson writes: Hi, I would like to suggest a standard where all packages provide an Rd page with the same name (or aliased) as the name of package so that help(package name) or ?package name is always here. This especially of interest to large packages with a large package index. This page could explain the package in general and gives some hints on how to start - not like extensive vignettes, but just to get started, e.g. list the most important functions. This page could typically contain information that is in the DESCRIPTION file (which contains valuable information hardly every accessed by a general user), such as who is the maintainer, how to report bugs and so on. How would this be different from the results of help(package = package name) ? Thanks for that. I was not aware of this one; I like how DESCRIPTION is included and how the index is divided in functions and dataset, e.g. help(package=MASS). May I also suggest that the CITATION file is included here, e.g. help(package=foreign). My suggestion differ in the sense that 1) additional information may be included such as which functions are main functions and which are of less interest, and 2) that it would show up in the HTML index page too. An automated solution such as help(package=name) is of course easier to maintain. Part of Rd files can be generated this way too, but I did not want to get too complicated in my suggestions. /Henrik -k If you think the above is a good idea, then, would it even be useful to enforce the existance of such a Rd page in R CMD check? Henrik Bengtsson __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
Wolfgang Huber wrote: Henrik Bengtsson writes: I would like to suggest a standard where all packages provide an Rd page with the same name (or aliased) as the name of package so that help(package name) or ?package name is always here. This especially of interest to large packages with a large package index. This page could explain the package in general and gives some hints on how to start - not like extensive vignettes, but just to get started, e.g. list the most important functions. But isn't that just what vignettes are there for? And I think nobody has said that vignettes should be extensive, and if they end up being so, that is a problem of the package author, and probably would end up being the same with yet another form of documentation. Yes, and you could call what I am suggestion a special type of vignette. But, I was more thinking of a very very short description page which is extremely easy to access and easy to write (I shouldn't have said not like extensive vignettes then, but rather like extremely short vignettes). Writing vignettes are easy, but apparently still not easy enough because not all packages have a vignette. Also, it is hard to compete with the command ?pkgname when it comes to access and response time, especially if the vignette is a PDF file but even if it is a HTML page. Also, an Rd file will be included in both the HTML help and the LaTeX manual. If there would be a standardized main document page, which I think ?pkgname is, but which could also apply vignette(pkgname), a new user would immediately know where to get the necessary information if running into problems or just want to try out a new package, e.g. install.packages(R.oo), then library(R.oo) and ?R.oo (much on the shown page is automatically generated from DESCRIPTION files etc, but I did not want to suggest that because that requires much more). Cheers Henrik Best regards Wolfgang - Wolfgang Huber European Bioinformatics Institute European Molecular Biology Laboratory Cambridge CB10 1SD England Phone: +44 1223 494642 Fax: +44 1223 494486 Http: www.ebi.ac.uk/huber - __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
My 0.02: I use Misc.Rd for the purpose that Duncan suggests. I put things like details and rationale for package organization, pointers to the most important function(s) in the package, and perhaps function descriptors for ubiquitous functions that don't warrant their own helppage, but need documentation [in the case of gsl, this would be strictify() and process.args(), which every user needs to know]. It would be *great* to be required to put in package.gsl.R (or should that be gsl.package.Rd?) for this purpose. Then maybe R CMD check could check for its presence and throw a wobbly if it isn't there. Some packages have so much material that it's difficult to know where the meat of the functionality lies, and Duncan's suggestion would help greatly in these circumstances. best wishes rksh On Jun 7, 2005, at 01:11 pm, Duncan Murdoch wrote: Kurt Hornik wrote: Henrik Bengtsson writes: Hi, I would like to suggest a standard where all packages provide an Rd page with the same name (or aliased) as the name of package so that help(package name) or ?package name is always here. This especially of interest to large packages with a large package index. This page could explain the package in general and gives some hints on how to start - not like extensive vignettes, but just to get started, e.g. list the most important functions. This page could typically contain information that is in the DESCRIPTION file (which contains valuable information hardly every accessed by a general user), such as who is the maintainer, how to report bugs and so on. I think this is a good idea. One minor problem is that for some packages that topic name is already in use for a function (e.g. boot). For that reason, I'd suggest that there *also* be an alias called package.package name, and the package name topic should link to it. How would this be different from the results of help(package = package name) ? 1. It would work with ?, like other help topics. 2. It would give an overview. It's possible to do that in DESCRIPTION or INDEX, but you don't get the same style as for other help files (e.g. no links to other topics, at least in Windows). We should work out what the topic headings should be and extend package.skeleton() and prompt() to write a bare-bones file that suggests the questions that need to be answered in the file. The headings I'd suggest are: \name \title \alias \description (longer than the typical entry in the DESCRIPTION file) \details (Should give a short guide to the main functions, should point out the existence of external documentation like vignettes, etc.) \author (could also describe maintainer, if different) \references \seealso (Should give references to related packages) \examples \keywords There is some duplication of material from DESCRIPTION, but usually this should be longer and more reader-friendly than that file. I'd be happy to write the description of this in R Extensions, and write the changes to prompt(), if we have agreement that this file should be mandatory in 2.2.x or 2.3.x, and you'll write the checks for it. (I think the check should just be for existence of aliases package name and package.package name, and could perhaps just give a warning in 2.2.x.) Duncan Murdoch __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel -- Robin Hankin Uncertainty Analyst National Oceanography Centre, Southampton European Way, Southampton SO14 3ZH, UK tel 023-8059-7743 __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
On Tue, 7 Jun 2005, Henrik Bengtsson wrote: Kurt Hornik wrote: How would this be different from the results of help(package = package name) ? Thanks for that. I was not aware of this one; I like how DESCRIPTION is included and how the index is divided in functions and dataset, e.g. help(package=MASS). May I also suggest that the CITATION file is included here, e.g. help(package=foreign). My suggestion differ in the sense that 1) additional information may be included such as which functions are main functions and which are of less interest, and 2) that it would show up in the HTML index page too. For point (1) you can write your own INDEX file, in which case it can have more information than the auto-generated one. A simple example is the survey package. My description of the INDEX file in courses has been that it contains a line for every sufficiently interesting function. Writing R Extensions says that normally this file is missing but I think this is descriptive rather than prescriptive. 2) seems sensible. The INDEX file is included in the CRAN page and I find it useful there. -thomas __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
Robin Hankin wrote: My 0.02: I use Misc.Rd for the purpose that Duncan suggests. I put things like details and rationale for package organization, pointers to the most important function(s) in the package, and perhaps function descriptors for ubiquitous functions that don't warrant their own helppage, but need documentation [in the case of gsl, this would be strictify() and process.args(), which every user needs to know]. It would be *great* to be required to put in package.gsl.R (or should that be gsl.package.Rd?) for this purpose. Then maybe R CMD check could check for its presence and throw a wobbly if it isn't there. Hi, Well, I pretty strenuously object. That is just what vignettes are for and the last thing I need is more wobbly's from R CMD check. Function documentation should document functions. If you want to document something more substantial then please use the tools already provided to do that - and if you don't want to, and you want to make use of the tools for function documentation in some other way please don't try to impose your version of what should happen on others. Best wishes Robert Some packages have so much material that it's difficult to know where the meat of the functionality lies, and Duncan's suggestion would help greatly in these circumstances. best wishes rksh On Jun 7, 2005, at 01:11 pm, Duncan Murdoch wrote: Kurt Hornik wrote: Henrik Bengtsson writes: Hi, I would like to suggest a standard where all packages provide an Rd page with the same name (or aliased) as the name of package so that help(package name) or ?package name is always here. This especially of interest to large packages with a large package index. This page could explain the package in general and gives some hints on how to start - not like extensive vignettes, but just to get started, e.g. list the most important functions. This page could typically contain information that is in the DESCRIPTION file (which contains valuable information hardly every accessed by a general user), such as who is the maintainer, how to report bugs and so on. I think this is a good idea. One minor problem is that for some packages that topic name is already in use for a function (e.g. boot). For that reason, I'd suggest that there *also* be an alias called package.package name, and the package name topic should link to it. How would this be different from the results of help(package = package name) ? 1. It would work with ?, like other help topics. 2. It would give an overview. It's possible to do that in DESCRIPTION or INDEX, but you don't get the same style as for other help files (e.g. no links to other topics, at least in Windows). We should work out what the topic headings should be and extend package.skeleton() and prompt() to write a bare-bones file that suggests the questions that need to be answered in the file. The headings I'd suggest are: \name \title \alias \description (longer than the typical entry in the DESCRIPTION file) \details (Should give a short guide to the main functions, should point out the existence of external documentation like vignettes, etc.) \author (could also describe maintainer, if different) \references \seealso (Should give references to related packages) \examples \keywords There is some duplication of material from DESCRIPTION, but usually this should be longer and more reader-friendly than that file. I'd be happy to write the description of this in R Extensions, and write the changes to prompt(), if we have agreement that this file should be mandatory in 2.2.x or 2.3.x, and you'll write the checks for it. (I think the check should just be for existence of aliases package name and package.package name, and could perhaps just give a warning in 2.2.x.) Duncan Murdoch __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel -- Robin Hankin Uncertainty Analyst National Oceanography Centre, Southampton European Way, Southampton SO14 3ZH, UK tel 023-8059-7743 __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
On 6/7/2005 11:12 AM, Robert Gentleman wrote: Robin Hankin wrote: My 0.02: I use Misc.Rd for the purpose that Duncan suggests. I put things like details and rationale for package organization, pointers to the most important function(s) in the package, and perhaps function descriptors for ubiquitous functions that don't warrant their own helppage, but need documentation [in the case of gsl, this would be strictify() and process.args(), which every user needs to know]. It would be *great* to be required to put in package.gsl.R (or should that be gsl.package.Rd?) for this purpose. Then maybe R CMD check could check for its presence and throw a wobbly if it isn't there. Hi, Well, I pretty strenuously object. That is just what vignettes are for and the last thing I need is more wobbly's from R CMD check. Function documentation should document functions. If you want to document something more substantial then please use the tools already provided to do that - and if you don't want to, and you want to make use of the tools for function documentation in some other way please don't try to impose your version of what should happen on others. The current .Rd files don't just document functions, they also document data objects and classes. But the main point here is that it's not good to have multiple disconnected sets of documentation for a package. Users should be able to say the equivalent of give me help on foo, and get help on foo, whether it's a function, a data object, a package, a method, a class, or whatever. It's a bad design to force them to ask for the same sort of thing in different ways depending on the type of thing they're asking for. If we had a way to link vignettes into the help system, then I'd think it would be perfectly acceptable for ?package to pop up a vignette for the package. However, right now we have too many different types of ways to display help, and not all of them are capable of displaying vignettes. Duncan Murdoch Best wishes Robert Some packages have so much material that it's difficult to know where the meat of the functionality lies, and Duncan's suggestion would help greatly in these circumstances. best wishes rksh On Jun 7, 2005, at 01:11 pm, Duncan Murdoch wrote: Kurt Hornik wrote: Henrik Bengtsson writes: Hi, I would like to suggest a standard where all packages provide an Rd page with the same name (or aliased) as the name of package so that help(package name) or ?package name is always here. This especially of interest to large packages with a large package index. This page could explain the package in general and gives some hints on how to start - not like extensive vignettes, but just to get started, e.g. list the most important functions. This page could typically contain information that is in the DESCRIPTION file (which contains valuable information hardly every accessed by a general user), such as who is the maintainer, how to report bugs and so on. I think this is a good idea. One minor problem is that for some packages that topic name is already in use for a function (e.g. boot). For that reason, I'd suggest that there *also* be an alias called package.package name, and the package name topic should link to it. How would this be different from the results of help(package = package name) ? 1. It would work with ?, like other help topics. 2. It would give an overview. It's possible to do that in DESCRIPTION or INDEX, but you don't get the same style as for other help files (e.g. no links to other topics, at least in Windows). We should work out what the topic headings should be and extend package.skeleton() and prompt() to write a bare-bones file that suggests the questions that need to be answered in the file. The headings I'd suggest are: \name \title \alias \description (longer than the typical entry in the DESCRIPTION file) \details (Should give a short guide to the main functions, should point out the existence of external documentation like vignettes, etc.) \author (could also describe maintainer, if different) \references \seealso (Should give references to related packages) \examples \keywords There is some duplication of material from DESCRIPTION, but usually this should be longer and more reader-friendly than that file. I'd be happy to write the description of this in R Extensions, and write the changes to prompt(), if we have agreement that this file should be mandatory in 2.2.x or 2.3.x, and you'll write the checks for it. (I think the check should just be for existence of aliases package name and package.package name, and could perhaps just give a warning in 2.2.x.) Duncan Murdoch __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel -- Robin Hankin Uncertainty Analyst National Oceanography Centre, Southampton European Way, Southampton SO14 3ZH,
Re: [Rd] Suggestion: help(package name)
On 6/7/05, Robert Gentleman [EMAIL PROTECTED] wrote: Robin Hankin wrote: My 0.02: I use Misc.Rd for the purpose that Duncan suggests. I put things like details and rationale for package organization, pointers to the most important function(s) in the package, and perhaps function descriptors for ubiquitous functions that don't warrant their own helppage, but need documentation [in the case of gsl, this would be strictify() and process.args(), which every user needs to know]. It would be *great* to be required to put in package.gsl.R (or should that be gsl.package.Rd?) for this purpose. Then maybe R CMD check could check for its presence and throw a wobbly if it isn't there. Hi, Well, I pretty strenuously object. That is just what vignettes are for and the last thing I need is more wobbly's from R CMD check. Function documentation should document functions. If you want to '?' or 'help' documents topics, as I under it, not necessarily functions. For example, ?iris ?Startup Further, '?' has a type?topic syntax, as well. Also, what is a wobbly? document something more substantial then please use the tools already provided to do that - and if you don't want to, and you want to make use of the tools for function documentation in some other way please don't try to impose your version of what should happen on others. Best wishes Robert Some packages have so much material that it's difficult to know where the meat of the functionality lies, and Duncan's suggestion would help greatly in these circumstances. best wishes rksh On Jun 7, 2005, at 01:11 pm, Duncan Murdoch wrote: Kurt Hornik wrote: Henrik Bengtsson writes: Hi, I would like to suggest a standard where all packages provide an Rd page with the same name (or aliased) as the name of package so that help(package name) or ?package name is always here. This especially of interest to large packages with a large package index. This page could explain the package in general and gives some hints on how to start - not like extensive vignettes, but just to get started, e.g. list the most important functions. This page could typically contain information that is in the DESCRIPTION file (which contains valuable information hardly every accessed by a general user), such as who is the maintainer, how to report bugs and so on. I think this is a good idea. One minor problem is that for some packages that topic name is already in use for a function (e.g. boot). For that reason, I'd suggest that there *also* be an alias called package.package name, and the package name topic should link to it. How would this be different from the results of help(package = package name) ? 1. It would work with ?, like other help topics. 2. It would give an overview. It's possible to do that in DESCRIPTION or INDEX, but you don't get the same style as for other help files (e.g. no links to other topics, at least in Windows). We should work out what the topic headings should be and extend package.skeleton() and prompt() to write a bare-bones file that suggests the questions that need to be answered in the file. The headings I'd suggest are: \name \title \alias \description (longer than the typical entry in the DESCRIPTION file) \details (Should give a short guide to the main functions, should point out the existence of external documentation like vignettes, etc.) \author (could also describe maintainer, if different) \references \seealso (Should give references to related packages) \examples \keywords There is some duplication of material from DESCRIPTION, but usually this should be longer and more reader-friendly than that file. I'd be happy to write the description of this in R Extensions, and write the changes to prompt(), if we have agreement that this file should be mandatory in 2.2.x or 2.3.x, and you'll write the checks for it. (I think the check should just be for existence of aliases package name and package.package name, and could perhaps just give a warning in 2.2.x.) Duncan Murdoch __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel -- Robin Hankin Uncertainty Analyst National Oceanography Centre, Southampton European Way, Southampton SO14 3ZH, UK tel 023-8059-7743 __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help(package name)
On 6/7/2005 11:59 AM, Robert Gentleman wrote: Duncan Murdoch wrote: On 6/7/2005 11:12 AM, Robert Gentleman wrote: Robin Hankin wrote: My 0.02: I use Misc.Rd for the purpose that Duncan suggests. I put things like details and rationale for package organization, pointers to the most important function(s) in the package, and perhaps function descriptors for ubiquitous functions that don't warrant their own helppage, but need documentation [in the case of gsl, this would be strictify() and process.args(), which every user needs to know]. It would be *great* to be required to put in package.gsl.R (or should that be gsl.package.Rd?) for this purpose. Then maybe R CMD check could check for its presence and throw a wobbly if it isn't there. Hi, Well, I pretty strenuously object. That is just what vignettes are for and the last thing I need is more wobbly's from R CMD check. Function documentation should document functions. If you want to document something more substantial then please use the tools already provided to do that - and if you don't want to, and you want to make use of the tools for function documentation in some other way please don't try to impose your version of what should happen on others. The current .Rd files don't just document functions, they also document data objects and classes. But the main point here is that it's not good to have multiple disconnected sets of documentation for a package. Users should be able to say the equivalent of give me help on foo, and get help on foo, whether it's a function, a data object, a package, a method, a class, or whatever. It's a bad design to force them to ask for the same sort of thing in different ways depending on the type of thing they're asking for. Hi Duncan and others, I think they are linked. There are tools available both in R and in Bioconductor and some pop things up and some don't. It doesn't take much work to add vignettes to the windows menu bar - as we have done in BioC for some time now - it would be nice if this was part of R, but no one seems to have been interested in achieving that. Fixing the help system to deal with more diverse kinds of help would be nice as well - but taking one part of it and saying, now everyone must do it this way is not that helpful. I respectfully disagree about the main point. My main point is, I don't want more things imposed on me; dealing with R CMD check is enough of a burden in its current version, without someone deciding that it would be nice to have a whole bunch more requirements. Folks should feel entirely free to do what they want - but a little less free to tell me what I should be doing. And I disagree pretty strenuously about that. One of the strengths of R is that it does impose standards on contributed packages, and these make them easier to use, less likely to conflict with each other, and so on. We shouldn't impose things lightly, but if they do make packages better, we should feel no reason not to tell you what you should be doing. Currently R has 3 types of help: the .Rd files in the man directory (which are converted into plain text, HTML, compiled HTML, LaTex, DVI, PDF, etc), the vignettes, and unstructured files in inst/doc. We currently require .Rd files for every function and data object. Adding a requirement to also document the package that way is not all that much of a burden, and will automatically give all those output formats I listed above. It will help to solve the often-complained about problem of packages that contain no overview at all. (Requiring a vignette and giving a way to display it would also do that, but I think requiring a .Rd file is less of a burden, and for anyone who has gone to the trouble of creating a vignette, gives a natural place for a link to it. Vignettes aren't used as much as they should be, because they are hidden away where users don't see them.) Duncan Murdoch Best wishes, Robert If we had a way to link vignettes into the help system, then I'd think it would be perfectly acceptable for ?package to pop up a vignette for the package. However, right now we have too many different types of ways to display help, and not all of them are capable of displaying vignettes. Duncan Murdoch Best wishes Robert Some packages have so much material that it's difficult to know where the meat of the functionality lies, and Duncan's suggestion would help greatly in these circumstances. best wishes rksh On Jun 7, 2005, at 01:11 pm, Duncan Murdoch wrote: Kurt Hornik wrote: Henrik Bengtsson writes: Hi, I would like to suggest a standard where all packages provide an Rd page with the same name (or aliased) as the name of package so that help(package name) or ?package name is always here. This especially of interest to large packages with a large package index. This page could explain the package in general and gives some
Re: [Rd] Suggestion: help(package name)
Duncan == Duncan Murdoch [EMAIL PROTECTED] on Tue, 07 Jun 2005 12:12:57 -0400 writes: . The current .Rd files don't just document functions, they also document data objects and classes. But the main point here is that it's not good to have multiple disconnected sets of documentation for a package. Users should be able to say the equivalent of give me help on foo, and get help on foo, whether it's a function, a data object, a package, a method, a class, or whatever. It's a bad design to force them to ask for the same sort of thing in different ways depending on the type of thing they're asking for. ... On 6/7/2005 11:59 AM, Robert Gentleman wrote: Hi Duncan and others, I think they are linked. There are tools available both in R and in Bioconductor and some pop things up and some don't. It doesn't take much work to add vignettes to the windows menu bar - as we have done in BioC for some time now - it would be nice if this was part of R, but no one seems to have been interested in achieving that. Fixing the help system to deal with more diverse kinds of help would be nice as well - but taking one part of it and saying, now everyone must do it this way is not that helpful. I respectfully disagree about the main point. My main point is, I don't want more things imposed on me; dealing with R CMD check is enough of a burden in its current version, without someone deciding that it would be nice to have a whole bunch more requirements. Folks should feel entirely free to do what they want - but a little less free to tell me what I should be doing. Duncan And I disagree pretty strenuously about that. One Duncan of the strengths of R is that it does impose Duncan standards on contributed packages, and these make Duncan them easier to use, less likely to conflict with Duncan each other, and so on. Duncan We shouldn't impose things lightly, but if they do Duncan make packages better, we should feel no reason not Duncan to tell you what you should be doing. As Kurt mentioned early in this thread, we currently have the auto-generated information from either help(package = pkgname)# or (equivalently!) library(help = pkgname) which shows DESCRIPTION + (user-written/auto-generated) INDEX + mentions vignettes and other contents in inst/doc/ Now if Duncan would write some R code that produces a man/pkgname.Rd file from the above information -- and as he mentioned also added some of that functionality to package.skeleton(), I think everyone could become happy, i.e., we could improve the system in the future with only a very light burden on the maintainers of currently existing packages: You'd have to run the new R function only once for every package you maintain. Also, the use of a user-written INDEX file could eventually completely be abandoned in favor of maintaining man/pkgname.Rd, which is much nicer; I'd welcome such a direction quite a bit. And as much as I do like (and read) the vignettes that are available, I also do agree that writing one other *.Rd file is easier for many new package authors than to write a vignette -- the package author already had to learn *.Rd syntax anyway -- and it's nice to be able to produce something where hyperlinks to the other existing reference material (ie. help pages) just works out of the box. OTOH, we should still keep in mind that it's worth to try to get bi-directional linking between (PDF) vignettes and help files (assuming all relevant files are installed by R CMD INSTALL of course). Martin Duncan Currently R has 3 types of help: the .Rd files in Duncan the man directory (which are converted into plain Duncan text, HTML, compiled HTML, LaTex, DVI, PDF, etc), Duncan the vignettes, and unstructured files in inst/doc. Duncan We currently require .Rd files for every function Duncan and data object. Adding a requirement to also Duncan document the package that way is not all that much Duncan of a burden, and will automatically give all those Duncan output formats I listed above. It will help to Duncan solve the often-complained about problem of packages Duncan that contain no overview at all. (Requiring a Duncan vignette and giving a way to display it would also Duncan do that, but I think requiring a .Rd file is less of Duncan a burden, and for anyone who has gone to the trouble Duncan of creating a vignette, gives a natural place for a Duncan link to it. Vignettes aren't used as much as they Duncan should be, because they are hidden away where users Duncan don't see them.) Duncan Duncan Murdoch Best wishes, Robert If we had a way to link vignettes into the help system, then I'd think it would be
Re: [Rd] Suggestion: help(package name)
Duncan Murdoch wrote: On 6/7/2005 11:59 AM, Robert Gentleman wrote: Duncan Murdoch wrote: On 6/7/2005 11:12 AM, Robert Gentleman wrote: Robin Hankin wrote: My 0.02: I use Misc.Rd for the purpose that Duncan suggests. I put things like details and rationale for package organization, pointers to the most important function(s) in the package, and perhaps function descriptors for ubiquitous functions that don't warrant their own helppage, but need documentation [in the case of gsl, this would be strictify() and process.args(), which every user needs to know]. It would be *great* to be required to put in package.gsl.R (or should that be gsl.package.Rd?) for this purpose. Then maybe R CMD check could check for its presence and throw a wobbly if it isn't there. Hi, Well, I pretty strenuously object. That is just what vignettes are for and the last thing I need is more wobbly's from R CMD check. Function documentation should document functions. If you want to document something more substantial then please use the tools already provided to do that - and if you don't want to, and you want to make use of the tools for function documentation in some other way please don't try to impose your version of what should happen on others. The current .Rd files don't just document functions, they also document data objects and classes. But the main point here is that it's not good to have multiple disconnected sets of documentation for a package. Users should be able to say the equivalent of give me help on foo, and get help on foo, whether it's a function, a data object, a package, a method, a class, or whatever. It's a bad design to force them to ask for the same sort of thing in different ways depending on the type of thing they're asking for. Hi Duncan and others, I think they are linked. There are tools available both in R and in Bioconductor and some pop things up and some don't. It doesn't take much work to add vignettes to the windows menu bar - as we have done in BioC for some time now - it would be nice if this was part of R, but no one seems to have been interested in achieving that. Fixing the help system to deal with more diverse kinds of help would be nice as well - but taking one part of it and saying, now everyone must do it this way is not that helpful. I respectfully disagree about the main point. My main point is, I don't want more things imposed on me; dealing with R CMD check is enough of a burden in its current version, without someone deciding that it would be nice to have a whole bunch more requirements. Folks should feel entirely free to do what they want - but a little less free to tell me what I should be doing. And I disagree pretty strenuously about that. One of the strengths of R is that it does impose standards on contributed packages, and these make them easier to use, less likely to conflict with each other, and so on. We shouldn't impose things lightly, but if they do make packages better, we should feel no reason not to tell you what you should be doing. Let's see, some of us (three years ago) developed a tool to solve this problem. We made it available to others to use as they saw fit. I feel no less strong than you do, but I certainly did not impose what I thought on you and I ask for the same respect. We have already solved this problem in our own way. You now seem to think that it is zero cost to impose on us a second (and in my view inferior solution). I am asking that you not do that. Please, feel free to develop what you want and to encourage others to use it, but don't try to make people do things just because you want them that way. We have lots of packages in BioC the costs of reengineering so we can meet your newly imposed standards are not zero. I think we have an expectation that such capricious behaviour will not be entered in to, and if we don't then perhaps it is time to branch the project. Best wishes, Robert Currently R has 3 types of help: the .Rd files in the man directory (which are converted into plain text, HTML, compiled HTML, LaTex, DVI, PDF, etc), the vignettes, and unstructured files in inst/doc. We currently require .Rd files for every function and data object. Adding a requirement to also document the package that way is not all that much of a burden, and will automatically give all those output formats I listed above. It will help to solve the often-complained about problem of packages that contain no overview at all. (Requiring a vignette and giving a way to display it would also do that, but I think requiring a .Rd file is less of a burden, and for anyone who has gone to the trouble of creating a vignette, gives a natural place for a link to it. Vignettes aren't used as much as they should be, because they are hidden away where users don't see them.) Duncan Murdoch Best wishes, Robert If we had a way to link
Re: [Rd] Suggestion: help(package name)
Currently methods?e will look for the alias e-methods so perhaps package?e could look for alias e-package. On 6/7/05, Achim Zeileis [EMAIL PROTECTED] wrote: On Tue, 7 Jun 2005 18:43:37 +0200 Martin Maechler wrote: Duncan == Duncan Murdoch [EMAIL PROTECTED] on Tue, 07 Jun 2005 12:12:57 -0400 writes: . The current .Rd files don't just document functions, they also document data objects and classes. But the main point here is that it's not good to have multiple disconnected sets of documentation for a package. Users should be able to say the equivalent of give me help on foo, and get help on foo, whether it's a function, a data object, a package, a method, a class, or whatever. It's a bad design to force them to ask for the same sort of thing in different ways depending on the type of thing they're asking for. ... On 6/7/2005 11:59 AM, Robert Gentleman wrote: Hi Duncan and others, I think they are linked. There are tools available both in R and in Bioconductor and some pop things up and some don't. It doesn't take much work to add vignettes to the windows menu bar - as we have done in BioC for some time now - it would be nice if this was part of R, but no one seems to have been interested in achieving that. Fixing the help system to deal with more diverse kinds of help would be nice as well - but taking one part of it and saying, now everyone must do it this way is not that helpful. I respectfully disagree about the main point. My main point is, I don't want more things imposed on me; dealing with R CMD check is enough of a burden in its current version, without someone deciding that it would be nice to have a whole bunch more requirements. Folks should feel entirely free to do what they want - but a little less free to tell me what I should be doing. Duncan And I disagree pretty strenuously about that. One Duncan of the strengths of R is that it does impose Duncan standards on contributed packages, and these make Duncan them easier to use, less likely to conflict with Duncan each other, and so on. Duncan We shouldn't impose things lightly, but if they do Duncan make packages better, we should feel no reason not Duncan to tell you what you should be doing. As Kurt mentioned early in this thread, we currently have the auto-generated information from either help(package = pkgname)# or (equivalently!) library(help = pkgname) which shows DESCRIPTION + (user-written/auto-generated) INDEX + mentions vignettes and other contents in inst/doc/ Now if Duncan would write some R code that produces a man/pkgname.Rd file from the above information I would like to second what Gabor said earlier in this thread: we cannot simply create man/pkgname.Rd because this will already exist for many packages. Examples that come to my mind include: betareg, chron, ellipse, flexmix, ineq, zoo, and many more. Renaming the package is not an option, so probably the man page has to be renamed to something like man/pkgname.package.Rd, say. And then doing help(package = foo) and help(foo.package) is not that much of a difference, is it? Personally, I find the former more intuitive. Z -- and as he mentioned also added some of that functionality to package.skeleton(), I think everyone could become happy, i.e., we could improve the system in the future with only a very light burden on the maintainers of currently existing packages: You'd have to run the new R function only once for every package you maintain. Also, the use of a user-written INDEX file could eventually completely be abandoned in favor of maintaining man/pkgname.Rd, which is much nicer; I'd welcome such a direction quite a bit. And as much as I do like (and read) the vignettes that are available, I also do agree that writing one other *.Rd file is easier for many new package authors than to write a vignette -- the package author already had to learn *.Rd syntax anyway -- and it's nice to be able to produce something where hyperlinks to the other existing reference material (ie. help pages) just works out of the box. OTOH, we should still keep in mind that it's worth to try to get bi-directional linking between (PDF) vignettes and help files (assuming all relevant files are installed by R CMD INSTALL of course). Martin Duncan Currently R has 3 types of help: the .Rd files in Duncan the man directory (which are converted into plain Duncan text, HTML, compiled HTML, LaTex, DVI, PDF, etc), Duncan the vignettes, and unstructured files in inst/doc. Duncan We currently require .Rd files for every function Duncan and data
Re: [Rd] Suggestion: help(package name)
I share Robert's `pretty strenuous' objections. Adding compulsory things for package writers seems to me to need very compelling arguments. Checking that a package does what it says (e.g. the code in vignettes can be run) is one thing, but checking it does things it does not say it wants to do is quite another. On Tue, 7 Jun 2005, Robert Gentleman wrote: Duncan Murdoch wrote: On 6/7/2005 11:59 AM, Robert Gentleman wrote: Duncan Murdoch wrote: On 6/7/2005 11:12 AM, Robert Gentleman wrote: Robin Hankin wrote: My 0.02: I use Misc.Rd for the purpose that Duncan suggests. I put things like details and rationale for package organization, pointers to the most important function(s) in the package, and perhaps function descriptors for ubiquitous functions that don't warrant their own helppage, but need documentation [in the case of gsl, this would be strictify() and process.args(), which every user needs to know]. It would be *great* to be required to put in package.gsl.R (or should that be gsl.package.Rd?) for this purpose. Then maybe R CMD check could check for its presence and throw a wobbly if it isn't there. Hi, Well, I pretty strenuously object. That is just what vignettes are for and the last thing I need is more wobbly's from R CMD check. Function documentation should document functions. If you want to document something more substantial then please use the tools already provided to do that - and if you don't want to, and you want to make use of the tools for function documentation in some other way please don't try to impose your version of what should happen on others. The current .Rd files don't just document functions, they also document data objects and classes. But the main point here is that it's not good to have multiple disconnected sets of documentation for a package. Users should be able to say the equivalent of give me help on foo, and get help on foo, whether it's a function, a data object, a package, a method, a class, or whatever. It's a bad design to force them to ask for the same sort of thing in different ways depending on the type of thing they're asking for. Hi Duncan and others, I think they are linked. There are tools available both in R and in Bioconductor and some pop things up and some don't. It doesn't take much work to add vignettes to the windows menu bar - as we have done in BioC for some time now - it would be nice if this was part of R, but no one seems to have been interested in achieving that. Fixing the help system to deal with more diverse kinds of help would be nice as well - but taking one part of it and saying, now everyone must do it this way is not that helpful. I respectfully disagree about the main point. My main point is, I don't want more things imposed on me; dealing with R CMD check is enough of a burden in its current version, without someone deciding that it would be nice to have a whole bunch more requirements. Folks should feel entirely free to do what they want - but a little less free to tell me what I should be doing. And I disagree pretty strenuously about that. One of the strengths of R is that it does impose standards on contributed packages, and these make them easier to use, less likely to conflict with each other, and so on. We shouldn't impose things lightly, but if they do make packages better, we should feel no reason not to tell you what you should be doing. Let's see, some of us (three years ago) developed a tool to solve this problem. We made it available to others to use as they saw fit. I feel no less strong than you do, but I certainly did not impose what I thought on you and I ask for the same respect. We have already solved this problem in our own way. You now seem to think that it is zero cost to impose on us a second (and in my view inferior solution). I am asking that you not do that. Please, feel free to develop what you want and to encourage others to use it, but don't try to make people do things just because you want them that way. We have lots of packages in BioC the costs of reengineering so we can meet your newly imposed standards are not zero. I think we have an expectation that such capricious behaviour will not be entered in to, and if we don't then perhaps it is time to branch the project. Best wishes, Robert Currently R has 3 types of help: the .Rd files in the man directory (which are converted into plain text, HTML, compiled HTML, LaTex, DVI, PDF, etc), the vignettes, and unstructured files in inst/doc. We currently require .Rd files for every function and data object. Adding a requirement to also document the package that way is not all that much of a burden, and will automatically give all those output formats I listed above. It will help to solve the often-complained about problem of packages that contain no overview at all. (Requiring a vignette and giving a way to display it would also do
Re: [Rd] Suggestion: help(package name)
Prof Brian Ripley wrote: I share Robert's `pretty strenuous' objections. Adding compulsory things for package writers seems to me to need very compelling arguments. Checking that a package does what it says (e.g. the code in vignettes can be run) is one thing, but checking it does things it does not say it wants to do is quite another. I don't understand your complaint. Could you explain what you meant by checking it does things it does not say it wants to do? My proposal (modified following the suggestions I've heard so far) is as follows: - to check that a couple of help topic aliases exist (pkg.package and pkg) - to recommend that pkg.package contain general information about the package, and that pkg be an alias for it, if it isn't used for some other purpose. - to write promptPackage() to help create an initial version of pkg.package.Rd. It can get some information from the DESCRIPTION file; perhaps it could go looking for a vignette, or the INDEX, or - to modify the other help system tools to make use of this (e.g. the package:pkg heading on a page would become a link to the pkg.package alias, etc.) None of these things are very much work, and I'd be happy to do them and document them. The thing that will be more work is to write the pkg.package.Rd files for every package. (I'd do it for the base packages; they'd be short.) It won't be a huge amount of work for any one package (many of them already have the basic content in various places, so for those it's mostly a matter of reformatting), but in total it will be a lot. I think the benefit of this will be that the help for a package will show up in a standard location, using the standard method for looking for it. This is not a huge benefit for any users who already know all about the current ways help can be given, but I think it would be a real benefit for users who aren't so familiar with things. It would help to unify the help system: everyone knows about ?topic, so providing a standard way for that to lead into all the rest of the documentation seems obviously beneficial to me. Making this optional would weaken it quite a bit. Packages couldn't give links to the main page in other packages if they weren't guaranteed to exist; producing the HTML would be more difficult if links worked sometimes and didn't work other times, etc. Robert Gentleman wrote: Let's see, some of us (three years ago) developed a tool to solve this problem. Do you mean vignettes? I think they solved a different problem. They provided a way to give good general documentation for a package, but they didn't provide a way to get to it through the help system. They aren't used for general introductory help for any of the standard packages except grid and Matrix, and they use different naming conventions in those two. We made it available to others to use as they saw fit. I feel no less strong than you do, but I certainly did not impose what I thought on you and I ask for the same respect. R imposes lots of things on me. I have to document every function, and I have to get the usage section right. These take work, but they make packages more useful. I think imposing one more help topic on the package is in the same character. I'm really surprised that you find it so objectionable. It's really not much work! We have already solved this problem in our own way. You now seem to think that it is zero cost to impose on us a second (and in my view inferior solution). I have no idea where you got the impression that I think this is zero cost. I think it's low cost per package, but obviously not zero. I am asking that you not do that. Please, feel free to develop what you want and to encourage others to use it, but don't try to make people do things just because you want them that way. We have lots of packages in BioC the costs of reengineering so we can meet your newly imposed standards are not zero. I'd put the cost of the proposal to the package writer at about the cost of documenting one function. I wouldn't call it reengineering. It's an addition, not a major change. I think we have an expectation that such capricious behaviour will not be entered in to, and if we don't then perhaps it is time to branch the project. To tell you the truth, I wouldn't consider branching over this issue. I'd prefer some rational discussion about the proposal. I really don't understand why you think it's such a disastrous one that you couldn't possibly live with it and would want to do all your work on a different branch. Here are the kinds of question I'd like to discuss: 1. Could you tell me what you think would be involved in reengineering? Maybe you have misunderstood the proposal, or I've missed something. How much time do you think this would take? 2. What is the current algorithm people should use to look for help on foo? Couldn't we make it simpler? I'd like it
RE: [Rd] Suggestion: help(package name)
Let me add to the pot: I think Robert and Brian are against imposing additional _requirement_ on packages to provide an overview in .Rd, and I tend to agree with that sentiment. However, if such a facility is made optional (like vignettes) for package author/maintainer, then I have no problem with it. Perhaps it can work like the CITATION file: The package author/maintainer can choose to (or not to) use it. If one is not provided in the package source, then something halfway sensible is auto-generated from various files (or perhaps just runs help(package=pkg). Or perhaps yet another function can be added to the `utils' package, like packageOverview(), which can either: - open an overview vignette if one is provided - open the overview .Rd in whatever format the default help is in - run help(package=pkg) if neither is available Just my $0.02... Andy From: Duncan Murdoch Prof Brian Ripley wrote: I share Robert's `pretty strenuous' objections. Adding compulsory things for package writers seems to me to need very compelling arguments. Checking that a package does what it says (e.g. the code in vignettes can be run) is one thing, but checking it does things it does not say it wants to do is quite another. I don't understand your complaint. Could you explain what you meant by checking it does things it does not say it wants to do? My proposal (modified following the suggestions I've heard so far) is as follows: - to check that a couple of help topic aliases exist (pkg.package and pkg) - to recommend that pkg.package contain general information about the package, and that pkg be an alias for it, if it isn't used for some other purpose. - to write promptPackage() to help create an initial version of pkg.package.Rd. It can get some information from the DESCRIPTION file; perhaps it could go looking for a vignette, or the INDEX, or - to modify the other help system tools to make use of this (e.g. the package:pkg heading on a page would become a link to the pkg.package alias, etc.) None of these things are very much work, and I'd be happy to do them and document them. The thing that will be more work is to write the pkg.package.Rd files for every package. (I'd do it for the base packages; they'd be short.) It won't be a huge amount of work for any one package (many of them already have the basic content in various places, so for those it's mostly a matter of reformatting), but in total it will be a lot. I think the benefit of this will be that the help for a package will show up in a standard location, using the standard method for looking for it. This is not a huge benefit for any users who already know all about the current ways help can be given, but I think it would be a real benefit for users who aren't so familiar with things. It would help to unify the help system: everyone knows about ?topic, so providing a standard way for that to lead into all the rest of the documentation seems obviously beneficial to me. Making this optional would weaken it quite a bit. Packages couldn't give links to the main page in other packages if they weren't guaranteed to exist; producing the HTML would be more difficult if links worked sometimes and didn't work other times, etc. Robert Gentleman wrote: Let's see, some of us (three years ago) developed a tool to solve this problem. Do you mean vignettes? I think they solved a different problem. They provided a way to give good general documentation for a package, but they didn't provide a way to get to it through the help system. They aren't used for general introductory help for any of the standard packages except grid and Matrix, and they use different naming conventions in those two. We made it available to others to use as they saw fit. I feel no less strong than you do, but I certainly did not impose what I thought on you and I ask for the same respect. R imposes lots of things on me. I have to document every function, and I have to get the usage section right. These take work, but they make packages more useful. I think imposing one more help topic on the package is in the same character. I'm really surprised that you find it so objectionable. It's really not much work! We have already solved this problem in our own way. You now seem to think that it is zero cost to impose on us a second (and in my view inferior solution). I have no idea where you got the impression that I think this is zero cost. I think it's low cost per package, but obviously not zero. I am asking that you not do that. Please, feel free to develop what you want and to encourage others to use it, but don't try to make people do things just because you want them that way. We have lots of packages in BioC the costs of reengineering so we can meet your newly
Re: [Rd] Suggestion: help(package name)
Liaw, Andy wrote: Let me add to the pot: I think Robert and Brian are against imposing additional _requirement_ on packages to provide an overview in .Rd, and I tend to agree with that sentiment. However, if such a facility is made optional (like vignettes) for package author/maintainer, then I have no problem with it. Perhaps it can work like the CITATION file: The package author/maintainer can choose to (or not to) use it. If one is not provided in the package source, then something halfway sensible is auto-generated from various files (or perhaps just runs help(package=pkg). Or perhaps yet another function can be added to the `utils' package, like packageOverview(), which can either: - open an overview vignette if one is provided - open the overview .Rd in whatever format the default help is in - run help(package=pkg) if neither is available We don't have a standard name for an overview vignette, and I don't like the idea of creating a new help function (packageOverview) that someone who doesn't know much about R will have to find before they can use, but I like the idea of the help system doing its best to help. So I'd like this better if it were modified so that ?foo tries the following - to open help alias foo - if that fails, and foo is a package name: - tries to open a vignette with some standard name (proposals?) - if that fails, then does help(package=foo) This has the disadvantage over the original proposal that help pages can't link to a standard help topic for the package, so I like the original better, but this would be better than the status quo. Duncan Murdoch Just my $0.02... Andy From: Duncan Murdoch Prof Brian Ripley wrote: I share Robert's `pretty strenuous' objections. Adding compulsory things for package writers seems to me to need very compelling arguments. Checking that a package does what it says (e.g. the code in vignettes can be run) is one thing, but checking it does things it does not say it wants to do is quite another. I don't understand your complaint. Could you explain what you meant by checking it does things it does not say it wants to do? My proposal (modified following the suggestions I've heard so far) is as follows: - to check that a couple of help topic aliases exist (pkg.package and pkg) - to recommend that pkg.package contain general information about the package, and that pkg be an alias for it, if it isn't used for some other purpose. - to write promptPackage() to help create an initial version of pkg.package.Rd. It can get some information from the DESCRIPTION file; perhaps it could go looking for a vignette, or the INDEX, or - to modify the other help system tools to make use of this (e.g. the package:pkg heading on a page would become a link to the pkg.package alias, etc.) None of these things are very much work, and I'd be happy to do them and document them. The thing that will be more work is to write the pkg.package.Rd files for every package. (I'd do it for the base packages; they'd be short.) It won't be a huge amount of work for any one package (many of them already have the basic content in various places, so for those it's mostly a matter of reformatting), but in total it will be a lot. I think the benefit of this will be that the help for a package will show up in a standard location, using the standard method for looking for it. This is not a huge benefit for any users who already know all about the current ways help can be given, but I think it would be a real benefit for users who aren't so familiar with things. It would help to unify the help system: everyone knows about ?topic, so providing a standard way for that to lead into all the rest of the documentation seems obviously beneficial to me. Making this optional would weaken it quite a bit. Packages couldn't give links to the main page in other packages if they weren't guaranteed to exist; producing the HTML would be more difficult if links worked sometimes and didn't work other times, etc. Robert Gentleman wrote: Let's see, some of us (three years ago) developed a tool to solve this problem. Do you mean vignettes? I think they solved a different problem. They provided a way to give good general documentation for a package, but they didn't provide a way to get to it through the help system. They aren't used for general introductory help for any of the standard packages except grid and Matrix, and they use different naming conventions in those two. We made it available to others to use as they saw fit. I feel no less strong than you do, but I certainly did not impose what I thought on you and I ask for the same respect. R imposes lots of things on me. I have to document every function, and I have to get the usage section right. These take work, but they make packages more useful. I think imposing one more help topic on the package is in the
Re: [Rd] Suggestion: help(package name)
My understanding is that one could still build, install and distribute a package that did not conform to this requirement but it would fail R CMD CHECK. Thus as long as you don't want to place it in a repository that requires a clean R CMD CHECK you are under no obligation to do it. But if you do want to use CRAN or other repository that enforces quality via R CMD CHECK then the package must meet that quality and so to that extent would this would be a requirement. Perhaps this could even be expanded into quality levels. In a sense this is already the case as the level can be regarded as whether the package: - fails R CMD CHECK - passes R CMD CHECK but with warnings - fully passes R CMD CHECK as shownn in the check summary: http://probability.ca/cran/src/contrib/checkSummary.html An additional level could be added for those packages possessing a vignette (where the horizontal line is the threshold for CRAN admission) but the quality would be published on the web as it is now: - fails R CMD check - - passes it with warnings - fully passes it - fully passes it and has a vignette Personally I think Duncan's proposal is an excellent idea and that the quality of packages should be driven and enforced by the needs of the users. This makes it easier to use packages for users and though it requires extra work from the developers it is not onerous. On 6/7/05, Liaw, Andy [EMAIL PROTECTED] wrote: Let me add to the pot: I think Robert and Brian are against imposing additional _requirement_ on packages to provide an overview in .Rd, and I tend to agree with that sentiment. However, if such a facility is made optional (like vignettes) for package author/maintainer, then I have no problem with it. Perhaps it can work like the CITATION file: The package author/maintainer can choose to (or not to) use it. If one is not provided in the package source, then something halfway sensible is auto-generated from various files (or perhaps just runs help(package=pkg). Or perhaps yet another function can be added to the `utils' package, like packageOverview(), which can either: - open an overview vignette if one is provided - open the overview .Rd in whatever format the default help is in - run help(package=pkg) if neither is available Just my $0.02... Andy From: Duncan Murdoch Prof Brian Ripley wrote: I share Robert's `pretty strenuous' objections. Adding compulsory things for package writers seems to me to need very compelling arguments. Checking that a package does what it says (e.g. the code in vignettes can be run) is one thing, but checking it does things it does not say it wants to do is quite another. I don't understand your complaint. Could you explain what you meant by checking it does things it does not say it wants to do? My proposal (modified following the suggestions I've heard so far) is as follows: - to check that a couple of help topic aliases exist (pkg.package and pkg) - to recommend that pkg.package contain general information about the package, and that pkg be an alias for it, if it isn't used for some other purpose. - to write promptPackage() to help create an initial version of pkg.package.Rd. It can get some information from the DESCRIPTION file; perhaps it could go looking for a vignette, or the INDEX, or - to modify the other help system tools to make use of this (e.g. the package:pkg heading on a page would become a link to the pkg.package alias, etc.) None of these things are very much work, and I'd be happy to do them and document them. The thing that will be more work is to write the pkg.package.Rd files for every package. (I'd do it for the base packages; they'd be short.) It won't be a huge amount of work for any one package (many of them already have the basic content in various places, so for those it's mostly a matter of reformatting), but in total it will be a lot. I think the benefit of this will be that the help for a package will show up in a standard location, using the standard method for looking for it. This is not a huge benefit for any users who already know all about the current ways help can be given, but I think it would be a real benefit for users who aren't so familiar with things. It would help to unify the help system: everyone knows about ?topic, so providing a standard way for that to lead into all the rest of the documentation seems obviously beneficial to me. Making this optional would weaken it quite a bit. Packages couldn't give links to the main page in other packages if they weren't guaranteed to exist; producing the HTML would be more difficult if links worked sometimes and didn't work other times, etc. Robert Gentleman wrote: Let's see, some of us (three years ago) developed a tool to solve this problem. Do you mean
