From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Brady Montz Newsgroups: gmane.emacs.devel Subject: Re: The minibuffer vs. Dialog Boxes (Re: Making XEmacs be more up-to-date) Date: 22 Apr 2002 09:54:09 -0700 Sender: emacs-devel-admin@gnu.org Message-ID: References: <87vgal3w79.fsf@tleepslib.sk.tsukuba.ac.jp> <87vgak30cw.fsf@tleepslib.sk.tsukuba.ac.jp> NNTP-Posting-Host: localhost.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1019494653 16553 127.0.0.1 (22 Apr 2002 16:57:33 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Mon, 22 Apr 2002 16:57:33 +0000 (UTC) Cc: xemacs-design@xemacs.org, emacs-devel@gnu.org Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.33 #1 (Debian)) id 16zh89-0004Ir-00 for ; Mon, 22 Apr 2002 18:57:33 +0200 Original-Received: from fencepost.gnu.org ([199.232.76.164]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 16zh8v-0001cK-00 for ; Mon, 22 Apr 2002 18:58:21 +0200 Original-Received: from localhost ([127.0.0.1] helo=fencepost.gnu.org) by fencepost.gnu.org with esmtp (Exim 3.34 #1 (Debian)) id 16zh7z-0002Km-00; Mon, 22 Apr 2002 12:57:23 -0400 Original-Received: from c64-255-216-95.sea1.cablespeed.com ([64.255.216.95] helo=sandman.balestra.org) by fencepost.gnu.org with esmtp (Exim 3.34 #1 (Debian)) id 16zh5D-0001zo-00 for ; Mon, 22 Apr 2002 12:54:31 -0400 Original-Received: (from bradym@localhost) by sandman.balestra.org (8.10.2/8.10.2) id g3MGs9J03253; Mon, 22 Apr 2002 09:54:09 -0700 (PDT) X-Authentication-Warning: sandman.balestra.org: bradym set sender to bradym@balestra.org using -f Original-To: "Stephen J. Turnbull" In-Reply-To: <87vgak30cw.fsf@tleepslib.sk.tsukuba.ac.jp> Original-Lines: 106 User-Agent: Gnus/5.0808 (Gnus v5.8.8) XEmacs/21.5 (bamboo) Errors-To: emacs-devel-admin@gnu.org X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.0.9 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: Emacs development discussions. List-Unsubscribe: , List-Archive: Xref: main.gmane.org gmane.emacs.devel:3042 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:3042 "Stephen J. Turnbull" writes: > >>>>> "Brady" == Brady Montz writes: > > Brady> "Stephen J. Turnbull" writes: > > >> Hm, I use them all the time. My only complaint is that we only > >> have mouse bindings for them. I'd like to be able to type RET > >> on them. Bonus points if C-x o TAB TAB RET Does The Right > >> Thing. > > Brady> I didn't say you didn't use them. Just that I haven't seen > Brady> many doc strings that take much advantage of them for the > Brady> "see also" purpose. > > Brady> Taking my running example of sort-lines, It's doc tells me > Brady> about it's config variable sort-fold-case, but I had to do > > I would say that's exactly right for a docstring. I agree. > Brady> a find-library sort to look at the source to find out about > Brady> sort-paragraphs, sort-pages, sort-fields, ... > > That may be what _you_ resorted to, but besides Eli's suggestion of > C-h a sort- RET, there's C-h C-f sort-lines RET (output appended > below; taller than you would get on a 80x24 TTY, but the line > containing "sort-paragraphs" would almost certainly appear). My > conclusion is that we don't need to redo all the docstrings, but > rather to educate people better about the available help functions. I don't think the doc strings need changing. When I piped in on this thread, I viewed it as a thread about the UI, specifically for beginers. I see very little in the UI which makes these various options obvious, and the biggest single struggle I have helping emacs beginners is helping them learn how to find out information. Currently, people have suggested three ways to get to sort-paragraph from sort-lines: open sort.el (my fallback approach), apropos, or Info-elisp-ref, and putting xrefs in the doc strings. Now, as for more xrefs in the docstring. Not good. Bad. For one thing, they are too likely to get stale. For another, I think the cross-referencing mechanism should be seperate from the little pieces that are being referenced. I don't think it's a good interface if there's a different way to get to the info node from the doc string than vice versa. I don't think I ever suggested this, but I can see why people might think that. My thinking more is that: I want xrefs, docstrings have a few of those, but they don't do enough for that, people writing those strings generally aren't putting xrefs in, and that's probably for the best cause xrefs are something different. Back to my example. So far, three people have suggested three ways. First, not all of these ways work for every function (for example, C-h C-f gnus just failed for me), nor for every situation (for example, starting from a keybinding instead of a function name), none of them are apparant from the UI (I can only judge from xemacs, and the inability of the beginners I've known to find them). Now, once I found sort-paragraph, it was a "duh I shoulda C-h a and that would have found it." But the fact is that even after 14 years, I hadn't ever seen it. And I know I've read the docs for sort-lines multiple times. I don't think I'm unusually dense, and I've seen many posts to various lists and newsgroups where people, even well known long-time users, had been missing out on "easy to find" functionality. One of the points from way back in this thread was that emacs isn't as easy to use as it could be. I think things like this are one reason why. Emacs can do a lot, and you can do most anything with it, including finding out everything you want to about how it works. But there's just this "friction" between emacs and the user, where things that could be much more simple or obvious just require that extra bit of work that can result in the user just not doing it. ------- So, time to experiment with some code. I'd like to know any idioms that people have for finding information. In particular, I'd like to know the situations in which those idioms are used. For example, knowing a fair bit about emacs, I generally start with my comfortable turf which is a known similar function, then I apropos, search the info pages or source, or a known phrase (generally with nice emacs terms like buffers, regions, yank, that are stirring up so much trouble elsewhere on this thread :)), and I google search. The more familiar I am with a package, the less likely I am to start with the info pages or menus. Probably shouldn't email those suggestions on this thread. I'm keeping this reply on this thread, but any replies to that last query should probably go on their own thread or straight to me. I think I'm viewing the documentation as a bit of a graph, with nodes being what you know or where you are. Examples: the function name, the key command, the phrase describing what you want, the info node, the main source file for the package, a menu entry, the customize page. And there's ways to get from each to the other. Which paths are most common, which are the most useful, and which entry points are most likely? With any luck, an interactive tutorial similar to the ones they gave me back in grade school about how to find stuff in the library will suffice. -- Brady Montz bradym@balestra.org