Eli Zaretskii <eliz@gnu.org> writes:

>> > If you want to know that so you could always get the same responses as
>> > from another system shell, then perhaps we should have an option to
>> > tell Eshell to always invoke an external program (maybe we already
>> > have such an option, but I couldn't find it).
>>
>> No, not like that, more like a friendly reminder: "this 'date' behaves
>> the Eshell way, while that 'rmdir' is the system program".
>
> But the answer to that question depends on the arguments and sometimes
> on the switches, doesn't it?  E.g., Eshell's 'rm' can delete processes
> and buffers, and unintern symbols, in addition to deleting files.
> What exactly it does depends on the arguments.  And if you invoke it
> with -d switch, it will call the external program, but if you invoke
> with -f or -i or -n, it will use the built-in.  So just given the
> verb, I don't see how you can have that indication.

Wow, I did not know that.  This is not documented in the docstring, but
I just saw it is mentioned in the help message.

That maybe it the root of the issue: what's the standard way of
documenting 'eshell/*' commands?

I think both `-h' and `C-h f' should document the same thing, it's
confusing otherwise.  Lest users suffer too much from the "Where did I
find that valuable help again?" syndrom.

>> > Isn't it true that a verb that doesn't begin with a '*' is _never_ a
>> > system program in Eshell?
>>
>> I'm tempted to answer "no, it's not true", but we might be
>> misunderstood.
>>
>> As far as I got it, the '*' is here to force Eshell to use the system
>> program, while no '*' tells Eshell to use its own version if available,
>> or the system program otherwise.
>
> So you want to have an indication when there's _no_ built-in
> implementation at all, is that it?

No.  Basically if I write "rm" in Eshell, Eshell will _always_ call
eshell/rm.  Only afterwards it will make a call to /bin/rm, depending on
the arguments.
As a user, what I want to know is what Eshell will call _first_, because
then I can know the starting point of what Eshell is going to do.

Basically, my idea is simple:

- If 'eshell/foo' exists, use some eshell-builtin face on "foo". The
user will then know that s/he should lookup the documentation of
eshell/foo.

- Otherwise use the normal face.  The user will then refer to the man
  page and the like.

--
Pierre Neidhardt

If the grass is greener on other side of fence, consider what may be
fertilizing it.