From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#52328: 27.2; [DOC] Paragraph about quit-restore-window Date: Tue, 07 Dec 2021 20:36:45 +0200 Message-ID: <83mtlcxnwi.fsf@gnu.org> References: <87tufm0xcd.fsf@laposte.net> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="20449"; mail-complaints-to="usenet@ciao.gmane.io" Cc: ke.vigouroux@laposte.net, 52328@debbugs.gnu.org To: rms@gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Dec 07 19:38:33 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1mufMG-00050n-IS for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 07 Dec 2021 19:38:32 +0100 Original-Received: from localhost ([::1]:40046 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mufMF-00063h-2O for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 07 Dec 2021 13:38:31 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:36246) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mufLm-00063J-QL for bug-gnu-emacs@gnu.org; Tue, 07 Dec 2021 13:38:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:55282) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mufLm-000713-GJ for bug-gnu-emacs@gnu.org; Tue, 07 Dec 2021 13:38:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1mufLm-0007g9-Cs for bug-gnu-emacs@gnu.org; Tue, 07 Dec 2021 13:38:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 07 Dec 2021 18:38:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 52328 X-GNU-PR-Package: emacs Original-Received: via spool by 52328-submit@debbugs.gnu.org id=B52328.163890222229440 (code B ref 52328); Tue, 07 Dec 2021 18:38:02 +0000 Original-Received: (at 52328) by debbugs.gnu.org; 7 Dec 2021 18:37:02 +0000 Original-Received: from localhost ([127.0.0.1]:38595 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mufKo-0007ef-6j for submit@debbugs.gnu.org; Tue, 07 Dec 2021 13:37:02 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:35286) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mufKm-0007eH-7K for 52328@debbugs.gnu.org; Tue, 07 Dec 2021 13:37:00 -0500 Original-Received: from [2001:470:142:3::e] (port=53144 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mufKg-0006v0-Sl; Tue, 07 Dec 2021 13:36:54 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=M1Es1Roxy2Wik3hjIeHFcUyOjEMf8+LymVhUT6TuEag=; b=ot4LNSHV/RpQSQ14DhHL pKIB9gHNTEuBbo4TEi8syT9VVSc35s3/TfSxP3ISFjo4sHwfWQh31RKCUbGQxtm/1wVLkj6TfYAKE n4bLmu8+Tv+Apg8XP1+WkA4DcSAPAHYN9ZCIqb7etvO927YrxCddnlyqg5IiyRip4IhQBwrvBkAMU sV9SyTuWmXYpKc1Kx/ZjMguXD8D9OwUR+L1Q0THEzDWgO8MA2EF2FBlMYUjWXjJEQg7/TRulKXzJ1 peCd1DMUlxlUtBlqf/ZGQq08C6eFI9fIg+qauRkGU/8ILMazT/+hJHhvdbRYkhRGvZSJQJuusjhAe TVrQUbWT5tXTeQ==; Original-Received: from [87.69.77.57] (port=1169 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mufKa-00033h-9I; Tue, 07 Dec 2021 13:36:48 -0500 In-Reply-To: (message from Richard Stallman on Mon, 06 Dec 2021 23:15:19 -0500) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:221860 Archived-At: > From: Richard Stallman > Date: Mon, 06 Dec 2021 23:15:19 -0500 > Cc: 52328@debbugs.gnu.org > > > If the third element of the ‘quit-restore’ parameter is a list of > > buffer, window start (*note Window Start and End), and point > > (*note > > Window Point), > > It would be clearer to present the list using Lisp syntax: > (@var{buffer} @var{window-start} @var{new-point}) > Then it can talk about these values with their names, which > is clearer. That is true. But that's far from being the single or the main problem of that description. > and that buffer is still live, the buffer will be > > displayed, and start and point set accordingly. > > It's bad to use passive voice; that is generally less clear because > of the missing subject, as well as more cluttered. > > "Set accordingly" is hard work to interpret because it is not concrete. I invite you to read the entire description of this function. It is very complex and is IMO very hard to grasp. I think it needs to be completely rewritten, with the method of presenting the various options rethought to be more clear. One possibility is to describe the options from the opposite POV: instead of saying "if the parameter is this-and-that, the function will do some stuff", first describe a job that the caller would want to do, with the rationale for that, and then how to tell the function to do that job. Other suggestions for clarifying that part will be most welcome.