Improving discoverability of the e: namespace for external commands
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_addexample (soe:pkg_add) might be a good way to implicitly clue users in. (Use ofe:some_command_with_underscoresmight 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 :)
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).