Re: [PATCH] rev-parse doc: clarify use of optional / required arguments

From

Jonathan Nieder <jrnieder@gmail.com>

Date

Oct 14, 2013, 14:36 UTC

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.