bug#7989: 23.2.91; How do I update "local" autoloads?

bug#7989: 23.2.91; How do I update "local" autoloads?

[Reuben Thomas]

It just occurred to me that I should be able to generate autoloads for
my per-user site-lisp files. Unfortunately, there’s nothing in either
the Emacs or Elisp manual that I can see on how to do this, and the
behavior of Emacs is confusing.

I store my per-user Elisp files in ~/local/share/emacs/site-lisp, which
is of course on my load-path.

After browsing about the system a little, the obvious thing seemed to be
to run update-directory-autoloads on this directory. This indeed
collected all the autoloads from this directory, but did two quite
surprising things:

1. It updated all the autoloads, not just the ones for that directory.
This seems to contradict the docstring for update-directory-autoloads,
which says “Update loaddefs.el with all the current autoloads from
DIRS”, and I had supplied precisely one directory, interactively.

2. It then wrote the resulting loaddefs.el to the source directory for
Emacs. This is very clear in the code, in autoload-generated-file, but
I’m at a loss to explain it: I can see this is useful while building
Emacs, but I can’t see what possible utility it has when using an
installed Emacs.

Then, there is very little documentation in the Emacs manual. There’s a
bit more detail in the Elisp manual, but I still can’t find anything
there about the default loaddefs.el, nor can I find how to change where
update-directory-autoloads writes its results, nor in any case where
loaddefs.el files are searched for.

By examining the layout of the ELPA files in my ~/.emacs.d directory, I
can see that it manages to write loaddefs files with different names,
one to each downloaded package’s directory, which are presumably loaded
when I start Emacs, so undoubtedly, there is a way to achieve everything
I want, but I just can’t easily find out how (presumably, reading
package.el would be a good next step).

However, surely it ought to be easier than this for a user simply to
generate loaddefs.el files for their own files?

Apologies if I’ve missed something obvious; if I haven’t, then I’d be
very happy, given an explanation of what I’m supposed to do, to write
patches for the Emacs manual and/or relevant docstrings.


In GNU Emacs 23.2.91.4 (i686-pc-linux-gnu, GTK+ Version 2.22.0)
 of 2011-01-13 on canta
Windowing system distributor `The X.Org Foundation', version 11.0.10900000
Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_GB.UTF-8
  value of $XMODIFIERS: nil
  locale-coding-system: utf-8-unix
  default enable-multibyte-characters: t

Major mode: Emacs-Lisp

Minor modes in effect:
  recentf-mode: t
  show-paren-mode: t
  savehist-mode: t
  minibuffer-electric-default-mode: t
  iswitchb-mode: t
  icomplete-mode: t
  global-whitespace-mode: t
  global-auto-revert-mode: t
  desktop-save-mode: t
  yas/global-mode: t
  yas/minor-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-n C-n C-s d i r e c t o r y C-a C-n C-n C-n C-n C-n 
C-n C-n C-s g e n e r a t e d - f i l e C-a <down> 
<down> <down> <down> <down> <down> <down> <up> <up> 
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <right> <right> <right> <right> <right> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <down> C-a M-x r e p o r t C-g M-x r 
e p o r t b u g <backspace> <backspace> <backspace> 
- e m a c s - b u g <return>

Recent messages:
Wrote /home/rrt/repo/emacs-23/lisp/loaddefs.el
Mark set [2 times]
Mark saved where search started
Quit
Type C-x 1 to remove help window.  
Mark saved where search started [3 times]
call-interactively: End of buffer [2 times]
Quit [2 times]
Mark saved where search started [3 times]
Quit

Load-path shadows:
/home/rrt/.emacs.d/elpa/ruby-mode-1.1/ruby-mode hides /usr/share/emacs-snapshot/site-lisp/ruby1.8-elisp/ruby-mode
/home/rrt/local/share/emacs/site-lisp/popup hides /usr/local/share/emacs/23.2.91/site-lisp/auto-complete/popup
/home/rrt/local/share/emacs/site-lisp/fuzzy hides /usr/local/share/emacs/23.2.91/site-lisp/auto-complete/fuzzy
/home/rrt/.emacs.d/elpa/css-mode-1.0/css-mode hides /usr/local/share/emacs/23.2.91/site-lisp/css-mode/css-mode
/home/rrt/.emacs.d/elpa/dictionary-1.8.7/link hides /usr/local/share/emacs/23.2.91/site-lisp/dictionary-el/link
/home/rrt/.emacs.d/elpa/dictionary-1.8.7/connection hides /usr/local/share/emacs/23.2.91/site-lisp/dictionary-el/connection
/home/rrt/.emacs.d/elpa/dictionary-1.8.7/dictionary-init hides /usr/local/share/emacs/23.2.91/site-lisp/dictionary-el/dictionary-init
/home/rrt/.emacs.d/elpa/dictionary-1.8.7/dictionary hides /usr/local/share/emacs/23.2.91/site-lisp/dictionary-el/dictionary
/home/rrt/local/share/emacs/site-lisp/dict hides /usr/local/share/emacs/23.2.91/site-lisp/emacs-goodies-el/dict
/home/rrt/.emacs.d/elpa/css-mode-1.0/css-mode hides /usr/local/share/emacs/23.2.91/lisp/textmodes/css-mode
/home/rrt/.emacs.d/elpa/ruby-mode-1.1/ruby-mode hides /usr/local/share/emacs/23.2.91/lisp/progmodes/ruby-mode
/home/rrt/.emacs.d/elpa/css-mode-1.0/css-mode hides /usr/share/emacs/site-lisp/css-mode/css-mode
/usr/local/share/emacs/23.2.91/site-lisp/auctex/tex-info hides /usr/share/emacs/site-lisp/auctex/tex-info
/usr/local/share/emacs/23.2.91/site-lisp/auctex/context-nl hides /usr/share/emacs/site-lisp/auctex/context-nl
/usr/local/share/emacs/23.2.91/site-lisp/auctex/context-en hides /usr/share/emacs/site-lisp/auctex/context-en
/usr/local/share/emacs/23.2.91/site-lisp/auctex/latex hides /usr/share/emacs/site-lisp/auctex/latex
/usr/local/share/emacs/23.2.91/site-lisp/auctex/tex-mik hides /usr/share/emacs/site-lisp/auctex/tex-mik
/usr/local/share/emacs/23.2.91/site-lisp/dictionary-el/lpath hides /usr/share/emacs/site-lisp/auctex/lpath
/usr/local/share/emacs/23.2.91/site-lisp/auctex/tex-buf hides /usr/share/emacs/site-lisp/auctex/tex-buf
/usr/local/share/emacs/23.2.91/site-lisp/auctex/tex-jp hides /usr/share/emacs/site-lisp/auctex/tex-jp
/usr/local/share/emacs/23.2.91/site-lisp/auctex/tex-bar hides /usr/share/emacs/site-lisp/auctex/tex-bar
/usr/local/share/emacs/23.2.91/site-lisp/auctex/tex hides /usr/share/emacs/site-lisp/auctex/tex
/usr/local/share/emacs/23.2.91/site-lisp/auctex/multi-prompt hides /usr/share/emacs/site-lisp/auctex/multi-prompt
/usr/local/share/emacs/23.2.91/site-lisp/auctex/tex-fptex hides /usr/share/emacs/site-lisp/auctex/tex-fptex
/usr/local/share/emacs/23.2.91/site-lisp/auctex/tex-font hides /usr/share/emacs/site-lisp/auctex/tex-font
/usr/local/share/emacs/23.2.91/site-lisp/auctex/tex-fold hides /usr/share/emacs/site-lisp/auctex/tex-fold
/usr/local/share/emacs/23.2.91/site-lisp/auctex/texmathp hides /usr/share/emacs/site-lisp/auctex/texmathp
/usr/local/share/emacs/23.2.91/site-lisp/auctex/context hides /usr/share/emacs/site-lisp/auctex/context
/usr/local/share/emacs/23.2.91/site-lisp/auctex/font-latex hides /usr/share/emacs/site-lisp/auctex/font-latex
/usr/local/share/emacs/23.2.91/site-lisp/auctex/bib-cite hides /usr/share/emacs/site-lisp/auctex/bib-cite
/usr/local/share/emacs/23.2.91/site-lisp/auctex/toolbar-x hides /usr/share/emacs/site-lisp/auctex/toolbar-x
/usr/local/share/emacs/23.2.91/site-lisp/auctex/tex-style hides /usr/share/emacs/site-lisp/auctex/tex-style

Features:
(shadow sort mail-extr message sendmail ecomplete rfc822 mml mml-sec
password-cache mm-decode mm-bodies mm-encode mailcap mail-parse rfc2231
rfc2047 rfc2045 qp ietf-drums mailabbrev nnheader gnus-util netrc
mm-util mail-prsvr gmm-utils mailheader canlock hashcash mail-utils
emacsbug apropos conf-mode newcomment pp multi-isearch jka-compr
find-func help-mode view tabify edebug noutline outline time-date vc-bzr
sha1 hex-util autoload dired longlines vc-git face-remap filladapt
flyspell completing-help recentf tree-widget wid-edit uniquify paren
savehist minibuf-eldef iswitchb icomplete whitespace autorevert time
cus-start cus-load desktop server php-mode etags cc-langs cc-mode
cc-fonts cc-menus cc-cmds cc-styles cc-align cc-engine cc-vars cc-defs
speedbar sb-image ezimage dframe lua-mode regexp-opt comint ring
ropemacs pymacs smart-quotes ffap ispell etags-update
auto-dictionary-autoloads css-mode-autoloads dictionary-autoloads
diff-git-autoloads dired-isearch-autoloads full-ack-autoloads
guess-style-autoloads js2-mode-autoloads kill-ring-search-autoloads
lambdacalc-autoloads magit-autoloads mv-shell-autoloads
ruby-mode-autoloads tumble-autoloads http-post-simple-autoloads package
reporter advice advice-preload yasnippet help-fns derived edmacro kmacro
easymenu assoc cl cl-19 muse-autoloads emacs-goodies-el
emacs-goodies-custom emacs-goodies-loaddefs easy-mmode bbdb-autoloads
preview-latex tex-site auto-loads tooltip ediff-hook vc-hooks
lisp-float-type mwheel x-win x-dnd font-setting tool-bar dnd fontset
image fringe lisp-mode register page menu-bar rfn-eshadow timer select
scroll-bar mldrag mouse jit-lock font-lock syntax facemenu font-core
frame cham georgian utf-8-lang misc-lang vietnamese tibetan thai
tai-viet lao korean japanese hebrew greek romanian slovak czech european
ethiopic indian cyrillic chinese case-table epa-hook jka-cmpr-hook help
simple abbrev loaddefs button minibuffer faces cus-face files
text-properties overlay md5 base64 format env code-pages mule custom
widget hashtable-print-readable backquote make-network-process dbusbind
system-font-setting font-render-setting gtk x-toolkit x multi-tty emacs)

-- 
http://rrt.sc3d.org/

bug#7989: 23.2.91; How do I update "local" autoloads?

[Eli Zaretskii]

> From: Reuben Thomas <rrt@sc3d.org>
> Date: Sat, 05 Feb 2011 13:06:15 +0000
> Cc: 
> 
> 1. It updated all the autoloads, not just the ones for that directory.
> This seems to contradict the docstring for update-directory-autoloads,
> which says “Update loaddefs.el with all the current autoloads from
> DIRS”, and I had supplied precisely one directory, interactively.

Please show exactly how you invoked update-directory-autoloads, with
all its arguments.

> 2. It then wrote the resulting loaddefs.el to the source directory for
> Emacs. This is very clear in the code, in autoload-generated-file, but
> I’m at a loss to explain it: I can see this is useful while building
> Emacs, but I can’t see what possible utility it has when using an
> installed Emacs.

See generated-autoload-file.

bug#7989: 23.2.91; How do I update "local" autoloads?

[Reuben Thomas]

[-- Attachment #1: Type: text/plain, Size: 2180 bytes --]

On 5 February 2011 15:33, Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Reuben Thomas <rrt@sc3d.org>
> > Date: Sat, 05 Feb 2011 13:06:15 +0000
> > Cc:
> >
> > 1. It updated all the autoloads, not just the ones for that directory.
> > This seems to contradict the docstring for update-directory-autoloads,
> > which says “Update loaddefs.el with all the current autoloads from
> > DIRS”, and I had supplied precisely one directory, interactively.
>
> Please show exactly how you invoked update-directory-autoloads, with
> all its arguments.
>

M-x update-directory-autoloads RET ~/local/share/emacs/site-lisp RET


> > 2. It then wrote the resulting loaddefs.el to the source directory for
> > Emacs. This is very clear in the code, in autoload-generated-file, but
> > I’m at a loss to explain it: I can see this is useful while building
> > Emacs, but I can’t see what possible utility it has when using an
> > installed Emacs.
>
> See generated-autoload-file.
>

I did, but I didn't see anything useful there; sorry if I'm being obtuse.
The apparently relevant bits say:

generated-autoload-file is a variable defined in `autoload.el'.
Its value is "loaddefs.el"

Documentation:
*File M-x update-file-autoloads puts autoloads into.
A `.el' file can set this in its local variables section to make its
autoloads go somewhere else.

First, there's something missing here: it doesn't explain that if the value
is a plain file name, then a directory is automatically prepended (and
that's the source directory, which seems odd).

Secondly, it doesn't tell me what to do to get the files I've installed in
my own directory to have a sensible loaddefs.el written. From reading the
above, there are two options:

1. I could annotate all the files I install in my personal site-lisp
directory with generated-autoload-file settings. That seems perverse.

2. I could set generated-autoload-file before running
update-directory-autoloads, but I have no idea whether this would have a
deleterious effect on, for example, ELPA. In a nutshell, why would I want to
set a global variable for a one-off operation?

-- 
http://rrt.sc3d.org

[-- Attachment #2: Type: text/html, Size: 2921 bytes --]

bug#7989: 23.2.91; How do I update "local" autoloads?

[Chong Yidong]

> *File M-x update-file-autoloads puts autoloads into.
> A `.el' file can set this in its local variables section to make its
> autoloads go somewhere else.
>
> First, there's something missing here: it doesn't explain that if the
> value is a plain file name, then a directory is automatically
> prepended (and that's the source directory, which seems odd).

I've clarified the docstring, thanks.

> 2. I could set generated-autoload-file before running
> update-directory-autoloads, but I have no idea whether this would have
> a deleterious effect on, for example, ELPA. In a nutshell, why would I
> want to set a global variable for a one-off operation?

ELPA isn't affected, because it explicitly binds generated-autoload-file
to an absolute filename before running update-directory-autoloads.

I agree that the interactive interfaces to update-file-autoloads and
update-directory-autoloads are not very friendly.  Maybe when they are
called interactively, they should prompt for generated-autoload-file.

bug#7989: 23.2.91; How do I update "local" autoloads?

[Stefan Monnier]

> I agree that the interactive interfaces to update-file-autoloads and
> update-directory-autoloads are not very friendly.  Maybe when they are
> called interactively, they should prompt for generated-autoload-file.

AFAICT the global default value of generated-autoload-file is only used
when you use those functions interactively, which was the case back when
Emacs did not bootstrap and didn't have much of a lisp/Makefile.
AFAICT nowadays these functions are rarely if ever used interactively to
rebuild Emacs's own loaddefs.el, so the default value is basically
never useful and should probably default to something like nil.


        Stefan

bug#7989: 23.2.91; How do I update "local" autoloads?

[Chong Yidong]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> AFAICT the global default value of generated-autoload-file is only used
> when you use those functions interactively, which was the case back when
> Emacs did not bootstrap and didn't have much of a lisp/Makefile.
> AFAICT nowadays these functions are rarely if ever used interactively to
> rebuild Emacs's own loaddefs.el, so the default value is basically
> never useful and should probably default to something like nil.

I've committed a change that does this, and makes the interactive
functions prompt for an autoload file.

bug#7989: 23.2.91; How do I update "local" autoloads?

[Reuben Thomas]

On 4 May 2011 16:40, Chong Yidong <cyd@stupidchicken.com> wrote:
>
> I've committed a change that does this, and makes the interactive
> functions prompt for an autoload file.

Thanks!

-- 
http://rrt.sc3d.org