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

From: Jakub Narebski <jnareb@gmail.com>
Date: Dec 2, 2010, 14:23 UTC
Message-ID: <m3wrns2r2d.fsf@localhost.localdomain>
In-Reply-To: <87fwugs7pf.fsf@picasso.cante.net>

Please do not cull Cc-list, i.e. respond replying to all people who participate in given (sub)thread. (If it is not possible, tell why).

Jari Aalto <jari.aalto@cante.net> writes:

Show 13 quoted lines

> 2010-12-02 10:53 Jan Krüger <jk@jk.gs>:
> > [Cc un-culled]
> >
> > --- Jari Aalto <jari.aalto@cante.net> wrote:
> >
> > > The reader have to guess "imagined groups"? Hm, that's interesting.
> >
> > Perhaps a more desirable (and agreeable) patch would introduce group
> > subheadings, then?
> 
> Yes, that's the standard way of doing groups. Just like it's being done
> in other manual pages that are huge. But it is not being done in small
> manual pages. GNU project certainly doesn't in general.

Note that GNU project produced many more or less stupid/smart conventions. It doesn't mean that we should follow them blindly (alphabetical sorting of options in manpages, GNU ChangeLog format, GNU indent style for C).

> 
> I agree that doing "groups" makes only sense on pages that have large
> number of options. For a screenful, it's more distracting than worth.

The other side of the fact that creating subsections grouping types of options makes only sense for pages/groups that have large number of options is that we need sorting by function, grouping related options together. See also use case below.

Show 5 quoted lines

> > In rev-list-related options we already have a couple of explicit
> > groups.
> 
> I can't find that manual page or file under Documentation/, could you
> help here?

"man git-rev-list", Documentation/rev-list-options.txt
 
[...]

> Well. In my experience (having watched others to learn) the manual pages
> are not the source used for learning.

Counterexample: Perl.

Show 10 quoted lines

> People go to the manual pages once they have a specific need for
> infomation and details. I could sketch these uses of manual pages:
> 
>     - Someone throws up a git command (IRC #git, Blogs, Web page). What
>       do all those unreadable one letter options mean? Gosh they don't
>       even mean the same accross different git* programs.
> 
>       > He searches manual pages A-Z, easy to spot all options. Not
>       > interested in related things. He tries to understand the
>       > command, script etc.

Contrived use case.  Disregarded.

Show 5 quoted lines

> 
>     - Someone is learning Git.
> 
>       > He certainly does not start from manual pages. Other soources of
>       > information are more in to him. Besides  Windows does not have those.

Did you check that 'man git-<cmd>' doesn't work on git on MS Windows (msysGit, git from Cygwin)?

You can always use 'git --help <cmd>'.

Show 5 quoted lines

>       > We might guess what MySGIt as other do: they reach Google button.
> 
>       This person just wants to solve a problem, get things done, the
>       faster the better. The easier the better, the less thinking the
>       better.

They read "Git User's Manual", or "Pro Git", or perhaps "Git Community Book" (the first included with git, the second and third available on-line).

Show 5 quoted lines

> 
>     - Geek. He wants to learn inside out.
> 
>       > He digests all. Related options, related pages, flipping
>       > form man to man as he knows all the glory details is just there.

And for geek grouping related options/config variables together is helpful.

You omitted very important use case, something that was mentioned more than once in this and related threads:

      - Someone wants to know/remember how to do something in Git.
        Assume that this someone knows git quite well, but not by heart.

      Here there is example that was give to you in this thread (or
      related subthread), namely someone checking the name of option that
      ignores whitespace, and because related options are grouped together
      the he/she realizes that he/she wants different but related option
      (-b/--ignore-space-change vs -w/--ignore-all-space).

      Another example could be someone searching for config options that
      affect git (re)packing performance.  Currently those config options
      are grouped together.

      If options are sorted alphabetically this task is made much harder.
      Note that he/she know how to use searching in pager or web browser.

Show 10 quoted lines

> It all depends if it is desireable to make pages more approachable to
> the average group, or are they kept to serve only small core audience.
> 
> There are 100+ manual pages in the git distribution. You get even
> disoriented in sheer numbers of them. And you have to throw dice to
> figure out in what page that information might be you are currently in
> need.
> 
> It's classical case of how to arrange information for easy retrieval.
> Think Libraries as model.

Computerized index, or manual? Perhaps it is classical case, but it is outdated: modern solutions use folksonomies / labels / tagging rather than Trove / Dewey classification or alphabetical sorting.

-- 
Jakub Narebski
Poland
ShadeHawk on #git