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

[Eli Zaretskii <eliz@gnu.org>]

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