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

[Mark.Bravington at csiro.au]

FWIW, the package-building tools in the 'mvbutils' package-- see ?mvbutils.packaging.tools-- are supposed to alleviate much of this (provided of course you are willing to sign up to MY view of the universe...). Building a "legal" package out of existing code from scratch takes me less than 5 minutes, I never have to write a line of Rd or call package.skeleton() or remember the syntax of NAMESPACE files etc, and if I don't want to write any doco myself yet I don't have to.  Plus, 
once I've built the package the first time, I can continue to work on it "live", without needing to unload/rebuild/reinstall all the time. The modus operandi is to work from a "task package folder"-- a level above/before the formal source-package layout-- which is the basis for (i) automatically generating the source package, and (ii) updating the installed package.

WRTO some of the points in the discussion already:  
 
 - Using fixr( myfunc, new.doc=T) is a bit like 'prompt'. It will add "legal" documentation to your function 'myfunc'-- ie it should pass RCMD CHECK. (As per an earlier post, this is "automatically manipulating some text to fill in the minimal documentation necessary to pass checks"). Of course, it still won't be much use to human beings unless you take the trouble to edit it. Having said that, I've come across some packages on CRAN with documentation that is little better...

 - Documentation is in plain-text that is automatically converted to Rd format later. Even if your plain-text is "wrong", it should still emerge as "legal" Rd & help files.

 - It's subsequently up to you to keep the doco in synch with any changes you make to the function itself, but at least the code & documentation for a function live next to each other in the same text file, so you are confronted with the one whenever you change the other.

 - You can work "live" on your package while it's loaded, and all changes/additions to the code and documentation are instantly reflected. [I know I said this already, but it bears repeating :)]

R 2.12 has changed the structure of installed packages (specifically, where DLLs live), and I haven't had time to tweak mvbutils accordingly-- hopefully I will find some time to sort it out before the release of 2.12.

This email may not excite much interest because-- unlike some of the other writers-- I personally found the R package creation process to be rather horrendous; it required me to learn a whole lot of very specific things that inevitably were forgotten by the next time I had to do it. In fact, it was enough to put me off writing documentation or proper packages for a long time. Now that I have an easy-to-use system in place, I've been much better about writing documentation and distributing mini-packages to colleagues.

Mark

-- 
Mark Bravington
CSIRO Mathematical & Information Sciences
Marine Laboratory
Castray Esplanade
Hobart 7001
TAS

ph (+61) 3 6232 5118
fax (+61) 3 6232 5012
mob (+61) 438 315 623

Kasper Daniel Hansen wrote:
> I agree with Kevin, I never run package.skeleton more than once.  But
> one advantage to running it over and over again is if you change the
> names or the ordering of function arguments.  That gets autowritten
> and I could see that being convenient if you change those a lot (as
> you sometime do in development)    
> 
> Kasper
> 
> On Thu, Sep 16, 2010 at 5:17 PM, Kevin R. Coombes
> <kevin.r.coombes at gmail.com> wrote: 
>>  The phrase that caught my attention in your post is the one about
>> "running package.skeleton() over and over".  When I'm developing
>> packages, I never run it more than once.  And I usually delete a lot
>> of the files it produces (since I like to organize my functions in
>> logical batches and  not in separate files).  And once I think I
>> have the file structure organized, I put everything under version
>> control and run future development out that system.
>> 
>> Can you explain why you would need to re-run package.skeleton()? Is
>> there some use case that I am missing?
>> 
>>    Kevin
>> 
>> On 9/16/2010 1:18 PM, Janko Thyson wrote:
>>> 
>>> 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. 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
>> 
>> ______________________________________________
>> 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