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