cli: Make tinygo help experience more consistent with go help

[m-kru]

Currently the output from the tinygo help command looks as follows:

TinyGo is a Go compiler for small places.
version: 0.27.0
usage: tinygo <command> [arguments]

commands:
  build:   compile packages and dependencies
  run:     compile and run immediately
  test:    test packages
  flash:   compile and flash to the device
  gdb:     run/flash and immediately enter GDB
  lldb:    run/flash and immediately enter LLDB
  monitor: open communication port
  env:     list environment variables used during build
  list:    run go list using the TinyGo root
  clean:   empty cache directory (/home/mkru/.cache/tinygo)
  targets: list targets
  info:    show info for specified target
  version: show version
  help:    print this help text

flags:
  -baudrate int
    	baudrate of serial monitor (default 115200)
  -bench string
    	run: regexp of benchmarks to run
  -benchmem
    	show memory stats for benchmarks
  -benchtime d
    	run each benchmark for duration d
  -c	compile the test binary but do not run it
  -cpuprofile string
    	cpuprofile output
  -deps
    	supply -deps flag to go list
  -dumpssa
    	dump internal Go SSA
  -gc string
    	garbage collector to use (none, leaking, conservative)
  -interp-timeout duration
    	interp optimization pass timeout (default 3m0s)
  -json
    	print data in JSON format
  -ldflags string
    	Go link tool compatible ldflags
  -llvm-features string
    	comma separated LLVM features to enable
  -monitor
    	enable serial monitor
  -no-debug
    	strip debug information
  -o string
    	output filename
  -ocd-commands string
    	OpenOCD commands, overriding target spec (can specify multiple separated by commas)
  -ocd-output
    	print OCD daemon output during debug
  -opt string
    	optimization level: 0, 1, 2, s, z (default "z")
  -p int
    	the number of build jobs that can run in parallel (default 12)
  -panic string
    	panic strategy (print, trap) (default "print")
  -port string
    	flash port (can specify multiple candidates separated by commas)
  -print-allocs string
    	regular expression of functions for which heap allocations should be printed
  -print-stacks
    	print stack sizes of goroutines
  -printir
    	print LLVM IR
  -programmer string
    	which hardware programmer to use
  -run string
    	run: regexp of tests to run
  -scheduler string
    	which scheduler to use (none, tasks, asyncify)
  -serial string
    	which serial output to use (none, uart, usb)
  -short
    	short: run smaller test suite to save time
  -size string
    	print sizes (none, short, full)
  -stack-size value
    	goroutine stack size (if unknown at compile time)
  -tags value
    	a space-separated list of extra build tags
  -target string
    	chip/board name or JSON target specification file
  -test
    	supply -test flag to go list
  -timeout duration
    	the length of time to retry locating the MSD volume to be used for flashing (default 20s)
  -v	verbose: print additional output
  -verifyir
    	run extra verification steps on LLVM IR
  -work
    	print the name of the temporary build directory and do not delete this directory on exit
  -x	Print commands

for more details, see https://tinygo.org/docs/reference/usage/

I propose to make tinygo help experience more coherent with go go help experience because of following reasons:

1. People usually run help command to see what commands and topics are available to formulate more concrete command. Right now they are flooded with flags and one needs to scroll up to see the commands.
2. People are used to go help experience. Making it more coherent would simply feel more natural.
3. Having additional help topics embedded into the binary makes the documentation exists in one place. One can even read most of the relevant documentation without Internet access.

I can imagine, that after the change the go help output would look something like this:

TinyGo is a Go compiler for small places.
version: 0.27.0

Usage:

    tinygo <command> [arguments]

The commands are:

    build     compile packages and dependencies
    clean     empty cache directory (/home/mkru/.cache/tinygo)
    env       list environment variables used during build
    flash     compile and flash to the device
    gdb       run/flash and immediately enter GDB
    help      print this help text
    list      run go list using the TinyGo root
    lldb      run/flash and immediately enter LLDB
    monitor   open communication port
    run       compile and run immediately
    test      test packages
    version   show version

Use "tinygo help <command>" for more information about a command.

Additional help topics:

    flags     general flags
    gc        garbage collector
    info      show info for specified target
    targets   list targets

Use "tinygo help <topic>" for more information about that topic.

The required work includes:

1. Removing : character from the command suffix, and increase space between command and its description.
2. Sort commands and additional help topics in alphabetical order.
3. Move info and targets to additional topics.
4. Move flags to newly created flags topic.
5. Create gc topic and place all garbage collector related flags and information there.

Of course more additional help topics can be added now or in the future when it is decided that it makes sense.

[deadprogram]

Seems to me that making tinygo help closer to go help is a good thing. A pull request to bring things closer in alignment would I'm sure be welcomed.

[bjornpagen]

#3743
my branch looks like this now, lmk if changes needed:

TinyGo is a Go compiler for small places.
version: 0.28.0-dev

Usage:

        tinygo <command> [arguments]

The commands are:

        build          compile packages and dependencies
        clean          empty cache directory (/home/mkru/.cache/tinygo)
        env            list environment variables used during build
        flash          compile and flash to the device
        gdb            run/flash and immediately enter GDB
        help           print this help text
        list           run go list using the TinyGo root
        lldb           run/flash and immediately enter LLDB
        monitor        open communication port
        run            compile and run immediately
        test           test packages
        version        show version

Use "tinygo help <command>" for more information about a command.

Additional help topics:

        flags          general flags
        info           show info for specified target
        targets        list targets

Use "tinygo help <topic>" for more information about that topic.

for more details, see https://tinygo.org/docs/reference/usage/

vs go:

Go is a tool for managing Go source code.

Usage:

        go <command> [arguments]

The commands are:

        bug         start a bug report
        build       compile packages and dependencies
        clean       remove object files and cached files
        doc         show documentation for package or symbol
        env         print Go environment information
        fix         update packages to use new APIs
        fmt         gofmt (reformat) package sources
        generate    generate Go files by processing source
        get         add dependencies to current module and install them
        install     compile and install packages and dependencies
        list        list packages or modules
        mod         module maintenance
        work        workspace maintenance
        run         compile and run Go program
        test        test packages
        tool        run specified go tool
        version     print Go version
        vet         report likely mistakes in packages

Use "go help <command>" for more information about a command.

Additional help topics:

        buildconstraint build constraints
        buildmode       build modes
        c               calling between Go and C
        cache           build and test caching
        environment     environment variables
        filetype        file types
        go.mod          the go.mod file
        gopath          GOPATH environment variable
        gopath-get      legacy GOPATH go get
        goproxy         module proxy protocol
        importpath      import path syntax
        modules         modules, module versions, and more
        module-get      module-aware go get
        module-auth     module authentication using go.sum
        packages        package lists and patterns
        private         configuration for downloading non-public code
        testflag        testing flags
        testfunc        testing functions
        vcs             controlling version control with GOVCS

Use "go help <topic>" for more information about that topic.

[dgryski]

Usage docs updated in #4467; closing. Please file a new bug if you still have issues.