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

[Janko Thyson]

> -----Ursprüngliche Nachricht-----
> Von: Mark.Bravington at csiro.au [mailto:Mark.Bravington at csiro.au]
> Gesendet: Freitag, 17. September 2010 01:36
> An: kasperdanielhansen at gmail.com; kevin.r.coombes at gmail.com
> Cc: janko.thyson at ku-eichstaett.de; r-devel at r-project.org
> Betreff: RE: [Rd] a small suggestion for improving the building of
> packages
> 
> 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.

Wow, that sounds cool! I also tried to come up with a framework that puts
the focus on coding functionality and not on tediously manipulating things
in order to end up with an actual package time and time again. Thanks for
mentioning that 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.

That TOTALLY reflects my experiences so far with building packages. I can
see that this is a piece of cake for experienced developers that already can
visualize the complete layout of their package structure in their mind and
thus don't need to change a lot during the actual development. But for me
it's still a rather incremental and tentative process (I regard facilitating
this to be one of the key advantages of R) that involves changing function
and/or argument names and their order quite often. That's also why I used
package.skeleton() numerous times to reflect the changed structure in the
Rd-files. Thanks a lot for all the hints so far on how to do this
differently. Yet, if we would roughly separate developers into cracks and
beginners, it would really be great to have such an 'easy-to-use system'
(e.g. mvbutils or an upgraded version of package.skeleton()) available for
the beginners, as part of the base distribution.

> 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