Documentation on default.el vs site-start.el

Documentation on default.el vs site-start.el

[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

Re: Documentation on default.el vs site-start.el

[Kevin Rodgers]

Niels Möller wrote:
 > 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.

`C-h v site-run-file' also says that it is customizable, but that
seems pointless: by the time the customization is done (whether in
custom-file, .emacs, or default.el) the default site-run-file has
already been loaded.

-- 
Kevin Rodgers

Re: Documentation on default.el vs site-start.el

[Johan Bockgård]

Kevin Rodgers <ihs_4664@yahoo.com> writes:

> `C-h v site-run-file' also says that it is customizable, but that
> seems pointless: by the time the customization is done (whether in
> custom-file, .emacs, or default.el) the default site-run-file has
> already been loaded.

In CVS Emacs the docstring already contains the following paragraph:

   This variable is defined for customization so as to make it visible
   in the relevant context. However, actually customizing it is not
   allowed, since it would not work anyway. The only way to set this
   variable usefully is to set it while building and dumping Emacs.

-- 
Johan Bockgård

Re: Documentation on default.el vs site-start.el

[Richard M. Stallman]

    `C-h v site-run-file' also says that it is customizable, but that
    seems pointless: by the time the customization is done (whether in
    custom-file, .emacs, or default.el) the default site-run-file has
    already been loaded.

The doc string says this:

    This variable is defined for customization so as to make
    it visible in the relevant context.  However, actually customizing it
    is not allowed, since it would not work anyway.  The only way to set
    this variable usefully is to set it while building and dumping Emacs."