[Prev][Next][Index][Thread][Search]

Re: Documentation for emacspeak 6, Re: Documentation for emacspeak 6, Re: Documentation for emacspeak 6, Re: Documentation for emacspeak 6

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
 > >wrong.
 > 
 > 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
 dired --
 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
 emacspeak-dired.el
 
 > 
 >                            - Jim Van Zandt

-- 
Best Regards,
--raman

      Adobe Systems                 Tel: 1 (408) 536 3945   (W14-129)
      Advanced Technology Group     Fax: 1 (408) 537 4042 
      (W14 129) 345 Park Avenue     Email: raman@xxxxxxxxxxx 
      San Jose , CA 95110 -2704     Email:  raman@xxxxxxxxxxx
      http://labrador.corp.adobe.com/~raman/raman.html (Adobe  Internal)
      http://www.cs.cornell.edu/Info/People/raman/raman.html  (Cornell)
-----------------------------------------------------------------------
    Disclaimer: The opinions expressed are my own and in no way should be taken
as representative of my employer, Adobe Systems Inc.
____________________________________________________________