bug#57556: 28.1; Eshell not finding executables in PATH when tramp-integration loaded

[Eli Zaretskii]

> Cc: 57556@debbugs.gnu.org
> Date: Wed, 12 Oct 2022 21:11:47 -0700
> From: Jim Porter <jporterbugs@gmail.com>
> 
> On 10/9/2022 11:01 AM, Michael Albinus wrote:
> > Jim Porter <jporterbugs@gmail.com> writes:
> > 
> >> I attached an updated version of my connection-local.el that tries to
> >> pull out the additions you made into some helpers. What do you think?
> > 
> > I gave it a short reading, and in general it looks OK (comments
> > below). Do you want to provide a patch for files-x.el with this?
> 
> Thanks for taking a look. I've added a separate patch (0002 in this 
> series) for adding these functions (with some improvements over the 
> little test script we worked on) to files-x.el. (Patch 0001 just fixes 
> an issue in the docs/tests where the :application had an extra quote.)
> 
> If you think it would be easier to track, I could file a new bug and put 
> patches 0001 and 0002 in there, then come back to this bug once that's 
> merged. Either way is fine by me.
> 
> The other patches in this series are mostly-unchanged from before, 
> except for 0006, which now uses the new 'setq-connection-local' macro.
> 
> > This patch shall also extent the "Connection Local Variables" section of
> > the Elisp manual. This section is already quite
> > long (~150 lines), and speaks almost about static setting of
> > connection-local variables. You bring dynamic settings here, maybe a
> > subsection would help to structure. And feel free to restructure the
> > other, long text if you believe it would help.
> 
> I added all this to the manual (with an example), and divided the 
> Connection Local Variables section into two subsections: one for how to 
> initialize profiles and set criteria for them, and another for applying 
> the variables. I put the 'setq-connection-local' docs in the second 
> section, since it's closely related to 'with-connection-local-variables'.

Thanks.  Some general documentation-related comments below.

> +@node Connection Local Profiles
> +@subsection Connection Local Profiles

It is generally a good idea to have a @cindex entry for the main topic
of a section/subsection.  Usually, the @cindex entry is just the node
or section name, with all of its words down-cases.  For example, here
I'd use

  @cindex connect local profiles

And similarly for the other subsection you added.

My other general comment is to never miss an opportunity of adding a
cross-reference when you reference a term or a symbol described
elsewhere in the documentation.  Never assume the reader already knows
what all the stuff you reference is about.  For example:

> +You can set variables in a few different ways.  To set a Lisp
> +variable, you can use the command @samp{setq @var{name} @var{value}},
> +which works much like its Lisp counterpart.

This will benefit from a cross-reference to where 'setq' is described
in the ELisp reference manual.

Please review the documentation changes for more cross-reference
opportunities like this one.