Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Format bare operators as code #971

Closed
lionel- opened this issue Nov 15, 2019 · 9 comments
Milestone

Comments

@lionel-
Copy link
Member

@lionel- lionel- commented Nov 15, 2019

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

This comment has been minimized.

Copy link
Member

@gaborcsardi gaborcsardi commented Nov 15, 2019

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-

This comment has been minimized.

Copy link
Member Author

@lionel- lionel- commented Nov 15, 2019

Maybe we could also support r [[

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

@gaborcsardi

This comment has been minimized.

Copy link
Member

@gaborcsardi gaborcsardi commented Nov 15, 2019

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

@hadley

This comment has been minimized.

Copy link
Member

@hadley hadley commented Nov 15, 2019

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

@lionel-

This comment has been minimized.

Copy link
Member Author

@lionel- lionel- commented Nov 18, 2019

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

This comment has been minimized.

Copy link
Member

@gaborcsardi gaborcsardi commented Nov 18, 2019

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

This comment has been minimized.

Copy link
Member

@hadley hadley commented Nov 20, 2019

@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{}.

@hadley hadley closed this in 5672485 Nov 20, 2019
@lionel-

This comment has been minimized.

Copy link
Member Author

@lionel- lionel- commented Nov 21, 2019

Should the tidy eval operators also be formatted as code?

@hadley

This comment has been minimized.

Copy link
Member

@hadley hadley commented Nov 21, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.