Re: *scratch* buffer documentation

[Eli Zaretskii]

> From: Jean-Christophe Helary <address@hidden>
> Date: Thu, 26 Dec 2019 09:54:02 +0900
> 
> > This is a standard Emacs behavior with any buffer that doesn't visit a
> > file, so I'm not sure why you expected to see anything special in this
> > case.
> 
> Interesting. I've used emacs on and off for more than 20 years, and much more 
> in the last few years, and I was never aware of that.

That's okay.  I use Emacs every day for the last 27 years, hack it for
the last 25, and I'm still learning something new at least once a week.

> 19 Using Multiple Buffers
> 
> → nothing about that default behavior

Because this is not about using buffers in general.

> 19.1 Creating and Selecting Buffers
> 
> → nothing about that default behavior

Because this is not about creating or selecting a buffer.

> 19.4 Killing Buffers
> 
> Buried at the bottom of the info about C-x k:

Let's not exaggerate, okay?  The _entire_ description of "C-x k" is
this:

     ‘C-x k’ (‘kill-buffer’) kills one buffer, whose name you specify in
  the minibuffer.  The default, used if you type just <RET> in the
  minibuffer, is to kill the current buffer.  If you kill the current
  buffer, another buffer becomes current: one that was current in the
  recent past but is not displayed in any window now.  If you ask to kill
  a file-visiting buffer that is modified, then you must confirm with
  ‘yes’ before the buffer is killed.

That's all of the 4 sentences of the description, and the 4th one
describes the feature we are talking about.  Saying this is "buried at
the bottom" does the manual an injustice, IMO.

> If that is how/where the default behavior is specified, maybe it
> ought to be in a more preeminent location.

IMO, this is exactly the location where it should be, as this is the
most prominent location for describing what happens when buffers are
killed.  More about that below.

> also, on the same page:
>
> " The command ‘M-x clean-buffer-list’ is a convenient way to purge them; it 
> kills all the unmodified buffers that you have not used for a long time."
> 
> which kind of suggests that modified buffers would not be killed

Modified buffers will not be killed by clean-buffer-list, that's
true.  But not in general, and not  by kill-buffer.  clean-buffer-list
is a separate command, with its own separate rules.  That's why its
name starts with "clean", not "kill".

> and thus contradict the above "default".

Do you still think there is a contradiction?

> And that's it, as far as I can tell. No other part of the Buffer chapter give 
> relevant information about what would happen to modified/unmodified buffers 
> that are killed. Maybe the information is located some place else, but then 
> we 
> need to worry about how that information about buffers would be discovered 
> there.
> 
> It seems to me that a default behavior should be very clearly defined very 
> early in the manual. Buffers are a huge part of Emacs (and a huge difference 
> with other text editors, that basically expect a user facing "buffer" to be 
> saved after modification) and user have a strong expectation that user 
> modified 
> data is safe and warning will be issued when that data is at risks (in most 
> reasonable cases).
> 
> So, would it be possible to have a strong clarification about the default 
> behavior and ephemeral quality of the buffers in the opening paragraphs of 
> "19 
> Using Multiple Buffers" ? That would be tremendously helpful.

I very much doubt that having this information in the introductory
overview of buffers would be helpful, or even useful.  Let me try to
explain why.

Our manuals are written to serve two basic purposes: (a) to allow
reading whole chapters of them, typically when the reader wants to
become familiar with a new subject; and (b) as a reference, when the
reader is already familiar with the subject, but wants to find a
description of a specific sub-topic.  It is a fundamental requirement
for a manual to serve both of these purposes equally well.

For the first of these two purposes, it is important to describe each
feature where it belongs, so we in general avoid dumping too much
information on the reader, and instead introduce the features
gradually and in the proper context, so that the information
"sticks".  The introductory text of the chapter that describes buffers
does precisely that: it introduces the concept of a buffer, and
provides the most basic and important information about buffers.  It
isn't easy, because a buffer is a very important object in Emacs, with
complex behavior and many related features.  So this introductory text
only includes the basic definitions and overview of what is in a
buffer.  Significantly, it doesn't even mention the possibility of
"killing" a buffer, mainly because this is not a very important
operation on buffers from the user's POV: one can have a very long
Emacs session without killing any of its buffers.  That is why killing
buffers is described relatively late into the chapter: it isn't the
first nor the second section of the chapter, only the 4th.

However, you are most probably using the manual as a reference.  For
that, the most important first step is to think of the subject or
topic or phrase that are pertinent to what you are looking for.  With
that topic or phrase in hand, use the 'i' (Info-index) command to
search for that topic or phrase.  If such a search using several
varieties of relevant topics you could think of doesn't find you the
stuff you were looking for, you probably should report a bug against
the indexing of that particular manual.

In this specific case, since the issue is what happens when a buffer
is killed, I would think of the following topics, in the order shown:

  . killing unsaved buffers
  . unsaved buffers
  . killing buffers

The first two fail to find anything, which indicates that the indexing
should be improved (which I just did), while the last one brings you
exactly to the section which describes this.

Do you think there are other pertinent phrases related to this
specific issue?

To summarize, it is important to keep the related information
together, so that reading about a feature would provide all the
relevant details about it, and the absolute minimum of irrelevant
ones.  This is important for both purposes the manual should serve.
Spreading the information to more places in the manual is not a good
idea, because it makes it harder to update when the behavior changes,
and because it risks confusing the readers with too much information
that might not be relevant.

I hope you now agree that the information about killing unsaved
buffers is exactly where it should be.