Work on help formatting

[CFiggers]

I've been tweaking cmd's help message formatting for use in my Janet-native project templating CLI utility, Juno. Here's some before/after comparisons:

Before, cmd/group	After, cmd/group

Before, cmd/fn	After, cmd/fn

To accomplish this, I've made passing a table or struct in the docstring position legal so that I can pass in an :epilogue key.

(cmd/group 
    {:doc (string/format
      ``
      Juno v%s
      
      Usage: juno <subcommand> {positional arguments} [options] 
      
        A simple CLI tool for creating new project directories. Defaults to a basic Janet project.
      ``
      version)
     :epilogue 
      ``
      General options:
      
        -h, --help   Print command-specific usage
      
      Examples:
      
        $ juno new new-project-name
        $ juno new template new-project-name
        $ juno joke
      
      ``}
      joke handle-joke
      license handle-license
      new handle-new
      config handle-configure)

For style cues, I've been taking inspiration from other CLI tools that seem well done to me. I like the GitHib CLI (gh) and certain parts of the zig compiler (though, not every branch of their help tree is documented consistently).

[ianthehenry]

Hey! I'm traveling this week so not super responsive.

Oh the newline in the usage for cmd/fn is clearly terrible... that's a very good improvement. I should just fix that; looks like a bug to me.

How are you determining the wrap width? I seem to recall that I just hardcoded 80 columns because I didn't want to shell out to tput and couldn't find a decent native way to get that. Although janet definitely knows it, for its own repl... I wonder if I could just expose that somewhere.

I prefer the bulleted style for lists to the hanging indent style, but I'm not sure why I used - in one place and : in another (maybe that's what OCaml's Command does? I don't remember off the top of my head). I think it would be reasonable to control those with a dynamic variable (and then you could use e.g. "" for the initial and " " for subsequent lines, instead of "- " initially and " " on subsequent lines to get hanging indent.

I think taking a struct of doc/epilogue ("postdoc"? :) is nice and provides a nice place to stick other things -- e.g. options to suppress or alter the default help generation maybe.

I like the usage section; it would be neat if individual commands could define their own (checked!) example invocations and then cmd/group would just print all of the examples from its child commands. Though then you don't have much control over the order... hmm.