Behavior of `R CMD build` depending of Rd content

Question

R CMD build behaves differently whether a Rd file contains \PR{} or not. See Writing R Extensions for details on the macros.

Example when a Rd file does not contain \PR{}:

$ R CMD build test
* checking for file 'test/DESCRIPTION' ... OK
* preparing 'test':
* checking DESCRIPTION meta-information ... OK
* installing the package to process help pages
* saving partial Rd database
* checking for LF line-endings in source and make files and shell scripts
* checking for empty or unneeded directories
* building 'test_0.1.tar.gz'

Example when a Rd file contains \PR{}:

$ R CMD build test
* checking for file 'test/DESCRIPTION' ... OK
* preparing 'test':
* checking DESCRIPTION meta-information ... OK
* installing the package to process help pages
* saving partial Rd database
* building the PDF package manual      # <- this
Hmm ... looks like a package           # <- this
Converting Rd files to LaTeX           # <- this
Creating pdf output from LaTeX ...     # <- this
Saving output to 'xxx/test.pdf' ...    # <- this
Done                                   # <- this
* checking for LF line-endings in source and make files and shell scripts
* checking for empty or unneeded directories
* building 'test_0.1.tar.gz'

The additional stage (i.e. building the PDF package manual, which can be quite slow on an old computer...) is due to the call to ..Rd2pdf in .build_packages (lines 619-625). However I do not understand what triggers this stage. In addition, it is triggered only for \PR{} and not for other macros such as \CRANpkg{} and \doi{}.

Can someone trace back what happens and why? The question is on base R functions only. I do not use helpers such as devtools.

Minimal test package

Package structure

test
test/man
test/man/one.Rd
test/R
test/R/one.R
test/DESCRIPTION
test/NAMESPACE

test/man/one.Rd

\name{one}
\alias{one}
\title{Get One}
\description{
Rd file containing or not the PR macro:
\PR{1} % comment/uncomment this line as needed
but containing other macros:
\CRANpkg{ggplot2} and \doi{10.1002/wics.147}
}
\usage{
one()
}

test/R/one.R

one <- function() 1

test/DESCRIPTION

Package: test
Version: 0.1
Title: Test
Author: Nobody
Maintainer: Nobody <[email protected]>
Description: Test.
License: GPL-3

test/NAMESPACE

export(one)

Build, check, and install with:

$ R CMD build test
$ R CMD check test_0.1.tar.gz
$ R CMD INSTALL test_0.1.tar.gz

Answer 1

Response from R-core on R's Bugzilla:

The \PR macro has initially been used exclusively in R's own NEWS.Rd, where stage does not really apply.

The stage=install default for Sexpr's probably has historical reasons: build was implemented later. I agree that stage=build is usually preferable in non-base packages to avoid blowing up the tarball with the PDF manual. A partial Rd db is often included anyway because of the \doi macro.

I haven't checked if/how we could modify the PR macro without breaking NEWS.Rd processing. Note that the macro is mentioned in WRE only as an example for \newcommand; I don't think it is of general use. It is unclear to which bug tracker a "PR#" would refer to in the help of a contributed package. It may be better to simply include the plain URL to a bug report here.

If you'd still like to use it, you could set \RdOpts{stage=build} at the beginning of the Rd file. (This requires R >= 4.1.0 due to Bug 18073.)