Update search tool help.

jira/bin/jira-search.sh
-----------------------
  o Help text growing long, refactor help text into jira-search/help.
  o Added command line switches --help-* and --usage-*

jira/jira-search/help/utils.sh
------------------------------
  o Added library functions for displaying context help.
  o Display switch permutations for a given prefix.
  o Display use cases for a given switch.

jira/jira-search/help/fixversion.switches
jira/jira-search/help/resolved.sh
jira/jira-search/help/resolved.switches
jira/jira-search/help/resolved.usage
jira/jira-search/help/user.switches
jira/jira-search/help/user.usage
-----------------------------------------
  o Switch help and usage text.

Change-Id: I0cd34475521c2b42054fbe4e7966a6d3767f8f89
diff --git a/jira/bin/jira-search.sh b/jira/bin/jira-search.sh
index 97b8cc2..462df4d 100755
--- a/jira/bin/jira-search.sh
+++ b/jira/bin/jira-search.sh
@@ -1,4 +1,21 @@
 #!/bin/bash
+# -----------------------------------------------------------------------
+# Copyright 2023-2024 Open Networking Foundation Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2023-2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
 ## --------------------------------------------------------------------
 ## Intent: Construct a jira ticket query with attributes
 ## --------------------------------------------------------------------
@@ -7,6 +24,9 @@
     declare pgm=''
     pgm="$(realpath --canonicalize-existing "$0")"
 
+    # stack-trace-on-error
+    # interrupt handler
+    # mkdir with auto-cleanup at exit
     declare root=''
     root="${pgm%%/jira/bin/jira-search.sh}"
     source "$root/lf/onf-common/common.sh" '--common-args-begin--'
@@ -16,6 +36,9 @@
 
     pgm_bin="${root}/bin"
     readonly pgm_bin
+
+    pgm_help="${root}/jira/jira-search/help"
+    readonly pgm_help
 }
 
 # set -euo pipefail
@@ -43,6 +66,7 @@
 #source "$pgmlib/resolved.sh"
 source "${pgm_lib}/fixversion.sh"
 source "${pgm_lib}/resolved.sh"
+source "${pgm_lib}/help/utils.sh"
 
 ## --------------------------------------------------------------------
 ## --------------------------------------------------------------------
@@ -331,36 +355,28 @@
 
 [SERVER]
   --server {cord,onf}
-  --onf         jira.opennetworking.org (default)
+  --onf         jira.opennetworking.org
   --opencord    jira.opencord.org
 
 [WHAT]
   --component   Search by component name assigned to ticket
   --label       Search by label name assigned to ticket.
   --text        Search string(s)
+EOH
 
-[FIXVERSION] - Voltha-v2.12
-  --fixversion-incl
-  --fixversion-excl
-  --fixversion-is-empty
-  --fixversion-not-empty
+#    declare -a topics=()
+#    topics+=('fixversion.switches')
+#    topics+=('resolved.switches')
+#
+#    help_switch_show "${topics[@]}"#
+    #
+#[USER(s)]
+#  --me          Tickets assigned to or reported by me.
+#  --user [u]    Tickets assigned to this user.
+#  --nobody      Raw query, no filtering by user
 
-[RESOLVED] - tokens={Declined, Won't Fix}
-  --resolved-start ccyy-mm-dd
-  --resolved-end   ccyy-mm-dd
-  --resolved-incl {token(s)}
-  --resolved-excl {token(s)}
-  --resolved-is-empty   Query for open tickets
-  --resolved-not-empty
 
-[USER(s)]
-  --me          Tickets assigned to or reported by me.
-  --user [u]    Tickets assigned to this user.
-  --nobody      Raw query, no filtering by user
-
-[BY-USER]
-  --assigned    Tickets assided to user
-  --reported    Tickets created by user
+    cat <<EOH
 
 [BOOL]
   --and            Join terms using 'AND'
@@ -376,17 +392,26 @@
   --text-or  [t]   Any of these terms
 
 [RANGE]
-  --newer [d]   Search for tickets created < [n] days ago.
-  --older [d]   Search for tickets created > [n] days ago.
+  --newer [d]      Search for tickets created < [n] days ago.
+  --older [d]      Search for tickets created > [n] days ago.
 
 [ALIASES]
-  --all         Query for all unresolved tickets
+  --all            Query for all unresolved tickets
+
+[TOPIC]
+  --fixversion     Query by field: fixedversion
+  --resolved       Query by field: resolved
+  --user           Query by owner, requestor or 'my' jira tickets.
+
+[HELP]
+  --help           This message
+  --help-{topic}   Display switch help and use case.     (--help-resolved)
+  --usage-{topic}  Display use cases for a given switch  (--usage-user)
 
 [USAGE]
-  $0 --assigned
+  $0 --opencord --assigned --unresolved
      o Display all tickets assigned to my login
-  $0 --requested --user tux
-     o Display all tickets requested by user tux
+
   $0 --reported --or --text 'bbsim' --text 'release'
      o Search for tickets that contain strings bbsim or release
   $0 --cord --text-and 'release' --text-and 'voltctl'
@@ -430,7 +455,10 @@
 
     case "$arg" in
 
-        -*help) usage; exit 0 ;;
+        '--help') usage; exit 0 ;;
+        '--help-'*) help_with "${arg/--help-/}" ;;
+        '--usage-'*) help_usage_show "${arg/--usage-/}"
+           ;;
 
         ##-----------------##
         ##---]  MODES  [---##
@@ -438,6 +466,16 @@
         -*debug)   declare -g -i debug=1 ;;
         --dry-run) declare -g -i dry_run=1 ;;
 
+        ##------------------------##
+        ##---]  SWITCH ALIAS  [---##
+        ##------------------------##
+        --unresolved)
+            declare -a args=()
+            args+=('--resolved-is-empty')
+            [[ $# -gt 0 ]] && { args+=("$@"); }
+            set -- "${args[@]}"
+            ;;
+
         ##-------------------##
         ##---]  BY USER  [---##
         ##-------------------##
@@ -462,8 +500,8 @@
             esac
             ;;
 
-         --onf) declare server='jira.opennetworking.org' ;;
-        --cord) declare server='jira.opencord.org'     ;;
+             --onf) declare server='jira.opennetworking.org' ;;
+        --opencord) declare server='jira.opencord.org'     ;;
 
         ##---------------------##
         ##---]  SEARCH-BY  [---##
@@ -534,7 +572,7 @@
             esac
             ;;
 
-        --resolved-*)
+        '--resolved-'*)
             # function get_jql_reasons()
             case "$arg" in
 
diff --git a/jira/jira-search/help/fixversion.switches b/jira/jira-search/help/fixversion.switches
new file mode 100644
index 0000000..9ddc4a2
--- /dev/null
+++ b/jira/jira-search/help/fixversion.switches
@@ -0,0 +1,27 @@
+# -----------------------------------------------------------------------
+# Copyright 2024 Open Networking Foundation Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent:
+## --------------------------------------------------------------------
+
+[FIXVERSION] - Voltha-v2.12
+  --fixversion-incl
+  --fixversion-excl
+  --fixversion-is-empty
+  --fixversion-not-empty
+# [EOF]
diff --git a/jira/jira-search/help/resolved.sh b/jira/jira-search/help/resolved.sh
new file mode 100644
index 0000000..4f0124f
--- /dev/null
+++ b/jira/jira-search/help/resolved.sh
@@ -0,0 +1,35 @@
+#!/bin/bash
+# -----------------------------------------------------------------------
+# Copyright 2023-2024 Open Networking Foundation Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2023-2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent: Construct a jira ticket query with attributes
+## --------------------------------------------------------------------
+
+function resolved_switches()
+{
+    local ref=$1; shift
+
+    
+[RESOLVED] - tokens={Declined, Won't Fix}
+  --resolved-start ccyy-mm-dd
+  --resolved-end   ccyy-mm-dd
+  --resolved-incl {token(s)}
+  --resolved-excl {token(s)}
+  --resolved-is-empty   Query for open tickets
+  --resolved-not-empty
+  --unresolved          Alias for resolved-is-empty
diff --git a/jira/jira-search/help/resolved.switches b/jira/jira-search/help/resolved.switches
new file mode 100644
index 0000000..86c49d3
--- /dev/null
+++ b/jira/jira-search/help/resolved.switches
@@ -0,0 +1,30 @@
+# -----------------------------------------------------------------------
+# Copyright 2024 Open Networking Foundation Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent:
+## --------------------------------------------------------------------
+
+[RESOLVED] - tokens={Declined, Won't Fix}
+  --resolved-start ccyy-mm-dd
+  --resolved-end   ccyy-mm-dd
+  --resolved-incl {token(s)}
+  --resolved-excl {token(s)}
+  --resolved-is-empty               Query for open tickets
+  --resolved-not-empty
+  --unresolved                      Alias for --resolved-if-empty
+# [EOF]
diff --git a/jira/jira-search/help/resolved.usage b/jira/jira-search/help/resolved.usage
new file mode 100644
index 0000000..fad5dbb
--- /dev/null
+++ b/jira/jira-search/help/resolved.usage
@@ -0,0 +1,29 @@
+# -----------------------------------------------------------------------
+# Copyright 2024 Open Networking Foundation Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent:
+## --------------------------------------------------------------------
+
+[RESOLVED]
+  $0 --server opencord --component bbsim --unresolved
+  $0 --server opencord --component bbsim --resolved-is-empty
+     o Query for open bbsim tickets.
+
+  $0 --proj VOL --fixversion "VOLTHA v2.12" --resolved-is-empty
+     o Query for unresolved v2.12 release tickets.
+# [EOF]
diff --git a/jira/jira-search/help/user.switches b/jira/jira-search/help/user.switches
new file mode 100644
index 0000000..38661e1
--- /dev/null
+++ b/jira/jira-search/help/user.switches
@@ -0,0 +1,30 @@
+# -----------------------------------------------------------------------
+# Copyright 2024 Open Networking Foundation Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent:
+## --------------------------------------------------------------------
+
+[USER(s)]
+  --me          Tickets assigned to or reported by me.
+  --user [u]    Tickets assigned to this user.
+  --nobody      Raw query, no filtering by user
+
+[BY-USER]
+  --assigned    Tickets assided to user
+  --reported    Tickets created by user    
+# [EOF]
diff --git a/jira/jira-search/help/user.usage b/jira/jira-search/help/user.usage
new file mode 100644
index 0000000..d94f374
--- /dev/null
+++ b/jira/jira-search/help/user.usage
@@ -0,0 +1,39 @@
+# -----------------------------------------------------------------------
+# Copyright 2024 Open Networking Foundation Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent:
+## --------------------------------------------------------------------
+
+[USER]
+  $0 --server opencord --unresolved --assigned --user tux
+     o Display all tickets assigned to user tux
+    
+  $0 --server opencord --requested --user tux
+     o Display all tickets requested by user tux
+
+  $0 --server opencord --unresolved --user tux
+     o Display open tickets assigned or requested by user tux.
+
+[BY USER]
+  $0 --server-opencord --assigned --unresolved
+     o Display all open tickets assigned to my login
+
+  $0 --server opencord --me
+     o Display tickets requested or assigned to my login.
+    
+# [EOF]
diff --git a/jira/jira-search/help/utils.sh b/jira/jira-search/help/utils.sh
new file mode 100644
index 0000000..53b237d
--- /dev/null
+++ b/jira/jira-search/help/utils.sh
@@ -0,0 +1,90 @@
+#!/bin/bash
+# -----------------------------------------------------------------------
+# Copyright 2024 Open Networking Foundation Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent:
+## --------------------------------------------------------------------
+
+## --------------------------------------------------------------------
+## --------------------------------------------------------------------
+function help_read()
+{
+    local -n ref=$1; shift
+    local path="$1"; shift
+
+    readarray text < <(grep -v -e '^#' "$path")
+    ref+=("${text[@]}")
+
+    return
+}
+
+## --------------------------------------------------------------------
+## --------------------------------------------------------------------
+function help_switch_show()
+{
+    local -a buffer=()
+
+    local helpwith
+    for helpwith in "$@"; do
+        local path="$pgm_help/${helpwith}.switches"
+        if [[ ! -e "$path" ]]; then
+            readarray fyls < <(find "$pgm_help" -name '*.switches')
+            echo "--usage-${helpwith} does not exist"
+            echo "Try one of:"
+            printf "  %s\n" "${fyls[@]}"
+            error "OUTA HERE"
+        fi
+        help_read buffer "$path"
+    done
+
+    printf '%s' "${buffer[@]}"
+    return
+}
+
+## --------------------------------------------------------------------
+## --------------------------------------------------------------------
+function help_usage_show()
+{
+    local -a buffer=()
+
+    local helpwith
+    for helpwith in "$@"; do
+        local path="$pgm_help/${helpwith}.usage"
+        if [[ ! -e "$path" ]]; then
+            readarray fyls < <(find "$pgm_help" -name '*.usage')
+            echo "--usage-${helpwith} does not exist"
+            echo "Try one of:"
+            printf "  %s\n" "${fyls[@]}"
+            error "OUTA HERE"
+        fi
+        help_read buffer "$path"
+    done
+
+    printf '%s' "${buffer[@]}"
+    return
+}
+
+## --------------------------------------------------------------------
+## --------------------------------------------------------------------
+function help_with()
+{
+    help_switch_show "$@"
+    help_usage_show "$@"
+}
+
+# [EOF]