From: frederik@ofb.net To: git@vger.kernel.org Subject: de-alphabetizing the documentation Date: Fri, 6 Jul 2018 13:04:23 -0700 Message-ID: <20180706200423.GC6343@ofb.net> (raw) Dear Git Developers, I am trying to learn how to use Git but I've been put off by not knowing where to start. I would like to start with the 'git' man page, but it lists the Git subcommands in alphabetical order, rather than in an order which would be useful for learners. For example, I'm not sure how often 'git bisect' is used, but it is strange to see it listed before 'git init' and 'git clone'. I know that 'gittutorial' exists, and I've indeed worked through it and some other Git tutorials. However, these are more like lists of examples that should come at the end of a typical manual page. I don't think they are intended as canonical references for the program functionality. At some point I would like to use the main 'git' manual page as my primary source of documentation. This would be easier if it were designed to be read straight through. I wonder if someone familiar with Git could list the commands in an order which makes more sense for learning, for example in the order in which they were invented by Git developers, or in the reverse order of frequency of use by a typical Git user. This could easily be derived from the shell history of someone who is reading this. (cat ~/.bash_history; cut -d ";" -f 2 ~/.zsh_history) | grep '^git ' | cut -d ' ' -f 2 | sort | uniq -c | sort -nr I would like to have this list for personal use, but once it is created, perhaps someone could also add it to the main Git man page. The list could be added at the top of the "GIT COMMANDS" section. Alternatively, and I think preferably, the entries in that section could be rearranged into this order. Finally, perhaps the same listing and/or reordering could be done for other important manual pages, like 'gitglossary'. Presumably 'gitglossary' should be sorted topologically, so that each term is defined prior to any terms depending on it. I'm not sure why alphabetical order was decided upon, but it seems less than useful in the information age, when people can easily search for text electronically. Maybe at some point someone decided to "clean up" the presentation by alphabetizing the manual page. As a user who is more concerned with substance, it is annoying to encounter such an emphasis on the superficial, which seems unworthy of such an important piece of software. Thank you, Frederick Eaton
next reply other threads:[~2018-07-06 20:37 UTC|newest] Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top 2018-07-06 20:04 frederik [this message] 2018-07-06 21:16 ` Jonathan Nieder 2018-07-06 21:18 ` Jonathan Nieder 2018-07-06 23:21 ` frederik 2018-07-06 23:47 ` Jonathan Nieder 2018-07-08 1:09 ` frederik 2018-07-24 19:52 ` frederik 2018-07-24 21:11 ` Jonathan Nieder 2018-08-11 2:30 ` frederik 2018-08-13 18:17 ` Junio C Hamano 2019-02-19 17:54 ` [PATCH 0/1] de-alphabetize command list Frederick Eaton 2019-02-21 18:05 ` frederik 2019-03-11 9:04 ` frederik 2019-03-11 14:38 ` Jacob Keller 2019-02-19 17:54 ` [PATCH] Prioritize list of commands appearing in git(1), via command-list.txt. Don't invoke 'sort' in Documentation/cmd-list.perl Frederick Eaton 2018-07-07 4:25 ` de-alphabetizing the documentation Theodore Y. Ts'o 2018-07-06 21:32 ` Eric Sunshine
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style List information: http://vger.kernel.org/majordomo-info.html * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20180706200423.GC6343@ofb.net \ --to=frederik@ofb.net \ --cc=git@vger.kernel.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
git@vger.kernel.org list mirror (unofficial, one of many) This inbox may be cloned and mirrored by anyone: git clone --mirror https://public-inbox.org/git git clone --mirror http://ou63pmih66umazou.onion/git git clone --mirror http://czquwvybam4bgbro.onion/git git clone --mirror http://hjrcffqmbrq6wope.onion/git # If you have public-inbox 1.1+ installed, you may # initialize and index your mirror using the following commands: public-inbox-init -V1 git git/ https://public-inbox.org/git \ git@vger.kernel.org public-inbox-index git Example config snippet for mirrors. Newsgroups are available over NNTP: nntp://news.public-inbox.org/inbox.comp.version-control.git nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git nntp://news.gmane.io/gmane.comp.version-control.git note: .onion URLs require Tor: https://www.torproject.org/ code repositories for the project(s) associated with this inbox: https://80x24.org/mirrors/git.git AGPL code for this site: git clone https://public-inbox.org/public-inbox.git