Undo limit variables in Emacs Manual

Undo limit variables in Emacs Manual

[Richard M. Stallman]

The variables undo-limit, undo-strong-limit and undo-outer-limit are
in basic.texi because that's where undo is documented, but they are
anything but basic.  I think they are important enough to be mentioned
in the manual.  I'd like to move their documentation to a different
place in the manual, but I am not sure where.

Can anyone suggest a good place?

Re: Undo limit variables in Emacs Manual

[Chong Yidong]

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

> The variables undo-limit, undo-strong-limit and undo-outer-limit are
> in basic.texi because that's where undo is documented, but they are
> anything but basic.  I think they are important enough to be mentioned
> in the manual.  I'd like to move their documentation to a different
> place in the manual, but I am not sure where.
>
> Can anyone suggest a good place?

One possibility is to make a new subsection of Using Multiple Buffers,
which discusses the maximum size (currently described in Using
Multiple Buffers) and undo limit size of each buffer.

RE: Undo limit variables in Emacs Manual

[Drew Adams]

    The variables undo-limit, undo-strong-limit and undo-outer-limit are
    in basic.texi because that's where undo is documented, but they are
    anything but basic.  I think they are important enough to be mentioned
    in the manual.  I'd like to move their documentation to a different
    place in the manual, but I am not sure where.

    Can anyone suggest a good place?

I think they're in the right place. Move them to a subnode of `Undo',
perhaps. Options affecting a feature are usually mentioned along with the
feature.

Otherwise, if you want Basics to just be a Getting Started section, then
cover just a tiny bit on undo in Basics and have the complete doc of undo
elsewhere. In that case, do likewise for all of Basics: treat it as a
Getting Started section in all respects.

In any case, wherever undo is documented completely is where these options
should be documented.

Re: Undo limit variables in Emacs Manual

[Richard M. Stallman]

    One possibility is to make a new subsection of Using Multiple Buffers,
    which discusses the maximum size (currently described in Using
    Multiple Buffers) and undo limit size of each buffer.

Thanks, but that doesn't seem like a very natural place for it.

Re: Undo limit variables in Emacs Manual

[Richard M. Stallman]

    I think they're in the right place. Move them to a subnode of `Undo',
    perhaps. Options affecting a feature are usually mentioned along with the
    feature.

It's the right place _logically_, but it's wrong because it is complex
details which will be too much for the people reading that chapter to
swallow.

    Otherwise, if you want Basics to just be a Getting Started section, then
    cover just a tiny bit on undo in Basics and have the complete doc of undo
    elsewhere.

Perhaps that is the right thing to do.

Where should that new Undo section go?

RE: Undo limit variables in Emacs Manual

[Drew Adams]

        I think they're in the right place. Move them to a subnode
        of `Undo', perhaps. Options affecting a feature are usually
mentioned
        along with the feature.

    It's the right place _logically_, but it's wrong because it is complex
    details which will be too much for the people reading that chapter to
    swallow.

One way to deal with that is to mention that this info can be skipped if...
This is a reasonable approach, if you don't plan to create a Getting Started
section.

        Otherwise, if you want Basics to just be a Getting Started
        section, then cover just a tiny bit on undo in Basics and have the
        complete doc of undo elsewhere.

    Perhaps that is the right thing to do.

You passed over the other part of it:

       In that case, do likewise for all of Basics: treat it as a
       Getting Started section in all respects.

This is non-trivial. An alternative is to add a Getting Started item to the
main menu, but have it just send people to the tutorial. The tutorial no
doubt covers undo. Of course, that doesn't work for the written manual.

    Where should that new Undo section go?

It does not fit in any of the existing sections. Create a new section on
Undo (if you don't want it in Basic Editing). It's OK to have a one-node
section (this is the case for Major Modes, for instance) - that just
indicates that 1) it belongs alone and 2) it is important (since it is in
the top-level menu). But that node would cover everything about undo, so
some of its info would be repeated (if also in Basic Editing).

Other things _could_ be grouped with Undo in the same section, but the
grouping choice would be artificial, because undo touches everything except
for persistence (e.g. file saving). That is, almost everything can be
undone, and undoing can be used in editing text, fixing typos, moving point
and mark,....

Suggestion: I would leave things as they are, and just mention that this
stuff is for more advanced use.

Re: Undo limit variables in Emacs Manual

[Richard M. Stallman]

    You passed over the other part of it:

	   In that case, do likewise for all of Basics: treat it as a
	   Getting Started section in all respects.

That's because I am not interested in that suggestion.  I see no
reason to take a rigid approach about this.