From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: *scratch* buffer documentation Date: Thu, 26 Dec 2019 18:22:07 +0200 Message-ID: <83k16jqcpc.fsf@gnu.org> References: <69AD1F67-BA40-4342-996E-CAC6CC545E2A@traduction-libre.org> <83lfr0v4ib.fsf@gnu.org> <3B5C95CE-77A8-48DA-BD5D-6BD8D8828C30@traduction-libre.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="128065"; mail-complaints-to="usenet@blaine.gmane.org" Cc: emacs-devel@gnu.org To: Jean-Christophe Helary Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Dec 26 17:22:48 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1ikVuR-000XAw-Ga for ged-emacs-devel@m.gmane.org; Thu, 26 Dec 2019 17:22:47 +0100 Original-Received: from localhost ([::1]:54832 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ikVuQ-0005v8-AS for ged-emacs-devel@m.gmane.org; Thu, 26 Dec 2019 11:22:46 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:33428) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ikVts-0005I6-Nc for emacs-devel@gnu.org; Thu, 26 Dec 2019 11:22:14 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:45592) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ikVts-0005xQ-1Q; Thu, 26 Dec 2019 11:22:12 -0500 Original-Received: from [176.228.60.248] (port=2618 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1ikVtr-0002iS-Ef; Thu, 26 Dec 2019 11:22:11 -0500 In-reply-to: <3B5C95CE-77A8-48DA-BD5D-6BD8D8828C30@traduction-libre.org> (message from Jean-Christophe Helary on Thu, 26 Dec 2019 09:54:02 +0900) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:243652 Archived-At: > From: Jean-Christophe Helary > 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 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.