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.