@matheusbsbs / matheus-bagliano / commits / 8534bb4cb1

git-cat-file.txt: fix list continuations rendering literally

With Asciidoctor, all of the '+' introduced in a797c0ea04 ("cat-file: add mailmap support to --batch-check option", 2022-12-20) render literally rather than functioning as list continuations. With asciidoc, this renders just fine. It's not too surprising that there is room for ambiguity and surprises here, since we have lists within lists. Simply replacing all of these '+' with empty lines makes this render fine using both tools. Except, in the third hunk, where after this inner '*' list ends, we want to continue with more contents of the outer list item (`--batch-command=<format>`). We can solve any ambiguity here and make this clear to both tools by wrapping the inner list in an open block (using "--"). For consistency, let's wrap all three of these inner lists from a797c0ea04 in open blocks. This also future-proofs us a little -- if we ever gain more contents after any of those first two lists, as we did already in a797c0ea04 for the third list, we're prepared and should render fine with both asciidoc and Asciidoctor from the start. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Martin Ågren committed Jan 18, 2023 at 09:27 UTC 8534bb4cb1329612bb749dcb7a6f27181d3becbd
1 file changed +12 -7
Documentation/git-cat-file.txt
+12 -7
@@ -93,47 +93,52 @@ OPTIONS
93 Print object information and contents for each object provided
94 on stdin. May not be combined with any other options or arguments
95 except `--textconv`, `--filters`, or `--use-mailmap`.
96 - +
96 ++
97 +--
98 * When used with `--textconv` or `--filters`, the input lines
99 must specify the path, separated by whitespace. See the section
100 `BATCH OUTPUT` below for details.
100 - +
101 +
102 * When used with `--use-mailmap`, for commit and tag objects, the
103 contents part of the output shows the identities replaced using the
104 mailmap mechanism, while the information part of the output shows
105 the size of the object as if it actually recorded the replacement
106 identities.
107 +--
108
109 --batch-check::
110 --batch-check=<format>::
111 Print object information for each object provided on stdin. May not be
112 combined with any other options or arguments except `--textconv`, `--filters`
113 or `--use-mailmap`.
112 - +
114 ++
115 +--
116 * When used with `--textconv` or `--filters`, the input lines must
117 specify the path, separated by whitespace. See the section
118 `BATCH OUTPUT` below for details.
116 - +
119 +
120 * When used with `--use-mailmap`, for commit and tag objects, the
121 printed object information shows the size of the object as if the
122 identities recorded in it were replaced by the mailmap mechanism.
123 +--
124
125 --batch-command::
126 --batch-command=<format>::
127 Enter a command mode that reads commands and arguments from stdin. May
128 only be combined with `--buffer`, `--textconv`, `--use-mailmap` or
129 `--filters`.
126 - +
130 ++
131 +--
132 * When used with `--textconv` or `--filters`, the input lines must
133 specify the path, separated by whitespace. See the section
134 `BATCH OUTPUT` below for details.
130 - +
135 +
136 * When used with `--use-mailmap`, for commit and tag objects, the
137 `contents` command shows the identities replaced using the
138 mailmap mechanism, while the `info` command shows the size
139 of the object as if it actually recorded the replacement
140 identities.
136 -
141 +--
142 +
143 `--batch-command` recognizes the following commands:
144 +