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

[Duncan Murdoch]

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