Definition lists are displayed as bullet lists

[narc-Ontakac2]

This can be seen in the ronn.1 man page itself, see lines 40 to 60. Interestingly it switches from .IP to .TP there. If I understand this correctly this should always be .TP.

[apjanke]

I believe you are correct here. I see the same thing in the rendered ronn.1 man page.

My understanding (mostly from the groff_man man page) is that .IP is "indented paragraph", and .TP is "tagged paragraph". AFAIK, there's no roff macro specifically for "definition lists", but a "tagged paragraph" is pretty much the same thing, just a more generalized form of it, and I think ronn should be emitting definition lists as .TP items.

The HTML rendering has a similar issue when I pop open ronn.1.html in a browser.

That second format looks right to me, which supports your view that .TP is the right way to do this.

Looks to me like the point where the ronn.1 output switches from .IP to .TP is where there's:

a) An additional intervening non-tagged/indented paragraph.
b) Oopsie, an unclosed <encoding item in the definition-list item immediately preceding it.

  * `-E`=<encoding>, `--encoding`=<encoding:
    Specify the encoding that input files are in. Default is UTF-8, regardless
    of user's locale settings. Input sent to STDIN is always treated as UTF-8,
    regardless of whether `-E` is passed.

Format options control the files `ronn` generates, or the output format when the
`--pipe` argument is specified. When no format options are given, both `--roff`
and `--html` are assumed.

  * `-r`, `--roff`:
    Generate roff output. This is the default behavior when no <file>s are given
    and ronn source text is read from standard input.

So probably this is a bug in the ronn processing, and there's also a bug in the ronn.1.ronn doco page which is maybe triggering it. I wonder if that unclosed tag is causing a parsing problem that is causing it to not properly recognize the preceding list as a definition list instead of a bullet list.

Have you observed this issue with other, simpler *.ronn files?

References

We've had some other issues with list rendering in Ronn-NG:

• First paragraph break missing from description list entry in HTML output #74
• Nested lists don't work #16

[apjanke]

Oh, also there's an item in the should-be-a-definition-list-but-rendered-as-a-bullet-list in ronn.1.ronn where the tag/definition-term item is lacking its trailing colon. That could be causing the type of list to be mis-detected, like there's some implicit "all(...)" logic in the list-type detection logic. See the missing trailing ":" in the "port" item here?

  * `-S`, `--server`:
    Don't generate files, start an HTTP server at <http://localhost:1207/> and
    serve dynamically generated HTML for the set of input <file>s. A file named
[...]

  * `--port`=<port>
    When used with `-S`/`--server`, runs the server at the specified port instead
    of the default port 1207.

  * `--pipe`:
    Don't generate files, write generated output to standard output. This is the
    default behavior when ronn source text is piped in on standard input and no
    <file> arguments are provided.

I'm thinking that if this is the problem, the right thing for ronn to do is issue a warning when it has mixed types of list items.

[apjanke]

Adding the missing closing ">" on that encoding item did not fix the list-type rendering. It only fixed the italicization of the "encoding" bit.

Adding the missing trailing ":" on that "port" item does seem to fix the list-type rendering.

Notice that the literal colons in the bullet item texts disappeared too.

This required no code changes in Ronn-NG, just fixes to the bad ronn.1.ronn markup. So that'll fix the formatting of the ronn man page. Change to fix the ronn.1 man page is on branch bug/94_defn-lists-as-bullet-lists, in 9c0ce30 and then a doco regeneration in the next commit. I think I'll roll that in to v0.10.1.

But I think this still calls for a code fix: I think ronn should be emitting a warning or error when it encounters a list with inconsistent bullet/tag/whatever items and there is some ambiguity about which type of list it's supposed to be. Planning that for v0.10.2.

[apjanke]

And I think here's the code problem/cause, in lib/ronn/document.rb around line 408.

    # Convert special format unordered lists to definition lists.
    def html_filter_definition_lists
      # process all unordered lists depth-first
      @html.search('ul').to_a.reverse_each do |ul|
        items = ul.search('li')
        next if items.any? { |item| item.inner_text.strip.split("\n", 2).first !~ /:$/ }

        [... then here's code to transform the `ul` list into a `dl` list ...]

I think that any? in conjunction with the ...first !~ /:$/ means that if any if the items in the list are missing the trailing ":" colon from their first line/tag, then that whole list will be identified as a bullet or regular list, instead of a special definition list.

Now I'm actually a little unsure what to do here. Should ronn issue a warning when there are inconsistent list item types? What if someone wants to make a bullet list where just some of the items' first lines have a trailing literal colon?

I think warning or erroring is still probably the right thing to do here, since the trailing : is special markup in ronn syntax, which means you just can't really have list item introducer lines with trailing colons, unless you want them to be interpreted as definition items.

[apjanke]

I'm downgrading this bug to Low priority, since it's a not-too-large cosmetic issue, and there's a workaround that ronn users can do currently.

[apjanke]

man ronn is looking nicer now for the 0.10.1 release. Thanks, @narc-Ontakac2!