You may want to invest in a spell-checker. On Dec 1, 2010, at 2:35 PM, Jari Aalto wrote: >> 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! > 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-- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html