Small thing: Consider ergonomics of customizing usage help

[lread]

Issue

I often like to customize usage help.

I goes something like so:

I write my own customized opts->table as a replacement for babashka cli's version.
Details are unimportant, but an example:

(defn- opts->table
  "Customized bb cli opts->table for cljdoc"
  [{:keys [spec order]}]
  (mapv (fn [[long-opt {:keys [alias default default-desc desc extra-desc ref require]}]]
          (let [alias (when alias
                        (str (kw-opt->cli-opt alias)))
                option (kw-opt->cli-opt long-opt)
                default-shown (or default-desc
                                  default)
                attribute (or (when require "*required*")
                              default-shown)
                desc-shown (cond-> [(if attribute
                                      (str desc " [" attribute "]")
                                      desc)]
                             extra-desc (into extra-desc))]
            [(str (when alias (str alias ", "))
                  option
                  (when ref (str " " ref)))
             (string/join "\n " desc-shown)]))
        (let [order (or order (keys spec))]
          (map (fn [k] [k (spec k)]) order))))

To use this customization, I also need to replace format-opts:

(defn format-opts
  "Customized bb cli format-opts for cljdoc"
  [{:as cfg}]
  (cli/format-table {:rows (opts->table cfg) :indent 1}))

I'm feeling we could do a little something here.

Option 0: Do nothing

Things are OK as is.

Option 1: Document only

The docs do currently give an example of using format-table with opts->table as an alternative to format-opts. Maybe elaborate on how one might use a custom opts->table.

Option 2: Add :opts->table-fn option to format-opts

The only real reason I'm overriding format-opts is to call my custom opts->table.

It might be nice to have format-opts accept an optional :opts->table-fn in its config map.

Proposal

Perhaps my usage is niche, but I find myself overriding opts->table often.
So, for me, option 2 seemed to make sense, but on reflection, maybe it is a bit silly to avoid bringing in such a simple small bit of code.

I'm thinking maybe option 1 makes sense.

Whaddya think?

[borkdude]

A fourth option might be to include the functionality you might need in opts->table?

[lread]

If I understand what you are saying, that's what I currently do.
I write a custom opts->table.

Maybe option 1: document only? With a wee example.

[borkdude]

What I mean: include options so you don't have to write a custom function at all?

[lread]

Oh.... I see watcha mean.

I'll make a TODO to review the reasons why I decided I needed custom opts->table implementations.