main: rework usage

main.go

@@ -1256,36 +1256,151 @@ func getBMPPorts() (gdbPort, uartPort string, err error) {
 	}
 }
 
-func usage(command string) {
-	switch command {
-	default:
-		fmt.Fprintln(os.Stderr, "TinyGo is a Go compiler for small places.")
-		fmt.Fprintln(os.Stderr, "version:", goenv.Version())
-		fmt.Fprintf(os.Stderr, "usage: %s <command> [arguments]\n", os.Args[0])
-		fmt.Fprintln(os.Stderr, "\ncommands:")
-		fmt.Fprintln(os.Stderr, "  build:   compile packages and dependencies")
-		fmt.Fprintln(os.Stderr, "  run:     compile and run immediately")
-		fmt.Fprintln(os.Stderr, "  test:    test packages")
-		fmt.Fprintln(os.Stderr, "  flash:   compile and flash to the device")
-		fmt.Fprintln(os.Stderr, "  gdb:     run/flash and immediately enter GDB")
-		fmt.Fprintln(os.Stderr, "  lldb:    run/flash and immediately enter LLDB")
-		fmt.Fprintln(os.Stderr, "  monitor: open communication port")
-		fmt.Fprintln(os.Stderr, "  ports:   list available serial ports")
-		fmt.Fprintln(os.Stderr, "  env:     list environment variables used during build")
-		fmt.Fprintln(os.Stderr, "  list:    run go list using the TinyGo root")
-		fmt.Fprintln(os.Stderr, "  clean:   empty cache directory ("+goenv.Get("GOCACHE")+")")
-		fmt.Fprintln(os.Stderr, "  targets: list targets")
-		fmt.Fprintln(os.Stderr, "  info:    show info for specified target")
-		fmt.Fprintln(os.Stderr, "  version: show version")
-		fmt.Fprintln(os.Stderr, "  help:    print this help text")
+const (
+	usageBuild = ` Compile the given program. The output binary is specified using the -o parameter.
+The generated file type depends on the extension:
+
+	.o: 				
+					Create a relocatable object file. You can use this option if you don't want to 
+					use the TinyGo build system or want to do other custom things.
+
+	.ll: 			
+					Create textual LLVM IR, after optimization. This is mainly useful for debugging.
+
+	.bc: 			
+					Create LLVM bitcode, after optimization. This may be useful for debugging or for
+					linking into other programs using LTO.
+
+	.hex 
+					Create an Intel HEX file to flash it to a microcontroller.
+
+	.bin
+					Similar, but create a binary file.
+
+	.wasm 			
+					Compile and link a WebAssembly file.
+
+(all other) Compile and link the program into a regular executable. For microcontrollers, it is
+common to use the .elf file extension to indicate a linked ELF file is generated. For Linux, it is 
+common to build binaries with no extension at all.`
+
+	usageRun = `Run the program, either directly on the host or in an emulated environment (depending on -target).\`
+
+	usageFlash = `Flash the program to a microcontroller. Some common flags are described below.
+
+	-target={name}: 
+					Specifies the type of microcontroller that is used. The name of the 
+					microcontroller is given on the individual pages for each board type
+					listed under Microcontrollers 
+					(https://tinygo.org/docs/reference/microcontrollers/)
+					Examples: "arduino-nano", "d1mini", "xiao".
+
+	-monitor: 
+					Start the serial monitor (see below) immediately after flashing. However,
+					some microcontrollers need a split second or two to configure the serial 
+					port after flashing, and using the "-monitor" flag can fail because the serial 
+					monitor starts too quickly. In that case, use the "tinygo monitor" command 
+					explicitly.`
+
+	usageMonitor = `Start the serial monitor on the serial port that is connected to the microcontroller. If there is
+only a single board attached to the host computer, the default values for various options should
+be sufficient. In other situations, particularly if you have multiple microcontrollers attached, 
+some parameters may need to be overridden using the following flags:
+
+	-port={port}: 
+					If there are multiple microcontroller attached, an error message will display
+					a list of potential serial ports. The appropriate port can be specified by this
+					flag. On Linux, the port will be something like /dev/ttyUSB0 or /dev/ttyACM1.
+					On MacOS, the port will look like /dev/cu.usbserial-1420. On Windows, the port
+					will be something like COM1 or COM31.
+
+	-baudrate={rate}: 
+					The default baud rate is 115200. Boards using the AVR processor (e.g. Arduino Nano,
+					Arduino Mega 2560) use 9600 instead.
+
+	-target={name}:
+					If you have more than one microcontrollers attached, you can sometimes just
+					specify the target name and let tinygo monitor figure out the port. Sometimes,
+					this does not work and you have to explicitly use the -port flag.
+
+The serial monitor intercepts several control characters for its own use instead of sending them
+to the microcontroller:
+
+    Control-C: terminates the tinygo monitor
+    Control-Z: suspends the tinygo monitor and drops back into shell
+    Control-\: terminates the tinygo monitor with a stack trace
+    Control-S: flow control, suspends output to the console
+    Control-Q: flow control, resumes output to the console
+    Control-@: thrown away by tinygo monitor
+
+Note: If you are using os.Stdin on the microcontroller, you may find that a CR character on the
+host computer (also known as Enter, ^M, or \r) is transmitted to the microcontroller without conversion,
+so os.Stdin returns a \r character instead of the expected \n (also known as ^J, NL, or LF) to indicate
+end-of-line. You may be able to get around this problem by hitting Control-J in tinygo monitor to 
+transmit the \n end-of-line character.`
+
+	usageGdb = `Compile the program, optionally flash it to a microcontroller if it is a remote target, and drop into
+a GDB shell. From there you can set breakpoints, start the program with "run" or "continue" ("run" for a
+local program, continue for on-chip debugging), single-step, show a backtrace, break and resume the
+program with Ctrl-C/"continue", etc. You may need to install extra tools (like openocd and arm-none-eabi-gdb)
+to be able to do this. Also, you may need a dedicated debugger to be able to debug certain boards
+if no debugger is integrated. Some boards (like the BBC micro:bit and most professional evaluation
+boards) have an integrated debugger.`
+
+	usageClean   = `Clean the cache directory, normally stored in $HOME/.cache/tinygo. This is not normally needed.`
+	usageHelp    = ` Print a short summary of the available commands, plus a list of command flags.`
+	usageVersion = `Print the version of the command and the version of the used $GOROOT.`
+	usageEnv     = ` Print a list of environment variables that affect TinyGo (as a shell script).
+If one or more variable names are given as arguments, env prints the value of each on a new line.`
+	usageDefault = `TinyGo is a Go compiler for small places.
+version: %s
+usage: %s <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
+	  ports:   	list available serial ports
+	  env:     	list environment variables used during build
+	  list:    	run go list using the TinyGo root
+	  clean:   	empty cache directory (%s)
+	  targets: 	list targets
+	  info:    	show info for specified target
+	  version: 	show version
+	  help:    	print this help text`
+)
+
+var (
+	commandHelp = map[string]string{
+		"build":   usageBuild,
+		"run":     usageRun,
+		"flash":   usageFlash,
+		"monitor": usageMonitor,
+		"gdb":     usageGdb,
+		"clean":   usageClean,
+		"help":    usageHelp,
+		"version": usageVersion,
+		"env":     usageEnv,
+	}
+)
 
+func usage(command string) {
+	val, ok := commandHelp[command]
+	if !ok {
+		fmt.Fprintf(os.Stderr, usageDefault, goenv.Version(), os.Args[0], goenv.Get("GOCACHE"))
 		if flag.Parsed() {
 			fmt.Fprintln(os.Stderr, "\nflags:")
 			flag.PrintDefaults()
 		}
 
 		fmt.Fprintln(os.Stderr, "\nfor more details, see https://tinygo.org/docs/reference/usage/")
+	} else {
+		fmt.Fprintln(os.Stderr, val)
 	}
+
 }
 
 func handleCompilerError(err error) {