From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Phil Sung Newsgroups: gmane.emacs.devel Subject: Re: guided tour suggestions Date: Mon, 11 Jun 2007 16:01:09 -0400 Message-ID: <87vedus1kq.fsf@phil.mit.edu> References: <200705031803.l43I3Yd29129@f7.net> <87mz0lfxy5.fsf@phil.mit.edu> <87k5umdqos.fsf@stupidchicken.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1181592084 13543 80.91.229.12 (11 Jun 2007 20:01:24 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 11 Jun 2007 20:01:24 +0000 (UTC) Cc: David House , mathias.dahl@gmail.com, drew.adams@oracle.com, emacs-devel@gnu.org To: Chong Yidong Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jun 11 22:01:22 2007 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1Hxq4n-0002Kn-KR for ged-emacs-devel@m.gmane.org; Mon, 11 Jun 2007 22:01:22 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Hxq4n-0004h8-AB for ged-emacs-devel@m.gmane.org; Mon, 11 Jun 2007 16:01:21 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Hxq4i-0004gl-Sp for emacs-devel@gnu.org; Mon, 11 Jun 2007 16:01:17 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Hxq4i-0004gZ-ED for emacs-devel@gnu.org; Mon, 11 Jun 2007 16:01:16 -0400 Original-Received: from biscayne-one-station.mit.edu ([18.7.7.80]) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1Hxq4h-0008EK-Sf for emacs-devel@gnu.org; Mon, 11 Jun 2007 16:01:16 -0400 Original-Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103]) by biscayne-one-station.mit.edu (8.13.6/8.9.2) with ESMTP id l5BK1A1O011602; Mon, 11 Jun 2007 16:01:10 -0400 (EDT) Original-Received: from phil.mit.edu (PHIL.MIT.EDU [18.243.2.47]) (authenticated bits=0) (User authenticated as psung@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id l5BK19Qi008093 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Mon, 11 Jun 2007 16:01:09 -0400 (EDT) In-Reply-To: <87k5umdqos.fsf@stupidchicken.com> (Chong Yidong's message of "Sat\, 02 Jun 2007 16\:52\:51 -0400") User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.0.95 (gnu/linux) X-Scanned-By: MIMEDefang 2.42 X-Spam-Score: 0.00 X-detected-kernel: Solaris 9 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:72641 Archived-At: Sorry for the delay, I just got back from traveling. Thanks, all, for your suggestions. I've incorporated some of them and am thinking about how to implement the rest. I had been sitting on another draft which improves the sometimes awkward wording of the original version, and removes a little bit of material which is probably not of interest to beginners, so I've posted that. The in-progress version is here: http://stuff.mit.edu/iap/emacs/emacs-guided-tour-1.html Chong Yidong writes: > parts of the text in are too small to be legible Indeed, they are. Sorry about that. (I think it's something about the GNU stylesheet which I didn't notice before.) > In the Mark section, under the column labelled "When you...", the first entry > is "C-SPC". To be grammatical, this should be "type C-SPC". In the same > column, the entry "Exit a search (C-s or C-r)" is confusing... Fixed. > In the section on Isearch, the sentioned "You can incremental search > backwards" is grammatically fishy. Maybe "You can perform a backward > incremental search" is better. Changed. > In "Integration with common tools", I think we should recommend M-x man > instead of M-x woman. Changed. My basis for recommending M-x woman was that it was more colorful... ;-) > In the Emacs Help Facilities section, the suggestion to run Info with M-x > info can probably use C-h i instead. Ah, of course. Actually, I should have just suggested C-h r (info-emacs-manual) here. By the way, what is the preferred way to direct the reader to a specific Info node? Should I suggest (info "(emacs)NODE") (as I have been doing) or something like C-h r g NODE RET? > Also, I wonder if the tour should mention transient mark mode. Now that > font-lock-mode is on by default, transient mark mode is IMHO the reigning > champion for Feature That Should Be Turned On By Default But Isn't. I've added a paragraph for transient-mark-mode. Drew Adams writes: >> 1. The screenshots on http://www.gnu.org/software/emacs/tour/ are too >> zoomed out to be legible. I guess the reason for this is so that >> the entire Emacs window can be displayed. I think it would be >> better if the screenshot images on the main page of the tour are at >> 100% zoom, and cropped so that only the relevant part of the window >> is seen. When you click on each image, it should bring you to a >> bigger imager showing the entire Emacs window. > > Generally agree. However, showing full-size screenshots takes a lot more > screen space and so interrupts the reading flow. Show at least some of the > screenshots (e.g. ediff, mail) reduced and uncropped, when it is important > to give an idea of the entire layout (but still let you click to get > full-size). > > * [screenshot ideas] I've added and improved some screenshots. Most are cropped to show some interesting part of the frame. * The first part has improved screenshots for a C buffer, EDiff, and Dired, and a new one for GDB. I'll redo Gnus and shell shortly. * I've added screenshots, in their respective sections, for isearch, compile, GDB, grep, function documentation, and the manual. >> 5. In the section on Macros, I think we should recommend the F3 and F4 >> keys new to Emacs 22, since they are easier to use than the old >> kmacro keys. Done. > No real opinion on that, except that some keyboards don't have function > keys, and some people never leave the home keys. I suppose. But the fact that the manual recommends F3 and F4 justifies this change. > The section should be called "Keyboard Macros" (or "Recording Interactions" > or some such), however, not Macros. Changed. > The order seems a bit weird: It seems odd to tour tramp, server, and > registers before "Common Emacs concepts" such as prefix args, modes, and > minibuffer, for instance. > "Useful features" is a catch-all category. It's content needs to be moved > (restructure). For example, move keyboard macros to the editing section. > I would say users should tour "Learning about Emacs" near the beginning (and > not call it Learning _more_ about Emacs) - teaching how to learn is one of > the first things to get across, not the last. Indeed, the ordering is sort of weird. This material is adapted from a lecture, so suggestions for a more sensible organization are welcome. The thing is, I wanted to convey "why Emacs is useful" with only a secondary goal of conveying "how to use Emacs"-- after all, this tour is not, and does not try to be, the Manual or the Tutorial. But modulo that I will try to mention the help features earlier and put things in a better order. > It might be useful to state that, unlike other editors, you can, in effect, > undo past undo actions (without going into detail trying to describe exactly > what that means). I agree that the undo pictures are somewhat intimidating in this context, so I've removed them. (Sorry, David.) > The region is not presented as such in a dedicated section (the closest > thing is the Mark section) - it is mentioned here and there. Narrowing > should be presented with the region. I've added a section for the region. Narrowing and transient-mark-mode are in it. > We might mention more about Emacs's features for editing code. Things such > as indentation that we take for granted, for instance. Good point. I'll think about adding more material in this vein. David House writes: > Again, I'd like to keep [phases-of-moon], for the sake of humour and to give > the impression that Emacs has everything you'd ever want, and then some. This captures my sentiment about the tour. I hope that it will get readers to think "Well, if Emacs has Tetris, then maybe it has _____ too" and then to actually look for features in the docs or on the web. Regards, Phil