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