Support help-echo for Transient infix arguments

[kickingvegas]

Enhancement Request

Support messaging a help/doc string for Transient infix arguments.

To my knowledge, infix arguments do not support having a help or docstring attribute. Rather Transient makes the assumption that the argument corresponds to a command line tool option that is documented with an installed man page.

A desired enhancement would be to have both short and long docstring support for infix arguments. The short docstring could be messaged in the minibuffer upon an event such as a mouse-over. The longer docstring could be loaded into a help buffer that is invoked by the key sequence ? {argument binding}.

If existing functionality can achieve the behavior described above, please provide guidance.

[tarsius]

Support messaging a help/doc string for prefix arguments.

Are you talking about Transient's infix arguments or Emacs' regular old universal (aka prefix) arguments?

[kickingvegas]

To clarify, yes, I’m talking about Transient infix arguments. Will amend wording. To clarify, in the example below given the infix argument --beginning, how can I attach a docstring to it?

(transient-define-prefix casual-fin-irr-menu ()
  "Casual internal rate of return menu.
\nMenu with argument support for the following functions:
- `casual--fin-irr'"
  ["Internal Rate of Return for Irregular Payments"
   ["Parameters"
    ("b" "Beginning" "--beginning")]]

  [("i" "Internal Rate of Return (1:)" casual--fin-irr :transient nil)]

  [:class transient-row
          ("C-g" "‹Back" ignore :transient transient--do-return)
          ("q" "Dismiss" ignore :transient transient--do-exit)
          ("U" "Undo Stack" calc-undo :transient t)])

[tarsius]

The short docstring could be messaged in the minibuffer upon an event such as a mouse-over.

There isn't any support for this, the reasoning being that the information that is always shown in the menu should be more descriptive than the "Beginning" in your example. And when that is not enough, which shouldn't happen a lot, additional information could be displayed in a separate buffer, using C-h <key> (i.e., what you call the "longer docstring").

I'll think about adding support for such "longer, but still fits on a line" documentation that is shown when hovering with the mouse and/or when moving through the menu using key bindings.

The longer docstring could be loaded into a help buffer that is invoked by the key sequence ?

That already exists. There's documentation about it, but the quickest way to learn what is supported, is to look at the transient-show-help methods. (This information is shown using C-h <key that would normally invoke this suffix>, if you are not familiar with this already, try it in Magit first.)

[tarsius]

In short you would have to use :show-help (lambda () (message "the help")), which of course is less convenient than, say, :help-echo "the help".

But transient-show-help is a generic function for a reason. You could add your own infix class, which adds the help-echo slot, and add a method, which just displays that, in whatever way you prefer.

Then you would have to use :class my-class :help-echo "...", which still would be inconvenient, I suppose. However, you might end up having to define infix arguments outside the prefix definition for other reasons anyway (using transient-define-infix/argument), at which point this shouldn't matter much anymore.

[kickingvegas]

All good, I guess I'll need to write more descriptive infix :description values.