a small suggestion for improving the building of packages

Thu, Sep 16, 2010 11:55 AM

On 16/09/2010 2:43 PM, Uwe Ligges wrote:

On 16.09.2010 20:18, Janko Thyson wrote:

 From: Uwe Ligges<ligges_at_statistik.tu-dortmund.de>
 Date: Wed, 15 Sep 2010 15:23:01 +0200
 On 29.08.2010 22:34, Kyle Matoba wrote:

 All,

 I just finished the process of build a package for the first time and

 found

 it characteristically (for R) very straightforward and well

 documented.

 Whenever I deal with open source software I always endeavor to finish

the

 task I have in mind, and upon completing this, I then revisit all of

the

 configurations, customizing as necessary to achieve my goals more

 fully.

 The ability to achieve some minimal level of functionality without

 the
 need

 for much filling in of configuration files, etc., is, I feel,

 important to

 not scaring off the less technically inclined such as myself.

 Based on this heuristic, it is my understanding that a few small

 suggestions

 could make building a warning-free package as easy as running
 package.skeleton(), then R CMD check, R CMD build:

 - Fill in default titles for each of the '*.Rd' files in /man
 - Take out the tildes in the 'examples' section of the '*-package.Rd'

 main

 documentation file for the package (it seems to confuse the latex

 compiler)

 - Put the lines '~~ Optionally other standard keywords, one per line,

 from

 file KEYWORDS in ~~
 ~~ the R documentation directory ~~' into the \references{} section,

 there

 is presently a warning about all text needing to be in a section.

 Dear Kyle,
 thanks for the suggestions. Actually, it is intended to generate
 warnings /
 Errors in R CMD check: We want to force package developers to document
 their
 packages probably. This way, package maintainers / developers have to
 touch
 each Rd file and cannot use them as is in order to pass the checks.
 Best wishes,
 uwe

 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.

- I don't think package.skeleton overwrites files unless you ask for it.

- I think once you got started with your package, it is not required to
call package skeleton again. I tend to add files manually since I am
working on the package hierarchy itself using some editor...

Hi Uwe.  This message is mostly for Janko and others.

You can add them manually, but I would usually use prompt(), a generic 
function that produces just one .Rd file.

It's really one of the prompt methods that package.skeleton is calling 
to produce the bad man pages.  My own feeling is that package.skeleton 
should produce a package that is installable, but it shouldn't pass "R 
CMD check" unless there's some manual intervention to fill in the details.
I think that is the current state of affairs, but if we're producing 
something that causes "R CMD build" or "R CMD INSTALL" to fail, please 
let us know.

By the way, I don't think the title can be filled in automatically 
unless a user has roxygen style documentation, so we don't.  But doesn't 
the roxygen package do that?

Duncan Murdoch

a small suggestion for improving the building of packages

Thread (11 messages)