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

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

[Robert Pluim]

Robert Pluim <rpluim@gmail.com> writes:

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

And of course had I implemented it, I wouldn't have made the silly
mistake in markup that I just fixed and pushed.

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

Yes.

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

[Robert Pluim]

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

Hereʼs a simple implementation, no doubt Iʼve missed some corner cases.

diff --git i/lisp/textmodes/texinfo.el w/lisp/textmodes/texinfo.el
index c2ceee6e6b..b696b81c1c 100644
--- i/lisp/textmodes/texinfo.el
+++ w/lisp/textmodes/texinfo.el
@@ -470,6 +470,7 @@ texinfo-mode-map
     (define-key map "\C-c\C-cu"    'texinfo-insert-@uref)
     (define-key map "\C-c\C-ct"    'texinfo-insert-@table)
     (define-key map "\C-c\C-cs"    'texinfo-insert-@samp)
+    (define-key map "\C-c\C-cr"    'texinfo-insert-dwim-@ref)
     (define-key map "\C-c\C-cq"    'texinfo-insert-@quotation)
     (define-key map "\C-c\C-co"    'texinfo-insert-@noindent)
     (define-key map "\C-c\C-cn"    'texinfo-insert-@node)
@@ -826,6 +827,31 @@ texinfo-insert-@quotation
   "Insert the string `@quotation' in a Texinfo buffer."
   \n "@quotation" \n _ \n)
 
+(define-skeleton texinfo-insert-dwim-@ref
+  "Insert appropriate `@ref{...}', `@xref{}', or `@pxref{}' command
+in a Texinfo buffer depending on surrounding context.
+A numeric argument says how many words the braces should surround.
+The default is not to surround any existing words with the braces."
+  nil
+  (cond
+   ;; parenthetical
+   ((looking-back "\(")
+    "@pxref{")
+   ;; beginning of sentence
+   ((looking-back "  ")
+    "@xref{")
+   ;; bol or eol
+   ((looking-at "^\\|$")
+    "@ref{")
+   ;; inside word
+   ((not (eq (char-syntax (char-after)) ? ))
+    (skip-syntax-backward "^ ")
+    "@ref{")
+   ;; everything else
+   (t
+    "@ref{"))
+  _ "}")
+
 (define-skeleton texinfo-insert-@samp
   "Insert a `@samp{...}' command in a Texinfo buffer.
 A numeric argument says how many words the braces should surround.

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

[Andreas Schwab]

On Jun 04 2018, Robert Pluim <rpluim@gmail.com> wrote:

> @@ -826,6 +827,31 @@ texinfo-insert-@quotation
>    "Insert the string `@quotation' in a Texinfo buffer."
>    \n "@quotation" \n _ \n)
>  
> +(define-skeleton texinfo-insert-dwim-@ref
> +  "Insert appropriate `@ref{...}', `@xref{}', or `@pxref{}' command

The first line should be one complete sentence.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

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

[Robert Pluim]

Andreas Schwab <schwab@suse.de> writes:

> On Jun 04 2018, Robert Pluim <rpluim@gmail.com> wrote:
>
>> @@ -826,6 +827,31 @@ texinfo-insert-@quotation
>>    "Insert the string `@quotation' in a Texinfo buffer."
>>    \n "@quotation" \n _ \n)
>>  
>> +(define-skeleton texinfo-insert-dwim-@ref
>> +  "Insert appropriate `@ref{...}', `@xref{}', or `@pxref{}' command
>
> The first line should be one complete sentence.

If thatʼs the only thing wrong with it, I guess itʼs a go.

Robert

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: emacs-devel@gnu.org
> Date: Mon, 04 Jun 2018 11:41:24 +0200
> 
> +   ;; beginning of sentence
> +   ((looking-back "  ")
> +    "@xref{")

This misses the beginning of a sentence after a newline, right?

> +   ;; bol or eol
> +   ((looking-at "^\\|$")
> +    "@ref{")
> +   ;; inside word
> +   ((not (eq (char-syntax (char-after)) ? ))
> +    (skip-syntax-backward "^ ")
> +    "@ref{")
> +   ;; everything else
> +   (t
> +    "@ref{"))
> +  _ "}")

Why did you need the first 2 cases that yield @ref?

This will need a NEWS entry.

Thanks.

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Date: Mon, 04 Jun 2018 16:02:25 +0200
> Cc: emacs-devel@gnu.org
> 
> Andreas Schwab <schwab@suse.de> writes:
> 
> >> +(define-skeleton texinfo-insert-dwim-@ref
> >> +  "Insert appropriate `@ref{...}', `@xref{}', or `@pxref{}' command
> >
> > The first line should be one complete sentence.
> 
> If thatʼs the only thing wrong with it, I guess itʼs a go.

No, Andreas is just lightning-fast in responding.  It is usually a
good idea to leave a patch for a week at least before you decide there
are no more comments.

Thanks.

Re: 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: emacs-devel@gnu.org
>> Date: Mon, 04 Jun 2018 11:41:24 +0200
>> 
>> +   ;; beginning of sentence
>> +   ((looking-back "  ")
>> +    "@xref{")
>
> This misses the beginning of a sentence after a newline, right?

Hmm. (looking-back (sentence-end)) perhaps? Or if thatʼs overkill
"\\(?:  \\|\\.\n\\)"

(I did wonder why thereʼs no (sentence-beginning))

>> +   ;; bol or eol
>> +   ((looking-at "^\\|$")
>> +    "@ref{")
>> +   ;; inside word
>> +   ((not (eq (char-syntax (char-after)) ? ))
>> +    (skip-syntax-backward "^ ")
>> +    "@ref{")
>> +   ;; everything else
>> +   (t
>> +    "@ref{"))
>> +  _ "}")
>
> Why did you need the first 2 cases that yield @ref?

If I have text like this:

word one
word two
 ^

with point where the ^ is, then we need to skip backwards until we
reach whitespace, otherwise we insert the ref in the middle of a word.

If we have this:

word one
word two
^

Then we donʼt want to skip backwards, since we'll end up before 'one',
hence we need to check for bol first. Similar reasoning applies for
eol.

I strongly suspect you'll now either ask for this to be explained in
the code and the docstring, or show me a single line of code that
achieves the same effect, thus providing me with another Emacs 'Aha!'
moment.

> This will need a NEWS entry.

Of course. Something like this, which will also go in the doc string.

** Texinfo
*** New function for inserting @pxref, @xref, or @ref commands
The function 'texinfo-insert-dwim-@ref', bound to 'C-c C-c r' by
default, inserts one of the three types of references based on the text
surrounding point, namely @pxref after a parenthesis, @xref at the
start of a sentence, else @ref.

Regards

Robert

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: emacs-devel@gnu.org
> Date: Mon, 04 Jun 2018 19:17:16 +0200
> 
> >> +   ;; beginning of sentence
> >> +   ((looking-back "  ")
> >> +    "@xref{")
> >
> > This misses the beginning of a sentence after a newline, right?
> 
> Hmm. (looking-back (sentence-end)) perhaps? Or if thatʼs overkill
> "\\(?:  \\|\\.\n\\)"

sentence-end sounds fine to me.

> >> +   ;; bol or eol
> >> +   ((looking-at "^\\|$")
> >> +    "@ref{")
> >> +   ;; inside word
> >> +   ((not (eq (char-syntax (char-after)) ? ))
> >> +    (skip-syntax-backward "^ ")
> >> +    "@ref{")
> >> +   ;; everything else
> >> +   (t
> >> +    "@ref{"))
> >> +  _ "}")
> >
> > Why did you need the first 2 cases that yield @ref?
> 
> If I have text like this:

Sorry, I missed the skip-syntax-backward call.

> > This will need a NEWS entry.
> 
> Of course. Something like this, which will also go in the doc string.
> 
> ** Texinfo
> *** New function for inserting @pxref, @xref, or @ref commands

This should end with a period.

> The function 'texinfo-insert-dwim-@ref', bound to 'C-c C-c r' by
> default, inserts one of the three types of references based on the text
> surrounding point, namely @pxref after a parenthesis, @xref at the
> start of a sentence, else @ref.

OK.

Thanks.

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

[Robert Pluim]

Latest version attached. I now limit the skip-syntax-backward to the
current line.

I have no idea how it was working correctly before, unless I somehow
managed to mess up the syntax table in my texinfo buffer (or more
likely I tested in a non-texinfo buffer). Testing appreciated.

((char-syntax (char-before)) at bol is '?>' in texinfo mode, which is
somewhat surprising, since it's '? ' in text mode)

Since the texinfo mode info documentation is part of the texinfo
package, Iʼll need to send them a patch as well.

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

	* lisp/textmodes/texinfo.el (texinfo-insert-dwim-@ref): New
	function. Insert appropriate type of reference based on
	surrounding text.
	(texinfo-mode-map): Add binding for texinfo-insert-dwim-@ref.

diff --git i/etc/NEWS w/etc/NEWS
index 01dcb441a7..a06bd442c2 100644
--- i/etc/NEWS
+++ w/etc/NEWS
@@ -171,6 +171,13 @@ interface that's more like functions like @code{search-forward}.
 \f
 * Changes in Specialized Modes and Packages in Emacs 27.1
 
+** Texinfo
+*** New function for inserting @pxref, @xref, or @ref commands.
+The function 'texinfo-insert-dwim-@ref', bound to 'C-c C-c r' by
+default, inserts one of three types of references based on the text
+surrounding point, namely @pxref after a parenthesis, @xref at the
+start of a sentence, else @ref.
+
 ** Browse-url
 *** The function 'browse-url-emacs' can now visit a URL in selected window.
 It now treats the optional 2nd argument to mean that the URL should be
diff --git i/lisp/textmodes/texinfo.el w/lisp/textmodes/texinfo.el
index ff723a4fb9..67333ddcf2 100644
--- i/lisp/textmodes/texinfo.el
+++ w/lisp/textmodes/texinfo.el
@@ -470,6 +470,7 @@ texinfo-mode-map
     (define-key map "\C-c\C-cu"    'texinfo-insert-@uref)
     (define-key map "\C-c\C-ct"    'texinfo-insert-@table)
     (define-key map "\C-c\C-cs"    'texinfo-insert-@samp)
+    (define-key map "\C-c\C-cr"    'texinfo-insert-dwim-@ref)
     (define-key map "\C-c\C-cq"    'texinfo-insert-@quotation)
     (define-key map "\C-c\C-co"    'texinfo-insert-@noindent)
     (define-key map "\C-c\C-cn"    'texinfo-insert-@node)
@@ -825,6 +826,36 @@ texinfo-insert-@quotation
   "Insert the string `@quotation' in a Texinfo buffer."
   \n "@quotation" \n _ \n)
 
+(define-skeleton texinfo-insert-dwim-@ref
+  "Insert appropriate `@pxref{...}', `@xref{}', or `@pef{}' command.
+Looks at text around point to decide what to insert; point after
+a parenthesis results in '@pxref{}', at the beginning of a
+sentence yields '@xref{}', any other location (including inside a
+word), will result in '@ref{}' at the nearest previous whitespace
+or beginning-of-line.
+A numeric argument says how many words the braces should
+surround.  The default is not to surround any existing words with
+the braces."
+  nil
+  (cond
+   ;; parenthesis
+   ((looking-back "\(")
+    "@pxref{")
+   ;; beginning of sentence
+   ((looking-back (sentence-end))
+    "@xref{")
+   ;; bol or eol
+   ((looking-at "^\\|$")
+    "@ref{")
+   ;; inside word
+   ((not (eq (char-syntax (char-after)) ? ))
+    (skip-syntax-backward "^ " (point-at-bol))
+    "@ref{")
+   ;; everything else
+   (t
+    "@ref{"))
+  _ "}")
+
 (define-skeleton texinfo-insert-@samp
   "Insert a `@samp{...}' command in a Texinfo buffer.
 A numeric argument says how many words the braces should surround.

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

[Noam Postavsky]

 On 5 June 2018 at 15:51, Robert Pluim <rpluim@gmail.com> wrote:
> Latest version attached. I now limit the skip-syntax-backward to the
> current line.

> ((char-syntax (char-before)) at bol is '?>' in texinfo mode, which is
> somewhat surprising, since it's '? ' in text mode)

This is the case in every mode which supports line comments, I think.

> +  (cond
> +   ;; parenthesis
> +   ((looking-back "\(")

That "\(" should be just "(". And I think you'll want to give a limit
to the looking-back calls, otherwise they can keep searching until the
beginning of buffer.

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

[Robert Pluim]

Noam Postavsky <npostavs@gmail.com> writes:

>  On 5 June 2018 at 15:51, Robert Pluim <rpluim@gmail.com> wrote:
>> Latest version attached. I now limit the skip-syntax-backward to the
>> current line.
>
>> ((char-syntax (char-before)) at bol is '?>' in texinfo mode, which is
>> somewhat surprising, since it's '? ' in text mode)
>
> This is the case in every mode which supports line comments, I think.
>
>> +  (cond
>> +   ;; parenthesis
>> +   ((looking-back "\(")
>
> That "\(" should be just "(".

Overenthusiastic backslashitis strikes again.

> And I think you'll want to give a limit
> to the looking-back calls, otherwise they can keep searching until the
> beginning of buffer.

((looking-back "(") should never look at more than one character. I
could always do (eq (char-before) ?() I suppose.

The regexp produced by (sentence-end) looks like itʼs fairly well
anchored. Besides, Iʼm not searching for an end-of-sentence, Iʼm
asking "Am I at end-of-sentence".

Robert

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

[Noam Postavsky]

On 6 June 2018 at 03:43, Robert Pluim <rpluim@gmail.com> wrote:

>> And I think you'll want to give a limit
>> to the looking-back calls, otherwise they can keep searching until the
>> beginning of buffer.
>
> ((looking-back "(") should never look at more than one character.

Perhaps it shouldn't, but Emacs doesn't make that kind of optimization:

(with-temp-buffer
  (let ((last-command-event ?a))
    (dotimes (i 8)
      (self-insert-command (expt 10 i))
      (benchmark 1 '(looking-back "(")))))
Elapsed time: 0.000036s
Elapsed time: 0.000030s
Elapsed time: 0.000066s
Elapsed time: 0.000427s
Elapsed time: 0.004068s
Elapsed time: 0.040317s
Elapsed time: 0.422173s
Elapsed time: 1.514244s

(with-temp-buffer
  (let ((last-command-event ?a))
    (dotimes (i 8)
      (self-insert-command (expt 10 i))
      (benchmark 1 '(looking-back "(" (1- (point)))))))
Elapsed time: 0.000031s
Elapsed time: 0.000027s [5 times]
Elapsed time: 0.000041s
Elapsed time: 0.000045s

> I could always do (eq (char-before) ?() I suppose.

That's probably better. But wait! This time you *should* have a backslash: ?\(

> The regexp produced by (sentence-end) looks like itʼs fairly well
> anchored. Besides, Iʼm not searching for an end-of-sentence, Iʼm
> asking "Am I at end-of-sentence".

Which is exactly why you should put a limit.

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

[Robert Pluim]

Noam Postavsky <npostavs@gmail.com> writes:

> On 6 June 2018 at 03:43, Robert Pluim <rpluim@gmail.com> wrote:
>
>>> And I think you'll want to give a limit
>>> to the looking-back calls, otherwise they can keep searching until the
>>> beginning of buffer.
>>
>> ((looking-back "(") should never look at more than one character.
>
> Perhaps it shouldn't, but Emacs doesn't make that kind of optimization:
>
> (with-temp-buffer
>   (let ((last-command-event ?a))
>     (dotimes (i 8)
>       (self-insert-command (expt 10 i))
>       (benchmark 1 '(looking-back "(")))))
> Elapsed time: 0.000036s
> Elapsed time: 0.000030s
> Elapsed time: 0.000066s
> Elapsed time: 0.000427s
> Elapsed time: 0.004068s
> Elapsed time: 0.040317s
> Elapsed time: 0.422173s
> Elapsed time: 1.514244s
>
> (with-temp-buffer
>   (let ((last-command-event ?a))
>     (dotimes (i 8)
>       (self-insert-command (expt 10 i))
>       (benchmark 1 '(looking-back "(" (1- (point)))))))
> Elapsed time: 0.000031s
> Elapsed time: 0.000027s [5 times]
> Elapsed time: 0.000041s
> Elapsed time: 0.000045s
>
>> I could always do (eq (char-before) ?() I suppose.
>
> That's probably better. But wait! This time you *should* have a backslash: ?\(

Thatʼs a matter of style, no? ?( works equally well, but emacs
convention appears to be ?\(

>> The regexp produced by (sentence-end) looks like itʼs fairly well
>> anchored. Besides, Iʼm not searching for an end-of-sentence, Iʼm
>> asking "Am I at end-of-sentence".
>
> Which is exactly why you should put a limit.

I donʼt understand that conclusion. If I have

some words.  some other words
             ^

with point at '^', (looking-back (sentence-end)) will match. If point is
not at an end of sentence, looking-back won't go backwards through the
buffer attempting to find one.

Although I could limit it to (point-at-bol 0) just to be extra super
sure, but my benchmarking shows no appreciable difference.

Robert

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

[Noam Postavsky]

On 6 June 2018 at 09:51, Robert Pluim <rpluim@gmail.com> wrote:

>>> I could always do (eq (char-before) ?() I suppose.
>>
>> That's probably better. But wait! This time you *should* have a backslash: ?\(
>
> Thatʼs a matter of style, no? ?( works equally well, but emacs
> convention appears to be ?\(

Mostly yes, but see also Bug#20852.

>>> The regexp produced by (sentence-end) looks like itʼs fairly well
>>> anchored. Besides, Iʼm not searching for an end-of-sentence, Iʼm
>>> asking "Am I at end-of-sentence".
>>
>> Which is exactly why you should put a limit.
>
> I donʼt understand that conclusion. If I have
>
> some words.  some other words
>              ^
>
> with point at '^', (looking-back (sentence-end)) will match. If point is
> not at an end of sentence, looking-back won't go backwards through the
> buffer attempting to find one.

Even worse, it will go backwards through the buffer attempting to find
a sentence that ends at point.

(with-temp-buffer
  (dotimes (i 7)
    (dotimes (_ (expt 10 i))
      (insert "Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua.  Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip ex ea commodo consequat.  Duis
aute irure dolor in reprehenderit in voluptate velit esse cillum
dolore eu fugiat nulla pariatur.  Excepteur sint occaecat
cupidatat non proident, sunt in culpa qui officia deserunt mollit
anim id est laborum."))
    (insert "  Sentence doesn't end here")
    (benchmark 1 '(looking-back (sentence-end)))))
Elapsed time: 0.000000s [3 times]
Elapsed time: 0.023000s
Elapsed time: 0.101000s
Elapsed time: 0.902000s
Elapsed time: 8.872000s

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

[Robert Pluim]

Noam Postavsky <npostavs@gmail.com> writes:

> On 6 June 2018 at 09:51, Robert Pluim <rpluim@gmail.com> wrote:
>
>>>> I could always do (eq (char-before) ?() I suppose.
>>>
>>> That's probably better. But wait! This time you *should* have a backslash: ?\(
>>
>> Thatʼs a matter of style, no? ?( works equally well, but emacs
>> convention appears to be ?\(
>
> Mostly yes, but see also Bug#20852.
>

I see the documentation changed from 'should' to 'must' as a result of
that bug. ?\( it is.

> Even worse, it will go backwards through the buffer attempting to find
> a sentence that ends at point.
>
> (with-temp-buffer
>   (dotimes (i 7)
>     (dotimes (_ (expt 10 i))
>       (insert "Lorem ipsum dolor sit amet, consectetur adipiscing
> elit, sed do eiusmod tempor incididunt ut labore et dolore magna
> aliqua.  Ut enim ad minim veniam, quis nostrud exercitation
> ullamco laboris nisi ut aliquip ex ea commodo consequat.  Duis
> aute irure dolor in reprehenderit in voluptate velit esse cillum
> dolore eu fugiat nulla pariatur.  Excepteur sint occaecat
> cupidatat non proident, sunt in culpa qui officia deserunt mollit
> anim id est laborum."))
>     (insert "  Sentence doesn't end here")
>     (benchmark 1 '(looking-back (sentence-end)))))
> Elapsed time: 0.000000s [3 times]
> Elapsed time: 0.023000s
> Elapsed time: 0.101000s
> Elapsed time: 0.902000s
> Elapsed time: 8.872000s

OK. Looks like my mental model of 'looking-back' was wrong. Iʼll add
the limit.

Robert