Documentation,cmd/dlv: tidy up --help output (#1649)

* scripts: use relative path in gen-cli-docs.go

Makes gen-cli-docs.go work outside GOPATH.

* Documentation,cmd/dlv: tidy up --help output

The description of --log-dest, --log-output and --backend is very
verbose and messes up the output of --help, move it to two "additional
help" subcommands.

Documentation/usage/dlv.md

@@ -19,30 +19,17 @@ Pass flags to the program you are debugging using `--`, for example:
 ### Options
 
 ```
-      --accept-multiclient   Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
       --api-version int      Selects API version when headless. (default 1)
-      --backend string       Backend selection:
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
-	default		Uses lldb on macOS, native everywhere else.
-	native		Native backend.
-	lldb		Uses lldb-server or debugserver.
-	rr		Uses mozilla rr (https://github.com/mozilla/rr).
- (default "default")
       --build-flags string   Build flags, to be passed to the compiler.
       --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
       --headless             Run debug server only, in headless mode.
       --init string          Init file, executed by the terminal client.
   -l, --listen string        Debugging server listen address. (default "127.0.0.1:0")
       --log                  Enable debugging server logging.
-      --log-dest string      Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string    Comma separated list of components that should produce debug output, possible values:
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
-	debugger	Log debugger commands
-	gdbwire		Log connection to gdbserial backend
-	lldbout		Copy output from debugserver/lldb to standard output
-	debuglineerr	Log recoverable errors reading .debug_line
-	rpc		Log all RPC messages
-	fncall		Log function call protocol
-	minidump	Log minidump loading
-Defaults to "debugger" when logging is enabled with --log.
       --wd string            Working directory for running the program. (default ".")
 ```
 
@@ -58,3 +45,5 @@ Defaults to "debugger" when logging is enabled with --log.
 * [dlv trace](dlv_trace.md)	 - Compile and begin tracing program.
 * [dlv version](dlv_version.md)	 - Prints version.
 
+* [dlv log](dlv_log.md)	 - Help about logging flags
+* [dlv backend](dlv_backend.md)	 - Help about the `--backend` flag

Documentation/usage/dlv_attach.md

@@ -19,30 +19,17 @@ dlv attach pid [executable]
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient   Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
       --api-version int      Selects API version when headless. (default 1)
-      --backend string       Backend selection:
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
-	default		Uses lldb on macOS, native everywhere else.
-	native		Native backend.
-	lldb		Uses lldb-server or debugserver.
-	rr		Uses mozilla rr (https://github.com/mozilla/rr).
- (default "default")
       --build-flags string   Build flags, to be passed to the compiler.
       --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
       --headless             Run debug server only, in headless mode.
       --init string          Init file, executed by the terminal client.
   -l, --listen string        Debugging server listen address. (default "127.0.0.1:0")
       --log                  Enable debugging server logging.
-      --log-dest string      Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string    Comma separated list of components that should produce debug output, possible values:
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
-	debugger	Log debugger commands
-	gdbwire		Log connection to gdbserial backend
-	lldbout		Copy output from debugserver/lldb to standard output
-	debuglineerr	Log recoverable errors reading .debug_line
-	rpc		Log all RPC messages
-	fncall		Log function call protocol
-	minidump	Log minidump loading
-Defaults to "debugger" when logging is enabled with --log.
       --wd string            Working directory for running the program. (default ".")
 ```
 

Documentation/usage/dlv_backend.md

@@ -0,0 +1,37 @@
+## dlv backend
+
+Help about the --backend flag.
+
+### Synopsis
+
+
+The --backend flag specifies which backend should be used, possible values
+are:
+
+	default		Uses lldb on macOS, native everywhere else.
+	native		Native backend.
+	lldb		Uses lldb-server or debugserver.
+	rr		Uses mozilla rr (https://github.com/mozilla/rr).
+
+
+
+### Options inherited from parent commands
+
+```
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
+      --api-version int      Selects API version when headless. (default 1)
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
+      --build-flags string   Build flags, to be passed to the compiler.
+      --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
+      --headless             Run debug server only, in headless mode.
+      --init string          Init file, executed by the terminal client.
+  -l, --listen string        Debugging server listen address. (default "localhost:0")
+      --log                  Enable debugging server logging.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
+      --wd string            Working directory for running the program. (default ".")
+```
+
+### SEE ALSO
+* [dlv](dlv.md)	 - Delve is a debugger for the Go programming language.
+

Documentation/usage/dlv_connect.md

@@ -14,30 +14,17 @@ dlv connect addr
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient   Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
       --api-version int      Selects API version when headless. (default 1)
-      --backend string       Backend selection:
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
-	default		Uses lldb on macOS, native everywhere else.
-	native		Native backend.
-	lldb		Uses lldb-server or debugserver.
-	rr		Uses mozilla rr (https://github.com/mozilla/rr).
- (default "default")
       --build-flags string   Build flags, to be passed to the compiler.
       --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
       --headless             Run debug server only, in headless mode.
       --init string          Init file, executed by the terminal client.
   -l, --listen string        Debugging server listen address. (default "127.0.0.1:0")
       --log                  Enable debugging server logging.
-      --log-dest string      Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string    Comma separated list of components that should produce debug output, possible values:
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
-	debugger	Log debugger commands
-	gdbwire		Log connection to gdbserial backend
-	lldbout		Copy output from debugserver/lldb to standard output
-	debuglineerr	Log recoverable errors reading .debug_line
-	rpc		Log all RPC messages
-	fncall		Log function call protocol
-	minidump	Log minidump loading
-Defaults to "debugger" when logging is enabled with --log.
       --wd string            Working directory for running the program. (default ".")
 ```
 

Documentation/usage/dlv_core.md

@@ -20,30 +20,17 @@ dlv core <executable> <core>
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient   Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
       --api-version int      Selects API version when headless. (default 1)
-      --backend string       Backend selection:
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
-	default		Uses lldb on macOS, native everywhere else.
-	native		Native backend.
-	lldb		Uses lldb-server or debugserver.
-	rr		Uses mozilla rr (https://github.com/mozilla/rr).
- (default "default")
       --build-flags string   Build flags, to be passed to the compiler.
       --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
       --headless             Run debug server only, in headless mode.
       --init string          Init file, executed by the terminal client.
   -l, --listen string        Debugging server listen address. (default "127.0.0.1:0")
       --log                  Enable debugging server logging.
-      --log-dest string      Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string    Comma separated list of components that should produce debug output, possible values:
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
-	debugger	Log debugger commands
-	gdbwire		Log connection to gdbserial backend
-	lldbout		Copy output from debugserver/lldb to standard output
-	debuglineerr	Log recoverable errors reading .debug_line
-	rpc		Log all RPC messages
-	fncall		Log function call protocol
-	minidump	Log minidump loading
-Defaults to "debugger" when logging is enabled with --log.
       --wd string            Working directory for running the program. (default ".")
 ```
 

Documentation/usage/dlv_debug.md

@@ -26,30 +26,17 @@ dlv debug [package]
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient   Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
       --api-version int      Selects API version when headless. (default 1)
-      --backend string       Backend selection:
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
-	default		Uses lldb on macOS, native everywhere else.
-	native		Native backend.
-	lldb		Uses lldb-server or debugserver.
-	rr		Uses mozilla rr (https://github.com/mozilla/rr).
- (default "default")
       --build-flags string   Build flags, to be passed to the compiler.
       --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
       --headless             Run debug server only, in headless mode.
       --init string          Init file, executed by the terminal client.
   -l, --listen string        Debugging server listen address. (default "127.0.0.1:0")
       --log                  Enable debugging server logging.
-      --log-dest string      Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string    Comma separated list of components that should produce debug output, possible values:
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
-	debugger	Log debugger commands
-	gdbwire		Log connection to gdbserial backend
-	lldbout		Copy output from debugserver/lldb to standard output
-	debuglineerr	Log recoverable errors reading .debug_line
-	rpc		Log all RPC messages
-	fncall		Log function call protocol
-	minidump	Log minidump loading
-Defaults to "debugger" when logging is enabled with --log.
       --wd string            Working directory for running the program. (default ".")
 ```
 

Documentation/usage/dlv_exec.md

@@ -26,30 +26,17 @@ dlv exec <path/to/binary>
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient   Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
       --api-version int      Selects API version when headless. (default 1)
-      --backend string       Backend selection:
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
-	default		Uses lldb on macOS, native everywhere else.
-	native		Native backend.
-	lldb		Uses lldb-server or debugserver.
-	rr		Uses mozilla rr (https://github.com/mozilla/rr).
- (default "default")
       --build-flags string   Build flags, to be passed to the compiler.
       --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
       --headless             Run debug server only, in headless mode.
       --init string          Init file, executed by the terminal client.
   -l, --listen string        Debugging server listen address. (default "127.0.0.1:0")
       --log                  Enable debugging server logging.
-      --log-dest string      Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string    Comma separated list of components that should produce debug output, possible values:
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
-	debugger	Log debugger commands
-	gdbwire		Log connection to gdbserial backend
-	lldbout		Copy output from debugserver/lldb to standard output
-	debuglineerr	Log recoverable errors reading .debug_line
-	rpc		Log all RPC messages
-	fncall		Log function call protocol
-	minidump	Log minidump loading
-Defaults to "debugger" when logging is enabled with --log.
       --wd string            Working directory for running the program. (default ".")
 ```
 

Documentation/usage/dlv_log.md

@@ -0,0 +1,51 @@
+## dlv log
+
+Help about logging flags.
+
+### Synopsis
+
+
+Logging can be enabled by specifying the --log flag and using the
+--log-output flag to select which components should produce logs.
+
+The argument of --log-output must be a comma separated list of component
+names selected from this list:
+
+
+	debugger	Log debugger commands
+	gdbwire		Log connection to gdbserial backend
+	lldbout		Copy output from debugserver/lldb to standard output
+	debuglineerr	Log recoverable errors reading .debug_line
+	rpc		Log all RPC messages
+	fncall		Log function call protocol
+	minidump	Log minidump loading
+
+Additionally --log-dest can be used to specify where the logs should be
+written. 
+If the argument is a number it will be interpreted as a file descriptor,
+otherwise as a file path.
+This option will also redirect the \"API listening\" message in headless
+mode.
+
+
+
+### Options inherited from parent commands
+
+```
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
+      --api-version int      Selects API version when headless. (default 1)
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
+      --build-flags string   Build flags, to be passed to the compiler.
+      --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
+      --headless             Run debug server only, in headless mode.
+      --init string          Init file, executed by the terminal client.
+  -l, --listen string        Debugging server listen address. (default "localhost:0")
+      --log                  Enable debugging server logging.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
+      --wd string            Working directory for running the program. (default ".")
+```
+
+### SEE ALSO
+* [dlv](dlv.md)	 - Delve is a debugger for the Go programming language.
+

Documentation/usage/dlv_replay.md

@@ -18,30 +18,17 @@ dlv replay [trace directory]
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient   Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
       --api-version int      Selects API version when headless. (default 1)
-      --backend string       Backend selection:
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
-	default		Uses lldb on macOS, native everywhere else.
-	native		Native backend.
-	lldb		Uses lldb-server or debugserver.
-	rr		Uses mozilla rr (https://github.com/mozilla/rr).
- (default "default")
       --build-flags string   Build flags, to be passed to the compiler.
       --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
       --headless             Run debug server only, in headless mode.
       --init string          Init file, executed by the terminal client.
   -l, --listen string        Debugging server listen address. (default "127.0.0.1:0")
       --log                  Enable debugging server logging.
-      --log-dest string      Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string    Comma separated list of components that should produce debug output, possible values:
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
-	debugger	Log debugger commands
-	gdbwire		Log connection to gdbserial backend
-	lldbout		Copy output from debugserver/lldb to standard output
-	debuglineerr	Log recoverable errors reading .debug_line
-	rpc		Log all RPC messages
-	fncall		Log function call protocol
-	minidump	Log minidump loading
-Defaults to "debugger" when logging is enabled with --log.
       --wd string            Working directory for running the program. (default ".")
 ```
 

Documentation/usage/dlv_run.md

@@ -14,30 +14,17 @@ dlv run
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient   Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
       --api-version int      Selects API version when headless. (default 1)
-      --backend string       Backend selection:
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
-	default		Uses lldb on macOS, native everywhere else.
-	native		Native backend.
-	lldb		Uses lldb-server or debugserver.
-	rr		Uses mozilla rr (https://github.com/mozilla/rr).
- (default "default")
       --build-flags string   Build flags, to be passed to the compiler.
       --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
       --headless             Run debug server only, in headless mode.
       --init string          Init file, executed by the terminal client.
   -l, --listen string        Debugging server listen address. (default "127.0.0.1:0")
       --log                  Enable debugging server logging.
-      --log-dest string      Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string    Comma separated list of components that should produce debug output, possible values:
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
-	debugger	Log debugger commands
-	gdbwire		Log connection to gdbserial backend
-	lldbout		Copy output from debugserver/lldb to standard output
-	debuglineerr	Log recoverable errors reading .debug_line
-	rpc		Log all RPC messages
-	fncall		Log function call protocol
-	minidump	Log minidump loading
-Defaults to "debugger" when logging is enabled with --log.
       --wd string            Working directory for running the program. (default ".")
 ```
 

Documentation/usage/dlv_test.md

@@ -25,30 +25,17 @@ dlv test [package]
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient   Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
       --api-version int      Selects API version when headless. (default 1)
-      --backend string       Backend selection:
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
-	default		Uses lldb on macOS, native everywhere else.
-	native		Native backend.
-	lldb		Uses lldb-server or debugserver.
-	rr		Uses mozilla rr (https://github.com/mozilla/rr).
- (default "default")
       --build-flags string   Build flags, to be passed to the compiler.
       --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
       --headless             Run debug server only, in headless mode.
       --init string          Init file, executed by the terminal client.
   -l, --listen string        Debugging server listen address. (default "127.0.0.1:0")
       --log                  Enable debugging server logging.
-      --log-dest string      Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string    Comma separated list of components that should produce debug output, possible values:
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
-	debugger	Log debugger commands
-	gdbwire		Log connection to gdbserial backend
-	lldbout		Copy output from debugserver/lldb to standard output
-	debuglineerr	Log recoverable errors reading .debug_line
-	rpc		Log all RPC messages
-	fncall		Log function call protocol
-	minidump	Log minidump loading
-Defaults to "debugger" when logging is enabled with --log.
       --wd string            Working directory for running the program. (default ".")
 ```
 

Documentation/usage/dlv_trace.md

@@ -29,30 +29,17 @@ dlv trace [package] regexp
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient   Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
       --api-version int      Selects API version when headless. (default 1)
-      --backend string       Backend selection:
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
-	default		Uses lldb on macOS, native everywhere else.
-	native		Native backend.
-	lldb		Uses lldb-server or debugserver.
-	rr		Uses mozilla rr (https://github.com/mozilla/rr).
- (default "default")
       --build-flags string   Build flags, to be passed to the compiler.
       --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
       --headless             Run debug server only, in headless mode.
       --init string          Init file, executed by the terminal client.
   -l, --listen string        Debugging server listen address. (default "127.0.0.1:0")
       --log                  Enable debugging server logging.
-      --log-dest string      Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string    Comma separated list of components that should produce debug output, possible values:
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
-	debugger	Log debugger commands
-	gdbwire		Log connection to gdbserial backend
-	lldbout		Copy output from debugserver/lldb to standard output
-	debuglineerr	Log recoverable errors reading .debug_line
-	rpc		Log all RPC messages
-	fncall		Log function call protocol
-	minidump	Log minidump loading
-Defaults to "debugger" when logging is enabled with --log.
       --wd string            Working directory for running the program. (default ".")
 ```
 

Documentation/usage/dlv_version.md

@@ -14,30 +14,17 @@ dlv version
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient   Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.
+      --accept-multiclient   Allows a headless server to accept multiple client connections.
       --api-version int      Selects API version when headless. (default 1)
-      --backend string       Backend selection:
+      --backend string       Backend selection (see 'dlv help backend'). (default "default")
-	default		Uses lldb on macOS, native everywhere else.
-	native		Native backend.
-	lldb		Uses lldb-server or debugserver.
-	rr		Uses mozilla rr (https://github.com/mozilla/rr).
- (default "default")
       --build-flags string   Build flags, to be passed to the compiler.
       --check-go-version     Checks that the version of Go in use is compatible with Delve. (default true)
       --headless             Run debug server only, in headless mode.
       --init string          Init file, executed by the terminal client.
   -l, --listen string        Debugging server listen address. (default "127.0.0.1:0")
       --log                  Enable debugging server logging.
-      --log-dest string      Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode.
+      --log-dest string      Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string    Comma separated list of components that should produce debug output, possible values:
+      --log-output string    Comma separated list of components that should produce debug output (see 'dlv help log')
-	debugger	Log debugger commands
-	gdbwire		Log connection to gdbserial backend
-	lldbout		Copy output from debugserver/lldb to standard output
-	debuglineerr	Log recoverable errors reading .debug_line
-	rpc		Log all RPC messages
-	fncall		Log function call protocol
-	minidump	Log minidump loading
-Defaults to "debugger" when logging is enabled with --log.
       --wd string            Working directory for running the program. (default ".")
 ```
 

cmd/dlv/cmds/commands.go

@@ -101,30 +101,17 @@ func New(docCall bool) *cobra.Command {
 	RootCommand.PersistentFlags().StringVarP(&Addr, "listen", "l", "127.0.0.1:0", "Debugging server listen address.")
 
 	RootCommand.PersistentFlags().BoolVarP(&Log, "log", "", false, "Enable debugging server logging.")
-	RootCommand.PersistentFlags().StringVarP(&LogOutput, "log-output", "", "", `Comma separated list of components that should produce debug output, possible values:
+	RootCommand.PersistentFlags().StringVarP(&LogOutput, "log-output", "", "", `Comma separated list of components that should produce debug output (see 'dlv help log')`)
-	debugger	Log debugger commands
+	RootCommand.PersistentFlags().StringVarP(&LogDest, "log-dest", "", "", "Writes logs to the specified file or file descriptor (see 'dlv help log').")
-	gdbwire		Log connection to gdbserial backend
-	lldbout		Copy output from debugserver/lldb to standard output
-	debuglineerr	Log recoverable errors reading .debug_line
-	rpc		Log all RPC messages
-	fncall		Log function call protocol
-	minidump	Log minidump loading
-Defaults to "debugger" when logging is enabled with --log.`)
-	RootCommand.PersistentFlags().StringVarP(&LogDest, "log-dest", "", "", "Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the \"API listening\" message in headless mode.")
 
 	RootCommand.PersistentFlags().BoolVarP(&Headless, "headless", "", false, "Run debug server only, in headless mode.")
-	RootCommand.PersistentFlags().BoolVarP(&AcceptMulti, "accept-multiclient", "", false, "Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.")
+	RootCommand.PersistentFlags().BoolVarP(&AcceptMulti, "accept-multiclient", "", false, "Allows a headless server to accept multiple client connections.")
 	RootCommand.PersistentFlags().IntVar(&APIVersion, "api-version", 1, "Selects API version when headless.")
 	RootCommand.PersistentFlags().StringVar(&InitFile, "init", "", "Init file, executed by the terminal client.")
 	RootCommand.PersistentFlags().StringVar(&BuildFlags, "build-flags", buildFlagsDefault, "Build flags, to be passed to the compiler.")
 	RootCommand.PersistentFlags().StringVar(&WorkingDir, "wd", ".", "Working directory for running the program.")
-	RootCommand.PersistentFlags().StringVar(&Backend, "backend", "default", `Backend selection:
-	default		Uses lldb on macOS, native everywhere else.
-	native		Native backend.
-	lldb		Uses lldb-server or debugserver.
-	rr		Uses mozilla rr (https://github.com/mozilla/rr).
-`)
 	RootCommand.PersistentFlags().BoolVarP(&CheckGoVersion, "check-go-version", "", true, "Checks that the version of Go in use is compatible with Delve.")
+	RootCommand.PersistentFlags().StringVar(&Backend, "backend", "default", `Backend selection (see 'dlv help backend').`)
 
 	// 'attach' subcommand.
 	attachCommand := &cobra.Command{
@@ -299,6 +286,47 @@ https://github.com/mozilla/rr
 		RootCommand.AddCommand(replayCommand)
 	}
 
+	RootCommand.AddCommand(&cobra.Command{
+		Use:   "backend",
+		Short: "Help about the --backend flag.",
+		Long: `The --backend flag specifies which backend should be used, possible values
+are:
+
+	default		Uses lldb on macOS, native everywhere else.
+	native		Native backend.
+	lldb		Uses lldb-server or debugserver.
+	rr		Uses mozilla rr (https://github.com/mozilla/rr).
+
+`})
+
+	RootCommand.AddCommand(&cobra.Command{
+		Use:   "log",
+		Short: "Help about logging flags.",
+		Long: `Logging can be enabled by specifying the --log flag and using the
+--log-output flag to select which components should produce logs.
+
+The argument of --log-output must be a comma separated list of component
+names selected from this list:
+
+
+	debugger	Log debugger commands
+	gdbwire		Log connection to gdbserial backend
+	lldbout		Copy output from debugserver/lldb to standard output
+	debuglineerr	Log recoverable errors reading .debug_line
+	rpc		Log all RPC messages
+	fncall		Log function call protocol
+	minidump	Log minidump loading
+
+Additionally --log-dest can be used to specify where the logs should be
+written. 
+If the argument is a number it will be interpreted as a file descriptor,
+otherwise as a file path.
+This option will also redirect the \"API listening\" message in headless
+mode.
+
+`,
+	})
+
 	RootCommand.DisableAutoGenTag = true
 
 	return RootCommand

cmd/dlv/dlv_test.go

@@ -22,7 +22,6 @@ import (
 	protest "github.com/go-delve/delve/pkg/proc/test"
 	"github.com/go-delve/delve/pkg/terminal"
 	"github.com/go-delve/delve/service/rpc2"
-	"github.com/spf13/cobra/doc"
 
 	"golang.org/x/tools/go/packages"
 )
@@ -286,7 +285,7 @@ func TestGeneratedDoc(t *testing.T) {
 	tempDir, err := ioutil.TempDir(os.TempDir(), "test-gen-doc")
 	assertNoError(err, t, "TempDir")
 	defer cmds.SafeRemoveAll(tempDir)
-	doc.GenMarkdownTree(cmds.New(true), tempDir)
+	exec.Command("go", "run", "scripts/gen-usage-docs.go", tempDir).Run()
 	entries, err := ioutil.ReadDir(tempDir)
 	assertNoError(err, t, "ReadDir")
 	for _, doc := range entries {

scripts/gen-cli-docs.go

@@ -11,7 +11,7 @@ import (
 )
 
 func main() {
-	fh, err := os.Create(os.ExpandEnv("$GOPATH/src/github.com/go-delve/delve/Documentation/cli/README.md"))
+	fh, err := os.Create(os.ExpandEnv("./Documentation/cli/README.md"))
 	if err != nil {
 		log.Fatalf("could not create README.md: %v", err)
 	}

scripts/gen-usage-docs.go

@@ -3,10 +3,35 @@
 package main
 
 import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+
 	"github.com/go-delve/delve/cmd/dlv/cmds"
 	"github.com/spf13/cobra/doc"
 )
 
+const defaultUsageDir = "./Documentation/usage"
+
 func main() {
-	doc.GenMarkdownTree(cmds.New(true), "./Documentation/usage")
+	usageDir := defaultUsageDir
+	if len(os.Args) > 1 {
+		usageDir = os.Args[1]
+	}
+	root := cmds.New(true)
+	doc.GenMarkdownTree(root, usageDir)
+	// GenMarkdownTree ignores additional help topic commands, so we have to do this manually
+	for _, cmd := range root.Commands() {
+		if cmd.Run == nil {
+			doc.GenMarkdownTree(cmd, usageDir)
+		}
+	}
+	fh, err := os.OpenFile(filepath.Join(usageDir, "dlv.md"), os.O_APPEND|os.O_WRONLY, 0)
+	if err != nil {
+		log.Fatalf("appending to dlv.md: %v", err)
+	}
+	defer fh.Close()
+	fmt.Fprintln(fh, "* [dlv log](dlv_log.md)\t - Help about logging flags")
+	fmt.Fprintln(fh, "* [dlv backend](dlv_backend.md)\t - Help about the `--backend` flag")
 }