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

[Jakub Narebski <jnareb@gmail.com>]

Jari Aalto <jari.aalto@cante.net> writes:
> 2010-12-01 19:48 Jakub Narebski <jnareb@gmail.com>:
> > > 2010-12-01 18:50 Jonathan Nieder <jrnieder@gmail.com>:
> >
> > 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.
> 
> Decreasing entropy is better goal even if we cannot make it perfect. We
> do what we can. And there are many pages that don't use include.

Increasing inconsistency is not good, and that would be the final side
effect.
 
> I don't mind work. You just watch and lean back.

But we do mind unnecessary code churn (well, in this case documentation
churn).  Unless you regard it as "academical" exercise.
 
The final decision on merging in (accepting) changes lies at git
maintainer.

> > > 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.
> 
> It makes sense regardless. Printing literature and how people read and
> search information hasn't changed since printing was invented.

How people search information *has* changed since printing was invented.

> > 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.
> 
> Nope. Manual pages are not where people learn things any more. They
> Google. They buy books. They copy from fellow worker.
> 
> The manual pages main use it as reference material. We don't need to
> fight the obvious.

Counterexample: Perl manpages.

-- 
Jakub Narebski
Poland
ShadeHawk on #git