The additional help topics were really hard to ever get to show. The
required conditionals were difficult to meet and did not seem to really
be logical.
Problems I see:
1) the top level command could never have additional topics.
2) you must have at least one sibling command AND one subcommand
3) we had the AND above, but then test both conditionals a second time
4) if the sub command was runnable we wouldn't print anything
5) if the sibling commands were not runnable we wouldn't print anything
4+5) it's possible that we printed "Additional help topics:" with nothing following it
6) We always printed ourselves as a sibling in the additional info
Whew, I think I fixed all of those! Again, using
https://github.com/eparis/readable-golang-template
I'm actually able to visualize the template and see this craziness.
The conditionals BEFORE this change:
{{if .HasParent}}
{{if and (gt .Commands 0) (gt .Parent.Commands 1) }}
Additional help topics:
{{if gt .Commands 0 }}
{{range .Commands}}
{{if not .Runnable}}
{{rpad .CommandPath .CommandPathPadding}} {{.Short}}
{{end}}
{{end}}
{{end}}
{{if gt .Parent.Commands 1 }}
{{range .Parent.Commands}}
{{if .Runnable}}
{{if not (eq .Name $cmd.Name) }}
{{end}}
{{rpad .CommandPath .CommandPathPadding}} {{.Short}}
{{end}}
{{end}}
{{end}}
{{end}}
{{end}}
The conditionals AFTER this change:
{{if or (.HasHelpSubCommands) (.HasRunnableSiblings)}}
Additional help topics:
{{if .HasHelpSubCommands}}
{{range .Commands}}
{{if not .Runnable}}
{{rpad .CommandPath .CommandPathPadding}} {{.Short}}
{{end}}
{{end}}
{{end}}
{{if .HasRunnableSiblings }}
{{range .Parent.Commands}}
{{if .Runnable}}
{{if not (eq .Name $cmd.Name) }}
{{rpad .CommandPath .CommandPathPadding}} {{.Short}}
{{end}}
{{end}}
{{end}}
{{end}}
{{end}}
I wrote https://github.com/eparis/readable-golang-template which
converts golang templates into something structured around the
conditionals. Obviously you can't just USE the output, but you can SEE
the problems. In this case the output shows something like:
{{if .HasParent}}
{{if and (gt .Commands 0) (gt .Parent.Commands 1) }}
Additional help topics:
{{if gt .Commands 0 }}
{{range .Commands}}
{{if not .Runnable}}
{{rpad .CommandPath .CommandPathPadding}} {{.Short}}
{{end}}
{{end}}
{{end}}
{{if gt .Parent.Commands 1 }}
{{range .Parent.Commands}}
{{if .Runnable}}
{{if not (eq .Name $cmd.Name) }}
{{end}}
{{rpad .CommandPath .CommandPathPadding}} {{.Short}}
{{end}}
{{end}}
{{end}}
{{end}}
{{end}}
We have a completely unused "{{if not (eq .Name $cmd.Name) }}"
Move the {{end}} after the {{rpad...}}
If the command has not set an output explicitly everything will go to
stderr. This makes a lot of sense, but is a huge PITA for people who
want to be able to grep the help output. It is very common for users to
want to do
command --help | grep flag
This patch fixes that by default help output (but not error output like
an invalid command) to stdout instead of defaulting to stderr.
Eric Paris