Towards a more flexible help output

[mickael-menu]

Not an issue per se, but I'm opening a discussion to gather ideas on how we could work towards a more flexible help output from Kong.

While Kong's default help output is elegant and fits most use cases, there's a need for more customization. The most recent example being HelpOptions.FlagsLast. Besides minor (but increasing maintenance burden) tweaks like this one, I can think of other changes which would be quite disruptive:

• translating the help output
• injecting additional help sections, for example the "additional help topics" section in Mercurial's hg --help
• adding color codes to format the output

An app is free to use Help(HelpFunc) to fully customize the output, but that means forgoing all the heavy lifting the default help printer provides.

Let's explore some possibilities.

Internationalization

Enabling i18n in Kong would be useful to cater for an international audience, but it should also enable overriding the default English strings such as:

• Commands:
• Run "app <command> --help" for more information on a command.
• Show context-sensitive help.

I don't have much experience in this area in Go, but it looks like the standard x/text/message package provides the tooling for this.

Template

A great way to provide a lot of flexibility would be to use templates instead of hard-coding the help structure in the help printer. This is also the solution Cobra opted for by offering a SetHelpTemplate() API.

Go has a native text/template package for this use case.

Discussing a potential template structure could be its own issue. But here are a few examples enabled by templating:

• the writeTwoColumns() function could be exposed as a columns template function cutting the input text at a particular delimiter (\t being a good candidate) and ignoring empty lines
• formatting could be handled systematically in the template (uppercase, color codes, : suffixes, etc.)

Different levels of details

Sometimes we need more compact help output:

• some apps show a compact output when using -h versus --help
• UsageOnError could benefit from displaying much less content

Using templates would help with this, by providing one template per details level, without modifying the printer logic.

Shipped as another package?

If these new dependencies are unwanted for the basic config, all of this could be shipped as a "plug-in" package which would expose a HelpFunc implementation to replace the default one.

[alecthomas]

(moved the issue to Discussions, which I had forgotten to enable)

Kingpin uses the text/template approach, and this is actually also why Kong explicitly has a public abstract data model - so that it could be used for such a purpose. In fact, Kingpin uses this system for writing completion templates, among other things. It doesn't have one yet because I wanted to keep Kong's core lean while I was building it out, but now that it is mostly stable it could be a good time to add it.

If you'd like to take a crack at this, it would be most welcome. A couple of things to think about:

1. It is likely that custom templates will want to be able to pass in extra template functions and variables.
2. The generated help should be able to accept a kong.Context so that it can display context-sensitive help. eg. exe cmd subcommand should display context-sensitive help on subcommand.

[mickael-menu]

Thanks for the insights, happy to hear that this was taken into account from the start.

I'm not sure I'll have the bandwidth to tackle this at the moment, but I will need it soonish and will be happy to participate in the effort. I saw that you used a fork of text/template in Kingpin, but it looks like the latest official version supports whitespace elision so I guess we could stick with it.

[alecthomas]

A possible interface would be to provide a function something like this:

// TemplatedHelpPrinter uses text/template to provide help formatting.
//
// The root of the template context is kong.Context.
func TemplatedHelpPrinter(template string, extraCtx interface{}, funcs template.FuncMap) HelpPrinter

You might also want to use functional options for this instead of the above, just to allow future expansion if necessary.

[alecthomas]

I've had a bit of a crack at this and it reminded me why I didn't replicate template-based help originally. It's really not trivial to make templates + template functions that support wrapping, columns, and so on. I think perhaps a better approach might be to just expose more of the help-based helper functions that already exist as private functions in Kong.

[jaco-codexorbis]

What may be useful is to extract or transform the available data in Application to a help/info oriented data structure. This help structure may be passed to a HelpWriterer interface.

A default HelpWriter can be created based on the structure but more specialised approaches may be implemented for any of the helper help functions or even a full HelpWriterer.

[alecthomas]

I'm not sure what this would look like in practice, what did you have in mind?

I would imagine that transforming the data model to something more help-oriented is the purpose of the help formatters really, given that depending on what help output users want, that help-oriented form could be completely different.

[alecthomas]

I'm leaning towards making no significant change here beyond maybe just exposing some helper functions to make writing help a bit simpler for users. Thoughts?

[mickael-menu]

I think that would fit the bill too. Ideally we would be able to plug in at different granularity levels in the formatting while falling back on the default implementation for the rest.

Maybe we should start by listing the customizing points that an app may need? I can think of:

1. Fine-tune changes
   1. translating the default help messages
   2. change a default string
      • e.g. usage %s instead of Usage: %s or Options instead of Flags
   3. customizing the formatting of a flag
      • e.g. \033[1;33m--title\033[0m <title> instead of --title=TITLE
   4. customizing the formatting of group titles
      • e.g. FLAGS instead of Flags:
   5. customizing the usage for a particular command:
      • e.g.git commit [<options>] [--] <pathspec>... instead of git commit <path> ...
2. Formatting changes
   1. Change the wrapping column and rules
      • HelpOptions.NoDocToText help text wrapping option #140 Disable text wrapping and honor user provided newlines
   2. Set the indent length
   3. Columnize arbitrary help sections
3. Structural changes
   1. Reorder help (sub-)sections
      • Help Option to position flags in help output #136 Print flags after the commands
      • Print flag groups in reverse order (have parent flags after children's)
   2. Insert custom help sections
      • e.g. the "additional help topics" section in Mercurial's hg --help
   3. Customize or remove the help footer/header
      • e.g. Run "git <command> --help" for more information on a command.
   4. Print arbitrary content between any help section.
   5. Changing the overarching formatting rules depending on current context (command, error, etc.), e.g.
      • options: Add kong.ShortUsageOnError() option #143 display short usage on error
      • display a footer or skip some groups for a particular command

@jaco-codexorbis's proposal of having an intermediary help data structure would help for this I think. Not something that tie the app to a particular help structure, but just to have a readily access to help's metadata. I'll write more ideas about this later.