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 are displayed as bullet lists #94

Open
narc-Ontakac2 opened this issue Jan 21, 2023 · 6 comments
Open

Definition lists are displayed as bullet lists #94

narc-Ontakac2 opened this issue Jan 21, 2023 · 6 comments
Assignees
Labels
bug Something isn't working documentation
Milestone

Comments

@narc-Ontakac2
Copy link

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 apjanke self-assigned this Jan 23, 2023
@apjanke
Copy link
Owner

apjanke commented Jan 23, 2023

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.

image

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:

@apjanke apjanke added bug Something isn't working documentation labels Jan 23, 2023
@apjanke apjanke added this to the 0.10.2 milestone Jan 23, 2023
@apjanke
Copy link
Owner

apjanke commented Jan 23, 2023

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 added a commit that referenced this issue Jan 23, 2023
…rendering

Looks like the missing trailing colon (":") on one item in a definition list was causing the whole list to be mis-detected as a bullet list instead. This change fixes the rendering of the ronn.1 man page itself. But I think there should be an additional fix that has ronn issue a warning or error when it encounters a list with inconsistent item types and there's some ambiguity as to what type of list it is.

See: #94
@apjanke
Copy link
Owner

apjanke commented Jan 23, 2023

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

image

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

image

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

apjanke commented Jan 23, 2023

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

apjanke commented Jan 23, 2023

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

apjanke commented Jan 23, 2023

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working documentation
Projects
Status: Low priority
Development

No branches or pull requests

2 participants