| Message ID | 20190422151541.GA1633@sigill.intra.peff.net (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | doc/ls-files: put nested list for "-t" option into block | expand |
Jeff King <peff@peff.net> writes: > 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). OK, thanks. > 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). Yup, I was looking at builtin/ls-files.c before sending the Makefile patch, too ;-) > Documentation/git-ls-files.txt | 2 ++ > 1 file changed, 2 insertions(+) > > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt > index 5298f1bc30..8461c0e83e 100644 > --- a/Documentation/git-ls-files.txt > +++ b/Documentation/git-ls-files.txt > @@ -118,6 +118,7 @@ OPTIONS > linkgit:git-status[1] `--short` or linkgit:git-diff[1] > `--name-status` for more user-friendly alternatives. > + > +-- > This option identifies the file status with the following tags (followed by > a space) at the start of each line: > > @@ -128,6 +129,7 @@ a space) at the start of each line: > C:: modified/changed > K:: to be killed > ?:: other > +-- > > -v:: > Similar to `-t`, but use lowercase letters for files
Hi, 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 > etc... > > but asciidoc also treats that as one big list. So this problem seems to > have been around forever. > > Signed-off-by: Jeff King <peff@peff.net> > --- > 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.
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 5298f1bc30..8461c0e83e 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -118,6 +118,7 @@ OPTIONS linkgit:git-status[1] `--short` or linkgit:git-diff[1] `--name-status` for more user-friendly alternatives. + +-- This option identifies the file status with the following tags (followed by a space) at the start of each line: @@ -128,6 +129,7 @@ a space) at the start of each line: C:: modified/changed K:: to be killed ?:: other +-- -v:: Similar to `-t`, but use lowercase letters for files
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 etc... but asciidoc also treats that as one big list. So this problem seems to have been around forever. Signed-off-by: Jeff King <peff@peff.net> --- 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. :) Documentation/git-ls-files.txt | 2 ++ 1 file changed, 2 insertions(+)