Re: [PATCH 7/7] git-tag.txt: list all modes in the description

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 14, 2011, 20:03 UTC
Message-ID: <7v8vxis7t1.fsf@alter.siamese.dyndns.org>
In-Reply-To: <496c871d087c0677ddd3374d432e56c891375025.1297695910.git.git@drmicha.warpmail.net>

Michael J Gruber <git@drmicha.warpmail.net> writes:

Show 6 quoted lines

> Currently, the description sounds as if it applied always, but most of
> its content is true in "create tag mode" only.
>
> Make this clearer by listing all modes and qualifying the main part.
>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>

Thanks for noticing; I agree with the basic idea.

Show 8 quoted lines

> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
> index 8b169e3..c503f60 100644
> --- a/Documentation/git-tag.txt
> +++ b/Documentation/git-tag.txt
> @@ -18,7 +18,7 @@ SYNOPSIS
> ...
> -Adds a tag reference in `.git/refs/tags/`.
> +Without `-d/-l/-v`: Adds a tag reference in `.git/refs/tags/`.

But this leaves the reader in suspense what these three exceptions are for after finishing the first sentence. How about rewording like this?

    Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given
    to delete, list or verify.

Then we don't need to repeat these three

    With `-d`: Deletes a tag.

    With `-l`: List tags.

    With `-v`: Verify tags.

that the readers would see in OPTIONS section fairly soon.