[Rd] Why should package.skeleton() fail R CMD check?

Martin Maechler
Wed, 31 Aug 2005 09:23:39 -0000

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