Hacker News new | ask | show | jobs
by arp242 361 days ago
Alignment (and maybe bold text for some things) is all you need in >95% of cases, IMHO.

One of the downsides of a lot of these tools is that's exactly what they don't do well: many things don't align or wrap nicely.

For example, here's a comparison of this fang library vs one where I just raw-dogged the usage text: https://imgur.com/a/QWh9TLD – the nice alignment does a lot more than colours. Especially for larger programs with a bunch of flags it can be such a pain. For example from an otherwise quite nice tool: https://imgur.com/a/RELL9Gk – you just completely lose any "overview".

I did spend some time on some better tooling to improve all of this, because manually writing these isn't super-fun either, but not so straight-forward to do well (or at least: not in a way that I like).
1 comments
quotemstr 361 days ago
> One of the downsides of a lot of these tools is that's exactly what they don't do well: many things don't align or wrap nicely.

Bling is easy. Unsexy usability details are hard.

    Z$ time ./example/run
    You ran the root command. Now try --help.
    ./example/run  0.13s user 0.27s system 177% cpu 0.228 total
Why would an example program take 228ms?

    Z$ ./example/run --name='abc def'
    
      Unknown command "def" for "example".                                                            

      Try --help for usage.
Huh? 'abc def' is one shell word. --name=abc works fine.

     Z$ ./example/run --name ''
          
       ERROR  
         
       Flag needs an argument: --name.                                                                 

       Try --help for usage.
But I did give it an argument: the empty string.

And why is the output indented two columns from the left margin anyway?

    Z$ ./example/run ''
    You ran the root command. Now try --help.

    Z$ ./example/run 'x'
          
      ERROR  
          
      Unknown command "x" for "example".                                                              

      Try --help for usage.
Should have produced an error using '' for the subcommand name.

    Z$ ./example/run sub "multi-word quoted string" --flag "another quoted string"
    Ran the sub command!

    Z$ ./example/run --help

      A little example program!                                                                         
                                                                                                        
      It doesn’t really do anything, but that’s the point.™                                             

      USAGE  


        example [command] [args] [--flags]                                     


      EXAMPLES  


        # Run it:                                                              
        example                                                                
                                                                               
        # Run it with some arguments:                                          
        example --name=Carlos -a -s Becker -a                                  
                                                                               
        # Run a subcommand with an argument:                                   
        example sub --async --foo=xyz --async arguments                        
                                                                               
        # Run with a quoted string:                                            
        example sub "quoted string"                                            
                                                                               
        # Mix and match:                                                       
        example sub "multi-word quoted string" --flag "another quoted string"  


      COMMANDS  

        help [command]                  Help about any command
        sub [command] [args] [--flags]  An example subcommand
        throw                           Throws an error

      FLAGS  

         -a --async                     Run async
         -h --help                      Help for example
         --name                         Your name (jane)
         -s --surname                   Your surname (doe)
         -v --version                   Version for example


    Z$ ./example/run sub "multi-word quoted string" --flag "another quoted string"
    zsh: command not found: example sub multi-word quoted string --flag another quoted string
Huh? Why did the command work when I typed it myself but not when I pasted from the help output?

Oh. Because the help output is using nbsp, not regular spaces.

Anyway, command line interfaces have a surprising number of hairy corner cases. I'd rather have boring monochrome that gets them right than an all-colorful theme auto-shell-completion-generating system that doesn't.

link
JdeBP 360 days ago
Here is one of your empty argument being thrown away instead of respected bugs:

* https://github.com/spf13/cobra/blob/6dec1ae26659a130bdb4c985...

I could explain the single-quote argument quoting error if you were running it on Windows. The Go runtime library does not provide single-quoting on Windows. At all. (This is historically the behaviour of C runtime libraries on Windows, too.) It should be using a proper argument vector and not doing its own command-line parsing on other platforms, though.

* https://cs.opensource.google/go/go/+/master:src/os/exec_wind...

* https://cs.opensource.google/go/go/+/master:src/os/proc.go;l...

link