[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#31636: 27.0.50; lockfile syntax searchable from info manual
From: |
Robert Pluim |
Subject: |
bug#31636: 27.0.50; lockfile syntax searchable from info manual |
Date: |
Thu, 31 May 2018 12:29:54 +0200 |
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);