Package overview document?

I'm not sure if this is a devel or help question.

I'd like to write an overview of a package, and have it show up when
someone types

 library(help=mypackage)

or

 help(package=mypackage)

or even better, 

 ?mypackage

Right now, the first two give me a copy of the INDEX file; what I'd
like to see is a longer description.  Is it reasonable to write such a
description into the INDEX file?  Is there some other file where I can

put it, so that it will show up when someone asks about my package?

What about the latter version?  Wouldn't it be a nice improvement if
that were possible, too?

On Sun, 31 Dec 2000, Duncan Murdoch wrote:

I'd like to write an overview of a package, and have it show up when
someone types

 library(help=mypackage)

Is it reasonable to write such a
description into the INDEX file?  Is there some other file where I can

That's what a lot of other packages do, e.g. boot.

 ?mypackage

It is possible, but you need to watch namespace issues.  For example,
package sm has a file sm.Rd that gives an overview: you need it loaded
for that to work via ?sm but help(sm, package="sm") works always
(if sm is installed).

The problem is ensuring that you have a non-clashing name. dse1 has
00General.Description which seems to me to be very likely to clash.

On Sun, 31 Dec 2000 14:11:47 +0000 (GMT Standard Time), Prof Brian D
Ripley <ripley@stats.ox.ac.uk> wrote:

On Sun, 31 Dec 2000, Duncan Murdoch wrote:

I'd like to write an overview of a package, and have it show up when
someone types

 library(help=mypackage)

  ...

Is it reasonable to write such a
description into the INDEX file?  Is there some other file where I can

That's what a lot of other packages do, e.g. boot.

Okay, I'll do that.  There are a couple of deficiencies, most notably
the fact that INDEX isn't used in the HTML or LaTeX versions of the
help files.  I saw in the docs somewhere that the DESCRIPTION text
would show up in the Latex output in some later version; is anyone
working on this?  If not, I might give it a shot.

 ?mypackage

It is possible, but you need to watch namespace issues.  For example,
package sm has a file sm.Rd that gives an overview: you need it loaded
for that to work via ?sm but help(sm, package="sm") works always
(if sm is installed).

The problem is ensuring that you have a non-clashing name. dse1 has
00General.Description which seems to me to be very likely to clash.

I think the most obvious choice of name is the name of the package,
but that would clash fairly often with the name of a function within
it (e.g. boot), and it wouldn't show up first in alphabetical lists.
What some other help systems (e.g. Winhelp) do when a request is
ambiguous is to present a list of choices, with extra information
appended to help select.  If R did that, the clash wouldn't be such a
big deal.