From ggrothendieck at gmail.com  Mon Jan  8 17:50:59 2007
From: ggrothendieck at gmail.com (Gabor Grothendieck)
Date: Mon, 8 Jan 2007 11:50:59 -0500
Subject: [Rd] Wish list
In-Reply-To: <971536df0701080745l3e076299k760279b7b10f2562@mail.gmail.com>
References: <971536df0612312228i4a4bb0b2h6c52c081213c296@mail.gmail.com>
	<45A042AB.4080709@stats.uwo.ca>
	<17826.25220.148425.414315@stat.math.ethz.ch>
	<971536df0701080745l3e076299k760279b7b10f2562@mail.gmail.com>
Message-ID: <971536df0701080850nbddb575saeff9d621fa47ac2@mail.gmail.com>

On 1/8/07, Gabor Grothendieck <ggrothendieck at gmail.com> wrote:
> On 1/8/07, Martin Maechler <maechler at stat.math.ethz.ch> wrote:
> > >>>>> "Duncan" == Duncan Murdoch <murdoch at stats.uwo.ca>
> > >>>>>     on Sat, 06 Jan 2007 19:45:31 -0500 writes:
> >
> >    Duncan> On 1/1/2007 1:28 AM, Gabor Grothendieck wrote:
> >    >> 7. documentation standards for packages - NEWS/ChangeLog
> >    >> (also should be accessible from CRAN page for package and
> >    >> should be included in built version of package) -
> >    >> package?mypackage
> >
> >    Duncan> Just to let you know: I uploaded a revision of rgl
> >    Duncan> just a minute ago, and moved the ChangeLog file to a
> >    Duncan> place where it will be included when installed, and
> >    Duncan> available from the ?rgl or package?rgl help topic.
> >
> > That's a good idea, but I think  "R CMD build" should try to do
> > this automatically,
> > and indeed try both 'NEWS' and 'ChangeLog'.
> >
> > With something like the following as basic idea,
> > ugly at the moment
> > (I'm using 'sh' syntax; assuming working directory is "just
> >  inside" the source package) :
> >
> >  if [ ! -f inst/ChangeLog ]
> >  then
> >   if [ -f ChangeLog ]
> >   then
> >      if [ ! -d inst ] ; then mkdir inst ; fi
> >      mv ChangeLog inst
> >
> >      <<< tar cfz .... etc build the   <pkg>_<version>tar.gz >>>
> >
> >      mv inst/ChangeLog .
> >   fi
> >  fi
> >
> > {{ yes, a proper solution would not use  'mv' and 'mv back' }}
> >
> > For pkg authors on a Unix alike OS, a very simple
> > solution would be to simply always have the real file in
> >   inst/ChangeLog
> > and have
> >   ln -s inst/ChangeLog .
> > such that niceities like "C-x 4 a" in Emacs for semi-automatic
> > ChangeLog updating still work.
> >
> > -----
> >
> > BTW, I wonder if extending the list to also include files such
> > as "TODO" or "README" wouldn't make sense too, but probably not:
> > People really interested in a package's development look at the
> > package *source*, not the installed package.
>
> I think it would be nice to extend this to THANKS so that contributors
> are recognized by the users of the package and not just the developers.
>

Also it would be nice if links to these files were on the CRAN description
page, e.g. to be clear I am referring to pages such as this:

http://cran.r-project.org/src/contrib/Descriptions/gsubfn.html

The NEWS and ChangeLog, in particular, contain information that
a user might want to read prior to downloading the package and
links to them would be particularly helpful there.



[Rd] Wish list
Gabor Grothendieck