Emacs FAQ for Emacs 22.1

Emacs FAQ for Emacs 22.1

[Romain Francoise]

I have installed a new version of the Emacs FAQ updated for the 22.1
release.  It should take into account all the changes of our upcoming
release (font lock mode now default, M-g prefix, new compile, new server
code, new max buffer size, etc).

I added a new node "New in Emacs 22": I'd appreciate if people could go
read it and improve it as they see fit, it still needs some work.
There's also a new node about SPC completion of file names in the
minibuffer.

If you maintain a package in Emacs, please take a few minutes to check
that all the information about your package in the FAQ is accurate.

Thanks,

-- 
Romain Francoise <romain@orebokech.com> | The sea! the sea! the open
it's a miracle -- http://orebokech.com/ | sea! The blue, the fresh, the
                                        | ever free! --Bryan W. Procter

Re: Emacs FAQ for Emacs 22.1

[Alexander Klimov]

Hi.

If `M-x customize-variable' is the preferred method then probably we
should replace things like

 Place the following Lisp form in your `.emacs' file:

     (setq scroll-step 1)

with

 Use M-x customize-variable to set scroll-step to 1

-- 
Regards,
ASK

Re: Emacs FAQ for Emacs 22.1

[Stefan Monnier]

> If `M-x customize-variable' is the preferred method then probably we
> should replace things like

>  Place the following Lisp form in your `.emacs' file:

>      (setq scroll-step 1)

> with

>  Use M-x customize-variable to set scroll-step to 1

Maybe it should even be replaced by

  M-x customize-variable RET scroll-convservatively RET

See docstring of scroll-step.


        Stefan

Re: Emacs FAQ for Emacs 22.1

[Romain Francoise]

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

> Maybe it should even be replaced by

>   M-x customize-variable RET scroll-convservatively RET

Yep, I've done that instead.

Thanks,

-- 
Romain Francoise <romain@orebokech.com> | The sea! the sea! the open
it's a miracle -- http://orebokech.com/ | sea! The blue, the fresh, the
                                        | ever free! --Bryan W. Procter

Re: Emacs FAQ for Emacs 22.1

[Luc Teirlinck]

Alexander Klimov wrote:

   If `M-x customize-variable' is the preferred method

Did we ever decide that?  I believe to remember that we decided
instead that use of Custom was completely optional.

Sincerely,

Luc.

Re: Emacs FAQ for Emacs 22.1

[David Kastrup]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> Alexander Klimov wrote:
>
>    If `M-x customize-variable' is the preferred method
>
> Did we ever decide that?  I believe to remember that we decided
> instead that use of Custom was completely optional.

Where is the contradiction?  That you are able to forego Custom does
not mean it isn't the preferred method.

It is _strongly_ preferred since it leads to variables getting
consistent values (unwitting users just love to confuse different
quotes, don't consider lists of strings and a single string different,
omit quotes where they are necessary and so on).  While we decided not
to introduce any changes that would render it impossible to set
variables without Custom, there is little point in documenting other
ways in the manuals.  People who want to access variables at the Lisp
level will just have to deal with Elisp and doc strings.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs FAQ for Emacs 22.1

[Luc Teirlinck]

David Kastrup wrote:

   While we decided not to introduce any changes that would render it
   impossible to set variables without Custom, there is little point
   in documenting other ways in the manuals.

We currently _do_ document both ways more or less equally in the Emacs
manual.  The Custom way in `(emacs)Easy Customization' and the .emacs
way in `(emacs)Init File'.  I do not see any reason to change that.
Several types of customization (say keybindings) can not even be done
through Custom.

Sincerely,

Luc.

Re: Emacs FAQ for Emacs 22.1

[David Kastrup]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> David Kastrup wrote:
>
>    While we decided not to introduce any changes that would render it
>    impossible to set variables without Custom, there is little point
>    in documenting other ways in the manuals.
>
> We currently _do_ document both ways more or less equally in the Emacs
> manual.  The Custom way in `(emacs)Easy Customization' and the .emacs
> way in `(emacs)Init File'.  I do not see any reason to change that.
> Several types of customization (say keybindings) can not even be done
> through Custom.

Which is a problem we need to address at some point of time.  It is
something people complain about.  There is little point in documenting
the use of Lisp where this interferes with Custom though.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs FAQ for Emacs 22.1

[Richard M. Stallman]

    If `M-x customize-variable' is the preferred method then probably we
    should replace things like

     Place the following Lisp form in your `.emacs' file:

	 (setq scroll-step 1)

    with

     Use M-x customize-variable to set scroll-step to 1

I am not sure.  Perhaps either way is ok, or it may depend
on the context.

Re: Emacs FAQ for Emacs 22.1

[Romain Francoise]

"Richard M. Stallman" <rms@gnu.org> writes:

> I am not sure.  Perhaps either way is ok, or it may depend
> on the context.

I think both methods have strengths: Customize is easy for beginners, so
we should encourage them to use it.  But learning how to program in
Emacs Lisp is important too, and setting up a .emacs file is the first
step.

What I've done in this particular case is mention the Customize method
first, and give the equivalent Lisp form as an alternative.

By the way, the FAQ doesn't cover Customize much: it explains what it
is, but not really how to use it.  Perhaps we should add a node named
"How do I customize Emacs?" explaining how to use Customize, and also
pointing to the "How do I setup a .emacs file?" node.  WDYT?

-- 
Romain Francoise <romain@orebokech.com> | The sea! the sea! the open
it's a miracle -- http://orebokech.com/ | sea! The blue, the fresh, the
                                        | ever free! --Bryan W. Procter

Re: Emacs FAQ for Emacs 22.1

[David Kastrup]

"Richard M. Stallman" <rms@gnu.org> writes:

>     If `M-x customize-variable' is the preferred method then probably we
>     should replace things like
>
>      Place the following Lisp form in your `.emacs' file:
>
> 	 (setq scroll-step 1)
>
>     with
>
>      Use M-x customize-variable to set scroll-step to 1
>
> I am not sure.  Perhaps either way is ok, or it may depend
> on the context.

While it depends in some manner on the context (the latter alternative
is certainly not helpful when talking about Lisp data structures and
programming practices), I think that with regard to .emacs forms, we
should generally prefer advertising Custom.  It saves us from dealing
with trouble from people who have in good faith used the wrong
set-form on some variable (when does one need to use setq-default?),
and who have, because of a lack of acquaintance with Lisp data
structures, used the wrong or illegal sexp on the right hand side of
stuff.

People who use setq should be comfortable with reading and
interpreting the documentation of variables.

So I think that in the Emacs manual, we should generally focus on
using customize.  There is nothing wrong with a chapter "how to
achieve things with Lisp in your .emacs by hand" or so (cars come with
service manuals, too), but for the general practice, I'd strongly
suggest we recommend using the knobs and dials provided for the user
where available instead of recommending fiddling with the engine
yourself.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs FAQ for Emacs 22.1

[David Kastrup]

"Richard M. Stallman" <rms@gnu.org> writes:

>     If `M-x customize-variable' is the preferred method then probably we
>     should replace things like
>
>      Place the following Lisp form in your `.emacs' file:
>
> 	 (setq scroll-step 1)
>
>     with
>
>      Use M-x customize-variable to set scroll-step to 1
>
> I am not sure.  Perhaps either way is ok, or it may depend
> on the context.

Post Scriptum: I think that in the electronic version of the manual,
there should be something like

    Use

        M-x customize-variable RET scroll-step RET

    in order to set scroll-step to 1

and the line with the customize-variable should be _clickable_ and
start customization.  gnus provides such buttons when it encounters
such a line in a Usenet posting or Email; it is a pity that our own
internal documentation does not work in that manner: it would
certainly make the manual more compelling.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: Emacs FAQ for Emacs 22.1

[Drew Adams]

    > I am not sure.  Perhaps either way is ok, or it may depend
    > on the context.

    While it depends in some manner on the context (the latter alternative
    is certainly not helpful when talking about Lisp data structures and
    programming practices), I think that with regard to .emacs forms, we
    should generally prefer advertising Custom.  It saves us from dealing
    with trouble from people who have in good faith used the wrong
    set-form on some variable (when does one need to use setq-default?),
    and who have, because of a lack of acquaintance with Lisp data
    structures, used the wrong or illegal sexp on the right hand side of
    stuff.

    People who use setq should be comfortable with reading and
    interpreting the documentation of variables.

    So I think that in the Emacs manual, we should generally focus on
    using customize.  There is nothing wrong with a chapter "how to
    achieve things with Lisp in your .emacs by hand" or so (cars come with
    service manuals, too), but for the general practice, I'd strongly
    suggest we recommend using the knobs and dials provided for the user
    where available instead of recommending fiddling with the engine
    yourself.

I generally agree with you here (focus on customize), except for relegating
all .emacs stuff to a separate section of the manual. It would be more
helpful, in general, to describe both methods together, for each individual
case (depending on the context). The customize method should of course be
emphasized and should be described first, but when the correponding Lisp
code for .emacs is _simple_ it should be presented too. IOW, I agree with
Romain about this.

Trying to do everything .emacs-related in a separate section of the manual
would be difficult and the result would be less useful, IMO. That doesn't
mean that we couldn't also have a section on .emacs practices (e.g. tips);
it just means that we shouldn't try to describe all the user-option Lisp
stuff in a .emacs section.

Of course, as you said, it all depends on the context.

Re: Emacs FAQ for Emacs 22.1

[Eli Zaretskii]

> From: Romain Francoise <romain@orebokech.com>
> Date: Wed, 14 Dec 2005 09:59:25 +0100
> Cc: emacs-devel@gnu.org
> 
> By the way, the FAQ doesn't cover Customize much: it explains what it
> is, but not really how to use it.  Perhaps we should add a node named
> "How do I customize Emacs?" explaining how to use Customize, and also
> pointing to the "How do I setup a .emacs file?" node.  WDYT?

I don't think it's a good idea.  The Emacs FAQ is not like most other
FAQs out there: it isn't supposed to be the first place people look
for any question or problem they might bump into.  The first place
they should look is in the Emacs manual, preferably through the index
search (`i') command.  And the Emacs manual already has a chapter that
describes Customize.  (It is, however, fine to have the node you
suggested that just points to the manual, IMHO.)

The FAQ should, IMO, cover minor or obscure issues not described in
the manual, places where to find extra packages, etc.  That is how it
was organized until now.

Re: Emacs FAQ for Emacs 22.1

[Richard M. Stallman]

    We currently _do_ document both ways more or less equally in the Emacs
    manual.  The Custom way in `(emacs)Easy Customization' and the .emacs
    way in `(emacs)Init File'.  I do not see any reason to change that.

We have no plans to deprecate the writing of setq calls, or to stop
teaching people to customize Emacs that way.  However, that's a slightly
different question from the one at hand.

The question at hand is, when giving beginners advice about how to
customize Emacs to do a specific thing, which method or methods should
we tell them to use?  I think it is good to customize for this.

Re: Emacs FAQ for Emacs 22.1

[Richard M. Stallman]

    By the way, the FAQ doesn't cover Customize much: it explains what it
    is, but not really how to use it.  Perhaps we should add a node named
    "How do I customize Emacs?" explaining how to use Customize, and also
    pointing to the "How do I setup a .emacs file?" node.  WDYT?

It is a good idea.

Re: Emacs FAQ for Emacs 22.1

[Richard M. Stallman]

    and the line with the customize-variable should be _clickable_ and
    start customization.

It seems like a good idea, for after the release, if someone wants to
do it.