bug#34911: 26.1; doc about lock file names

bug#34911: 26.1; doc about lock file names

[Drew Adams]

> > The default value is "^\\.?#\\|^\\.$\\|^\\.\\.$".
> >
> > \\.?# matches only the first char of an auto-save file
> > name, and the first two chars of a lock file name.  It
> > does not match the full name, requiring it to end with
> > `#'.  That means that (1) it cannot be used as is for,
> > say, font-locking such a (complete) name, and (2) as
> > it is now, it can falsely identify files that are not
> > auto-save or lock files.
> 
> Then maybe we need to change the default value, but that's a separate
> issue.  AFAIU, the bug report was about documentation.

Yes, improving the default value is welcome (and needed).
But currently it is unchanged.  As a result there is a
doc bug because what the doc says about the default value
is incorrect.  If you fix the default value to be what
the doc says then the doc will not need to change.  Else
it does need to change.

BTW, I think (but am not 100% sure) that `^' and `$' are
the wrong things to use here.  Instead, `\`' and `\''
should be used.

> > Also, please add a doc string for `dired-omit-regexp',
> > referring to `dired-omit-files' (where this missing doc
> > will hopefully be added) and `dired-omit-extensions', as
> > is done for `dired-mark-omitted', for example.
> 
> Another separate issue, unrelated to file locks, AFAIU.

Do you need a separate bug report for that?

> > Does this clarify what I meant by "the default value only
> > approximately matches auto-save files (and lock files?)"?
> 
> Yes, but I don't necessarily see that as a problem.

Why not?

bug#34911: 26.1; doc about lock file names

[Eli Zaretskii]

> Date: Tue, 19 Mar 2019 13:15:00 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 34911@debbugs.gnu.org
> 
> > Then maybe we need to change the default value, but that's a separate
> > issue.  AFAIU, the bug report was about documentation.
> 
> Yes, improving the default value is welcome (and needed).
> But currently it is unchanged.  As a result there is a
> doc bug because what the doc says about the default value
> is incorrect.

No, I don't see that it does.  At most, it says something that is not
100% accurate, in some rare cases.

> > > Does this clarify what I meant by "the default value only
> > > approximately matches auto-save files (and lock files?)"?
> > 
> > Yes, but I don't necessarily see that as a problem.
> 
> Why not?

Because the issues sound mostly theoretical to me.

bug#34911: 26.1; doc about lock file names

[Drew Adams]

> > I don't see documented anywhere what a lock file name looks like.
> > I looked through both the Emacs manual and the Elisp manual.  Did I miss
> > it somehow, or is it defined/described nowhere?
> 
> It is described in the node "File Locks" in the ELisp manual.

I started there.  I see nothing in that node that says
what the name looks like.  I'm using Emacs 26.  Did
someone perhaps add a description of it since that
release?

> > Please let users know what how lock files are named.  Thx.  If this is
> > already done somewhere, please refer to that location from node (elisp)
> > `File Locks'.
> 
> The node "Interlocking" in the user manual, where file locking is
> described on the user level, has a cross-reference to the above node
> pf ELisp manual.  So I'm unsure how you missed that.

Please explain how that replies to the text you quote,
or to any of the text in the bug report?  AFAICT, there
is nothing in the Emacs manual (including of course the
node you cite) or in the Elisp manual (including the node
you cite) that tells you how lock files are named.

That's what this bug report is about (and its near-duplicate,
#25469, also touches on this lack).  

> > Please also update the doc of `dired-omit-files' to make clear that its
> > default value only approximately matches auto-save files (and lock
> > files?), and that even this is true only for the default naming regime
> > for auto-save files.
> 
> I don't understand this part.  Concretely, what is missing in the doc
> string, and why do you think it is necessary to add whatever is
> missing?

The default value is "^\\.?#\\|^\\.$\\|^\\.\\.$".

\\.?# matches only the first char of an auto-save file
name, and the first two chars of a lock file name.  It
does not match the full name, requiring it to end with
`#'.  That means that (1) it cannot be used as is for,
say, font-locking such a (complete) name, and (2) as
it is now, it can falsely identify files that are not
auto-save or lock files.

And it does not necessarily match auto-save file names
at all, as they can be nearly anything, it seems:

(elisp) `Auto-Saving' makes a point of saying that each
of  `auto-save-file-name-p' and `make-auto-save-file-name'
exists "so that you can customize it if you wish to change
the naming convention for auto-save files".  And for each
it reminds us "If you redefine it, be sure to redefine the
[other] function ... correspondingly."

IOW, apparently the `#...#' is conventional but users are
practically invited to adopt alternative naming schemes.

While those two functions go together, so that changing
the naming scheme for one calls for changing it also for
the other, there are other functions and variables that
presume the standard naming convention.  Their doc does
not, so far, speak to the possibility of a naming change.

Also, please add a doc string for `dired-omit-regexp',
referring to `dired-omit-files' (where this missing doc
will hopefully be added) and `dired-omit-extensions', as
is done for `dired-mark-omitted', for example.

Does this clarify what I meant by "the default value only
approximately matches auto-save files (and lock files?)"?

bug#34911: 26.1; doc about lock file names

[Eli Zaretskii]

> Date: Tue, 19 Mar 2019 07:54:48 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 34911@debbugs.gnu.org
> 
> > > I don't see documented anywhere what a lock file name looks like.
> > > I looked through both the Emacs manual and the Elisp manual.  Did I miss
> > > it somehow, or is it defined/described nowhere?
> > 
> > It is described in the node "File Locks" in the ELisp manual.
> 
> I started there.  I see nothing in that node that says
> what the name looks like.  I'm using Emacs 26.  Did
> someone perhaps add a description of it since that
> release?

Yes, as I wrote in a followup message, this information is now present
in what will be Emacs 26.2.

> The default value is "^\\.?#\\|^\\.$\\|^\\.\\.$".
> 
> \\.?# matches only the first char of an auto-save file
> name, and the first two chars of a lock file name.  It
> does not match the full name, requiring it to end with
> `#'.  That means that (1) it cannot be used as is for,
> say, font-locking such a (complete) name, and (2) as
> it is now, it can falsely identify files that are not
> auto-save or lock files.

Then maybe we need to change the default value, but that's a separate
issue.  AFAIU, the bug report was about documentation.

> Also, please add a doc string for `dired-omit-regexp',
> referring to `dired-omit-files' (where this missing doc
> will hopefully be added) and `dired-omit-extensions', as
> is done for `dired-mark-omitted', for example.

Another separate issue, unrelated to file locks, AFAIU.

> Does this clarify what I meant by "the default value only
> approximately matches auto-save files (and lock files?)"?

Yes, but I don't necessarily see that as a problem.

bug#34911: 26.1; doc about lock file names

[Noam Postavsky]

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

Drew Adams <drew.adams@oracle.com> writes:
>
>> > Please also update the doc of `dired-omit-files' to make clear that its
>> > default value only approximately matches auto-save files (and lock
>> > files?), and that even this is true only for the default naming regime
>> > for auto-save files.
>> 
>> I don't understand this part.  Concretely, what is missing in the doc
>> string, and why do you think it is necessary to add whatever is
>> missing?
>
> The default value is "^\\.?#\\|^\\.$\\|^\\.\\.$".
>
> \\.?# matches only the first char of an auto-save file
> name, and the first two chars of a lock file name.  It
> does not match the full name, requiring it to end with
> `#'.  That means that (1) it cannot be used as is for,
> say, font-locking such a (complete) name, and (2) as
> it is now, it can falsely identify files that are not
> auto-save or lock files.

It's a regexp, so of course you can name files which aren't auto-save or
lock files in such a way that they match it.

> And it does not necessarily match auto-save file names
> at all, as they can be nearly anything, it seems:
>
> (elisp) `Auto-Saving' makes a point of saying that each
> of  `auto-save-file-name-p' and `make-auto-save-file-name'
> exists "so that you can customize it if you wish to change
> the naming convention for auto-save files".  And for each
> it reminds us "If you redefine it, be sure to redefine the
> [other] function ... correspondingly."
>
> IOW, apparently the `#...#' is conventional but users are
> practically invited to adopt alternative naming schemes.

How about we stop inviting that?  It sounds like something from before
user options were invented, and messing around with auto-save functions
kind of seems like asking for trouble.


[-- Attachment #2: patch --]
[-- Type: text/plain, Size: 4761 bytes --]

From a0a64e54e72d8b88810104e7fcc275dd1bb32bec Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Sun, 12 May 2019 12:27:41 -0400
Subject: [PATCH] Don't recommend redefining auto-save filename functions
 (Bug#34911)

* doc/lispref/backups.texi (Auto-Saving): Document
auto-save-file-name-transforms.
* lisp/files.el (make-auto-save-file-name)
(auto-save-file-name-p): Remove suggestion to redefine for
customization.
---
 doc/lispref/backups.texi | 67 +++++++++++++++++++-----------------------------
 lisp/files.el            |  5 ++--
 2 files changed, 30 insertions(+), 42 deletions(-)

diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index 6a5b6d1661..5f414e3066 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -460,6 +460,33 @@ Auto Save mode is enabled if @code{buffer-auto-save-file-name} is
 non-@code{nil} and @code{buffer-saved-size} (see below) is non-zero.
 @end deffn
 
+@defvar auto-save-file-name-transforms
+This variable lists transforms to apply to buffer file name before
+making auto-save file name.
+
+Each transform is a list of the form @code{(@var{regexp}
+@var{replacement} [@var{uniquify}])}: @var{regexp} is a regular
+expression to match against the file name.  If it matches,
+@code{replace-match} is used to replace the matching part with
+@var{replacement}.  If the optional element @var{uniquify} is non-nil,
+the auto-save file name is constructed by taking the directory part of
+the replaced file-name, concatenated with the buffer file name with
+all directory separators changed to @samp{!} to prevent clashes.  This
+will not work correctly if your filesystem truncates the resulting
+name.
+
+All the transforms in the list are tried, in the order they are listed.
+When one transform applies, its result is final;
+no further transforms are tried.
+
+The default value is set up to put the auto-save file into the
+temporary directory (@pxref{Unique File Names}) for editing a
+remote file.
+
+On MS-DOS filesystems without long names this variable is always
+ignored.
+@end defvar
+
 @defun auto-save-file-name-p filename
 This function returns a non-@code{nil} value if @var{filename} is a
 string that could be the name of an auto-save file.  It assumes
@@ -481,21 +508,6 @@ name.  The argument @var{filename} should not contain a directory part.
      @result{} nil
 @end group
 @end example
-
-The standard definition of this function is as follows:
-
-@example
-@group
-(defun auto-save-file-name-p (filename)
-  "Return non-nil if FILENAME can be yielded by..."
-  (string-match "^#.*#$" filename))
-@end group
-@end example
-
-This function exists so that you can customize it if you wish to
-change the naming convention for auto-save files.  If you redefine it,
-be sure to redefine the function @code{make-auto-save-file-name}
-correspondingly.
 @end defun
 
 @defun make-auto-save-file-name
@@ -511,31 +523,6 @@ function should check that variable first.
      @result{} "/xcssun/users/rms/lewis/#backups.texi#"
 @end group
 @end example
-
-Here is a simplified version of the standard definition of this
-function:
-
-@example
-@group
-(defun make-auto-save-file-name ()
-  "Return file name to use for auto-saves \
-of current buffer.."
-  (if buffer-file-name
-@end group
-@group
-      (concat
-       (file-name-directory buffer-file-name)
-       "#"
-       (file-name-nondirectory buffer-file-name)
-       "#")
-    (expand-file-name
-     (concat "#%" (buffer-name) "#"))))
-@end group
-@end example
-
-This exists as a separate function so that you can redefine it to
-customize the naming convention for auto-save files.  Be sure to
-change @code{auto-save-file-name-p} in a corresponding way.
 @end defun
 
 @defopt auto-save-visited-file-name
diff --git a/lisp/files.el b/lisp/files.el
index f3b502095d..501073c71c 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -6176,7 +6176,7 @@ (defun rename-auto-save-file ()
 (defun make-auto-save-file-name ()
   "Return file name to use for auto-saves of current buffer.
 Does not consider `auto-save-visited-file-name' as that variable is checked
-before calling this function.  You can redefine this for customization.
+before calling this function.
 See also `auto-save-file-name-p'."
   (if buffer-file-name
       (let ((handler (find-file-name-handler buffer-file-name
@@ -6283,7 +6283,8 @@ (defun make-auto-save-file-name ()
 
 (defun auto-save-file-name-p (filename)
   "Return non-nil if FILENAME can be yielded by `make-auto-save-file-name'.
-FILENAME should lack slashes.  You can redefine this for customization."
+FILENAME should lack slashes.
+See also `make-auto-save-file-name'."
   (string-match "\\`#.*#\\'" filename))
 \f
 (defun wildcard-to-regexp (wildcard)
-- 
2.11.0

bug#34911: 26.1; doc about lock file names

[Noam Postavsky]

Noam Postavsky <npostavs@gmail.com> writes:

> Drew Adams <drew.adams@oracle.com> writes:
>>
>> The default value is "^\\.?#\\|^\\.$\\|^\\.\\.$".
>>
>> \\.?# matches only the first char of an auto-save file
>> name, and the first two chars of a lock file name.  It
>> does not match the full name, requiring it to end with
>> `#'.  That means that (1) it cannot be used as is for,
>> say, font-locking such a (complete) name, and (2) as
>> it is now, it can falsely identify files that are not
>> auto-save or lock files.
>
> It's a regexp, so of course you can name files which aren't auto-save or
> lock files in such a way that they match it.

After looking at it some more, I realize you were probably suggesting
that the regexp should have something like "^.#\\|^#.*#$" instead of
"^\\.?#"

bug#34911: 26.1; doc about lock file names

[Drew Adams]

> >> The default value is "^\\.?#\\|^\\.$\\|^\\.\\.$".
> >>
> >> \\.?# matches only the first char of an auto-save file
> >> name, and the first two chars of a lock file name.  It
> >> does not match the full name, requiring it to end with
> >> `#'.  That means that (1) it cannot be used as is for,
> >> say, font-locking such a (complete) name, and (2) as
> >> it is now, it can falsely identify files that are not
> >> auto-save or lock files.
> >
> > It's a regexp, so of course you can name files which aren't auto-save or
> > lock files in such a way that they match it.
> 
> After looking at it some more, I realize you were probably suggesting
> that the regexp should have something like "^.#\\|^#.*#$" instead of
> "^\\.?#"

No, I don't think so.  It is correct, I think, to
say that the beginning matches .# (or the whole
thing matches . or ..) - that is, the dot is literal.

What I was saying was that it is not enough to say
how it starts.  It should (in all cases) match the
full file name.  (And it is better to use \` and \'.)

A main reason is what I mentioned: being able to
reuse the variable for font-locking.

I do that in `dired+.el', for example.  Option
`diredp-omit-files-regexp' is a regexp to font-lock
file names omitted by `dired-omit-mode'.

The default value is defined this way, reusing the
value of `dired-omit-files':

(let* ((strg  dired-omit-files) ; <=========== Reuse it
       (strg  (if (eq ?^ (aref strg 0)) ; Remove initial ^
                  (substring strg 1)
                strg))
       (strg  (replace-regexp-in-string
               "\\(\\\\[|]\\)\\^"       ; Remove other ^'s
               "\\1"
               strg
               'FIXEDCASE
               nil))
       (strg  (replace-regexp-in-string
               "\\([$]\\)"              ; Remove $'s
               ""
               strg
               'FIXEDCASE
               nil)))
  strg)

Doc string:

Regexp for font-locking file names to be omitted by `dired-omit-mode'.
The regexp is matched only against the file name, but the entire line
is highlighted (with face `diredp-omit-file-name').

The default value of this option differs from that of
`dired-omit-files' by removing "^" from the beginning, and "$"
from the end, of each regexp choice.  (The default value of
`dired-omit-files', at least prior to Emacs 27, uses "^" and "$",
but it should not.)

If you want to control the beginning and end of choice matches then
use "\`" and "\'" instead of "^" and "$".

Note: If you change the value of this option then you need to restart
Emacs to see the effect of the new value on font-locking.

bug#34911: 26.1; doc about lock file names

[Noam Postavsky]

Drew Adams <drew.adams@oracle.com> writes:

>> >> The default value is "^\\.?#\\|^\\.$\\|^\\.\\.$".
>> >>
>> >> \\.?# matches only the first char of an auto-save file
>> >> name, and the first two chars of a lock file name.  It
>> >> does not match the full name, requiring it to end with
>> >> `#'.  That means that (1) it cannot be used as is for,
>> >> say, font-locking such a (complete) name, and (2) as
>> >> it is now, it can falsely identify files that are not
>> >> auto-save or lock files.
>> >
>> > It's a regexp, so of course you can name files which aren't auto-save or
>> > lock files in such a way that they match it.
>> 
>> After looking at it some more, I realize you were probably suggesting
>> that the regexp should have something like "^.#\\|^#.*#$" instead of
>> "^\\.?#"
>
> No, I don't think so.  It is correct, I think, to
> say that the beginning matches .# (or the whole
> thing matches . or ..) - that is, the dot is literal.

Sorry, forgot to escape the dot, I meant

    "^\\.#\\|^#.*#$" instead of "^\\.?#"

bug#34911: 26.1; doc about lock file names

[Drew Adams]

> >> >> The default value is "^\\.?#\\|^\\.$\\|^\\.\\.$".
> >> >>
> >> >> \\.?# matches only the first char of an auto-save file
> >> >> name, and the first two chars of a lock file name.  It
> >> >> does not match the full name, requiring it to end with
> >> >> `#'.  That means that (1) it cannot be used as is for,
> >> >> say, font-locking such a (complete) name, and (2) as
> >> >> it is now, it can falsely identify files that are not
> >> >> auto-save or lock files.
> >> >
> >> > It's a regexp, so of course you can name files which aren't auto-save or
> >> > lock files in such a way that they match it.
> >>
> >> After looking at it some more, I realize you were probably suggesting
> >> that the regexp should have something like "^.#\\|^#.*#$" instead of
> >> "^\\.?#"
> >
> > No, I don't think so.  It is correct, I think, to
> > say that the beginning matches .# (or the whole
> > thing matches . or ..) - that is, the dot is literal.
> 
> Sorry, forgot to escape the dot, I meant
> 
>     "^\\.#\\|^#.*#$" instead of "^\\.?#"

I don't think so.  More like this, I think:

"^\\.?#[^#]#$\\|^\\.$\\|^\\.\\.$" or preferably this:

"\\`\\.?#[^#]#\\'\\|\\`\\.\\'\\|\\`\\.\\.\\'"

But maybe .* is better than [^#]; dunno.

I don't have time to check right now, but I think
the names to match, besides . and .., start with
.# or # and end with #.  The idea is to match the
start and end, and whatever is between the two.

bug#34911: 26.1; doc about lock file names

[Noam Postavsky]

Drew Adams <drew.adams@oracle.com> writes:

>>     "^\\.#\\|^#.*#$" instead of "^\\.?#"
>
> I don't think so.  More like this, I think:
>
> "^\\.?#[^#]#$\\|^\\.$\\|^\\.\\.$" or preferably this:

This will fail to match lock file names (because they don't end in "#").

> But maybe .* is better than [^#]; dunno.

Specifically, [^#] will fail for filenames that include "#".

(let ((buffer-file-name "/foo/my-#tag-list"))
  (make-auto-save-file-name)) ;=> "/foo/#my-#tag-list#"

bug#34911: 26.1; doc about lock file names

[Drew Adams]

> >>     "^\\.#\\|^#.*#$" instead of "^\\.?#"
> >
> > I don't think so.  More like this, I think:
> 
> This will fail to match lock file names (because they don't end in "#").

Good.  (This is why doc was needed.)

> > But maybe .* is better than [^#]; dunno.

And anyway, I forgot * after [^#].

> Specifically, [^#] will fail for filenames that include "#".
> (let ((buffer-file-name "/foo/my-#tag-list"))
>   (make-auto-save-file-name)) ;=> "/foo/#my-#tag-list#"

Right  I had forgotten whether that was allowed.
Checking (elisp) `Auto-Saving'...

OK.  So maybe it should be something like this:

"\\`\\.#.*\\|\\`\\.?#.*#\\'\\|\\`\\.\\'\\|\\`\\.\\.\\'"

where:

Lock file: "\\`\\.#.*" - starts with ".#" and ends at eol.
Auto-save file: "\\`#.*#\\'" - starts and ends with "#".
Current or parent directory: "\\`\\.\\'\\|\\`\\.\\.\\" - "." or ".."

bug#34911: 26.1; doc about lock file names

[Lars Ingebrigtsen]

Noam Postavsky <npostavs@gmail.com> writes:

> How about we stop inviting that?  It sounds like something from before
> user options were invented, and messing around with auto-save functions
> kind of seems like asking for trouble.

[...]

> * doc/lispref/backups.texi (Auto-Saving): Document
> auto-save-file-name-transforms.
> * lisp/files.el (make-auto-save-file-name)
> (auto-save-file-name-p): Remove suggestion to redefine for
> customization.

There was no discussion of this patch, but it makes sense to me, so I
went ahead and applied it to Emacs 28.

Drew had some other suggestions here, but I think this doc change is
sufficient, so I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#34911: 26.1; doc about lock file names

[Drew Adams]

I take that as a "won't fix".

I don't have time to belabor this.  I'm hoping that Noam might take another look and follow up with some of the changes needed.  If not, too bad.

bug#34911: 26.1; doc about lock file names

[Drew Adams]

I started from the doc of `dired-omit-files', which says:

  The default is to omit `.', `..', auto-save files and lock files.
                                                        ^^^^^^^^^^

And the default value is this: "^\\.?#\\|^\\.$\\|^\\.\\.$"

I can only guess that a lock file has either the same syntax as (the
default syntax of) an auto-save file: `#...#', or that prefixed by `.':
`.#...#'.  In fact, it's a stretch to guess even that, as the ^\.?#
doesn't necessarily match even an auto-save file (no # appended).

I don't see documented anywhere what a lock file name looks like.
I looked through both the Emacs manual and the Elisp manual.  Did I miss
it somehow, or is it defined/described nowhere?

Please let users know what how lock files are named.  Thx.  If this is
already done somewhere, please refer to that location from node (elisp)
`File Locks'.

Please also update the doc of `dired-omit-files' to make clear that its
default value only approximately matches auto-save files (and lock
files?), and that even this is true only for the default naming regime
for auto-save files.

In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#34911: 26.1; doc about lock file names

[Glenn Morris]

https://debbugs.gnu.org/25469

bug#34911: 26.1; doc about lock file names

[Drew Adams]

> https://urldefense.proofpoint.com/v2/url?u=https-
> 3A__debbugs.gnu.org_25469&d=DwIBAg&c=RoP1YumCXCgaWHvlZYR8PZh8Bv7qIrMUB65eapI_
> JnE&r=kI3P6ljGv6CTHIKju0jqInF6AOwMCYRDQUmqX22rJ98&m=ZQXJQudbtYivz1y22NetuHLhZ
> w6CxfyhnaFolvxcbS8&s=1vr5xywPgW1Od5O-51aGFhhPoAmPbYnHwGhA2JYv7EI&e=

Thanks.  So it's a duplicate.  Good to know.

bug#34911: 26.1; doc about lock file names

[Eli Zaretskii]

close 25469 26.2
thanks

> From: Glenn Morris <rgm@gnu.org>
> Date: Mon, 18 Mar 2019 19:17:51 -0400
> 
> 
> https://debbugs.gnu.org/25469

This was fixed already, so that bug should be closed.

I'm not yet closing this one, because it seems to say something beyond
the issue raised in 25469.

bug#34911: 26.1; doc about lock file names

[Eli Zaretskii]

> Date: Mon, 18 Mar 2019 15:47:52 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> I don't see documented anywhere what a lock file name looks like.
> I looked through both the Emacs manual and the Elisp manual.  Did I miss
> it somehow, or is it defined/described nowhere?

It is described in the node "File Locks" in the ELisp manual.

> Please let users know what how lock files are named.  Thx.  If this is
> already done somewhere, please refer to that location from node (elisp)
> `File Locks'.

The node "Interlocking" in the user manual, where file locking is
described on the user level, has a cross-reference to the above node
pf ELisp manual.  So I'm unsure how you missed that.

> Please also update the doc of `dired-omit-files' to make clear that its
> default value only approximately matches auto-save files (and lock
> files?), and that even this is true only for the default naming regime
> for auto-save files.

I don't understand this part.  Concretely, what is missing in the doc
string, and why do you think it is necessary to add whatever is
missing?

bug#34911: 26.1; doc about lock file names

[Eli Zaretskii]

> Date: Tue, 19 Mar 2019 08:56:40 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: 34911@debbugs.gnu.org
> 
> It is described in the node "File Locks" in the ELisp manual.
> 
> > Please let users know what how lock files are named.  Thx.  If this is
> > already done somewhere, please refer to that location from node (elisp)
> > `File Locks'.
> 
> The node "Interlocking" in the user manual, where file locking is
> described on the user level, has a cross-reference to the above node
> of ELisp manual.  So I'm unsure how you missed that.

Oh, I see you reported this from Emacs 26.1, whose manuals don't
include the additions I mentioned.  That explains why you didn't see
them.