Re: [PATCH v2 2/5] pretty format %(trailers) doc: avoid repetition
On Sun, Dec 6, 2020 at 1:25 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
Show 9 quoted lines
>
> 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. Let's try to make this more explicit, and upper-case "BOOL"
> for consistency with the existing "<SEP>" and "<K>".
... but not sure it's worth repeating that we upper-case "BOOL".
Show 22 quoted lines
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/pretty-formats.txt | 30 ++++++++++++++++--------------
> 1 file changed, 16 insertions(+), 14 deletions(-)
>
> diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
> index 84bbc7439a6..66dfa122361 100644
> --- a/Documentation/pretty-formats.txt
> +++ b/Documentation/pretty-formats.txt
> @@ -252,7 +252,15 @@ endif::git-rev-list[]
> interpreted by
> linkgit:git-interpret-trailers[1]. The
> `trailers` string may be followed by a colon
> - and zero or more comma-separated options:
> + and zero or more comma-separated options.
> + If any option is provided multiple times the
> + last occurance wins.
> ++
> +The boolean options accept an optional value `[=<BOOL>]`. The values
> +`true`, `false`, `on`, `off` etc. are all accepted. See the "boolean"
> +sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean
> +option is given with no value, it's enabled.
> +** 'only[=BOOL]': select whether non-trailer lines from the trailer
Here it's "[=BOOL]" while above it's "[=<BOOL>]"
> +** 'unfold[=BOOL]': make it behave as if interpret-trailer's `--unfold`
> +** 'valueonly[=BOOL]': skip over the key part of the trailer line and only
> + show the value part.
Christian Couder <christian.couder@gmail.com>