bug#23865: 24.5; doc string of `tramp-remote-path'

bug#23865: 24.5; doc string of `tramp-remote-path'

[Drew Adams]

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

bug#23865: 24.5; doc string of `tramp-remote-path'

[Jonathan Kotta]

[-- 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 --]

bug#23865: 24.5; doc string of `tramp-remote-path'

[Drew Adams]

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

bug#23865: 24.5; doc string of `tramp-remote-path'

[Michael Albinus]

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.

bug#23865: 24.5; doc string of `tramp-remote-path'

[Drew Adams]

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

bug#23865: 24.5; doc string of `tramp-remote-path'

[Michael Albinus]

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.

bug#23865: 24.5; doc string of `tramp-remote-path'

[Drew Adams]

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

bug#23865: 24.5; doc string of `tramp-remote-path'

[Eli Zaretskii]

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

bug#23865: 24.5; doc string of `tramp-remote-path'

[Michael Albinus]

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.

bug#23865: 24.5; doc string of `tramp-remote-path'

[Eli Zaretskii]

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

bug#23865: 24.5; doc string of `tramp-remote-path'

[Jiege Chen]

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

bug#23865: 24.5; doc string of `tramp-remote-path'

[Michael Albinus]

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.