Italic text in \insertCite{}

[ms609]

When I attempt to include markdown-formatted italic text in a textual citation, my documentation object appears as "Internal Server Error"

Non-italic

\insertCite{@sensu @Author2000}{MyPackage}

Successfully appears in place as "sensu Author (2000)"

Italic

\insertCite{@_sensu_ @Author2000}{MyPackage}

In the generated Rd file, this produces \insertCite{@\emph{sensu} @Steel2006}{TreeTools}, which I expect to render as "sensu Author (2000)".

Instead, the documentation page does not render; I just see a blank page reading "Internal Server Error".

[GeoBosh]

Thanks for the report. This is definitely a bug.

It may have something to do with \e being invalid escape sequence in R. Are you rendering the Rd to html when you get the "Internal Server Error" message? Anyway, I have any information to investigate myself.

[ms609]

Yes, it's the HTML output where I see the error.

I'm using roxygen2 in RStudio to render the documentation with devtools::document(), then ?FunctionName at the console.

Thanks for investigating, and for maintaining this extremely useful package!

[GeoBosh]

I added a line like yours in one of the Rd files in Rdpack

\insertCite{@see \emph{package} @Rpackage:rbibutils}{Rdpack}

calling viewRd() to view the file under devtools (but not in Rstudio) revealed that it is indeed the \e causing the problem with both, help and text rendering:

viewRd("man/viewRd.Rd") # type is getOption("help_type")
## Error:  Error: '\e' is an unrecognized escape in character string starting ""@see \e"
viewRd("man/viewRd.Rd", type = "html")
## Error:  Error: '\e' is an unrecognized escape in character string starting ""@see \e"
viewRd("man/viewRd.Rd", type = "text")
## Error:  Error: '\e' is an unrecognized escape in character string starting ""@see \e"

Attempting to build the package from the shell throws the same error.

[GeoBosh]

Thanks for the praise! Users help, as well with bug reports. Also, your post on Stackoverflow several years ago is probably the main way users can learn about this functionality, especially given that Rdpack is not on any task view. Another user alerted me that 'bibtex' had not been really maintained several months before it was declared orphaned, so I had time to prepare.

[GeoBosh]

I think that that the behaviour involving \e is actually a feature rather than a bug. R's functions and tools correctly throw error with informative message. The "internal server error" thrown by Rstudio's server should probably be classified as a bug in their server. The error message in the examples above is thrown before control is passed to Rdpack`s function. Long story short, the backslashes need heavy escaping here. This is not practical for Rd users and completely unacceptable for markdown users.

As a workaround I added an option to drop the parentheses in parenthesised citations, so that the user can add text with arbitrary markup before and after the citation and put manually the parentheses where needed. Compare the output of the following two commands:

Rdpack::insert_citeOnly("@see also @Rpackage:rbibutils and @parseRd", package = "Rdpack")
## (see also Boshnakov and Putman 2020 and Murdoch 2010)

Rdpack::insert_citeOnly("@see also @Rpackage:rbibutils and @parseRd;nobrackets", package = "Rdpack")
## see also Boshnakov and Putman 2020 and Murdoch 2010

Here Rdpack::insert_citeOnly is the function processing the Rd macro. To get "see also" in italic, take it out of the \insertCite call. For example, a markdown documentation chunk could be something like:

(_see also_ \insertCite{@see also @Rpackage:rbibutils and @parseRd;nobrackets}{Rdpack})

The equivalent Rd excerpt would be

(\emph{see also} \insertCite{@see also @Rpackage:rbibutils and @parseRd;nobrackets}{Rdpack})

Both will result in the following in the rendered documentation:

(see also Boshnakov and Putman 2020 and Murdoch 2010)

The version of Rdpack on Github now supports this feature. I would consider suggestions for better user-side syntax and other approaches.

[ms609]

Seems like a great solution, thanks! I'll hope to give it a go in the next few days...

Cheers!

[ms609]

Have given this a go and can confirm that it's a great solution; I can't see any obvious way to improve it! Thank you.

[GeoBosh]

Rdpack 2.1.4 is now on CRAN and includes this feature.