[Rd] faqs

[Duncan Murdoch]

On 14/11/2007 8:53 PM, Gabor Grothendieck wrote:
> Another possibility is to just place it at the end of the vignette.
> That is where it is in the proto package:
> 
> http://cran.r-project.org/doc/vignettes/proto/proto.pdf
> 
> Package documentation is already quite scattered and adding
> a faq() command would add just one more thing one has
> to do.  Here are some places one might look already for
> documentation:
> 
> package?mypackage

Or just ?mypackage.  Writing R Extensions recommends package?mypackage, 
with ?mypackage also working if that name isn't taken.  However, the 
advice is ignored more than it is followed.

> vignette(...)
> library(help = mypackage)
> ?mycommand
> home page
> WISHLIST file
> NEWS file
> THANKS file
> svn log
> 
> I personally would give a much higher priority to a standardized
> place to find change information.  Some packages provide it.
> Some don't which is very frustrating since you see a new version
> and have no idea what has changed.  If they do document it you
> often have to download the source just to get at the change information.

Where do you put it?  I put it in inst/ChangeLog, which ends up 
installed in the package root as ChangeLog.

Whenever this has come up in the past, there have been several 
proposals, but no consensus.  So, to encourage consensus, I've got a 
proposal:

Why don't we vote on a location, with every voter agreeing to follow the 
majority?  The only condition I'd put on it is that it should be 
something that gets installed, hence somewhere in inst, but I'd be happy 
to change the name if ChangeLog doesn't win.

My vote is for inst/ChangeLog.

Duncan Murdoch

> 
> 
> 
> On Nov 14, 2007 8:22 PM, roger koenker <roger at ysidro.econ.uiuc.edu> wrote:
>> An extremely modest proposal:
>>
>> It would be nice if packages could have a FAQ and if
>>
>>        faq(package.name)
>>
>> would produce this faq.  And if, by default
>>
>>        faq()
>>        FAQ()
>>
>> would produce the admirable R faq...  Apologies in advance
>> if there is already a mechanism like this, but help.search()
>> didn't reveal anything.
>>
>> url:    www.econ.uiuc.edu/~roger                Roger Koenker
>> email   rkoenker at uiuc.edu                       Department of Economics
>> vox:    217-333-4558                            University of Illinois
>> fax:    217-244-6678                            Champaign, IL 61820
>>
>> ______________________________________________
>> R-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel