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@xxxxxxxxx> writes:
> 2010-12-02 10:53 Jan Krüger <jk@xxxxx>:
> > [Cc un-culled]
> >
> > --- Jari Aalto <jari.aalto@xxxxxxxxx> 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.
> > 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.
> 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.
>
> - 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>'.
> > 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).
>
> - 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.
> 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
--
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