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: 23 Apr 2002 11:20:43 -0700 Sender: emacs-devel-admin@gnu.org Message-ID: References: <87vgal3w79.fsf@tleepslib.sk.tsukuba.ac.jp> <87vgak30cw.fsf@tleepslib.sk.tsukuba.ac.jp> <7263-Mon22Apr2002224014+0300-eliz@is.elta.co.il> <87bscbysbm.fsf@tleepslib.sk.tsukuba.ac.jp> <878z7euysa.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 1019586094 7516 127.0.0.1 (23 Apr 2002 18:21:34 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Tue, 23 Apr 2002 18:21:34 +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 1704v0-0001x7-00 for ; Tue, 23 Apr 2002 20:21:34 +0200 Original-Received: from fencepost.gnu.org ([199.232.76.164]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 1704wI-0002Vc-00 for ; Tue, 23 Apr 2002 20:22:54 +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 1704um-0005T6-00; Tue, 23 Apr 2002 14:21:20 -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 1704uO-0005Rj-00 for ; Tue, 23 Apr 2002 14:20:56 -0400 Original-Received: (from bradym@localhost) by sandman.balestra.org (8.10.2/8.10.2) id g3NIKhw06900; Tue, 23 Apr 2002 11:20:43 -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: <878z7euysa.fsf@tleepslib.sk.tsukuba.ac.jp> Original-Lines: 97 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:3121 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:3121 "Stephen J. Turnbull" writes: > >>>>> "Brady" == Brady Montz writes: > > Brady> "Stephen J. Turnbull" writes: > > >> But more what? Does that mean go from the docstring to Info > >> page (and should that be the User Guide or the Lispref?), or > >> the mode's keymap wallpaper, or the mode docstring, or > >> hyperapropos, or Info index? Or (dare I say it?) help-on-help? > > Brady> Sounds like a good start to me. > > But describing it took 5 lines, and putting in the xrefs themselves > won't be much less ... many docstrings are two or three. Overkill, I > think, and pretty quickly very annoying. > > TBH, I don't see the kind of concrete example/suggestion here that I > could take and run with, not yet. I would personally be quite happy with the concrete suggestion I made of a single, uniform browsing interface where I can trivially get from one piece of documentation to another. The analogy I used was a web-ring. So, how about a doc-ring between: 1. the info node 2. the source 3. an example/howto 4. the docstring 5. the key binding 6. the mode or greater package a command is in 7. related commands/variables (by name, location, explicitly listed by a doc writer, whatever). 8. the customize page 9. home pages of packages (like gnus's home page). With uniform programming and user interfaces it should be extendable. If someone writes something that can handle a "I want to capitalize a paragraph" request, he should be able to plug it in. If someone else writes something that finds in your init files where the variable you're looking up was set, that might be something people would want. Given any of those, I want to be able to, with a single fluid click or flick of my eye, be able to find as many of the others as possible. More importantly, I want my friends and roommate to be able to, so they'll stop struggling and pestering me, and start using emacs effectively. The main problem they seem to have is that they discover a few of that list (1, 4 mainly), and only after weeks of struggle before they ask me do they find out about the others. "Oh, C-h m, that's cool! I wish I'd known about that sooner." Examples, in particular, are hard to find. That might be another issue altogether. I'm wondering about the fixation on xrefs within the docstrings. It could be from the desire to drill down on a specific example, but I'm wondering if there's been a miscommunication. My primary interest is in better xrefs between the doc domains, rather than within them. Improving the first would probably help the second though. For example, I'm editing a C++ file. What's the simplest way for me to pull up the info docs on the current major and minor modes? What's the quickest way to get a list of the configuration options affecting them? The quickest way to set them? Are there any minor modes people commonly use with C++ files that I'm not using? I think that the last would require some extra doc-writing, but the others could be handled by a better interface guiding the user from one thing (say, the output of C-h m) to the next (the info page for each mode in there, or the appropirate customize pages). I'll try to get a rough draft of this in the next few weeks, when I can tear myself away from MSDN :). > Brady> However, I have found MSDN, especially the newer content > Brady> which appears to have a higher quality standard, to be very > Brady> useful though. I've satisfied 90% of my windows API > Brady> questions by wandering about there, and have learned lots > Brady> of unasked for but very useful stuff along the way. > > This is exactly what Eli and I recommend that you do with the Emacs > docs ... wander about. Hm. I see some difference between Emacs and > Windows, but enough similarity in scale and scope to justify the > analogy. Wandering is a good recommendation. My recommendation is to find a way to make this easy for beginners. Most of my attempts to get beginners to wander through the emacs realm result in them becoming irritated with the interface it provides to do so, and they generally bail. That is my main point, and thrust of my examples. As for how to do this, I only have suggestions. -- Brady Montz bradym@balestra.org