Configurable help text width and inter-column spacing #16

Closed
kriegaex opened this Issue Jul 27, 2012 · 2 comments

Comments

Projects
None yet
2 participants

In an E-Mail I asked a while ago:

I would like to be able to increase the output width of the help screen from 80 to something like 100. A quick glance at your internal formatting classes shows that there does not seem to be a lot of hardcoded stuff, so my wish is: make the width configurable. In many cases this would save users from implementing their own help formatters. Furthermore, in my case there is way too much wasted white space in between parameter and description columns, so it would also be nice to have a parameter to influence the white space in between the columns.

Paul's answer was:

When I created the help formatting stuff, I had initially thought about publishing more functionality. Then I thought, gee, help formatting is generally drudgery, how about offering a reasonable default (80 chars wide, two columns, etc.). Then I got enough requests about help formatting that I offered up writing custom formatters. It sounds like an option somewhere in between is what you're looking for. Maybe publishing the BuiltinHelpFormatter (renaming to something like BasicHelpFormatter), adding a constructor arg for screen width?

Yes, that would be a step into the right direction. What is also really important though, as mentioned above, is to avoid wasting space on screen by making the first column ("Option") just as wide as minimally necessary. The rest would be used by the usually more verbose "Description" column. Real world example from one of my programs:

Option                                  Description                            
------                                  -----------                            
-?, --help                              Display this help text                 
-d, --download-dir <File>               Download directory for openbooks; must 
                                          exist (default: .)                   
-l, --log-level <Integer>               Log level (0=normal, 1=verbose,        
                                          2=debug, 3=trace) (default: 0)       
-p, --pretty-print <Integer>            Pretty-print after clean-up (0=no,     
                                          1=yes); no saves ~15% processing     
                                          time (default: 1)                    
-t, --threading <Integer>               Threading mode (0=single, 1=multi);    
                                          single is slower, but better for     
                                          diagnostics) (default: 1)            

As you can see, there are 12 columns of white space in between options and description. While preserving the same width of 80 characters, this could also be rewritten like this, still keeping the column distance at 2 characters:

Option                        Description                            
------                        -----------                            
-?, --help                    Display this help text                 
-d, --download-dir <File>     Download directory for openbooks; must exist
                                (default: .)
-l, --log-level <Integer>     Log level (0=normal, 1=verbose, 2=debug, 3=trace)
                                (default: 0)       
-p, --pretty-print <Integer>  Pretty-print after clean-up (0=no, 1=yes); no
                                saves ~15% processing time (default: 1)                    
-t, --threading <Integer>     Threading mode (0=single, 1=multi); single is
                                slower, but better for diagnostics) (default:
                                1)

For a total width of 92 it would look like this:

Option                        Description                            
------                        -----------                            
-?, --help                    Display this help text                 
-d, --download-dir <File>     Download directory for openbooks; must exist (default: .)
-l, --log-level <Integer>     Log level (0=normal, 1=verbose, 2=debug, 3=trace) (default: 0)
-p, --pretty-print <Integer>  Pretty-print after clean-up (0=no, 1=yes); no saves ~15%
                                processing time (default: 1)
-t, --threading <Integer>     Threading mode (0=single, 1=multi); single is slower, but
                                better for diagnostics) (default: 1)

Without word wrap (total width of 127) it would look like this:

Option                        Description                            
------                        -----------                            
-?, --help                    Display this help text                 
-d, --download-dir <File>     Download directory for openbooks; must exist (default: .)
-l, --log-level <Integer>     Log level (0=normal, 1=verbose, 2=debug, 3=trace) (default: 0)
-p, --pretty-print <Integer>  Pretty-print after clean-up (0=no, 1=yes); no saves ~15% processing time (default: 1)
-t, --threading <Integer>     Threading mode (0=single, 1=multi); single is slower, but better for diagnostics) (default: 1)

So optionally turning off word wrap altogether would also be an interesting option.

Collaborator

pholser commented Jul 27, 2012

Excellent. I'll set about publishing something along the lines of BasicHelpFormatter with configurable overall width and inter-column spacing.

Collaborator

pholser commented Nov 20, 2012

Available in 4.4 beta 2

pholser closed this Nov 20, 2012

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment