Roxygen2: Parsing for % characters

[ha0ye]

Can roxygen include a warning when the resulting .Rd file is mis-formatted as a result of un-escaped % characters? (which end up as comments in the .Rd format)

This sometimes produces a warning for mismatched quotes or braces (e.g. #530, #742, #786), but this doesn't always seem to be caught until R CMD CHECK.

reprex below:

library(roxygen2)

lines <- c("#' compute a percentage",
           "#' @param x the % value to use",
           "#' @export",
           "f <- function(x, y) {x / 100 * y}")

roc_proc_text(rd_roclet(), lines)
#> $f.Rd
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in RtmpcTEw4i/file6ca12af04873
#> \name{f}
#> \alias{f}
#> \title{compute a percentage}
#> \usage{
#> f(x, y)
#> }
#> \arguments{
#>   \item{x}{the % value to use}
#> }
#> \description{
#> compute a percentage
#> }

^{Created on 2019-07-18 by the reprex package (v0.3.0)}

[hadley]

I'm not sure if we'll be able to catch this one easily, but maybe we can check for an unescaped % on the final line.

[hadley]

The check is done in rdComplete() — it would probably need an additional argument as to whether or not it's a multi-line block. If that argument was true, and in_latex_comment was true, then roxygen_parse_tag() would set complete to false

[hadley]

The check shouldn't be on whether or not it's an multiline block, but whether or not the output is going to generate Rd. And rdComplete() doesn't know anything about code blocks, so my initial idea won't work at all.

Maybe it's just better to automatically escape % while doing the markdown processing? The downside is we'll have to figure out how to handle existing \% (which will be converted to \\%) but maybe that's rare enough that a one time break is worth it.

[tbates]

Be nice now if the inverse of this comment was true: "Can roxygen include a warning when the resulting .Rd file is mis-formatted as a result of escaped % characters? (which end up as backslashes in the .Rd format)

[gavinsimpson]

Ugggh; this change to escape % but not check if it's already escaped is going to bite people in the ass a lot; This caught me out at the weekend (\% -> \\%) but the errors I was seeing upon converting to roxygen to Rd weren't at all helpful in tracking down what was actually wrong.

Any chance that this could be revisited so that \% isn't automagically escaped again? I'll open a new issue if you;d like but thought best to ask here first.

[trashbirdecology]

Ugggh; this change to escape % but not check if it's already escaped is going to bite people in the ass a lot; This caught me out at the weekend (\% -> \\%) but the errors I was seeing upon converting to roxygen to Rd we're at all helpful in tracking down what was actually wrong.

Any chance that this could be revisited so that \% _isn't_ automagically escaped again? I'll open a new issue if you;d like but thought best to ask here first.

@gavinsimpson update "we're" to "were not(?)"

[hadley]

Unfortunately, I don't think changing the policy will help; it'll just add more confusion. Having to escape % sucks, but I'm reasonably confident it's the net least painful solution long term.