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
compelling arguments. Checking that a package does what it
code in vignettes can be run) is one thing, but checking 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
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
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
encourage others to use it, but don't try to make people do
because you want them that way.
We have lots of packages in BioC the costs of
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
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 if the algorithm was
"type ?foo, and read what you get", regardless of what foo is. The
proposal above doesn't achieve that, but it gets closer.
Duncan Murdoch