Re: The minibuffer vs. Dialog Boxes (Re: Making XEmacs be more up-to-date)

[Brady Montz <bradym@balestra.org>]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> >>>>> "Brady" == Brady Montz <bradym@balestra.org> writes:
> 
>     Brady> "Stephen J. Turnbull" <stephen@xemacs.org> 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