[R-pkg-devel] NOTE about lack of prebuilt manual

Short version

I have recently tried to update two of my CRAN packages and I am getting
the NOTE from R CMD check --as-cran

Package has help file(s) containing install/render-stage \Sexpr{}
expressions but no prebuilt PDF manual.

(It comes on one line in the check.log)

What am I doing wrong?

===================

More details

Both packages have lived successfuly on CRAN for some time but my recent
attempts to update lead to the NOTE shown above. I notice that the
version currently on CRAN do have in the tarball a directory called
build which amongst other thing does contain the package manual. However
when I build the updated versions the tarball still contains a build
directory but without the manual.

I am using 4.4.1 under Windows 10. I open a command line and do
everything from there with R CMD, I do not use any helper package. The
help files do not explicitly contain any instance of \Sexpr{} but they
do contain macros. Both of them use mathjaxr and Rdpack and one also has
some macros written by me. They have been like that for some while. The
Rd files are hand-written, I do not use any package to generate
documentation.

I notice that R CMD build has an option to turn off the manual but I do
not set that and there does not seem to be a turn on option. I have
looked at the NEWS for R4.4.0 and 4.4.1 but withou enlightenment. The
versions on CRAN were probably generated with R 4.3.3 judgin by the date
when I made them.

I know it is only a NOTE but I would like to know why it is happening.

I hope that is enough detail to be helpful but I can expand on any
unclear areas.

--
Michael

This is something I'd run into recently as well.

The R devs changed the default from building the manual to not building the
manual. Now if you want (or need) to build the manual, you should add

BuildManual: TRUE

to your DESCRIPTION.

On Mon, Jul 8, 2024, 10:05 Michael Dewey <lists at dewey.myzen.co.uk> wrote:

Short version

I have recently tried to update two of my CRAN packages and I am getting
the NOTE from R CMD check --as-cran

Package has help file(s) containing install/render-stage \Sexpr{}
expressions but no prebuilt PDF manual.

(It comes on one line in the check.log)

What am I doing wrong?

===================

More details

Both packages have lived successfuly on CRAN for some time but my recent
attempts to update lead to the NOTE shown above. I notice that the
version currently on CRAN do have in the tarball a directory called
build which amongst other thing does contain the package manual. However
when I build the updated versions the tarball still contains a build
directory but without the manual.

I am using 4.4.1 under Windows 10. I open a command line and do
everything from there with R CMD, I do not use any helper package. The
help files do not explicitly contain any instance of \Sexpr{} but they
do contain macros. Both of them use mathjaxr and Rdpack and one also has
some macros written by me. They have been like that for some while. The
Rd files are hand-written, I do not use any package to generate
documentation.

I notice that R CMD build has an option to turn off the manual but I do
not set that and there does not seem to be a turn on option. I have
looked at the NEWS for R4.4.0 and 4.4.1 but withou enlightenment. The
versions on CRAN were probably generated with R 4.3.3 judgin by the date
when I made them.

I know it is only a NOTE but I would like to know why it is happening.

I hope that is enough detail to be helpful but I can expand on any
unclear areas.

--
Michael

	[[alternative HTML version deleted]]

-----Original Message-----
From: R-package-devel <r-package-devel-bounces at r-project.org> On Behalf Of Uwe
Ligges
Sent: Monday, July 8, 2024 16:40
To: Iris Simmons <ikwsimmo at gmail.com>; Michael Dewey <lists at dewey.myzen.co.uk>
Cc: List r-package-devel <r-package-devel at r-project.org>
Subject: Re: [R-pkg-devel] NOTE about lack of prebuilt manual

On 08.07.2024 16:08, Iris Simmons wrote:

This is something I'd run into recently as well.

The R devs changed the default from building the manual to not building the
manual. Now if you want (or need) to build the manual, you should add

Well, not really, we still build manuals unless file(s) containing
install/render-stage \Sexpr{}  are present (as in this case).

Best,
Uwe Ligges

BuildManual: TRUE

to your DESCRIPTION.

On Mon, Jul 8, 2024, 10:05 Michael Dewey <lists at dewey.myzen.co.uk> wrote:

Short version

I have recently tried to update two of my CRAN packages and I am getting
the NOTE from R CMD check --as-cran

Package has help file(s) containing install/render-stage \Sexpr{}
expressions but no prebuilt PDF manual.

(It comes on one line in the check.log)

What am I doing wrong?

===================

More details

Both packages have lived successfuly on CRAN for some time but my recent
attempts to update lead to the NOTE shown above. I notice that the
version currently on CRAN do have in the tarball a directory called
build which amongst other thing does contain the package manual. However
when I build the updated versions the tarball still contains a build
directory but without the manual.

I am using 4.4.1 under Windows 10. I open a command line and do
everything from there with R CMD, I do not use any helper package. The
help files do not explicitly contain any instance of \Sexpr{} but they
do contain macros. Both of them use mathjaxr and Rdpack and one also has
some macros written by me. They have been like that for some while. The
Rd files are hand-written, I do not use any package to generate
documentation.

I notice that R CMD build has an option to turn off the manual but I do
not set that and there does not seem to be a turn on option. I have
looked at the NEWS for R4.4.0 and 4.4.1 but withou enlightenment. The
versions on CRAN were probably generated with R 4.3.3 judgin by the date
when I made them.

I know it is only a NOTE but I would like to know why it is happening.

I hope that is enough detail to be helpful but I can expand on any
unclear areas.

--
Michael

This appears to be related to this change
(https://cran.r-project.org/doc/manuals/r-devel/NEWS.html):

- tools::checkRd() (used by R CMD check) detects more problems with
?\Sexpr?-based dynamic content, including bad nesting of ?\Sexpr?s
and invalid arguments.

? Tue, 9 Jul 2024 08:54:22 +0000
"Viechtbauer, Wolfgang (NP)"
<wolfgang.viechtbauer at maastrichtuniversity.nl> ?????:

This appears to be related to this change
(https://cran.r-project.org/doc/manuals/r-devel/NEWS.html):

- tools::checkRd() (used by R CMD check) detects more problems with
?\Sexpr?-based dynamic content, including bad nesting of ?\Sexpr?s
and invalid arguments.

The exact change was:

r85348 | hornik | 2023-10-18 08:13:46 +0000 (Wed, 18 Oct 2023) | 1 line
Build PDF refman only when explicitly asked for.

--- src/library/tools/R/build.R (revision 85347)
+++ src/library/tools/R/build.R (revision 85348)
@@ -633,7 +633,7 @@
          }

         needRefman <- manual &&
-            parse_description_field(desc, "BuildManual", TRUE) &&
+            parse_description_field(desc, "BuildManual", FALSE) &&
              any(btinfo[, "later"])
         if (needRefman) {
             messageLog(Log, "building the PDF package manual")

So now R CMD build only builds the manual when both BuildManual is set
to yes _and_ there are \Sexpr{}s with [stage=install or render].
(Previously BuildManual: yes was assumed by default.)

Was the motivation for this change to make R CMD build faster for
everyone, with the expectation that the relatively rare package
maintainers with non-[stage=build] \Sexpr{}s will set BuildManual: yes
to adapt?