[ESS-bugs] ess-mode 5.2.7; cannot get help for contour()

[Martin Maechler]

>>>>> "StEgl" == Stephen Eglen <S.J.Eglen at damtp.cam.ac.uk>
>>>>>     on Fri, 1 Jul 2005 23:13:40 +0100 writes:

    StEgl> Sebastian Luque writes:
    >> On Fri, 3 Jun 2005 17:36:50 +0100,
    >> Stephen Eglen <S.J.Eglen at damtp.cam.ac.uk> wrote:
    >> >
    >> > I would suggest deleting all customization of comint variables in your
    >> > .emacs - and seeing if that works.  i.e. remove
    >> >
    >> >> setq comint-output-filter-functions
    >> 
    >> Ok, I had a chance to go over this tonight and found that
    >> ess-help-kill-bogus-buffers was causing my problems. I had it set to t at
    >> some point just to try. Once I removed this customization (the variable is
    >> nil by default), help works normally.

    StEgl> i took a look at this again.  A quick trace found the problem.  In the
    StEgl> help file for contour, you can see the following lines of text:

    StEgl> There is currently no documentation about the algorithm. The
    StEgl> source code is in '$R_HOME/src/main/plot3d.c'.

    StEgl> and the magic words "no documentation" then cause
    StEgl> ess-help-bogus-buffer-p to return the buffer position of that text! My
    StEgl> first thought then was to restrict the search to the first few hundred
    StEgl> characters of text.  Much to my surprise, the defun already has this
    StEgl> argumnet NR-FIRST, but the code has:

    StEgl> ;; search in first nr-first (default 120) chars only
    StEgl> (and nil (if (not nr-first) (setq nr-first 120)))

    StEgl> so nr-first, even when set to nil, stays as nil because of that
    StEgl> (and nil ...) at the start of the line.  anyone know why that code has
    StEgl> effectively been commented out?  It doesn't look like a recent change
    StEgl> - the most recent relevant log entry seems to be:

    StEgl> r1875 | maechler | 2002-01-10 17:23:49 +0000 (Thu, 10 Jan 2002) | 2 lines
    StEgl> ess-help-bogous-..buffer  fix

and the ChangeLog entry is slightly more helpful :

>> 2002-01-10  Martin Maechler  <maechler at stat.math.ethz.ch>
>> 
>> 	    * ess-help.el (ess-help-bogus-buffer-p): now also
>>               works in R when
>> 	      help.try.all.packages = TRUE.

Now, to show what I fixed then, look at the following in R (*R* buffer) 
-- note: this takes several minutes if you have `too' many
   packages available -- you may first do the following:

 > .libPaths({print(l <- .libPaths()); l[length(l)]})
 
	(which prints the old libPath -- that you can restitute
	 by    .libPaths(l)   afterwards 0

  > options("help.try.all.packages" = TRUE)
  > ?rlm

you get an  *help[R](rlm)*  buffer with the content

------------------------------------------------------------------------------
  Help for topic 'rlm' is not in any loaded package but can be found in the
  following packages:

    Package               Library
    MASS                  /u/maechler/R/D/r-devel/64-linux-inst/library
------------------------------------------------------------------------------

Now if the user consequently loads MASS :

    > library(MASS)

and types

    > ?rlm

again, I would have wanted that  the previous *help[R](rlm)*
buffer was considered  'bogous' and hence a new buffer would be
written with the correct content  {the real help on rlm() in MASS}.

But when I try all this now, it ``doesn't work'', i.e.,
I have to manually kill the  *help[R](rlm)* buffer
such that a new one is written.

This may well be because the messages are different in R now,
than they were in Jan.2002.

Note that *did* routinely have  
     options("help.try.all.packages" = TRUE) 
set back then, but had to stop it because it takes too long with
the 1061 so packages that I have available in my .libPaths() at work;
{on my laptop the count is "only" 633 :-}


    StEgl> So, shall we just put that code back in, but maybe increase the
    StEgl> default (and document it in the doc string) to be something like 300
    StEgl> characters in case there was a worry that 120 was not far enough to
    StEgl> look?

In any case, we should be more careful in determining when a
buffer is bogous {i.e. should n't be kept the next time help is
asked for on the same topic}.

Martin

    StEgl> Presumably the other pages that Sebastian found the error with is when
    StEgl> similar text "no documentation" is found in other manual pages.

(my guess too).