Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Definition lists in markdown #576

Closed
nuno-agostinho opened this issue Feb 2, 2017 · 12 comments
Closed

Definition lists in markdown #576

nuno-agostinho opened this issue Feb 2, 2017 · 12 comments

Comments

@nuno-agostinho
Copy link

@nuno-agostinho nuno-agostinho commented Feb 2, 2017

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
Copy link
Collaborator

@gaborcsardi gaborcsardi commented Feb 2, 2017

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.

@hadley hadley closed this Feb 2, 2017
@tbates
Copy link
Contributor

@tbates tbates commented Apr 6, 2017

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
Copy link
Member

@hadley hadley commented Apr 6, 2017

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

@gaborcsardi
Copy link
Collaborator

@gaborcsardi gaborcsardi commented Apr 6, 2017

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
Copy link
Contributor

@tbates tbates commented Apr 6, 2017

@hadley
Copy link
Member

@hadley hadley commented Apr 6, 2017

Yeah, tables would be moderately useful.

@gaborcsardi
Copy link
Collaborator

@gaborcsardi gaborcsardi commented Apr 6, 2017

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
Copy link
Collaborator

@gaborcsardi gaborcsardi commented Apr 6, 2017

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

@hadley
Copy link
Member

@hadley hadley commented Apr 6, 2017

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

@tbates
Copy link
Contributor

@tbates tbates commented Apr 8, 2017

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
Copy link

@1beb 1beb commented Feb 7, 2020

A newer option is:

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

@tbates
Copy link
Contributor

@tbates tbates commented Feb 7, 2020

And roxygen2 now supports markdown tables. So happy days

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants