or run:   go doc golang.org/x/tools/cmd/callgraph

Unfortunately, go doc doesn't work for modules that aren't listed in a go.mod file, such as installed commands:

% go doc golang.org/x/tools/cmd/callgraph
doc: no required module provides package golang.org/x/tools/cmd/callgraph: go.mod file not found in current directory or any parent directory; see 'go help modules'

Cautious support.

I dislike the idea of printing all known documentation every time the command line is incomplete or incorrect. This is a common behavior of a number of tools, although not all. I'm scarred by years of subcommands of various tools printing masses of output when all I need is to be told I typoed a line, or forgot to write "format" instead of "fmt". Programs are too eager to scroll my working text off the screen in the interest of providing full documentation. When mid-flow, too much text can be worse than not enough.

If I get the flags wrong, print the flags and nothing else. Otherwise just tell me how to get fuller documentation. Your proposal covers that in a sensible way.

So I am supportive, but there is more to lock down, stylewise. For instance, the usage message should not include an essay about all the ways you can use the tool. In fact, by default I think the usage message should always be a single sentence, as in the example above. Your example satisfies this property, but many other commands do not.

Answer the question that needs to be answered, and none other, and do it briefly.

Essentially the opposite of #27580

@seankhliao, not quite exactly the opposite, though — arguably much of the verbose go help documentation printed on the command line should be moved to online documentation too.

$ go doc golang.org/x/tools/cmd/callgraph@latest
doc: package golang.org/x/tools/cmd/callgraph@latest: can only use path@version syntax with 'go get' and 'go install' in module-aware mode

There should be a proposal to allow go doc module@version.

Traditionally, a problem for Go package documentation was that you would want to put a high level overview into the README for people browsing on GitHub, but that would then need to be duplicated in the Go doc. The pkg site now shows the README, which is good for de-duplication, but maybe go doc could show it too? That plus go doc path@version would be very powerful and simple.

There should be a proposal to allow go doc module@version.

You're right. Here it is: #63696

A potential thought experiment could be how to improve go help list documentation.
I'd also appreciate a shorter doc than what go help list currently offers, but also prefer to see sufficient details about what -f flag takes without needing the network and visiting the online documentation. go doc go (or go doc cmd/go) is too long to be useful in terminal and moreover, hard to guess for new users.

This proposal and #27580 complement each other IMO.
#27580 talks about the -h or --help. This proposal talks about compact help info.

For example, go help mod -h now tells me Run 'go help mod edit'.
go help mod edit then prints two pages long message and tells me See https://golang.org/ref/mod#go-mod-edit.

Ideally, we want go mod edit -h to print the amount of info this proposal proposes.
Personally, I don't mind seeing a long, more verbose details with go help mod that I can less or grep.

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

Here's a new potential canonical usage message:

% gofmt --help
Usage: gofmt [flags] [path ...]

  -cpuprofile file
    	write cpu profile to file
  -d	display diffs instead of rewriting files
  -e	report all errors (not just the first 10 on different lines)
  -l	list files whose formatting differs from gofmt's
  -r rule
    	apply rewrite rule (e.g., 'a[b:len(a)] -> a[b:]')
  -s	simplify code
  -w	write result to (source) file instead of stdout

Docs: go doc cmd/gofmt
https://pkg.go.dev/cmd/gofmt

Sharing some thoughts Russ and I had while developing the example above:

• The message should be a mere reminder of command syntax: no introduction, no concepts, no explanations.
• The first line presents syntax, and is followed by a blank.
• The flags should be printed by flag.PrintDefaults.
• The reader is referred to a go doc command that provides the complete manual. This allows them to read the docs without leaving their terminal, and works even for non-public code.
• In addition, a URL provides the complete manual as a web page.

Two helper functions to print each of the last two items, taking the package name (e.g. cmd/gofmt) from runtime/debug.ReadBuildInfo.Path, could potentially be added to the flag package, along with advice on how to produce a good usage message.

Have all remaining concerns about this proposal been addressed?

Proposed standard -help format in #63659 (comment).

Based on the discussion above, this proposal seems like a likely accept.
— rsc for the proposal review group

Proposed standard -help format in #63659 (comment).

No change in consensus, so accepted. 🎉
This issue now tracks the work of implementing the proposal.
— rsc for the proposal review group

Proposed standard -help format in #63659 (comment).

In addition, a URL provides the complete manual as a web page.

I know this is closed for comments, but I think that setting up an automated check that the manual links aren't broken automatically is prudent if we want the documentation to stay "strong" as domains and webservers move and deteriorate over time.

setting up an automated check that the manual links aren't broken automatically is prudent if we want the documentation to stay "strong" as domains and webservers move and deteriorate over time.

Russ and I discussed adding new public functions to the flag package that would assist in the printing of canonical help messages, perhaps by introspecting the main package to generate the go doc command and/or the pkg.go.dev URL, including the correct module version. If a user wants to write a test that makes an external HTTP request, they're free to do that, but it doesn't seem like the responsibility of the flag package.