{"thread":{"id":"25881","subject":"[PATCH] git-commit.txt: Order options alphabetically","startedAt":"2010-12-01T14:58:46Z","lastAt":"2010-12-03T13:03:59Z","messageCount":22,"participants":["jari.aalto@cante.net","Jonathan Nieder","Jari Aalto","Jakub Narebski","Junio C Hamano","Kevin Ballard","Jan Krüger","Erik Faye-Lund","Nguyen Thai Ngoc Duy"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"156935","messageId":"1291215526-11428-1-git-send-email-jari.aalto@cante.net","threadId":"25881","inReplyTo":null,"subject":"[PATCH] git-commit.txt: Order options alphabetically","fromName":"","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-01T14:58:46Z","receivedAt":"2010-12-01T14:58:46Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"From: Jari Aalto \n\n\nSigned-off-by: Jari Aalto \n---\n Documentation/git-commit.txt | 220 +++++++++++++++++++++---------------------\n 1 files changed, 110 insertions(+), 110 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 42fb1f5..770f20b 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -59,73 +59,6 @@ OPTIONS\n \tbeen modified and deleted, but new files you have not\n \ttold git about are not affected.\n \n--C ::\n---reuse-message=::\n-\tTake an existing commit object, and reuse the log message\n-\tand the authorship information (including the timestamp)\n-\twhen creating the commit.\n-\n--c ::\n---reedit-message=::\n-\tLike '-C', but with '-c' the editor is invoked, so that\n-\tthe user can further edit the commit message.\n-\n---reset-author::\n-\tWhen used with -C/-c/--amend options, declare that the\n-\tauthorship of the resulting commit now belongs of the committer.\n-\tThis also renews the author timestamp.\n-\n---short::\n-\tWhen doing a dry-run, give the output in the short-format. See\n-\tlinkgit:git-status[1] for details. Implies `--dry-run`.\n-\n---porcelain::\n-\tWhen doing a dry-run, give the output in a porcelain-ready\n-\tformat. See linkgit:git-status[1] for details. Implies\n-\t`--dry-run`.\n-\n--z::\n-\tWhen showing `short` or `porcelain` status output, terminate\n-\tentries in the status output with NUL, instead of LF. If no\n-\tformat is given, implies the `--porcelain` output format.\n-\n--F ::\n---file=::\n-\tTake the commit message from the given file. Use '-' to\n-\tread the message from the standard input.\n-\n---author=::\n-\tOverride the commit author. Specify an explicit author using the\n-\tstandard `A U Thor ` format. Otherwise \n-\tis assumed to be a pattern and is used to search for an existing\n-\tcommit by that author (i.e. rev-list --all -i --author=);\n-\tthe commit author is then copied from the first such commit found.\n-\n---date=::\n-\tOverride the author date used in the commit.\n-\n--m ::\n---message=::\n-\tUse the given as the commit message.\n-\n--t ::\n---template=::\n-\tUse the contents of the given file as the initial version\n-\tof the commit message. The editor is invoked and you can\n-\tmake subsequent changes. If a message is specified using\n-\tthe `-m` or `-F` options, this option has no effect. This\n-\toverrides the `commit.template` configuration variable.\n-\n--s::\n---signoff::\n-\tAdd Signed-off-by line by the committer at the end of the commit\n-\tlog message.\n-\n--n::\n---no-verify::\n-\tThis option bypasses the pre-commit and commit-msg hooks.\n-\tSee also linkgit:githooks[5].\n-\n --allow-empty::\n \tUsually recording a commit that has the exact same tree as its\n \tsole parent commit is a mistake, and the command prevents you\n@@ -138,23 +71,6 @@ OPTIONS\n empty commit message without using plumbing commands like\n linkgit:git-commit-tree[1].\n \n---cleanup=::\n-\tThis option sets how the commit message is cleaned up.\n-\tThe '' can be one of 'verbatim', 'whitespace', 'strip',\n-\tand 'default'. The 'default' mode will strip leading and\n-\ttrailing empty lines and #commentary from the commit message\n-\tonly if the message is to be edited. Otherwise only whitespace\n-\tremoved. The 'verbatim' mode does not change message at all,\n-\t'whitespace' removes just leading/trailing whitespace lines\n-\tand 'strip' removes both whitespace and commentary.\n-\n--e::\n---edit::\n-\tThe message taken from file with `-F`, command line with\n-\t`-m`, and from file with `-C` are usually used as the\n-\tcommit log message unmodified. This option lets you\n-\tfurther edit the message taken from these sources.\n-\n --amend::\n \tUsed to amend the tip of the current branch. Prepare the tree\n \tobject you would want to replace the latest commit as usual\n@@ -180,6 +96,68 @@ You should understand the implications of rewriting history if you\n amend a commit that has already been published. (See the \"RECOVERING\n FROM UPSTREAM REBASE\" section in linkgit:git-rebase[1].)\n \n+--author=::\n+\tOverride the commit author. Specify an explicit author using the\n+\tstandard `A U Thor ` format. Otherwise \n+\tis assumed to be a pattern and is used to search for an existing\n+\tcommit by that author (i.e. rev-list --all -i --author=);\n+\tthe commit author is then copied from the first such commit found.\n+\n+-c ::\n+--reedit-message=::\n+\tLike '-C', but with '-c' the editor is invoked, so that\n+\tthe user can further edit the commit message.\n+\n+-C ::\n+--reuse-message=::\n+\tTake an existing commit object, and reuse the log message\n+\tand the authorship information (including the timestamp)\n+\twhen creating the commit.\n+\n+--cleanup=::\n+\tThis option sets how the commit message is cleaned up.\n+\tThe '' can be one of 'verbatim', 'whitespace', 'strip',\n+\tand 'default'. The 'default' mode will strip leading and\n+\ttrailing empty lines and #commentary from the commit message\n+\tonly if the message is to be edited. Otherwise only whitespace\n+\tremoved. The 'verbatim' mode does not change message at all,\n+\t'whitespace' removes just leading/trailing whitespace lines\n+\tand 'strip' removes both whitespace and commentary.\n+\n+--date=::\n+\tOverride the author date used in the commit.\n+\n+--dry-run::\n+\tDo not create a commit, but show a list of paths that are\n+\tto be committed, paths with local changes that will be left\n+\tuncommitted and paths that are untracked.\n+\n+-e::\n+--edit::\n+\tThe message taken from file with `-F`, command line with\n+\t`-m`, and from file with `-C` are usually used as the\n+\tcommit log message unmodified. This option lets you\n+\tfurther edit the message taken from these sources.\n+\n+-F ::\n+--file=::\n+\tTake the commit message from the given file. Use '-' to\n+\tread the message from the standard input.\n+\n+-m ::\n+--message=::\n+\tUse the given as the commit message.\n+\n+-n::\n+--no-verify::\n+\tThis option bypasses the pre-commit and commit-msg hooks.\n+\tSee also linkgit:githooks[5].\n+\n+--no-status::\n+\tDo not include the output of linkgit:git-status[1] in the\n+\tcommit message template when using an editor to prepare the\n+\tdefault commit message. See option `--status'.\n+\n -i::\n --include::\n \tBefore making a commit out of staged contents so far,\n@@ -199,6 +177,50 @@ FROM UPSTREAM REBASE\" section in linkgit:git-rebase[1].)\n \tthe last commit without committing changes that have\n \talready been staged.\n \n+-q::\n+--quiet::\n+\tSuppress commit summary message.\n+\n+--status::\n+\tInclude the output of linkgit:git-status[1] in the commit\n+\tmessage template when using an editor to prepare the commit\n+\tmessage. Defaults to on, but can be used to override\n+\tconfiguration variable commit.status. See option `--no-status'.\n+\n+--porcelain::\n+\tWhen doing a dry-run, give the output in a porcelain-ready\n+\tformat. See linkgit:git-status[1] for details. Implies\n+\t`--dry-run`.\n+\n+--reset-author::\n+\tWhen used with -C/-c/--amend options, declare that the\n+\tauthorship of the resulting commit now belongs of the committer.\n+\tThis also renews the author timestamp.\n+\n+-s::\n+--signoff::\n+\tAdd Signed-off-by line by the committer at the end of the commit\n+\tlog message.\n+\n+--short::\n+\tWhen doing a dry-run, give the output in the short-format. See\n+\tlinkgit:git-status[1] for details. Implies `--dry-run`.\n+\n+-t ::\n+--template=::\n+\tUse the contents of the given file as the initial version\n+\tof the commit message. The editor is invoked and you can\n+\tmake subsequent changes. If a message is specified using\n+\tthe `-m` or `-F` options, this option has no effect. This\n+\toverrides the `commit.template` configuration variable.\n+\n+-v::\n+--verbose::\n+\tShow unified diff between the HEAD commit and what\n+\twould be committed at the bottom of the commit message\n+\ttemplate. Note that this diff output doesn't have its\n+\tlines prefixed with '#'.\n+\n -u[]::\n --untracked-files[=]::\n \tShow untracked files (Default: 'all').\n@@ -216,32 +238,10 @@ See linkgit:git-config[1] for configuration variable\n used to change the default for when the option is not\n specified.\n \n--v::\n---verbose::\n-\tShow unified diff between the HEAD commit and what\n-\twould be committed at the bottom of the commit message\n-\ttemplate. Note that this diff output doesn't have its\n-\tlines prefixed with '#'.\n-\n--q::\n---quiet::\n-\tSuppress commit summary message.\n-\n---dry-run::\n-\tDo not create a commit, but show a list of paths that are\n-\tto be committed, paths with local changes that will be left\n-\tuncommitted and paths that are untracked.\n-\n---status::\n-\tInclude the output of linkgit:git-status[1] in the commit\n-\tmessage template when using an editor to prepare the commit\n-\tmessage. Defaults to on, but can be used to override\n-\tconfiguration variable commit.status.\n-\n---no-status::\n-\tDo not include the output of linkgit:git-status[1] in the\n-\tcommit message template when using an editor to prepare the\n-\tdefault commit message.\n+-z::\n+\tWhen showing `short` or `porcelain` status output, terminate\n+\tentries in the status output with NUL, instead of LF. If no\n+\tformat is given, implies the `--porcelain` output format.\n \n \\--::\n \tDo not interpret any more arguments as options.\n-- \n1.7.2.3\n"},{"id":"156958","messageId":"20101201165043.GF26120@burratino","threadId":"25881","inReplyTo":"1291215526-11428-1-git-send-email-jari.aalto@cante.net","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-12-01T16:50:43Z","receivedAt":"2010-12-01T16:50:43Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi again,\n\njari.aalto@cante.net wrote:\n\n> [Subject: [PATCH] git-commit.txt: Order options alphabetically]\n>\n> Signed-off-by: Jari Aalto \n\nHere's what Documentation/SubmittingPatches has to say.\n\n\t[...] patches which plainly describe the things that\n\thelp reviewers check the patch, and future maintainers understand\n\tthe code, are the most beautiful patches. Descriptions that summarise\n\tthe point in the subject well, and describe the motivation for the\n\tchange, the approach taken by the change, and if relevant how this\n\tdiffers substantially from the prior version, can be found on Usenet\n\tarchives back into the late 80's. Consider it like good Netiquette,\n\tbut for code.\n\nHere, you've explained what the patch does, but not why. How are\nreviewers to evaluate whether it succeeded?\n\nIf the goal is sorted option lists in all manpages, that will _have_\nto be automated. Some manpages read some and not all of their options\nfrom an external file. But before we deal with that: why would I want\nsorted option lists in all manpages?\n\nSorting can sometimes be an improvement; it just seems better to\nmention the particulars of the situation and why sorting rather than\nsome thematic grouping is appropriate in a given case.\n\nHope that helps,\nJonathan\n"},{"id":"156962","messageId":"87r5e1v2g8.fsf@picasso.cante.net","threadId":"25881","inReplyTo":"20101201165043.GF26120@burratino","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-01T17:16:07Z","receivedAt":"2010-12-01T17:16:07Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-01 18:50 Jonathan Nieder :\n> If the goal is sorted option lists in all manpages, that will _have_\n> to be automated.\n\nWho is going to write that script? I'm afraid that will never happen.\n\nIt's easier and faster to edit. One page at a time. As time allows.\nNobody is going take vacation and do it once for all. Bit by bit is\nbetter approach.\n\n> why would I want sorted option lists in all manpages?\n\nDoes that really need an answer? You read from top to bottom, therefore\nA-Z. Well, GNU uses it in manula pages. It looks good, it looks\nprofessional, it looks clean. And it works when searching (= no\noriantation problems).\n\nJari\n"},{"id":"156965","messageId":"m362vd4c6h.fsf@localhost.localdomain","threadId":"25881","inReplyTo":"87r5e1v2g8.fsf@picasso.cante.net","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-12-01T17:48:57Z","receivedAt":"2010-12-01T17:48:57Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jari, could you please do not cull Cc list, if possible? Thanks in\nadvance.\n\nJari Aalto writes:\n> 2010-12-01 18:50 Jonathan Nieder :\n\n> > If the goal is sorted option lists in all manpages, that will _have_\n> > to be automated.\n> \n> Who is going to write that script? I'm afraid that will never happen.\n> \n> It's easier and faster to edit. One page at a time. As time allows.\n> Nobody is going take vacation and do it once for all. Bit by bit is\n> better approach.\n\nBut because some manpages \"include\" other pages (to refactor common\noptions), it would be impossible to sort alphabetically options in all\nmanpages. So why bother with impossible? It would only introduce\ninconsistency.\n\n> > why would I want sorted option lists in all manpages?\n> \n> Does that really need an answer? You read from top to bottom, therefore\n> A-Z. Well, GNU uses it in manual pages. \n\nWhat do you mean by \"GNU\" here?\n\n> It looks good, it looks\n> professional, it looks clean. And it works when searching (= no\n> orientation problems).\n\nIt works if you have separate user's documentation from reference\ndocumentation. GNU projects were meant to have manpages as reference,\nand info pages as user's documentation. Options sorted alphabetically\nmight make sense for reference documentation. \n\nBut git manpages doesn't serve _only_ as reference documentation. And\nlearning commands from manpages where options are sorted alphabetically\ninstead of grouped together by function *suck* big time.\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"156979","messageId":"87k4jtuyky.fsf@picasso.cante.net","threadId":"25881","inReplyTo":"m362vd4c6h.fsf@localhost.localdomain","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-01T18:39:41Z","receivedAt":"2010-12-01T18:39:41Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-01 19:48 Jakub Narebski :\n>> 2010-12-01 18:50 Jonathan Nieder :\n>\n> But because some manpages \"include\" other pages (to refactor common\n> options), it would be impossible to sort alphabetically options in all\n> manpages. So why bother with impossible? It would only introduce\n> inconsistency.\n\nDecresing entropy is better goal even if we cannot make it perfect. We\ndo what we can. And there are many pages that don't use include.\n\nI don't mind work. You just watch and lean back.\n\n>> professional, it looks clean. And it works when searching (= no\n>> orientation problems).\n>\n> It works if you have separate user's documentation from reference\n> documentation. GNU projects were meant to have manpages as reference,\n> and info pages as user's documentation. Options sorted alphabetically\n> might make sense for reference documentation.\n\nIt makes sense regardless. Printing literature and how people read and\nsearch information hasn't chnage since printing was invented.\n\n> But git manpages doesn't serve _only_ as reference documentation. And\n> learning commands from manpages where options are sorted alphabetically\n> instead of grouped together by function *suck* big time.\n\nNope. Manual pages are not where people learn things any more. They\nGoogle. They buy books. Teh copy from fellow worker. \n\nThe manual pages main use it as reference material. We don't need to\nfight the obvious.\n\nJari\n"},{"id":"156989","messageId":"7vzkspuw8g.fsf@alter.siamese.dyndns.org","threadId":"25881","inReplyTo":"87r5e1v2g8.fsf@picasso.cante.net","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-12-01T19:30:23Z","receivedAt":"2010-12-01T19:30:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n>> why would I want sorted option lists in all manpages?\n>\n> Does that really need an answer?\n\nYes.\n\n> You read from top to bottom, therefore\n> A-Z.\n\nI used to think that back when I referred to printed documentation more\noften than online, but not anymore. Alphabetical ordering is somewhat\nlast century; the documentation is often more useful if the options are\ngrouped together by features and concepts they relate to.\n"},{"id":"157028","messageId":"295D1E95-1C61-4960-8C9C-BDB0BD4A1A50@sb.org","threadId":"25881","inReplyTo":"7vzkspuw8g.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Kevin Ballard","fromEmail":"kevin@sb.org","sentAt":"2010-12-01T21:58:43Z","receivedAt":"2010-12-01T21:58:43Z","isPatch":true,"sender":{"key":"kevin@sb.org","avatar":"https://avatars.githubusercontent.com/u/714?v=4"},"body":"On Dec 1, 2010, at 11:30 AM, Junio C Hamano wrote:\n\n>> You read from top to bottom, therefore\n>> A-Z.\n> \n> I used to think that back when I referred to printed documentation more\n> often than online, but not anymore. Alphabetical ordering is somewhat\n> last century; the documentation is often more useful if the options are\n> grouped together by features and concepts they relate to.\n\nI completely agree. Alphabetical sorting is only useful when you already\nknow the name of the command you want, and you have no search function.\nIf you don't know the name of the command you want, then grouping by\nfunctionality is far better, and if you have a search function, then there\nis no real benefit at all to A-Z sorting. Trying to make the manpage look\n\"nice\" at the expense of removing functional grouping is misguided.\n\n-Kevin Ballard\n"},{"id":"157036","messageId":"87r5e1t93o.fsf@picasso.cante.net","threadId":"25881","inReplyTo":"7vzkspuw8g.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-01T22:35:23Z","receivedAt":"2010-12-01T22:35:23Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-01 21:30 Junio C Hamano :\n>\n> Alphabetical ordering is somewhat last century\n\nTell me aftter many more decades and I may believe it. When computer\nscreen is no more alike print media.\n\n> the documentation is often more useful if the options are\n> grouped together by features and concepts they relate to.\n\nWhere do you see grouping all the sudden? Manaula pages are not\nprimarily used to learn things, they are used as reference. Just like\nBook indexes.\n\nI haven't seed anyone for 10's of years who would have read full manaul\npage from top to botton; every single line at one stop.\n\nThey come and go, come and go to read it. Learn bit by bit. And there is\nthe strenght od proper indexing, the alphabetical.\n\nJari\n"},{"id":"157038","messageId":"87mxopt8my.fsf@picasso.cante.net","threadId":"25881","inReplyTo":"295D1E95-1C61-4960-8C9C-BDB0BD4A1A50@sb.org","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-01T22:45:25Z","receivedAt":"2010-12-01T22:45:25Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-01 23:58 Kevin Ballard :\n> On Dec 1, 2010, at 11:30 AM, Junio C Hamano wrote:\n>\n> Trying to make the manpage look \"nice\" at the expense of removing\n> functional grouping is misguided.\n\nPlease explain where is the removed functionality in here:\n\nGIT-COMMIT(1) Git Manual GIT-COMMIT(1)\n\nOPTIONS\n -a, --all\n Tell the command to automatically stage files that have been\n modified and deleted, but new files you have not told git about are\n not affected.\n\n -C , --reuse-message=\n Take an existing commit object, and reuse the log message and the\n authorship information (including the timestamp) when creating the\n commit.\n\n -c , --reedit-message=\n Like -C, but with -c the editor is invoked, so that the user can\n further edit the commit message.\n\n --reset-author\n When used with -C/-c/--amend options, declare that the authorship of\n the resulting commit now belongs of the committer. This also renews\n the author timestamp.\n\nWhat is the reason --reset-author is in that position? What\nfunctionality is serves? There are loads of similar ones. I don't see\nany group. Neither probably Joe Average.\n\nTo me the git-pages do not look that professional when options are\nwhereever. Take 10 manual pages side by side in terminals and the\noptions are chaos (try locating some option, say \"-v\", on every command\nand try to figure if it serves same purpose in every command or not).\n\nWhen the pages list options in alphabetical order, it doesn't take long\nto compare commands: similarities and differences in options, or missing\noptions, or inconsistencies for that matter.\n\nJari\n"},{"id":"157039","messageId":"2C3777CB-2DDD-4FF5-842B-23F7EF838611@sb.org","threadId":"25881","inReplyTo":"87r5e1t93o.fsf@picasso.cante.net","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Kevin Ballard","fromEmail":"kevin@sb.org","sentAt":"2010-12-01T22:49:02Z","receivedAt":"2010-12-01T22:49:02Z","isPatch":true,"sender":{"key":"kevin@sb.org","avatar":"https://avatars.githubusercontent.com/u/714?v=4"},"body":"You may want to invest in a spell-checker.\n\nOn Dec 1, 2010, at 2:35 PM, Jari Aalto wrote:\n\n>> the documentation is often more useful if the options are\n>> grouped together by features and concepts they relate to.\n> \n> Where do you see grouping all the sudden? Manaula pages are not\n> primarily used to learn things, they are used as reference. Just like\n> Book indexes.\n\nMost certainly they are used to learn things. Especially with tools like git.\nDon't know what options you can give to git-diff? Read the manpage!\n\n> I haven't seed anyone for 10's of years who would have read full manaul\n> page from top to botton; every single line at one stop.\n> \n> They come and go, come and go to read it. Learn bit by bit. And there is\n> the strenght od proper indexing, the alphabetical.\n\nIndexing, sure, but the actual manpage is not an index. A-Z ordering makes\nno sense for the manpage. When people read, chunk by chunk, they expect\nrelated functionality. It especially helps with discoverability. For example,\nI know of the -w flag to git-diff that tells it to ignore whitespace. I'm not\ncertain this does exactly what I want, so I pop open the manpage, search for\n-w, and read it. And I'm right, it doesn't do what I want. But right next to\nit is the flag -b, and that _does_ do precisely what I want. If the manpage\nwas ordered alphabetically, I'd likely have never found the -b flag. As it is,\nall 3 whitespace-related flags to git-diff are grouped together, and it helps\nnot only with reading the manpage for the first time (as I learn all related\nconcepts at the same time), but with discovering the related flags when I go\nback to read documentation on the flags I already know.\n\n-Kevin Ballard"},{"id":"157041","messageId":"E02740CE-37EE-4701-BB2D-18AD493D1C05@sb.org","threadId":"25881","inReplyTo":"87mxopt8my.fsf@picasso.cante.net","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Kevin Ballard","fromEmail":"kevin@sb.org","sentAt":"2010-12-01T22:52:51Z","receivedAt":"2010-12-01T22:52:51Z","isPatch":true,"sender":{"key":"kevin@sb.org","avatar":"https://avatars.githubusercontent.com/u/714?v=4"},"body":"On Dec 1, 2010, at 2:45 PM, Jari Aalto wrote:\n\n> 2010-12-01 23:58 Kevin Ballard :\n>> On Dec 1, 2010, at 11:30 AM, Junio C Hamano wrote:\n>> \n>> Trying to make the manpage look \"nice\" at the expense of removing\n>> functional grouping is misguided.\n> \n> Please explain where is the removed functionality in here:\n> \n> GIT-COMMIT(1) Git Manual GIT-COMMIT(1)\n> \n> OPTIONS\n> -a, --all\n> Tell the command to automatically stage files that have been\n> modified and deleted, but new files you have not told git about are\n> not affected.\n> \n> -C , --reuse-message=\n> Take an existing commit object, and reuse the log message and the\n> authorship information (including the timestamp) when creating the\n> commit.\n> \n> -c , --reedit-message=\n> Like -C, but with -c the editor is invoked, so that the user can\n> further edit the commit message.\n> \n> --reset-author\n> When used with -C/-c/--amend options, declare that the authorship of\n> the resulting commit now belongs of the committer. This also renews\n> the author timestamp.\n> \n> What is the reason --reset-author is in that position? What\n> functionality is serves? There are loads of similar ones. I don't see\n> any group. Neither probably Joe Average.\n\nIt's entirely possible that this isn't ordered well, but from your quoted text\nI would assume --reset-author is there because it's related to the -C and -c\nflags (which directly precede it). In fact, if it wasn't for the current ordering,\nI never would have even known about that flag.\n\n> To me the git-pages do not look that professional when options are\n> whereever. Take 10 manual pages side by side in terminals and the\n> options are chaos (try locating some option, say \"-v\", on every command\n> and try to figure if it serves same purpose in every command or not).\n\nYou seem overly concerned with the visual aesthetics and not at all with the\nactual content.\n\n> When the pages list options in alphabetical order, it doesn't take long\n> to compare commands: similarities and differences in options, or missing\n> options, or inconsistencies for that matter.\n\nWhy would you compare commands like that? There's really no reason at all to\nbelieve that the -c flag for one command is even related to the -c flag for\nanother command.\n\n-Kevin Ballard"},{"id":"157046","messageId":"87aakpt7uw.fsf@picasso.cante.net","threadId":"25881","inReplyTo":"E02740CE-37EE-4701-BB2D-18AD493D1C05@sb.org","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-01T23:02:15Z","receivedAt":"2010-12-01T23:02:15Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-02 00:52 Kevin Ballard :\n> On Dec 1, 2010, at 2:45 PM, Jari Aalto wrote:\n>> What is the reason --reset-author is in that position? What\n>\n> It's entirely possible...\n\nThe reader have to guess \"imagined groups\"? Hm, that's interesting.\n\n>> To me the git-pages do not look that professional...\n>\n> You seem overly concerned with the visual aesthetics and not at all with the\n> actual content.\n\nHumans read visually. It's built in. Distractions slow down. Try writing\n\n abcdef = 1\n x123.213.123..123. = 4\n sdaölkasd = 1\n\nvs.\n\n abcdef = 1\n x123.213.123..123. = 4\n sdaölkasd = 1\n\nThere is a reason why people like Excel cells. Not my invention.\n\n>> When the pages list options in alphabetical order, it doesn't take long\n>> to compare commands: similarities and differences in options, or missing\n>> options, or inconsistencies for that matter.\n>\n> Why would you compare commands like that? There's really no reason at all to\n> believe that the -c flag for one command is even related to the -c flag for\n> another command.\n\nI take it you have written loads of software. The reasons come from\nstandard Software Development and Quality auditions. Git's command line\nis inconsistent in many places and there is room for improvement.\nDocumentation is one way to spot those.\n\nAnd ther eis perfect reasons to, again, expect consistency on some level\nof command options to mean same thing\n\nLike why some commands need number in:\n\n -n NUMBER\n\nWhereas other's use:\n\n -NUMBER\n\nExamples like that.\n\nJari\n"},{"id":"157047","messageId":"8762vdt7oo.fsf@picasso.cante.net","threadId":"25881","inReplyTo":"2C3777CB-2DDD-4FF5-842B-23F7EF838611@sb.org","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-01T23:05:59Z","receivedAt":"2010-12-01T23:05:59Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-02 00:49 Kevin Ballard :\n> You may want to invest in a spell-checker.\n> ... Manaula pages are not primarily used to learn things, they are\n> used as reference.\n>\n> Most certainly they are used to learn things. Especially with tools like git.\n> Don't know what options you can give to git-diff? Read the manpage!\n\nThat little word \"primarily.\" You don't find anyone who learnt from\nmanual page first is person is on his 20's. Google is full of Git\nvideos. Guess which won the sexiest contest.\n\nI'm addressing the current audience, this generation, not old farts like\nme. Linus, Hamano et all, when computers were Golden age and Z-something.\n\nJari\n"},{"id":"157061","messageId":"4BA22C80-9F0C-4F5F-8DBF-3E49D3D9C36A@sb.org","threadId":"25881","inReplyTo":"8762vdt7oo.fsf@picasso.cante.net","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Kevin Ballard","fromEmail":"kevin@sb.org","sentAt":"2010-12-01T23:40:22Z","receivedAt":"2010-12-01T23:40:22Z","isPatch":true,"sender":{"key":"kevin@sb.org","avatar":"https://avatars.githubusercontent.com/u/714?v=4"},"body":"On Dec 1, 2010, at 3:05 PM, Jari Aalto wrote:\n\n> 2010-12-02 00:49 Kevin Ballard :\n>> You may want to invest in a spell-checker.\n>> ... Manaula pages are not primarily used to learn things, they are\n>> used as reference.\n>> \n>> Most certainly they are used to learn things. Especially with tools like git.\n>> Don't know what options you can give to git-diff? Read the manpage!\n> \n> That little word \"primarily.\" You don't find anyone who learnt from\n> manual page first is person is on his 20's. Google is full of Git\n> videos. Guess which won the sexiest contest.\n\nHow about me? I'm 25, I've been using git for a couple of years, and the manpages\nhave always been my primary documentation.\n\nThe videos are great at convincing people to use git. But people always turn to\nthe manpages in order to learn the details.\n\n-Kevin Ballard"},{"id":"157077","messageId":"871v60u47i.fsf@picasso.cante.net","threadId":"25881","inReplyTo":"4BA22C80-9F0C-4F5F-8DBF-3E49D3D9C36A@sb.org","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-02T05:35:45Z","receivedAt":"2010-12-02T05:35:45Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-02 01:40 Kevin Ballard :\n> On Dec 1, 2010, at 3:05 PM, Jari Aalto wrote:\n>> That little word \"primarily.\" You don't find anyone who learnt from\n>> manual page first is person is on his 20's. Google is full of Git\n>> videos. Guess which won the sexiest contest.\n>\n> How about me? I'm 25, I've been using git for a couple of years, and\n> the manpages have always been my primary documentation.\n\nAnd your background before that (those 5 years?). Can you say that\nyou're an average, to fit a imagned genralized 20's audience? I'm sure\nyou have heard how hard it is nowadays to teach programming or Software\nEngineering in Universities.\n\n> The videos are great at convincing people to use git. But people\n> always turn to the manpages in order to learn the details.\n\n\"Details\". You said it. They are consulted.\n\nNot to learn as a primary method per se. The manual pages are too\ntechnical; not really their fault, they are supposed to be. As \"manuals\"\nare.\n\nThe progression goes:\n\n - Google, more Google, and yet more Google (or the next line swapped)\n - Videos, and Google blogs\n - Co-worker, Co-student, Co-\n - Git Book, The Pro Book etc. (when there is time, free of other duties).\n - And more Google.\n ... man pages at the bottom after you have used Git for some time.\n\nTo add perspective: there is no manual pages in Windows. What you have\nis a browser that is one click away from information.\n\nJari\n"},{"id":"157094","messageId":"20101202095324.34237fb2@jk.gs","threadId":"25881","inReplyTo":"87aakpt7uw.fsf@picasso.cante.net","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jan Krüger","fromEmail":"jk@jk.gs","sentAt":"2010-12-02T08:53:24Z","receivedAt":"2010-12-02T08:53:24Z","isPatch":true,"sender":{"key":"jk@jk.gs","avatar":"https://avatars.githubusercontent.com/u/1774?v=4"},"body":"[Cc un-culled]\n\n--- Jari Aalto wrote:\n\n> The reader have to guess \"imagined groups\"? Hm, that's interesting.\n\nPerhaps a more desirable (and agreeable) patch would introduce group\nsubheadings, then? I agree with the majority of people who chimed in\nhere that functional grouping is a good thing. Perhaps we should\nactually commit to that by having explicit groups.\n\nIn rev-list-related options we already have a couple of explicit\ngroups. I think I'd go insane if I ever had to find anything in there\nwithout those groups.\n\n> [...] Git's command\n> line is inconsistent in many places and there is room for improvement.\n> Documentation is one way to spot those.\n\nThat seems to be the only reason you've brought forward for alphabetic\nsorting, except the claim that \"people read from top to\nbottom\" (which is essentially true, but I don't think anybody would\nread, say, a printed dictionary all the way through; the alphabetic\nordering there is for being able to index/search the content in the\nabsence of another way to index/search).\n\nIn any case, the end user will probably be more often interested in\nappropriately grouped options than in being able to easily find\ninconsistencies between various commands.\n\n-Jan\n"},{"id":"157103","messageId":"87fwugs7pf.fsf@picasso.cante.net","threadId":"25881","inReplyTo":"20101202095324.34237fb2@jk.gs","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-02T12:03:08Z","receivedAt":"2010-12-02T12:03:08Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-02 10:53 Jan Krüger :\n> [Cc un-culled]\n>\n> --- Jari Aalto wrote:\n>\n>> The reader have to guess \"imagined groups\"? Hm, that's interesting.\n>\n> Perhaps a more desirable (and agreeable) patch would introduce group\n> subheadings, then?\n\nYes, that's the standard way of doing groups. Just like it's being done\nin other manual pages that are huge. But it is not being done in small\nmanual pages. GNU project certainly doesn't in general.\n\nI agree tat doing \"groups\" makes only sense on pages that have large\nnumber of options. For a screenful, it's more distracting than worth.\n\n> In rev-list-related options we already have a couple of explicit\n> groups.\n\nI can't find that manual page or file under Documentation/, could you\nhelp here?\n\n>> [...] Git's command\n>> line is inconsistent in many places and there is room for improvement.\n>> Documentation is one way to spot those.\n>\n> That seems to be the only reason you've brought forward for alphabetic\n> sorting\n>\n> In any case, the end user will probably be more often interested in\n> appropriately grouped options than in being able to easily find\n> inconsistencies between various commands.\n\nWell. In my experience (having watched others to learn) the manual pages\nare not the source used for learning.\n\n - They are technical documentation\n - They are reference documentation\n - They are visited, then discarded, visited and discarded.\n\nPeople primarily learn outside of manaula pages. No wonder Books are\nbeing written. Compare:\n\n - Have you seen the Web SVN book?\n - Have you seen the Web HG Book?\n\nPeople go to the manual pages once they have a specific need for\ninfomation and details. I could sketch these uses of manual pages:\n\n - Someone throws up a git command (IRC #git, Blogs, Web page). What\n do all those unreadable one letter options mean? Gosh they don't\n even mean the save accross different git* programs.\n\n > He searches manual pages A-Z, easy to spot all options. Not\n > interested in related things. He tries to understand the\n > command, script etc.\n\n - Someone is learning Git.\n\n > He certainly does not start from manual pages. Other soources of\n > information are more in to him. Besides Windows does not have those.\n > We might guess what MySGIt as other do: they reach Google button.\n\n This person just wants to solve a problem, get things done, the\n faster the better. The easier the better, the less thinking the\n better.\n\n - Geek. He wants to learn inside out.\n\n > He digestestes all. Related options, related pages, flipping\n > form man to man as he knows all the glory details is just there.\n\nIt all depends if it is desireable to make pages more approachable to\nthe average group, or are they kept to serve only small core audience.\n\nThere are 100+ manual pages in the git distribution. You get even\ndisoriented in shere numbers of them. And you have to throw dice to\nfigure out in what page that information might be you are currently in\nneed.\n\nIt's classical case of how to arrange information for easy retrieval.\nThink Libraries as model.\n\nJari\n"},{"id":"157116","messageId":"m3wrns2r2d.fsf@localhost.localdomain","threadId":"25881","inReplyTo":"87fwugs7pf.fsf@picasso.cante.net","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-12-02T14:23:16Z","receivedAt":"2010-12-02T14:23:16Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Please do not cull Cc-list, i.e. respond replying to all people who\nparticipate in given (sub)thread. (If it is not possible, tell why).\n\nJari Aalto writes:\n> 2010-12-02 10:53 Jan Krüger :\n> > [Cc un-culled]\n> >\n> > --- Jari Aalto wrote:\n> >\n> > > The reader have to guess \"imagined groups\"? Hm, that's interesting.\n> >\n> > Perhaps a more desirable (and agreeable) patch would introduce group\n> > subheadings, then?\n> \n> Yes, that's the standard way of doing groups. Just like it's being done\n> in other manual pages that are huge. But it is not being done in small\n> manual pages. GNU project certainly doesn't in general.\n\nNote that GNU project produced many more or less stupid/smart\nconventions. It doesn't mean that we should follow them blindly\n(alphabetical sorting of options in manpages, GNU ChangeLog format,\nGNU indent style for C).\n\n> \n> I agree that doing \"groups\" makes only sense on pages that have large\n> number of options. For a screenful, it's more distracting than worth.\n\nThe other side of the fact that creating subsections grouping types of\noptions makes only sense for pages/groups that have large number of\noptions is that we need sorting by function, grouping related options\ntogether. See also use case below.\n\n> > In rev-list-related options we already have a couple of explicit\n> > groups.\n> \n> I can't find that manual page or file under Documentation/, could you\n> help here?\n\n\"man git-rev-list\", Documentation/rev-list-options.txt\n \n[...]\n> Well. In my experience (having watched others to learn) the manual pages\n> are not the source used for learning.\n\nCounterexample: Perl.\n\n> People go to the manual pages once they have a specific need for\n> infomation and details. I could sketch these uses of manual pages:\n> \n> - Someone throws up a git command (IRC #git, Blogs, Web page). What\n> do all those unreadable one letter options mean? Gosh they don't\n> even mean the same accross different git* programs.\n> \n> > He searches manual pages A-Z, easy to spot all options. Not\n> > interested in related things. He tries to understand the\n> > command, script etc.\n\nContrived use case. Disregarded.\n\n> \n> - Someone is learning Git.\n> \n> > He certainly does not start from manual pages. Other soources of\n> > information are more in to him. Besides Windows does not have those.\n\nDid you check that 'man git-' doesn't work on git on MS Windows\n(msysGit, git from Cygwin)?\n\nYou can always use 'git --help '.\n\n> > We might guess what MySGIt as other do: they reach Google button.\n> \n> This person just wants to solve a problem, get things done, the\n> faster the better. The easier the better, the less thinking the\n> better.\n\nThey read \"Git User's Manual\", or \"Pro Git\", or perhaps \"Git Community Book\"\n(the first included with git, the second and third available on-line).\n\n> \n> - Geek. He wants to learn inside out.\n> \n> > He digests all. Related options, related pages, flipping\n> > form man to man as he knows all the glory details is just there.\n\nAnd for geek grouping related options/config variables together is\nhelpful.\n\n\nYou omitted very important use case, something that was mentioned more\nthan once in this and related threads:\n\n - Someone wants to know/remember how to do something in Git.\n Assume that this someone knows git quite well, but not by heart.\n\n Here there is example that was give to you in this thread (or\n related subthread), namely someone checking the name of option that\n ignores whitespace, and because related options are grouped together\n the he/she realizes that he/she wants different but related option\n (-b/--ignore-space-change vs -w/--ignore-all-space).\n\n Another example could be someone searching for config options that\n affect git (re)packing performance. Currently those config options\n are grouped together.\n\n If options are sorted alphabetically this task is made much harder.\n Note that he/she know how to use searching in pager or web browser.\n\n> It all depends if it is desireable to make pages more approachable to\n> the average group, or are they kept to serve only small core audience.\n> \n> There are 100+ manual pages in the git distribution. You get even\n> disoriented in sheer numbers of them. And you have to throw dice to\n> figure out in what page that information might be you are currently in\n> need.\n> \n> It's classical case of how to arrange information for easy retrieval.\n> Think Libraries as model.\n\nComputerized index, or manual? Perhaps it is classical case, but it is\noutdated: modern solutions use folksonomies / labels / tagging rather than\nTrove / Dewey classification or alphabetical sorting.\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"157117","messageId":"m3sjyg2qtc.fsf@localhost.localdomain","threadId":"25881","inReplyTo":"87k4jtuyky.fsf@picasso.cante.net","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-12-02T14:27:58Z","receivedAt":"2010-12-02T14:27:58Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jari Aalto writes:\n> 2010-12-01 19:48 Jakub Narebski :\n> > > 2010-12-01 18:50 Jonathan Nieder :\n> >\n> > But because some manpages \"include\" other pages (to refactor common\n> > options), it would be impossible to sort alphabetically options in all\n> > manpages. So why bother with impossible? It would only introduce\n> > inconsistency.\n> \n> Decreasing entropy is better goal even if we cannot make it perfect. We\n> do what we can. And there are many pages that don't use include.\n\nIncreasing inconsistency is not good, and that would be the final side\neffect.\n \n> I don't mind work. You just watch and lean back.\n\nBut we do mind unnecessary code churn (well, in this case documentation\nchurn). Unless you regard it as \"academical\" exercise.\n \nThe final decision on merging in (accepting) changes lies at git\nmaintainer.\n\n> > > professional, it looks clean. And it works when searching (= no\n> > > orientation problems).\n> >\n> > It works if you have separate user's documentation from reference\n> > documentation. GNU projects were meant to have manpages as reference,\n> > and info pages as user's documentation. Options sorted alphabetically\n> > might make sense for reference documentation.\n> \n> It makes sense regardless. Printing literature and how people read and\n> search information hasn't changed since printing was invented.\n\nHow people search information *has* changed since printing was invented.\n\n> > But git manpages doesn't serve _only_ as reference documentation. And\n> > learning commands from manpages where options are sorted alphabetically\n> > instead of grouped together by function *suck* big time.\n> \n> Nope. Manual pages are not where people learn things any more. They\n> Google. They buy books. They copy from fellow worker.\n> \n> The manual pages main use it as reference material. We don't need to\n> fight the obvious.\n\nCounterexample: Perl manpages.\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"157148","messageId":"20101202203001.3793718d@jk.gs","threadId":"25881","inReplyTo":"87fwugs7pf.fsf@picasso.cante.net","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Jan Krüger","fromEmail":"jk@jk.gs","sentAt":"2010-12-02T19:30:01Z","receivedAt":"2010-12-02T19:30:01Z","isPatch":true,"sender":{"key":"jk@jk.gs","avatar":"https://avatars.githubusercontent.com/u/1774?v=4"},"body":"[Cc unculled again; I will ignore all further posts from you until you\nstop culling or explain why you are ignoring all requests to stop\nculling.]\n\n--- Jari Aalto wrote:\n\n> Yes, that's the standard way of doing groups. Just like it's being\n> done in other manual pages that are huge. But it is not being done in\n> small manual pages. GNU project certainly doesn't in general.\n\nWhat makes the GNU project the gold standard? They've got some pretty\nweird conventions, such as their coding style.\n\n> I agree tat doing \"groups\" makes only sense on pages that have large\n> number of options. For a screenful, it's more distracting than worth.\n\nYou are \"agreeing with\" something I didn't say. That's not very helpful.\n\n> Well. In my experience (having watched others to learn) the manual\n> pages are not the source used for learning.\n\nThey were for me.\n\n> - They are technical documentation\n\nI want related things in technical documentation to be grouped.\n\n> - They are reference documentation\n\nI want related things in reference documentation to be grouped.\n\n> - They are visited, then discarded, visited and discarded.\n\nCorrect. Especially for that reason, I want related things to be\ngrouped. I don't want to scroll through the entire list of options just\nto find everything related to what I want to do.\n\n> - Someone throws up a git command (IRC #git, Blogs, Web page).\n> What do all those unreadable one letter options mean? Gosh they don't\n> even mean the save accross different git* programs.\n\nThe only realistic way around that is to stop using \n\n> > He searches manual pages A-Z, easy to spot all options. Not\n> > interested in related things. He tries to understand the\n> > command, script etc.\n\nBecause everyone always knows whether the desired option is called\n--skip-foo, --no-use-foo, --disable-foo, --no-foo, --antifoo or --bar?\n\nIn virtually all cases, I know what I want but not the name of the\noption. It rarely happens that I know the name of the option but not\nwhat it does.\n\n> This person just wants to solve a problem, get things done, the\n> faster the better. The easier the better, the less thinking the\n> better.\n\nAs mentioned, I believe that alphabetic ordering makes it harder and\ntake longer.\n\n> > He digestestes all. Related options, related pages, flipping\n> > form man to man as he knows all the glory details is just\n> > there.\n\nEven then, learning works better if you learn things grouped by\nsimilarities. Alphabetic ordering of the material just makes it harder.\nYou don't see the English teachers hand out vocabulary lessons in\nalphabetic order, do you?\n\n> There are 100+ manual pages in the git distribution. You get even\n> disoriented in shere numbers of them. And you have to throw dice to\n> figure out in what page that information might be you are currently in\n> need.\n\nThat is correct, but none of your patches change anything about that.\n\n> It's classical case of how to arrange information for easy retrieval.\n> Think Libraries as model.\n\nHave you ever been inside a library? The bookshelves are not ordered\nalphabetically. There is a section for physics and a section for\nzoology and a section for architecture. That makes it easier to find.\n\nIn fact, even before the advent of computers, the catalogs of libraries\nwere available in two forms: alphabetically ordered (which only helps\nif you know the exact name of what you are looking for) and ordered by\ncategory (which is pretty much the only way to find something if you\ndon't know exactly what you want, unless you want to read the whole\ncatalog back to front).\n\n\n\nIn any case, we can go around in circles forever on this. Our opinions\nare different, and if we don't accept each others' arguments, nothing\nwill ever come of this. The next stage in a productive discussion is to\neither stop bothering or to produce evidence. If you have any\nscientific evidence that alphabetically ordered lists make it easier to\nfind things the names of which you don't know, I'll be happy to look at\nit.\n\n-Jan\n"},{"id":"157202","messageId":"AANLkTimd3vksNYXaJwhygRConkKMfC7-UUufevhYY4ZK@mail.gmail.com","threadId":"25881","inReplyTo":"8762vdt7oo.fsf@picasso.cante.net","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Erik Faye-Lund","fromEmail":"kusmabite@gmail.com","sentAt":"2010-12-03T12:10:29Z","receivedAt":"2010-12-03T12:10:29Z","isPatch":true,"sender":{"key":"kusmabite@gmail.com","avatar":"https://avatars.githubusercontent.com/u/47073?v=4"},"body":"On Thu, Dec 2, 2010 at 12:05 AM, Jari Aalto wrote:\n> 2010-12-02 00:49 Kevin Ballard :\n>> You may want to invest in a spell-checker.\n>>  ... Manaula pages are not primarily used to learn things, they are\n>>  used as reference.\n>>\n>> Most certainly they are used to learn things. Especially with tools like git.\n>> Don't know what options you can give to git-diff? Read the manpage!\n>\n> That little word \"primarily.\" You don't find anyone who learnt from\n> manual page first is person is on his 20's.\n\nStop making things up. I'm in my 20's and learned Git primarily by\nreading the manual pages.\n"},{"id":"157207","messageId":"AANLkTinRHRqpLZg4awT4KwjvXDsQrwMprG=U1vgcZswo@mail.gmail.com","threadId":"25881","inReplyTo":"1291215526-11428-1-git-send-email-jari.aalto@cante.net","subject":"Re: [PATCH] git-commit.txt: Order options alphabetically","fromName":"Nguyen Thai Ngoc Duy","fromEmail":"pclouds@gmail.com","sentAt":"2010-12-03T13:03:59Z","receivedAt":"2010-12-03T13:03:59Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"I think you can start a fork now, with everything sorted\nalphabetically. Massive changes do not fit well in git development\nmodel. It causes lots of conflicts.\n\nI would like to hear any user feedback from such a fork. If it proves\nactually helpful for end users, it would be merged eventually.\n-- \nDuy\n"}]}