Proposal: Formatted and Paginated Help

[rads]

Features

• When using a terminal, add ANSI escape codes for bold and underlined text (particularly useful for Usage text)
• When using a terminal, pipe help output to --pager/$PAGER//usr/bin/less -is (disabled in Windows?)
• When --pager is set and falsy, disable pager

Docs from man man

-P  pager
              Specify which pager to use.  This option overrides the MANPAGER environment variable, which in turn overrides the
              PAGER variable.  By default, man uses /usr/bin/less -is.

Example (final formatting TBD)

[borkdude]

Are there any other tools that do this? Why not let the user do the piping? What if the user pipes the output to a file, then we should not emit ansi escape codes. Should we write a man page instead?

Also see babashka/babashka#1299

[rads]

@borkdude:

Are there any other tools that do this?

I did a quick survey on my machine and to my surprise the only command I could find that did this was less --help. 😆 So you have a point there. That said, if we in the Clojure community were to extract the ANSI colors and pagination into a small library and set a standard so that any CLI tool could work consistently like this out-of-the-box, it seems like that would be a good thing.

To put things in perspective, this isn't a huge priority for me, because I know there are other important things we can solve instead. No need to worry about this too much if you disagree with what I'm saying here, but I at least wanted to share my feelings about it. I would rank the ANSI formatting higher than the pagination since the ANSI formatting requires us as implementors to specify where the formatting should be. In contrast the pagination can be filled in by the user.

Why not let the user do the piping?

The best user experience should be the default. I think in practice most people would appreciate it if these things just worked out-of-the-box. Key word here being default, since it would still be possible to opt-out.

What if the user pipes the output to a file, then we should not emit ansi escape codes.

Yeah, I think this is doable. In contrast to the pagination behavior, I was able to find a couple examples of modern tools with colorized help (bun, docker). When I pipe the help output of these tools to a file, the ANSI codes are removed as expected.

Should we write a man page instead?

I think the man pages would be in a different format from the --help text, right? The problem is writing and formatting docs is pretty time consuming so I want to stay away from duplicating any efforts there, especially given our limited dev time.

[borkdude]

I don't think adding paginated help is something we should do: it would complicate things too much imo.

[rads]

@borkdude: Understood. Does that mean ANSI formatting is still on the table? If so I'll make a placeholder issue just for that, otherwise I will just move on to other stuff.

[borkdude]

I think we should first solve babashka/babashka#1299 before we can reliably do ANSI.

[borkdude]

IMO it's not that important, but feel free to create an issue for it.

[rads]

Sounds good. I agree that the issue you linked higher priority.