From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Apologia for bzr Date: Fri, 03 Jan 2014 10:57:32 +0200 Message-ID: <83d2k9xx1f.fsf@gnu.org> References: <20140102211452.GA28685@c3po> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1388739492 16582 80.91.229.3 (3 Jan 2014 08:58:12 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 3 Jan 2014 08:58:12 +0000 (UTC) Cc: esr@thyrsus.com, kfogel@red-bean.com, emacs-devel@gnu.org To: Toby Cubitt Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jan 03 09:58:19 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Vz0aA-0005Mx-7w for ged-emacs-devel@m.gmane.org; Fri, 03 Jan 2014 09:58:18 +0100 Original-Received: from localhost ([::1]:48672 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vz0a9-0003MA-Pm for ged-emacs-devel@m.gmane.org; Fri, 03 Jan 2014 03:58:17 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:37173) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vz0a3-0003M0-7A for emacs-devel@gnu.org; Fri, 03 Jan 2014 03:58:15 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Vz0Zy-0007sB-SQ for emacs-devel@gnu.org; Fri, 03 Jan 2014 03:58:11 -0500 Original-Received: from mtaout20.012.net.il ([80.179.55.166]:64507) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vz0Zy-0007s6-Ek for emacs-devel@gnu.org; Fri, 03 Jan 2014 03:58:06 -0500 Original-Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0MYT00200HXY3G00@a-mtaout20.012.net.il> for emacs-devel@gnu.org; Fri, 03 Jan 2014 10:57:33 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MYT001W2I7VUB90@a-mtaout20.012.net.il>; Fri, 03 Jan 2014 10:57:31 +0200 (IST) In-reply-to: <20140102211452.GA28685@c3po> X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 X-Received-From: 80.179.55.166 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:167124 Archived-At: > Date: Thu, 2 Jan 2014 21:14:52 +0000 > From: Toby Cubitt > Cc: esr@thyrsus.com, kfogel@red-bean.com, emacs-devel@gnu.org > > > They are impenetrable. The very first words will get you in a "WTF?" > > mode. Just try to read the first sentences of any random man page > > through a newbie's eyes. No term is ever explained before used -- do > > these guys even understand what it means to _explain_ things? It's as > > if you need to learn a whole new language. > > This is the Emacs mailing list I'm on, right? Emacs of "find" a file to > open it, files live in "buffers", "windows" aren't windows but "frames" > are, "kill" to cut and "yank" to paste fame? ;-) Indeed, and we all know that these are obstacles to newbies, so wise people (and git development is full of them, right?) shouldn't have gone that way. At least in Emacs we have an excuse that the bulk of the terminology developed when no other software provided any similar features; there's no such excuse for git (or bzr or hg). Anyway, there's a big difference here: in Emacs documentation, every term is explained before it is used, and rarely used terms have cross-references to where they are described. > > Here, a typical example from git-commit: > > > > DESCRIPTION > > > > Stores the current contents of the index in a new commit along with > > a log message from the user describing the changes. > > > > Huh? "Contents of the index"? I used to know what commit was, now I > > don't. > > The same could be said of most unix man pages. I'm reading Unix man pages for many years, and I must disagree: they are generally quite self-explanatory. Git is exceptional in this regard. > Good man pages aren't supposed to be tutorials. They're supposed to > be reference manuals, for looking up a terse and comprehensive > description of usage, options, switches, flags etc. Or at least, > that's how I've always understood (and used) them. You are missing the point: I didn't want a tutorial. I use VCSes for many years, and dVCSes for some; I already know what it means to commit a changeset and what is the basic workflow of using a dVCS. I wanted a "terse and comprehensive description" of the git's commit command, including all of its options. But when I read the above "Description" line, I start to question the correctness of my notion of what a commit is. Here, look at these "descriptions" of 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. If you don't already know what is "staging", you will never understand that this is one of the most important and useful options. Also, "haven't told Git about new files" fails to mention "git add". Once I've managed to grasp all that, I've made an alias for "commit -a", because that's what I almost always want. (And why isn't that the default, dammit?) --reuse-message= Take an existing commit object, and reuse the log message and the authorship information (including the timestamp) when creating the commit. "Commit object"? what's that? There's no reference to where this is explained; without such a reference, this "description" is non-instrumental, and thus useless. This problem is, of course, common to all the other options that refer to a "commit object", of which there are many on this page. --allow-empty Usually recording a commit that has the exact same tree as its sole parent commit is a mistake, and the command prevents you from making such a commit. This option bypasses the safety, and is primarily for use by foreign SCM interface scripts. "Recording a commit"? what's that? And is "commit that has the exact same tree as its sole parent commit" a complicated way of saying "no changes since the last commit", or is there some important subtlety here that I'm missing? Even bzr's commit docs does much better: --unchanged Commit even if nothing has changed. Etc., etc. -- I could go for hours on end with these examples. Mind you, I have this and other important git man pages open on my desktop at all times, and I consult them all the time. And I still don't get some of the details. And if you are still not convinced, let me show you what this "documentation" style would mean if the Emacs manual would use it. Let's take for example what the C-f key does in Emacs. You think you know what it does? Here's what the Emacs manual says: `C-f' Move forward one character (`forward-char'). Simple, self-explanatory, and concise. Also inaccurate, because that's not what really happens when you press C-f. Here's what does happen: `C-f' Move forward to the next visible buffer position, skipping any invisible text and lines hidden by selective display. The next redisplay cycle will display the cursor on the grapheme cluster to which the new buffer position belongs. If the new buffer position is the newline character, display the cursor on the empty glyph beyond the end of the line. If the new buffer position has a display property defined for it, display the cursor on the first glyph produced from that display property, or on the glyph that has the 'cursor' property defined for it. This is the accurate description of what C-f does, complete with references to about half a dozen of highly technical terms that I didn't bother to explain. I managed to be an efficient and happy Emacs user and hacker for 15 years without knowing most of this. It's not until I started seriously hacking the display engine 5 years ago that I became aware of all those details -- because I needed them then to be able to make the changes in the Emacs display. > And there *are* decent git tutorials available from the official web site > that explain things without assuming you already know how git works > (e.g. http://git-scm.com/book isn't bad). I DON'T WANT TUTORIALS, I've already read them. I want some decent reference documentation. I just don't want all the details about what's going on under the hood crammed down my throat every time I want to learn what some option does, or find an option that does what I need to accomplish. > Or maybe my problem is I'm a maths professor :) I didn't say that ;-)