Re: Documentation for emacspeak 6, Re: Documentation for emacspeak 6, Re: Documentation for emacspeak 6, Re: Documentation for emacspeak 6
To: Jim Van Zandt <firstname.lastname@example.org>
Subject: Re: Documentation for emacspeak 6, Re: Documentation for emacspeak 6, Re: Documentation for emacspeak 6, Re: Documentation for emacspeak 6
From: "T. V. Raman" <raman@Adobe.COM>
Date: Wed, 23 Apr 1997 19:38:22 -0700
Cc: raman@Adobe.COM, email@example.com
Comments: Hyperbole mail buttons accepted, v03.19.07.
Jim Van Zandt writes:
> >I am personally not sure that the automatically generated pages add
> >any value; since all that information and more is already available
> >via commands describe-function and describe-key. Also, in my
> >personal judgement the user is likely to get confused rather than
> >informed by the automatically generated pages, but I could be grossly
> If you know the key, or the function name, then describe-key or
> describe-function give you the description. However, if you don't
> know what functions might exist, let alone what their function names
> are, and don't want to hunt at random through the possible key
> sequences, then you need a collection of descriptions organized by
> functional area. That is why I wanted the automatically generated
> descriptions included.
True. But unfortunately, what comes out of the automatic generation
process is misleading and not too useful for the following reasons:
Consider a user who opens the manual to the chapter on dired.
He sees just one function documented there--
this is because emacspeak achieves the rest of its work by advising
at this point not only is the user confused-- he is unlikely to read
anything else or use dired mode,
concluding that the system is lacking features.
Also, the reason why it is important to learn to use describe
function is that that is how you learn all of emacs, and that is in
what is needed --emacspeak itself has little to learn in terms of
using dired etc.
And no--you don't need to know the name of the function to use
describe function --the incremental completion feature is there for
a good reason.
> describe-function and describe-key correspond to a reference manual
> (for reminding the user who already understands the system, but has
> forgotten the details). I was trying to write an introduction, for
> the new user.
The introduction is useful --what I question is the automatic
fragments pulled from modules like emacspeak-calendar.el and
> - Jim Van Zandt
Adobe Systems Tel: 1 (408) 536 3945 (W14-129)
Advanced Technology Group Fax: 1 (408) 537 4042
(W14 129) 345 Park Avenue Email: firstname.lastname@example.org
San Jose , CA 95110 -2704 Email: email@example.com
http://labrador.corp.adobe.com/~raman/raman.html (Adobe Internal)
Disclaimer: The opinions expressed are my own and in no way should be taken
as representative of my employer, Adobe Systems Inc.