From hb at stat.berkeley.edu  Tue Nov  3 19:57:17 2009
From: hb at stat.berkeley.edu (Henrik Bengtsson)
Date: Tue, 3 Nov 2009 10:57:17 -0800
Subject: [Rd] Wishlist: Downgrade missing Rd links to NOTEs for
	non-installed Suggested packages
Message-ID: <59d7961d0911031057k61d5b4e0wbd75e48ced30106c@mail.gmail.com>

Hi,

I wish to suggest that Rd cross references to help sections in
"Suggested" packages that are not installed should be reported as
NOTE:s and not WARNING:s by R CMD check.  This should only apply to
packages under Suggests: in DESCRIPTION.


RATIONALE:
1. One reason for putting a package under Suggests: is that it does
not exist on any public repositories, but still possible to install
and use.  The functions provided by such a package is not necessary by
most people, but may be used by a few who then take the effort to get
hold of and install that package.  [I don't want to discuss why such
package are not on public repositories; there are heaps of reasons
which are out of my control].

2. If option $R_check_force_suggests=false, then R CMD check will
silently accept that packages under Suggests: are not
available/installed.  This is the policy of CRAN.

3. However, R CMD check will give a WARNING for Rd cross reference to
such packages, e.g.

  * checking Rd cross-references ... WARNING
    Unknown package(s) ?JohnDoePkg? in Rd xrefs

4. CRAN has a strict policy of not allowing any WARNINGs (or ERRORs).
Hence, you are forced to remove such Rd references.

5. The only way to get rid of such WARNINGs is to removing the Rd
reference/replacing it with plain text, e.g replace
\link[JohnDoePkg:aFcn]{aFcn} with 'aFcn()' in \pkg{JohnDoePkg}.  This
will "break" the link for those who do got around to install the
Suggested package.  I believe this is counter productive [I'll spare
you with real-life analogues] and discourage good documentation.  I
argue that it makes sense to keep *potentially* missing references,
especially now with the new dynamic help system.


Because of the above, I wish to suggest that such Rd links are
replaced by NOTEs.  NOTEs are accepted by CRAN.

/Henrik



[Rd] Wishlist: Downgrade missing Rd links to NOTEs for non-installed Suggested packages
Henrik Bengtsson