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

[Eli Zaretskii <eliz@gnu.org>]

> From: Robert Pluim <rpluim@gmail.com>
> Date: Tue, 29 May 2018 15:17:26 +0200
> Cc: Brady Trainor <mail@bradyt.com>, 31636@debbugs.gnu.org
> 
> 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(-)

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.