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:
> 
>     >> 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