aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.markdown4
-rwxr-xr-xbin/han53
-rw-r--r--man/han.118
-rw-r--r--vim/after/ftplugin/sh.vim5
4 files changed, 80 insertions, 0 deletions
diff --git a/README.markdown b/README.markdown
index 4dd4c918..ea8b15ad 100644
--- a/README.markdown
+++ b/README.markdown
@@ -280,6 +280,10 @@ Three SSH-related scripts and their manuals are included:
If you want to use the manuals, you may need to add `~/.local/share/man` to
your `/etc/manpath` configuration, depending on your system.
+There's also a script `han(1)` to provide a `keywordprg` for Bash script
+development that will look for `help` topics. You could use it from the shell
+too. It also has a brief manual.
+
Known issues
------------
diff --git a/bin/han b/bin/han
new file mode 100755
index 00000000..5248f285
--- /dev/null
+++ b/bin/han
@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+
+#
+# If called with a single argument, try running the help builtin for the given
+# keyword, writing its output to a file. If it succeeds, show that. If not,
+# pass the call to man(1).
+#
+# This was written so it could be used as a 'keywordprg' in Vim for Bash files;
+# you can then use the K normal-mode binding over both shell builtins (e.g. read,
+# set, export) and external programs (e.g. cat, grep, ed).
+#
+# :set keywordprg=han
+#
+# You could put the above command in ~/.vim/after/ftplugin/sh.vim like this:
+#
+# " Use han(1) as a man(1) wrapper for Bash files if available
+# if exists("b:is_bash") && executable('han')
+# setlocal keywordprg=han
+# endif
+#
+# Author: Tom Ryder <tom@sanctum.geek.nz>
+# Copyright: 2015 Inspire Net Ltd
+#
+
+# Give up completely if no BASH_VERSINFO (<2.0)
+if ! test "$BASH_VERSINFO" ; then
+ return
+fi
+
+# Figure out the options with which we can call help; Bash >=4.0 has an -m
+# option which prints the help output in a man-page like format.
+declare -a helpopts
+if ((BASH_VERSINFO[0] >= 4)) ; then
+ helpopts=(-m)
+fi
+
+# Create a temporary file and set up a trap to get rid of it.
+out=$(mktemp)
+cleanup() {
+ rm -f -- "$out"
+}
+trap cleanup EXIT
+
+# If we have exactly one argument and a call to the help builtin with that
+# argument succeeds, display its output with `pager -s`.
+if (($# == 1)) && help "${helpopts[@]}" "$1" >"$out" 2>/dev/null ; then
+ exec pager -s -- "$out"
+
+# Otherwise, just pass all the arguments to man(1).
+else
+ exec man "$@"
+fi
+
diff --git a/man/han.1 b/man/han.1
new file mode 100644
index 00000000..8bb65be4
--- /dev/null
+++ b/man/han.1
@@ -0,0 +1,18 @@
+.TH HAN 1 "May 2015" "Manual page for han"
+.SH NAME
+.B han
+\- try running builtin help, then man(1)
+.SH SYNOPSIS
+.B han
+.I (HELPTOPIC | MANARGS...)
+.SH DESCRIPTION
+If called with a single argument, try running the help builtin for the given
+keyword, writing its output to a file. If it succeeds, show that. If not, pass
+the call to man(1).
+.P
+This was written so it could be used as a 'keywordprg' in Vim for Bash files;
+you can then use the K normal-mode binding over both shell builtins (e.g. read,
+set, export) and external programs (e.g. cat(1), grep(1), ed(1)).
+.SH AUTHOR
+Tom Ryder <tom@sanctum.geek.nz>
+
diff --git a/vim/after/ftplugin/sh.vim b/vim/after/ftplugin/sh.vim
index d612eba8..e872844d 100644
--- a/vim/after/ftplugin/sh.vim
+++ b/vim/after/ftplugin/sh.vim
@@ -2,3 +2,8 @@
" doesn't highlight
let g:sh_isk='@,48-57,_,192-255,.,/'
+" Use han(1) as a man(1) wrapper for Bash files if available
+if exists("b:is_bash") && executable('han')
+ setlocal keywordprg=han
+endif
+