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

[Janko Thyson]

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

Yes it does but I ran into the problem of roxygen not being able to process
non-S4 and S4-style code/Rd-files correctly if all the files are in the same
directory, e.g. pkg/man.
I played around with 'use.Rd2' but either way I either ended up with empty
titles or this error message:
http://lists.r-forge.r-project.org/pipermail/roxygen-devel/2009-November/000
096.html.  

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