pretty format %(trailers) doc: avoid repetition
Change the documentation for the various %(trailers) options so it isn't repeating part of the documentation for "only" about how boolean values are handled. Instead, let's split the description of that into general documentation at the top. It then suffices to refer to it by listing the options as "opt[=<BOOL>]". I'm also changing it to upper-case "[=<BOOL>]" from "[=val]" for consistency with "<SEP>" It took me a couple of readings to realize that these options were referring back to the "only" option's treatment of boolean values. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Dec 9, 2020 at 16:52 UTC
2762e17117fdd7ab73eb3f2970620a6f91500d01
1 file changed
+16
-14
Documentation/pretty-formats.txt
+16
-14
@@ -252,7 +252,15 @@ endif::git-rev-list[]
252
interpreted by
253
linkgit:git-interpret-trailers[1]. The
254
`trailers` string may be followed by a colon
255
- and zero or more comma-separated options:
255
+ and zero or more comma-separated options.
256
+ If any option is provided multiple times the
257
+ last occurance wins.
258
++
259
+The boolean options accept an optional value `[=<BOOL>]`. The values
260
+`true`, `false`, `on`, `off` etc. are all accepted. See the "boolean"
261
+sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean
262
+option is given with no value, it's enabled.
263
++
264
** 'key=<K>': only show trailers with specified key. Matching is done
265
case-insensitively and trailing colon is optional. If option is
266
given multiple times trailer lines matching any of the keys are
@@ -261,27 +269,21 @@ endif::git-rev-list[]
269
desired it can be disabled with `only=false`. E.g.,
270
`%(trailers:key=Reviewed-by)` shows trailer lines with key
271
`Reviewed-by`.
264
-** 'only[=val]': select whether non-trailer lines from the trailer
265
- block should be included. The `only` keyword may optionally be
266
- followed by an equal sign and one of `true`, `on`, `yes` to omit or
267
- `false`, `off`, `no` to show the non-trailer lines. If option is
268
- given without value it is enabled. If given multiple times the last
269
- value is used.
272
+** 'only[=<BOOL>]': select whether non-trailer lines from the trailer
273
+ block should be included.
274
** 'separator=<SEP>': specify a separator inserted between trailer
275
lines. When this option is not given each trailer line is
276
terminated with a line feed character. The string SEP may contain
277
the literal formatting codes described above. To use comma as
278
separator one must use `%x2C` as it would otherwise be parsed as
275
- next option. If separator option is given multiple times only the
276
- last one is used. E.g., `%(trailers:key=Ticket,separator=%x2C )`
279
+ next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`
280
shows all trailer lines whose key is "Ticket" separated by a comma
281
and a space.
279
-** 'unfold[=val]': make it behave as if interpret-trailer's `--unfold`
280
- option was given. In same way as to for `only` it can be followed
281
- by an equal sign and explicit value. E.g.,
282
+** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold`
283
+ option was given. E.g.,
284
`%(trailers:only,unfold=true)` unfolds and shows all trailer lines.
283
-** 'valueonly[=val]': skip over the key part of the trailer line and only
284
- show the value part. Also this optionally allows explicit value.
285
+** 'valueonly[=<BOOL>]': skip over the key part of the trailer line and only
286
+ show the value part.
287
288
NOTE: Some placeholders may depend on other options given to the
289
revision traversal engine. For example, the `%g*` reflog options will