Text after a bullet list

[jennybc]

I'm having trouble with text after a bullet list in Markdown-ified roxygen and I think it's possible the problem is here. The problem is definitely in the XML produced from the markdown. But there are many things that happen along the way.

I want a bullet list in the description. If I have text right after the list, it gets catenated with the last bullet point. If I add an extra blank line, the text drops out of description and into details.

Here's a pure commonmark example that might explain it. Notice how the text after the bullet list gets absorbed into the bullet item. I tried with both values of hardbreaks. Is this correct behaviour?

library(commonmark)
txt <- "
first line
  * bullet 1
  * bullet 2
second line  
"
txt <- paste0(txt, collapse = "\n")

writeLines(markdown_xml(txt, hardbreaks = FALSE), "hardbreaks-FALSE.xml")
writeLines(markdown_xml(txt, hardbreaks = TRUE), "hardbreaks-TRUE.xml")

hardbreaks-FALSE.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document SYSTEM "CommonMark.dtd">
<document xmlns="http://commonmark.org/xml/1.0">
  <paragraph>
    <text>first line</text>
  </paragraph>
  <list type="bullet" tight="true">
    <item>
      <paragraph>
        <text>bullet 1</text>
      </paragraph>
    </item>
    <item>
      <paragraph>
        <text>bullet 2</text>
        <softbreak />
        <text>second line</text>
      </paragraph>
    </item>
  </list>
</document>

hardbreaks-TRUE.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document SYSTEM "CommonMark.dtd">
<document xmlns="http://commonmark.org/xml/1.0">
  <paragraph>
    <text>first line</text>
  </paragraph>
  <list type="bullet" tight="true">
    <item>
      <paragraph>
        <text>bullet 1</text>
      </paragraph>
    </item>
    <item>
      <paragraph>
        <text>bullet 2</text>
        <softbreak />
        <text>second line</text>
      </paragraph>
    </item>
  </list>
</document>

[jeroen]

Yes commonmark mandates that a list is terminated by a white line. But unfortunately as you point out, a white line in roxygen2 gets preparsed as section split.

One workaround is to insert a white line but explicitly prefix both blocks with a @description tag. This seems to work:

#' This is the title
#'
#' @description Here begins the description with a list:
#'  - **foo** bla bla
#'  - **bar** bla bla bla
#'  - **baz** blablabla
#'
#' @description Some more description text.

Maybe @gaborcsardi has a more elegant solution...

[jennybc]

Thanks. It's clear there's no problem in commonmark, then. I'll see whether @gaborcsardi thinks it merits an issue in roxygen2. The workaround is helpful.

[gaborcsardi]

I have nothing to add. G

On 16 Jun 2017 15:39, "Jennifer (Jenny) Bryan" notifications@github.com wrote:

Closed #7 https://github.com/jeroen/commonmark/issues/7.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/jeroen/commonmark/issues/7#event-1126952034, or mute the thread https://github.com/notifications/unsubscribe-auth/AAoTQBwxGsTKuB_t88c5u6y9pb8X4K1Lks5sEpOggaJpZM4N8eqA .

[hadley]

We'll make sure to mention this in the upcoming tidyverse style for roxygen page.