markdown support does not work within \if{latex}{} condition?

[allenzhuaz]

I really like the roxygen2 build markdown support with option Roxygen: list(markdown = TRUE) or @md, but when I wrote some documentation within the if{latex}{} condition, the markdown language did not work within the latex condition, even if I set the markdown support option.

Details

For example, I have to write multiple items as:
#' \if{latex}{
#' Example:
#' \itemize{
#' \item 1st item
#' \item 2nd item
#' \item 3rd item }}

rather than
#' \if{latex}{
#' Example:
#' * 1st item
#' * 2nd item
#' * 3rd item }

Similarly, for inserting a table, seemingly I am only allowed to write:
#' \if{latex}{
#' \tabular{ll}{
#' a \tab b \cr
#' c \tab d
#' }}
but not allowed to use markdown, like:
#' \if{latex}{
#' | a | b |
#' |----|----|
#' | c | d |
#' }

Can the markdown support also be implemented within LaTeX condition?

[gaborcsardi]

Maybe we can fix this. Can you provide a reproducible examples please? See https://github.com/r-lib/roxygen2/blob/master/.github/SUPPORT.md#making-a-reprex

[allenzhuaz]

Please see the reproducible example:

library(roxygen2)
roc_proc_text(rd_roclet(), "
#' @section Test
#' \if{latex}{
#' List example:
#' * 1st item
#' * 2nd item
#' * 3rd item
#' Table example:
#' | a | b |
#' |---|---|
#' | c | d |
#' }
#' @export
fun <- function(){return(NULL)}
")

[hadley]

Actual reprex:

library(roxygen2)
roc_proc_text(rd_roclet(), "
#' Title
#' @section Test:
#' \\if{latex}{
#' List example:
#' * 1st item
#' * 2nd item
#' * 3rd item
#' Table example:
#' | a | b |
#' |---|---|
#' | c | d |
#' }
#' @export
fun <- function(){return(NULL)}
")[[1]]
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in ./<text>
#> \name{fun}
#> \alias{fun}
#> \title{Title}
#> \usage{
#> fun()
#> }
#> \description{
#> Title
#> }
#> \section{Test}{
#> 
#> \if{latex}{
#> List example:
#> * 1st item
#> * 2nd item
#> * 3rd item
#> Table example:
#> | a | b |
#> |---|---|
#> | c | d |
#> }
#> }

^{Created on 2020-03-10 by the reprex package (v0.3.0)}

[hadley]

I think getting this to work is going to be hard, because we'd have to parse the Rd in order to figure out which bits should be transformed.

[gaborcsardi]

According to my comments at

roxygen2/R/markdown-escaping.R

Lines 13 to 16 in 357d856

	#' Some Rd macros are treated specially:
	#'
	#' * For `if`, markdown is only allowed in the second argument.
	#' * For `ifelse` markdown is allowed in the second and third arguments.

this should work.

But it does not. It is probably not that hard, because we already escape these macros, so they are already parsed.

[gaborcsardi]

Yeah, so I think for this we need to add another mode to the roxygen_parse_tag() C function, to only parse the first argument of \if or \ifelse and leave the rest in place.

roxygen2/src/isComplete.cpp

Line 14 in e86cebf

int roxygen_parse_tag(std::string string, bool is_code = false,

[allenzhuaz]

Yeah, so I think for this we need to add another mode to the roxygen_parse_tag() C function, to only parse the first argument of \if or \ifelse and leave the rest in place.

roxygen2/src/isComplete.cpp

Line 14 in e86cebf

int roxygen_parse_tag(std::string string, bool is_code = false,

Thanks for looking into this feature, still on demand for the feature in our development, wondering whether it will be implemented in the next released version?

[gaborcsardi]

We'll look at this issue before the next release, yes.

[hadley]

Giving up on this because I now believe it would require a combined markdown + Rd parser, which I'm doubtful is worth the effort.