From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Tim X Newsgroups: gmane.emacs.help Subject: Re: Failing to see the allure of Emacs Date: Thu, 25 Mar 2010 19:42:53 +1100 Organization: Unlimited download news at news.astraweb.com Message-ID: <87mxxweqr6.fsf@rapttech.com.au> References: <877hp5e2op.fsf@lola.goethe.zz> <87pr2u7ie3.fsf@lola.goethe.zz> <9uudnY0F7J_qFjfWnZ2dnUVZ8oCdnZ2d@posted.visi> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: dough.gmane.org 1272998767 9718 80.91.229.12 (4 May 2010 18:46:07 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 4 May 2010 18:46:07 +0000 (UTC) To: help-gnu-emacs@gnu.org Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Tue May 04 20:46:05 2010 connect(): No such file or directory Return-path: Envelope-to: geh-help-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1O9N80-0007i9-Qp for geh-help-gnu-emacs@m.gmane.org; Tue, 04 May 2010 20:45:57 +0200 Original-Received: from localhost ([127.0.0.1]:60972 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1O9N80-0005Js-42 for geh-help-gnu-emacs@m.gmane.org; Tue, 04 May 2010 14:45:56 -0400 Original-Path: usenet.stanford.edu!news.glorb.com!news2.glorb.com!news.glorb.com!news.astraweb.com!border5.newsrouter.astraweb.com!not-for-mail Original-Newsgroups: gnu.emacs.help User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) Cancel-Lock: sha1:c46E0mwk+WLKt00jbsEqGdaPVYA= Original-Lines: 82 Original-NNTP-Posting-Host: 35c262c6.news.astraweb.com Original-X-Trace: DXC=22173j1BLhNm=FFS; n7SGML?0kYOcDh@JAlN_2e List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.help:73053 Archived-At: "akaiser@visi.com" writes: > I understand all the objections made to my saying that the emacs documentation > is incomplete, not up to date, and not readily usable, and I don't feel like > arguing the matter merely in technical detail. Some disagree. That's cool. > I wish them well. > > I have a relative who, before email, never wrote me. Once she had email, she > became a very lively correspondent. Paper wasn't her medium, but email was. > > Got the idea? > > I can read source code and I do; but there's a lot of source code, and most of > it is unrewarding reading. I can use info, but I don't like it. Please don't > tell me "use info", because info is designed and intended not for reading, but > for brief, casual online reference, and that is its cognitive organization. > It's poor as a learning tool, at least for text-based and example-based > learners like me. I'm a fast reader and I like hectares of well-indexed text > with lots of bookmarks: that's my best medium. > > If documentation is worth doing -- and I think it is -- then it's worth doing > well, in a way that meets the needs of the people who'll actually use it. In > that light, emacs documentation seems to me to hold up not too well. > > Look through this newsgroup for all the places a response has said "Have you > tried function such-and-such", or "that behavior is controlled by variable X > except that the default is variable Y". If the documentation were better, > much of that would disappear. > > When a literate, conscientious user with decades of programming experience, > decades of experience writing documentation, decades of using emacs, and > decades of support for free software says something like what I say, trying to > argue him down is unproductive. Of course I appreciate all the concrete help > I've gotten here and in other such forums, but it sure would be good to have > complete, up to date, readily usable documentation. (Smiling.) > Your statements are noted and on some levels your criticisms have some validity. However, the responses you recieved are largely due to the way you initially expressed the issue. Rather than saying that the existing format of the documentation is not one you find condusive to your specific style of learning or use, your statement was that emacs lacked documentation. These are two different things. Emacs has very comprehensive documentation. There is a reason it is often referred to as the self documenting editor. Most of the standard functions and variables have documentation that is easy to lookup. Emacs has a whole range of facilities to make it easy to find documentation on these things. Many may not appear intuitive to anyone unfamiliar with emacs and some people even take some time to become familiar with these facilities, but this is a different issue to documentation not existing. I would also suggest that your perspective on info would be worth re-examining. The three main info manuals that come with emacs all have extensive indexing, cross-references, bookmarks, etc. Due to the fact it was one of the very first hypertext type manual systems, it can appear very alien at first, but once you become accustomed to it, it is both useful for quick reference and lookup as well as general learning of concepts, techniques etc. Based on your style of learning, I would highly recommend the emacs lisp intro as a good starting point. This will give you the higher level explinations and instruction/example approach you prefer. The emacs manual is then sful for specific areas and the emacs lisp reference provides all the nitty gritty details you will need to write emacs lisp or get more specific details. Of course, the final point to mention is that emacs is an open source project and its documentation is only ever as good as what users are prepared to contribute. Based on your years of experience and your percieved weaknesses in what exists, perhaps trying to add/improve/extend what is there would be a more profitable use of time than complaining that what is there is no good because it doesn't suit your (and possibly others) way of learning. It is easy to criticise, but more rewarding to improve. If you see a weakness, do something about it. As soon as you show your actually more interested in improving the situation rather than just moaning about it, I expect a number of people will be keen to help. Tim -- tcross (at) rapttech dot com dot au