From: Jonathan Nieder <jrnieder@gmail.com>
Date: Mon, 14 Oct 2013 14:36:32 GMT
Subject: Re: [PATCH] rev-parse doc: clarify use of optional / required arguments
Message-ID: <20131014143632.GD21200@google.com>
In-Reply-To: <1381760611-9573-1-git-send-email-boklm@mars-attacks.org>

Nicolas Vigier wrote:

> "the option is optional" was confusing as it is not the option but its
> argument which is optional.
>
> Signed-off-by: Nicolas Vigier <boklm@mars-attacks.org>

Thanks.

[...]
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -259,9 +259,10 @@ Each line of options has this format:
[...]
> -	* Use `?` to mean that the option is optional (though its use is discouraged).
> +	* Use `?` if the option takes an optional argument (though its use is
> +	  discouraged).

This still seems confusing: the argument's use is discouraged?

Would something like the following make sense?

	* Use `?` if [...]. This is used for historical options
	  that once took no argument and later gained an optional
	  argument. Use of this feature for new options is
	  discouraged.

Hope that helps,
Jonathan