Am 6/11/2015 um 4:55 PM schrieb Dirk Eddelbuettel:
On 11 June 2015 at 09:15, Kevin Coombes wrote:
| Grumpy Observation: In reaction to (1), I went to CRAN and randomly
| clicked on a dozen packages to see how many of them follow this rule.
| Half of them violate it explicitly, mostly just starting with "This
| package...". Most of the rest get around it by starting with a sentence
| fragment that omits the subject (which is _implicitly_ "this package").
| Only one of them started with a complete sentence that gave the
| background of the problem the package was intended to solve.
Also look at the Date: of those packages -- CRAN Policy changes have always
been implemented on a rolling basis. So new(er) packages conform to new(er)
tests, updates are always never forced on already-uploaded packages.
Yes, that's true, but may also create headaches to me when regularly
updating packages. I appreciate high standards and clear rules, given
that their motivation is obvious or clearly explained.
Therefore, I do not completely understand yet the motivation of "the
Description field in the DESCRIPTION should file should not start with
'This package' or with the package name ..." ? Where is it explained?
Now, what is the goal, a relatively long abstract with a general problem
description and then the solution, like in a scientific paper - or a
short and efficient paragraph what the package does, especially as
"Writing R Extensions" tells us:
"Description: A (one paragraph) description of what
the package does and why it may be useful."
I think that the "first sentence is a sentence fragment with implicit
'this package'" - style is not so bad, cf.:
graphics: R functions for base graphics.
stats: R statistical functions.
lme4:
Fit linear and generalized linear mixed-effects models.The models and
their components are represented using S4 classes and methods. The core
computational algorithms are implemented using the Eigen C++ library for
numerical linear algebra and RcppEigen "glue".
zoo:
An S3 class with methods for totally ordered indexed
observations. It is particularly aimed at irregular time series
of numeric vectors/matrices and factors. zoo's key design goals
are independence of a particular index/date/time class and
consistency with ts and base R by providing methods to extend
standard generics.
ggplot2: An implementation of the grammar of graphics
in R. It combines the advantages of both base and
lattice graphics: conditioning and shared axes are
handled automatically, and you can still build up a
plot step by step from multiple data sources. It also
implements a sophisticated multidimensional
conditioning system and a consistent interface to map
data to aesthetic attributes. See http://ggplot2.org
for more information, documentation and examples.
I'm still searching for good examples ...
The communication of such changes is not quite what I liked it to be.
I agree, so it is a big step forward that we now have this list.
But
if you care you can subscribe to the output stream of a cron job I have
watching over this:
https://twitter.com/CRANPolicyWatch
If you don't like twitter subscription you can still glance at that page.
I should probably do the same for the SVN source of Writing R Extensions in
R-devel...
Yes, that's what I +/- regularly did.
Many Thanks,
Thomas
--
Dr. Thomas Petzoldt
Technische Universitaet Dresden
Faculty of Environmental Sciences
Institute of Hydrobiology
01062 Dresden, Germany
E-Mail: thomas.petzo...@tu-dresden.de
http://tu-dresden.de/Members/thomas.petzoldt
______________________________________________
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
