Documentation on default.el vs site-start.el

[nisse@lysator.liu.se (Niels Möller)]

I'm using

GNU Emacs 21.4.1 (i386-pc-linux-gnu, X toolkit, Xaw3d scroll bars) of 2005-03-17 on trouble, modified by Debian

and the emacs manual that describes itself as "it corresponds to GNU
Emacs version 21.3".

The manual describes "site-start.el" in the section "The Init File,
`~/.emacs'", like this:

     Your site may also have a "site startup file"; this is named
  `site-start.el', if it exists.  Like `default.el', Emacs finds this
  file via the standard search path for Lisp libraries.  Emacs loads this
  library before it loads your init file.  To inhibit loading of this
  library, use the option `-no-site-file'.  *Note Initial Options::.

This doesn't explain when one should use default.el and when one
should use site-start.el. The documentation string for site-run-file
in startup.el gives the following advice:

  Don't use the `site-start.el' file for things some users may not like.
  Put them in `default.el' instead, so that users can more easily
  override them.  Users can prevent loading `default.el' with the `-q'
  option or by setting `inhibit-default-init' in their own init files,
  but inhibiting `site-start.el' requires `--no-site-file', which
  is less convenient.

I think this is good advice, and it would make sense to include it
also in the manual. And perhaps also explain further what's the
motivation for having two different site configuration files.

(At the moment, I'm also bug-reporting a debian package that puts
"things some users may not like" into configuration files loaded with
site-start.el, and I'm trying to explain why that is a bad idea.
Clearer documentation on what site-start.el really is intended for
would help people to use it in the right way).

Regards,
/Niels