From fee7fdd43f2473b750489d10e4b8ed46619fac16 Mon Sep 17 00:00:00 2001
From: Tom Ryder <tom@sanctum.geek.nz>
Date: Thu, 21 May 2015 16:26:32 +1200
Subject: Add han(1)

---
 README.markdown           |  4 ++++
 bin/han                   | 53 +++++++++++++++++++++++++++++++++++++++++++++++
 man/han.1                 | 18 ++++++++++++++++
 vim/after/ftplugin/sh.vim |  5 +++++
 4 files changed, 80 insertions(+)
 create mode 100755 bin/han
 create mode 100644 man/han.1

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
+
-- 
cgit v1.2.3