* bug#23865: 24.5; doc string of `tramp-remote-path'
@ 2016-06-28 20:30 Drew Adams
2016-06-28 20:36 ` Jonathan Kotta
0 siblings, 1 reply; 12+ messages in thread
From: Drew Adams @ 2016-06-28 20:30 UTC (permalink / raw)
To: 23865
(Note: I don't use this. I just tried to understand it while looking at
it for someone else. Perhaps if I used it things would be clearer.)
The doc string says that the value is a list of directories. But the
default value is a list of directories, but including the symbol
`tramp-default-remote-path' as the head of the list. That symbol
doesn't look like a directory. How is a user to understand this?
In GNU Emacs 24.5.1 (i686-pc-mingw32)
of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
`configure --prefix=/c/usr --host=i686-pc-mingw32'
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#23865: 24.5; doc string of `tramp-remote-path'
2016-06-28 20:30 bug#23865: 24.5; doc string of `tramp-remote-path' Drew Adams
@ 2016-06-28 20:36 ` Jonathan Kotta
2016-06-28 20:57 ` Drew Adams
0 siblings, 1 reply; 12+ messages in thread
From: Jonathan Kotta @ 2016-06-28 20:36 UTC (permalink / raw)
Cc: 23865
[-- Attachment #1: Type: text/plain, Size: 1062 bytes --]
There is another special symbol `tramp-own-remote-path` that can be added
to `tramp-remote-path`. Both of the special symbols show up in customize.
The docstring should definitely mention both.
On Tue, Jun 28, 2016 at 3:30 PM, Drew Adams <drew.adams@oracle.com> wrote:
> (Note: I don't use this. I just tried to understand it while looking at
> it for someone else. Perhaps if I used it things would be clearer.)
>
> The doc string says that the value is a list of directories. But the
> default value is a list of directories, but including the symbol
> `tramp-default-remote-path' as the head of the list. That symbol
> doesn't look like a directory. How is a user to understand this?
>
>
> In GNU Emacs 24.5.1 (i686-pc-mingw32)
> of 2015-04-11 on LEG570
> Windowing system distributor `Microsoft Corp.', version 6.1.7601
> Configured using:
> `configure --prefix=/c/usr --host=i686-pc-mingw32'
>
>
>
>
--
Thanks,
Jonathan Kotta
Hofstadter's Law:
It always takes longer than you expect, even
when you take into account Hofstadter's Law.
[-- Attachment #2: Type: text/html, Size: 1595 bytes --]
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#23865: 24.5; doc string of `tramp-remote-path'
2016-06-28 20:36 ` Jonathan Kotta
@ 2016-06-28 20:57 ` Drew Adams
2016-06-29 7:41 ` Michael Albinus
0 siblings, 1 reply; 12+ messages in thread
From: Drew Adams @ 2016-06-28 20:57 UTC (permalink / raw)
To: Jonathan Kotta; +Cc: 23865
> There is another special symbol `tramp-own-remote-path` that can
> be added to `tramp-remote-path`. Both of the special symbols
> show up in customize. The docstring should definitely mention both.
Right. Forgot to mention that.
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#23865: 24.5; doc string of `tramp-remote-path'
2016-06-28 20:57 ` Drew Adams
@ 2016-06-29 7:41 ` Michael Albinus
2016-06-29 13:53 ` Drew Adams
2016-06-29 15:21 ` Eli Zaretskii
0 siblings, 2 replies; 12+ messages in thread
From: Michael Albinus @ 2016-06-29 7:41 UTC (permalink / raw)
To: Drew Adams; +Cc: 23865, Jonathan Kotta
Drew Adams <drew.adams@oracle.com> writes:
>> There is another special symbol `tramp-own-remote-path` that can
>> be added to `tramp-remote-path`. Both of the special symbols
>> show up in customize. The docstring should definitely mention both.
>
> Right. Forgot to mention that.
The docstring of `tramp-remote-path' is oriented to the custom
interface. In custom, `tramp-default-remote-path' and
`tramp-own-remote-path' are not offered under their symbol name, but as
"Default Directories" and "Private Directories". These entries are
documented.
Best regards, Michael.
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#23865: 24.5; doc string of `tramp-remote-path'
2016-06-29 7:41 ` Michael Albinus
@ 2016-06-29 13:53 ` Drew Adams
2016-06-29 14:58 ` Michael Albinus
2016-06-29 15:21 ` Eli Zaretskii
1 sibling, 1 reply; 12+ messages in thread
From: Drew Adams @ 2016-06-29 13:53 UTC (permalink / raw)
To: Michael Albinus; +Cc: 23865, Jonathan Kotta
> The docstring of `tramp-remote-path' is oriented to the custom
> interface. In custom, `tramp-default-remote-path' and
> `tramp-own-remote-path' are not offered under their symbol name, but as
> "Default Directories" and "Private Directories". These entries are
> documented.
Right. That's the (doc) bug. It is fine to be "oriented" to
interactive use of Customize. It is a failing to incorrectly
describe the variable value. That hurts, rather than helps
users. The doc string can do both: describe things in terms
of the UI and also correctly describe the possible values.
What it should not do is what it does now: give the impression
that the list values are all strings (and not say anything
about those two symbols that have special meaning for the
variable value).
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#23865: 24.5; doc string of `tramp-remote-path'
2016-06-29 13:53 ` Drew Adams
@ 2016-06-29 14:58 ` Michael Albinus
2016-06-29 15:09 ` Drew Adams
0 siblings, 1 reply; 12+ messages in thread
From: Michael Albinus @ 2016-06-29 14:58 UTC (permalink / raw)
To: Drew Adams; +Cc: 23865, Jonathan Kotta
Drew Adams <drew.adams@oracle.com> writes:
> Right. That's the (doc) bug. It is fine to be "oriented" to
> interactive use of Customize. It is a failing to incorrectly
> describe the variable value. That hurts, rather than helps
> users. The doc string can do both: describe things in terms
> of the UI and also correctly describe the possible values.
>
> What it should not do is what it does now: give the impression
> that the list values are all strings (and not say anything
> about those two symbols that have special meaning for the
> variable value).
I was aware of this problem when writing the docstring. Unfortunately,
there's no possibility to let it look different in `describe-variable'
and the custom UI.
Would the following patch fit the bill?
--8<---------------cut here---------------start------------->8---
*** /home/albinus/src/emacs/lisp/net/tramp-sh.el.~cfb3c61f1ffec9a6322407fdd228d5cc31c31ed0~ 2016-06-29 16:55:53.466570072 +0200
--- /home/albinus/src/emacs/lisp/net/tramp-sh.el 2016-06-29 16:55:36.918161072 +0200
***************
*** 527,541 ****
You can use `~' in this list, but when searching for a shell which groks
tilde expansion, all directory names starting with `~' will be ignored.
! `Default Directories' represent the list of directories given by
! the command \"getconf PATH\". It is recommended to use this
! entry on top of this list, because these are the default
directories for POSIX compatible commands. On remote hosts which
do not offer the getconf command (like cygwin), the value
\"/bin:/usr/bin\" is used instead of.
! `Private Directories' are the settings of the $PATH environment,
! as given in your `~/.profile'."
:group 'tramp
:type '(repeat (choice
(const :tag "Default Directories" tramp-default-remote-path)
--- 527,543 ----
You can use `~' in this list, but when searching for a shell which groks
tilde expansion, all directory names starting with `~' will be ignored.
! `Default Directories', indicated internally by
! `tramp-default-remote-path', represent the list of directories
! given by the command \"getconf PATH\". It is recommended to use
! this entry on top of this list, because these are the default
directories for POSIX compatible commands. On remote hosts which
do not offer the getconf command (like cygwin), the value
\"/bin:/usr/bin\" is used instead of.
! `Private Directories', indicated internally by
! `tramp-own-remote-path', are the settings of the $PATH
! environment, as given in your `~/.profile'."
:group 'tramp
:type '(repeat (choice
(const :tag "Default Directories" tramp-default-remote-path)
--8<---------------cut here---------------end--------------->8---
Best regards, Michael.
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#23865: 24.5; doc string of `tramp-remote-path'
2016-06-29 14:58 ` Michael Albinus
@ 2016-06-29 15:09 ` Drew Adams
0 siblings, 0 replies; 12+ messages in thread
From: Drew Adams @ 2016-06-29 15:09 UTC (permalink / raw)
To: Michael Albinus; +Cc: 23865, Jonathan Kotta
> Would the following patch fit the bill?
Yes, I think that's an improvement. Thx.
You might want to refer to the "head", "car", or "first element" of a
list instead of the "top" of a list. I'm not sure people will understand
"top" here. (But use your own judgment.)
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#23865: 24.5; doc string of `tramp-remote-path'
2016-06-29 7:41 ` Michael Albinus
2016-06-29 13:53 ` Drew Adams
@ 2016-06-29 15:21 ` Eli Zaretskii
2016-06-29 16:11 ` Michael Albinus
2016-06-30 11:17 ` Jiege Chen
1 sibling, 2 replies; 12+ messages in thread
From: Eli Zaretskii @ 2016-06-29 15:21 UTC (permalink / raw)
To: Michael Albinus; +Cc: 23865, jpkotta
> From: Michael Albinus <michael.albinus@gmx.de>
> Date: Wed, 29 Jun 2016 09:41:30 +0200
> Cc: 23865@debbugs.gnu.org, Jonathan Kotta <jpkotta@gmail.com>
>
> The docstring of `tramp-remote-path' is oriented to the custom
> interface. In custom, `tramp-default-remote-path' and
> `tramp-own-remote-path' are not offered under their symbol name, but as
> "Default Directories" and "Private Directories". These entries are
> documented.
Michael, are you okay with the following change of the doc string?
diff --git a/lisp/net/tramp-sh.el b/lisp/net/tramp-sh.el
index bff6ec3..6954fd6 100644
--- a/lisp/net/tramp-sh.el
+++ b/lisp/net/tramp-sh.el
@@ -506,10 +506,12 @@ tramp-remote-path
entry on top of this list, because these are the default
directories for POSIX compatible commands. On remote hosts which
do not offer the getconf command (like cygwin), the value
-\"/bin:/usr/bin\" is used instead of.
+\"/bin:/usr/bin\" is used instead of. This entry is represented in
+the list by the special value `tramp-default-remote-path'.
`Private Directories' are the settings of the $PATH environment,
-as given in your `~/.profile'."
+as given in your `~/.profile'. This entry is represented in
+the list by the special value `tramp-own-remote-path'."
:group 'tramp
:type '(repeat (choice
(const :tag "Default Directories" tramp-default-remote-path)
^ permalink raw reply related [flat|nested] 12+ messages in thread
* bug#23865: 24.5; doc string of `tramp-remote-path'
2016-06-29 15:21 ` Eli Zaretskii
@ 2016-06-29 16:11 ` Michael Albinus
2016-06-29 16:36 ` Eli Zaretskii
2016-06-30 11:17 ` Jiege Chen
1 sibling, 1 reply; 12+ messages in thread
From: Michael Albinus @ 2016-06-29 16:11 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 23865, jpkotta
Eli Zaretskii <eliz@gnu.org> writes:
Hi Eli,
> Michael, are you okay with the following change of the doc string?
Yes, of course! Pls push.
Best regards, Michael.
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#23865: 24.5; doc string of `tramp-remote-path'
2016-06-29 16:11 ` Michael Albinus
@ 2016-06-29 16:36 ` Eli Zaretskii
0 siblings, 0 replies; 12+ messages in thread
From: Eli Zaretskii @ 2016-06-29 16:36 UTC (permalink / raw)
To: Michael Albinus; +Cc: 23865-done, jpkotta
> From: Michael Albinus <michael.albinus@gmx.de>
> Cc: drew.adams@oracle.com, 23865@debbugs.gnu.org, jpkotta@gmail.com
> Date: Wed, 29 Jun 2016 18:11:17 +0200
>
> Eli Zaretskii <eliz@gnu.org> writes:
>
> Hi Eli,
>
> > Michael, are you okay with the following change of the doc string?
>
> Yes, of course! Pls push.
Done, and closing.
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#23865: 24.5; doc string of `tramp-remote-path'
2016-06-29 15:21 ` Eli Zaretskii
2016-06-29 16:11 ` Michael Albinus
@ 2016-06-30 11:17 ` Jiege Chen
2016-06-30 13:41 ` Michael Albinus
1 sibling, 1 reply; 12+ messages in thread
From: Jiege Chen @ 2016-06-30 11:17 UTC (permalink / raw)
To: 23865
Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Michael Albinus <michael.albinus@gmx.de>
>> Date: Wed, 29 Jun 2016 09:41:30 +0200
>> Cc: 23865@debbugs.gnu.org, Jonathan Kotta <jpkotta@gmail.com>
>>
>> The docstring of `tramp-remote-path' is oriented to the custom
>> interface. In custom, `tramp-default-remote-path' and
>> `tramp-own-remote-path' are not offered under their symbol name, but as
>> "Default Directories" and "Private Directories". These entries are
>> documented.
>
> Michael, are you okay with the following change of the doc string?
>
> diff --git a/lisp/net/tramp-sh.el b/lisp/net/tramp-sh.el
> index bff6ec3..6954fd6 100644
> --- a/lisp/net/tramp-sh.el
> +++ b/lisp/net/tramp-sh.el
> @@ -506,10 +506,12 @@ tramp-remote-path
> entry on top of this list, because these are the default
> directories for POSIX compatible commands. On remote hosts which
> do not offer the getconf command (like cygwin), the value
> -\"/bin:/usr/bin\" is used instead of.
> +\"/bin:/usr/bin\" is used instead of. This entry is represented in
'instead of' should be 'instead'.
> +the list by the special value `tramp-default-remote-path'.
>
> `Private Directories' are the settings of the $PATH environment,
> -as given in your `~/.profile'."
> +as given in your `~/.profile'. This entry is represented in
> +the list by the special value `tramp-own-remote-path'."
> :group 'tramp
> :type '(repeat (choice
> (const :tag "Default Directories" tramp-default-remote-path)
>
>
>
>
>
--
Jiegec
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#23865: 24.5; doc string of `tramp-remote-path'
2016-06-30 11:17 ` Jiege Chen
@ 2016-06-30 13:41 ` Michael Albinus
0 siblings, 0 replies; 12+ messages in thread
From: Michael Albinus @ 2016-06-30 13:41 UTC (permalink / raw)
To: Jiege Chen; +Cc: 23865
Jiege Chen <jiegec@qq.com> writes:
>> -\"/bin:/usr/bin\" is used instead of.
>> +\"/bin:/usr/bin\" is used instead of. This entry is represented in
>
> 'instead of' should be 'instead'.
Thanks, I've fixed this in the emacs-25 branch. I've replaced also "top"
by "head", as suggested by Drew.
Best regards, Michael.
^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2016-06-30 13:41 UTC | newest]
Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-06-28 20:30 bug#23865: 24.5; doc string of `tramp-remote-path' Drew Adams
2016-06-28 20:36 ` Jonathan Kotta
2016-06-28 20:57 ` Drew Adams
2016-06-29 7:41 ` Michael Albinus
2016-06-29 13:53 ` Drew Adams
2016-06-29 14:58 ` Michael Albinus
2016-06-29 15:09 ` Drew Adams
2016-06-29 15:21 ` Eli Zaretskii
2016-06-29 16:11 ` Michael Albinus
2016-06-29 16:36 ` Eli Zaretskii
2016-06-30 11:17 ` Jiege Chen
2016-06-30 13:41 ` Michael Albinus
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).