Improved usage messages for actions (#402) (cp. inkarkat/todo.txt-cli@3…

…1d8772)

(This relates to commit inkarkat/todo.txt-cli@31d8772)

System-info: Ubuntu 20.04.6 LTS, x86_64
Platform-info: bash 5.0.17(1)-release

.vim/sh_action.txt

@@ -4,10 +4,10 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) ITEM#[, ITEM#, ...] [TERM...]"
+    echo "    $(basename $0) NR [NR ...] [TERM...]"
     echo "      TODO"
     echo ""
     exit
 }
 
-errmsg="usage: $TODO_SH $(basename $0) ITEM#[, ITEM#, ...] [TERM...]"
+errmsg="usage: $TODO_SH $(basename $0) NR [NR ...] [TERM...]"

actions/addagain

@@ -11,7 +11,7 @@
 #
 # REMARKS:
 #
-# COPYRIGHT: (C) 2012-2022 Ingo Karkat
+# COPYRIGHT: (C) 2012-2024 Ingo Karkat
 #   This program is free software; you can redistribute it and/or modify it
 #   under the terms of the GNU General Public License.
 #   See http://www.gnu.org/copyleft/gpl.txt
@@ -26,8 +26,9 @@ shift
     echo "    $(basename $0) [TERM...]"
     echo "      Adds a done task specified by TERM(s) as an open task again."
     echo "      When multiple tasks are found, queries which task to choose."
-    echo "    $(basename $0) ITEM#[, ITEM#, ...] [TERM...]"
-    echo "      Adds done, but not yet archived task(s) from todo.txt as open task(s)."
+    echo "    $(basename $0) NR [NR ...] [TERM...]"
+    echo "      Adds done, but not yet archived task(s) from todo.txt line NR as open"
+    echo "      task(s)."
     echo ""
     exit
 }

actions/addlike

@@ -11,7 +11,7 @@
 #
 # REMARKS:
 #
-# COPYRIGHT: (C) 2012-2013 Ingo Karkat
+# COPYRIGHT: (C) 2012-2024 Ingo Karkat
 #   This program is free software; you can redistribute it and/or modify it
 #   under the terms of the GNU General Public License.
 #   See http://www.gnu.org/copyleft/gpl.txt
@@ -23,19 +23,19 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) [ITEM#] THING SIMILAR TO ITEM#"
-    echo "      Adds THING SIMILAR TO ITEM#, including the project(s) and context(s) from"
-    echo "      ITEM# or, if omitted, the last task in todo.txt."
+    echo "    $(basename $0) [NR] THING SIMILAR TO NR"
+    echo "      Adds THING SIMILAR TO NR, including the project(s) and context(s) from"
+    echo "      line NR or, if omitted, the last task in todo.txt."
     echo ""
     exit
 }
 
 shopt -s extglob
 
-errmsg="usage: $TODO_SH $(basename $0) [ITEM#] THING SIMILAR TO ITEM#"
+errmsg="usage: $TODO_SH $(basename $0) [NR] THING SIMILAR TO NR"
 item=
 if [[ "$1" = +([0-9]) ]]; then
-    # We got an ITEM#.
+    # We got a NR.
     item=$1
     shift
 else

actions/addprereq

@@ -23,13 +23,13 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) ITEM#[, ITEM#, ...] \"THING DEPENDING ON ITEM#\""
-    echo "      Adds THING DEPENDING ON ITEM#, and marks them as depending on ITEM#."
+    echo "    $(basename $0) NR [NR ...] \"THING DEPENDING ON NR\""
+    echo "      Adds THING DEPENDING ON NR, and marks them as depending on NR."
     echo ""
     exit
 }
 
-errmsg="usage: $TODO_SH $(basename $0) ITEM#[, ITEM#, ...] \"THING DEPENDING ON ITEM#\""
+errmsg="usage: $TODO_SH $(basename $0) NR [NR ...] \"THING DEPENDING ON NR\""
 
 typeset -a depitems=()
 while [[ "$1" =~ ^[,0-9]+$ ]]

actions/archive

@@ -11,7 +11,7 @@
 #
 # REMARKS:
 #
-# COPYRIGHT: (C) 2010-2022 Ingo Karkat
+# COPYRIGHT: (C) 2010-2024 Ingo Karkat
 #   This program is free software; you can redistribute it and/or modify it
 #   under the terms of the GNU General Public License.
 #   See http://www.gnu.org/copyleft/gpl.txt
@@ -28,10 +28,10 @@ shift
     echo "      and removes blank lines."
     echo "    $(basename $0) TERM..."
     echo "      If TERM specified, processes only tasks that contain TERM(s)."
-    echo "      Note that if TERM is a number it is considered as an ITEM# number."
-    echo "    $(basename $0) ITEM#[, ITEM#, ...]"
-    echo "      Processes task(s) ITEM# and removes blank lines. Ignores ITEM# if it's"
-    echo "      not done or trashed."
+    echo "      Note that if TERM is a number it is considered as a NR number."
+    echo "    $(basename $0) NR [NR ...]"
+    echo "      Processes task(s) on line(s) NR and removes blank lines."
+    echo "      Ignores line NR if it's not done or trashed."
     echo ""
     exit
 }

actions/attach

@@ -23,13 +23,13 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) [mv|move] ITEM# FILE|- [...]"
+    echo "    $(basename $0) [mv|move] NR FILE|- [...]"
     echo "      Copies (/ moves) FILE(s) to the attachment subdir of \$TODO_DIR and adds a"
-    echo "      a: reference to the task."
+    echo "      a: reference to the task on line NR."
     echo ""
     exit
 }
-errmsg="usage: $TODO_SH $(basename $0) [mv|move] ITEM# FILE|- [...]"
+errmsg="usage: $TODO_SH $(basename $0) [mv|move] NR FILE|- [...]"
 
 typeset -a action=(cp)
 if [ "$1" = "mv" -o "$1" = "move" ]; then

actions/browse

@@ -22,8 +22,8 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) ITEM#[, ITEM#, ...]"
-    echo "      Searches for URLs of web resources in the task text and"
+    echo "    $(basename $0) NR [NR ...]"
+    echo "      Searches for URLs of web resources in the task text on line NR and"
     echo "      launches a browser."
     echo "    $(basename $0) [TERM...]"
     echo "      Displays all tasks that contain URLs and TERM(s)."

actions/bump

@@ -11,7 +11,7 @@
 #
 # REMARKS:
 #
-# COPYRIGHT: (C) 2012-2013 Ingo Karkat
+# COPYRIGHT: (C) 2012-2024 Ingo Karkat
 #   This program is free software; you can redistribute it and/or modify it
 #   under the terms of the GNU General Public License.
 #   See http://www.gnu.org/copyleft/gpl.txt
@@ -23,16 +23,16 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) ITEM#[, ITEM#, ...]"
-    echo "      Increments a bump counter for each ITEM#."
+    echo "    $(basename $0) NR [NR ...]"
+    echo "      Increments a bump counter for each task on line NR."
     echo "      Use this whenever you're annoyed by an open task, to get a better"
     echo "      measure about its importance."
     echo ""
     exit
 }
 
 : ${TODOTXT_BUMP_MARKER:='!'}
-errmsg="usage: $TODO_SH $(basename $0) ITEM#[, ITEM#, ...]]"
+errmsg="usage: $TODO_SH $(basename $0) NR [NR ...]]"
 [ $# -eq 0 ] && die "$errmsg"
 
 for item in ${*//,/ }; do

actions/cheat

@@ -73,8 +73,8 @@ j:goal       joined to goal; when this is done, other tasks with the same goal
 t:2010-10-10 future task becomes due on the date, created via todo.sh schedule
 u:2011-12-01 do-until, ultimate, latest due date until the task should have been
              done.
-w:42         waiting for task number, created via todo.sh wait ITEM# for 42
-w:Gina       waiting for person / event, created via todo.sh wait ITEM# Gina
+w:42         waiting for task number, created via todo.sh wait NR for 42
+w:Gina       waiting for person / event, created via todo.sh wait NR Gina
 x:42         trash as a duplicate of task 42; useful as an alternative to
              todo.sh dup del when editing in other clients.
 x:2011-12-01 trash on date.

actions/clone

@@ -23,15 +23,16 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) ITEM# [PATTERN REPLACEMENT ...]"
-    echo "      Clones ITEM# into a new task and replaces PATTERN with REPLACEMENT."
+    echo "    $(basename $0) NR [PATTERN REPLACEMENT ...]"
+    echo "      Clones task on line NR into a new task and replaces PATTERN with"
+    echo "      REPLACEMENT."
     echo ""
     exit
 }
 
 shopt -s extglob
 
-errmsg="usage: $TODO_SH $(basename $0) ITEM# [PATTERN REPLACEMENT ...]"
+errmsg="usage: $TODO_SH $(basename $0) NR [PATTERN REPLACEMENT ...]"
 item=$1; shift
 
 [ -z "$item" ] && die "$errmsg"

actions/comment

@@ -11,7 +11,7 @@
 #
 # REMARKS:
 #
-# COPYRIGHT: (C) 2010-2022 Ingo Karkat
+# COPYRIGHT: (C) 2010-2024 Ingo Karkat
 #   This program is free software; you can redistribute it and/or modify it
 #   under the terms of the GNU General Public License.
 #   See http://www.gnu.org/copyleft/gpl.txt
@@ -23,13 +23,13 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) ITEM#[, ITEM#, ITEM#, ...] COMMENT"
-    echo "      Adds / appends COMMENT (with comment marker) on task(s) on line ITEM#."
+    echo "    $(basename $0) NR [NR ...] COMMENT"
+    echo "      Adds / appends COMMENT (with comment marker) on task(s) on line(s) NR."
     echo ""
     exit
 }
 
-errmsg="usage: $TODO_SH $(basename $0) ITEM#[, ITEM#, ITEM#, ...] COMMENT"
+errmsg="usage: $TODO_SH $(basename $0) NR [NR ...] COMMENT"
 [ $# -eq 0 ] && die "$errmsg"
 
 : ${TODOTXT_COMMENT_SYMBOL:= => }

actions/conflate

@@ -11,7 +11,7 @@
 #
 # REMARKS:
 #
-# COPYRIGHT: (C) 2013-2022 Ingo Karkat
+# COPYRIGHT: (C) 2013-2024 Ingo Karkat
 #   This program is free software; you can redistribute it and/or modify it
 #   under the terms of the GNU General Public License.
 #   See http://www.gnu.org/copyleft/gpl.txt
@@ -23,14 +23,15 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) KEEPITEM# ITEM#[, ITEM#, ...] [CONJUNCTION]"
-    echo "      Combines ITEM# with KEEPITEM# (concatenated [with CONJUNCTION]) and"
-    echo "      deletes all ITEM#. Duplicate projects and contexts are removed."
+    echo "    $(basename $0) KEEP-NR NR [NR ...] [CONJUNCTION]"
+    echo "      Combines task(s) on line(s) NR with KEEP-NR (concatenated"
+    echo "      [with CONJUNCTION]) and deletes all NR."
+    echo "      Duplicate projects and contexts are removed."
     echo ""
     exit
 }
 
-errmsg="usage: $TODO_SH $(basename $0) KEEPITEM# ITEM#[, ITEM#, ...] [CONJUNCTION]"
+errmsg="usage: $TODO_SH $(basename $0) KEEP-NR NR [NR ...] [CONJUNCTION]"
 [ $# -eq 0 ] && die "$errmsg"
 
 keepitem=$1

actions/consider

@@ -23,15 +23,15 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) ITEM#[, ITEM#, ...]"
-    echo "      Adds priority O to task(s) on line ITEM#"
+    echo "    $(basename $0) NR [NR ...]"
+    echo "      Adds priority O to task(s) on line NR"
     echo "      only for today and tomorrow."
     echo "      Use \"todo.sh opportunity\" to specify a different date range."
     echo ""
     exit
 }
 
-errmsg="usage: $TODO_SH $(basename $0) ITEM#[, ITEM#, ...]"
+errmsg="usage: $TODO_SH $(basename $0) NR [NR ...]"
 [ $# -lt 1 ] && die "$errmsg"
 
 exec "$TODO_FULL_SH" opportunity "$@" '2 days'

actions/del

@@ -23,15 +23,15 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) ITEM#[, ITEM#, ITEM#, ...] [TERM]"
-    echo "      Deletes the task(s) on line ITEM# in todo.txt."
-    echo "      Task(s) that were dependent on ITEM# have that blocker removed."
+    echo "    $(basename $0) NR [NR ...] [TERM]"
+    echo "      Deletes the task(s) on line NR in todo.txt."
+    echo "      Task(s) that were dependent on NR have that blocker removed."
     echo "      If TERM specified, deletes only TERM from the task."
     echo ""
     exit
 }
 
-errmsg="usage: $TODO_SH $(basename $0) ITEM#[, ITEM#, ITEM#, ...] [TERM]"
+errmsg="usage: $TODO_SH $(basename $0) NR [NR ...] [TERM]"
 [ $# -eq 0 ] && die "$errmsg"
 
 items=

actions/depri

@@ -23,19 +23,19 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) ITEM#[, ITEM#, ITEM#, ...]|all|[PRIORITIES] [on DATE|DATE-] [COMMENT]"
-    echo "    $(basename $0) [on DATE|DATE-] ITEM#[, ITEM#, ITEM#, ...]|all|[PRIORITIES] [COMMENT]"
+    echo "    $(basename $0) NR [NR ...]|all|[PRIORITIES] [on DATE|DATE-] [COMMENT]"
+    echo "    $(basename $0) [on DATE|DATE-] NR [NR ...]|all|[PRIORITIES] [COMMENT]"
     echo "      Deprioritizes (removes the priority) from the task(s)"
-    echo "      on line ITEM# in todo.txt, or all (currently) prioritized tasks, or all"
+    echo "      on line NR in todo.txt, or all (currently) prioritized tasks, or all"
     echo "      (currently) having PRIORITIES (a single one (A) or range (A-C))."
     echo "      With DATE-, the task will be deprioritized on DATE (via d:DATE)."
-    echo "    $(basename $0) [never|on none] ITEM#[, ITEM#, ITEM#, ...]|all|[PRIORITIES] [COMMENT]"
+    echo "    $(basename $0) [never|on none] NR [NR ...]|all|[PRIORITIES] [COMMENT]"
     echo "      Removes the d:DATE deprioritization on a date."
     echo ""
     exit
 }
 
-errmsg="usage: $TODO_SH $(basename $0) ITEM#[, ITEM#, ITEM#, ...]|all|[PRIORITIES] [never|on none|on DATE|DATE-] [COMMENT]"
+errmsg="usage: $TODO_SH $(basename $0) NR [NR ...]|all|[PRIORITIES] [never|on none|on DATE|DATE-] [COMMENT]"
 [ $# -eq 0 ] && die "$errmsg"
 
 makeDate()

actions/did

@@ -23,20 +23,20 @@ action=$1
 shift
 
 [ "$action" = "usage" ] && {
-    echo "    $(basename $0) ITEM#[, ITEM#, ITEM#, ...] [on] DATE [COMMENT]"
-    echo "      Marks task(s) on line ITEM# as done at DATE in todo.txt,"
+    echo "    $(basename $0) NR [NR ...] [on] DATE [COMMENT]"
+    echo "      Marks task(s) on line NR as done at DATE in todo.txt,"
     echo "      optionally appending COMMENT."
-    echo "    $(basename $0) ITEM#[, ITEM#, ITEM#, ...] after DATESPAN [COMMENT]"
-    echo "      Marks task(s) on line ITEM# as done DATESPAN later than the added date,"
+    echo "    $(basename $0) NR [NR ...] after DATESPAN [COMMENT]"
+    echo "      Marks task(s) on line NR as done DATESPAN later than the added date,"
     echo "      optionally appending COMMENT."
-    echo "    $(basename $0) ITEM#[, ITEM#, ITEM#, ...] the same|next day [COMMENT]"
-    echo "      Marks task(s) on line ITEM# as done on the same/next day they were added."
-    echo "      Task(s) that were dependent on ITEM# have that blocker removed."
+    echo "    $(basename $0) NR [NR ...] the same|next day [COMMENT]"
+    echo "      Marks task(s) on line NR as done on the same/next day they were added."
+    echo "      Task(s) that were dependent on NR have that blocker removed."
     echo ""
     exit
 }
 
-errmsg="usage: $TODO_SH $(basename $0) ITEM#[, ITEM#, ITEM#, ...] [on] DATE | after DATESPAN | the same|next day [COMMENT]"
+errmsg="usage: $TODO_SH $(basename $0) NR [NR ...] [on] DATE | after DATESPAN | the same|next day [COMMENT]"
 [ $# -eq 0 ] && die "$errmsg"
 
 items=