Re: [PATCH v1 1/2] Documentation/rev-list-options: wrap --date=<format> block with "--"

From: Todd Zullinger <tmz@pobox.com>
Date: Apr 5, 2019, 01:20 UTC
Message-ID: <20190405012002.GO4047@pobox.com>
In-Reply-To: <20190401130804.GA11664@sigill.intra.peff.net>

Hi,

Jeff King wrote:

Show 14 quoted lines

> On Sat, Mar 30, 2019 at 02:30:00PM -0400, Todd Zullinger wrote:
> 
>> Using "+" to continue multiple list items is more tedious and
>> error-prone than wrapping the entire block with "--" block markers.
>> 
>> When using asciidoctor, the list items after the --date=iso list items
>> are incorrectly formatted when using "+" continuation.  Use "--" block
>> markers to correctly format the block.
>> 
>> When using asciidoc there is no change in how the content is rendered.
> 
> This seems like an asciidoctor bug, though I think this kind of
> list-within-a-list stuff is inherently a bit heuristic-driven just due
> to the syntax.

Indeed. There's certainly a limit to the changes we want to make solely to work-around issues in either asciidoc or asciidoctor. When the work-around is (at least arguably) an improvement, then it's probably worthwhile. That's how I thought about it, anyway. :)

Show 5 quoted lines

> I do agree that the result after your patch is more readable, so I think
> I prefer it even if the asciidoctor bug were fixed. I suspect we could
> be using "--" blocks for readability in more places (I don't think it's
> worth going on a hunt to convert old spots, but something to keep in
> mind as we write new documentation).

Agreed, that sounds perfectly reasonable to me. The Asciidoctor user manual says:

    If you’re attaching more than one block to a list item,
    you’re strongly encouraged to wrap the content inside an
    open block. That way, you only need a single list
    continuation line to attach the open block to the list
    item. Within the open block, you write like you normally
    would, no longer having to worry about adding list
    continuations between the blocks to keep them attached
    to the list item.

https://asciidoctor.org/docs/user-manual/#list-continuation

I imagine it's "strongly encouraged" both to help consumers avoid these sort of oddly-parsed continuation issues, as well as the Asciidoctor devs from having to field as many bug reports.

-- 
Todd