*scratch* buffer documentation

*scratch* buffer documentation

[Jean-Christophe Helary]

I am not seeing anything in the Emacs manual that says a modified *scratch* buffer does not trigger a "buffer modified. Kill anyway ?" message when quitting.

The first reference to the *scratch* buffer is in "5 Entering Emacs" and it implicitly refers to the "Lisp Interaction" section to know more. After checking other instances of *scratch* in the manual, it seems that the "Lisp Interaction" section is the place where most of the information about the *scratch* buffer is gathered. It reads:

-------
When Emacs starts up, it contains a buffer named ‘*scratch*’, which is
provided for evaluating Emacs Lisp expressions interactively.  Its major
mode is Lisp Interaction mode.  You can also enable Lisp Interaction
mode by typing ‘M-x lisp-interaction-mode’.

   In the ‘*scratch*’ buffer, and other Lisp Interaction mode buffers,
‘C-j’ (‘eval-print-last-sexp’) evaluates the Lisp expression before
point, and inserts the value at point.  Thus, as you type expressions
into the buffer followed by ‘C-j’ after each expression, the buffer
records a transcript of the evaluated expressions and their values.  All
other commands in Lisp Interaction mode are the same as in Emacs Lisp
mode.

   At startup, the ‘*scratch*’ buffer contains a short message, in the
form of a Lisp comment, that explains what it is for.  This message is
controlled by the variable ‘initial-scratch-message’, which should be
either a documentation string, or ‘nil’ (which means to suppress the
message).

   An alternative way of evaluating Emacs Lisp expressions interactively
is to use Inferior Emacs Lisp mode, which provides an interface rather
like Shell mode (*note Shell Mode::) for evaluating Emacs Lisp
expressions.  Type ‘M-x ielm’ to create an ‘*ielm*’ buffer which uses
this mode.  For more information, see that command’s documentation.
-------


I'd like to propose to modify it this way:

-------
The *scratch* buffer

When Emacs starts up, it contains a buffer named ‘*scratch*’, which is
provided for evaluating Emacs Lisp expressions interactively.  Its major
mode is Lisp Interaction mode.

   At startup, the ‘*scratch*’ buffer contains a short message, in the
form of a Lisp comment, that explains what it is for.  This message is
controlled by the variable ‘initial-scratch-message’, which should be
either a documentation string, or ‘nil’ (which means to suppress the
message).

   If you kill the ‘*scratch*’ buffer after a modification, Emacs will not ask you to confirm the kill and the contents of the ‘*scratch*’ buffer will be lost.  This behavior is not customizable.

Lisp Interaction mode

   You can enable Lisp Interaction mode in other buffers by typing ‘M-x lisp-interaction-mode’.

   In Lisp Interaction mode buffers, including the ‘*scratch*’ buffer,
‘C-j’ (‘eval-print-last-sexp’) evaluates the Lisp expression before
point, and inserts the value at point.  Thus, as you type expressions
into the buffer followed by ‘C-j’ after each expression, the buffer
records a transcript of the evaluated expressions and their values.  All
other commands in Lisp Interaction mode are the same as in Emacs Lisp
mode.

   An alternative way of evaluating Emacs Lisp expressions interactively
is to use Inferior Emacs Lisp mode, which provides an interface rather
like Shell mode (*note Shell Mode::) for evaluating Emacs Lisp
expressions.  Type ‘M-x ielm’ to create an ‘*ielm*’ buffer which uses
this mode.  For more information, see that command’s documentation.
-------


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: *scratch* buffer documentation

[Óscar Fuentes]

Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
writes:

> I am not seeing anything in the Emacs manual that says a modified
> *scratch* buffer does not trigger a "buffer modified. Kill anyway ?"
> message when quitting.

Isn't that manifestly implicit on the first line of *scratch* ? :

;; This buffer is for text that is not saved

"for thext that is not saved" means "throwaway" to me.

Re: *scratch* buffer documentation

[Jean-Christophe Helary]

> On Dec 25, 2019, at 10:24, Óscar Fuentes <ofv@wanadoo.es> wrote:
> 
> Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> writes:
> 
>> I am not seeing anything in the Emacs manual that says a modified
>> *scratch* buffer does not trigger a "buffer modified. Kill anyway ?"
>> message when quitting.
> 
> Isn't that manifestly implicit on the first line of *scratch* ? :
> 
> ;; This buffer is for text that is not saved

No, because it is possible to save the buffer to a file. Also, the value of this text can be changed, so there is no guarantee that the user sees it.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: *scratch* buffer documentation

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> Date: Wed, 25 Dec 2019 08:58:45 +0900
> 
> I am not seeing anything in the Emacs manual that says a modified *scratch* buffer does not trigger a "buffer modified. Kill anyway ?" message when quitting.

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.

> > Isn't that manifestly implicit on the first line of *scratch* ? :
> > 
> > ;; This buffer is for text that is not saved
> 
> No, because it is possible to save the buffer to a file. Also, the value of this text can be changed, so there is no guarantee that the user sees it.

Let's clarify the "is not saved" part of the text that is in the
buffer, it's much more efficient than any documentation anywhere.

If that text is changed, whoever changes it is expected to know what
he or she is doing, so let's not argue about that use case.

Thanks.

Re: *scratch* buffer documentation

[Jean-Christophe Helary]

> On Dec 25, 2019, at 23:55, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> Date: Wed, 25 Dec 2019 08:58:45 +0900
>> 
>> I am not seeing anything in the Emacs manual that says a modified *scratch* buffer does not trigger a "buffer modified. Kill anyway ?" message when quitting.
> 
> 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. I always thought it was a property of the *scratch* buffer. I guess it's because I was mostly using buffer from files or saving new buffers to files.

So, I just checked the documentation (emacs manual) and here is what I found:

19 Using Multiple Buffers

→ nothing about that default behavior

19.1 Creating and Selecting Buffers

→ nothing about that default behavior

19.4 Killing Buffers

Buried at the bottom of the info about C-x k:

"If you ask to kill a file-visiting buffer that is modified, then you must confirm with ‘yes’ before the buffer is killed."

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

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 and thus contradict the above "default".

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.

Or am I still missing something ?

JC


>>> Isn't that manifestly implicit on the first line of *scratch* ? :
>>> 
>>> ;; This buffer is for text that is not saved
>> 
>> No, because it is possible to save the buffer to a file. Also, the value of this text can be changed, so there is no guarantee that the user sees it.
> 
> Let's clarify the "is not saved" part of the text that is in the
> buffer, it's much more efficient than any documentation anywhere.
> 
> If that text is changed, whoever changes it is expected to know what
> he or she is doing, so let's not argue about that use case.
> 
> Thanks.
> 

Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

RE: *scratch* buffer documentation

[arthur miller]

[-- Attachment #1: Type: text/plain, Size: 4164 bytes --]

I Think that you are missing one important thing: users are generally not idiots. Despite what Apple might think about computer users.

I have also being using Emacs for more then 20 years and I have even never red the fine manual more then for the occasional lookups, and yet it was always clear to me how buffers behave. Nor have I ever lost anything in that venerable scratch buffer. Emacs does have its dark corners, but I don't think saving buffers or scratch buffers or even that plist from customize is one of them.

Skickat från min Samsung Galaxy-smartphone.



-------- Originalmeddelande --------
Från: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
Datum: 2019-12-26 01:54 (GMT+01:00)
Till: emacs-devel <emacs-devel@gnu.org>
Ämne: Re: *scratch* buffer documentation



> On Dec 25, 2019, at 23:55, Eli Zaretskii <eliz@gnu.org> wrote:
>
>> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> Date: Wed, 25 Dec 2019 08:58:45 +0900
>>
>> I am not seeing anything in the Emacs manual that says a modified *scratch* buffer does not trigger a "buffer modified. Kill anyway ?" message when quitting.
>
> 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. I always thought it was a property of the *scratch* buffer. I guess it's because I was mostly using buffer from files or saving new buffers to files.

So, I just checked the documentation (emacs manual) and here is what I found:

19 Using Multiple Buffers

→ nothing about that default behavior

19.1 Creating and Selecting Buffers

→ nothing about that default behavior

19.4 Killing Buffers

Buried at the bottom of the info about C-x k:

"If you ask to kill a file-visiting buffer that is modified, then you must confirm with ‘yes’ before the buffer is killed."

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

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 and thus contradict the above "default".

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.

Or am I still missing something ?

JC


>>> Isn't that manifestly implicit on the first line of *scratch* ? :
>>>
>>> ;; This buffer is for text that is not saved
>>
>> No, because it is possible to save the buffer to a file. Also, the value of this text can be changed, so there is no guarantee that the user sees it.
>
> Let's clarify the "is not saved" part of the text that is in the
> buffer, it's much more efficient than any documentation anywhere.
>
> If that text is changed, whoever changes it is expected to know what
> he or she is doing, so let's not argue about that use case.
>
> Thanks.
>

Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune




[-- Attachment #2: Type: text/html, Size: 5519 bytes --]

Re: *scratch* buffer documentation

[Jean-Christophe Helary]

> On Dec 26, 2019, at 11:29, arthur miller <arthur.miller@live.com> wrote:
> 
> I Think that you are missing one important thing: users are generally not idiots.

It is not about being idiots or not. But about how self-contained should the documentation be.

If you show me the place in the documentation where the default behavior is described then I'll need to worry about why I did not find it.

> Emacs does have its dark corners, but I don't think saving buffers

Indeed, saving buffers is not an issue. It is killing buffers that is.

Jean-Christophe

> -------- Originalmeddelande --------
> Från: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org> 
> Datum: 2019-12-26 01:54 (GMT+01:00)
> Till: emacs-devel <emacs-devel@gnu.org> 
> Ämne: Re: *scratch* buffer documentation
> 
> 
> 
> > On Dec 25, 2019, at 23:55, Eli Zaretskii <eliz@gnu.org> wrote:
> > 
> >> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> >> Date: Wed, 25 Dec 2019 08:58:45 +0900
> >> 
> >> I am not seeing anything in the Emacs manual that says a modified *scratch* buffer does not trigger a "buffer modified. Kill anyway ?" message when quitting.
> > 
> > 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. I always thought it was a property of the *scratch* buffer. I guess it's because I was mostly using buffer from files or saving new buffers to files.
> 
> So, I just checked the documentation (emacs manual) and here is what I found:
> 
> 19 Using Multiple Buffers
> 
> → nothing about that default behavior
> 
> 19.1 Creating and Selecting Buffers
> 
> → nothing about that default behavior
> 
> 19.4 Killing Buffers
> 
> Buried at the bottom of the info about C-x k:
> 
> "If you ask to kill a file-visiting buffer that is modified, then you must confirm with ‘yes’ before the buffer is killed."
> 
> If that is how/where the default behavior is specified, maybe it ought to be in a more preeminent location.
> 
> 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 and thus contradict the above "default".
> 
> 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.
> 
> Or am I still missing something ?
> 
> JC
> 
> 
> >>> Isn't that manifestly implicit on the first line of *scratch* ? :
> >>> 
> >>> ;; This buffer is for text that is not saved
> >> 
> >> No, because it is possible to save the buffer to a file. Also, the value of this text can be changed, so there is no guarantee that the user sees it.
> > 
> > Let's clarify the "is not saved" part of the text that is in the
> > buffer, it's much more efficient than any documentation anywhere.
> > 
> > If that text is changed, whoever changes it is expected to know what
> > he or she is doing, so let's not argue about that use case.
> > 
> > Thanks.
> > 
> 
> Jean-Christophe Helary
> -----------------------------------------------
> http://mac4translators.blogspot.com @brandelune

Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: *scratch* buffer documentation

[Óscar Fuentes]

Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
writes:

>> I Think that you are missing one important thing: users are generally
>> not idiots.
>
> It is not about being idiots or not. But about how self-contained
> should the documentation be.
>
> If you show me the place in the documentation where the default
> behavior is described then I'll need to worry about why I did not find
> it.

  19.4 Killing Buffers

     ‘C-x k’ (‘kill-buffer’) kills one buffer, [...] If you ask to kill
  a file-visiting buffer that is modified, then you must confirm with
  ‘yes’ before the buffer is killed.


A corollary is that other buffers may not trigger the confirmation.

>> Emacs does have its dark corners, but I don't think saving buffers
>
> Indeed, saving buffers is not an issue. It is killing buffers that is.

IMO the implication that Emacs only cares about the persistence of
changes made to file-visiting buffers is clear. If the user, somehow,
expects that Emacs will warn on quitting about changes to *scratch*, he
will swiftly learn what "This buffer is for text that is not saved"
means :-)

Re: *scratch* buffer documentation

[Jean-Christophe Helary]

Óscar,

Please read my reply to Eli.

JC


> On Dec 26, 2019, at 12:27, Óscar Fuentes <ofv@wanadoo.es> wrote:
> 
> Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> writes:
> 
>>> I Think that you are missing one important thing: users are generally
>>> not idiots.
>> 
>> It is not about being idiots or not. But about how self-contained
>> should the documentation be.
>> 
>> If you show me the place in the documentation where the default
>> behavior is described then I'll need to worry about why I did not find
>> it.
> 
>  19.4 Killing Buffers
> 
>     ‘C-x k’ (‘kill-buffer’) kills one buffer, [...] If you ask to kill
>  a file-visiting buffer that is modified, then you must confirm with
>  ‘yes’ before the buffer is killed.
> 
> 
> A corollary is that other buffers may not trigger the confirmation.
> 
>>> Emacs does have its dark corners, but I don't think saving buffers
>> 
>> Indeed, saving buffers is not an issue. It is killing buffers that is.
> 
> IMO the implication that Emacs only cares about the persistence of
> changes made to file-visiting buffers is clear. If the user, somehow,
> expects that Emacs will warn on quitting about changes to *scratch*, he
> will swiftly learn what "This buffer is for text that is not saved"
> means :-)
> 
> 

Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: *scratch* buffer documentation

[Jean-Christophe Helary]

> On Dec 26, 2019, at 12:27, Óscar Fuentes <ofv@wanadoo.es> wrote:
> 
> A corollary is that other buffers may not trigger the confirmation.

A *default behavior* should not be handled as a "corollary" to the description of a given command. That's the opposite.

Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: *scratch* buffer documentation

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> 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.

Re: *scratch* buffer documentation

[Jean-Christophe Helary]

> On Dec 27, 2019, at 1:22, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> I hope you now agree that the information about killing unsaved
> buffers is exactly where it should be.

No, because what is important here is not whether a buffer is killed or not, but what are the intrinsic properties of buffers.

What you call "default behavior" and what Óscar calls a corollary of the kill-buffer description comes from the nature of buffers and that nature is not properly explained. That explanation should come as the second sentence of "19 Using Multiple Buffers". Or maybe the second paragraph.

I just tried something:

create a buffer, type something, kill Emacs.

Of course, when I restarted Emacs the buffer was gone.

In any other editor I'd either have a warning that I'm going to lose data or the data would have been automatically saved and would be restored when I restarted the editor.

This behavior is specific to Emacs and its buffers and should be properly documented.

Of course, now I don't need that documentation any more since it's been discussed here for the last few hours. So it's likely that I won't forget it. But that's not this kind of information persistence that I'm after.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: *scratch* buffer documentation

[Lars Ingebrigtsen]

Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
writes:

> I just tried something:
>
> create a buffer, type something, kill Emacs.
>
> Of course, when I restarted Emacs the buffer was gone.
>
> In any other editor I'd either have a warning that I'm going to lose
> data or the data would have been automatically saved and would be
> restored when I restarted the editor.

Are there any other editors where you can open a "buffer" that's not
associated with a file?

Most people use editors to edit files, and if you do that, Emacs behaves
pretty much like any other editors in that respect.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: *scratch* buffer documentation

[Jean-Christophe Helary]

> On Dec 27, 2019, at 2:36, Lars Ingebrigtsen <larsi@gnus.org> wrote:
> 
> Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> writes:
> 
>> I just tried something:
>> 
>> create a buffer, type something, kill Emacs.
>> 
>> Of course, when I restarted Emacs the buffer was gone.
>> 
>> In any other editor I'd either have a warning that I'm going to lose
>> data or the data would have been automatically saved and would be
>> restored when I restarted the editor.
> 
> Are there any other editors where you can open a "buffer" that's not
> associated with a file?

As far as *UX* is concerned (I'm not concerned about the internals), pretty much all the editors I use. Including the most basic macos TextEdit.

When you create a new "file" it is just a "buffer" and is not associated to any material file at that point. And TextEdit will keep the data even if the file is not created/saved even if TextEdit is "killed" and restarted.

The cool (?) thing about Emacs is that you can do the same thing in 2 ways:
create a buffer
visit a non existing *file*

when you modify and then kill the two without saving, in one case the data is gone, in the other case Emacs does not ask you whether you worry about the contents of the *file* or not, but whether you worry about the *buffer*...

So the main difference in Emacs is that either you start by saying you want to associate the buffer to a file, or you finish by saying that. That is a complication that does not exist in (most) other editors.

But as far as the user is concerned (and users now have the possibility to have a lot of experience outside the Emacs realm before coming here, or while using Emacs) it is not fundamentally different, and not different from what they experience outside Emacs, especially since the nature of a buffer is not properly explained.

> Most people use editors to edit files,

I don't know that. I know that I'd paste a big bunch of data into an open window in BBEdit and do regex search replaces and then paste the results back to wherever I need it, and that window will never be saved to a file. I use TextEdit like that plenty of the time too. There is a lot of transient information that will be reshuffled to various applications and I just need a place to type a few things. But I know that contrary to Emacs, such transient data is mostly safe in other applications.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: *scratch* buffer documentation

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> Date: Fri, 27 Dec 2019 02:15:16 +0900
> 
> I just tried something:
> 
> create a buffer, type something, kill Emacs.
> 
> Of course, when I restarted Emacs the buffer was gone.
> 
> In any other editor I'd either have a warning that I'm going to lose data or the data would have been automatically saved and would be restored when I restarted the editor.

So maybe you should ask for a new feature, where such a warning will
be displayed.

> This behavior is specific to Emacs and its buffers and should be properly documented.

It _is_ documented.  The disagreement between us is _where_ should it
be documented.  I'm saying that the proper place to document it is
where killing buffers is described.  For example, what happens with
buffers when you exit Emacs is described in "Exiting", where the
manual says:

     “Killing” Emacs means terminating the Emacs program.  To do this,
  type ‘C-x C-c’ (‘save-buffers-kill-terminal’).  A two-character key
  sequence is used to make it harder to type by accident.  If there are
  any modified file-visiting buffers when you type ‘C-x C-c’, Emacs first
  offers to save these buffers.  If you do not save them all, it asks for
  confirmation again, since the unsaved changes will be lost.  Emacs also
  asks for confirmation if any subprocesses are still running, since
  killing Emacs will also kill the subprocesses (*note Shell::).

What you seem to be asking is unreasonable: to have everything related
to buffers in one section.  That will be a very large and confusing
section, lumping many loosely related traits of buffers together.  It
will not be an easy reading at all.

Therefore, we choose to subdivide the complex topic of buffers and
their behavior into several sections, and describe each trait near the
commands and variables related to it.  That makes the manual introduce
the features gradually, and latter reading about each set of related
features much easier.

Re: *scratch* buffer documentation

[Jean-Christophe Helary]

> On Dec 27, 2019, at 5:25, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> 
>> This behavior is specific to Emacs and its buffers and should be properly documented.
> 
> It _is_ documented.  The disagreement between us is _where_ should it
> be documented.

Eli,

I am starting to see where the disagreement is.

> What you seem to be asking is unreasonable: to have everything related
> to buffers in one section.

What about a 1-word addition? The File Handling section has the word "permanent" in it:

======================================================================
18 File Handling
****************

The operating system stores data permanently in named “files”, so most
of the text you edit with Emacs comes from a file and is ultimately
stored in a file.
======================================================================


What about adding a word that indicates the temporary nature of buffers as a qualifier to "object" in Using Multiple Buffers?

That way we have a clear opposition early in the description of the two objects and that would help discovery/understanding the other traits of buffers.

There are a number of words that fit the description. The antonym of "permanent" seems to be "temporary" and synonyms of "temporaty" are "transient," "ephemeral," "transitory," "provisory" and a few others. I like "provisory" because it implies a condition to change the status of the buffer.

So what about something like that:

======================================================================
19 Using Multiple Buffers
*************************

The text you are editing in Emacs resides in a provisory object called a
“Buffer”.
======================================================================


When I read "provisory" I have alarm bells ringing and I want to know more, so I check the rest of the documentation and indeed, I find the kill command and that confirms that buffers are indeed provisory and need to be saved to a *permanent* file to have their contents archived.

Would that be an agreeable proposal?


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: *scratch* buffer documentation

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> Date: Fri, 27 Dec 2019 10:03:53 +0900
> 
> ======================================================================
> 19 Using Multiple Buffers
> *************************
> 
> The text you are editing in Emacs resides in a provisory object called a
> “Buffer”.
> ======================================================================
> 
> When I read "provisory" I have alarm bells ringing and I want to know more, so I check the rest of the documentation and indeed, I find the kill command and that confirms that buffers are indeed provisory and need to be saved to a *permanent* file to have their contents archived.
> 
> Would that be an agreeable proposal?

Maybe, except that it cannot be a single word.  We cannot say
"provisory" (a better word is "provisional", btw) without explaining
what it means in this context.  And some might even say that
"provisional" is inaccurate, because that's not exactly the nature of
a buffer: it never changes as long as it exists, so there's no
changing of it later.

How about this addition instead, after the first paragraph:

  Buffers exist as long as they are used, and are deleted ("killed")
  when no longer needed, either by you (see Kill Buffer) or by Emacs
  (e.g., when you exit Emacs, see Exiting).

Re: *scratch* buffer documentation

[Jean-Christophe Helary]

> On Dec 27, 2019, at 17:12, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> How about this addition instead, after the first paragraph:
> 
>  Buffers exist as long as they are used, and are deleted ("killed")
>  when no longer needed, either by you (see Kill Buffer) or by Emacs
>  (e.g., when you exit Emacs, see Exiting).

:) Do you want me to send a patch with that ?

Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: *scratch* buffer documentation

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> Date: Fri, 27 Dec 2019 18:12:17 +0900
> 
> > How about this addition instead, after the first paragraph:
> > 
> >  Buffers exist as long as they are used, and are deleted ("killed")
> >  when no longer needed, either by you (see Kill Buffer) or by Emacs
> >  (e.g., when you exit Emacs, see Exiting).
> 
> :) Do you want me to send a patch with that ?

No, just say that you are okay with it.

Re: *scratch* buffer documentation

[Jean-Christophe Helary]

> On Dec 27, 2019, at 18:26, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> Date: Fri, 27 Dec 2019 18:12:17 +0900
>> 
>>> How about this addition instead, after the first paragraph:
>>> 
>>> Buffers exist as long as they are used, and are deleted ("killed")
>>> when no longer needed, either by you (see Kill Buffer) or by Emacs
>>> (e.g., when you exit Emacs, see Exiting).
>> 
>> :) Do you want me to send a patch with that ?
> 
> No, just say that you are okay with it.

I'm ok with that. Thank you. I had prepared something but I guess it's less of a hassle to just commit everything on your side.

JC

Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: *scratch* buffer documentation

[VanL]

>> When I read "provisory" I have alarm bells ringing and I want to
>> know more, so I check the rest of the documentation and indeed, I
>> find the kill command and that confirms that buffers are indeed
>> provisory and need to be saved to a *permanent* file to have their
>> contents archived.

The intro to RPi4B uses the words 'volatile' and 'non-volatile' memory.

-- 
 əə0@ 7 6 4 5 bit byte word 6 5 0 2 memory map dma intelligence io 🐞
 一 二 三 言 語 𝔖 元 示 証 明 海 自 己 漢 本 人 Gnus/Emacs (berkeley-unix)

Re: *scratch* buffer documentation

[Eli Zaretskii]

> From: VanL <van@scratch.space>
> Date: Fri, 27 Dec 2019 22:31:22 +1100
> 
> >> When I read "provisory" I have alarm bells ringing and I want to
> >> know more, so I check the rest of the documentation and indeed, I
> >> find the kill command and that confirms that buffers are indeed
> >> provisory and need to be saved to a *permanent* file to have their
> >> contents archived.
> 
> The intro to RPi4B uses the words 'volatile' and 'non-volatile' memory.

Buffers aren't "volatile", either, they don't evaporate unless killed.

Re: *scratch* buffer documentation

[John Yates]

[-- Attachment #1: Type: text/plain, Size: 782 bytes --]

Jumping in after having read only the last few post in the thread.

How about "nonpersistent"?

/john

On Fri, Dec 27, 2019 at 9:06 AM Eli Zaretskii <eliz@gnu.org> wrote:

> > From: VanL <van@scratch.space>
> > Date: Fri, 27 Dec 2019 22:31:22 +1100
> >
> > >> When I read "provisory" I have alarm bells ringing and I want to
> > >> know more, so I check the rest of the documentation and indeed, I
> > >> find the kill command and that confirms that buffers are indeed
> > >> provisory and need to be saved to a *permanent* file to have their
> > >> contents archived.
> >
> > The intro to RPi4B uses the words 'volatile' and 'non-volatile' memory.
>
> Buffers aren't "volatile", either, they don't evaporate unless killed.
>
>

-- 
John Yates
505 Tremont St, #803
Boston, MA 02116

[-- Attachment #2: Type: text/html, Size: 1784 bytes --]

Re: *scratch* buffer documentation

[Eli Zaretskii]

> From: John Yates <john@yates-sheets.org>
> Date: Fri, 27 Dec 2019 13:24:56 -0500
> Cc: VanL <van@scratch.space>, Emacs developers <emacs-devel@gnu.org>
> 
> Jumping in after having read only the last few post in the thread.
> 
> How about "nonpersistent"?

I decided to write a description instead of using some term that needs
to be explained.

At this point, please read the text I added, and if you have any
problems with it, tell here.

RE: *scratch* buffer documentation

[Drew Adams]

> How about this addition instead, after the first paragraph:
> 
>   Buffers exist as long as they are used, and are deleted ("killed")
>   when no longer needed, either by you (see Kill Buffer) or by Emacs
>   (e.g., when you exit Emacs, see Exiting).

Minor suggestion (and I agree that it can
help to have some such statement where we
introduce buffers):

"Used" could mislead.  It could give the
impression that a buffer is "no longer
needed" only when it is no longer visible
or is being actively edited by a user.

It's not about whether a user is using the
buffer (or that she thinks she is).

It may not be obvious here that it's about
whether Emacs - anything in Emacs - is
"using" the buffer, i.e., that there is some
reference to it - some need for it.  (But
"reference" might not be clear to some
non-programmers.)

"No longer needed" is probably clear enough,
on its own.  Without saying what that means,
it will likely be interpreted correctly, as
meaning that Emacs (not just a user) needs
the buffer for some reason.

It's OK to be vague about what "need" means,
even if it's not so OK (IMO) to be vague
about what "use" means.  I suggest dropping
mention of being "used".

Re: *scratch* buffer documentation

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> How about this addition instead, after the first paragraph:
>
>   Buffers exist as long as they are used, and are deleted ("killed")
>   when no longer needed, either by you (see Kill Buffer) or by Emacs
>   (e.g., when you exit Emacs, see Exiting).

I think this is even more confusing, really -- it sounds like buffers
are temporary things that may disappear without you knowing ("e.g.").

If anything needs to be said here, it's that buffers aren't necessarily
tied to files, and if such a buffer is killed, the contents of the
buffer will not be saved anywhere.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no