builtins should not print entire usage summary on invalid use

[floam]

Consider

~ $ bind \e\c foo
Invalid token '\e\c'
fish: bind \e\c foo
           ^

This seems like it ought to be:

~ $ bind \e\c foo
fish: bind \e\c foo
           ^
Invalid token '\e\c'

Further:

~ $ functions -x
functions: Unknown option '-x'

       functions ‐‐ print or erase functions

   Synopsis
       functions [ ‐a | ‐‐all ] [ ‐n | ‐‐names ]
       functions ‐c OLDNAME NEWNAME
       functions ‐d DESCRIPTION FUNCTION
       functions [ ‐e | ‐q ] FUNCTIONS...

functions: Type 'help functions' for related documentation

We should place the error after the usage information. Sometimes it can be long and the error, far away.

[krader1961]

We should place the error after the usage information.

No. The error should be foremost (i.e. "front and center"). That functions -x outputs usage text rather than a mention to run man functions is itself a bug IMHO.

[ridiculousfish]

Agreed with @krader on both counts. Outputting the full usage spec just obscures the error message. I'd be in favor of replacing the "output full usage on error behavior" with a pointer to how to access the usage, e.g. to run man functions.

[floam]

That works too. The main issue is when the usage spec pushes the actual error off screen.

[zanchey]

That functions -x outputs usage text rather than a mention to run man functions is itself a bug IMHO.

Shall we track that here then?

[floam]

What might be the issue is not where we output usage output at all, but how "full" our manpage-derived usage output can be unnecessarily.

typical manpage-parsed output:
$ __fish_print_help fish_realpath

       fish_realpath ‐‐ Convert a path to an absolute path without symlinks

   Synopsis
       fish_realpath path

   Description
       This is an implementation of the external realpath command that
       doesn’t support any options. It’s meant to be used only by scripts
       which need to be portable. In general scripts shouldn’t invoke this
       directly. They should just use realpath which will fallback to this
       builtin if an external command cannot be found.

       If the path is invalid no translated path will be written to stdout
       and an error will be reported. This implementation behaves like the
       GNU command being invoked with ‐‐canonicalize‐existing.

should be more like 1-2 lines (and is where I did this by hand):

$ realpath
usage: realpath file …
     resolves files as absolute paths without symlinks

[faho]

Yeah, I just removed the summary. It's fluff, people can use the man page or help.

[floam]

I sure wish we had a nice way to spit out a succinct usage line.

[floam]

I think we could have kept the man page thing and just more carefully cut up the output.