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 12:26:05 +0200 Message-ID: <838uuxxsxu.fsf@gnu.org> References: <20140102095347.6834E381D0C@snark.thyrsus.com> <87fvp6bdd9.fsf_-_@ktab.red-bean.com> <83wqiixqbb.fsf@gnu.org> <20140102172804.GB13245@thyrsus.com> <83vby2xo6x.fsf@gnu.org> <20140102183432.GB13506@thyrsus.com> <83sit6xgfg.fsf@gnu.org> <8761q18kni.fsf@thinkpad.tsdh.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1388744779 9837 80.91.229.3 (3 Jan 2014 10:26:19 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 3 Jan 2014 10:26:19 +0000 (UTC) Cc: esr@thyrsus.com, kfogel@red-bean.com, emacs-devel@gnu.org To: Tassilo Horn Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jan 03 11:26:24 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 1Vz1xP-0000Eh-6C for ged-emacs-devel@m.gmane.org; Fri, 03 Jan 2014 11:26:23 +0100 Original-Received: from localhost ([::1]:49043 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vz1xO-0007v3-Oh for ged-emacs-devel@m.gmane.org; Fri, 03 Jan 2014 05:26:22 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:55586) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vz1xG-0007o4-K9 for emacs-devel@gnu.org; Fri, 03 Jan 2014 05:26:19 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Vz1x7-00081Q-Qd for emacs-devel@gnu.org; Fri, 03 Jan 2014 05:26:14 -0500 Original-Received: from mtaout20.012.net.il ([80.179.55.166]:48859) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vz1x7-00081F-Ik; Fri, 03 Jan 2014 05:26:05 -0500 Original-Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0MYT00200MAYR900@a-mtaout20.012.net.il>; Fri, 03 Jan 2014 12:26:04 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MYT002S0MBFN130@a-mtaout20.012.net.il>; Fri, 03 Jan 2014 12:26:04 +0200 (IST) In-reply-to: <8761q18kni.fsf@thinkpad.tsdh.org> 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:167142 Archived-At: > From: Tassilo Horn > Cc: esr@thyrsus.com, kfogel@red-bean.com, emacs-devel@gnu.org > Date: Fri, 03 Jan 2014 10:44:17 +0100 > > Eli Zaretskii writes: > > > They are impenetrable. The very first words will get you in a "WTF?" > > mode. > > All the terminology that's referred to in the git command man pages is > defined in one central place, the gitglossary(7) man page. First, there are no references to glossary in these places, and, as you know well, references in man pages are a PITA to use (unlike in Info). More importantly, the glossary, at least git's glossary, is not going to help here. Let's take this example I showed earlier: --reuse-message= Take an existing commit object, and reuse the log message and the authorship information (including the timestamp) when creating the commit. Clearly, what I need to know here, and is never explained, is how do I _reference_ a commit object. Now, here's what the glossary tells me: commit object An object which contains the information about a particular revision, such as parents, committer, author, date and the tree object which corresponds to the top directory of the stored revision. I hope you will agree with me that after reading this, I'm none the wiser. (There are a few hyperlinks in the text I show above, but none of them helps, either.) It actually tells me things that I could easily guessed myself, but never even hints at what I'm looking for. Reminds me of Microsoft documentation: to open a file click File->Open. > But in fact, basically every git command man page should list that > under SEE ALSO but doesn't. That's impractical: it would make the See Also section be of infinite length. Instead, the man page should either use a less formal style, or give examples (e.g., in parentheses) showing how the formal abstract terminology is related to practical issues. IOW, the authors should recognize that when I'm reading a man page, I usually look for answers to very practical questions, I'm not very interested in abstract relations between abstract opaque objects and concepts.