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

[Todd Zullinger <tmz@pobox.com>]

Hi,

Jeff King wrote:
> 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. :)

> 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