From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#31636: 27.0.50; lockfile syntax searchable from info manual Date: Tue, 29 May 2018 19:46:38 +0300 Message-ID: <83r2luv28h.fsf@gnu.org> References: <20180529073311.EEA09102DA@mailuser.nyi.internal> <876036hn2e.fsf@gmail.com> <87tvqqd7rp.fsf@gmail.com> <87r2lufvo9.fsf@gmail.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1527612306 9027 195.159.176.226 (29 May 2018 16:45:06 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 29 May 2018 16:45:06 +0000 (UTC) Cc: mail@bradyt.com, 31636@debbugs.gnu.org, npostavs@gmail.com To: Robert Pluim , Paul Eggert Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue May 29 18:45:01 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fNhk4-0002CV-Fj for geb-bug-gnu-emacs@m.gmane.org; Tue, 29 May 2018 18:45:00 +0200 Original-Received: from localhost ([::1]:33975 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fNhmB-0005k3-HD for geb-bug-gnu-emacs@m.gmane.org; Tue, 29 May 2018 12:47:11 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49205) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fNhm4-0005jl-3E for bug-gnu-emacs@gnu.org; Tue, 29 May 2018 12:47:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fNhm2-00070L-Tr for bug-gnu-emacs@gnu.org; Tue, 29 May 2018 12:47:04 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:46341) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fNhm2-00070B-Pu for bug-gnu-emacs@gnu.org; Tue, 29 May 2018 12:47:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fNhm2-0001TH-Gw for bug-gnu-emacs@gnu.org; Tue, 29 May 2018 12:47:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 29 May 2018 16:47:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31636 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 31636-submit@debbugs.gnu.org id=B31636.15276124175644 (code B ref 31636); Tue, 29 May 2018 16:47:02 +0000 Original-Received: (at 31636) by debbugs.gnu.org; 29 May 2018 16:46:57 +0000 Original-Received: from localhost ([127.0.0.1]:54238 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fNhlw-0001Sx-Pw for submit@debbugs.gnu.org; Tue, 29 May 2018 12:46:57 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:58192) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fNhlu-0001Si-IY for 31636@debbugs.gnu.org; Tue, 29 May 2018 12:46:54 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fNhlk-0006rU-HQ for 31636@debbugs.gnu.org; Tue, 29 May 2018 12:46:49 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:36099) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fNhlk-0006rQ-E6; Tue, 29 May 2018 12:46:44 -0400 Original-Received: from [176.228.60.248] (port=1414 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1fNhlj-0000N3-Th; Tue, 29 May 2018 12:46:44 -0400 In-reply-to: <87r2lufvo9.fsf@gmail.com> (message from Robert Pluim on Tue, 29 May 2018 15:17:26 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] 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: 208.118.235.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:146707 Archived-At: > From: Robert Pluim > Date: Tue, 29 May 2018 15:17:26 +0200 > Cc: Brady Trainor , 31636@debbugs.gnu.org > > From: Robert Pluim > Date: Tue, 29 May 2018 10:19:16 +0200 > Subject: [PATCH] Add more discoverable documentation for '.#' > To: emacs-devel@gnu.org > > * doc/emacs/files.texi (Interlocking): Add index entry for '.#' and > mention its use in lockfile names. > > * src/filelock.c (Flock_buffer): Mention '.#' string, add reference to > Interlocking info node. > --- > doc/emacs/files.texi | 4 +++- > src/filelock.c | 4 +++- > 2 files changed, 6 insertions(+), 2 deletions(-) Hmm... I'm okay with describing this in the doc string (and then perhaps also describe the info recorded in the symlink? it doesn't sound like it is less important than the exact file name). But I'm not sure we want to add this to the manual. First, the current text clearly tries not to divulge the exact way of computing the name of the lockfile. Second, if and when this changes (and we've seen changes there just a year or two ago), someone will need to remember to go back and update the manual, which they will surely forget, which then will leave outdated information in the manual. Finally, this is not really a user-level stuff, so the user manual is not a good place for it to begin with. I'd be interested to hear Paul's take on this, as someone who worked on the related code not too long ago. Paul? Below I comment on the manual part of the patch, in case I will be outvoted eventually (whaat? how??). > diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi > index 1ced7ca07c..72d538161a 100644 > --- a/doc/emacs/files.texi > +++ b/doc/emacs/files.texi > @@ -766,9 +766,11 @@ Interlocking > > @findex ask-user-about-lock > @cindex locking files > +@cindex .# This index entry is not useful. Imagine a reader looking at the entry in the index -- will they understand what it's about? Probably not. Instead, I'd use this: @cindex .#, lock file names > When you make the first modification in an Emacs buffer that is > visiting a file, Emacs records that the file is @dfn{locked} by you. > -(It does this by creating a specially-named symbolic link@footnote{If > +(It does this by creating a specially-named symbolic link, whose name > +contains the string @code{.#} @footnote{If "Contains the string" is again a half-truth. It sounds like this bug report is against telling half-truths. > diff --git a/src/filelock.c b/src/filelock.c > index f2dc723407..042fe9e00b 100644 > --- a/src/filelock.c > +++ b/src/filelock.c > @@ -773,7 +773,9 @@ DEFUN ("lock-buffer", Flock_buffer, Slock_buffer, > FILE defaults to current buffer's visited file, > or else nothing is done if current buffer isn't visiting a file. > > -If the option `create-lockfiles' is nil, this does nothing. */) > +If the option `create-lockfiles' is nil, this does nothing. > +The name of the lockfile used contains '.#', see > +Info node `(emacs)Interlocking' for more information. */) The place where you describe the form of the file name is sub-optimal. I'd instead do this in the doc string of create-lockfiles, it seems much more natural there. And I'd also add there a link to the doc string of lock-buffer. As I said above, I think if we are describing this in more detail, why not describe also the information recorded in the lockfile? If someone looked up the lockfile name, someone else may wish to look up the data it records and understand what that is, no? Thanks.