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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Paul Eggert <eggert@cs.ucla.edu>,  mail@bradyt.com,  
> 31636@debbugs.gnu.org,  npostavs@gmail.com
> Date: Tue, 29 May 2018 21:06:01 +0200
> 
> > 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).
> 
> I understood the OP's concern to be that there was no obvious link
> from '.#' files and the fact that those files are used for locking. I
> donʼt see a need to put all the details about that locking in the doc
> string.

My reasoning was that if someone wants to know about these funny file
names, someone else would like to know more.  E.g., the symlink points
to a specially-formatted target, and that target records important
info.

> >>    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.
> 
> How is it a half-truth? Is the lockfile name not constructed by
> prepending '.#' to the filename?

It is, but you don't actually say that.  The whole truth would be

  It does this by creating a symlink whose name is
  @file{.#@var{fname}}, where @var{fname} is the name of the locked
  file.

Given Paul's comments, perhaps we should simply say

  It does this by creating a symlink whose name begins with
  @file{.#}

and leave the rest to the ELisp manual.

> > 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?
> 
> Didnʼt you make the point just now that this kind of detail could
> change and weʼd forget to update the documentation? Or did you want
> this in the elisp manual?

The latter.