Re: [PATCH] doc/cat-file: allow --use-mailmap for --batch options

[Christian Couder <christian.couder@gmail.com>]

On Fri, Sep 23, 2022 at 9:36 PM Siddharth Asthana
<siddharthasthana31@gmail.com> wrote:
>
> The command git cat-file can now use the mailmap mechanism to replace
> idents with their canonical versions for commit and tag objects. There
> are several options like `--batch`, `--batch-check` and
> `--batch-command` that can be combined with `--use-mailmap`. But, the
> documentation for `--batch`, `--batch-check` and `--batch-command`
> doesn't say so. This patch fixes that documentation.
>
> Mentored-by: Christian Couder's avatarChristian Couder <christian.couder@gmail.com>
> Mentored-by: John Cai's avatarJohn Cai <johncai86@gmail.com>

As you told me separately, you should remove "Christian Couder's
avatar" and "John Cai's avatar" from the above trailers.

> Signed-off-by: Siddharth Asthana <siddharthasthana31@gmail.com>
> ---

Here after the line that contains only '---' and before the short
stats below, you could write some small explanations about where this
patch comes from.

For example you could say that it was previously sent as the first
patch of a a 3 patch series:

https://lore.kernel.org/git/20220916205946.178925-2-siddharthasthana31@gmail.com/

And you could tell what changes you made compared to the previous patch.

>  Documentation/git-cat-file.txt | 44 ++++++++++++++++++++++++----------
>  1 file changed, 31 insertions(+), 13 deletions(-)
>
> diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
> index ec30b5c574..3fdafc07ce 100644
> --- a/Documentation/git-cat-file.txt
> +++ b/Documentation/git-cat-file.txt
> @@ -89,26 +89,44 @@ OPTIONS
>  --batch::
>  --batch=<format>::
>         Print object information and contents for each object provided
> -       on stdin.  May not be combined with any other options or arguments
> -       except `--textconv` or `--filters`, in which case the input lines
> -       also need to specify the path, separated by whitespace.  See the
> -       section `BATCH OUTPUT` below for details.
> +       on stdin.
> +
> +       * When used with `--textconv` or `--filters`, the input lines
> +         must specify the path, separated by whitespace. See the section
> +         `BATCH OUTPUT` below for details.
> +
> +       * When used with `--use-mailmap`, the info command shows the size
> +         the object, if the idents recorded in it were the ones "corrected"
> +         by the mailmap mechanism.
> +         Cannot be used with any other options.

Have you checked the result of `git help cat-file` after `make instll-doc`?

Shouldn't you use something like the following instead for additional
paragraphs inside some indented text:

+
* When used with `--textconv` or `--filters`, the input lines
must specify the path, separated by whitespace. See the section
`BATCH OUTPUT` below for details.
+

?

(Note that the + signs in what I suggest above should be actually
added to the file and aren't what a diff displays in front of new
lines.)

Also it's not very clear if "Cannot be used with any other options."
is part of the last "* When ..." paragraph or not.