Links to non-vignette documentation

They are meant to replace the INDEX, which you shouldn't need to create
any more.  The DESCRIPTION file is still needed, but it contains more
structured information meant for mechanical reading and processing; the
package man page is meant to be the place to put things intended for
people to read.

Do I need to keep the list of functions on the package man page in
sync myself, or will they be automatically rebuilt?  Is the intention
to eventually change help(package=XXX) to point to the package man
page?

No, there's no automatic building after the promptPackage call.  It's up 
to you to decide which functions need to be mentioned to users.  In 
large packages it usually doesn't make sense to list all the functions, 
so the package writer needs to use judgement here.  There are other 
mechanisms (e.g. ls("package:XXX") for a list of names, the help index 
generation for a list of names and titles) to get a list of everything.

There aren't any immediate plans to change help(package=XXX), but I 
think in the long run, if package?XXX receives wider support than it has 
now, it would make sense to make that change.

Duncan Murdoch