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

[Martin Maechler]

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