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

From: Michael Albinus <[email-masked]>
Date: Sat, 15 Oct 2022 12:38:05 +0200

Jim Porter <[email-masked]> writes:

Hi Jim,

>> @var{} produces already capital letters, so you are more consistent
>> with
>> @var{name}.
>
> My intent was to make that display as all-caps in the HTML
> documentation as well. In that excerpt, 'NAME' should always be an
> environment variable, so I used the capitalization conventions that
> env vars usually use. 'name', on the other hand, could be a Lisp
> variable or an env var.

You use @var{} by side-effect6, which is always problematic. For
example, RMS is looking for a replacement of the texinfo syntax for
documentation, org syntax is a candidate. But whatever is chosen, an
automatic conversion from .texinfo to .<whatever> could be problematic
then.

Use what is offered by texinfo. Say for example

--8<---------------cut here---------------start------------->8---
the @env{PATH} environment variable
--8<---------------cut here---------------end--------------->8---

And in sample code, do not apply further formatting, but say it as you
mean it

--8<---------------cut here---------------start------------->8---
@samp{setq name value}
@samp{export NAME=value}
--8<---------------cut here---------------end--------------->8---

> I adjusted these docs a bit since they seemed unclear to me on a
> second reading (see attached), but kept the all-caps NAME for env
> vars. If you still think that's wrong, I'll change it to lower-case
> before merging.

Otherwise, it LGTM. Somewhere there is only one space after a dot
(should be two spaces), but I didn't marked this during review, and now
I'm too lazy to look for :-)

I'd say just push it to the repo, and if there's something left to do we
can stiil do it.

Best regards, Michael.