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

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

[Brady Trainor]

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.

Thank you!

-- 
Brady

In GNU Emacs 27.0.50 (build 1, x86_64-apple-darwin17.4.0, NS appkit-1561.20 Version 10.13.3 (Build 17D102))
 of 2018-04-11 built on computer
Repository revision: 57442b6812e9ec565efc39f722e84079dd71d8c0
System Description:  Mac OS X 10.13.3

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Making completion list...

Configured using:
 'configure --disable-dependency-tracking --disable-silent-rules
 --enable-locallisppath=/usr/local/share/emacs/site-lisp
 --infodir=/usr/local/Cellar/emacs/HEAD-57442b6/share/info/emacs
 --prefix=/usr/local/Cellar/emacs/HEAD-57442b6 --without-x --with-xml2
 --with-dbus --with-gnutls --with-imagemagick --with-modules --with-rsvg
 --without-pop --with-ns --disable-ns-self-contained'

Configured features:
RSVG IMAGEMAGICK DBUS NOTIFY ACL GNUTLS LIBXML2 ZLIB TOOLKIT_SCROLL_BARS
NS MODULES THREADS

Important settings:
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message rmc puny seq byte-opt gv
bytecomp byte-compile cconv dired dired-loaddefs format-spec rfc822 mml
easymenu mml-sec password-cache epa derived epg epg-config gnus-util
rmail rmail-loaddefs mm-decode mm-bodies mm-encode mail-parse rfc2231
mailabbrev gmm-utils mailheader cl-loaddefs cl-lib sendmail rfc2047
rfc2045 ietf-drums mm-util mail-prsvr mail-utils term/screen term/xterm
xterm time-date elec-pair tooltip eldoc electric uniquify ediff-hook
vc-hooks lisp-float-type mwheel term/ns-win ns-win ucs-normalize
mule-util term/common-win tool-bar dnd fontset image regexp-opt fringe
tabulated-list replace newcomment text-mode elisp-mode lisp-mode
prog-mode register page menu-bar rfn-eshadow isearch timer select
scroll-bar mouse jit-lock font-lock syntax facemenu font-core
term/tty-colors frame cl-generic cham georgian utf-8-lang misc-lang
vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms cp51932
hebrew greek romanian slovak czech european ethiopic indian cyrillic
chinese composite charscript charprop case-table epa-hook jka-cmpr-hook
help simple abbrev obarray minibuffer cl-preloaded nadvice loaddefs
button faces cus-face macroexp files text-properties overlay sha1 md5
base64 format env code-pages mule custom widget hashtable-print-readable
backquote dbusbind kqueue cocoa ns multi-tty make-network-process emacs)

Memory information:
((conses 16 208559 10343)
 (symbols 48 20073 1)
 (miscs 40 33 124)
 (strings 32 29281 1750)
 (string-bytes 1 769239)
 (vectors 16 33056)
 (vector-slots 8 675093 10872)
 (floats 8 51 470)
 (intervals 56 232 0)
 (buffers 992 12))

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

[Robert Pluim]

[-- Attachment #1: Type: text/plain, Size: 922 bytes --]

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?)


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-more-discoverable-documentation-for.patch --]
[-- Type: text/x-patch, Size: 1967 bytes --]

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

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

[Noam Postavsky]

Robert Pluim <rpluim@gmail.com> writes:

> 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.

Yes, that's usually the case.  I think you can drop the word "currently"
from your patch.

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

[Robert Pluim]

[-- Attachment #1: Type: text/plain, Size: 375 bytes --]

Noam Postavsky <npostavs@gmail.com> writes:

> Robert Pluim <rpluim@gmail.com> writes:
>
>> 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.
>
> Yes, that's usually the case.  I think you can drop the word "currently"
> from your patch.

OK. V2 attached.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-more-discoverable-documentation-for.patch --]
[-- Type: text/x-patch, Size: 1952 bytes --]

From 03525a8319ba7a1fb9d1375fa989db0bf9f7feb1 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..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 .#
   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
 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..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.  */)
   (Lisp_Object file)
 {
   if (NILP (file))
-- 
2.17.0.775.ge144d126d7

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

[Eli Zaretskii]

> 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.

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

[Robert Pluim]

Eli Zaretskii <eliz@gnu.org> writes:

>
> 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.

> 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.

See my previous paragraph: the goal is to inform the user that file
locking is occurring, so the user manual is a good place to make that
clear (without necessarily going into the gory details).

> 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??).

Not by me: I trust your taste.

>> 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

See, Iʼve learnt something from you again, and the end result will be
better for it :-)

>
>>    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?

>> 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.

Makes sense.

> 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?

Robert

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

[Paul Eggert]

On 05/29/2018 09:46 AM, Eli Zaretskii wrote:
> I'd be interested to hear Paul's take on this, as someone who worked
> on the related code not too long ago.  Paul?

On the one hand this is low-level detail. On the other, it is 
user-visible detail, e.g., when I use dired or 'ls' on a directory I'll 
see the symlinks. So I'd be mildly inclined to see a brief mention in 
the user manual with details as necessary in the elisp manual. The user 
manual could say something simple like 'lock files are directory entries 
whose names begin with ".#"'. If more details are needed, they could be 
in the elisp manual (e.g., MS-Windows lock names are independent of lock 
names of other systems).

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.

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

[Eli Zaretskii]

> Cc: npostavs@gmail.com, mail@bradyt.com, 31636@debbugs.gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Tue, 29 May 2018 12:20:48 -0700
> 
> On the one hand this is low-level detail. On the other, it is 
> user-visible detail, e.g., when I use dired or 'ls' on a directory I'll 
> see the symlinks. So I'd be mildly inclined to see a brief mention in 
> the user manual with details as necessary in the elisp manual. The user 
> manual could say something simple like 'lock files are directory entries 
> whose names begin with ".#"'. If more details are needed, they could be 
> in the elisp manual (e.g., MS-Windows lock names are independent of lock 
> names of other systems).

OK, let's do it this way.

Thanks.

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

[Robert Pluim]

Eli Zaretskii <eliz@gnu.org> writes:

>> > 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.

So what I currently have is below. create-lockfiles references the
user manual (and 'lock-buffer') which in turn references the lisp
reference manual.

Do we want a '.#' index entry in the lispref as well?
Do I need to explain that USER will be replaced by the current user,
etc?

Let the wordsmithing begin!

2018-05-31  Robert Pluim  <rpluim@gmail.com>

	* src/filelock.c (create-lockfiles): Add cross reference to
	file locking in user manual and to 'lock-buffer'.  Add string
	'.#' to help users find the doc string.

	* doc/emacs/files.texi (Interlocking): Point user at detailed
	file locking description in lisp reference manual.  Add index
	entry for '.#' to improve disoverability of information about locking.

	* doc/lispref/files.texi (File Locks): Describe in detail what
	the form of the lock file is.

diff --git i/doc/emacs/files.texi w/doc/emacs/files.texi
index 1ced7ca07c..406e7d980c 100644
--- i/doc/emacs/files.texi
+++ w/doc/emacs/files.texi
@@ -766,13 +766,16 @@ Interlocking
 
 @findex ask-user-about-lock
 @cindex locking files
+@cindex .#, lock file names
+@cindex file locking
   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
 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
-whenever an Emacs buffer visiting it has unsaved changes.
+used.} with special contents in the same directory. @xref{File
+Locks,,, elisp} for more details.)  Emacs removes the lock when you
+save the changes.  The idea is that the file is locked whenever an
+Emacs buffer visiting it has unsaved changes.
 
 @vindex create-lockfiles
   You can prevent the creation of lock files by setting the variable
diff --git i/doc/lispref/files.texi w/doc/lispref/files.texi
index f62b670f47..89a98bd588 100644
--- i/doc/lispref/files.texi
+++ w/doc/lispref/files.texi
@@ -720,8 +720,13 @@ File Locks
 Emacs can then detect the first attempt to modify a buffer visiting a
 file that is locked by another Emacs job, and ask the user what to do.
 The file lock is really a file, a symbolic link with a special name,
-stored in the same directory as the file you are editing.  (On file
-systems that do not support symbolic links, a regular file is used.)
+stored in the same directory as the file you are editing.  The name is
+constructed by prepending @file{.#} to the filename of the buffer.
+The target of the symbolic link will be of the form
+@code{USER@@HOST.PID:BOOT}.  @code{:BOOT} is omitted if the boot time
+is unavailable.  (On file systems that do not support symbolic links,
+a regular file is used instead, with contents of the form
+@code{USER@@HOST.PID:BOOT}.)
 
   When you access files using NFS, there may be a small probability that
 you and another user will both lock the same file simultaneously.
diff --git i/src/filelock.c w/src/filelock.c
index f2dc723407..4f7ec414f5 100644
--- i/src/filelock.c
+++ w/src/filelock.c
@@ -849,7 +849,9 @@ syms_of_filelock (void)
   Vtemporary_file_directory = Qnil;
 
   DEFVAR_BOOL ("create-lockfiles", create_lockfiles,
-	       doc: /* Non-nil means use lockfiles to avoid editing collisions.  */);
+	       doc: /* Non-nil means use lockfiles to avoid editing collisions.
+The names of the lockfiles will start with `.#'.  See also
+`lock-buffer' and Info node `(emacs)Interlocking'.  */);
   create_lockfiles = 1;
 
   defsubr (&Sunlock_buffer);

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: mail@bradyt.com,  31636@debbugs.gnu.org,  eggert@cs.ucla.edu,  npostavs@gmail.com
> Date: Thu, 31 May 2018 12:29:54 +0200
> 
> Do we want a '.#' index entry in the lispref as well?

Yes.

> Do I need to explain that USER will be replaced by the current user,
> etc?

Yes, I think so.

> --- i/doc/emacs/files.texi
> +++ w/doc/emacs/files.texi
> @@ -766,13 +766,16 @@ Interlocking
>  
>  @findex ask-user-about-lock
>  @cindex locking files
> +@cindex .#, lock file names
> +@cindex file locking
>    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
>  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
> -whenever an Emacs buffer visiting it has unsaved changes.
> +used.} with special contents in the same directory. @xref{File
> +Locks,,, elisp} for more details.)  Emacs removes the lock when you
> +save the changes.  The idea is that the file is locked whenever an
> +Emacs buffer visiting it has unsaved changes.

This is OK.

> --- i/doc/lispref/files.texi
> +++ w/doc/lispref/files.texi
> @@ -720,8 +720,13 @@ File Locks
>  Emacs can then detect the first attempt to modify a buffer visiting a
>  file that is locked by another Emacs job, and ask the user what to do.
>  The file lock is really a file, a symbolic link with a special name,
> -stored in the same directory as the file you are editing.  (On file
> -systems that do not support symbolic links, a regular file is used.)
> +stored in the same directory as the file you are editing.  The name is
> +constructed by prepending @file{.#} to the filename of the buffer.
> +The target of the symbolic link will be of the form
> +@code{USER@@HOST.PID:BOOT}.  @code{:BOOT} is omitted if the boot time
> +is unavailable.  (On file systems that do not support symbolic links,
> +a regular file is used instead, with contents of the form
> +@code{USER@@HOST.PID:BOOT}.)

This should use @var{user}, @var{host} etc. for the components of the
target file name, and it should explain shortly what each component
stands for.

> diff --git i/src/filelock.c w/src/filelock.c
> index f2dc723407..4f7ec414f5 100644
> --- i/src/filelock.c
> +++ w/src/filelock.c
> @@ -849,7 +849,9 @@ syms_of_filelock (void)
>    Vtemporary_file_directory = Qnil;
>  
>    DEFVAR_BOOL ("create-lockfiles", create_lockfiles,
> -	       doc: /* Non-nil means use lockfiles to avoid editing collisions.  */);
> +	       doc: /* Non-nil means use lockfiles to avoid editing collisions.
> +The names of the lockfiles will start with `.#'.  See also
> +`lock-buffer' and Info node `(emacs)Interlocking'.  */);

Here I would say that the name of the lockfile is constructed by
prepending a '.#' to the name of the file being locked.

Thanks.

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

[Robert Pluim]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Robert Pluim <rpluim@gmail.com>
>> Cc: mail@bradyt.com,  31636@debbugs.gnu.org,  eggert@cs.ucla.edu,  npostavs@gmail.com
>> Date: Thu, 31 May 2018 12:29:54 +0200
>> 
>> Do we want a '.#' index entry in the lispref as well?
>
> Yes.
>

Done.

>> Do I need to explain that USER will be replaced by the current user,
>> etc?
>
> Yes, I think so.

I should have known better than to ask. Done. I even gritted my teeth
and wrote "Emacs's".

> This should use @var{user}, @var{host} etc. for the components of the
> target file name, and it should explain shortly what each component
> stands for.

I donʼt see any difference in the visual appearance from using @var,
but I made the change anyway, and expanded the explanation (I noticed
that texinfo.el has no bindings for inserting @ref, @xref, and @pxref,
should I add some?  C-cC-c[rp] are free, but x is already used for
@example, so 'C-cC-cX'? Or maybe 'C-cC-cC-x' for @xref?)

> Here I would say that the name of the lockfile is constructed by
> prepending a '.#' to the name of the file being locked.

Done.

2018-05-31  Robert Pluim  <rpluim@gmail.com>

	* src/filelock.c (create-lockfiles): Add cross reference to
	file locking in user manual and to 'lock-buffer'.  Add string
	'.#' to help users find the doc string.

	* doc/emacs/files.texi (Interlocking): Point user at detailed
	file locking description in lisp reference manual.  Add index
	entry for '.#' to improve disoverability of information about locking.

	* doc/lispref/files.texi (File Locks): Describe in detail what
	the form of the lock file is.  Add index entry for '.#' to
	improve disoverability of information about locking.

diff --git i/doc/emacs/files.texi w/doc/emacs/files.texi
index 1ced7ca07c..406e7d980c 100644
--- i/doc/emacs/files.texi
+++ w/doc/emacs/files.texi
@@ -766,13 +766,16 @@ Interlocking
 
 @findex ask-user-about-lock
 @cindex locking files
+@cindex .#, lock file names
+@cindex file locking
   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
 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
-whenever an Emacs buffer visiting it has unsaved changes.
+used.} with special contents in the same directory. @xref{File
+Locks,,, elisp} for more details.)  Emacs removes the lock when you
+save the changes.  The idea is that the file is locked whenever an
+Emacs buffer visiting it has unsaved changes.
 
 @vindex create-lockfiles
   You can prevent the creation of lock files by setting the variable
diff --git i/doc/lispref/files.texi w/doc/lispref/files.texi
index f62b670f47..012a7a0a7c 100644
--- i/doc/lispref/files.texi
+++ w/doc/lispref/files.texi
@@ -712,6 +712,7 @@ File Locks
 @section File Locks
 @cindex file locks
 @cindex lock file
+@cindex .#, lock file names
 
   When two users edit the same file at the same time, they are likely
 to interfere with each other.  Emacs tries to prevent this situation
@@ -720,8 +721,17 @@ File Locks
 Emacs can then detect the first attempt to modify a buffer visiting a
 file that is locked by another Emacs job, and ask the user what to do.
 The file lock is really a file, a symbolic link with a special name,
-stored in the same directory as the file you are editing.  (On file
-systems that do not support symbolic links, a regular file is used.)
+stored in the same directory as the file you are editing.  The name is
+constructed by prepending @file{.#} to the filename of the buffer.
+The target of the symbolic link will be of the form
+@code{@var{user}@@@var{host}.@var{pid}:@var{boot}}, where @var{user}
+is replaced with the current username (from @code{user-login-name}),
+@var{host} with the name of the host where Emacs is running (from
+@code{system-name}), @var{pid} with Emacs's process id, and @var{boot}
+with the time since the last reboot.  @code{:@var{boot}} is omitted if
+the boot time is unavailable.  (On file systems that do not support
+symbolic links, a regular file is used instead, with contents of the
+form @code{@var{user}@@@var{host}.@var{pid}:@var{boot}}.)
 
   When you access files using NFS, there may be a small probability that
 you and another user will both lock the same file simultaneously.
diff --git i/src/filelock.c w/src/filelock.c
index f2dc723407..d33063c879 100644
--- i/src/filelock.c
+++ w/src/filelock.c
@@ -849,7 +849,10 @@ syms_of_filelock (void)
   Vtemporary_file_directory = Qnil;
 
   DEFVAR_BOOL ("create-lockfiles", create_lockfiles,
-	       doc: /* Non-nil means use lockfiles to avoid editing collisions.  */);
+	       doc: /* Non-nil means use lockfiles to avoid editing collisions.
+The name of the (per-buffer) lockfile is constructed by prepending a
+'.#' to the name of the file being locked.  See also `lock-buffer' and
+Info node `(emacs)Interlocking'.  */);
   create_lockfiles = 1;
 
   defsubr (&Sunlock_buffer);

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: mail@bradyt.com,  31636@debbugs.gnu.org,  eggert@cs.ucla.edu,  npostavs@gmail.com
> Date: Fri, 01 Jun 2018 12:47:54 +0200
> 
> > This should use @var{user}, @var{host} etc. for the components of the
> > target file name, and it should explain shortly what each component
> > stands for.
> 
> I donʼt see any difference in the visual appearance from using @var,

In Info format, you won't see any difference, because @var up-cases
its argument in that format.  But in the printed manual the visual
appearance of @var is very different: it gives the argument the
slanted typeface and doesn't up-case it.

> (I noticed that texinfo.el has no bindings for inserting @ref,
> @xref, and @pxref, should I add some?  C-cC-c[rp] are free, but x is
> already used for @example, so 'C-cC-cX'? Or maybe 'C-cC-cC-x' for
> @xref?)

How about using just "C-c C-c r" and letting it intuit the exact form
from the context?  @xref is only used at the beginning of a sentence,
and @pxref should normally follow an open paren.

In any case, adding this to texinfo.el would be a welcome addition, I
think.

The patch LGTM, thanks.

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

[Robert Pluim]

Eli Zaretskii <eliz@gnu.org> writes:

>> (I noticed that texinfo.el has no bindings for inserting @ref,
>> @xref, and @pxref, should I add some?  C-cC-c[rp] are free, but x is
>> already used for @example, so 'C-cC-cX'? Or maybe 'C-cC-cC-x' for
>> @xref?)
>
> How about using just "C-c C-c r" and letting it intuit the exact form
> from the context?  @xref is only used at the beginning of a sentence,
> and @pxref should normally follow an open paren.
>

OK. Iʼll think about how best to add that

> In any case, adding this to texinfo.el would be a welcome addition, I
> think.
>
> The patch LGTM, thanks.

Pushed as 9188291f7a to emacs-26.

Thanks

Robert

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

[Robert Pluim]

Eli Zaretskii <eliz@gnu.org> writes:

>> (I noticed that texinfo.el has no bindings for inserting @ref,
>> @xref, and @pxref, should I add some?  C-cC-c[rp] are free, but x is
>> already used for @example, so 'C-cC-cX'? Or maybe 'C-cC-cC-x' for
>> @xref?)
>
> How about using just "C-c C-c r" and letting it intuit the exact form
> from the context?  @xref is only used at the beginning of a sentence,
> and @pxref should normally follow an open paren.
>

OK. Iʼll think about how best to add that.

> In any case, adding this to texinfo.el would be a welcome addition, I
> think.
>
> The patch LGTM, thanks.

Pushed as 9188291f7a to emacs-26.

Thanks

Robert