[PATCH v2] Re: add documentation for mailinfo.scissors and '--no-scissors'

From: Nicolas Sebrecht <nicolas.s.dev@gmx.fr>
To: Junio C Hamano <gitster@pobox.com>
Cc: Nicolas Sebrecht <nicolas.s.dev@gmx.fr>,
	Nanako Shiraishi <nanako3@lavabit.com>,
	git@vger.kernel.org, Pierre Habouzit <madcoder@debian.org>
Subject: [PATCH v2] Re: add documentation for mailinfo.scissors and '--no-scissors'
Date: Sat, 12 Sep 2009 05:03:51 +0200	[thread overview]
Message-ID: <20090912030351.GC18684@vidovic> (raw)
In-Reply-To: <7v8wglw60x.fsf@alter.siamese.dyndns.org>

[ Thank you (again) for this very good explanation. ]

The 11/09/09, Junio C Hamano wrote:
> Nicolas Sebrecht <nicolas.s.dev@gmx.fr> writes:
> 
> > Ok. So, the fact that the usage of git-am doesn't tell about
> > --no-scissors is the expected behaviour?
> 
> You _could_ argue that we _could_ describe a long option "frotz" that
> lacks the '!' flag in OPTIONS_SPEC as "--[no-]frotz" in the output by
> changing the rev-parse --parseopt, if you really want to.
> 
> However, I think that is not done deliberately to avoid cluttering the
> output.  I Cc'ed the primary guilty party ;-) of the parse-options
> infrastructure.

Well, if it is expected to not have the "--[no-]frotz" in usage where
applicable I'll be fine with that (even if it may sounds a bit odd for a
sane user). Otherwise, I believe it could be a (small) improvement for
the UI.

> Currently, non-bool options are not marked with '!'.  Nobody sane would
> say "git am --no-directory foo", but "rev-parse --parseopt" acccepts such
> a nonsense input, and it is up to the calling script to catch it and barf.
> But "rev-parse --parseopt" will start saying "--[no-]directory=" with such
> a change, which is not good.
> 
> And --no-scissors is not that special.  We could add --no-signoff to say
> "I do not want to sign-off this one time" explicitly, and it is crazy if
> we had to add another line in OPTIONS_SPEC when we want to do so, when it
> is clear "signoff" option is a boolean.
> 
> As a long term direction, I'd rather not to see "no-" in OPTIONS_SPEC, but
> have that taken care of by "rev-parse --parseopt" to keep our sanity.  The
> only existing offender is "no-verify" in "rebase -i".  Let's solve it (if
> there is anything to solve, which I doubt) without adding new ones.

Now (with all this background in mind), I agree that the "no-" in
OPTIONS_SPEC looks ugly.

<If there were something to change>

As you say, we can't blindly rely on the "is a boolean" and "option name
begin with 'no-'" things altogether. Perhaps a new magic character
('-'?) beside the current flags of PARSEOPT could smartly do the trick?

</>

Pierre, opinion?

-- 
Nicolas Sebrecht