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

[Uwe Ligges]

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

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

Best,
Uwe





>
> Best regards, my thanks go out to everyone as well,
> Janko
>
>>> Thanks, as always, to everyone for their hard work to keep my
>> statistical
>>> computing free and easy.
>>>
>>> Best,
>>>
>>> Kyle
>>>
>>> [[alternative HTML version deleted]]
>>>
>>> ______________________________________________
>>> 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