Loading when viewing docstring of autoloaded function

Loading when viewing docstring of autoloaded function

[Chong Yidong]

It's a long-standing problem that documentation viewed with C-h * might
not make much sense if it refers to stuff defined in a library that has
not yet been loaded.

The most annoying aspect is that autoloaded functions often have
docstrings containing key substitution constructs, which are expanded
into `M-x FOO' because the relevant keymaps are not yet defined.  I'd
like to suggest a simple workaround: if an autoloaded function contains
key substitution constructs, just outright load the library where it was
defined.  There's not much point in being conservative about loading
libraries, since it is so fast nowadays.  See attached patch.

Alternatively, we could introduce a full-blown solution by adding a new
docstring substitution construct to invoke library loading, but I'm not
sure we need that.

Opinions?


=== modified file 'lisp/help-fns.el'
*** lisp/help-fns.el	2012-06-11 20:35:00 +0000
--- lisp/help-fns.el	2012-06-23 07:15:55 +0000
***************
*** 534,541 ****
        (let* ((advertised (gethash def advertised-signature-table t))
  	     (arglist (if (listp advertised)
  			  advertised (help-function-arglist def)))
! 	     (doc (condition-case err (documentation function)
!                     (error (format "No Doc! %S" err))))
  	     (usage (help-split-fundoc doc function)))
  	(with-current-buffer standard-output
  	  ;; If definition is a keymap, skip arglist note.
--- 534,550 ----
        (let* ((advertised (gethash def advertised-signature-table t))
  	     (arglist (if (listp advertised)
  			  advertised (help-function-arglist def)))
! 	     (doc-raw (condition-case err
! 			  (documentation function t)
! 			(error (format "No Doc! %S" err))))
! 	     ;; If the function is autoloaded, and its docstring has
! 	     ;; key substitution constructs, load the library.
! 	     (doc (progn
! 		    (and (eq (car-safe def) 'autoload)
! 			 (string-match "\\([^\\]=\\|[^=]\\|\\`\\)\\\\[[{<]"
! 				       doc-raw)
! 			 (load (cadr def) t))
! 		    (substitute-command-keys doc-raw)))
  	     (usage (help-split-fundoc doc function)))
  	(with-current-buffer standard-output
  	  ;; If definition is a keymap, skip arglist note.

RE: Loading when viewing docstring of autoloaded function

[Drew Adams]

> The most annoying aspect is that autoloaded functions often have
> docstrings containing key substitution constructs, which are expanded
> into `M-x FOO' because the relevant keymaps are not yet defined.  I'd
> like to suggest a simple workaround: if an autoloaded 
> function contains key substitution constructs, just outright load
> the library where it was defined.  There's not much point in being
> conservative about loading libraries, since it is so fast nowadays.
>  See attached patch.
> 
> Opinions?

Let the user decide.  Add a user option.  Make your new behavior the default, if
you like.  But give users an easy way to choose not to load stuff just for doc
strings.  The code change is trivial - it costs nothing to give users a say.

> Alternatively, we could introduce a full-blown solution by 
> adding a new docstring substitution construct to invoke library
> loading, but I'm not sure we need that.

That gives developers a choice, for the individual string.  Dunno whether that
is needed (no, a priori).

But give users the choice - they are the ones enjoying/suffering the
consequences.

Re: Loading when viewing docstring of autoloaded function

[Samuel Bronson]

On Jun 23, 2012, at 9:07 AM, Drew Adams wrote:

>> The most annoying aspect is that autoloaded functions often have
>> docstrings containing key substitution constructs, which are expanded
>> into `M-x FOO' because the relevant keymaps are not yet defined.
>
> Let the user decide.  Add a user option.  Make your new behavior the  
> default, if
> you like.  But give users an easy way to choose not to load stuff  
> just for doc
> strings.  The code change is trivial - it costs nothing to give  
> users a say.

How about just adding a "load module and rerender" button to the  
*Help* buffer in that case?

I've been annoyed by such docstrings, but at the same time I can see  
myself being much *more* annoyed at the proposed "just load it"  
solution in certain instances.  Some packages, like it or not, do  
things that may be undesirable when you so much as load them.

RE: Loading when viewing docstring of autoloaded function

[Drew Adams]

> >> The most annoying aspect is that autoloaded functions often have
> >> docstrings containing key substitution constructs, which 
> >> are expanded into `M-x FOO' because the relevant keymaps are
> >> not yet defined.
> >
> > Let the user decide.  Add a user option.  Make your new 
> > behavior the default, if you like.  But give users an easy
> > way to choose not to load stuff just for doc strings.  The code
> > change is trivial - it costs nothing to give users a say.
> 
> How about just adding a "load module and rerender" button to the  
> *Help* buffer in that case?
> 
> I've been annoyed by such docstrings, but at the same time I can see  
> myself being much *more* annoyed at the proposed "just load it"  
> solution in certain instances.  Some packages, like it or not, do  
> things that may be undesirable when you so much as load them.

Good, but again: give users the choice.  That behavior could be one of the
option values.

Re: Loading when viewing docstring of autoloaded function

[Stefan Monnier]

> instances.  Some packages, like it or not, do things that may be undesirable
> when you so much as load them.

These are bugs that need fixing anyway.


        Stefan

Re: Loading when viewing docstring of autoloaded function

[Samuel Bronson]

On Jul 2, 2012, at 12:21 PM, Stefan Monnier wrote:

>> instances.  Some packages, like it or not, do things that may be  
>> undesirable
>> when you so much as load them.
>
> These are bugs that need fixing anyway.


Yes, well, keep in mind that not all packages are part of Emacs, and  
some of their maintainers might think otherwise.

Re: Loading when viewing docstring of autoloaded function

[Stefan Monnier]

>>> instances.  Some packages, like it or not, do things that may be
>>> undesirable when you so much as load them.
>> These are bugs that need fixing anyway.
> Yes, well, keep in mind that not all packages are part of Emacs,

Don't worry: it's hard to forget.

> and some of their maintainers might think otherwise.

They're simply wrong, and wronger by the minute.

Emacs already loads file in various occasions without an explicit call
to `load' or `require' and even more so for files that have autoloaded
functions.

They may not like it, but they'll have to adapt,


        Stefan

Re: Loading when viewing docstring of autoloaded function

[Stefan Monnier]

> The most annoying aspect is that autoloaded functions often have
> docstrings containing key substitution constructs, which are expanded
> into `M-x FOO' because the relevant keymaps are not yet defined.  I'd
> like to suggest a simple workaround: if an autoloaded function contains
> key substitution constructs, just outright load the library where it was
> defined.  There's not much point in being conservative about loading
> libraries, since it is so fast nowadays.  See attached patch.

I don't mind auto-loading eagerly, but I do care about seeing
"autoloaded" on the first line of the description of the function,
because I often use C-h f <foo> RET to figure out whether that function
is autoloaded or is already fully defined.


        Stefan

Re: Loading when viewing docstring of autoloaded function

[Štěpán Němec]

On Sat, 23 Jun 2012 17:44:10 +0800
Chong Yidong wrote:

> It's a long-standing problem that documentation viewed with C-h * might
> not make much sense if it refers to stuff defined in a library that has
> not yet been loaded.
>
> The most annoying aspect is that autoloaded functions often have
> docstrings containing key substitution constructs, which are expanded
> into `M-x FOO' because the relevant keymaps are not yet defined.  I'd
> like to suggest a simple workaround: if an autoloaded function contains
> key substitution constructs, just outright load the library where it was
> defined.  There's not much point in being conservative about loading
> libraries, since it is so fast nowadays.  See attached patch.
>
> Alternatively, we could introduce a full-blown solution by adding a new
> docstring substitution construct to invoke library loading, but I'm not
> sure we need that.
>
> Opinions?

Other than the fact that this is not a solution but workaround, I don't
like the idea. Loading may be fast, but the loaded libraries use memory
and change the environment, which seems too much to pay for a docstring
or seeing a proper key binding (which you might never want to actually
use) to me.

So if you do this, please at least do provide an option to turn it off.

-- 
Štěpán

Re: Loading when viewing docstring of autoloaded function

[Stefan Monnier]

> Other than the fact that this is not a solution but workaround, I don't
> like the idea. Loading may be fast, but the loaded libraries use memory
> and change the environment, which seems too much to pay for a docstring
> or seeing a proper key binding (which you might never want to actually
> use) to me.

I'd bet you'd never notice the difference unless you were actively
looking for it.

> So if you do this, please at least do provide an option to turn it off.

If you do bump into a problem because of it, I'd be happy to accept
a patch from you (assuming you'd sign the required copyright paperwork,
of course).


        Stefan

Re: Loading when viewing docstring of autoloaded function

[Leo]

On 2012-06-24 13:09 +0800, Stefan Monnier wrote:
>> Other than the fact that this is not a solution but workaround, I don't
>> like the idea. Loading may be fast, but the loaded libraries use memory
>> and change the environment, which seems too much to pay for a docstring
>> or seeing a proper key binding (which you might never want to actually
>> use) to me.

These arguments seem valid. I think we are paying too much for too
little gain.

Leo

Re: Loading when viewing docstring of autoloaded function

[Andreas Röhler]

Am 24.06.2012 08:25, schrieb Leo:
> On 2012-06-24 13:09 +0800, Stefan Monnier wrote:
>>> Other than the fact that this is not a solution but workaround, I don't
>>> like the idea. Loading may be fast, but the loaded libraries use memory
>>> and change the environment, which seems too much to pay for a docstring
>>> or seeing a proper key binding (which you might never want to actually
>>> use) to me.
>
> These arguments seem valid. I think we are paying too much for too
> little gain.
>
> Leo
>
>
>


what about delivering an independent index, resp. to the way etags produces it?
I.e in this case command-name, docstring, source-file-name.

Andreas

Re: Loading when viewing docstring of autoloaded function

[Chong Yidong]

Andreas Röhler <andreas.roehler@online.de> writes:

> what about delivering an independent index, resp. to the way etags
> produces it?  I.e in this case command-name, docstring,
> source-file-name.

I don't see a feasible way to extract that information, short of
actually loading the library.

Re: Loading when viewing docstring of autoloaded function

[Andreas Röhler]

Am 24.06.2012 11:03, schrieb Chong Yidong:
> Andreas Röhler <andreas.roehler@online.de> writes:
>
>> what about delivering an independent index, resp. to the way etags
>> produces it?  I.e in this case command-name, docstring,
>> source-file-name.
>
> I don't see a feasible way to extract that information, short of
> actually loading the library.
>

think at indexing Emacs sources, i.e. it's documented symbols.
That index might be delivered with Emacs, but kept independent from loading the stuff.

eindex like etags

Andreas