unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#10319: 24.0.92; doc string of `file-remote-p'
@ 2011-12-18  2:17 Drew Adams
  2011-12-18  8:33 ` Michael Albinus
  0 siblings, 1 reply; 16+ messages in thread
From: Drew Adams @ 2011-12-18  2:17 UTC (permalink / raw)
  To: 10319

This part means nothing, and is misleading:
 
"`file-remote-p' will never open a connection on its own."
 
What could "on its own" possibly mean here.  This function can invoke a
handler, which can open a connection.  So this function can open a
connection.  We don't distinguish what the implementation of a function
does from what the function does.  If the code in the body of
`file-remote-p' ends up opening a connection, then `file-remote-p' opens
a connection.
 
You are probably trying to say something useful here (what?), but so far
you have not said anything useful by this sentence.  And it misleads.

In GNU Emacs 24.0.92.1 (i386-mingw-nt5.1.2600) of 2011-12-06 on MARVIN
 Windowing system distributor `Microsoft Corp.', version 5.1.2600
 configured using `configure --with-gcc (4.6) --no-opt --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-2.10.1/include --ldflags
 -LD:/devel/emacs/libs/gnutls-2.10.1/lib'







^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-18  2:17 bug#10319: 24.0.92; doc string of `file-remote-p' Drew Adams
@ 2011-12-18  8:33 ` Michael Albinus
  2011-12-18 15:02   ` Drew Adams
  0 siblings, 1 reply; 16+ messages in thread
From: Michael Albinus @ 2011-12-18  8:33 UTC (permalink / raw)
  To: Drew Adams; +Cc: 10319

"Drew Adams" <drew.adams@oracle.com> writes:

> This part means nothing, and is misleading:
>  
> "`file-remote-p' will never open a connection on its own."
>  
> What could "on its own" possibly mean here.  This function can invoke a
> handler, which can open a connection.  So this function can open a
> connection.  We don't distinguish what the implementation of a function
> does from what the function does.  If the code in the body of
> `file-remote-p' ends up opening a connection, then `file-remote-p' opens
> a connection.

the intention is exactly as said: any implementation of `file-remote-p'
shall not open a new remote connection, if it is not established yet.

> You are probably trying to say something useful here (what?), but so far
> you have not said anything useful by this sentence.  And it misleads.

The wording comes from me. If there are better ways to say this, please
propose. I'm not a native English speaker.

Best regards, Michael.





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-18  8:33 ` Michael Albinus
@ 2011-12-18 15:02   ` Drew Adams
  2011-12-19  8:40     ` Michael Albinus
  0 siblings, 1 reply; 16+ messages in thread
From: Drew Adams @ 2011-12-18 15:02 UTC (permalink / raw)
  To: 'Michael Albinus'; +Cc: 10319

> > "`file-remote-p' will never open a connection on its own."
> >  
> > What could "on its own" possibly mean here.  This function 
> > can invoke a handler, which can open a connection.  So
> > this function can open a connection.  We don't distinguish
> > what the implementation of a function does from what the
> > function does.  If the code in the body of `file-remote-p'
> > ends up opening a connection, then `file-remote-p' opens
> > a connection.
> 
> the intention is exactly as said: any implementation of 
> `file-remote-p' shall not open a new remote connection,
> if it is not established yet.

I didn't understand that from the phrase used.  I thought
that it somehow was referring to the fact that the handler
might open a new connection, and that that wouldn't be
`file-remote-p' doing so "on its own".

But if a given connection has already been established,
and if `file-remote-p' then (re-)opens it, it is not a
"new" connection.  Or maybe I'm missing something else
(maybe a difference between open and establish?).  So
even your better explanation here leaves me a little
confused.

Do you just want to say that `file-remote-p' never opens
a new connection (i.e., a connection that is not already
established/open)?

If so, let's just say that: It never opens a new remote
connection.  It can only reuse a connection that is
already open.

If not, then I'm afraid I'm still confused about the
behavior (I'm no expert on remote connection) and what we
are trying to say about it.

> > You are probably trying to say something useful here 
> > (what?), but so far you have not said anything useful
> > by this sentence.  And it misleads.
> 
> The wording comes from me. If there are better ways to say 
> this, please propose. I'm not a native English speaker.

I understand, and will try to propose something, once I
understand what we're really trying to say.  Can the handler
establish a _new_ connection?  If so, then `file-remote-p'
can do so. If not, then can't we just say that
`file-remote-p' never establishes (opens) a new connection?

Let me know what the point is - what we're trying to
communicate about opening connections, and once I understand
that I can make a suggestion wrt wording.  Thx.






^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-18 15:02   ` Drew Adams
@ 2011-12-19  8:40     ` Michael Albinus
  2011-12-19 16:10       ` Drew Adams
  0 siblings, 1 reply; 16+ messages in thread
From: Michael Albinus @ 2011-12-19  8:40 UTC (permalink / raw)
  To: Drew Adams; +Cc: 10319

"Drew Adams" <drew.adams@oracle.com> writes:

> Do you just want to say that `file-remote-p' never opens
> a new connection (i.e., a connection that is not already
> established/open)?

Yes.

> If so, let's just say that: It never opens a new remote
> connection.  It can only reuse a connection that is
> already open.

Sounds OK to me.

> I understand, and will try to propose something, once I
> understand what we're really trying to say.  Can the handler
> establish a _new_ connection?  If so, then `file-remote-p'
> can do so. If not, then can't we just say that
> `file-remote-p' never establishes (opens) a new connection?

It is a promise to libraries using `file-remote-p'. It is guaranteed
that the function call is cheap, and that it could be used here and
there w/o remarkable overhead.

It is also an implementation hint. Any handler that provides an own
implementation of `file-remote-p' shall behave like this.
`tramp-handle-file-remote-p' and `ange-ftp-file-remote-p' do so.

As a consequence, the result might differ whether a connection is
already open, or not. If the connection is not established yet, we get

(file-remote-p "/ssh::" 'localname) => ""

If there is an established connection, we see

(file-remote-p "/ssh::" 'localname) => "/home/albinus"

Best regards, Michael.





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-19  8:40     ` Michael Albinus
@ 2011-12-19 16:10       ` Drew Adams
  2011-12-19 18:26         ` Michael Albinus
  0 siblings, 1 reply; 16+ messages in thread
From: Drew Adams @ 2011-12-19 16:10 UTC (permalink / raw)
  To: 'Michael Albinus'; +Cc: 10319

> > Do you just want to say that `file-remote-p' never opens
> > a new connection (i.e., a connection that is not already
> > established/open)?
> 
> Yes.
> 
> > If so, let's just say that: It never opens a new remote
> > connection.  It can only reuse a connection that is
> > already open.
> 
> Sounds OK to me.

Let's do that then.  IMO, that will avoid some misunderstanding.

> > Can the handler establish a _new_ connection?  If so, then
> > `file-remote-p' can do so. If not, then can't we just say
> > that `file-remote-p' never establishes (opens) a new
> > connection?
> 
> It is a promise to libraries using `file-remote-p'. It is guaranteed
> that the function call is cheap, and that it could be used here and
> there w/o remarkable overhead.

That is covered by what is said above: it never opens  new connection.

> It is also an implementation hint. Any handler that provides an own
> implementation of `file-remote-p' shall behave like this.
> `tramp-handle-file-remote-p' and `ange-ftp-file-remote-p' do so.

I doubt that trying to hint that in the doc string will help more than hurt user
understanding.  IMO we would either need to spell that out clearly or put it in
comments in the code.

I think the latter is preferable.  The doc string should be aimed mainly at
users of the function, not at implementors of substitute definitions of it.  But
all of that kind of thing can be stated clearly in the source file for those to
whom it is useful.

> As a consequence, the result might differ whether a connection is
> already open, or not. If the connection is not established yet, we get
> (file-remote-p "/ssh::" 'localname) => ""
> If there is an established connection, we see
> (file-remote-p "/ssh::" 'localname) => "/home/albinus"

That might be worth pointing out in the doc string.  It might be useful to users
of the function.  Perhaps you could just add text like this:

  "The return value can differ depending on whether there
   is an existing connection."

Do we want to say more than that?  Is there some rule about this?  E.g., if no
existing connection is the return value _always_ ""?  If no rule, then just
adding that sentence (or similar) should be enough.

Thx - Drew






^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-19 16:10       ` Drew Adams
@ 2011-12-19 18:26         ` Michael Albinus
  2011-12-19 19:44           ` Drew Adams
  0 siblings, 1 reply; 16+ messages in thread
From: Michael Albinus @ 2011-12-19 18:26 UTC (permalink / raw)
  To: Drew Adams; +Cc: 10319

"Drew Adams" <drew.adams@oracle.com> writes:

>> > If so, let's just say that: It never opens a new remote
>> > connection.  It can only reuse a connection that is
>> > already open.
>>
>> Sounds OK to me.
>
> Let's do that then.  IMO, that will avoid some misunderstanding.
>
>> It is also an implementation hint. Any handler that provides an own
>> implementation of `file-remote-p' shall behave like this.
>> `tramp-handle-file-remote-p' and `ange-ftp-file-remote-p' do so.
>
> I doubt that trying to hint that in the doc string will help more than
> hurt user understanding.  IMO we would either need to spell that out
> clearly or put it in comments in the code.

I didn't intend to include it as such. It is an implicit implementation
hint.

> I think the latter is preferable.  The doc string should be aimed
> mainly at users of the function, not at implementors of substitute
> definitions of it.  But all of that kind of thing can be stated
> clearly in the source file for those to whom it is useful.

OK.

>> As a consequence, the result might differ whether a connection is
>> already open, or not. If the connection is not established yet, we get
>> (file-remote-p "/ssh::" 'localname) => ""
>> If there is an established connection, we see
>> (file-remote-p "/ssh::" 'localname) => "/home/albinus"
>
> That might be worth pointing out in the doc string.  It might be
> useful to users of the function.  Perhaps you could just add text like
> this:
>
>   "The return value can differ depending on whether there
>    is an existing connection."

We shall mention that the return value is still a string. And the
difference happens only for localname parts.

> Do we want to say more than that?  Is there some rule about this?
> E.g., if no existing connection is the return value _always_ ""?  If
> no rule, then just adding that sentence (or similar) should be enough.

I wouldn't give a rule. There are other cases, like (file-remote-p
"/ssh::" 'localname), which returns "~" when there is no connection, and
"/home/albinus" otherwise.

Combining your proposals, the docstring could be

  "Test whether FILE specifies a location on a remote system.  Returns
   nil or a string identifying the remote connection (ideally a prefix
   of FILE).  For example, the remote identification for filename
   "/user@host:/foo" could be "/user@host:".  A file is considered
   "remote" if accessing it is likely to be slower or less reliable than
   accessing local files.  Furthermore, relative file names do not work
   across remote connections.

   IDENTIFICATION specifies which part of the identification shall be
   returned as string.  IDENTIFICATION can be the symbol `method',
   `user', `host' or `localname'; any other value is handled like nil
   and means to return the complete identification string.  The string
   returned for IDENTIFICATION `localname' can differ depending on
   whether there is an existing connection."

   If CONNECTED is non-nil, the function returns an identification only
   if FILE is located on a remote system, and a connection is
   established to that remote system.

  `file-remote-p' never opens a new remote connection.  It can only
   reuse a connection that is already open."

> Thx - Drew

Best regards, Michael.





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-19 18:26         ` Michael Albinus
@ 2011-12-19 19:44           ` Drew Adams
  2011-12-19 21:18             ` Michael Albinus
  0 siblings, 1 reply; 16+ messages in thread
From: Drew Adams @ 2011-12-19 19:44 UTC (permalink / raw)
  To: 'Michael Albinus'; +Cc: 10319

> > That might be worth pointing out in the doc string.  It might be
> > useful to users of the function.  Perhaps you could just add
> > text like this:
> >   "The return value can differ depending on whether there
> >    is an existing connection."
> 
> We shall mention that the return value is still a string. And the
> difference happens only for localname parts.

Good.

> > Do we want to say more than that?  Is there some rule about this?
> > E.g., if no existing connection is the return value _always_ ""?  If
> > no rule, then just adding that sentence (or similar) should 
> > be enough.
> 
> I wouldn't give a rule. There are other cases, like (file-remote-p
> "/ssh::" 'localname), which returns "~" when there is no 
> connection, and "/home/albinus" otherwise.
> 
> Combining your proposals, the docstring could be
> 
>   "Test whether FILE specifies a location on a remote system.  Returns
>    nil or a string

Returns -> Return.  I think that's the convention, but I'm no expert.

>    identifying the remote connection (ideally a prefix
>    of FILE).  For example, the remote identification for filename
>    "/user@host:/foo" could be "/user@host:".

>    A file is considered "remote" if accessing it is likely to
>    be slower or less reliable than accessing local files.

I'd suggest moving that just after the first sentence ("Test...").

>    Furthermore, relative file names do not work across remote
>    connections.

Why "Furthermore"?  This seems unrelated to anything preceding it.  If I'm
right, I'd suggest just dropping "Furthermore".  But in fact I don't know what
this sentence means.  What do you mean here by "do not work"?

>    IDENTIFICATION specifies which part of the identification shall be
>    returned as string.

shall be returned as string -> to return

>    IDENTIFICATION can be the symbol `method',
>    `user', `host' or `localname'; any other value is handled like nil
>    and means to return the complete identification string.  

No need for "string" here.

>    The string
>    returned for IDENTIFICATION `localname' can differ depending on
>    whether there is an existing connection."

Good.

>    If CONNECTED is non-nil, the function returns an

the function returns -> return
 
>    identification only if FILE is located on a remote system,

No comma here.

>    and a connection is established to that remote system.

>   `file-remote-p' never opens a new remote connection.  It can only
>    reuse a connection that is already open."

I'd suggest putting that last part just after "A file is considered remote
if..."

Something like this (but see my question about relative file names not working):

 Test whether FILE specifies a location on a remote system.
 A file is considered remote if accessing it is likely to
 be slower or less reliable than accessing local files.

 `file-remote-p' never opens a new remote connection.  It can
 only reuse a connection that is already open. Relative file
 names do not work across remote connections (????).

 Return nil or a string identifying the remote connection
 (ideally a prefix of FILE).  For example, the remote
 identification for filename "/user@host:/foo" could be
 "/user@host:".  

 IDENTIFICATION specifies which part of the identification to
 return.  IDENTIFICATION can be the symbol `method',
 `user', `host', or `localname'.  Any other value is handled
 like nil and means to return the complete identification.
 The string returned for IDENTIFICATION `localname' can differ
 depending on whether there is an existing connection."

 If CONNECTED is non-nil, return an identification only
 if FILE is located on a remote system and a connection is
 established to that remote system.

We should also perhaps say what "the complete identification" is/means.  IOW,
when IDENTIFICATION is nil, what can we say about the return value?

HTH - Drew






^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-19 19:44           ` Drew Adams
@ 2011-12-19 21:18             ` Michael Albinus
  2011-12-19 21:29               ` Drew Adams
  0 siblings, 1 reply; 16+ messages in thread
From: Michael Albinus @ 2011-12-19 21:18 UTC (permalink / raw)
  To: Drew Adams; +Cc: 10319

"Drew Adams" <drew.adams@oracle.com> writes:

>>    A file is considered "remote" if accessing it is likely to
>>    be slower or less reliable than accessing local files.
>
> I'd suggest moving that just after the first sentence ("Test...").
>
>>    Furthermore, relative file names do not work across remote
>>    connections.
>
> Why "Furthermore"?  This seems unrelated to anything preceding it.  If I'm
> right, I'd suggest just dropping "Furthermore".  But in fact I don't know what
> this sentence means.  What do you mean here by "do not work"?

Both sentences from the docstring are not from me. For the first
sentence, I even disagree with Stefan (but we should NOT discuss this
here).

The second sentence means that a relative filename like "/sudo::../../.."
does not make sense, because it cannot expand out of the "/sudo::"
jail.

> Something like this (but see my question about relative file names not working):
>
>  Test whether FILE specifies a location on a remote system.
>  A file is considered remote if accessing it is likely to
>  be slower or less reliable than accessing local files.
>
>  `file-remote-p' never opens a new remote connection.  It can
>  only reuse a connection that is already open. Relative file
>  names do not work across remote connections (????).
>
>  Return nil or a string identifying the remote connection
>  (ideally a prefix of FILE).  For example, the remote
>  identification for filename "/user@host:/foo" could be
>  "/user@host:".  
>
>  IDENTIFICATION specifies which part of the identification to
>  return.  IDENTIFICATION can be the symbol `method',
>  `user', `host', or `localname'.  Any other value is handled
>  like nil and means to return the complete identification.
>  The string returned for IDENTIFICATION `localname' can differ
>  depending on whether there is an existing connection."
>
>  If CONNECTED is non-nil, return an identification only
>  if FILE is located on a remote system and a connection is
>  established to that remote system.

Sounds OK to me. From my point of view you could submit the changed docstring.

> We should also perhaps say what "the complete identification" is/means.  IOW,
> when IDENTIFICATION is nil, what can we say about the return value?

In that case, the returned string could make a local file name remote. We
could always offer to apply

   (concat (file-remote-p "whatever") "local-file-name")

given that `concat' accepts nil as argument.

> HTH - Drew

Best regards, Michael.





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-19 21:18             ` Michael Albinus
@ 2011-12-19 21:29               ` Drew Adams
  2011-12-20  9:15                 ` Michael Albinus
  0 siblings, 1 reply; 16+ messages in thread
From: Drew Adams @ 2011-12-19 21:29 UTC (permalink / raw)
  To: 'Michael Albinus'; +Cc: 10319

> The second sentence means that a relative filename like 
> "/sudo::../../.." does not make sense, because it cannot
> expand out of the "/sudo::" jail.

So what are we trying to tell _users_ here?
Is this what we are really trying to say?

 FILE must be an absolute file name.

If so, what should we say happens if you nevertheless pass a relative file name?
Return value is unspecified (could be nil or non-nil)?  An error is raised?
What should we tell users is the behavior?

> > Something like this (but see my question about relative 
> > file names not working):
> >
> >  Test whether FILE specifies a location on a remote system.
> >  A file is considered remote if accessing it is likely to
> >  be slower or less reliable than accessing local files.
> >
> >  `file-remote-p' never opens a new remote connection.  It can
> >  only reuse a connection that is already open. Relative file
> >  names do not work across remote connections (????).
> >
> >  Return nil or a string identifying the remote connection
> >  (ideally a prefix of FILE).  For example, the remote
> >  identification for filename "/user@host:/foo" could be
> >  "/user@host:".  
> >
> >  IDENTIFICATION specifies which part of the identification to
> >  return.  IDENTIFICATION can be the symbol `method',
> >  `user', `host', or `localname'.  Any other value is handled
> >  like nil and means to return the complete identification.
> >  The string returned for IDENTIFICATION `localname' can differ
> >  depending on whether there is an existing connection."
> >
> >  If CONNECTED is non-nil, return an identification only
> >  if FILE is located on a remote system and a connection is
> >  established to that remote system.
> 
> Sounds OK to me. From my point of view you could submit the 
> changed docstring.
>
> > We should also perhaps say what "the complete 
> > identification" is/means.  IOW, when IDENTIFICATION is nil,
> > what can we say about the return value?
> 
> In that case, the returned string could make a local file 
> name remote. We could always offer to apply
>    (concat (file-remote-p "whatever") "local-file-name")
> given that `concat' accepts nil as argument.

Sorry, I just don't understand your reply to my question (what is the complete
identification - what is returned if IDENTIFICATION is nil).  Could you rephrase
or elaborate?

Thx - Drew






^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-19 21:29               ` Drew Adams
@ 2011-12-20  9:15                 ` Michael Albinus
  2011-12-20 15:53                   ` Drew Adams
  0 siblings, 1 reply; 16+ messages in thread
From: Michael Albinus @ 2011-12-20  9:15 UTC (permalink / raw)
  To: Drew Adams; +Cc: 10319

"Drew Adams" <drew.adams@oracle.com> writes:

>> The second sentence means that a relative filename like 
>> "/sudo::../../.." does not make sense, because it cannot
>> expand out of the "/sudo::" jail.
>
> So what are we trying to tell _users_ here?
> Is this what we are really trying to say?
>
>  FILE must be an absolute file name.
>
> If so, what should we say happens if you nevertheless pass a relative
> file name?  Return value is unspecified (could be nil or non-nil)?  An
> error is raised?  What should we tell users is the behavior?

Any relative filename cannot expand to a different remote connection, or
a filename of your local filesystem. But you are right, this information
is irrelevant for the docstring of `file-remote-p'.

>> > We should also perhaps say what "the complete 
>> > identification" is/means.  IOW, when IDENTIFICATION is nil,
>> > what can we say about the return value?
>> 
>> In that case, the returned string could make a local file 
>> name remote. We could always offer to apply
>>    (concat (file-remote-p "whatever") "local-file-name")
>> given that `concat' accepts nil as argument.
>
> Sorry, I just don't understand your reply to my question (what is the
> complete identification - what is returned if IDENTIFICATION is nil).
> Could you rephrase or elaborate?

When IDENTIFICATION is nil, the returned string is everything until the
last ":" (with expanded default method, default user, default host).

(file-remote-p "/sudo::/") => "/sudo:root@localhost:"

(file-remote-p "/localhost:/") => "/scpc:localhost:"

What I have tried to explain is a common technique for creation of new
remote filenames, derived from an existing one. Let's say you have a
variable `file' containing the remote filename "/sudo::/path/to/file",
and you want to create a new remote filename for the file "/bin/sh". You
apply then (concat (file-remote-p file) "/bin/sh")

> Thx - Drew

Best reards, Michael.





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-20  9:15                 ` Michael Albinus
@ 2011-12-20 15:53                   ` Drew Adams
  2011-12-20 17:02                     ` Michael Albinus
  0 siblings, 1 reply; 16+ messages in thread
From: Drew Adams @ 2011-12-20 15:53 UTC (permalink / raw)
  To: 'Michael Albinus'; +Cc: 10319

> > So what are we trying to tell _users_ here?
> > Is this what we are really trying to say?
> >
> >  FILE must be an absolute file name.
> >
> > If so, what should we say happens if you nevertheless pass 
> > a relative file name?  Return value is unspecified (could
> > be nil or non-nil)?  An error is raised?  What should we
> > tell users is the behavior?
> 
> Any relative filename cannot expand to a different remote 
> connection, or a filename of your local filesystem. But you
> are right, this information is irrelevant for the docstring
> of `file-remote-p'.

"relative file names do not work across remote connections" should be dropped,
as it is not clear at all what we're trying to say by it.  If we want to say
something about relative file names, then it needs to be clear, whatever it is.

We really should say what happens if a relative file name is passed as arg.
It's still not clear to me, from your statement above.

Are you saying that nil is always returned for a relative file name?  If so,
let's just say that: "Return nil if FILE is a relative file name".  (No need to
say that you must or should use an absolute name.)

If that's not the case, please try again to explain, and I'll propose something
else once I understand.  (Simple tests seem to indicate that nil is returned.)

> >> > We should also perhaps say what "the complete 
> >> > identification" is/means.  IOW, when IDENTIFICATION is nil,
> >> > what can we say about the return value?
> >> 
> >> In that case, the returned string could make a local file 
> >> name remote. We could always offer to apply
> >>    (concat (file-remote-p "whatever") "local-file-name")
> >> given that `concat' accepts nil as argument.
> >
> > Sorry, I just don't understand your reply to my question 
> > (what is the complete identification - what is returned if 
> > IDENTIFICATION is nil).  Could you rephrase or elaborate?
> 
> When IDENTIFICATION is nil, the returned string is everything 
> until the last ":" (with expanded default method, default user,
> default host).
> 
> (file-remote-p "/sudo::/") => "/sudo:root@localhost:"
> (file-remote-p "/localhost:/") => "/scpc:localhost:"

Fine. Let's say that (it's not obvious, IMHO).

 When IDENTIFICATION is nil, the returned string is a complete
 remote identifier: with components method, user, and host.
 The components are those present in FILE, with defaults filled
 in for any that are missing.

> What I have tried to explain is a common technique for creation of new
> remote filenames, derived from an existing one. Let's say you have a
> variable `file' containing the remote filename "/sudo::/path/to/file",
> and you want to create a new remote filename for the file 
> "/bin/sh". You apply then (concat (file-remote-p file) "/bin/sh")

That's a useful tip about another way to _use_ the function, and also not so
obvious.  Let's say that too.

  Tip: You can use this expansion of remote identifier components
  to derive a new remote name from an existing one.  For example,
  if FILE is "/sudo::/path/to/file" then 
  (concat (file-remote-p FILE) "/bin/sh") returns a remote
  name for file "/bin/sh" that has the same remote identifier as
  FILE but expanded; a name such as "/sudo:myhost.org:/bin/sh".

HTH.






^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-20 15:53                   ` Drew Adams
@ 2011-12-20 17:02                     ` Michael Albinus
  2011-12-20 17:08                       ` Drew Adams
  0 siblings, 1 reply; 16+ messages in thread
From: Michael Albinus @ 2011-12-20 17:02 UTC (permalink / raw)
  To: Drew Adams; +Cc: 10319

"Drew Adams" <drew.adams@oracle.com> writes:

> Are you saying that nil is always returned for a relative file name?  If so,
> let's just say that: "Return nil if FILE is a relative file name".  (No need to
> say that you must or should use an absolute name.)

Thinking about (and testing a little bit) it seems like this: for
relative file names it always returns nil, indeed. This is because it
does not apply `expand-file-name'. Your proposed sentence looks OK.

>> When IDENTIFICATION is nil, the returned string is everything 
>> until the last ":" (with expanded default method, default user,
>> default host).
>> 
>> (file-remote-p "/sudo::/") => "/sudo:root@localhost:"
>> (file-remote-p "/localhost:/") => "/scpc:localhost:"
>
> Fine. Let's say that (it's not obvious, IMHO).
>
>  When IDENTIFICATION is nil, the returned string is a complete
>  remote identifier: with components method, user, and host.
>  The components are those present in FILE, with defaults filled
>  in for any that are missing.

OK.

>> What I have tried to explain is a common technique for creation of new
>> remote filenames, derived from an existing one. Let's say you have a
>> variable `file' containing the remote filename "/sudo::/path/to/file",
>> and you want to create a new remote filename for the file 
>> "/bin/sh". You apply then (concat (file-remote-p file) "/bin/sh")
>
> That's a useful tip about another way to _use_ the function, and also not so
> obvious.  Let's say that too.
>
>   Tip: You can use this expansion of remote identifier components
>   to derive a new remote name from an existing one.  For example,
>   if FILE is "/sudo::/path/to/file" then 
>   (concat (file-remote-p FILE) "/bin/sh") returns a remote
>   name for file "/bin/sh" that has the same remote identifier as
>   FILE but expanded; a name such as "/sudo:myhost.org:/bin/sh".

OK as well. Minor change: the result for the sudo case ought to be
"/sudo:root@myhost:/bin/sh". "root" is the default user name for "sudo",
and "myhost" instead of "myhost.org" because the default host name in
this case is the value of `system-name'.

> HTH.

Thanks, and best regards, Michael.





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-20 17:02                     ` Michael Albinus
@ 2011-12-20 17:08                       ` Drew Adams
  2011-12-20 17:14                         ` Michael Albinus
  0 siblings, 1 reply; 16+ messages in thread
From: Drew Adams @ 2011-12-20 17:08 UTC (permalink / raw)
  To: 'Michael Albinus'; +Cc: 10319

Sounds like you have what you need now and will update the doc string, so this
can be closed.  Thx for your help.






^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-20 17:08                       ` Drew Adams
@ 2011-12-20 17:14                         ` Michael Albinus
  2011-12-20 17:33                           ` Drew Adams
  0 siblings, 1 reply; 16+ messages in thread
From: Michael Albinus @ 2011-12-20 17:14 UTC (permalink / raw)
  To: Drew Adams; +Cc: 10319

"Drew Adams" <drew.adams@oracle.com> writes:

> Sounds like you have what you need now and will update the doc string, so this
> can be closed.  Thx for your help.

Sounds like everything is your wording. Do you want to commit it under
your name?

Best regards, Michael.





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-20 17:14                         ` Michael Albinus
@ 2011-12-20 17:33                           ` Drew Adams
  2011-12-21 18:34                             ` Michael Albinus
  0 siblings, 1 reply; 16+ messages in thread
From: Drew Adams @ 2011-12-20 17:33 UTC (permalink / raw)
  To: 'Michael Albinus'; +Cc: 10319

> Sounds like everything is your wording. Do you want to commit it under
> your name?

Please commit it for me.  You can use my name if you like.  Thx.






^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#10319: 24.0.92; doc string of `file-remote-p'
  2011-12-20 17:33                           ` Drew Adams
@ 2011-12-21 18:34                             ` Michael Albinus
  0 siblings, 0 replies; 16+ messages in thread
From: Michael Albinus @ 2011-12-21 18:34 UTC (permalink / raw)
  To: Drew Adams; +Cc: 10319-done

"Drew Adams" <drew.adams@oracle.com> writes:

>> Sounds like everything is your wording. Do you want to commit it under
>> your name?
>
> Please commit it for me.  You can use my name if you like.  Thx.

Done.

Thanks again, and best regards, Michael.





^ permalink raw reply	[flat|nested] 16+ messages in thread

end of thread, other threads:[~2011-12-21 18:34 UTC | newest]

Thread overview: 16+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2011-12-18  2:17 bug#10319: 24.0.92; doc string of `file-remote-p' Drew Adams
2011-12-18  8:33 ` Michael Albinus
2011-12-18 15:02   ` Drew Adams
2011-12-19  8:40     ` Michael Albinus
2011-12-19 16:10       ` Drew Adams
2011-12-19 18:26         ` Michael Albinus
2011-12-19 19:44           ` Drew Adams
2011-12-19 21:18             ` Michael Albinus
2011-12-19 21:29               ` Drew Adams
2011-12-20  9:15                 ` Michael Albinus
2011-12-20 15:53                   ` Drew Adams
2011-12-20 17:02                     ` Michael Albinus
2011-12-20 17:08                       ` Drew Adams
2011-12-20 17:14                         ` Michael Albinus
2011-12-20 17:33                           ` Drew Adams
2011-12-21 18:34                             ` 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).