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

[Janko Thyson]

> -----Ursprüngliche Nachricht-----
> Von: William Dunlap [mailto:wdunlap at tibco.com]
> Gesendet: Donnerstag, 16. September 2010 20:45
> An: Janko Thyson; r-devel at r-project. org
> Betreff: RE: [Rd] a small suggestion for improving the building of
> packages
> 
> > 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.

Uwe just pointed out that there is the argument 'force' that does that but
since it said 'If FALSE will not overwrite an existing directory' I somehow
didn't consider it to handle the update=TRUE/FALSE case. My bad.

> 
> 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 agree. It would be nice if package.skeleton() would create a
'full-feature' skeleton removing empty directories during R CMD check.

> 
> 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".
> 

Oh, never really considered 'prompt()' before. Thanks for the suggestion!
All the manuals always mention 'package.skeleton()'
But couldn't you realize your destdir feature by just building a wrapper
around 'prompt()' or using it in a sapply/lapply construct?
The last couple of days I played around with Roxygen and together with a
couple of utility-functions I managed to completely automate the whole
process from creating a full-feature skeleton, processing the Rds with
roxygenize() and running the full R CMD suite on the package. That way you
document your code right within the actual script which I think is great.

Best regards,
Janko

> 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
> >