Format help option value as it's own column

[epage]

Issue by polarathene
Wednesday Apr 18, 2018 at 10:24 GMT
Originally opened as clap-rs/clap#1251

---

Rust Version

1.25

Affected Version of clap

2.31.2

Expected Behavior Summary

Ability to align option values into their own column, similar to how the help text is aligned.

OPTIONS:
    -f, --file                    <PATH>        Specify the path to the shared memory file [current: /dev/shm/looking-glass]
    -s, --use-spice                             Disable spice client
    -c, --spice-host              <HOST>        Specify the spice host [current: 127.0.0.1] [default: 127.0.0.1]
    -p, --spice-port              <PORT>        Specify the spice port [current: 5900] [default: 5900]
    -J, --disable-cursor-scaling                Disable cursor position scaling
    -M, --show-host-cursor                      Don't hide the host cursor
    -k, --show-fps                              Enable FPS display
    -g                            <NAME>        Force the use of a specific renderer [possible values: opengl, vulkan]
    -o, --renderer-option         <OPTION>...   Specify a renderer option (ie: opengl:vsync=0) Alternatively specify "list" to
                                                list all renderers and their options
    -a, --auto-resize                           Auto resize the window to the guest
    -n, --prevent-resize                        Don't allow the window to be manually resized
    -r, --ignore-aspect-ratio                   Don't maintain the aspect ratio
    -d, --borderless                            Borderless mode
    -F, --borderless-fullscreen                 Borderless fullscreen mode
    -x, --x-position              <XPOS>        Initial window X position [current: center]
    -y, --y-position              <YPOS>        Initial window Y position [current: center]
    -w, --width                   <WIDTH>       Initial window width [current: 1024]
    -b, --height                  <HEIGHT>      Initial window width [current: 768]
    -Q, --ignore-quit                           Ignore requests to quit (ie: Alt+F4)
    -l, --license                               License information
    -h, --help                                  Prints help information
    -V, --version                               Prints version information

Actual Behavior Summary

OPTIONS:
    -f, --file <PATH>                    Specify the path to the shared memory file [current: /dev/shm/looking-glass]
    -s, --use-spice                      Disable spice client
    -c, --spice-host <HOST>              Specify the spice host [current: 127.0.0.1] [default: 127.0.0.1]
    -p, --spice-port <PORT>              Specify the spice port [current: 5900] [default: 5900]
    -J, --disable-cursor-scaling         Disable cursor position scaling
    -M, --show-host-cursor               Don't hide the host cursor
    -k, --show-fps                       Enable FPS display
    -g <NAME>                            Force the use of a specific renderer [possible values: opengl, vulkan]
    -o, --renderer-option <OPTION>...    Specify a renderer option (ie: opengl:vsync=0) Alternatively specify "list" to
                                         list all renderers and their options
    -a, --auto-resize                    Auto resize the window to the guest
    -n, --prevent-resize                 Don't allow the window to be manually resized
    -r, --ignore-aspect-ratio            Don't maintain the aspect ratio
    -d, --borderless                     Borderless mode
    -F, --borderless-fullscreen          Borderless fullscreen mode
    -x, --x-position <XPOS>              Initial window X position [current: center]
    -y, --y-position <YPOS>              Initial window Y position [current: center]
    -w, --width <WIDTH>                  Initial window width [current: 1024]
    -b, --height <HEIGHT>                Initial window width [current: 768]
    -Q, --ignore-quit                    Ignore requests to quit (ie: Alt+F4)
    -l, --license                        License information
    -h, --help                           Prints help information
    -V, --version                        Prints version information

---

I guess I could have -h just show the short options with an afterhelp note to use --help for long options. I have no idea if the alignment is better UX improving readability or not, just something I noticed when I introduced long options it became less obvious which options took values at a glance. I take it I'd have a similar but less pronounced issue if I alter the layout to -short <val> --long too.

In an issue on this repo, you mentioned you were working on a CLI UX mdbook, did you finish and release that anywhere?

[epage]

Comment by kbknapp
Tuesday Jun 05, 2018 at 01:43 GMT

---

Sorry for the wait, I've been away with my day job for a few weeks.

I'm not opposed to adding a cargo feature to align argument values. I say cargo feature because this would require an additional dep of something like tabwriter. I can't say I'll be able to add this super soon, as I need to work on getting the 3.x alpha/beta out first, but if someone wants to work on this I'd be happy to mentor it.

I haven't finished the CLI UX book, as I've been swamped the past few months (~year), but I still intend on working on it.