From maechler at stat.math.ethz.ch  Mon Nov 19 18:28:12 2007
From: maechler at stat.math.ethz.ch (Martin Maechler)
Date: Mon, 19 Nov 2007 18:28:12 +0100
Subject: [Rd] NEWS file (was  faqs)
In-Reply-To: <80BEBDD4-6222-499D-A9E8-AC091DC91278@r-project.org>
References: <D4F43809-6D74-4FA4-92AB-0A9248072A1A@ysidro.econ.uiuc.edu>
	<971536df0711141753r5753c3c5i6faf438bd65ebc03@mail.gmail.com>
	<473BB9E1.4020001@stats.uwo.ca>
	<971536df0711142055t652a618jbac4b5f23af48652@mail.gmail.com>
	<4ACB4F00-5E33-4ADD-B6BD-80324ACAAFCA@r-project.org>
	<473C6B78.5090605@stats.uwo.ca>
	<80BEBDD4-6222-499D-A9E8-AC091DC91278@r-project.org>
Message-ID: <18241.51116.624403.781256@stat.math.ethz.ch>


    SU> On Nov 15, 2007, at 10:53 AM, Duncan Murdoch wrote:

    >> On 11/15/2007 9:57 AM, Simon Urbanek wrote:
    >>> On Nov 14, 2007, at 11:55 PM, Gabor Grothendieck wrote:
    >>>> inst/NEWS would have the advantage of consistency with
    >>>> R itself which also has a NEWS file.
    >>>> 
    >>> I vote for NEWS for reasons above plus because that's
    >>> what I use in my packages already ;).  IMHO it should be
    >>> installed automatically if present, i.e. it shouldn't be
    >>> necessary to have it in inst/NEWS, just plain NEWS
    >>> should suffice.
    >> 
    >> And you're volunteering to make that change?
    >> 

    SU> Yup, in R-devel now (43464). However, there are other candidate files  
    SU> as well and we don't do anything with the NEWS file just
    SU> yet ... any further ideas?

Yes, I think  'NEWS' and 'ChangeLog' are typically used a bit
differently, and I would be very happy if we could install
either (and both) if present...

I'm sorry for coming this late to the thread...
Martin


    SU> Cheers, Simon

    >> 
    >>> Cheers, Simon
    >>>> 
    >>>> On Nov 14, 2007 10:15 PM, Duncan Murdoch
    >>>> <murdoch at stats.uwo.ca> wrote:
    >>>>> 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
>>>>
>>>>
>>>
>>> ______________________________________________
>>> 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



[Rd] NEWS file (was faqs)
Martin Maechler