Definition lists in markdown

[nuno-agostinho]

How does one creates definition lists in markdown? For instance, how to translate the following to Markdown:

#' \describe{
#'   \item{Pear}{Green fruit}
#'   \item{Banana}{Yellow fruit}
#' }

Unfortunately, the Markdown vignette doesn't mention these types of list.

[gaborcsardi]

You cannot, currently. Not supported by the commonmark implementation we use. There is a discussion here: https://talk.commonmark.org/t/description-list/289/1
But there seems to be no interest...

At some point we'll look at adding commonmark extensions for various Rd features that are currently not supported. But for now you'll have to write this list in Rd.

[tbates]

Would it make sense to use the same markdown that GitHub uses? Would give tables, and other features that would make a lot of sense to improving help docs

[hadley]

@tbates I know that commonmark can now use the GitHub extensions. Can you please review the options available and open a new issue?

[gaborcsardi]

Here is the GFM spec for commonmark: https://github.github.com/gfm/

It does not seem to support definition lists. It has:

• tables
• task lists
• strikethrough
• autolinks
• disallowed raw html

None if these seem very important to me.

[tbates]

I asked this on stack a week ago... Glad if tables are supported. Enabling them would help build nice Rd files. http://stackoverflow.com/questions/43017168/does-roxygen-6-support-tables

[hadley]

Yeah, tables would be moderately useful.

[gaborcsardi]

OK. Fun challenge:

1. do you have a manual page with a table?
2. do you know of a manual page with a table?

I admit, that I don't know of any.

[gaborcsardi]

But maybe if we make it easier, then people will actually use it.

[hadley]

I know I've made one. I just don't remember where.

[tbates]

CRAN give this example

#' \url{https://cran.r-project.org/doc/manuals/R-exts.html#Lists-and-tables}
#'
#' \tabular{rlll}{
#' [,1] \tab Ozone \tab numeric \tab Ozone (ppb)\cr
#' [,2] \tab Solar.R \tab numeric \tab Solar R (lang)\cr
#' [,3] \tab Wind \tab numeric \tab Wind (mph)\cr
#' [,4] \tab Temp \tab numeric \tab Temperature (degrees F)\cr
#' [,5] \tab Month \tab numeric \tab Month (1--12)\cr
#' [,6] \tab Day \tab numeric \tab Day of month (1--31)
#' }
#'

Which in markdown would be:

[,1]	Ozone	numeric	Ozone (ppb)
[,2]	Solar.R	numeric	Solar R (lang)
[,3]	Wind	numeric	Wind (mph)
[,4]	Temp	numeric	Temperature (degrees F)
[,5]	Month	numeric	Month (1--12)
[,6]	Day	numeric	Day of month (1--31)

In R help, the table just has a little white space around cells, no border formatting. The R doesn't appear to support any of the latex tabular notation for adding borders ( \tabular{ l | c | r | r} )

[,1]	Ozone	numeric	Ozone (ppb)
[,2]	Solar.R	numeric	Solar R (lang)
[,3]	Wind	numeric	Wind (mph)
[,4]	Temp	numeric	Temperature (degrees F)
[,5]	Month	numeric	Month (1--12)
[,6]	Day	numeric	Day of month (1--31)

[1beb]

A newer option is:

#' @details Describe your list here
#'
#' * item1 Description of item1
#' * item2 Description of item2
#' @md

[tbates]

And roxygen2 now supports markdown tables. So happy days