bug#31636: 27.0.50; lockfile syntax searchable from info manual

[Robert Pluim]

Brady Trainor <mail@bradyt.com> writes:

> I had hoped to find about files such as `/tmp/.#fileA` by searching in
> the info manual for ".#". But I did not find such a string there, nor
> via `apropos-documentation`.
>
> If a user encounters such a file in a directory, I think it would lead
> to good discoverability if a manual or docstring had some mention of the
> string ".#", so that one might search for it.
>
> I'm sending this report without having spent a lot of time on it now,
> not sure if this ".#" convention comes from outside of emacs.

We could add an index entry to the info manual. Adding a reference
inside the docstring of 'lock-buffer' would enable
'apropos-documentation' to find it as well.

This does mean that if the implementation of locking ever changes,
weʼd need to update those docs, but I donʼt think thereʼs much chance
of that.

Proposed patch (for emacs-26?)

>From 2655d523a8136365e00076e1162598913f58277c Mon Sep 17 00:00:00 2001
From: Robert Pluim <rpluim@gmail.com>
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(-)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 1ced7ca07c..f80ad5bbd7 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 .#
   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
+currently contains the string @code{.#} @footnote{If
 your file system does not support symbolic links, a regular file is
 used.} with special contents in the same directory.)  Emacs removes the lock
 when you save the changes.  The idea is that the file is locked
diff --git a/src/filelock.c b/src/filelock.c
index f2dc723407..d93adf8e81 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 currently contains '.#', see
+Info node `(emacs)Interlocking' for more information.  */)
   (Lisp_Object file)
 {
   if (NILP (file))
-- 
2.17.0.775.ge144d126d7