Fix “\special” in usage documentation

[klmr]

The reference usage parser was missing support for the Rd \special tag. This PR adds the missing support.

The \special tag is rarely used so it’s easily overlooked. The PR contains an addition to the test project under tests/testthat/assets/reference which illustrates the usage for the ? operator (mirroring that of the core R ? operator defined in ‘utils’).

It’s worth considering how such “special” operators should be rendered in the pkgdown reference index (currently, ? is rendered as `?()`, which is … idiosyncratic). But this affects operators regardless of their Rd usage declaration, and is therefore beyond the scope of this PR.

[hadley]

Can you please point to the docs for \special? I don't see it in R-exts.

[klmr]

I don’t think it’s mentioned in R-exts. It’s mentioned in Duncan Murdoch’s 2010 description of parseRd, and it is used extensively throughout the R core library’s Rd files.

[hadley]

In that case, can you add a comment above as_html.tag_special() that provides a brief explanation and links to a couple of examples in https://github.com/wch/r-source?

[klmr]

Gladly. How’s the new commit? Are the path references OK or should I include actual links into the Git mirror?

I’ve also force-pushed a rebase against master, since the previous PR had a conflict.

I’ve just noticed that the ‘rlang’ package currently has no “usage” section for its bang bang, big bang and interpolation operators in ?nse-force, which might be a use-case for \special.

[hadley]

Could you make them real links please?

Agreed about use in rlang - there are probably a few places we can use it now that we know it exists.

[hadley]

Thanks! Can you you please add a news bullet (it should briefly describe the change and end with (@yourname, #issuenumber)), and then I'll merge.