Format bare operators as code

[lionel-]

So that both inline snippets are formatted as code in this example:

#> `data` can be any vector with `names()` and `[[` implementations.

Do we need a more general way to be explicit that a backticked expression should be formatted as code?

[gaborcsardi]

Well, you can always do

\code{`[[`}

I think. But it makes sense to capture the common operators I guess. Maybe we could also support

`r [[`

to force \code{}.

[lionel-]

Maybe we could also support r [[

I was thinking the same, it seems like an intuitive extension of the syntax.

[gaborcsardi]

Right. Strictly speaking it is a breaking change, though.

[hadley]

I think the easiest way is just to add a lookup list for operators, that'll catch 95% of the cases.

[lionel-]

I think part of the problem is that I didn't understand the difference between \verb and \code. From R-exts :

Verb:

Indicate text that is a literal example of a sequence of characters, with no interpretation of e.g. \var, but which will be included within word-wrapped text. Displayed using typewriter font if possible.

Code:

Indicate text that is a literal example of a piece of an R program, e.g., a fragment of R code or the name of an R object. Text is entered in R-like syntax, and displayed using typewriter font where possible. Macros \var and \link are interpreted within text.

It seems like the main difference is that code allows linking to other parts of the R documentation. And conversely verb allows inserting Rd macros literally. Does that mean we shouldn't care which of verb and code are used, since they seem to be typeset the same way?

Of relevance, non-parsable code is correctly formatted as code when it's part of a link:

[`does not parse`][foobar]

generates

\code{\link[=foobar]{does not parse}}

So one solution is to just declare code vs verb as an internal detail that doesn't concern users and roxygen should be free to generate one or the other based on the context.

[gaborcsardi]

Does that mean we shouldn't care which of verb and code are used, since they seem to be typeset the same way?

Considering that in roxygen markdown you cannot put \var or \link into \code{} (generated via backticks) currently, that would be sensible. FWIW before the latest version roxygen only generated \code{} from markdown, which was not always correct Rd, but this usage of \code{} is very common, so R accepts it.

Of relevance, non-parsable code is correctly formatted as code when it's part of a link:

Yeah, links are parsed specially, we need to do a lot of magic there, because Rd is quite peculiar with them.

So one solution is to just declare code vs verb as an internal detail that doesn't concern users and roxygen should be free to generate one or the other based on the context.

I think that is the current state of affairs, until there will be some formatting differences, e.g. we link symbols in \code{} to manual pages or something else.

[hadley]

@lionel- there are other some subtle differences — e.g. IIRC strings need to be closed and braces need to be matching in \code{} but not \verb{}.

[lionel-]

Should the tidy eval operators also be formatted as code?

[hadley]

If you can provide me a compelling reason that it makes a difference I can look into it 😄