Coding Convections - Enabling a feature by loading a file

Coding Convections - Enabling a feature by loading a file

[Peter S Galbraith]

Hi all,

The coding conventions say:

   * When a package provides a modification of ordinary Emacs behavior,
     it is good to include a command to enable and disable the feature,
     Provide a command named `WHATEVER-mode' which turns the feature on
     or off, and make it autoload (*note Autoload::).  Design the
     package so that simply loading it has no visible effect--that
     should not enable the feature.(2)  Users will request the feature
     by invoking the command.

The first part is fine (`include a command to enable and disable the
feature').  But what is the rationale behind the loading of a package
having no visisble effect?  If the only purpose of a package is to
enable a feature (say changing the cursor to a bar), why ask users to
do:

     (require 'bar-cursor)
     (bar-cursor-mode 1)

instead of only:

     (require 'bar-cursor)

?

I am perfect happy for packages to install themselves correctly once
loaded without having to go through more hoops.

Thanks,
Peter

Re: Coding Convections - Enabling a feature by loading a file

[Stefan Monnier]

>>>>> "Peter" == Peter S Galbraith <psg@debian.org> writes:
> feature').  But what is the rationale behind the loading of a package
> having no visisble effect?  If the only purpose of a package is to

A package might be loaded implicitly by something like `customize'
just to get the list of groups/variables it offers.  You wouldn't
want to turn a feature ON just because you're browsing some of the
related variables (you might even be browsing something that you didn't
know was related).

>      (require 'bar-cursor)
>      (bar-cursor-mode 1)
> instead of only:
>      (require 'bar-cursor)

It should be only

   (bar-cursor-mode 1)

because bar-cursor-mode should be autoloaded.


        Stefan

Re: Coding Convections - Enabling a feature by loading a file

[Peter S Galbraith]

Stefan Monnier <monnier+gnu.emacs.help/news/@flint.cs.yale.edu> wrote:

> >>>>> "Peter" == Peter S Galbraith <psg@debian.org> writes:
> > feature').  But what is the rationale behind the loading of a package
> > having no visisble effect?  If the only purpose of a package is to
> 
> A package might be loaded implicitly by something like `customize'
> just to get the list of groups/variables it offers.  You wouldn't
> want to turn a feature ON just because you're browsing some of the
> related variables (you might even be browsing something that you didn't
> know was related).

But this is only true if its defcustoms are copied to another file,
right?  How else could it get loaded?  Or do you mean if the user loads
it in order to see its customizations?
 
> >      (require 'bar-cursor)
> >      (bar-cursor-mode 1)
> > instead of only:
> >      (require 'bar-cursor)
> 
> It should be only
> 
>    (bar-cursor-mode 1)
> 
> because bar-cursor-mode should be autoloaded.

But this is only true if autoloads are generated.  Is it standard
practice to do that for files added to someones site directory or for a
user under $HOME?  I know I've never done that (I might start now that I
think of it).

I'm not talking about a file are is part of Emacs, but one distributed
separately.  How strongly should we adhere to that coding convention?

Thanks!
-- 
Peter S. Galbraith, Debian Developer          <psg@debian.org>
                                 http://people.debian.org/~psg
GPG key 1024/D2A913A1 - 97CE 866F F579 96EE  6E68 8170 35FF 799E

Re: Coding Convections - Enabling a feature by loading a file

[Stefan Monnier]

> But this is only true if autoloads are generated.  Is it standard
> practice to do that for files added to someones site directory or for a
> user under $HOME?  I know I've never done that (I might start now that I
> think of it).

It's true that it's rarely done, but I think it should be fixed.
My install.el package embryo tries to do that by providing a standard way
for people to install a "package" and that procedure adds the
necessary autoloads.

> I'm not talking about a file are is part of Emacs, but one distributed
> separately.  How strongly should we adhere to that coding convention?

Why should there be a difference ?  After all, any unbundled package is
just a potential bundled package.


        Stefan


PS: Another circumstance where a package might get loaded implicitly
    is during byte-compilation.  There's probably others.

Re: Coding Convections - Enabling a feature by loading a file

[Lute Kamstra]

Peter S Galbraith <psg@debian.org> writes:

[...]

> But what is the rationale behind the loading of a package having no
> visisble effect?  If the only purpose of a package is to enable a
> feature (say changing the cursor to a bar), why ask users to do:
>
>      (require 'bar-cursor)
>      (bar-cursor-mode 1)
>
> instead of only:
>
>      (require 'bar-cursor)
>
> ?
>
> I am perfect happy for packages to install themselves correctly once
> loaded without having to go through more hoops.

I'm not familiar with bar-cursor.el, but in general a library can
implement more than one feature.  In such a case, it is usually not
obvious which feature to turn on.  It is best to turn nothing on
automatically and let the user choose which of the features to use by
explicitly turning them on.  Even if a library contains only one
feature now, features might be added in future versions.  Such changes
won't surprise the user if nothing is turned on upon loading the
library.

Furthermore, some other library could (require 'bar-cursor) to use
some function that is defined in bar-cursor.el.  In such a case, you
usually do not want bar-cursor-mode to be turned on.

Lute.

-- 
(spook) => "unclassified Montenegro Serbian"
(insert-file-contents "~/.signature") => (error "`~/.signature' too rude")

Re: Coding Convections - Enabling a feature by loading a file

[Peter S Galbraith]

Lute Kamstra <Lute.Kamstra@cwi.nl> wrote:

> Peter S Galbraith <psg@debian.org> writes:
> 
> [...]
> 
> > But what is the rationale behind the loading of a package having no
> > visisble effect?  If the only purpose of a package is to enable a
> > feature (say changing the cursor to a bar), why ask users to do:
> >
> >      (require 'bar-cursor)
> >      (bar-cursor-mode 1)
> >
> > instead of only:
> >
> >      (require 'bar-cursor)
> >
> > ?
> >
> > I am perfect happy for packages to install themselves correctly once
> > loaded without having to go through more hoops.
> 
> I'm not familiar with bar-cursor.el, but in general a library can
> implement more than one feature.  In such a case, it is usually not
> obvious which feature to turn on.  It is best to turn nothing on
> automatically and let the user choose which of the features to use by
> explicitly turning them on.  Even if a library contains only one
> feature now, features might be added in future versions.  Such changes
> won't surprise the user if nothing is turned on upon loading the
> library.
> 
> Furthermore, some other library could (require 'bar-cursor) to use
> some function that is defined in bar-cursor.el.  In such a case, you
> usually do not want bar-cursor-mode to be turned on.
> 
> Lute.

Yeah, those are good reasons.  You guys have convinced me that the added
steps are worth it in the long run.

Thanks for your comments,

Peter