search

wviechtb / mathjaxr

R package to make use of Mathjax in Rd files
47 stars 6 forks source link

underscore in roxygen2 documentation sometimes renders as \emph #7

Closed roseodea closed 2 years ago

roseodea commented 3 years ago

Hi @wviechtb, I'm having problems with _ and \_ in mathjaxr equations being interpreted as \emph and \\emph.

Reproducible examples: https://github.com/roseodea/UnderscoreProblem

Do you have any advice for this problem?

Thanks, Rose

wviechtb commented 3 years ago

First of all, thanks for raising such a well-documented issue. The problem stems not from mathjaxr itself but the use of markdown parsing in roxygen2 (https://roxygen2.r-lib.org/articles/rd-formatting.html). In markdown, underline characters are used to indicate emphasized text. To avoid this happening in equations, roxygen2 does not interpret underlines as markdown within certain Rd tags including \eqn and \deqn but it does not know about the macros provided by mathjaxr (e.g., \mjdeqn). You can switch off markdown parsing (which you have globally enabled with Roxygen: list(markdown = TRUE) in DESCRIPTION) using the @noMd tag (the @md you used is superfluous since markdown parsing is already enabled globally), but it does not seem to be possible to just disable it for certain parts of a single help file. Why sometimes underlines are converted to \emph and sometimes not is not clear to me, but this has to do with the underlying rules for markdown parsing. Maybe there is a trick one could exploit here to avoid the parsing, but ultimately, I think this needs to be addressed in roxygen2 itself (not sure what the best solution is, but maybe it should be possible to allow the specification of macro names within which no markdown parsing is done).

bwiernik commented 3 years ago

@wviechtb I think the roxygen2 folks would accept a pull request adding the mathjaxr tags to the vector of escaped Rd tags here https://github.com/r-lib/roxygen2/blob/master/R/markdown-escaping.R#L32

wviechtb commented 3 years ago

@bwiernik While that may be a possibility, those tags are the 'official' Rd ones (as far as I can tell) and I am not sure if people should be suggesting to add 'their' tags to that list. This could really get out of hand and there might be clashes. Instead, it might be better if there was a way to specify tags to be ignored via DESCRIPTION, for example by expanding on Roxygen: list(markdown = TRUE) and allowing that list to include additional tags to be specified for which markdown parsing should be ignored.

wviechtb commented 2 years ago

Happy to see that roxygen2 now escapes the mathjaxr tags (and thanks to @bwiernik for making the pull request): https://github.com/r-lib/roxygen2/pull/1231

bwiernik commented 2 years ago

Awesome! I'd forgotten about this!

roseodea commented 2 years ago

Thanks!