elvish icon indicating copy to clipboard operation
elvish copied to clipboard

Improving discoverability of the e: namespace for external commands

Open therealpxc opened this issue 5 years ago • 1 comments

Happily, Elvish has a really convenient way to ensure that the command you're invoking is an external program without the use of special syntax. It's currently documented in the pages for the full language specification and the Cookbook, but it could be helpful to newbies to mention it in a couple more places, like:

  • the page for builtins, next to the section on explicitly invoking them, add a section titled something like ‘Avoiding a builtin’
  • the Effective Elvish page, in the section on Naming commands, using the Elvish syntax for explicitly invoking an external command with the pkg_add example (so e:pkg_add) might be a good way to implicitly clue users in. (Use of e:some_command_with_underscores might also be a nice convention for signaling compliance with the naming conventions with respect to underscores, when you want to deal with external commands that have them in their names, too)
  • add a mention of how to explicitly invoke external commands on the Builtin and Internal Commands section of the Fundamentals page, maybe add a link to the Special Namespaces subsection of the language specification page
  • maybe in addition to their listings on the general refs page, list all of the builtin namespaces (special and module) in a section on the Builtins page?

Maybe all of those together is overkill, but hopefully at least some of them are agreeable suggestions :)

therealpxc avatar Sep 28 '20 03:09 therealpxc

See also the discussion of command resolution. That text is probably borderline incomprehensible to anyone who is not a computer scientist or software engineer. It is also a natural place to document how to force the use of an external command or a builtin (as in from a function of the same name by using the builtin: namespace prefix).

krader1961 avatar Oct 02 '20 03:10 krader1961