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

From: Jakub Narebski <jnareb@gmail.com>
Date: Dec 1, 2010, 17:48 UTC
Message-ID: <m362vd4c6h.fsf@localhost.localdomain>
In-Reply-To: <87r5e1v2g8.fsf@picasso.cante.net>

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>:

Show 8 quoted lines

> > 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