Re: [PATCH] git-commit.txt: Order options alphabetically

From: Kevin Ballard <kevin@sb.org>
Date: Dec 1, 2010, 22:49 UTC
Message-ID: <2C3777CB-2DDD-4FF5-842B-23F7EF838611@sb.org>
In-Reply-To: <87r5e1t93o.fsf@picasso.cante.net>

You may want to invest in a spell-checker.

On Dec 1, 2010, at 2:35 PM, Jari Aalto wrote:

Show 6 quoted lines

>> the documentation is often more useful if the options are
>> grouped together by features and concepts they relate to.
> 
> Where do you see grouping all the sudden? Manaula pages are not
> primarily used to learn things, they are used as reference. Just like
> Book indexes.

Most certainly they are used to learn things. Especially with tools like git. Don't know what options you can give to git-diff? Read the manpage!

Show 5 quoted lines

> I haven't seed anyone for 10's of years who would have read full manaul
> page from top to botton; every single line at one stop.
> 
> They come and go, come and go to read it. Learn bit by bit. And there is
> the strenght od proper indexing, the alphabetical.

Indexing, sure, but the actual manpage is not an index. A-Z ordering makes no sense for the manpage. When people read, chunk by chunk, they expect related functionality. It especially helps with discoverability. For example, I know of the -w flag to git-diff that tells it to ignore whitespace. I'm not certain this does exactly what I want, so I pop open the manpage, search for -w, and read it. And I'm right, it doesn't do what I want. But right next to it is the flag -b, and that _does_ do precisely what I want. If the manpage was ordered alphabetically, I'd likely have never found the -b flag. As it is, all 3 whitespace-related flags to git-diff are grouped together, and it helps not only with reading the manpage for the first time (as I learn all related concepts at the same time), but with discovering the related flags when I go back to read documentation on the flags I already know.

-Kevin Ballard