Re: [PATCH] doc/ls-files: put nested list for "-t" option into block
- Date: Tue, 23 Apr 2019 22:03:13 -0400
- From: Todd Zullinger <tmz@xxxxxxxxx>
- Subject: Re: [PATCH] doc/ls-files: put nested list for "-t" option into block
Jeff King wrote:
> The description for the "-t" option contains a sub-list of all of the
> possible file status outputs. But because of the newline separating that
> list from the description paragraph, asciidoc treats the sub-list
> entries as a continuation of the overall options list, rather than as
> children of the "-t" description.
> We could fix it by adding a "+" before the sub-list to connect it to the
> rest of the "-t" text. But using a pair of "--" to delimit the block is
> perhaps more readable, and may have better compatibility with
> asciidoctor, as in 39a869b2f2 (Documentation/rev-list-options: wrap
> --date=<format> block with "--", 2019-03-30).
> The extra blank line comes from 5bc0e247c4 (Document ls-files -t as
> semi-obsolete., 2010-07-28), but the problem actually seems older than
> that. Before then, we did:
> -t:: some text...
> H:: cached
> M:: unmerged
> but asciidoc also treats that as one big list. So this problem seems to
> have been around forever.
> Signed-off-by: Jeff King <peff@xxxxxxxx>
> Junio: I happened to notice this while hunting for "ls-files" options
> that could make your makefile de-dup patch unnecessary (but
> didn't find anything).
> Todd: Just an FYI that your "--" strategy is spreading. :)
Heh, cool. This is an obviously simple fix, but for good
measure I checked the results with asciidoc 8.6.10 as well
as asciidoctor 1.5.6 and 2.0.8. The output from each of
them looks good.