Bat: Update the sort order in --help and the manpage

[eth-p]

As mentioned in @sharkdp's comment on issue #651, the order in which things show up in --help was intended to be "most useful"/"most frequently used" first.

As @sharkdp also pointed out in his comment, some of the entries need to be moved to bring --help back in line with its intended ordering scheme.

I'm opening this issue as a way to keep track of that, and to also get feedback from people who use bat and want to suggest some improvements to the current order or let us know which options they find themselves using most frequently.

[sharkdp]

Most often used options for me:

• -l/--language
• -p/--plain
• -L/--list-languages
• -A/--show-all (much less frequent than the top three)

--list-languages might only be there because I am developing bat :smile:.

[sharkdp]

Also, we shouldn't just "blindly" sort it by used-most-frequently. Maybe even more important would be to group similar options together:

• --theme, --list-themes
• --language,--list-languages
• --plain, --number and --style?
• ...

[adiabatic]

Also: --help and the manpage should have the same order. Perhaps this issue's name should be changed to "Update the sort order in --help and the manpage"?

[adiabatic]

--list-languages might only be there because I am developing bat 😄.

It's useful to me when I've got my fish-completions-writer hat on, but almost never otherwise. Quite honestly, I'm surprised it got a single-letter option in the latest release — that's prime real estate being used up by an option that probably gets run almost never.

[adiabatic]

I strongly endorse keeping related options close together.

Related opinions, in no particular order:

• --language (and its helper, --list-languages) probably shouldn't be first, as bat can usually guess well enough in my experience.
• --theme, --color, and --italic-text all seem like peas in a pod to me.
• --unbuffered should probably be the last option before --help and --version.
• --tabs, --wrap, and --terminal-width all seem of a kind. Maybe throw in --paging and --pager, too.
• --plain and its friends, whatever they may be, should probably be first. That said, I set BAT_STYLE to "plain" in my config.fish and haven't needed to touch it since. Terminal.app generally scrolls more nicely than less-in-Terminal does, so I'm mildly anti-pager.

[hrlmartins]

Hello guys, I'm newcomer trying to get my feet wet on this project since it is something I actually use. This one seemed like a good start if everyone agrees :)

So personally, I rarely use any flag really. By itself it serves most of my needs. Nevertheless I tried to reach to an order of what seemed the most "useful":

OPTIONS:
    -A, --show-all                    
            Show non-printable characters like space, tab or newline. This option can also be used
            to print binary files. Use '--tabs' to control the width of the tab-placeholders.
    -r, --line-range <N:M>...         
            Only print the specified range of lines for each file. For example:
              '--line-range 30:40' prints lines 30 to 40
              '--line-range :40' prints lines 1 to 40
              '--line-range 40:' prints lines 40 to the end of the file
    -H, --highlight-line <N>...       
            Highlight the N-th line with a different background color
        --tabs <T>                    
            Set the tab width to T spaces. Use a width of 0 to pass tabs through directly
        --wrap <mode>                 
            Specify the text-wrapping mode (*auto*, never, character). The '--terminal-width' option
            can be used in addition to control the output width.
        --terminal-width <width>      
            Explicitly set the width of the terminal instead of determining it automatically. If
            prefixed with '+' or '-', the value will be treated as an offset to the actual terminal
            width. See also: '--wrap'.
    -n, --number                      
            Only show line numbers, no other decorations. This is an alias for '--style=numbers'
        --color <when>                
            Specify when to use colored output. The automatic mode only enables colors if an
            interactive terminal is detected. Possible values: *auto*, never, always.
        --italic-text <when>          
            Specify when to use ANSI sequences for italic text in the output. Possible values:
            always, *never*.
        --decorations <when>          
            Specify when to use the decorations that have been specified via '--style'. The
            automatic mode only enables decorations if an interactive terminal is detected. Possible
            values: *auto*, never, always.
        --paging <when>               
            Specify when to use the pager. To control which pager is used, set the PAGER or
            BAT_PAGER environment variables (the latter takes precedence) or use the '--pager'
            option. To disable the pager permanently, set BAT_PAGER to an empty string or set
            '--paging=never' in the configuration file. Possible values: *auto*, never, always.
        --pager <command>             
            Determine which pager is used. This option will overwrite the PAGER and BAT_PAGER
            environment variables. The default pager is 'less'. To disable the pager completely, use
            the '--paging' option. Example: '--pager "less -RF"'.
    -m, --map-syntax <from:to>...     
            Map a file extension or file name to an existing syntax. For example, to highlight
            *.conf files with the INI syntax, use '-m conf:ini'. To highlight files named
            '.myignore' with the Git Ignore syntax, use '-m .myignore:gitignore'.
        --theme <theme>               
            Set the theme for syntax highlighting. Use '--list-themes' to see all available themes.
            To set a default theme, add the '--theme="..."' option to the configuration file or
            export the BAT_THEME environment variable (e.g.: export BAT_THEME="...").
        --list-themes                 
            Display a list of supported themes for syntax highlighting.
        --style <style-components>    
            Configure which elements (line numbers, file headers, grid borders, Git modifications,
            ..) to display in addition to the file contents. The argument is a comma-separated list
            of components to display (e.g. 'numbers,changes,grid') or a pre-defined style ('full').
            To set a default style, add the '--style=".."' option to the configuration file or
            export the BAT_STYLE environment variable (e.g.: export BAT_STYLE=".."). Possible
            values: *auto*, full, plain, changes, header, grid, numbers, snip.
    -p, --plain                       
            Only show plain style, no decorations. This is an alias for '--style=plain'. When '-p'
            is used twice ('-pp'), it also disables automatic paging (alias for '--style=plain
            --pager=never').
    -l, --language <language>         
            Explicitly set the language for syntax highlighting. The language can be specified as a
            name (like 'C++' or 'LaTeX') or possible file extension (like 'cpp', 'hpp' or 'md'). Use
            '--list-languages' to show all supported language names and file extensions.
    -L, --list-languages              
            Display a list of supported languages for syntax highlighting.
    -u, --unbuffered                  
            This option exists for POSIX-compliance reasons ('u' is for 'unbuffered'). The output is
            always unbuffered - this option is simply ignored.
    -h, --help                        
            Print this help message.

    -V, --version                     
            Show version information.

Given the the tool's use case and many of the comments, the "filtering" options seemed the most interesting to me. --show all controls whether or not it shows all characters, which seems very useful to find "nasty" rogue characters at times. And well, --line-range: I just want to show part of a huge file :)

From -H to basically -p this seems just visual "sugar" to me, with H (and maybe --tabs) being the most relevant to bring focus to a specific line.

-l... well meh, never had any trouble with it or the need to syntax highlight in a different way. All options below that seem even less useful or used in very specific cases, hence being last in this list.

And that is basically it. What do you think? Suggestions are welcome.

[sharkdp]

Hello guys, I'm newcomer trying to get my feet wet on this project since it is something I actually use. This one seemed like a good start if everyone agrees :)

Sounds great!

I don't quite agree with your order. IMO, --plain and --language are probably the most important options. --plain is not just "visual sugar", it's also useful to switch off the pager (-pp) and to have an output without decorations if you want to select code with the mouse. I use --language frequently when piping into bat. If a program outputs JSON, I can use … | bat -ljson. If I use strace, I can get a colorized output by using strace … 2>&1 | bat -lstrace.

Apart from that, I don't really care too much as long as it's clustered.

Another option would be to just alphabetically sort it and get on with it :smile:

[hrlmartins]

I don't quite agree with your order. IMO, --plain and --language are probably the most important options. --plain is not just "visual sugar", it's also useful to switch off the pager (-pp) and to have an output without decorations if you want to select code with the mouse. I use --language frequently when piping into bat. If a program outputs JSON, I can use … | bat -ljson. If I use strace, I can get a colorized output by using strace … 2>&1 | bat -lstrace.

Thanks for the feedback. I tried to be as agnostic as possible and clearly that is not possible as it might depend on people's uses :P.

Anyways, before reverting back to sorting the options what do you think of putting those two near the top, but bellow show all (taking line-range down) like so:

OPTIONS:
    -A, --show-all                    
            Show non-printable characters like space, tab or newline. This option can also be used
            to print binary files. Use '--tabs' to control the width of the tab-placeholders.
    -p, --plain                       
            Only show plain style, no decorations. This is an alias for '--style=plain'. When '-p'
            is used twice ('-pp'), it also disables automatic paging (alias for '--style=plain
            --pager=never').
    -l, --language <language>         
            Explicitly set the language for syntax highlighting. The language can be specified as a
            name (like 'C++' or 'LaTeX') or possible file extension (like 'cpp', 'hpp' or 'md'). Use
            '--list-languages' to show all supported language names and file extensions.
    -H, --highlight-line <N>...       
            Highlight the N-th line with a different background color
        --tabs <T>                    
            Set the tab width to T spaces. Use a width of 0 to pass tabs through directly
        --wrap <mode>                 
            Specify the text-wrapping mode (*auto*, never, character). The '--terminal-width' option
            can be used in addition to control the output width.
        --terminal-width <width>      
            Explicitly set the width of the terminal instead of determining it automatically. If
            prefixed with '+' or '-', the value will be treated as an offset to the actual terminal
            width. See also: '--wrap'.
    -n, --number                      
            Only show line numbers, no other decorations. This is an alias for '--style=numbers'
        --color <when>                
            Specify when to use colored output. The automatic mode only enables colors if an
            interactive terminal is detected. Possible values: *auto*, never, always.
        --italic-text <when>          
            Specify when to use ANSI sequences for italic text in the output. Possible values:
            always, *never*.
        --decorations <when>          
            Specify when to use the decorations that have been specified via '--style'. The
            automatic mode only enables decorations if an interactive terminal is detected. Possible
            values: *auto*, never, always.
        --paging <when>               
            Specify when to use the pager. To control which pager is used, set the PAGER or
            BAT_PAGER environment variables (the latter takes precedence) or use the '--pager'
            option. To disable the pager permanently, set BAT_PAGER to an empty string or set
            '--paging=never' in the configuration file. Possible values: *auto*, never, always.
        --pager <command>             
            Determine which pager is used. This option will overwrite the PAGER and BAT_PAGER
            environment variables. The default pager is 'less'. To disable the pager completely, use
            the '--paging' option. Example: '--pager "less -RF"'.
    -m, --map-syntax <from:to>...     
            Map a file extension or file name to an existing syntax. For example, to highlight
            *.conf files with the INI syntax, use '-m conf:ini'. To highlight files named
            '.myignore' with the Git Ignore syntax, use '-m .myignore:gitignore'.
        --theme <theme>               
            Set the theme for syntax highlighting. Use '--list-themes' to see all available themes.
            To set a default theme, add the '--theme="..."' option to the configuration file or
            export the BAT_THEME environment variable (e.g.: export BAT_THEME="...").
        --list-themes                 
            Display a list of supported themes for syntax highlighting.
        --style <style-components>    
            Configure which elements (line numbers, file headers, grid borders, Git modifications,
            ..) to display in addition to the file contents. The argument is a comma-separated list
            of components to display (e.g. 'numbers,changes,grid') or a pre-defined style ('full').
            To set a default style, add the '--style=".."' option to the configuration file or
            export the BAT_STYLE environment variable (e.g.: export BAT_STYLE=".."). Possible
            values: *auto*, full, plain, changes, header, grid, numbers, snip.
    -r, --line-range <N:M>...         
            Only print the specified range of lines for each file. For example:
              '--line-range 30:40' prints lines 30 to 40
              '--line-range :40' prints lines 1 to 40
              '--line-range 40:' prints lines 40 to the end of the file
    -L, --list-languages              
            Display a list of supported languages for syntax highlighting.
    -u, --unbuffered                  
            This option exists for POSIX-compliance reasons ('u' is for 'unbuffered'). The output is
            always unbuffered - this option is simply ignored.
    -h, --help                        
            Print this help message.

    -V, --version                     
            Show version information.

It seems it keeps everything important on the top and clustered up :)

[sharkdp]

Sounds good!

[sharkdp]

closed via #700 by @hrlmartins

[sharkdp]

This has been released in bat 0.13.