Jeff King wrote: > On Mon, Apr 24, 2023 at 05:02:25PM -0700, Junio C Hamano wrote: > > > Felipe Contreras <felipe.contreras@xxxxxxxxx> writes: > > > > > No, it's for the formatting machinery. > > > > > > The fact that both asciidoc and asciidoctor happen to understand our quircky > > > formatting in this particualr situation doesn't mean it isn't quirky. > > > > > > In this particular case the parsers do understand what we are trying to do, > > > because we just just pepper list continuations (`+`) everywhere and it happens > > > to work. > > > > I'll stop at pointing out that the first "no" sounds much stronger > > than the text that tries to substantiate it, which says that the > > machinery works fine without the changes. > > > > > This discrepancy confused Jeff in [1]. > > > > And this is a good reason to add this change for humans. > > Since I'm being used as the example, I'd like to point that I think this > is somewhat tangential to what actually confused me there. > > What confused me in that earlier message was that having "+" as the > continuation between a code-block and its call-out list is odd, since > "+" is about continuing a list item. Indeed. > It happens to work because we're in a larger list item, No, there's only one list item, but yes, it works when the callout is inside one. The `+` is continuing the list item the callout list is part of, it's not part of the callout. > but it breaks when you put the two of them in their own block (which is the > part that got me). You only need to put one, but when you do, the `+` doesn't belong there as it's not part of the callout. > Using just a blank line between the code block and the call-out list > (instead of the "+") works for asciidoc (it is happy to keep the two > together) but not asciidoctor (it ends the outer ordered list before > starting the callout list). I don't know what you mean. These are three paragraphs: foo bar roo These are two paragraphs inside a list item with continuations: 1. foo + bar + roo These are three paragraphs inside a list item with an open block: 1. foo + -- bar roo -- If you are inside an open block, you don't need the list continuations (`+`). Therefore a callout inside an open block inside a list item does not need continuations: 1. foo + -- ---- line 1 <1> line 2 <2> ---- <1> callout 1 <2> callout 2 -- Just like a callout outside a list item: ---- line 1 <1> line 2 <2> ---- <1> callout 1 <2> callout 2 It's only a callout inside a list item with no open block that needs continuations, just like any other paragraph: 1. foo + ---- line 1 <1> line 2 <2> ---- + <1> callout 1 + <2> callout 2 > So the second hunk in the patch, to drop the extra continuation between > the code block and the callout, makes perfect sense to me. > > The first hunk seems less obviously good to me. I don't see why: it's exactly the same change: removing an unnecessary space. Except that space is represented with a `+` inside a list item. > We might say that it is good to always > stick the callout list directly adjacent to the associated code block, > since it does matter in other cases. I'd say that is good. > But dropping the blank lines between the paragraph-sized callout blocks makes > the source less readable, That is a value judgement. It may be less readable to you, I disagree. I would expect the subsequent callout blocks as close to the listing block they refer to as possible. > and empty lines between list elements are a pretty normal thing in asciidoc. Usually, yeah when these list elements are independent, but callout elements are not independent. To me this is perfectly readable: This is a simple example in sh: ---- #!/bin/sh <1> echo 'hello world' <2> ---- <1> Shebang <2> "echo" prints This is a simple example in Ruby: ---- #!/usr/bin/env ruby <1> puts 'hello world' <2> ---- <1> Standard shebang <2> "puts" puts a string Put spaces on the callouts, and it's the exact opposite: This is a simple example in sh: ---- #!/bin/sh <1> echo 'hello world' <2> ---- <1> Shebang <2> "echo" prints This is a simple example in Ruby: ---- #!/usr/bin/env ruby <1> puts 'hello world' <2> ---- <1> Standard shebang <2> "puts" puts a string Cheers. -- Felipe Contreras
