`delta --help | less` reveals the coloring escape sequences

[ghost]

The options in the FLAGS and OPTIONS sections are colored with escape sequences even when the output is not a terminal, and this results in some garbage on the screen.

[tpoliaw]

Not sure if it's intentional behaviour or not but you can use less -R to show colours in less. If you set LESS='-R' (in .bashrc or similar) it will show colour by default.

[ghost]

Thanks, @tpoliaw ! Most people don't know about this option (or any less option), though. Also, less is not the only thing one might want to pipe to. grep comes to mind. If the string I want to find in the quite long help output happens to have color sequences in it, it won't show up:

% delta --help | grep -C4 'default: raw'
%

Even ls, which is usually used with color enabled, has its help (pretty long, like delta's) in black and white.

[tpoliaw]

Absolutely, I think it would be better to only output colour if stdout is a tty. It was just a workaround for now to let less work.

I might have a look at a PR to change this if @dandavison hasn't already got ideas or is against it.

[tpoliaw]

Looking at this, structopt defaults to only use colours for a tty and it's been explicitly set to always use colour here. I'll hold off the PR for now as it looks like a deliberate choice.

[dandavison]

Hi @lepotic, @tpoliaw you're right, I'm guilty here! I did deliberately set the help text to always be coloured. I did that because I wanted the colours to be present when I'm viewing the help text and, because the help text is long, I wanted to pipe it to less. I.e. I didn't like the alternative of allowing it to dump all the coloured output to the screen and then scrolling upwards to find what I wanted. I do see that of the other Rust CLIs rg, bat, and exa, none of them do what delta is doing.

@tpoliaw it's always been in the back of my mind that the ideal would be for delta to automatically pipe its help text to less (when stdout is a tty) just like delta does with its normal output (again, when stdout is a tty). However, I've never looked into whether that is achievable with structopt. If you agree that that would be a good alternative and felt like investigating, that would be fantastic. A quick skim of the structopt/clap docs led me to https://docs.rs/clap/2.33.3/clap/struct.App.html#method.write_long_help which looks superficially like it could be used to write into a writer object with paging, i.e. such as delta creates here https://github.com/dandavison/delta/blob/feb89ac4387524c7ab571065cec7a190d1917f16/src/main.rs#L85-L86 and also in the show_themes and show_syntax_themes functions in the same file. But I can also imagine that we might run into problems and feel like we're fighting against clap, by trying to get --help to behave differently.

There's a tangentially related issue that it would be nice if -h showed a brief summary of options and --help the full text, and it appears that this is also possible with structopt https://docs.rs/structopt/0.3.21/structopt/#help-messages This is issue https://github.com/dandavison/delta/issues/377

[tpoliaw]

the ideal would be for delta to automatically pipe its help text to less

That could work. It's not what I'd generally expect from a help command but I can't see it being a bad thing. While many commands don't do it, there are several that do open less. less itself opens its help in itself, whereas the various git subcommands delegate to man to open their man page which in turn delegates to less, eg git log --help is equivalent to man git-log.

Looking into how man shows formatting, it overrides user settings and sets LESS to '-ix8Rm' + a whole load of prompt logic (which I had no idea less could do) + the user's original $LESS. Maybe something like that would be the way to go for delta to ensure that the right flags are set. Is less ubiquitous enough to assume that every *nix(ish) system has it?

I'll have a look when I get a chance. I'm doing some other stuff using structopt at the minute so I imagine I'm going to be spending some quality time reading through all their docs anyway.

[dandavison]

That would be great, and thanks for thinking about it.

Is less ubiquitous enough to assume that every *nix(ish) system has it?

Yes, I think we can assume that every delta user has less installed. Even on Windows, I believe the common way people install git involves git bundling a less binary, and I'm OK assuming that delta usage is very closely related to git usage.

[c0dev0id]

I also came here to either ask for a manpage or a help output that I can read in a pager like less. Some tools provide --help and --long-help, this would be nice here as well.

[dandavison]

I also came here to either ask for a manpage or a help output that I can read in a pager like less.

Hi @c0dev0id, that exists! It's delta --help. It includes color to make the output more readable, so when piping to less you must include the -R flag.

I am interested in making a short help version -h and long help --help, like ripgrep does, and I'm interested in having delta's help page automatically. (@tpoliaw did you learn anything about how one would achieve that with structopt?)

Most people don't know about this option (or any less option), though.

I think I'm going to push back slightly here. delta is a tool for programmers, so it's OK to assume a slightly higher level of sophistication. If people didn't know it before, then the -R flag is definitely a good one to learn.

For grep, you can use ansifilter to remove colours, but I certainly agree that's a bit convoluted. I would say personally that piping into less -R and using the search facilities in less is going to be a better experience than grepping help output.

I think delta's manual (i.e. --help) would be much less readable without colour:

[c0dev0id]

I think you focused at wrong part of the sentence.

...or a help output that I can read in a pager like less.

EDIT: Okay... the blame is on my side... I read too short and didn't know about less -R. That works.

[zachriggle]

Agree with @dandavison -- especially since 99% of the functionality of delta is to add color to things, it doesn't make sense to NOT print colors when being piped somewhere.

@c0dev0id If I can suggest some more settings, I use the following flags

export LESS='--quit-if-one-screen --ignore-case --LONG-PROMPT --RAW-CONTROL-CHARS --chop-long-lines --no-init --window -4 --jump-target=.5'

Where -R is equivalent to --RAW-CONTROL-CHARS.