Show command help in $PAGER or less #3434

mrinalwadhwa · 2022-09-07T09:23:01Z

Currently:

We have many help commands that show a long help, for example ockam secure-channel --help. This hides the command syntax above the fold.

Desired:

Detect if $PAGER is set, if so invoke that and send all help output to it.
If $PAGER is not set, default to less

We love helping new contributors!
If you have questions or need help as you work on your first Ockam contribution, please leave a comment on this discussion.
If you're looking for other issues to contribute to, checkout this discussion and labels - good first issue or help wanted

The text was updated successfully, but these errors were encountered:

phillyphil91 · 2022-09-09T14:50:25Z

Hey, i would like to take a look at this, as a first contribution. I am not entirely sure, I understand the details fully though.
At what stage should the check for $PAGER happen? And once that's set to less instead of the normal display of the help commands, this should be "routed" as input to less ?

Edit: Found HELP_DETAIL or rather the place where help::template etc. is defined

phillyphil91 · 2022-09-09T19:11:52Z

In general it looks like only man uses the $MANPAGER or $PAGER env. So I guess I would have to find a way for the help output to use the tools specified by those ENVs as well. I can take a look if clap allows this or if there is any other way to do this.
If I'm going off into the wrong direction, please let me know.

mrinalwadhwa · 2022-09-09T19:49:20Z

@phillyphil91 thank you for spending time on this.
I think that is right direction.
We need to find a way in clap to override where the output goes.

mrinalwadhwa · 2022-09-09T19:52:30Z

The clap community has a friendly discussions page here https://github.com/clap-rs/clap/discussions so asking there for some guidance might be helpful as well.

phillyphil91 · 2022-09-09T20:02:46Z

The clap community has a friendly discussions page here https://github.com/clap-rs/clap/discussions so asking there for some guidance might be helpful as well.

Good idea. I will have a look there.

@phillyphil91 thank you for spending time on this. I think that is right direction. We need to find a way in clap to override where the output goes.

Clap allows you to write to stdout or to a io::Write object.

The problem then still is how to get this into less for example. Maybe it would be easier to just allow the user to do ockam secure-channel --help | less if they want to. But i will have another look.

mrinalwadhwa · 2022-09-09T20:05:59Z

I was thinking if we can capture the help output, then maybe we can execute echo "$output" | less in a subprocess

phillyphil91 · 2022-09-09T20:16:07Z

i was thinking the same, but was not able to get anything meaningful working yet. I'll have another look at spawning (sub)processes. Thanks

phillyphil91 · 2022-09-10T10:07:25Z

I found something that allows you to open a sub-process for example for less (How to run ‘less’ command for command line application) and wait until the sub-process exits but the question is if it's possible run this as a custom function or something if the help command is used. Disabling the help sub command is possible in clap but then help would have to be implemented ourselves alongside clap, which would mean help::template etc. could not be used.

But I opened a question in the clap forum to see if they have any idea: clap-rs/clap#4200

phillyphil91 · 2022-09-11T18:18:26Z

So according to clap-rs/clap#4201, using a pager for the help output is currently being investigated by the clap team. So maybe this issue can be closed until further advancement is done on their side? Or are there any other suggestions?

mrinalwadhwa · 2022-09-11T19:23:51Z

@phillyphil91 Thank you for exploring this and engaging with the Clap community on that thread. I'll leave the issue open so we remember to come back to it.

In the meantime, maybe we should invest effort in making -h and --help should short and long help respectively. I feel this distinction is hard to discover for new users.

epage · 2022-09-12T21:33:36Z

In the meantime, maybe we should invest effort in making -h and --help should short and long help respectively. I feel this distinction is hard to discover for new users.

In clap v4 (working on wrapping up the final documentation for it), we've updated the help output in hopes to reduce confusion on this. See clap-rs/clap#4159

mrinalwadhwa · 2022-09-14T06:33:18Z

@epage Thank you for that context. clap v4 sounds exciting, looking forward to upgrading to it!

phillyphil91 · 2022-09-15T14:01:06Z

@phillyphil91 Thank you for exploring this and engaging with the Clap community on that thread. I'll leave the issue open so we remember to come back to it.

In the meantime, maybe we should invest effort in making -h and --help should short and long help respectively. I feel this distinction is hard to discover for new users.

So create different help messages according to if -h or --help was used?

And the -h one would only show the most important help info for the command and maybe refer to --help for a more detailed one. Or what were you thinking? @mrinalwadhwa

mrinalwadhwa · 2022-09-15T15:30:18Z

@phillyphil91 that's exactly what I was thinking. We maybe able to control it with a help_template or long_help related options in clap.

epage · 2022-09-15T15:35:10Z

If you want, with arg.help and arg.long_help, you can get the clap v4 behavior today.

If you aren't defining your own help, it can most likely work by doing something like cmd.mut_arg("help", |arg| arg.help("...").long_help("..."))

cailloumajor · 2022-09-16T06:08:16Z

Hello, maybe it can help, the great https://github.com/sharkdp/bat tool automatically (I guess it is configurable) uses pager if output is too long.

mrinalwadhwa · 2022-09-16T06:40:50Z

@cailloumajor 👋 If you have thoughts / ideas on how this could work until clap has it baked in. We'd love to learn more / explore them with you.

epage · 2022-09-16T12:19:20Z

Some pre-built pager options

bat though I'm unsure if there how heavy weight it is just for a help pager
minus is focused on being a pager library and has feature flags to trim things down
pager works by forking your process so any output is automatically sent to an external pager. You need to make sure you do any terminal capability detection before the fork occurs
- If colored help is enabled, do the detection yourself and pass it into Command::color
- If wrap_help is enabled, call terminal_size directly and pass that into Command::term_width
- Hmm, doesn't look like this handles quoted strings correctly

If you go the route of writing your own pager, I've compared different pager implementations for my experiment with a git tool and to prepare for integrating a pager into clap.

phillyphil91 · 2022-09-16T18:33:01Z

If you want, with arg.help and arg.long_help, you can get the clap v4 behavior today.

If you aren't defining your own help, it can most likely work by doing something like cmd.mut_arg("help", |arg| arg.help("...").long_help("..."))

but help and long_help only exists for arguments right? not for commands or subcommands. I can't set those for running subcommands like ockam secure-channel --help for example?

or would that be achievable via
cmd.mut_arg("help", |arg| arg.help("...").long_help("..."))?

epage · 2022-09-16T18:51:54Z

If you want the clap v4 behavior where the description for -h, --help adapts a hint per shot or long help, yes, you could call mut_arg on each Command to set that up.

ripgrep and bat take a different approach where they put it in either the command's about and long_about or in after_help and after_long_help.

phillyphil91 · 2022-09-17T09:58:55Z

Sorry for being so persistent about this. But here is what I tried doing from my understanding (see mut_arg:

But this "only" changes the description of the -h and --help flag:

And:

But what I was hoping to do is have the actual behavior of the entire help messages that's printed adjust to -h vs --help
So e.g. -h would show:

And --help would show the same plus the whole about + examples etc:

I'm not really sure if that is achievable. Allow the user for a short help message with -h and a longer one with examples etc. with --help .
As you can see help_template is being used and I also wonder if that can be set for whether the short or long help argument was used.

epage · 2022-09-17T23:51:35Z

I think what you are wanting to set is after_long_help. That will allow you to add text after the auto-generated help content but only for --help / help subcommand.

hargut · 2022-10-08T13:02:51Z

The above PR implements the approach of using after_long_help which I do think is a good start to address this topic. Nevertheless it is another solution as the requested $PAGER usage.

Personally I'm not a fan of using pagers as default in help, as it typically requires to quit that pager. Most of the time when help is displayed options are either missing, typos or order issues occurred, therefore the short help should be fine for the larger portion of the cases.

hargut · 2022-10-08T17:15:38Z

To address the issue of the early line wraps I've opened a ticket & PR on clap.
clap-rs/clap#4360 # issue
clap-rs/clap#4361 # pr

hargut · 2022-10-09T07:29:07Z

The clap PR was accepted and the version has been updated. This was included in #3622

mariannegoldin · 2023-04-20T20:12:39Z

Hi there! I am working with some new contributors to open source to get them setup on this repo and looking for a good first issue.

Given the update in #3622 - is this issue still open as written?

mrinalwadhwa · 2023-04-20T20:25:58Z

@mariannegoldin yes, we've made progress in breaking out long_about and after_long_help but we don't yet have the ability to show help inside a pager so this is still open.

ockam/implementations/rust/ockam/ockam_command/src/node/create.rs

Lines 54 to 55 in 3227d2a

    
           long_about = docs::about(LONG_ABOUT), 
        
           after_long_help = docs::after_help(AFTER_LONG_HELP)

mariannegoldin · 2023-04-20T20:35:53Z

@mariannegoldin yes, we've made progress in breaking out long_about and after_long_help but we don't yet have the ability to show help inside a pager so this is still open.

ockam/implementations/rust/ockam/ockam_command/src/node/create.rs

Lines 54 to 55 in 3227d2a

long_about = docs::about(LONG_ABOUT),

after_long_help = docs::after_help(AFTER_LONG_HELP)

Thanks much! This will be good context to look at in determining if we are able to take this issue on.

deebrecke · 2023-04-24T22:33:25Z

This is the issue that my team has chosen for our first attempt. We are students and this is our first open-source project. If there is any additional information you can provide for us, we would greatly appreciate it.

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses #3434

mrinalwadhwa · 2023-06-09T10:51:09Z

Landed in #5049
Thank you @i-b-o-t and everyone who helped along the way 🥳

mrinalwadhwa added good first issue help wanted Implementation: Rust Component: Command labels Sep 7, 2022

mrinalwadhwa changed the title ~~Show command help in $PAGER~~ Show command help in $PAGER or less Sep 7, 2022

mrinalwadhwa mentioned this issue Sep 22, 2022

Investigate switch to clap v4.0 #3506

Closed

adrianbenavides added the hacktoberfest Apply to issues you want contributors to help with label Oct 3, 2022

hargut mentioned this issue Oct 8, 2022

chore(rust): ockam_command: unify help #3622

Merged

4 tasks

adrianbenavides linked a pull request Oct 11, 2022 that will close this issue

chore(rust): ockam_command: unify help #3622

Merged

4 tasks

mergify bot closed this as completed in #3622 Oct 12, 2022

mrinalwadhwa reopened this Oct 12, 2022

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 1, 2023

Paginate help texts

9a98b04

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 1, 2023

feat(rust): Paginate help texts

64da7c4

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 2, 2023

feat(rust): Paginate help texts

f8dc883

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

i-b-o-t mentioned this issue Jun 2, 2023

feat(rust): paginate help texts #5049

Merged

4 tasks

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 2, 2023

feat(rust): paginate help texts

adcdd28

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 2, 2023

feat(rust): paginate help texts

784c03a

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 6, 2023

feat(rust): paginate help texts

a716616

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 6, 2023

feat(rust): paginate help texts

4276d23

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 6, 2023

feat(rust): paginate help texts

dbcb242

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 6, 2023

feat(rust): paginate help texts

5e88859

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 6, 2023

feat(rust): paginate help texts

b449d91

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 6, 2023

feat(rust): paginate help texts

e85fda7

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 6, 2023

feat(rust): paginate help texts

62f2cf5

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

i-b-o-t added a commit to i-b-o-t/ockam that referenced this issue Jun 7, 2023

feat(rust): paginate help texts

c34b4e6

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses build-trust#3434

adrianbenavides pushed a commit that referenced this issue Jun 8, 2023

feat(rust): paginate help texts

79bcaf6

using $PAGER if set, defaulting to `less` and falling back to `more` or no pagination if no pager is available. Addresses #3434

mrinalwadhwa closed this as completed Jun 9, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Show command help in $PAGER or less #3434

Show command help in $PAGER or less #3434

mrinalwadhwa commented Sep 7, 2022 •

edited

phillyphil91 commented Sep 9, 2022 •

edited

phillyphil91 commented Sep 9, 2022

mrinalwadhwa commented Sep 9, 2022

mrinalwadhwa commented Sep 9, 2022

phillyphil91 commented Sep 9, 2022

mrinalwadhwa commented Sep 9, 2022

phillyphil91 commented Sep 9, 2022

phillyphil91 commented Sep 10, 2022 •

edited

phillyphil91 commented Sep 11, 2022

mrinalwadhwa commented Sep 11, 2022

epage commented Sep 12, 2022

mrinalwadhwa commented Sep 14, 2022

phillyphil91 commented Sep 15, 2022

mrinalwadhwa commented Sep 15, 2022

epage commented Sep 15, 2022

cailloumajor commented Sep 16, 2022

mrinalwadhwa commented Sep 16, 2022

epage commented Sep 16, 2022 •

edited

phillyphil91 commented Sep 16, 2022 •

edited

epage commented Sep 16, 2022

phillyphil91 commented Sep 17, 2022

epage commented Sep 17, 2022

hargut commented Oct 8, 2022

hargut commented Oct 8, 2022

hargut commented Oct 9, 2022 •

edited

mariannegoldin commented Apr 20, 2023

mrinalwadhwa commented Apr 20, 2023

mariannegoldin commented Apr 20, 2023

deebrecke commented Apr 24, 2023

mrinalwadhwa commented Jun 9, 2023

Show command help in $PAGER or less #3434

Show command help in $PAGER or less #3434

Comments

mrinalwadhwa commented Sep 7, 2022 • edited

Currently:

Desired:

phillyphil91 commented Sep 9, 2022 • edited

phillyphil91 commented Sep 9, 2022

mrinalwadhwa commented Sep 9, 2022

mrinalwadhwa commented Sep 9, 2022

phillyphil91 commented Sep 9, 2022

mrinalwadhwa commented Sep 9, 2022

phillyphil91 commented Sep 9, 2022

phillyphil91 commented Sep 10, 2022 • edited

phillyphil91 commented Sep 11, 2022

mrinalwadhwa commented Sep 11, 2022

epage commented Sep 12, 2022

mrinalwadhwa commented Sep 14, 2022

phillyphil91 commented Sep 15, 2022

mrinalwadhwa commented Sep 15, 2022

epage commented Sep 15, 2022

cailloumajor commented Sep 16, 2022

mrinalwadhwa commented Sep 16, 2022

epage commented Sep 16, 2022 • edited

phillyphil91 commented Sep 16, 2022 • edited

epage commented Sep 16, 2022

phillyphil91 commented Sep 17, 2022

epage commented Sep 17, 2022

hargut commented Oct 8, 2022

hargut commented Oct 8, 2022

hargut commented Oct 9, 2022 • edited

mariannegoldin commented Apr 20, 2023

mrinalwadhwa commented Apr 20, 2023

mariannegoldin commented Apr 20, 2023

deebrecke commented Apr 24, 2023

mrinalwadhwa commented Jun 9, 2023

mrinalwadhwa commented Sep 7, 2022 •

edited

phillyphil91 commented Sep 9, 2022 •

edited

phillyphil91 commented Sep 10, 2022 •

edited

epage commented Sep 16, 2022 •

edited

phillyphil91 commented Sep 16, 2022 •

edited

hargut commented Oct 9, 2022 •

edited