patchgit-commit.txt: Order options alphabetically

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

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-commit.txt |  220 +++++++++++++++++++++---------------------
 1 files changed, 110 insertions(+), 110 deletions(-)

Hi again,

jari.aalto@cante.net wrote:

Here's what Documentation/SubmittingPatches has to say.

	[...] patches which plainly describe the things that
	help reviewers check the patch, and future maintainers understand
	the code, are the most beautiful patches.  Descriptions that summarise
	the point in the subject well, and describe the motivation for the
	change, the approach taken by the change, and if relevant how this
	differs substantially from the prior version, can be found on Usenet
	archives back into the late 80's.  Consider it like good Netiquette,
	but for code.

Here, you've explained what the patch does, but not why. How are reviewers to evaluate whether it succeeded?

If the goal is sorted option lists in all manpages, that will _have_ to be automated. Some manpages read some and not all of their options from an external file. But before we deal with that: why would I want sorted option lists in all manpages?

Sorting can sometimes be an improvement; it just seems better to mention the particulars of the situation and why sorting rather than some thematic grouping is appropriate in a given case.

Hope that helps, Jonathan

2010-12-01 18:50 Jonathan Nieder <jrnieder@gmail.com>:

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.

Does that really need an answer? You read from top to bottom, therefore A-Z. Well, GNU uses it in manula pages. It looks good, it looks professional, it looks clean. And it works when searching (= no oriantation problems).

Jari

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

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

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.

What do you mean by "GNU" here?

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.

2010-12-01 19:48 Jakub Narebski <jnareb@gmail.com>:

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

I don't mind work. You just watch and lean back.

It makes sense regardless. Printing literature and how people read and search information hasn't chnage since printing was invented.

Nope. Manual pages are not where people learn things any more. They Google. They buy books. Teh copy from fellow worker.

The manual pages main use it as reference material. We don't need to fight the obvious.

Jari

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

Increasing inconsistency is not good, and that would be the final side
effect.
 

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.

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

Counterexample: Perl manpages.

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

Yes.

I used to think that back when I referred to printed documentation more often than online, but not anymore. Alphabetical ordering is somewhat last century; the documentation is often more useful if the options are grouped together by features and concepts they relate to.

On Dec 1, 2010, at 11:30 AM, Junio C Hamano wrote:

I completely agree. Alphabetical sorting is only useful when you already know the name of the command you want, and you have no search function. If you don't know the name of the command you want, then grouping by functionality is far better, and if you have a search function, then there is no real benefit at all to A-Z sorting. Trying to make the manpage look "nice" at the expense of removing functional grouping is misguided.

-Kevin Ballard

2010-12-01 23:58 Kevin Ballard <kevin@sb.org>:

Please explain where is the removed functionality in here:

GIT-COMMIT(1)                      Git Manual                     GIT-COMMIT(1)

OPTIONS
       -a, --all
           Tell the command to automatically stage files that have been
           modified and deleted, but new files you have not told git about are
           not affected.

       -C <commit>, --reuse-message=<commit>
           Take an existing commit object, and reuse the log message and the
           authorship information (including the timestamp) when creating the
           commit.

       -c <commit>, --reedit-message=<commit>
           Like -C, but with -c the editor is invoked, so that the user can
           further edit the commit message.

       --reset-author
           When used with -C/-c/--amend options, declare that the authorship of
           the resulting commit now belongs of the committer. This also renews
           the author timestamp.

What is the reason --reset-author is in that position? What functionality is serves? There are loads of similar ones. I don't see any group. Neither probably Joe Average.

To me the git-pages do not look that professional when options are whereever. Take 10 manual pages side by side in terminals and the options are chaos (try locating some option, say "-v", on every command and try to figure if it serves same purpose in every command or not).

When the pages list options in alphabetical order, it doesn't take long to compare commands: similarities and differences in options, or missing options, or inconsistencies for that matter.

Jari

On Dec 1, 2010, at 2:45 PM, Jari Aalto wrote:

It's entirely possible that this isn't ordered well, but from your quoted text I would assume --reset-author is there because it's related to the -C and -c flags (which directly precede it). In fact, if it wasn't for the current ordering, I never would have even known about that flag.

You seem overly concerned with the visual aesthetics and not at all with the actual content.

Why would you compare commands like that? There's really no reason at all to believe that the -c flag for one command is even related to the -c flag for another command.

-Kevin Ballard

2010-12-02 00:52 Kevin Ballard <kevin@sb.org>:

The reader have to guess "imagined groups"? Hm, that's interesting.

Humans read visually. It's built in. Distractions slow down. Try writing

    abcdef = 1
    x123.213.123..123. = 4
    sdaölkasd = 1

vs.

    abcdef              = 1
    x123.213.123..123.  = 4
    sdaölkasd           = 1

There is a reason why people like Excel cells. Not my invention.

I take it you have written loads of software. The reasons come from standard Software Development and Quality auditions. Git's command line is inconsistent in many places and there is room for improvement. Documentation is one way to spot those.

And ther eis perfect reasons to, again, expect consistency on some level of command options to mean same thing

Like why some commands need number in:

    -n NUMBER

Whereas other's use:

    -NUMBER

Examples like that.

Jari

[Cc un-culled]

--- Jari Aalto <jari.aalto@cante.net> wrote:

Perhaps a more desirable (and agreeable) patch would introduce group subheadings, then? I agree with the majority of people who chimed in here that functional grouping is a good thing. Perhaps we should actually commit to that by having explicit groups.

In rev-list-related options we already have a couple of explicit groups. I think I'd go insane if I ever had to find anything in there without those groups.

That seems to be the only reason you've brought forward for alphabetic sorting, except the claim that "people read from top to bottom" (which is essentially true, but I don't think anybody would read, say, a printed dictionary all the way through; the alphabetic ordering there is for being able to index/search the content in the absence of another way to index/search).

In any case, the end user will probably be more often interested in appropriately grouped options than in being able to easily find inconsistencies between various commands.

-Jan

2010-12-02 10:53 Jan Krüger <jk@jk.gs>:

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.

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

I can't find that manual page or file under Documentation/, could you help here?

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

    - They are technical documentation
    - They are reference documentation
    - They are visited, then discarded, visited and discarded.

People primarily learn outside of manaula pages. No wonder Books are being written. Compare:

    - Have you seen the Web SVN book?
    - Have you seen the Web HG Book?

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

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

    - Geek. He wants to learn inside out.

      > He digestestes all. Related options, related pages, flipping
      > form man to man as he knows all the glory details is just there.

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

Jari

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:

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

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.

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

Counterexample: Perl.

Contrived use case.  Disregarded.

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

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

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.

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.

[Cc unculled again; I will ignore all further posts from you until you stop culling or explain why you are ignoring all requests to stop culling.]

--- Jari Aalto <jari.aalto@cante.net> wrote:

What makes the GNU project the gold standard? They've got some pretty weird conventions, such as their coding style.

You are "agreeing with" something I didn't say. That's not very helpful.

They were for me.

I want related things in technical documentation to be grouped.

I want related things in reference documentation to be grouped.

Correct. Especially for that reason, I want related things to be grouped. I don't want to scroll through the entire list of options just to find everything related to what I want to do.

The only realistic way around that is to stop using 

Because everyone always knows whether the desired option is called --skip-foo, --no-use-foo, --disable-foo, --no-foo, --antifoo or --bar?

In virtually all cases, I know what I want but not the name of the option. It rarely happens that I know the name of the option but not what it does.

As mentioned, I believe that alphabetic ordering makes it harder and take longer.

Even then, learning works better if you learn things grouped by similarities. Alphabetic ordering of the material just makes it harder. You don't see the English teachers hand out vocabulary lessons in alphabetic order, do you?

That is correct, but none of your patches change anything about that.

Have you ever been inside a library? The bookshelves are not ordered alphabetically. There is a section for physics and a section for zoology and a section for architecture. That makes it easier to find.

In fact, even before the advent of computers, the catalogs of libraries were available in two forms: alphabetically ordered (which only helps if you know the exact name of what you are looking for) and ordered by category (which is pretty much the only way to find something if you don't know exactly what you want, unless you want to read the whole catalog back to front).

In any case, we can go around in circles forever on this. Our opinions are different, and if we don't accept each others' arguments, nothing will ever come of this. The next stage in a productive discussion is to either stop bothering or to produce evidence. If you have any scientific evidence that alphabetically ordered lists make it easier to find things the names of which you don't know, I'll be happy to look at it.

-Jan

2010-12-01 21:30 Junio C Hamano <gitster@pobox.com>:

Tell me aftter many more decades and I may believe it. When computer screen is no more alike print media.

Where do you see grouping all the sudden? Manaula pages are not primarily used to learn things, they are used as reference. Just like Book indexes.

I haven't seed anyone for 10's of years who would have read full manaul page from top to botton; every single line at one stop.

They come and go, come and go to read it. Learn bit by bit. And there is the strenght od proper indexing, the alphabetical.

Jari

You may want to invest in a spell-checker.

On Dec 1, 2010, at 2:35 PM, Jari Aalto wrote:

Most certainly they are used to learn things. Especially with tools like git. Don't know what options you can give to git-diff? Read the manpage!

Indexing, sure, but the actual manpage is not an index. A-Z ordering makes no sense for the manpage. When people read, chunk by chunk, they expect related functionality. It especially helps with discoverability. For example, I know of the -w flag to git-diff that tells it to ignore whitespace. I'm not certain this does exactly what I want, so I pop open the manpage, search for -w, and read it. And I'm right, it doesn't do what I want. But right next to it is the flag -b, and that _does_ do precisely what I want. If the manpage was ordered alphabetically, I'd likely have never found the -b flag. As it is, all 3 whitespace-related flags to git-diff are grouped together, and it helps not only with reading the manpage for the first time (as I learn all related concepts at the same time), but with discovering the related flags when I go back to read documentation on the flags I already know.

-Kevin Ballard

2010-12-02 00:49 Kevin Ballard <kevin@sb.org>:

That little word "primarily." You don't find anyone who learnt from manual page first is person is on his 20's. Google is full of Git videos. Guess which won the sexiest contest.

I'm addressing the current audience, this generation, not old farts like me. Linus, Hamano et all, when computers were Golden age and Z-something.

Jari

On Dec 1, 2010, at 3:05 PM, Jari Aalto wrote:

How about me? I'm 25, I've been using git for a couple of years, and the manpages have always been my primary documentation.

The videos are great at convincing people to use git. But people always turn to the manpages in order to learn the details.

-Kevin Ballard

2010-12-02 01:40 Kevin Ballard <kevin@sb.org>:

And your background before that (those 5 years?). Can you say that you're an average, to fit a imagned genralized 20's audience? I'm sure you have heard how hard it is nowadays to teach programming or Software Engineering in Universities.

"Details". You said it. They are consulted.

Not to learn as a primary method per se. The manual pages are too technical; not really their fault, they are supposed to be. As "manuals" are.

The progression goes:

    - Google, more Google, and yet more Google (or the next line swapped)
    - Videos, and Google blogs
    - Co-worker, Co-student, Co-<whatever>
    - Git Book, The Pro Book etc. (when there is time, free of other duties).
    - And more Google.
    ... man pages at the bottom after you have used Git for some time.

To add perspective: there is no manual pages in Windows. What you have is a browser that is one click away from information.

Jari

On Thu, Dec 2, 2010 at 12:05 AM, Jari Aalto <jari.aalto@cante.net> wrote:

Stop making things up. I'm in my 20's and learned Git primarily by reading the manual pages.

I think you can start a fork now, with everything sorted alphabetically. Massive changes do not fit well in git development model. It causes lots of conflicts.

I would like to hear any user feedback from such a fork. If it proves actually helpful for end users, it would be merged eventually.