[Rd] a small suggestion for improving the building of packages

[Duncan Murdoch]

  On 16/09/2010 2:45 PM, William Dunlap wrote:
> >  From: r-devel-bounces at r-project.org
> >  [mailto:r-devel-bounces at r-project.org] On Behalf Of Janko Thyson
> >  Sent: Thursday, September 16, 2010 11:19 AM
> >  To: r-devel at r-project. org
> >  Subject: Re: [Rd] a small suggestion for improving the
> >  building of packages
> ...
> >  Dear Uwe,
> >  in principle, I totally agree with your point of politely
> >  forcing developers
> >  to write well documented packages. However, when you're trying to put
> >  together a package, you (or at least I) never get it
> >  completely right on the
> >  first, say, 20 tries ;-) Yet, by running package.skelleton()
> >  over and over
> >  to keep track of changes you made during the process, you
> >  overwrite all Rd
> >  files each time - including the ones that you might already
> >  have put a lot
> >  of effort into.
>
> Running package.skeleton more than once is destructive.
> Perhaps it needs an update=TRUE/FALSE sort of option
> to let you add functions and Rd templates.

Yes, that would be a nice addition.  I think good default behaviour 
would be to only create new files if none of the same name already exist 
(and warn that's what you did), but with an option to completely 
overwrite what was there.

> When I start a package I don't use package.skeleton,
> mainly because it won't make all the usual directories
> that I expect to eventually use: src, data, inst, test
> (or it is tests?), etc.  I'd rather that it made all
> the usual directories (with the proper spelling) so
> I could delete them if they ended up being empty.
> Do other package writers use package.skeleton routinely?

I don't make a lot of new packages, but I do use it for quick little 
ones.  I'm not so sure we should create all the directories:  it's 
mainly aimed at beginners, who might find that intimidating.  Advanced 
users can do what you do.  Perhaps an option (default off) to create 
everything
would be a good compromise.

Duncan Murdoch

> I copy a template package directory, edit the template
> DESCRIPTION file, copy my code into the appropriate
> subdirectories, and run prompt(func, filename="pkg/man/func.Rd")
> on each function or dataset.   The last step is a pain:
> it would be nice if prompt had a dir= or destdir= argument
> so that
>     prompt(func, destdir="pkg/man")
> would make the file "pkg/man/func.Rd".
>
> Bill Dunlap
> Spotfire, TIBCO Software
> wdunlap tibco.com
>
> >  And delaying documentation to the very end of
> >  the process is
> >  probably not the best idea either ;-) IMHO the community
> >  should favor the
> >  approaches taken by packages such as roxygen or inlinedocs as
> >  at least it
> >  provides some sort of direct synchronization between code and
> >  documentation.
> >  Maybe one could agree on rejecting code that is missing
> >  roxygen or inlinedoc
> >  code, which would ensure that code is documented properly. In
> >  fact, isn't
> >  programming all about automating unnecessary manual
> >  procedures? I would
> >  count starting from scratch with all help files time and time
> >  again to be
> >  one of those unnecessary procedures. This time could better
> >  be invested in
> >  increasing the package's functionality.
> >
> >  Best regards, my thanks go out to everyone as well,
> >  Janko
> >
> >  >  >  Thanks, as always, to everyone for their hard work to keep my
> >  >  statistical
> >  >  >  computing free and easy.
> >  >  >
> >  >  >  Best,
> >  >  >
> >  >  >  Kyle
> >  >  >
> >  >  >  [[alternative HTML version deleted]]
> >  >  >
> >  >  >  ______________________________________________
> >  >  >  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