From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Xah Lee Newsgroups: gmane.emacs.help Subject: Re: some examples of emacs manual problem Date: Mon, 13 Sep 2010 05:27:00 -0700 (PDT) Organization: http://groups.google.com Message-ID: <25b7de41-8845-4ae1-a6db-92fcdedba94c@m17g2000prl.googlegroups.com> References: <271a3fcf-8845-4164-bbd8-9d687e8fbb6d@p22g2000pre.googlegroups.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Trace: dough.gmane.org 1291868903 8225 80.91.229.12 (9 Dec 2010 04:28:23 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Thu, 9 Dec 2010 04:28:23 +0000 (UTC) To: help-gnu-emacs@gnu.org Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Thu Dec 09 05:28:19 2010 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 1PQY78-0002Ch-Nk for geh-help-gnu-emacs@m.gmane.org; Thu, 09 Dec 2010 05:28:19 +0100 Original-Received: from localhost ([127.0.0.1]:37338 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PQY78-0001pw-0V for geh-help-gnu-emacs@m.gmane.org; Wed, 08 Dec 2010 23:28:18 -0500 Original-Path: usenet.stanford.edu!postnews.google.com!m17g2000prl.googlegroups.com!not-for-mail Original-Newsgroups: gnu.emacs.help Original-Lines: 96 Original-NNTP-Posting-Host: 67.180.85.8 Original-X-Trace: posting.google.com 1284380821 25953 127.0.0.1 (13 Sep 2010 12:27:01 GMT) Original-X-Complaints-To: groups-abuse@google.com Original-NNTP-Posting-Date: Mon, 13 Sep 2010 12:27:01 +0000 (UTC) Complaints-To: groups-abuse@google.com Injection-Info: m17g2000prl.googlegroups.com; posting-host=67.180.85.8; posting-account=bRPKjQoAAACxZsR8_VPXCX27T2YcsyMA User-Agent: G2/1.0 X-HTTP-UserAgent: Mozilla/5.0 (Windows; U; Windows NT 6.0; en-US) AppleWebKit/534.3 (KHTML, like Gecko) Chrome/6.0.472.55 Safari/534.3, gzip(gfe) Original-Xref: usenet.stanford.edu gnu.emacs.help:181263 X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Users list for the GNU Emacs text editor 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:76643 Archived-At: Hi stefan, i think the general situation is not about logical flaw or deficiency of emacs manual. Rather, it's generation gap. (side note: one example i've been thinking is to compare the classic english literature Gulliver's Travels. It is well acknowledged by all scholars to be a impecable piece of english work in grammar, style, story quality, satire execution, but if you read it today, you find it's exceedingly difficult to understand... requiring a background understanding all the politics, history, of europe at the time, as well as the writing style and vocabulary that's few hundred years old) back to emacs manual... to my mind, emacs manual problems can be solved rather without much difficulty, yet still remain accurate, true to emacs spirit, and i think agreeable to FSF's philosophy as well as any marketing spirit thrown in. Xah =E2=88=91 xahlee.org =E2=98=84 On Sep 13, 3:30=C2=A0am, Stefan Monnier wrote: > > (1) The writer presumes all users are beginners, with no experience in > > using a editor, even no experience in using a computer. Look at this > > sentence: > > =C2=A0 =C2=A0 Files are named units of text which are stored by the ope= rating > > system for you to retrieve later by name. > > O please, do i need to be told what's a file? > > We could/should probably remove that part, indeed. > > > (2) The author seems to have stopped in the 1980s, lots of tech terms > > have gone obsolete. Look at this: > > =C2=A0 =C2=A0 We use the term frame to mean the entire terminal screen = or > > graphical window used by Emacs. > > =C2=A0 =C2=A0 The main area of the frame, below the tool bar (if one ex= ists) and > > above the echo area, is called the window. > > Wow, your =E2=80=9Cframe=E2=80=9D is my =E2=80=9Cwindow=E2=80=9D, then = what the heck is your =E2=80=9Cwindow=E2=80=9D? > > In what way is that a problem in the manual? =C2=A0These are the terms us= ed > throughout Emacs's source code and for reasons of Emacs's design source > code names are very visible to the user, so if the manual doesn't > explain what we mean by "frame" and "window", that will be a lot more > confusing. > > > (3) Author is nostalgic of the past era; some advanced features of the > > past are no longer advanced. Example: > > =C2=A0 =C2=A0 You are reading about GNU Emacs, the GNU incarnation of t= he > > advanced, self-documenting, customizable, extensible editor Emacs. > > Huh? =E2=80=9Cself-documenting=E2=80=9D? What editor doesn't have docum= entation? > > =E2=80=9Cextensible, customizable=E2=80=9D? Nowadays many editors all c= an be extended > > or customized to various degrees. > > Very few programs have so much documentation available online. > Even many internal functions have online documentation. > And very few programs are nearly as deeply customizable. > Yes, it's a question of degree, but I think we're still ahead in > those areas. =C2=A0As for "advanced", well it's just a marketing term. > > > (4) Some features are too powerful, so explanation would be > > cumbersome: > > =C2=A0 =C2=A0 You can yank text from the kill ring into any position in= a > > buffer, including a position in a different buffer; the kill ring is > > shared by all buffers. > > The =E2=80=9Cyank & kill=E2=80=9D here is like =E2=80=9Ccut & paste=E2= =80=9D, then what's =E2=80=9Ckill ring=E2=80=9D? > > Perhaps that means when you cut many times, it won't leave just the > > last cut text, previous cuts are all still in =E2=80=9Ckill ring=E2=80= =9D. > > If you look up kill-ring in the index (e.g. by typing "i kill-ring RET" > in Info), you'll find the section "13.3 Yanking Earlier Kills" which > I hope explains it well enough. > > > (5) Because Emacs uses keyboard as its primary input, although these > > days we have mouse, but the core design philosophy still requires all > > functionalities be operable with a keyboard. For example, =E2=80=9Csele= cting a > > text=E2=80=9D can be easily done with a mouse, but the manual must use = lots > > words to explain how this is done with keyboard. Example: > > If you consider it useless to use the keyboard when you can use the > mouse, that's your problem. =C2=A0For people who find it handy to use the > keyboard, this section is useful. > > =C2=A0 =C2=A0 =C2=A0 =C2=A0 Stefan