Improved usage messages for actions (#402)

Co-authored-by: Ingo Karkat <[email protected]>

README.md

@@ -74,10 +74,10 @@ For example, to add a todo item, you can do:
 todo.sh add "THING I NEED TO DO +project @context"
 ```
 ### `replace`
-Replaces task on line ITEM# with UPDATED TODO.
+Replaces task on line NR with UPDATED TODO.
 
 ```shell
-todo.sh replace ITEM# "UPDATED TODO"
+todo.sh replace NR "UPDATED TODO"
 ```
 ### `report`
 Adds the number of open tasks and done tasks to report.txt.

USAGE.md

@@ -38,13 +38,13 @@ todo.sh addto DEST "TEXT TO ADD"
 ```
 
 ### `append`
-Adds TEXT TO APPEND to the end of the task on line ITEM#.
+Adds TEXT TO APPEND to the end of the task on line NR.
 
 Quotes optional.
 
 ```shell
-todo.sh append ITEM# "TEXT TO APPEND"
-todo.sh app ITEM# "TEXT TO APPEND"
+todo.sh append NR "TEXT TO APPEND"
+todo.sh app NR "TEXT TO APPEND"
 ```
 
 ### `archive`
@@ -71,26 +71,26 @@ todo.sh deduplicate
 ```
 
 ### `del`
-Deletes the task on line ITEM# in todo.txt. If TERM specified, deletes only TERM from the task.
+Deletes the task on line NR in todo.txt. If TERM specified, deletes only TERM from the task.
 
 ```shell
-todo.sh del ITEM# [TERM]
-todo.sh rm ITEM# [TERM]
+todo.sh del NR [TERM]
+todo.sh rm NR [TERM]
 ```
 
 ### `depri`
-Deprioritizes (removes the priority) from the task(s) on line ITEM# in todo.txt.
+Deprioritizes (removes the priority) from the task(s) on line NR in todo.txt.
 
 ```shell
-todo.sh depri ITEM#[, ITEM#, ITEM#, ...]
-todo.sh dp ITEM#[, ITEM#, ITEM#, ...]
+todo.sh depri NR [NR ...]
+todo.sh dp NR [NR ...]
 ```
 
 ### `do`
-Marks task(s) on line ITEM# as done in todo.txt.
+Marks task(s) on line NR as done in todo.txt.
 
 ```shell
-todo.sh do ITEM#[, ITEM#, ITEM#, ...]
+todo.sh do NR [NR ...]
 ```
 
 ### `help`
@@ -164,34 +164,34 @@ todo.sh lsprj [TERM...]
 ```
 
 ### `move`
-Moves a line from source text file (SRC) to destination text file (DEST). Both source and destination file must be located in the directory defined in the configuration directory. When SRC is not defined it's by default todo.txt.
+Moves line NR from source text file (SRC) to destination text file (DEST). Both source and destination file must be located in the directory defined in the configuration directory. When SRC is not defined it's by default todo.txt.
 
 ```shell
-todo.sh move ITEM# DEST [SRC]
-todo.sh mv ITEM# DEST [SRC]
+todo.sh move NR DEST [SRC]
+todo.sh mv NR DEST [SRC]
 ```
 
 ### `prepend`
-Adds TEXT TO PREPEND to the beginning of the task on line ITEM#. Quotes optional.
+Adds TEXT TO PREPEND to the beginning of the task on line NR. Quotes optional.
 
 ```shell
-todo.sh prepend ITEM# "TEXT TO PREPEND"
-todo.sh prep ITEM# "TEXT TO PREPEND"
+todo.sh prepend NR "TEXT TO PREPEND"
+todo.sh prep NR"TEXT TO PREPEND"
 ```
 
 ### `pri`
-Adds PRIORITY to task on line ITEM#.  If the task is already prioritized, replaces current priority with new PRIORITY. PRIORITY must be a letter between A and Z.
+Adds PRIORITY to task on line NR.  If the task is already prioritized, replaces current priority with new PRIORITY. PRIORITY must be a letter between A and Z.
 
 ```shell
-todo.sh pri ITEM# PRIORITY
-todo.sh p ITEM# PRIORITY
+todo.sh pri NR PRIORITY
+todo.sh p NR PRIORITY
 ```
 
 ### `replace`
-Replaces task on line ITEM# with UPDATED TODO.
+Replaces task on line NR with UPDATED TODO.
 
 ```shell
-todo.sh replace ITEM# "UPDATED TODO"
+todo.sh replace NR "UPDATED TODO"
 ```
 
 ### `report`

tests/actions-test-lib.sh

@@ -6,7 +6,7 @@ make_dummy_action()
     cat > "$1" <<EOF
 #!/bin/bash
 [ "\$1" = "usage" ] && {
-    echo "    $actionName ITEM#[, ITEM#, ...] [TERM...]"
+    echo "    $actionName NR [NR ...] [TERM...]"
     echo "      This custom action does $actionName."
     echo ""
     exit

tests/t1100-replace.sh

@@ -14,7 +14,7 @@ todo.sh add notice the daisies > /dev/null
 test_todo_session 'replace usage' <<EOF
 >>> todo.sh replace adf asdfa
 === 1
-usage: todo.sh replace ITEM# "UPDATED ITEM"
+usage: todo.sh replace NR "UPDATED ITEM"
 EOF
 
 test_todo_session 'basic replace' <<EOF

tests/t1200-pri.sh

@@ -6,7 +6,7 @@ test_description='basic priority functionality
 
 test_todo_session 'priority usage' <<EOF
 >>> todo.sh pri B B
-usage: todo.sh pri ITEM# PRIORITY[, ITEM# PRIORITY, ...]
+usage: todo.sh pri NR PRIORITY [NR PRIORITY ...]
 note: PRIORITY must be anywhere from A to Z.
 === 1
 EOF

tests/t1400-prepend.sh

@@ -6,7 +6,7 @@ test_description='basic prepend functionality
 
 test_todo_session 'prepend usage' <<EOF
 >>> todo.sh prepend B B
-usage: todo.sh prepend ITEM# "TEXT TO PREPEND"
+usage: todo.sh prepend NR "TEXT TO PREPEND"
 === 1
 EOF
 

tests/t1500-do.sh

@@ -8,13 +8,13 @@ test_description='do functionality
 
 test_todo_session 'do usage' <<EOF
 >>> todo.sh do B B
-usage: todo.sh do ITEM#[, ITEM#, ITEM#, ...]
+usage: todo.sh do NR [NR ...]
 === 1
 EOF
 
-test_todo_session 'do missing ITEM#' <<EOF
+test_todo_session 'do missing NR' <<EOF
 >>> todo.sh do
-usage: todo.sh do ITEM#[, ITEM#, ITEM#, ...]
+usage: todo.sh do NR [NR ...]
 === 1
 EOF
 

tests/t1600-append.sh

@@ -14,7 +14,7 @@ todo.sh add notice the daisies > /dev/null
 test_todo_session 'append usage' <<EOF
 >>> todo.sh append adf asdfa
 === 1
-usage: todo.sh append ITEM# "TEXT TO APPEND"
+usage: todo.sh append NR "TEXT TO APPEND"
 EOF
 
 test_todo_session 'append error' <<EOF

tests/t1700-depri.sh

@@ -6,7 +6,7 @@ test_description='basic depriority functionality
 
 test_todo_session 'depriority usage' <<EOF
 >>> todo.sh depri B B
-usage: todo.sh depri ITEM#[, ITEM#, ITEM#, ...]
+usage: todo.sh depri NR [NR ...]
 === 1
 EOF
 

tests/t1800-del.sh

@@ -8,7 +8,7 @@ SPACE=' '
 
 test_todo_session 'del usage' <<EOF
 >>> todo.sh del B
-usage: todo.sh del ITEM# [TERM]
+usage: todo.sh del NR [TERM]
 === 1
 EOF
 

tests/t2110-help-action.sh

@@ -32,24 +32,24 @@ test_todo_session 'multiple actions help' <<'EOF'
     shorthelp
       List the one-line usage of all built-in and add-on actions.
 \
-    append ITEM# "TEXT TO APPEND"
-    app ITEM# "TEXT TO APPEND"
-      Adds TEXT TO APPEND to the end of the task on line ITEM#.
+    append NR "TEXT TO APPEND"
+    app NR "TEXT TO APPEND"
+      Adds TEXT TO APPEND to the end of the task on line NR.
       Quotes optional.
 \
 EOF
 
 test_todo_session 'short and long form of action help' <<'EOF'
 >>> todo.sh help append
-    append ITEM# "TEXT TO APPEND"
-    app ITEM# "TEXT TO APPEND"
-      Adds TEXT TO APPEND to the end of the task on line ITEM#.
+    append NR "TEXT TO APPEND"
+    app NR "TEXT TO APPEND"
+      Adds TEXT TO APPEND to the end of the task on line NR.
       Quotes optional.
 \
 
 >>> todo.sh help app
-    app ITEM# "TEXT TO APPEND"
-      Adds TEXT TO APPEND to the end of the task on line ITEM#.
+    app NR "TEXT TO APPEND"
+      Adds TEXT TO APPEND to the end of the task on line NR.
       Quotes optional.
 \
 EOF

tests/t6040-completion-files.sh

@@ -13,8 +13,8 @@ test_todo_completion 'files beginning with d after addto' 'todo.sh addto d' 'don
 test_todo_completion 'all files after listfile' 'todo.sh listfile ' "$FILES"
 test_todo_completion 'all files after lf' 'todo.sh -v lf ' "$FILES"
 test_todo_completion 'nothing after move' 'todo.sh move ' ''
-test_todo_completion 'all files after move ITEM#' 'todo.sh move 1 ' "$FILES"
-test_todo_completion 'all files after mv ITEM#' 'todo.sh mv 1 ' "$FILES"
-test_todo_completion 'all files after move ITEM# DEST' 'todo.sh move 1 todo.sh ' "$FILES"
+test_todo_completion 'all files after move NR' 'todo.sh move 1 ' "$FILES"
+test_todo_completion 'all files after mv NR' 'todo.sh mv 1 ' "$FILES"
+test_todo_completion 'all files after move NR DEST' 'todo.sh move 1 todo.sh ' "$FILES"
 
 test_done

tests/t6060-completion-addon-files.sh

@@ -11,17 +11,17 @@ test_todo_completion 'nothing after unconfigured bar' 'todo.sh bar ' ''
 
 _todo_file1_actions='foo|bar'
 test_todo_completion 'all files after configured bar' 'todo.sh bar ' "$FILES"
-test_todo_completion 'nothing after configured bar ITEM#' 'todo.sh bar 1 ' ''
+test_todo_completion 'nothing after configured bar NR' 'todo.sh bar 1 ' ''
 
 _todo_file2_actions='baz'
 test_todo_completion 'nothing after configured baz' 'todo.sh baz ' ''
-test_todo_completion 'all files after configured baz ITEM#' 'todo.sh baz 1 ' "$FILES"
-test_todo_completion 'nothing after configured baz ITEM# MORE' 'todo.sh baz 1 more ' ''
+test_todo_completion 'all files after configured baz NR' 'todo.sh baz 1 ' "$FILES"
+test_todo_completion 'nothing after configured baz NR MORE' 'todo.sh baz 1 more ' ''
 
 _todo_file3_actions='biz'
 test_todo_completion 'nothing after configured biz' 'todo.sh biz ' ''
-test_todo_completion 'nothing after configured biz ITEM#' 'todo.sh biz 1 ' ''
-test_todo_completion 'all files after configured biz ITEM# MORE' 'todo.sh biz 1 more ' "$FILES"
-test_todo_completion 'nothing after configured biz ITEM# EVEN MORE' 'todo.sh biz 1 even more ' ''
+test_todo_completion 'nothing after configured biz NR' 'todo.sh biz 1 ' ''
+test_todo_completion 'all files after configured biz NR MORE' 'todo.sh biz 1 more ' "$FILES"
+test_todo_completion 'nothing after configured biz NR EVEN MORE' 'todo.sh biz 1 even more ' ''
 
 test_done

tests/t8020-actions-help.sh

@@ -20,22 +20,22 @@ make_action "quux"
 
 test_todo_session 'custom action help' <<'EOF'
 >>> todo.sh help foo
-    foo ITEM#[, ITEM#, ...] [TERM...]
+    foo NR [NR ...] [TERM...]
       This custom action does foo.
 \
 
 >>> todo.sh help bar
-    bar ITEM#[, ITEM#, ...] [TERM...]
+    bar NR [NR ...] [TERM...]
       This custom action does bar.
 \
 EOF
 
 test_todo_session 'multiple custom actions help' <<'EOF'
 >>> todo.sh help foo bar
-    foo ITEM#[, ITEM#, ...] [TERM...]
+    foo NR [NR ...] [TERM...]
       This custom action does foo.
 \
-    bar ITEM#[, ITEM#, ...] [TERM...]
+    bar NR [NR ...] [TERM...]
       This custom action does bar.
 \
 EOF
@@ -46,7 +46,7 @@ TODO: No action "doesnotexist" exists.
 === 1
 
 >>> todo.sh help foo doesnotexist bar
-    foo ITEM#[, ITEM#, ...] [TERM...]
+    foo NR [NR ...] [TERM...]
       This custom action does foo.
 \
 TODO: No action "doesnotexist" exists.
@@ -55,20 +55,20 @@ EOF
 
 test_todo_session 'mixed built-in and custom actions help' <<'EOF'
 >>> todo.sh help foo shorthelp bar
-    foo ITEM#[, ITEM#, ...] [TERM...]
+    foo NR [NR ...] [TERM...]
       This custom action does foo.
 \
     shorthelp
       List the one-line usage of all built-in and add-on actions.
 \
-    bar ITEM#[, ITEM#, ...] [TERM...]
+    bar NR [NR ...] [TERM...]
       This custom action does bar.
 \
 EOF
 
 test_todo_session 'custom override of built-in action help' <<'EOF'
 >>> todo.sh help ls
-    ls ITEM#[, ITEM#, ...] [TERM...]
+    ls NR [NR ...] [TERM...]
       This custom action does ls.
 \
 EOF

tests/t9999-testsuite_example.sh

@@ -90,7 +90,7 @@ TODO: $HOME/todo.txt archived.
 TODO: Report file updated.
 
 >>> todo.sh append g a
-usage: todo.sh append ITEM# "TEXT TO APPEND"
+usage: todo.sh append NR "TEXT TO APPEND"
 === 1
 
 >>> todo.sh append 2 and think