R devel - Aug 2010 - a small suggestion for improving the building of packages

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.

Thanks, as always, to everyone for their hard work to keep my statistical
computing free and easy.

Best,

Kyle

	[[alternative HTML version deleted]]

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



> 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

On Sep 15, 2010, at 10:14 AM, peter dalgaard wrote:
> 
> On Sep 15, 2010, at 17:01 , Liaw, Andy wrote:
>> 
>> Or else it may be possible to have some malicious person write a script
>> that 
>> automagically generate some large number of bogus packages and submit
>> them to CRAN...
>> 
>> Andy
>> 
> 
> 
> Douglas Adams - 
> - There is a theory which states that if ever anybody discovers exactly
what the Universe is for and why it is here, it will instantly disappear and be
replaced by something even more bizarre and inexplicable. There is another
theory which states that this has already happened.

BTW, that "other" theory helps to explain some local politicians... 
;-)

Regards,

Marc Schwartz
http://www.wolframalpha.com/input/?i=what+is+the+meaning+of+life%3F

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

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