I am copying a function from the checkmate package which contains the following bit of ROxygen documentation:

#'  \item{strict:}{Performs checks like with \dQuote{unique} and additionally fails for names with UTF-8 characters and names which do not comply to R's variable name restrictions.
#'    As regular expression, this is \dQuote{^[.]*[a-zA-Z]+[a-zA-Z0-9._]*$}.}

When I run devtools::document() this is converted into:

\item{strict:}{Performs checks like with \dQuote{unique} and additionally fails for names with UTF-8 characters and names which do not comply to R's variable name restrictions.
As regular expression, this is \dQuote{^\link{.}\emph{\link{a-zA-Z}+\link{a-zA-Z0-9._}}$}.}

The square brackets from the regular expression are interpreted as links. This happens to square brackets elsewhere as well. I have tried escaping them as \\[ but this doesn't help.

Clearly the developers of checkmate don't have this problem since their documentation is correctly formatted. There is nothing obvious in devtools::document() to help.

I am copying a function from the checkmate package which contains the following bit of ROxygen documentation:

#'  \item{strict:}{Performs checks like with \dQuote{unique} and additionally fails for names with UTF-8 characters and names which do not comply to R's variable name restrictions.
#'    As regular expression, this is \dQuote{^[.]*[a-zA-Z]+[a-zA-Z0-9._]*$}.}

When I run devtools::document() this is converted into:

\item{strict:}{Performs checks like with \dQuote{unique} and additionally fails for names with UTF-8 characters and names which do not comply to R's variable name restrictions.
As regular expression, this is \dQuote{^\link{.}\emph{\link{a-zA-Z}+\link{a-zA-Z0-9._}}$}.}

The square brackets from the regular expression are interpreted as links. This happens to square brackets elsewhere as well. I have tried escaping them as \\[ but this doesn't help.

Clearly the developers of checkmate don't have this problem since their documentation is correctly formatted. There is nothing obvious in devtools::document() to help.

• r
• escaping
• devtools
• roxygen2
• roxygen

1 Answer 1

I suspect you have Markdown support turned on for your package.

That is to say, you have this line in your DESCRIPTION file:

Roxygen: list(markdown = TRUE)

When Markdown support is turned on, documentation code like this in a roxygen chunk:

\dQuote{^[.]*[a-zA-Z]+[a-zA-Z0-9._]*$}

Gets rendered as:

\dQuote{^\link{.}\emph{\link{a-zA-Z}+\link{a-zA-Z0-9._}}$}

Whereas without Markdown support you get:

\dQuote{^[.]*[a-zA-Z]+[a-zA-Z0-9._]*$}

If needed, you can use @md or @noMd to turn markdown support on or off for a documentation block. See here for more details.

Alternatively, escaping the square brackets with a single backslash will work (i.e., \[ and \]), but you will still have to deal with the *s which indicate italics in markdown. Unfortunately, it appears you cannot simply escape asterisks with backslashes in the same way here. There are some ideas here which you might try, but it might be easier to simply wrap the entire regular expression in backticks which are used to indicate code and arguably what those characters are anyway. Something like:

\dQuote{`^[.]*[a-zA-Z]+[a-zA-Z0-9._]*$`}

which will render as:

\dQuote{\verb{^[.]*[a-zA-Z]+[a-zA-Z0-9._]*$}}