From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#37771: 26.3; doc for `dired-auto-revert-buffer' Date: Thu, 17 Oct 2019 15:34:20 +0000 (UTC) Message-ID: <6ef7235b-4091-437c-87da-46ad883cb235@default> References: <60cfbdb5-8f92-4af6-bf5a-f1f7f05bd1c6@default> <87zhi0krit.fsf@gnus.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="177158"; mail-complaints-to="usenet@blaine.gmane.org" Cc: 37771@debbugs.gnu.org To: Lars Ingebrigtsen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Oct 17 18:23:34 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1iL8Yn-000jwa-D8 for geb-bug-gnu-emacs@m.gmane.org; Thu, 17 Oct 2019 18:23:33 +0200 Original-Received: from localhost ([::1]:52434 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iL8Yl-0005ph-NY for geb-bug-gnu-emacs@m.gmane.org; Thu, 17 Oct 2019 12:23:31 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58986) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iL7po-0004Ah-Pu for bug-gnu-emacs@gnu.org; Thu, 17 Oct 2019 11:37:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iL7pm-0004sj-Gl for bug-gnu-emacs@gnu.org; Thu, 17 Oct 2019 11:37:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:39920) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iL7pm-0004sc-C6 for bug-gnu-emacs@gnu.org; Thu, 17 Oct 2019 11:37:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1iL7pm-0008FT-7g for bug-gnu-emacs@gnu.org; Thu, 17 Oct 2019 11:37:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 17 Oct 2019 15:37:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 37771 X-GNU-PR-Package: emacs Original-Received: via spool by 37771-submit@debbugs.gnu.org id=B37771.157132659331655 (code B ref 37771); Thu, 17 Oct 2019 15:37:01 +0000 Original-Received: (at 37771) by debbugs.gnu.org; 17 Oct 2019 15:36:33 +0000 Original-Received: from localhost ([127.0.0.1]:48741 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iL7pI-0008EV-SO for submit@debbugs.gnu.org; Thu, 17 Oct 2019 11:36:33 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:56896) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iL7pG-0008EI-N2 for 37771@debbugs.gnu.org; Thu, 17 Oct 2019 11:36:31 -0400 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x9HFYNYr012987; Thu, 17 Oct 2019 15:36:24 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2019-08-05; bh=SwEwXISbY+2+a6cAEKDD28ZZlkSb2UXRuQP5ccgln2o=; b=JwJVyrHInbeQN4Dag35WjlD42H5289YVCW3FrZunxEZMteKzPnDVRl7wLLeXCGN2iKbp UYy54J/G8T8s3IRjK2zbfarnLziT4PqM2826bG6bJbwgzx5HGTVK7II/iuZKcCoV8q3R Ex+lGs7TKatqCZfRAzy8BNWdzpeF0qfrulaZyj7UL15QPvSIiYcicB4gJ3qdr7DrKwgp ZzedJr6e+W53cilCUId1srprQ63l9fd9yefRLm10LlnO3+96rKH3aCaMXSQFcvEzKuuZ ud8vJPnSL6iS31yLEz7JNvBv7Se66gArQCUNuE8A23qPlEEl7xMrxPPmTVMGetHyGaTd wQ== Original-Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by userp2120.oracle.com with ESMTP id 2vk7frq2px-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 17 Oct 2019 15:36:24 +0000 Original-Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x9HFX7dF137835; Thu, 17 Oct 2019 15:34:23 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by aserp3030.oracle.com with ESMTP id 2vpcm34hk2-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 17 Oct 2019 15:34:23 +0000 Original-Received: from abhmp0003.oracle.com (abhmp0003.oracle.com [141.146.116.9]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id x9HFYL1p024121; Thu, 17 Oct 2019 15:34:21 GMT In-Reply-To: <87zhi0krit.fsf@gnus.org> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4900.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9413 signatures=668684 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1908290000 definitions=main-1910170139 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9413 signatures=668684 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1011 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1908290000 definitions=main-1910170139 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 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.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:169592 Archived-At: > > Please consider improving the doc so that it does the following: > > > > * Explains what is meant by "visiting" a Dired buffer. The Emacs > > manuals and other doc only speak about visiting a file in a buffer. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > Just what constitutes "visiting" a Dired buffer? It seems like > > it's sufficient to display the buffer and select its window. > > Is that it? >=20 > It means whatever Emacs means by "visiting" a file. I don't see what's > there to explain. Why do you think so? Nowhere in our doc do we introduce a notion of "visiting" a buffer. And a Dired buffer is not a file. Isn't what's really meant only that the buffer is displayed and its window is selected? If so, say so. That's a far cry from visiting a file. > > * Explains the Value Menu items in Customize - in particular, item > > `Revert changed Dired buffer'. >=20 > Explaining what "revert" means in this context seems a bit odd. > There's a manual for that. No. Buffer reverting is particular to different kinds of buffer (apart from file buffers, where it acts about the same for any file). So explain what it means to revert a Dired buffer. And yes, it means something particular. > > * Explains that the option has no effect on Dired buffers containing > > arbitrary file lists (i.e., whose DIRNAME is a cons). It is > > relevant only for actual directory listings. >=20 > You mean that switching it off doesn't stop reverting in that case? Switching what off? I don't know what you mean here. The point is that reverting a Dired buffer means one thing for a file listing (ordinary use of Dired). It means something else when the buffer has any an arbitrary list of files (e.g. from different dirs that are not just subdirs). In such cases IF reverting is possible its behavior can be particular to the particular kind of listing. And this variable does not apply - its value has no effect.=20 > =09 ;; Always revert when `dir-or-list' is a cons. Also revert > =09 ;; if `dired-directory' is a cons but `dir-or-list' is not. > =09 ((or (consp dir-or-list) (consp dired-directory)) > =09 (setq dired-directory dir-or-list) > =09 (revert-buffer)) > =09 ;; Always revert regardless of whether it has changed or not. > =09 ((eq dired-auto-revert-buffer t) > =09 (revert-buffer)) >=20 > As far as I can tell, this is only reached when you call `dired' > explicitly with a list of file names? That dired updates the buffer > when you call it with a bunch of file names, without consulting > dired-auto-revert-buffer, seems pretty self-evident. Self-evident from the code. The point is that the _doc_ for the variable should say that it has no effect in such cases - it applies only to ordinary file listings, such as produced by `ls'. > > * Lists the Lisp values that correspond to the Value Menu items. >=20 > They all seem documented? No. This one is not: "Revert changed Dired buffer". > "Revert changed Dired buffer" dired-directory-changed-p) > is just a predicate function. Of course it is. But it is a particular, predefined predicate, which corresponds to one of the menu items. This is no different from when we have menu items that correspond to other particular values. We document them. Users should be able to see the correspondence between the documented Lisp values and the menu items. > Didn't see anything that needed fixing here, and I'm closing this bug > report. Unfortunate.