Re: [PATCH] Docs: Add -X option to git-merge's synopsis.

[Marc Branchaud <marcnarc@xiplink.com>]

Junio C Hamano wrote:
> 
> 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.

I noticed the alphabetical sorting when I made the patch, so I guess my
opinion on functional grouping is pretty obvious.  FWIW, I find functional
groupings make it easier to find unknown options.  An alphabetical sorting is
really only helpful if you already know what you're looking for.  And in that
case, like you say, these docs are usually read in an electronic form, where
it's easy enough to just do a search for whatever's desired.

In any case, regardless of the consensus on this issue, alphabetical sorting
doesn't seem to make much sense for merge-options.txt given the way it's
included in git-merge.txt and git-pull.txt.

		M.