threads / patch / 50969

patchdoc/ls-files: put nested list for "-t" option into block

Subject: [PATCH] doc/ls-files: put nested list for "-t" option into block

## tl;dr

3 messages between Apr 22, 2019 and Apr 24, 2019. Diffs are folded; open one to read it.

replies: 2people: 3as markdown or json

Jeff King· Apr 22, 2019, 15:15 UTC · lore

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(+)
Show changes to Documentation/git-ls-files.txt +2 −0
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
-- 
2.21.0.1180.g837af34674
Junio C Hamano· Apr 23, 2019, 01:24 UTC · re: Jeff King · lore

Re: [PATCH] doc/ls-files: put nested list for "-t" option into block

Jeff King <peff@peff.net> writes:
Show 5 quoted lines
> 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 ;-)

Show 23 quoted lines
>  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
Todd Zullinger· Apr 24, 2019, 02:03 UTC · re: Jeff King · lore

Re: [PATCH] doc/ls-files: put nested list for "-t" option into block

Hi,
Jeff King wrote:
Show 31 quoted lines
> 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.

-- 
Todd

← back to recent threads