R devel - Mar 2022 - stage=install in \doi definition could lead to problems

Good Sys.time() everyone,

If this is not the right place for such questions, please let me know.

I was wondering why \doi has been changed to stage=install instead of
stage=build in r81891 [1]. I think it might lead to problems, but in
the spirit of Chesterton's fence, I'd like to learn the reasons. Is it
to make R CMD build more performant, avoiding the need for the
"installing the package to process man pages" step for the common case
of the \doi macro?

Some DOIs look a bit scary. One example that comes to mind is as
follows:

10.1002/(SICI)1099-128X(199801/02)12:1<55::AID-CEM501>3.0.CO;2-#

Until the recent fix in r81817 [2], it used to require special
treatment in order to display correctly in a man page, but now it just
works if I copy and paste it into \doi{}. With the macro definition
using [stage=build], I could build a package with a recent build of
R-devel, get the correct \doi expansion inlined, install the package on
an older version of R, and it would still work, thanks to R keeping the
parse tree in build/partial.rdb.

With the macro defined using [stage=install], any version of R older
than 2022-02-25 (r81817), which doesn't have this fix, would fail to
link to the DOI correctly, not having the correct expansion of \doi
to rely upon any more:

Rd2HTML(parse_Rd(textConnection('\\name{foo}\n\\title{bar}\\description{\\doi{10.1002/(SICI)1099-128X(199801/02)12:1<55::AID-CEM501>3.0.CO;2-#}}'),
fragment = FALSE), stages = c('build'))

<a
href="http://doi.org/10.1002/(SICI)1099-128X(199801/02)12:1%3C55::AID-CEM501%3E3.0.CO;2-#">doi:
10.1002/(SICI)1099-128X(199801/02)12:1&lt;55::AID-CEM501&gt;3.0.CO;2-#</a>

(The hash sign doesn't get URL-encoded, and the link gets broken.)

Sorry for giving you yet another case of <https://xkcd.com/1172/>. If I
have to, I might be able to "unroll" the macro myself for the few
cases
where it matters.

-- 
Best regards,
Ivan

[1]
https://github.com/r-devel/r-svn/commit/2de6a23b3ee31dadb77aabc598dbc3420cd419c0

[2]
https://github.com/r-devel/r-svn/commit/628bb4c3479d6c28694c2fa0e7f3440840eef59e

Am 15.03.22 um 21:38 schrieb Ivan Krylov:
> Good Sys.time() everyone,
> 
> If this is not the right place for such questions, please let me know.
Thank you for your feedback! I think this is the right place (but note 
that such very recent changes *could* still be work in progress and may 
sometimes need a bit more time to be worth discussing here).
> 
> I was wondering why \doi has been changed to stage=install instead of
> stage=build in r81891 [1]. I think it might lead to problems, but in
> the spirit of Chesterton's fence, I'd like to learn the reasons. Is
it
> to make R CMD build more performant, avoiding the need for the
> "installing the package to process man pages" step for the common
case
> of the \doi macro?
Yes, that certainly is one of the advantages of the change, affecting 
more than 1000 packages on CRAN that currently ship a partial Rd db just 
because they use the \doi macro. Besides considerably speeding up R CMD 
build for these packages, the change also slightly reduces the size of 
the tarballs.

I think the most probable reason for the previous use of stage=build for 
that Sexpr was to avoid shipping the PDF package manual with the 
package, as generally triggered by install or render time Sexprs. This 
has now been addressed.
> 
> Some DOIs look a bit scary. One example that comes to mind is as
> follows:
> 
> 10.1002/(SICI)1099-128X(199801/02)12:1<55::AID-CEM501>3.0.CO;2-#
> 
> Until the recent fix in r81817 [2], it used to require special
> treatment in order to display correctly in a man page, but now it just
> works if I copy and paste it into \doi{}. With the macro definition
> using [stage=build], I could build a package with a recent build of
> R-devel, get the correct \doi expansion inlined, install the package on
> an older version of R, and it would still work, thanks to R keeping the
> parse tree in build/partial.rdb.
> 
> With the macro defined using [stage=install], any version of R older
> than 2022-02-25 (r81817), which doesn't have this fix, would fail to
> link to the DOI correctly, not having the correct expansion of \doi
> to rely upon any more:
> 
>
Rd2HTML(parse_Rd(textConnection('\\name{foo}\n\\title{bar}\\description{\\doi{10.1002/(SICI)1099-128X(199801/02)12:1<55::AID-CEM501>3.0.CO;2-#}}'),
> fragment = FALSE), stages = c('build'))
> 
> <a
>
href="http://doi.org/10.1002/(SICI)1099-128X(199801/02)12:1%3C55::AID-CEM501%3E3.0.CO;2-#">doi:
>
10.1002/(SICI)1099-128X(199801/02)12:1&lt;55::AID-CEM501&gt;3.0.CO;2-#</a>
> 
> (The hash sign doesn't get URL-encoded, and the link gets broken.)
> 
> Sorry for giving you yet another case of <https://xkcd.com/1172/>. If
I
> have to, I might be able to "unroll" the macro myself for the few
cases
> where it matters.
> 
Thank you for the example. I think there is another solution: you could 
set \RdOpts{stage=build} before the Rd section containing that "scary"
\doi (and if needed revert to \RdOpts{stage=install} afterwards). Then 
the corresponding Sexpr would get evaluated during the build stage as 
before and the correctly escaped hyperlink from building with 
R-devel/4.2.0 would be available also in older R versions.

	Sebastian