a small suggestion for improving the building of packages

-----Urspr?ngliche Nachricht-----
Von: Duncan Murdoch [mailto:murdoch.duncan at gmail.com]
Gesendet: Donnerstag, 16. September 2010 20:55
An: Uwe Ligges
Cc: Janko Thyson; r-devel at r-project. org
Betreff: Re: [Rd] a small suggestion for improving the building of
packages

  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

- Last time I used package.skeleton is probably more than 2 years ago
(except for presentations in courses about package creation).

Best,
Uwe