Linux Fu: A Little Help for Bash

It isn’t uncommon these days for a programmer’s editor to offer you help about what you are typing, ranging from a pop up with choices to a full-blown code template. If you have written a million lines of code in the language, this might even annoy you. However, if you use it only occasionally, these can be very helpful. I’ve used Unix and Linux for many years, but I realize that there are people who don’t use it every day. With the Raspberry Pi, Linux servers, and Windows 10 having a bash shell, there are more people using a shell “every once in a while” than ever before. Could you use a little help? If so, you might try bashelp: a little something I put together while writing about bash completion.

There’s good news and bad news. The good news is that Unix has a built-in help command — man — and has for some time. The bad news is that you need to stop what you are typing and enter a man command to use it. Man, by the way, is short for manual.

There are GUI front-ends to man (like yelp, on the left) and you can even use a web browser locally or remotely. However, none of these are connected to what you are typing. You have to move to another window, enter your search term, then go back to your typing. That got me to thinking about how to get a sort of context-sensitive inline help for bash.

As with tab completion, there are two parts to consider in creating a help function: a shell function to get help, and a means of telling readline to call that function. The bashelp.sh script provides both. However, it only works if $DISPLAY is set, indicating you are using a GUI terminal. The Mac, by the way, doesn’t do GUI this way, so if you are trying to get it to work on a Mac, you’d need to change that in a few places. If you do and you get it to work, I’d love to see a pull request or a fork.

The script lets you set a “help” character. I picked Control+Y which the bind command thinks is “\C-Y.” You’ll find that near the top of the script and you can change it if you want. There are also a few configuration items so you can run man in a new terminal or you can run a graphical man replacement. See the readme for details on configuration.

The function is pretty simple.  It bails if you don’t have X (again, looking at $DISPLAY). It also expects line data from readline in $READLINE_LINE and $READLINE_POINT. If there’s no line, the script quits. The function then takes the first word of the line up to a space as a token and then parses all the options to launch the right man viewer.

Of course, this is just one thing you could do by subverting readline. It is a handy trick to have in your toolbox if you use or write scripts for bash.

If you want more bash customization, you can always pick out a new prompt. If you’d like to make your help script bounce the focus back to your original window or close under certain circumstances, you might want to read up on commanding GUI windows.