no paragraph tags when list is tight

[KristofferC]

This and JuliaDocs/Documenter.jl#493 should fix #21922

I interpret CommonMarks:

(The difference in HTML output is that paragraphs in a loose list are wrapped in

tags, while paragraphs in a tight list are not.)

as that it is the rendering of the paragraphs that should be changed based on the context (in a tight list or not). Easiest way to get that context to the Paragraph-writer was through an extra field.

[mortenpi]

The writers should always be able to check its parent item as well, so it could be a part of the List (e.g. as in Documenter). My objection to having this be a part of Paragraph is that the following:

x = List(items=[Paragraph(x), ...])
y = MD(); push!(y.content, x.items[1])

should "just work" and y render correctly, even if x is a tight list. In an MD the .intightlist has no meaning.

In Documenter we could have a separate mdconvert(paragraph::Markdown.Paragraph, parent::Markdown.List) = ... method to render it if need be, although it feels like it should be possible to have it all in mdconvert(::List, ...).

[KristofferC]

Okay, yeah I'm making design decisions here based on insufficient knowledge about Markdown in general and the implementation. I just want to get the issue fixed and hammering until I get the output I want :P. One of the problems is that there are two writers (one in Base and one in Documenter) and the data structure has to satisfy both.

In Documenter the function mdconvert takes a parent but in Julia it is just e.g. html(io::IO, md::Paragraph) i.e. no parent to look at. I could make istight a property of the List and have mdconvert for Paragraph in Documenter look at it, but Base will then keep inserting <p> then. Perhaps that is ok?

[mortenpi]

Well, I think the easiest thing would be to simply update the writers everywhere. 😄 We probably can't get around that -- I have the impression that currently everything basically assumes loose lists.

Could you say what you envision the structure of the Markdown.List objects should be for a set of example lists? I think that should be decided first and then the writers written for that. So, for example, the following lists:

- a _emph_
- b _emph_

- a _emph_

- b _emph_

* a _emph_

  b _emph_
* c _emph_

[mortenpi]

Side note: I'm familiar with the writer code in Documenter, but I have only given a cursory glance at the code in Base. That's kind of why I'm "appealing to higher ideals", rather than proposing code. It would actually be great to document / spec out all the objects in Base.Markdown, so that it would be clear how they should be used and what the writers can assume about them

[KristofferC]

Updated to let writers take a parent and have the loose field inside the list which the Paragraph looks at. Also updated the Documenter PR at JuliaDocs/Documenter.jl#493

[StefanKarpinski]

Just loose since it's a property and not a predicate function?

[KristofferC]

Bump, what can I do here? I find the large distance between the list items somewhat of a fork in my eye...

[mortenpi]

Any objections to removing the Markdown.Paragraph "wrappers" though? It could (should?) be the writer of the List that decides whether a <p> tag gets written or not (based on the .loose flag), no? The Markdown.List object for both the tight and loose version of

- a
- b

looks like this (numbers enumerate the .items vector):

Markdown.MD(
  [
    Markdown.List(ordered = -1, loose = ...,
      1 => [
        Markdown.Paragraph(
          [
            "a",
          ]
        ),
      ]
      2 => [
        Markdown.Paragraph(
          [
            "b",
          ]
        ),
      ]
    ),
  ]
)

The Paragraphs don't seem to add anything to this tree.

[mortenpi]

Should we try to get this in before 0.6 by the way to make sure the lists display nicely in the docs? Would this type of change even be accepted for 0.6 backporting at this stage?

[KristofferC]

I tried my best to get it working with the approach you suggested and it was pretty easy to fix the html writer. The other ones where more annoying though and I couldn't afford to spend more time on it. Having the extra field in the paragraph and leave all the writers in Base as is would not change any functionality but at least provide an rescale hatch just for Documenter.jl. I'll try upload what I had as a WIP.