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

[Jakub Narebski <jnareb@gmail.com>]

Jari, could you please do not cull Cc list, if possible?  Thanks in
advance.

Jari Aalto <jari.aalto@cante.net> writes:
> 2010-12-01 18:50 Jonathan Nieder <jrnieder@gmail.com>:

> > If the goal is sorted option lists in all manpages, that will _have_
> > to be automated.
> 
> Who is going to write that script? I'm afraid that will never happen.
> 
> It's easier and faster to edit. One page at a time. As time allows.
> Nobody is going take vacation and do it once for all. Bit by bit is
> better approach.

But because some manpages "include" other pages (to refactor common
options), it would be impossible to sort alphabetically options in all
manpages.  So why bother with impossible?  It would only introduce
inconsistency.

> > why would I want sorted option lists in all manpages?
> 
> Does that really need an answer? You read from top to bottom, therefore
> A-Z. Well, GNU uses it in manual pages. 

What do you mean by "GNU" here?

>                                          It looks good, it looks
> professional, it looks clean. And it works when searching (= no
> orientation problems).

It works if you have separate user's documentation from reference
documentation.  GNU projects were meant to have manpages as reference,
and info pages as user's documentation.  Options sorted alphabetically
might make sense for reference documentation.  

But git manpages doesn't serve _only_ as reference documentation.  And
learning commands from manpages where options are sorted alphabetically
instead of grouped together by function *suck* big time.

-- 
Jakub Narebski
Poland
ShadeHawk on #git