R devel - Aug 2005 - Why should package.skeleton() fail R CMD check?

I find it a bit peculiar that a package skeleton created with a utils
function package.skeleton() fails subsequent R CMD check. I do
understand that the function is intended to produce only a skeleton that
should be edited by the package author. I think that it would be
justified to say that the skeleton *should* fail the test. However, I
have two arguments against intentional failure:

* When you produce a skeleton, a natural thing is to see if it works and
run R CMD check. It is is baffling (but educating) if this fails.

* The second argument is more major: If you produce a package with
several functions, you want to edit one Rd file in time to see what
errors you made. You don't want to correct errors in other Rd files not
yet edited by you to see your own errors. This kind of incremental
editing is much more pleasant, as following strict R code is painful
even with your own mistakes.

The failure comes only from Rd files, and it seems that the violating
code is produced by prompt.default function hidden in the utils
namespace. I attach a uniform diff file which shows the minimal set of
changes I had to do make utils:::prompt.default to produce Rd files
passing R CMD check. There are still two warnings: one on missing source
files and another on missing keywords, but these are not fatal. This
still produces bad looking latex. These are the changes I made 

* I replaced "__description__" with "description", since
"__" will give
latex errors. 

* I enclosed ""Make other sections" within Note, so that it
won't give
error on stray top level text. It will now appear as numbered latex
\section{} in dvi file, but that can the package author correct.

* I replaced reference to a non-existent function ~~fun~~ with a
reference to function help. 

I'm sorry for the formatting of the diff file: my emacs/ESS is cleverer
than I and changes indentation and line breaks against my will.

cheers, jari oksanen
-- 
Jari Oksanen -- Dept Biology, Univ Oulu, 90014 Oulu, Finland
Ph. +358 8 5531526, cell +358 40 5136529, fax +358 8 5531061
email jari.oksanen at oulu.fi, homepage http://cc.oulu.fi/~jarioksa/

>>>>> "Jari" == Jari Oksanen <jarioksa at
sun3.oulu.fi>
>>>>>     on Wed, 31 Aug 2005 11:58:10 +0300 writes:
    Jari> I find it a bit peculiar that a package skeleton created with a
utils
    Jari> function package.skeleton() fails subsequent R CMD check. I do
    Jari> understand that the function is intended to produce only a skeleton
that
    Jari> should be edited by the package author. I think that it would be
    Jari> justified to say that the skeleton *should* fail the test. However,
I
    Jari> have two arguments against intentional failure:

    Jari> * When you produce a skeleton, a natural thing is to see if it
works and
    Jari> run R CMD check. It is is baffling (but educating) if this fails.

yes, and the ``but educating'' part has at least kept me from
fixing the problem in the past.
However, I nowadays rather agree with you.

    Jari> * The second argument is more major: If you produce a package with
    Jari> several functions, you want to edit one Rd file in time to see what
    Jari> errors you made. You don't want to correct errors in other Rd
files not
    Jari> yet edited by you to see your own errors. This kind of incremental
    Jari> editing is much more pleasant, as following strict R code is
painful
    Jari> even with your own mistakes.

    Jari> The failure comes only from Rd files, and it seems that the
violating
    Jari> code is produced by prompt.default function hidden in the utils
    Jari> namespace. I attach a uniform diff file which shows the minimal set
of
    Jari> changes I had to do make utils:::prompt.default to produce Rd files
    Jari> passing R CMD check. There are still two warnings: one on missing
source
    Jari> files and another on missing keywords, but these are not fatal.
This
    Jari> still produces bad looking latex. 

both is *desired*; a package author *should* get some urge to
edit the files,  but I now agree that she should only get
warnings, not errors.

    Jari> These are the changes I made 

    Jari> * I replaced "__description__" with
"description", since "__" will give
    Jari> latex errors. 

    Jari> * I enclosed ""Make other sections" within Note, so
that it won't give
    Jari> error on stray top level text. It will now appear as numbered latex
    Jari> \section{} in dvi file, but that can the package author correct.

    Jari> * I replaced reference to a non-existent function ~~fun~~ with a
    Jari> reference to function help. 

sounds all reasonable


    Jari> I'm sorry for the formatting of the diff file: my emacs/ESS is
cleverer
    Jari> than I and changes indentation and line breaks against my will.

hmm; did you *edit* the *source*
or did you just edit a ``dump'' of the function definition?

Since you didn't use  text/plain  as content type, your
attachment didn't make it to the list anyway, and you have a
second chance:

Please use a "diff -u" against

   https://svn.R-project.org/R/trunk/src/library/utils/R/prompt.R

or maybe even a "diff -ubBw ..." one.

Thank you for your proposition and willingness to contribute!

Martin Maechler, ETH Zurich