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

[Jari Oksanen]

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/