From 42424d58817383d94fef85b6ba301dc3bb0cfd7d Mon Sep 17 00:00:00 2001
From: Ingo Karkat <swdev@ingo-karkat.de>
Date: Fri, 27 Apr 2012 11:48:01 +0200
Subject: [PATCH] ENH: Print usage help for custom action.

Currently, the only way to get usage help for a custom action is to use "todo.sh help" and scroll / search for the action name. (Or try to call the action without / with invalid parameters to hopefully get a one-line syntax summary.)
This extends the help command to print the usage of optionally passed custom action names.
---
 tests/t8020-actions-help.sh | 71 +++++++++++++++++++++++++++++++++++++
 todo.sh                     | 33 ++++++++++++++---
 2 files changed, 99 insertions(+), 5 deletions(-)
 create mode 100755 tests/t8020-actions-help.sh

diff --git a/tests/t8020-actions-help.sh b/tests/t8020-actions-help.sh
new file mode 100755
index 0000000..6f6746b
--- /dev/null
+++ b/tests/t8020-actions-help.sh
@@ -0,0 +1,71 @@
+#!/bin/bash
+
+test_description='actions help functionality
+
+This test checks listing the usage help of a custom action.
+'
+. ./test-lib.sh
+
+unset TODO_ACTIONS_DIR
+test_todo_session 'custom action help with no custom action directory' <<'EOF'
+>>> todo.sh help foo
+TODO: No actions directory exists.
+=== 1
+EOF
+
+mkdir .todo.actions.d
+make_action()
+{
+	cat > ".todo.actions.d/$1" <<EOF
+#!/bin/bash
+[ "\$1" = "usage" ] && {
+    echo "    $1 ITEM#[, ITEM#, ...] [TERM...]"
+    echo "      This custom action does $1."
+    echo ""
+    exit
+}
+echo "custom action $1"
+EOF
+chmod +x ".todo.actions.d/$1"
+}
+
+make_action "foo"
+make_action "bar"
+make_action "quux"
+
+test_todo_session 'custom action help' <<'EOF'
+>>> todo.sh help foo
+    foo ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does foo.
+\
+
+>>> todo.sh help bar
+    bar ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does bar.
+\
+EOF
+
+test_todo_session 'multiple custom actions help' <<'EOF'
+>>> todo.sh help foo bar
+    foo ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does foo.
+\
+    bar ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does bar.
+\
+EOF
+
+test_todo_session 'nonexisting action help' <<'EOF'
+>>> todo.sh help doesnotexist
+TODO: No add-on action "doesnotexist" exists.
+=== 1
+
+>>> todo.sh help foo doesnotexist bar
+    foo ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does foo.
+\
+TODO: No add-on action "doesnotexist" exists.
+=== 1
+EOF
+
+test_done
diff --git a/todo.sh b/todo.sh
index 4837120..8d1080e 100755
--- a/todo.sh
+++ b/todo.sh
@@ -302,6 +302,23 @@ addonHelp()
     fi
 }
 
+addonUsage()
+{
+    if [ -d "$TODO_ACTIONS_DIR" ]; then
+        for actionName
+        do
+            action="${TODO_ACTIONS_DIR}/${actionName}"
+            if [ -f "$action" -a -x "$action" ]; then
+                "$action" usage
+            else
+                die "TODO: No add-on action \"${actionName}\" exists."
+            fi
+        done
+    else
+        die "TODO: No actions directory exists."
+    fi
+}
+
 die()
 {
     echo "$*"
@@ -1075,13 +1092,19 @@ case $action in
     ;;
 
 "help" )
-    if [ -t 1 ] ; then # STDOUT is a TTY
-        if which "${PAGER:-less}" >/dev/null 2>&1; then
-            # we have a working PAGER (or less as a default)
-            help | "${PAGER:-less}" && exit 0
+    shift  ## Was help; new $1 is first help topic / action name
+    if [ $# -gt 0 ]; then
+        # Don't use PAGER here; we don't expect much usage output from one / few actions.
+        addonUsage "$@"
+    else
+        if [ -t 1 ] ; then # STDOUT is a TTY
+            if which "${PAGER:-less}" >/dev/null 2>&1; then
+                # we have a working PAGER (or less as a default)
+                help | "${PAGER:-less}" && exit 0
+            fi
         fi
+        help # just in case something failed above, we go ahead and just spew to STDOUT
     fi
-    help # just in case something failed above, we go ahead and just spew to STDOUT
     ;;
 
 "shorthelp" )