From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 12 Apr 2010 16:45:42 GMT
Subject: Re: [PATCH] Docs: Add -X option to git-merge's synopsis.
Message-ID: <7v39z0livd.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1271089693-21365-1-git-send-email-marcnarc@xiplink.com>

Marc Branchaud <marcnarc@xiplink.com> writes:

> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index 9c9618c..ceec787 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -9,7 +9,8 @@ git-merge - Join two or more development histories together
>  SYNOPSIS
>  --------
>  [verse]
> -'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
> +'git merge' [-n] [--stat] [--no-commit] [--squash]...
> +	[-s <strategy>] [-X <strategy-option>]...
>  	[--[no-]rerere-autoupdate] [-m <msg>] <commit>...
>  'git merge' <msg> HEAD <commit>...

Good.

> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
> index 37ce9a1..722d704 100644
> --- a/Documentation/merge-options.txt
> +++ b/Documentation/merge-options.txt
> @@ -62,6 +62,11 @@ option can be used to override --squash.
>  	is used instead ('git merge-recursive' when merging a single
>  	head, 'git merge-octopus' otherwise).
>  
> +-X <option>::
> +--strategy-option=<option>::
> +	Pass merge strategy specific option through to the merge
> +	strategy.
> +
>  --summary::
>  --no-summary::
>  	Synonyms to --stat and --no-stat; these are deprecated and will be
> @@ -76,8 +81,3 @@ ifndef::git-pull[]
>  --verbose::
>  	Be verbose.
>  endif::git-pull[]
> -
> --X <option>::
> ---strategy-option=<option>::
> -	Pass merge strategy specific option through to the merge
> -	strategy.
> -- 

This is somewhat imcomplete; the current merge-options.txt seems to be
organized more-or-less alphabetically (begins with "commit", ascends to
"ff", "log", "s-something", and ends with "X"), but it has acquired
additions at random places (e.g. "ff-only").

I do not think reorganizing the option descriptions in functional groups
is a bad idea, and if we make that an overall goal of our documentation
set, the patch is certainly going in the right direction.

I used to prefer alphabetical order slightly over functional grouping
because it would make things easier to find in printed pages, but these
days people read on paper a lot less often, so I am personally fine with
"do not list options in alphabetical order; group them with related
features, and do so consistently across all manual pages".

So I'll take the patch as is, but before going further I would like to
first see list concensus to such a reorganization.

Thanks.